> ## Documentation Index
> Fetch the complete documentation index at: https://gump.build/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Implement Spec

> Decompose, implement, adversarial review, converge.

# Implement Spec

Decompose, implement, adversarial review, converge. The reference workflow.

## When to use

For quality-sensitive work that needs adversarial review. Each task goes through implementation, gate validation, and a workflow validator review. If the review fails, the implementer receives targeted feedback and iterates. Escalation to a stronger model kicks in after repeated failures.

```bash theme={null}
gump run implement-spec --spec spec.md
```

## The workflow

```yaml theme={null}
name: implement-spec
max_budget: 20.00

steps:
  - name: decompose
    type: split
    get:
      prompt: |
        Decompose {spec} into independent tasks with disjoint blast radii.
    run:
      agent: claude-opus
    gate: [schema]
    each:
      - name: converge
        type: code
        get:
          prompt: |
            Implement: {task.description}
            Files: {task.files}
            {prev.gate.review.comments}
          context:
            - file: docs/architecture.md
        run:
          agent: claude-sonnet
          guard:
            max_turns: 60
        gate:
          - compile
          - test
          - validate: validators/arch-review
              diff: "{diff}"
              spec: "{spec}"
              agent: claude-opus
        retry:
          - attempt: 2
            prompt: |
              Deviations remain: {gate.review.comments}
              Fix only these. Files: {task.files}
          - attempt: 4
            agent: claude-opus
            session: new
            worktree: reset
          - exit: 6

      - name: smoke
        type: code
        get:
          prompt: |
            Run smoke tests and fix any issues.
            Do not refactor. Only fix failures.
          session: from: converge
        run:
          agent: {converge.agent}
          guard:
            max_turns: 30
        gate: [compile, test]
        retry:
          - exit: 3

  - name: quality
    gate: [compile, lint, test]
```

## How it works

The decompose step splits the spec into tasks. For each task, the converge step implements the code and then runs three gates: compile, test, and a **workflow validator** (`validators/arch-review`) that uses Claude Opus to review the diff against the spec.

If the validator review fails, the retry overrides the prompt with targeted feedback from `{gate.review.comments}` — the agent gets a focused instruction instead of the full spec. From attempt 4, escalation switches to Claude Opus with a fresh session and reset worktree.

The smoke step reuses the session from converge (`session: from: converge`) and the same agent that converged (`agent: {converge.agent}`) — if converge escalated to Opus, smoke runs with Opus too.

## Execution trace

```
[decompose]                  running  (claude-opus)
[decompose]                  pass     3 tasks

[build/task-1/converge]      running  (claude-sonnet)  attempt 1
[build/task-1/converge]      gate     compile ✓  test ✓  review ✗
[build/task-1/converge]      retry    attempt 2 — prompt override
[build/task-1/converge]      running  (claude-sonnet)  attempt 2
[build/task-1/converge]      gate     compile ✓  test ✓  review ✓
[build/task-1/converge]      pass

[build/task-1/smoke]         running  (claude-sonnet)  session from: converge
[build/task-1/smoke]         pass

[quality]                    gate     compile ✓  lint ✓  test ✓
[quality]                    pass

Run completed: pass  duration: 12m34s  cost: $8.42
```

## Customize

<AccordionGroup>
  <Accordion title="Replace the validator">
    Create your own `validators/my-review` workflow with `type: validate` and swap it in the gate.
  </Accordion>

  <Accordion title="Remove the smoke step">
    Delete the smoke step from `each:` if you trust the quality gate alone.
  </Accordion>

  <Accordion title="Add HITL on the plan">
    Add `hitl: before_gate` on `decompose` to validate the task breakdown manually.
  </Accordion>

  <Accordion title="Use parallel tasks">
    Add `parallel: true` on the decompose step. Requires strictly disjoint blast radii.
  </Accordion>
</AccordionGroup>