implement-backlog

Files (2)

• SKILL.md
• output-location.test.sh

SKILL.md (first lines)

# Backlog Implementation (Epic-Consistent)

Shared files: a path written `@rules/…`, `@skills/…`, `@templates/…` or `@docs/…` is relative to the
plugin root, `${CLAUDE_PLUGIN_ROOT}` — not to the project being worked on. Read it from there.

**Usage:** `/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]`

Runs as a thin orchestrator that delegates heavy steps to model-tiered sub-agents
(haiku/sonnet/opus) to minimize token cost.

## Desired Outcome

Implement a selected backlog item while keeping the whole Epic coherent:

- **Consistency across the Epic.** Every change is made with the parent Epic (What / Why / Key
  Results) and all sibling Sub-Epics and Issues in view, reusing their contracts and avoiding
  conflicts (naming, API shapes, data model, ubiquitous language, NFR budgets).
- **Visible progress.** The executed work is appended back onto the Epic / Sub-Epic / Issue on the
  tracker (comments + status labels), and mirrored to a local implementation log.
- **Docs that ship with the code.** The README(s) and `docs/` pages covering the changed surface
  are updated on the same branch, so code and documentation are reviewed and merged together.
- **Whole-Epic optimization.** A lightweight consistency review runs after each item, and an
  on-demand roll-up review spans the whole Epic.
- **Shared source of truth.** Cross-cutting rules (architecture, coding standards, ubiquitous
  language, data contracts, NFR budgets) are assembled once into a referenceable pack and consulted
  on every item, with new cross-cutting decisions recorded so later items stay aligned.

Code lands in the target project's **source tree** (see Output Location); the tracker and
`reports/backlog/` hold the progress trail. This skill runs against the **target project** (the one
holding `reports/` and the backlog), the same way other architect skills operate — it never edits
nexus-architect itself.

## Decision Criteria

- **Item selection** — Use the item given as an argument (local id like `I1.2.3`, `#<iid>`, or a
  URL). With no argument, list items labeled `status::doing`, and confirm the pick with the user via
  AskUserQuestion. If none are `doing`, offer `status::todo` / ready items under the active Epic.
  Never start implementing an item the user has not confirmed (unless `--auto`).
- **Scope** — An **Issue** is implemented directly. A **Sub-Epic** drives its Issues in dependency
  order, confirming each. An **Epic** drives its Sub-Epics. Default focus is Issue-level.
- **Consistency over local speed** — When a sibling already defines a contract, interface, or naming
  the item depends on, reuse it. Do not introduce a competing pattern; if the existing one is wrong,
  raise it as a finding rather than silently diverging.
- **Fabrication ban** — Implement only what the item's acceptance criteria and the referenced design
  reports specify. Do not invent requirements, endpoints, or numbers.
- **Output location** — Code written here is a **deliverable**: it is committed, reviewed in a
  PR/MR, and merged. It therefore belongs in the target project's real source tree, **not** in
  `generated/`, which the output structure contract (@templates/output-structure.md) reserves for regenerable
  pipeline output and which target projects commonly git-ignore alongside `reports/` and `work/`.
  See Output Location for how the source root is resolved and verified.

## Output Location

Resolve the **source root** once per item, in this precedence:

1. `--out=<path>` — explicit override, always wins.
2. `source_root` recorded in `shared-context/decisions.md` by a previous item — reuse it so every
   item under the Epic writes to the same place.
3. The existing repo layout — an already-present service/module directory matching the item's
   service (e.g. `services/<service>/`, `apps/<service>/`, or a build-tool root such as
   `settings.gradle`/`pom.xml`/`pnpm-workspace.yaml` member).
4. Greenfield repo with no source yet — propose `services/{service}/` (service naming per
   `architecture-guardrails.md`) and confirm with the user via AskUserQuestion, unless `--auto`.

The resolved root must satisfy two checks before any code is written:

- **Not git-ignored** — `git check-ignore -q <source_root>` must exit **1** (no ignore rule
  matches). Exit 0 means the path is ignored, so `git add` would silently stage nothing and the
  downstream review → PR/MR → merge chain would break on an empty commit; stop and report the
  matching rule (`git check-ignore -v <source_root>`) rather than writing code into it. Any other
  exit status is a git error — surface it instead of assuming the path is safe.
- **Inside the repo** — the root resolves within the target project's git worktree.

Record the resolved root as a `source_root` decision in `shared-context/decisions.md` the first time
it is established. Pass `--out=generated/<service>/` explicitly when the intent genuinely is
throwaway scaffolding rather than merge-bound work.

The rules in this section are asserted as behaviour by
`skills/implement-backlog/output-location.test.sh` (the ignore gate, the working-branch commit, and
empty-commit detection, on a scratch repository) — run it after changing them.

## Prerequisites

| File / source | Required/Recommended | Produced by |
|---------------|----------------------|-------------|
| `reports/backlog/backlog-manifest.json` | Required | /architect:export-backlog |
| The tracker (GitLab/GitHub) with the Epic/Sub-Epic/Issue items | Required | /architect:export-backlog |
| `reports/` design & product artifacts (referenced by item traceability IDs) | Required | product / architect pipelines |
| `glab` / `gh` authenticated for the target project | Required | user |

Read the output language from `work/pipeline-progress.json` (`options.output_language`, default
`en`); `--lang` overrides it. Generated report/comment text uses that language; code identifiers,
label keys, and traceability IDs stay in English (per the repo language rule).

## Status Taxonomy (shared with export-backlog)

Scoped labels on GitLab, plain labels on GitHub:
`status::todo` · `status::doing` · `status::review` · `status::done` · `status::blocked`
(GitHub form: `status:todo` …). If the labels do not exist, create them once. Default selection
target is `doing`.

## Sub-Agent Execution & Model Assignment

This skill runs as a **thin orchestrator (sonnet)** that delegates the heavy steps to sub-agents
(Agent tool; see @skills/common/sub-agent-patterns.md), each pinned to the cheapest model tier
that can do the job. Two rules keep token cost minimal:

- **Context protection** — the orchestrator never bulk-reads design reports, sibling Issues, or
  the produced code itself. Sub-agents read them and return compact digests; the orchestrator holds
  only the manifest, the digests, the mini-plan, and the tracker state.
- **Cheapest-capable tier** — haiku for mechanical transforms, sonnet for structured generation and
  analysis, opus **only** for judgment (planning against Epic-wide contracts, consistency
  verdicts). Escalate a delegated step one tier only when the item is judgment-heavy (ambiguous
  contracts, distributed-transaction/2PC design, cross-service data ownership); never use opus for
  work a cheaper tier can do.

| Step | Delegated work | Sub-agent (model) | Returns to orchestrator |
|------|----------------|-------------------|-------------------------|
| 1 | Derive each shared-context file from its source reports | one **sonnet** agent per file, in parallel | file written + 1-line summary |

From wfukatsu/nexus-architect, MIT.

More from wfukatsu/nexus-architect