Files

T

nntrivi2001 effdaf4ba8 feat(skills): run every judging stage in a fresh-context subagent

The session that writes the code is the worst judge of it: it believes the
code is correct and remembers the reasoning its tests are meant to challenge.
Split the pipelines along a judge/do boundary — the driving session implements,
runs the mechanical gates, publishes and applies fixes; every stage whose job
is to judge the work is dispatched to a subagent with an EMPTY context.

ship-feature-lane:
- New hard rule: plan debate (0b), unit tests (1b), e2e (3), code review (4),
  browser QC (6) and the senior gate (7) run in fresh-context agents.
  `subagent_type: fork` is forbidden for these — a fork inherits the
  implementing session's context, which is the bias being escaped.
- New Stage 1b: an independent agent writes the unit tests the implementation
  is missing (test files only, no weakening existing tests) and returns
  UNIT-TESTS: PASS/FAIL. A FAIL is fixed in the source, never in the test.
- Stage 3 delegates the e2e run + triage (the poll/timeout discipline moves
  into the agent's brief); Stage 4 delegates the code-review skill run.
- Stages 6/7 keep their agents but may no longer be primed with the driving
  session's context, conclusions or known-issue list.
- Stage 10: CI still red on the same job after a fix goes to a fresh agent —
  calling your own failure a flake twice pushes a real defect past the gate.
- Fix-loop: a re-entry touching non-test source re-runs Stage 1b first.

ship-feature: same boundary for the plan, tests, review and gate phases.

docs/LANES.md updated to match.

2026-08-21 16:59:57 +07:00

7.3 KiB

Raw Blame History

name, description

name	description
ship-feature	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 `ccam 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 CCAM 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 ccam 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 ccam stage call, run ccam 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.

ccam stage needs a lane owning the current directory. If it reports no lane, this repo was never adopted (ccam 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

ccam 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 / mcp / 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

ccam 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

ccam 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

ccam 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. MCP → npm run mcp:typecheck + npm run mcp:build. 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: ccam 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

ccam 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>.
Apply what is worth applying 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.
ccam stage gate --evidence "<what was verified>"

ship — docs, then the user's call

ccam 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.
ccam 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

7.3 KiB Raw Blame History