Composition patterns
A composition pattern is a proven way to combine skills inside a plan. There are seven. Each one solves a different kind of coordination: chaining, parallelizing, routing, validating, reviewing, repeating, and sharing context.
This guide explains each pattern, how to write it in an engine plan, and which real plans use it. The full conceptual definition is in ARCHITECTURE.md (section 3) of the crowdar-qa-skills repo.
Summary
| # | Pattern | What for | How to write it in the engine |
|---|---|---|---|
| 3.1 | Sequential Pipeline | Chain skills, each one using the output of the previous one | Steps in order + ${...} |
| 3.2 | Fan-out / Fan-in | Run several skills (or the same one on several pieces of data) at the same time | for_each or parallel |
| 3.3 | Router / Dispatcher | Choose which path to follow based on the input | Model 2 (between plans) or when (inside the plan) |
| 3.4 | Validator / Guard | Validate before moving on to the next step | guard and stop_unless |
| 3.5 | Reviewer | Have another skill, with a clean context, review the result | A reviewer step + stop_unless |
| 3.6 | Loop with exit criterion | Repeat until a goal is met | Inside the skill, with an iteration cap |
| 3.7 | Chain-of-Skills with shared context | Let a step use data from several previous steps | output_to + ${...} over the append-only context |
3.1 Sequential Pipeline
What it is: skill A → skill B → skill C. Each one takes the output of the previous one.
When: when there is a linear dependency: you can't plan without having read the story, or generate tests without the plan.
steps:
- skill: lippia-neo-read-user-story
tools: [file]
input:
user_story: ${input.description}
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
guard: true
- skill: lippia-neo-generate-test-suite
tools: [file]
input:
manual_execution_report_path: "execution/${user_story.us_id}/${user_story.us_id}-scripted-execution-report.json"
output_to: new_tests
Keep in mind:
- Use
guard: trueon every step whose output is consumed by the next one: if a step returns something malformed, it's better to stop there than to carry the error forward. - Outputs have to be structured data (guaranteed by each skill's
output_schema), not free text.
In real plans: all of them. feature-new-end-to-end (steps 1 to 6), qa-bug-fix-verification (1 to 4), ui-selector-repair (1 to 3).
3.2 Fan-out / Fan-in
What it is: several executions are launched at the same time and then the results are gathered. There are two variants:
Variant A — the same skill over a list (for_each)
steps:
- skill: lippia-neo-create-test-plan
for_each: ${input.user_stories} # a list
tools: [file]
input:
user_story: ${item} # the current element
output_to: test_plans # ends up as a list, in the same order
continue_on_error: true # if one fails, the others continue
If input.user_stories has three stories, the skill runs three times in parallel and test_plans ends up as a list with the three results (null in the position of one that failed, if continue_on_error is set).
Variant B — different skills at the same time (parallel)
steps:
- parallel:
- skill: lippia-neo-find-existing-tests
tools: [file]
input:
source_summary: ${bug_summary}
output_to: coverage
- skill: lippia-neo-read-user-story
tools: [file]
input:
user_story: ${bug_summary.related_user_story}
output_to: related_story
continue_on_error: false
- skill: lippia-neo-review-test-coverage # fan-in: uses both outputs
tools: [file]
input:
existing_tests: ${coverage.existing_tests}
related_us_summary: ${related_story}
output_to: coverage_review
Keep in mind:
- The engine runs at most 5 executions at a time. If the list has 50 elements, it processes them 5 at a time, so as not to hit the AI provider's usage limits.
- The sub-steps of a
parallelgroup cannot read the output of another sub-step in the same group: they run at the same time. They can only use data from previous steps. - Without
continue_on_error, if one execution fails, the whole step fails.
In real plans: none of the current plans use it yet. It is the natural candidate for generating test plans for several stories in an epic, or for running independent explorations in parallel.
3.3 Router / Dispatcher
What it is: something classifies the input and routes it to the right path. The router has to report how confident it is, so it can escalate to a human when it's unsure.
In the engine there are two levels:
Level 1 — between plans (Model 2)
The engine does it on its own, with neo run --input "<texto>": the lippia-neo-classify-task skill chooses the plan and the engine escalates to a human if the confidence is below 0.7. See Orchestration models in the engine.
Level 2 — inside a plan (when)
One step classifies and returns the data that decides the path; the following steps use when to run only if they apply:
steps:
# The classifier: decides where the story comes from
- skill: lippia-neo-resolve-user-story-source
tools: [file]
input:
user_story: ${input.description}
output_to: resolved_source
guard: true
# Path A: only if it's a Jira ticket. `file` lets the skill read its references/jira.md
- skill: lippia-neo-fetch-user-story
when: ${resolved_source.fetch_url_jira}
tools: [jira, file]
input:
story_ref: ${resolved_source.fetch_url_jira}
provider: jira
output_to: jira_fetch
# Path B: only if it's an Azure DevOps work item. `file` lets the skill read its references/azure-devops.md
- skill: lippia-neo-fetch-user-story
when: ${resolved_source.fetch_url_azure_devops}
tools: [azure-devops, file]
input:
story_ref: ${resolved_source.fetch_url_azure_devops}
provider: azure-devops
output_to: azure_fetch
Both paths use the same fetch skill, each with a different fixed provider: since skill: can't be a reference, each branch is its own step. If the story is a local file, neither path runs and the plan continues with the next step.
Keep in mind:
whenevaluates a reference, not an expression:${x.confidence > 0.7}doesn't work. The classifier skill has to return the deciding value directly (a boolean, a URL, or a list that may be empty).- The skill name (
skill:) can't be a reference: the engine doesn't supportskill: ${clasificacion.tipo}. Each possible path is written as a step with its ownwhen.
In real plans: feature-new-end-to-end (steps 1a → 1b Jira | 1c Azure DevOps); qa-bug-coverage (step 1.5 runs only if the bug references a story).
3.4 Validator / Guard
What it is: a check between two steps, so that nothing invalid is passed downstream.
The engine has two checks, which can be combined:
| Check | Validates | If it fails |
|---|---|---|
guard: true |
The format: that the output matches the skill's output_schema |
The plan ends in failed |
stop_unless: ${...} |
The content: that the data indicates it's OK to continue | The plan ends in stopped (planned stop, not an error) |
steps:
- skill: lippia-neo-read-user-story
tools: [file]
input:
user_story: ${input.description}
output_to: user_story
guard: true # correct format
stop_unless: ${user_story.can_continue} # the story has the minimum needed to continue
- skill: lippia-neo-create-test-plan
tools: [file]
input:
us_id: ${user_story.us_id}
user_story: ${user_story.summary}
output_to: test_plan
guard: true
stop_unless: ${test_plan.scenarios} # without scenarios, there's no point exploring
You can also add a validator skill as its own step, between the producer and the consumer, and stop based on its result:
- skill: validar-gherkin # validator skill (example)
input:
draft: ${draft}
output_to: validation
guard: true
stop_unless: ${validation.valid}
Keep in mind:
- A validator skill's errors have to be actionable ("line 5: Given without Then"), not generic.
- If validation is retried, always use a cap on the number of attempts.
In real plans: they all use guard. stop_unless appears in feature-new-end-to-end (steps 1d and 2), qa-bug-coverage (step 4: stops if the bug doesn't reproduce), and qa-bug-fix-verification (step 2: stops if there are no tests covering the bug).
3.5 Reviewer (review with clean context)
What it is: a variant of the validator where the check is done by another skill using AI judgment, instead of rules. The key is that the reviewer has a clean context: whoever produced the result tends to defend it.
In the engine, each step is an independent invocation that only sees what it receives in its input. A reviewer step has a clean context by design. It's also a good idea to use a different model from the producer's:
steps:
- skill: lippia-neo-create-test-plan
tools: [file]
input:
user_story: ${user_story.summary}
output_to: test_plan
guard: true
- skill: revisar-plan-de-pruebas # reviewer skill (example)
model: anthropic/claude-sonnet-4-5 # a different model from the producer's
input:
user_story: ${user_story.summary} # only what's needed to judge
test_plan: ${test_plan}
output_to: plan_review
guard: true
stop_unless: ${plan_review.approved}
Keep in mind:
- Give the reviewer only what it needs to judge, not the producer's history.
- It isn't a built-in engine mechanism: you build it with one more step,
model, andstop_unless. It requires a reviewer skill to exist, with anoutput_schemathat returns the verdict.
In real plans: none of the current plans use it yet.
3.6 Loop with exit criterion
What it is: repeating something until a goal is met (for example, until all tests pass), with a cap on the number of rounds and detection of when it gets stuck.
In the engine, the loop lives inside the skill, not in the plan. The plan only gives it the budget:
- skill: lippia-neo-run-and-heal
tools: [file, shell]
loop:
max_iterations: 100 # agent budget: how many times it can use tools
input:
config:
max_iterations: 3 # loop cap: run → repair → run
run_label: post-fix
output_to: heal_summary
guard: true
lippia-neo-run-and-heal runs the suite, repairs what fails, and runs it again, until everything passes, the cap is reached, or it detects that it has stopped improving. Its output says how it ended (for example green, plateau_abort, or max_iter_abort), and the next step can use that value.
Keep in mind:
- The iteration cap is not optional: without it, a loop might never end and consume credits without limit.
- You need to detect when it gets stuck: if two rounds in a row don't improve, it's better to exit and escalate.
- The engine doesn't have a generic "evaluator" loop at the plan level; if you need one, the loop goes inside a skill.
In real plans: feature-new-end-to-end (step 5), qa-bug-fix-verification (step 3), and ui-selector-repair (step 3), always through lippia-neo-run-and-heal.
3.7 Chain-of-Skills with shared context
What it is: several skills work on the same context, each one adds information to it, and a step can read data from any previous step, not just the last one.
steps:
- skill: lippia-neo-read-user-story
tools: [file]
input:
user_story: ${input.description}
output_to: user_story
- skill: lippia-neo-run-manual-testing
tools: [browser, file]
input:
test_plan_path: "test-plans/${user_story.us_id}-test-plan.md"
output_to: exploration
- skill: lippia-neo-run-and-heal
tools: [file, shell]
input:
config:
run_label: feature-e2e
output_to: heal_summary
- skill: lippia-neo-write-test-report
tools: [file]
input: # reads from three different steps
us_id: ${user_story.us_id}
manual_results: ${exploration}
automation_results:
- label: feature-e2e
run: ${heal_summary}
output_to: report
Keep in mind:
- The context is append-only: each
output_toadds a new key, and reusing a key that was already written stops the plan. That way each piece of data has a single origin. - Everything written to the context is recorded in the audit (
audit.db,contexttable): the context history is the execution history.
In real plans: feature-new-end-to-end (step 6 reads steps 1d, 3, and 5), qa-bug-coverage (step 5 reads steps 2, 3, and 4), and qa-bug-fix-verification (step 4 reads steps 1 and 3).
Which pattern to use
flowchart TD
A{Are the skills<br/>independent of each other?} -- Yes --> B{Do the results<br/>need to be gathered?}
B -- Yes --> FO[3.2 Fan-out / Fan-in]
B -- No --> SEP[Separate plans or steps]
A -- No --> C{Is the dependency<br/>linear?}
C -- Yes --> D{Can the output<br/>be invalid?}
D -- Yes --> SV[3.1 Sequential + 3.4 Guard<br/>or 3.5 Reviewer]
D -- No --> S[3.1 Sequential]
C -- No --> E{Is there a clear<br/>exit criterion?}
E -- Yes --> L[3.6 Loop with criterion]
E -- No --> CH[3.7 Shared context]
And if the path depends on the input (Jira or Azure, tests exist or they don't), add a 3.3 Router with when.
Full real example: feature-new-end-to-end
The plan that runs in CI today with the feature label combines five of the seven patterns:
| Step | Skill | Patterns |
|---|---|---|
| 1a | lippia-neo-resolve-user-story-source |
3.1, 3.3 (classifies the source), 3.4 |
| 1b | lippia-neo-fetch-user-story (provider: jira) |
3.3 (when: Jira only), 3.4 |
| 1c | lippia-neo-fetch-user-story (provider: azure-devops) |
3.3 (when: Azure DevOps only), 3.4 |
| 1d | lippia-neo-read-user-story |
3.1, 3.4 (stop_unless: can_continue) |
| 2 | lippia-neo-create-test-plan |
3.1, 3.4 (stop_unless: scenarios) |
| 3 | lippia-neo-run-manual-testing |
3.1, 3.4 |
| 4 | lippia-neo-generate-test-suite |
3.1, 3.4 |
| 5 | lippia-neo-run-and-heal |
3.1, 3.4, 3.6 (run → repair loop) |
| 6 | lippia-neo-write-test-report |
3.4, 3.7 (reads 1d, 3, and 5) |
The full YAML is in plans/feature-new-end-to-end.yaml in the crowdar-engine-mvp repo, commented step by step.