nntrivi2001
c7dbaf2d9f
Two leftovers from the rebrand, done together because they touch the same docs and manifests. **Data directory.** `agent-dashboard` could not simply be renamed in the source: it names a real directory holding the live SQLite database. Startup now moves it once, via `migrateLegacyDataDir()` in `server/lib/claude-home.js` — a same-filesystem rename, so it is instant even at multiple gigabytes and cannot leave two divergent copies. `getDataDir()` stays PURE and resolves to the legacy path until the move happens; the first version of this put the rename inside the getter, which meant `npm run test:server` relocated the developer's real database as a side effect. The call sits behind `require.main === module` and ahead of the router requires, because those pull in db.js, which opens SQLite at module load. A failed rename is silent and the old directory keeps being used: an unfashionable directory name beats a blank database beside an unreachable one. Same treatment for the port-discovery file (`.agent-dashboard.json` → `.agenthub.json`, old one dropped on write). Not renamed on purpose: the Sagi localStorage keys (renaming silently resets everyone's prefs) and the PWA manifest `id` (changing it orphans an installed app). **MCP server.** 4 tool calls in 46 days across 577,132 events, against 4,556 lines of TypeScript, a 2 MB committed build artifact, and a pre-commit guard that had already blocked commits twice. Deleted: `mcp/`, the maintainer skills and `mcp-reviewer` agent, the build check, `plugins/agenthub/.mcp.json`, `docs/MCP.md`, 12 npm scripts, 5 Makefile targets, and every doc section describing it. Kept, because they are unrelated things sharing the name: the Config Explorer's MCP tab and its API, per-lane Playwright MCP, the agenthub-config plugin's MCP audit, and the historical `mcp__plugin_agenthub_*` events that analytics must keep attributing. Verified: server 1432/1432, client 459/459, tsc clean, prettier clean. Both directions of the migration proven — a sandbox-HOME test run leaves the legacy directory untouched, and a real boot moves it with its contents intact.
149 lines
8.1 KiB
Markdown
149 lines
8.1 KiB
Markdown
---
|
|
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.
|
|
---
|
|
|
|
# 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.
|
|
|
|
## Phases
|
|
|
|
### intake — understand before touching anything
|
|
- `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.
|
|
- Requirement fuzzy or open to more than one reading? **superpowers:brainstorming**.
|
|
|
|
### plan — a written plan, challenged before it is code
|
|
- `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.
|
|
|
|
### implement — smallest coherent diff
|
|
- `agenthub stage implementing`
|
|
- **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, don't self-grade.** Both halves below run in 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.
|
|
- **Independent unit tests.** 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.** Backend changed → `npm run test:server`. Frontend →
|
|
`npm run test:client`.
|
|
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.
|
|
|
|
### review — a real review pass, not a re-read
|
|
- `agenthub stage review --status running`
|
|
- Hand the review to a **fresh-context agent** (`subagent_type: Code Reviewer`,
|
|
FOREGROUND, never `fork`) — a reviewer that watched you write the code is not
|
|
a reviewer. It runs the **code-review** skill on the working diff
|
|
(see also **superpowers:requesting-code-review** for what to hand over).
|
|
Final line: `REVIEW: CLEAN` or `REVIEW: FINDINGS — <n>`.
|
|
- **Domain reviewers, in parallel with the above (same message, separate
|
|
Agent calls).** Check `git diff --name-only` (against the base this task
|
|
started from) for touched layers and launch every matching one —
|
|
FOREGROUND, fresh context, never `fork`, addressed as `agenthub:backend-reviewer`
|
|
/ `agenthub:frontend-reviewer`:
|
|
- Any path under `server/` → `agenthub:backend-reviewer`.
|
|
- Any path under `client/` → `agenthub:frontend-reviewer`.
|
|
- Neither touched → skip both; the generic Code Reviewer
|
|
above is the only gate.
|
|
- 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 — the generic review plus every domain
|
|
reviewer that ran — with **superpowers:receiving-code-review** judgment:
|
|
verify each point, neither blind agreement nor blind rejection.
|
|
- Changed code in response? Re-run the `tests` phase.
|
|
|
|
### gate — evidence before the completion claim
|
|
- **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 — <what is
|
|
missing>`. A one-line fix does not need it; anything you would defend in a
|
|
review does.
|
|
- `agenthub stage gate --evidence "<what was verified>"`
|
|
|
|
### 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 "<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`
|