| name | stepargs-dsl |
| description | Breaks down a task into steps and arguments using StepArgs DSL, a lightweight text format that is easier for an LLM to generate reliably than JSON, then parses and validates it deterministically with a bundled CLI to produce structured JSON. Use when a task needs to be turned into structured step/argument data, especially when values contain long text, nested JSON, or code that would be error-prone to emit as JSON directly. |
StepArgs DSL
What this does
- Generate the task breakdown as StepArgs DSL text, in-context, following the prompt template.
- Delegate parsing and validation to the bundled CLI (
scripts/cli.js) — never hand-parse the DSL yourself.
- The CLI prints a JSON result (
steps + validation) to stdout and a human-readable summary of errors/warnings to stderr.
Choosing engine + template
Workflow
- Read the chosen prompt template from
references/ and generate the DSL text in-context, substituting the task description for the template's placeholder.
- Run the CLI, piping the generated DSL text in via stdin:
node scripts/cli.js --engine unicode <<'EOF'
<generated DSL text>
EOF
- Check the exit code:
0 → the JSON on stdout is valid, done.1 → read the error:/warning: lines on stderr (each has a line number + message), fix the DSL text, and retry step 2.
- Always go through the CLI for parsing/validation. Do not write a DSL parser yourself or interpret the syntax by hand.
CLI flags
--engine unicode|simple (default unicode)--no-validate — skip validation, fast parse only (no validation key in the output)--strict — promote warnings to failures; check validation.isValid, not just whether validation.errors is non-empty, since strict mode can set isValid: false with errors: [] when only warnings triggered it--limits default|web-ui|strict|none (default default)
Output shape
{
"steps": { "StepName": { "argName": "value" } },
"validation": {
"isValid": true,
"errors": [{ "line": 3, "message": "..." }],
"warnings": [{ "line": 5, "message": "..." }]
}
}
validation is omitted entirely when --no-validate is passed.
References
