---
title: implement-backlog
description: >-
  Description of the skill that drives implementation by routing work to
  sub-agents sized for each role, selecting the AI model based on task
  difficulty
seo:
  image: /ogp.png
---
This skill is the most complex in the suite. It uses **sub-agents** (small, role-specific AIs that Claude Code delegates work to) and features a technique called **model tiering**, where the AI model used (haiku / sonnet / opus) is selected based on how demanding the task is.

## Command and Key Options

```
/architect:implement-backlog [item] [--epic=<id>] [--build-context] [--review-epic[=<id>]] [--out=<path>] [--confirm-versions|--no-confirm-versions] [--refresh-versions] [--dry-run] [--auto] [--lang=en|ja]
```

| Option | Meaning |
|---|---|
| `item` | Implementation target. Specify as `I1.2.3`, `#<iid>`, or a URL. If omitted, picks up items with `status::doing` and prompts for confirmation |
| `--epic` | Narrow the target to a specific Epic |
| `--build-context` | Rebuild the shared-context pack |
| `--review-epic[=<id>]` | Run a rollup review across an entire Epic |
| `--out` | Explicitly set the output location (`source_root`) for generated code |
| `--confirm-versions` / `--no-confirm-versions` | Whether to ask the user to confirm dependency library versions |
| `--refresh-versions` | Discard recorded version decisions (`work/version-decisions.json`) and re-investigate |
| `--dry-run` | Report what would be implemented without writing any code |
| `--auto` | Skip mid-run confirmation prompts |
| `--lang` | Output language for comments and reports |

## Processing Flow

Step 1 (shared-context pack build) runs only on the first invocation; Steps 2 onward loop until there are no remaining Issues.
Node colors indicate which model handles each step (see "Model Assignment Rules" below for the color key).
Uncolored nodes are handled by the skill itself (sonnet) rather than delegated to a sub-agent.

```mermaid
flowchart TD
  S0["Step 0: manifest and platform resolution"]
  S1["Step 1: shared-context pack build (first run only)"]:::sonnet
  S2["Step 2: Issue selection (confirm with user)"]
  S3["Step 3: consistency digest collection"]:::haiku
  S4["Step 4: branch creation + mini-plan"]:::opus
  S5["Step 5: implementation"]:::sonnet
  S5b["Step 5b: documentation generation"]:::sonnet
  S5c["Step 5c: quality gate (8 stages)"]
  S6["Step 6: Epic consistency check"]:::opus
  S7["Step 7: progress recording"]:::haiku
  S8["Step 8: move to next item"]

  S0 --> S1 --> S2
  S2 --> S3 --> S4 --> S5 --> S5b --> S5c
  S5c -->|PASS| S6 --> S7 --> S8
  S5c -->|FAIL| S5
  S8 -->|next Issue| S2

  classDef haiku fill:#dbeafe,stroke:#3b82f6
  classDef sonnet fill:#dcfce7,stroke:#22c55e
  classDef opus fill:#fef3c7,stroke:#f59e0b
```

1. **Step 0: manifest and platform resolution**

    Reads the `backlog-manifest.json` file and determines which issue-tracking platform to use — GitLab or GitHub.

2. **Step 1: shared-context pack build (first run only)**

    This work happens exactly once. Multiple sonnet <Tooltip tip="A small AI spun out for a specific role. The parent receives only the result." headline="sub-agents" cta="See in glossary" href="/glossary">sub-agents</Tooltip> run concurrently to build the [Shared-Context pack](/concepts/shared-context) — pre-assembled information that is shared across subsequent steps.

3. **Step 2: Issue selection (confirm with user)**

    Selects the next Issue to work on. If an in-progress item (`status::doing`) exists, it takes priority; otherwise the skill looks for an unstarted item (`status::todo`). Before proceeding, the user is asked to confirm the selected Issue.

4. **Step 3: consistency digest collection**

    Uses a haiku sub-agent to perform a read-only investigation of the codebase. The findings are called the "consistency digest" — a summary of information needed before implementation begins. No files are modified.

5. **Step 4: branch creation + mini-plan**

    Creates a working branch named `feature/<issue-id>-<slug>`, then has an opus sub-agent produce a concise implementation plan (mini-plan).

6. **Step 5: implementation**

    Sonnet sub-agents implement actual code concurrently, working in coherent units of change.

7. **Step 5b: documentation generation**

    Runs `/architect:generate-docs` to update the README and `docs/` to reflect the current changes. The updates are committed to the same branch as the code so they are reviewed together in the same PR/MR. If documentation drift is detected, it is recorded as a finding on the Issue rather than patched in place.

8. **Step 5c: quality gate (8 stages)**

    Runs `/architect:verify-implementation --gate`. Build, unit / contract / integration tests, SAST (static analysis for vulnerabilities), dependency vulnerability scan, API security review, and design-conformance check are applied in sequence across 8 stages.

    Each stage passes only if the corresponding command actually ran and succeeded — "probably fine" does not count as a pass. Stages that did not run are still recorded with a reason (`not-applicable` / `not-configured` / `skipped-by-user`). **A single FAIL blocks progression to Step 6.** Blockers are sent back to the Step 5 implementation agent and the gate is re-run. Only code that clears this gate is handed off for human review.

9. **Step 6: Epic consistency check**

    An opus sub-agent determines whether the current implementation aligns with the overall goal of the <Tooltip tip="The largest unit of work, grouping multiple Issues." headline="Epic" cta="See in glossary" href="/glossary">Epic</Tooltip>. This result feeds into the rollup triggered by `--review-epic`, which reviews multiple Issues together.

10. **Step 7: progress recording**

    A haiku sub-agent drafts a comment summarizing progress to date.

11. **Step 8: move to next item**

    Returns to Step 2 (Issue selection) and begins work on the next Issue.

## Model Assignment Rules

The guiding principle is "use the cheapest model capable of the task." The colors in the diagram above correspond to the models in this table.

| Task | Model | Diagram color | Rationale |
|---|---|---|---|
| Context collection (Explore), drafting progress comments | haiku | Blue | Straightforward work: read files and summarize |
| Shared-context pack generation, code implementation, documentation generation | sonnet | Green | Assembling documents and code according to a defined structure |
| Mini-plan creation, Epic consistency judgment, Epic rollup | **opus** | Yellow | Requires deep judgment about alignment with Epic-level goals and constraints |

## Branch Name Contract

The `feature/<issue-id>-<slug>` naming convention is applied when `implement-backlog` first creates a branch.
The separate `review-issue` and `merge-issue` skills then locate **that same branch name** to perform review and merge.
This naming rule is therefore an implicit shared contract among skills.

## Output Location Validation

Before writing any code, the skill verifies that the output location (`source_root`) is not excluded from Git tracking.

This is done with the command `git check-ignore -q <path>`, which checks whether a given path matches any `.gitignore` rule. An exit code of **1** means the path is not ignored — it is safe to write there.

The `generated/` directory is reserved for auto-generated output and is `.gitignore`d in most projects; the skill never writes there.

```bash
git check-ignore -q backend
echo "check-ignore exit: $?"   # 1 means not gitignored = safe to write
```

## Dependency Version Resolution

If an AI writes a library version number from memory (training knowledge), it may specify a version that does not exist or is already outdated. To prevent this, the rule file `@rules/dependency-versions.md` mandates: **never write a version number from memory — always look it up in the registry (the package distribution source).**

As a concrete example, `maven-metadata.xml` was fetched directly from Maven Central (the Java library distribution site) using `curl` to confirm the latest version. At the time, Spring Boot 4.1.0 was a freshly released minor version with no patch releases yet, so the more battle-tested 4.0.7 was chosen deliberately. The rationale for that decision is recorded in `work/version-decisions.json`.