Skip to content

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: true on 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 parallel group 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:

  • when evaluates 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 support skill: ${clasificacion.tipo}. Each possible path is written as a step with its own when.

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, and stop_unless. It requires a reviewer skill to exist, with an output_schema that 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_to adds 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, context table): 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.