claude/skills/ship-feature/SKILL.md

---
name: ship-feature
description: Use when shipping a new feature end-to-end — needs design brainstorm, planning, TDD implementation with subagents, error recovery, code review, and finish. Multi-agent orchestrator (9-step pipeline). Triggers: "ship feature", "ship-feature", "build and merge", "feature end-to-end", "implement and ship".
argument-hint: <feature description>
allowed-tools: Read, Write, Edit, Bash, Grep, Glob
---

# ORCHESTRATOR: SHIP FEATURE

## REQUEST
$ARGUMENTS

---

## STEP 0 — PLUGIN CHECK + AUTO-ACTIVATE
Load `$HOME/.claude/agents/plugin-advisor.md`. Feed request.
- ACTION REQUIRED → show RECOMMENDATIONS block, offer: A) fix plugins B) type "force". STOP.
- PROPOSED CHANGES exist → show list, ask "Apply? (yes / no / customize)". Apply on confirm.
- OK → `✅ Plugin check passed — [active plugins] — complexity: <score>%`, continue.

## STEP 0b — PROJECT CONTEXT CHECK
Verify the project has a `CLAUDE.md` and print a brief orientation summary:
```bash
ls CLAUDE.md .claude/CLAUDE.md 2>/dev/null | head -1
git branch --show-current 2>/dev/null || echo "not a git repo"
git log --oneline -3 --format="%h %<(50,trunc)%s" 2>/dev/null || true
ls .gsd/ROADMAP.md 2>/dev/null | head -1
```
- **CLAUDE.md found** → read it silently, then print orientation header (informational, not a gate):
  ```
  📋 PROJECT CONTEXT
  Project : <name from CLAUDE.md>
  Stack   : <stack from CLAUDE.md>
  Branch  : <current git branch>
  Recent  : <last 3 commit messages>
  GSD     : <current milestone if .gsd/ROADMAP.md exists, else "not initialized">
  ```
  Continue to STEP 1.
- **Not found** →
  Print: "⚠️ No CLAUDE.md found in this directory.
  This project has not been onboarded into claude-config.
  Run `/onboard` first to generate CLAUDE.md and project settings,
  then re-run `/ship-feature`."
  STOP.

## STEP 0c — CTX7 CACHE CHECK (if fast-libs in project)
Check if the project uses fast-evolving libs (scan `package.json` for next, react, prisma, supabase, drizzle, expo):
1. If `.ctx7-cache/` exists with recent files (<7 days old) → print `📚 ctx7 cache found: <libs>` and continue.
2. If `.ctx7-cache/` missing or stale AND `ctx7` is installed AND fast-libs detected:
   ```bash
   mkdir -p .ctx7-cache
   # Fetch docs for each detected fast-lib (adapt to actual deps):
   ctx7 docs /vercel/next.js "app router middleware routing" > .ctx7-cache/nextjs-core.md 2>/dev/null || true
   ctx7 docs /prisma/prisma "schema client queries" > .ctx7-cache/prisma-core.md 2>/dev/null || true
   ```
   Print: `📚 ctx7 docs pre-fetched for: <libs>`
3. If no fast-libs or `ctx7` not installed → skip silently.

During implementation (STEP 4), when making decisions about fast-lib APIs:
- Read the relevant `.ctx7-cache/<lib>.md` file before writing code.
- This avoids repeated ctx7 calls and keeps docs available without context cost.

## STEP 1 — BRAINSTORM
Invoke `superpowers:brainstorming`. Refine request into validated design via Socratic questioning. Don't proceed until design approved.

## STEP 2 — PLAN
Invoke `superpowers:writing-plans`. Break design into tasks (2-5 min each). Each task: exact file paths, full code, verification steps.

## STEP 3 — VALIDATION GATE ★ MANDATORY STOP
```
SHIP FEATURE — VALIDATION GATE
FEATURE: <n> | TASKS: <count>
<numbered task list>
Approve and execute? (yes / request changes)
```
Changes → back to STEP 2. Approved → continue.

## STEP 4 — IMPLEMENT
Invoke `superpowers:subagent-driven-development`. Isolated subagents. 2-stage review per task: spec compliance → code quality.

## STEP 4b — ERROR RECOVERY (if STEP 4 fails)
If a subagent returns a build error, failing test, or type error:
1. Load `$HOME/.claude/agents/analyzer.md` in DEBUG MODE on the exact error output.
   Produce: root cause hypotheses (ordered), affected files, what NOT to touch.
2. Present gate:
```
SHIP FEATURE — ERROR IN STEP 4
TASK    : <task name that failed>
ERROR   : <one-line summary>
HYPOTHESES:
  1. [HIGH] <cause> — evidence: <…>
  2. [MED]  <cause> — evidence: <…>
OPTIONS :
  A) Apply fix for hypothesis 1 and re-run this task
  B) Skip this task and continue with remaining tasks
  C) Abort feature — preserve work done so far
```
3. Wait for user choice. Do NOT auto-fix. Do NOT proceed without explicit approval.
4. If A → apply minimal fix, re-run STEP 4 for the failed task only. Max 2 retry attempts.
   If still failing after 2 → fall back to options B or C.
   If B → before skipping: scan remaining task list for tasks that depend on the failed task
     (look for references to the same file or function in subsequent tasks).
     If dependents found → present: "Tasks [N, M] depend on the skipped task.
       Skip them too? (yes / keep and accept partial implementation)"
     If no dependents → skip cleanly and continue.

## STEP 5 — ANALYZE
Load `$HOME/.claude/agents/analyzer.md`. Check: no regressions, no stale code, no plan deviations.

## STEP 6 — CODE REVIEW
Invoke `superpowers:requesting-code-review`. Fix all CRITICAL before proceeding.

## STEP 7 — CAPITALIZE (memory registries)
Feature shipped implies at least one design decision worth capturing. Run this BEFORE STEP 8 FINISH — the implementation commits (STEP 4) already exist, so the entries' hash references are valid, and the memory commit lands on the branch that FINISH integrates (otherwise it strands outside the PR):

1. Scan conversation context for:
   - **Design / architecture choices with rationale** → candidate for `decisions.md` (BDR-XXX).
   - **Reusable patterns, surprising discoveries** → candidate for `learnings.md` (LRN-XXX).
   - **Dead-ends with identified root cause** → candidate for `blockers.md` (BLK-XXX).
2. For each candidate, pre-fill a full entry (ID, date, title, body per registry schema) from conversation context.
3. Present them grouped:
   ```
   CAPITALIZE — registres proposés
   
   [ decisions.md ]
     BDR-XXX — <titre> — <1-line why>
   [ learnings.md ]
     LRN-XXX — <pattern>
   [ blockers.md ]
     (aucun)
   
   Valider lesquels ? (all / <IDs> / edit / skip)
   ```
4. Append approved entries to the registries. Update the Index table at the top of each file.
5. Append a one-line entry to `.claude/memory/journal.md` under today's date heading (`## YYYY-MM-DD`).

**Language rule**: written entries are ALWAYS in English (see CLAUDE.md "Memory registries" § Language). The interactive gate above may mirror the user's language; the appended entries must not.

If nothing substantive to log → print `CAPITALIZE: nothing substantive to log` and skip.

**Then commit the memory** — follow `$HOME/.claude/lib/capitalize-commit.md`: it
surgically commits what capitalize just wrote (`.claude/memory` + `.claude/tasks`
only, never `git add -A`) as one `chore(memory)` commit, reports the memory-commit
hash, and no-ops if nothing was written. It runs BEFORE STEP 8 FINISH so the
memory is integrated with the branch, not stranded outside the PR.

## STEP 8 — FINISH
Invoke `superpowers:finishing-a-development-branch`. Tests pass, build clean, ready to merge.

## STEP 9 — DOC SYNC
<!-- Stays post-FINISH = TWIN CHANTIER: doc-sync has the same PR-stranding bug
     capitalize just fixed (artifacts written after integration). Deferred to
     v-next; move it before FINISH then. Not fixed here to keep v1 scoped. -->
Load `$HOME/.claude/agents/doc-syncer.md`.
Execute in automatic mode:
`auto-mode scope: <list of files modified during this session>`

---

## RULES
- No skipping steps. No merged agent responsibilities.
- No implement without user approval at STEP 3.
- Subagents isolated — no shared context between tasks.
- Fix all CRITICAL review issues before proceeding.
- Stop if requirements unclear at any step.
- STEP 4 errors → STEP 4b gate required before any fix. Never auto-patch a failing subagent.

---

## FAILURE PATHS (orchestrator-level)

The pipeline must handle these without aborting silently:

| Situation | Behavior |
|---|---|
| STEP 0b — `CLAUDE.md` missing | STOP with the printed message ("Run `/onboard` first…"). Do not proceed. |
| STEP 0c — `ctx7` not installed but fast-libs detected | Skip pre-fetch silently. During STEP 4, log `📚 ctx7 cache miss for <lib>` and continue with vanilla model knowledge. |
| STEP 1 — brainstorming returns "design unclear" twice | Escalate: ask user "Switch to /init-project (greenfield-style design) or refine the feature request?" |
| STEP 3 — user replies "request changes" | Loop back to STEP 2 with user's notes. Cap at 3 iterations; on the 3rd "request changes" without approval, ask "Pause and rescope this feature?" |
| STEP 4 — subagent crashes (tool error, not test failure) | Treat as STEP 4b error path, present hypothesis-led gate. |
| STEP 4b — option A retried 2× still failing | Force fall-through to B or C. Do not loop a 3rd time. |
| STEP 6 — review returns CRITICAL items | Loop back to STEP 4 for those items only. Cap at 2 review-cycle iterations; if still CRITICAL, escalate. |
| STEP 7 — `.claude/memory/` missing | Create the registry files from `~/.claude/templates/memory/` first, then proceed. |

---

## FINAL OUTPUT
```
FEATURE SHIPPED: <n>
TASKS: <N>/<N> | TESTS: ✅/❌ | REVIEW: APPROVED/CHANGES REQUIRED
REMAINING ISSUES: <list or none>
```