Anatomy of a plan
A plan is a YAML file that describes a workflow: which skills run, in what order, with what data, and what happens if something goes wrong. The engine reads it, validates it, and runs it. This guide is the complete reference for the format.
1. A minimal plan
name: leer-y-planificar
description: Reads a user story and generates its test plan.
default_model: anthropic/claude-haiku-4-5-20251001
required_keys:
- user_story_path: Local path to the user story .md file.
steps:
- skill: lippia-neo-read-user-story
tools: [file]
input:
user_story: ${input.user_story_path}
output_to: user_story
guard: true
- skill: lippia-neo-create-test-plan
tools: [file]
input:
us_id: ${user_story.us_id}
user_story: ${user_story.summary}
output_to: test_plan
You run it with:
neo run plans/leer-y-planificar.yaml --workspace . \
--data '{"user_story_path":"user-stories/US-010.md"}'
2. Plan fields
| Field | Required | What it is |
|---|---|---|
name |
Yes | The plan's identifier. In Model 2 it is what the classifier returns, and what an overlay replaces |
description |
No (yes for M2) | What the plan does and when it applies. It is the only thing the Model 2 classifier sees |
version |
No | The plan's version. Default 0.1.0 |
default_model |
Yes | AI model for all the steps, in provider/model format (for example openai/gpt-5.4) |
stack |
No | The skills folder. If present, it takes priority over CROWDAR_SKILLS_DIR. It's best not to use it: a fixed path only works with the repos cloned in that location |
required_keys |
No | The data the plan needs to receive as input (see point 4) |
steps |
Yes (at least one) | The list of steps |
3. Step fields
Each step is either a skill (skill:) or a group of steps in parallel (parallel:), never both.
| Field | What it does | Example |
|---|---|---|
skill |
The skill to run (the name of its folder) | lippia-neo-create-test-plan |
input |
The data the skill receives. It can be fixed values or ${...} references |
us_id: ${user_story.us_id} |
output_to |
The name under which its return value is saved, so the following steps can read it | test_plan |
tools |
The tools the skill can use while it works (see point 6). If there is at least one, the skill runs as an agent | [file, browser] |
model |
Model for this step only, instead of default_model |
anthropic/claude-sonnet-4-5 |
loop.max_iterations |
How many tool rounds the agent can take in this step. Default 8 |
max_iterations: 100 |
guard |
If it is true and the output doesn't match the skill's schema, the plan ends with status failed |
true |
when |
The step runs only if this reference has a "truthy" value | ${resolved_source.fetch_url_jira} |
stop_unless |
After the step, if this reference is "falsy", the plan stops with status stopped |
${user_story.can_continue} |
for_each |
Runs the skill once for each element of a list, in parallel | ${historias} |
parallel |
A list of steps that run at the same time | see Patterns |
continue_on_error |
In for_each or parallel: if one element fails, it continues with the others |
true |
3.1 guard vs. stop_unless
Both stop the plan, but for different reasons:
guard: true |
stop_unless: ${...} |
|
|---|---|---|
| What it checks | That the output has the correct format (schema) | That the content allows it to continue |
| When it stops | The skill returned something malformed | The skill returned something valid, but which indicates there's no point continuing (for example, the story has no acceptance criteria) |
| Final status | failed (code 1) |
stopped (code 0) |
| Is it an error | Yes | No: it is a planned stop |
Without guard, an invalid output keeps going
If a step doesn't have guard: true and the skill returns something that doesn't match its schema, the step is marked as invalid in the audit, but the plan continues. Put guard: true on every step whose output is used by the following steps.
3.2 loop.max_iterations is not "repeating the skill"
loop.max_iterations is the agent's round budget within a single step: how many times it can use tools (read a file, click, run a command) before the engine cuts it off. It doesn't repeat the whole skill.
If the skill has its own loop (for example, lippia-neo-run-and-heal runs the suite, repairs, and runs it again), that loop is configured in the skill's input, not in loop:
- skill: lippia-neo-run-and-heal
tools: [file, shell]
loop:
max_iterations: 100 # agent budget (engine)
input:
config:
max_iterations: 3 # run → repair → run cycles (skill)
4. required_keys
It lists the data the plan needs to receive. Each entry can be just the name, or the name with a description:
required_keys:
- identifier # name only
- bug_report: > # name + description
Reference to the bug: local path, ticket URL (Jira/Azure DevOps),
or the full report as text.
- In Model 4 they document what you have to pass in
--data/--input-file. - In Model 2 they are what
lippia-neo-build-plan-inputhas to extract from the request. The description is what tells it what to look for: without it, the skill only has the key's name. If any is missing, the engine escalates to a human.
The description is data, not a comment
Write it as key: description, not as a YAML comment (# ...). Comments are lost when the file is read and never reach the engine.
5. ${...} references
A reference reads a piece of data from the plan's context: the initial input or what a previous step wrote with output_to.
| Reference | What it reads |
|---|---|
${input.description} |
The description key of the plan's input |
${user_story} |
Everything written by the step with output_to: user_story |
${user_story.us_id} |
A specific field of that output (you can go down several levels with dots) |
${item} |
Inside a for_each: the current element of the list |
5.1 How they are resolved
| Case | Result |
|---|---|
The value is only the reference: user_story: ${user_story} |
The data is passed as is, with its type (object, list, number) |
The reference is inside a text: "test-plans/${user_story.us_id}-test-plan.md" |
It is replaced as text: "test-plans/US-010-test-plan.md" |
The reference points to something nobody wrote, and the skill needs it (the skill's required_keys) |
The plan aborts at that step with UnresolvedRefError |
| The reference points to something nobody wrote, but the data is optional | It is passed empty (null, or "" inside a text) and a warning is logged |
Data that "doesn't exist" is different from data that exists with a null value: if a step wrote null, the reference resolves without error.
5.2 when and stop_unless evaluate a reference, not an expression
when and stop_unless accept a simple reference and check whether its value is "truthy". They don't accept comparisons:
when: ${matched.has_matches} # OK
when: ${repair.repaired_tests} # OK: an empty list is "falsy"
when: ${classification.confidence > 0.7} # does NOT work: the engine doesn't evaluate expressions
The following are considered "falsy": false, null, 0, "", an empty list, and an empty object. If you need a condition, the previous skill has to return the boolean already computed.
5.3 The context is append-only
Each output_to adds a new key. Writing the same key twice is an error: the plan stops. This guarantees that each piece of data has a single origin and that the audit shows exactly which step wrote what.
6. Tools (tools)
| Tool | What it lets the skill do | Where it comes from |
|---|---|---|
file |
Read, list, and write files. It writes only inside the --workspace; it can also read the skills folder |
From the engine |
shell |
Run commands in the terminal, inside the --workspace, with a limit of 120 seconds per command |
From the engine |
browser |
Navigate the app: open pages, click, take screenshots | From the framework's adapter (for example, the Playwright one launches the official Playwright MCP) |
jira, azure-devops, github, gitlab |
Read tickets, create bugs, etc. | From the mcp_servers section of qa-stack.yaml |
How the engine resolves a tool that isn't file or shell:
- It looks for an entry with that exact name in
mcp_serversofqa-stack.yaml. - If it doesn't find one, it looks in what the skill's adapter declares (
adapter.yaml,provides:section). - If it still doesn't find it, it ignores it and leaves a warning in the log (
ignoring unknown tools). The step continues, but without that tool.
The name has to match exactly
If the plan asks for tools: [atlassian] but qa-stack.yaml declares mcp_servers.jira, the engine doesn't connect the two: the skill runs without access to Jira. In the plan, use the same names as in mcp_servers.
Each MCP server is launched when the step starts and closed when it ends, always with the --workspace folder as the working directory.
7. What the engine adds to each skill
In addition to what you write in input, the engine passes the skill the following, without you having to ask:
| Data | When | What for |
|---|---|---|
adapter |
If the skill has adapters and there is a qa-stack.yaml |
The path and instructions of the project's framework or CI adapter |
skill |
If the skill has a references/ folder |
The skill's absolute path and the list of its references, so it can read them |
8. Validation
The engine validates the plan before running the first step. If something doesn't match the format, it runs nothing and tells you:
error: invalid plan plans/mi-plan.yaml:
steps.0: a step needs either 'skill' or 'parallel' (exactly one)
Common format errors:
| Error | Cause |
|---|---|
a step needs either 'skill' or 'parallel' (exactly one) |
A step has both, or neither |
'for_each' applies to a skill step, not a 'parallel' group |
for_each was combined with parallel |
a required_keys entry must be a bare key name, or a single key_name: description mapping |
A required_keys entry has more than one key |
Field required in default_model or name |
A required plan field is missing |