--- 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 `, 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 ` with `run_in_background: true`. - Never narrate a wait you are not actually running. If you cannot sustain one, say so plainly and stop. ## 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 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. ### 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. ### 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. ### 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** (Agent tool, `subagent_type: general-purpose` — FOREGROUND, and **never `fork`**: a fork inherits your context, which is the bias you are trying to escape). Hand it only what it can verify itself — repo path, the spec/requirement, `git diff` range, the commands — never your own conclusions. 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 — added` or `UNIT-TESTS: FAIL — :: `. - **Suite run → plain Bash, here.** Backend changed → `npm run test:server`. Frontend → `npm run test:client`. 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 ""`, or `--result fail` with what failed. A step you could not run is reported as not run, never as passed. ### 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** (the official plugin's, run as `/code-review` on the working diff). It is not optional and is not replaced by an agent reviewing "in its own words" — run it in a **fresh-context agent** (`subagent_type: Code Reviewer`, FOREGROUND, never `fork`; a reviewer that watched you write the code is not a reviewer), whose job is to invoke that skill and report its findings. See **superpowers:requesting-code-review** for what to hand over. Final line: `REVIEW: CLEAN` or `REVIEW: FINDINGS — `. - **Domain reviewers, conditional on the touched layers**, launched in parallel with the above (same message, separate Agent calls) — FOREGROUND, fresh context, never `fork`: - 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 — `. - 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. ### 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. - For a change of any real size, the gate is a **fresh-context agent** too (`general-purpose`, FOREGROUND, never `fork`): 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 — `. A one-line fix does not need it; anything you would defend in a review does. - **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 ""` ### 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. - `agenthub stage done --status passed --evidence ""` ## 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`