LightSOPLang Worked Examples

Fallback Planner Script

The fallback planner stored at tests/recursiveAgent/recursiveAgentFixtures/.AchillesSkills/fallbackSuite/plannerFallback/oskill.md demonstrates a minimal LightSOPLang program. It captures the incoming prompt and then attempts to run a placeholder skill. The line @prompt prompt copies the user request into a variable called prompt. The next line executes the nonexistent-placeholder command, passing the prompt as the first argument and a descriptive string as the second argument. The interpreter resolves the reference to $prompt before invoking the command registry. The intent tag investigation is supplied as a literal, allowing the orchestration skill to treat the step as investigative even when the command fails.

@prompt prompt
@attempt nonexistent-placeholder $prompt "Attempt non-existent skill" investigation

This example highlights how scripts encode business context even when the actual command is expected to fail. The fallback section in the descriptor instructs the agent to reschedule MCP tools if necessary.

Inventory Planner Script

The orchestration planner at tests/recursiveAgent/recursiveAgentFixtures/.AchillesSkills/orchestrationSuite/planner/oskill.md embeds LightSOPLang in its Markdown descriptor. The script first stores the user prompt, then triggers the reporting skill, then triggers the data skill. Each command receives the prompt and a human-readable justification. The interpreter records the variable dependencies report and data, ensuring that confirmation messages include both steps.

@prompt prompt
@report report $prompt "Primary summary" reporting
@data data $prompt "Collect supporting facts" data-fetch

Because the descriptor lists report and data under allowed skills, the command registry exposes only these two commands to the script. The runtime therefore prevents accidental invocation of unrelated skills even when the script is regenerated.

Metric Scanner Script

The MCP skill at tests/recursiveAgent/recursiveAgentFixtures/.AchillesSkills/llmSuite/llmData/mskill.md shows how tool selection works. Although the descriptor relies on LLM planning in the regression tests, adding a LightSOPLang block would follow exactly the same pattern as the orchestration script. The identifier metricScanner would map to an MCP tool and the raw prompt would become its argument. The returned plan lists the tool name, the arguments, and the descriptive rationale string.

English Mode in Practice

Several tests, notably tests/lightSOPLang/englishScriptFixes.test.mjs, exercise the #!english directive. The script begins with the directive and then lists human language instructions. The interpreter asks the LLMAgent for LightSOPLang code, executes it, and, if any command fails, requests a revision. The new code replaces the previous script while retaining a history of attempts. This feature enables non-technical authors to describe desired behaviour in plain English while keeping the execution layer deterministic.