AgentHub/skills/ship-feature/SKILL.md

---
name: ship-feature
description: Implement a feature safely end-to-end in this repository. Use when adding or changing functionality across backend, frontend, or MCP with required verification and documentation updates. Drives the Superpowers workflow skills and declares each phase with `agenthub stage` so the dashboard's pipeline map follows along. Brainstorms WITH the user at intake, stops for their approval of the plan before any code, reviews with Claude Code's own `code-review` plus only the domain reviewers the diff actually needs, and stops again at the gate for their acceptance — a NO-GO loops back to implement or plan rather than shipping.
---

# Ship Feature

Use this workflow for medium or large implementation tasks. It does not restate
how to plan, test, or review — the Superpowers skills own that. What lives here
is the phase order, this repository's own rules, and the stage declaration at
each boundary.

For a feature inside a AgentHub **lane**, use `ship-feature-lane` instead: it adds
the branch/e2e/QC/senior-gate/PR half this skill deliberately leaves out.

## Declaring the stage

Each phase below starts with `agenthub stage <node>`, which is what puts the phase
on the lane's pipeline map. The nodes are the `default` template's:
`intake → plan → implement → tests → review → gate → ship → done`.

Set the template yourself, don't rely on how the lane was created: before your
first `agenthub stage` call, run `agenthub lanes pipeline default` (no id needed —
resolves from `cwd`; a no-op if the lane is already on it). This is what makes
the choice invisible to the human — whichever of `ship-feature` or
`ship-feature-lane` actually runs is what decides the template, not a picker
they have to get right in advance.

`agenthub stage` needs a lane owning the current directory. If it reports no lane,
this repo was never adopted (`agenthub lanes add --cwd $(pwd)` fixes it) — carry on
with the workflow and skip the stage calls; they are reporting, not control
flow. Never skip a phase because its stage call failed.

Declaring beats detection. The dashboard also *infers* these stages from the
Superpowers skill invocations below, but an inference never renders `done` and
never overrides a declaration — and detection cannot move a lane BACKWARD past
a declared stage, so a rework loop is invisible unless you re-declare the phase
you dropped back to.

## Waiting for an agent or a long command

A phase that dispatches a foreground agent (tests, review, gate) or runs a long
command is **already** wired to wake you: you are re-invoked the moment a
backgrounded Agent or helper finishes. So:

- Do not poll for it, and do not invent a timer. **`ScheduleWakeup` is a
  `/loop`-only primitive** — this pipeline is not a `/loop` session, so it
  neither paces nor sustains anything here, and in `auto` permission mode it can
  simply be refused (the safety classifier is a model call, which fails when
  that model is briefly unavailable). Never let a phase's progress depend on it.
- Need to pace a wait anyway (a CI run, an external queue)? Background the wait:
  `sleep <secs>` with `run_in_background: true`.
- Never narrate a wait you are not actually running. If you cannot sustain one,
  say so plainly and stop.

## The shape of a run

Forward: `intake → plan → implement → tests → review → gate → ship → done`.
Two back-edges, and they are the point of the pipeline, not its failure mode:

- **`tests`/`review` → `implement`** — a failure or a finding sends you to the
  code, then forward through `tests` and `review` again.
- **`gate` → `plan`** — a NO-GO about the APPROACH (wrong scope, wrong shape,
  the requirement meant something else) replans and re-earns the user's
  approval. A NO-GO about a DEFECT goes to `implement` instead.

Going back is a declaration: re-run `agenthub stage <node>` for the node you
dropped to. Detection cannot move a lane backward on its own, so a silent
rework leaves the dashboard showing a stage you already left, and the nodes
ahead keep the previous pass's evidence.

## Right-size the run before you start it

This pipeline is not free: every phase that dispatches an agent costs a model
call and minutes of wall clock, and the fix-loop pays it again on each lap.
Match its weight to the work, and say in one line which weight you picked.

| Work | What runs |
|---|---|
| **Trivial** — typo, rename, one-line fix, a question | Not this skill. Do it, run the touched suite, say what you did. |
| **Small** — one layer, a few files, no new interface | `intake` questions → `implement` → `tests` → `review` with `code-review` alone → `gate` (the user's acceptance IS the gate). Skip the plan-debate agent, the independent-test agent and the gate agent. |
| **Medium / large** — multi-file, new route/schema/interface, cross-layer, or anything you would defend in a review | Every phase below, in full. |

Sizing is a claim you make out loud, not a shortcut you take quietly. When
torn, take the heavier one. A small task that grows re-sizes upward mid-run —
re-declare the phase you re-enter and pick up the skipped agents from there.

## Dispatching a judgement (used by `tests`, `review`, `gate`)

One contract, written once, so the phases below don't each re-argue it:

- **Fresh context, FOREGROUND, never `fork`.** A fork inherits your context —
  precisely the bias the dispatch exists to escape. Foreground because the phase
  gates on the answer, and the agent's completion is what re-invokes you.
- **Hand only what the agent can verify for itself**: the repo path, the
  requirement/plan, the `git diff` range, the commands to run. Never your
  conclusions — "I already checked X", "this is safe because…" — those are the
  very claims it is there to test.
- **One parseable final line** is the verdict (`UNIT-TESTS:`, `REVIEW:`,
  `BACKEND-REVIEW:`, `FRONTEND-REVIEW:`, `GATE:`). Read that line; never infer a
  pass from prose around it.
- **Never dispatch what a command answers.** Running a suite, reading a log,
  grepping a path — do it yourself. An agent is for judgement, not for typing.
- Agents for the same phase go out in **one message** so they run concurrently.

## Resuming after a compaction

A long run outlives the context window. Re-derive your position, don't guess it:

- `agenthub lanes` — the lane's declared stage, status and notes.
- `git status` + `git diff --stat <base>...` — what is actually built.
- The plan file — what was actually approved.

Resume at the declared stage and re-run it from the top; every `agenthub`
command is idempotent. **A phase whose evidence you cannot find did not
happen** — re-run it rather than assuming a past self did.

## Phases

### intake — brainstorm WITH the user, always
- `agenthub stage intake --status running`
- Restate the requirement and its success criteria.
- Explore the impacted modules: `Explore` agent for breadth, then read the key
  files yourself. Identify which layers are hit (server / client / docs /
  scripts) — `repo-onboarding` if the area is unfamiliar.
- **superpowers:brainstorming is MANDATORY here, not a fallback for a fuzzy
  requirement.** Run it before any plan exists. Skipping it because the ask
  "seems clear" is the single most common way this pipeline builds the wrong
  thing: a requirement typed in one line always leaves scope, edge cases and
  acceptance criteria unstated.
- **Ask only what the repo cannot answer.** Read first, ask second: a question
  whose answer is in the code, the tests, `CLAUDE.md` or the existing UI costs
  the user's time and earns you a worse answer than reading would. What belongs
  to the user is intent — scope, priorities, trade-offs, what "done" means —
  never facts you could have looked up.
- **Ask the user, and wait for the answer.** Put the open questions to them with
  `AskUserQuestion` — batched in one round (up to 4 at a time), each with real
  options, exactly the way plan mode asks. Questions that change what you build:
  scope boundaries, which surfaces are in/out, behavior on the edge cases you
  found, what "done" means. You may not answer them on the user's behalf, and
  you may not move to `plan` until they are answered. Answering yourself and
  proceeding IS the bug this phase exists to prevent.
- The one exception: the user explicitly said to skip the questions and decide
  yourself ("cứ làm đi", "no questions", "you decide"). Then state the
  assumptions you are proceeding under, in writing, and go on.
- **Leave when:** the user's answers are in hand (or their explicit "decide
  yourself" is), and you can state the scope, the non-goals and what "done"
  means in your own words without a guess in any of them.

### plan — a written plan, challenged, then APPROVED by the user
- `agenthub stage plan`
- **superpowers:writing-plans**: approach, files to change, the test strategy
  (which behavior each test pins), and how each success criterion is met.
- If the task is a bug rather than a feature: **superpowers:systematic-debugging**
  first. Root cause, not symptom — and grep every caller of the function you
  are about to change, not just the path the report names.
- Have the plan **challenged by a fresh-context agent** (`Plan` or
  `general-purpose`, never `fork`): missed requirements, wrong assumptions, a
  simpler approach, unhandled edge cases. Give it the requirement and the plan,
  not your reasons for believing the plan. Apply what survives
  **superpowers:receiving-code-review** scrutiny.
- **STOP. The plan is presented to the user and implementation does not start
  until they approve it in this turn.** Show the plan (or its path plus a short
  summary: what changes, which files, what is deliberately out of scope, how it
  will be verified) and ask with `AskUserQuestion` — approve / revise / change
  approach. "Revise" means edit the plan and ask again; the loop is the point.
  Writing a plan and immediately implementing it is exactly the behavior this
  phase forbids, however obvious the plan looks to you.
- Approval covers the plan as presented. Work that turns out to need a
  materially different approach comes BACK here (`agenthub stage plan` again)
  for a fresh approval, rather than drifting under the old one.
- **Leave when:** a written plan exists, it survived the challenge, and the user
  approved THIS version of it in this turn.

### implement — smallest coherent diff
- `agenthub stage implementing`
- Entered only from an **approved** plan (or from a gate NO-GO sending work
  back here). No approval in this turn → you are still in `plan`.
- **superpowers:test-driven-development**: failing test → minimal code → green.
- Smallest diff that satisfies the requirement. Every changed line traces to it.
- **file-headers** applies to every source file you create or edit.
- Work the approved plan task by task, in its order. Before leaving this phase,
  re-read the plan's acceptance criteria and check each one against what you
  actually built — that list, not your memory of it, is what `gate` will ask
  about.
- **The plan turning out wrong is a result, not a detour.** If implementing
  shows the approach cannot work, or the requirement means something else, stop
  and go back to `plan` (re-declare it, present the new plan, get it approved
  again). Quietly building a different thing than the one approved is the
  failure this phase has to avoid.
- Long implementation? Re-declare `agenthub stage implementing` as you go — it
  doubles as the heartbeat, so the dashboard doesn't read a working lane as
  stalled.
- **Leave when:** every plan task is done, every acceptance criterion has
  something concrete behind it, and the diff contains nothing that traces to
  neither.

### tests — this repo's verification, not a claim
- `agenthub stage tests --status running`
- **Dispatch the judgement, run the commands yourself.** Only work that needs an
  unbiased pair of eyes is worth an agent; a deterministic command is not.
  - **Independent unit tests → a fresh-context agent** (`general-purpose`; see
    *Dispatching a judgement*). It reads the requirement
    and the diff cold and writes the tests the implementation is *missing* —
    happy, negative and boundary, in the repo's existing style. It may not touch
    non-test files nor weaken existing tests. Final line:
    `UNIT-TESTS: PASS — <n> added` or `UNIT-TESTS: FAIL — <test> :: <defect>`.
  - **Suite run → plain Bash, here.** Run the suite(s) the diff actually needs:
    backend changed → `npm run test:server`; frontend changed →
    `npm run test:client`; both → both. A docs-only change needs neither, and
    running the other layer's suite proves nothing about this diff. Nothing is judged, so nothing is
    delegated: an agent for this buys a second model's tokens to read output you
    can read for free. A UI snapshot diff is reported for review, **never
    blindly regenerated** (`cd client && npx vitest run -u` is yours to run,
    only after you read the diff).
- `FAIL` → fix the **source** (root cause), not the agent's test — then re-run
  this phase. Rewriting a failing independent test to pass is the one move that
  makes this whole phase worthless.
- Record the outcome: `agenthub stage tests --evidence "<what passed>"`, or
  `--result fail` with what failed. A step you could not run is reported as not
  run, never as passed.
- **Leave when:** the suites the diff needs are green in output you actually
  read, and the independent-test agent (when the size called for one) returned
  `PASS`.

### review — the native review, plus the domains this diff actually touched
- `agenthub stage review --status running`
- **Read the diff first, then decide who reviews it.** `git diff --name-only`
  against the base this task started from is what picks the reviewers. Spawning
  a fixed set regardless of what changed wastes a pass on files nobody touched,
  and worse, reads as coverage that never happened.
- **Scale the pass to the diff.** A handful of lines in one layer gets the
  `code-review` pass alone — three agents re-reading a 20-line change costs
  three times the tokens for one opinion. Add the domain reviewer(s) once the
  change is big enough to have seams: multiple files in a layer, a route or
  schema or hook touched, or anything you would want a second reader on.
- **Always: Claude Code's own `code-review` skill** (`/code-review`, on the
  working diff — it is also what the `review` node declares). Not optional, and
  not replaced by an agent reviewing "in its own words": run it in a
  fresh-context `Code Reviewer` agent whose job is to invoke that skill and
  report what it found (a reviewer that watched you write the code is not a
  reviewer). See **superpowers:requesting-code-review** for what to hand over.
  Final line: `REVIEW: CLEAN` or `REVIEW: FINDINGS — <n>`.
- **Domain reviewers, conditional on the touched layers**, in the same message
  as the above so they run concurrently:
  - Any path under `server/` (routes, lib, hooks, db, CLI-facing code) →
    `agenthub:backend-reviewer`. No backend path changed → do not launch it.
  - Any path under `client/` (components, pages, i18n, styles) →
    `agenthub:frontend-reviewer`. No frontend path changed → do not launch it.
  - Both touched → both, in the same message so they run concurrently.
  - Neither touched (docs-only, scripts-only, config-only) → neither; the
    `code-review` pass above is the whole review.
  - Hand each ONLY the repo path and the working diff — each scopes itself to
    its own domain's files. Each ends with its own parseable line:
    `BACKEND-REVIEW:` / `FRONTEND-REVIEW:` — `CLEAN` or `FINDINGS — <n>`.
- Apply what is worth applying — `code-review` plus every domain reviewer that
  ran — with **superpowers:receiving-code-review** judgment: verify each point,
  neither blind agreement nor blind rejection. A point you reject is answered
  with a reason, not silence.
- **Changed code in response? Re-run `tests`, then re-run THIS phase.** Review
  is a loop, not a checkpoint: it ends when a pass over the current diff comes
  back clean (or with only findings you have explicitly and defensibly
  rejected), not when one pass has been performed.
- Record it: `agenthub stage review --evidence "<n> findings across <who ran>,
  resolved"`.
- **Leave when:** the latest pass over the CURRENT diff is clean or
  argued-through — not when a pass has merely happened.

### gate — evidence, then the user's acceptance
- **superpowers:verification-before-completion**. Commands actually run, output
  actually read. This is the phase that stops "should work" from shipping.
- At medium/large size the gate is a **fresh-context agent** too
  (`general-purpose`): hand it the requirement, the diff range and the
  verification commands — not your evidence — and let it re-run and re-check
  them. Final line: `GATE: GO` or `GATE: NO-GO — <what is missing>`. At small
  size skip it; the user's acceptance below is the gate.
- **The gate is not yours to wave through. Ask the user.** Present, in a few
  lines: what was built, what was verified and how (the commands and their real
  outcome), what review found and what you did about it, and anything you could
  not run. Then ask with `AskUserQuestion`: accept / send back for fixes /
  rethink the approach. Silence is not acceptance, and neither is `GATE: GO` —
  the agent gate checks the evidence, the user decides whether this is what they
  wanted.
- **NO-GO, or the user does not accept → go BACK, do not proceed.** Pick the
  node by the size of what is wrong, and re-declare it so the dashboard follows
  the rework (a declaration on an earlier node clears the nodes ahead of it —
  that is what makes a loop visible instead of leaving stale `done` evidence):
  - A defect, a missed case, a wrong detail → `agenthub stage implementing`, fix
    at the root cause, then forward through `tests` and `review` again.
  - Wrong approach, wrong scope, a requirement that turns out to mean something
    else → `agenthub stage plan`, replan, and get the plan approved again (the
    `plan` phase's approval step applies in full, every time through).
  - Either way the phases after it run again. Never carry a NO-GO forward into
    `ship` with a note about it.
- Only once the user has accepted: `agenthub stage gate --evidence "<what was
  verified, and that the user accepted it>"`
- **Leave when:** the verification really ran, its output was really read, and
  the user said yes. Two of three is a NO-GO.

### ship — docs, then the user's call
- `agenthub stage ship`
- **update-project-docs** — mandatory for any change to behavior, config,
  interfaces, events, schema, CLI commands, or features. Not optional, not
  deferred, not "if asked".
- Commit / push / PR **only when the user asks in this turn**. Finishing an
  implementation is not authorization to commit.
- **Leave when:** the docs that the change made wrong are right again, and you
  have reported plainly what shipped, what was verified, and what you skipped.
- `agenthub stage done --status passed --evidence "<what shipped>"`

## This repository's own rules

Not restated here. `CLAUDE.md` is loaded in every session and already binds
them — backward-compatible API/WebSocket contracts, fail-safe hooks,
migration-safe schema changes, the destructive-lane and git-argv guards, and
the lane boundaries (the console never writes a stage; the runtime never writes
`stage`/`status`/`notes`). A second copy here would only drift out of sync with
the first. Read `CLAUDE.md` and `.claude/rules/` for the area you are touching.

## References
- Checklist template: `references/feature-checklist.md`