Feature Resume

/feature-resume "" [--status] [--share] [--list]

Tells you exactly where a feature is and what to run next. Use this after any interruption, crash, or context switch.

Flags:

• (no flag) — navigation mode: current position, stage progress, next command
• --status — session briefing mode: what was done, current blockers, next agenda
• --share — condensed standup/team format (implies --status)
• --list — list all active features with their current stage (ignores slug argument)

Works for both /feature and /feature-quick slugs.

Step 0 — List mode (--list)

If --list flag is set:

1. List all directories under .feature/ (excluding _archive/ and project-config.md)
2. For each directory, read status.md and extract: stage, substage, last updated timestamp. Also check for work_group field or double-dash convention (<group>--<wd>) to identify work-group-sourced features.
3. If .work/ exists and any features are work-group-sourced, group them by work group. Display:

───────────────────────────────────────────────
📋 ACTIVE FEATURES
───────────────────────────────────────────────

Work group: <group-slug> (N/M complete)
  <slug>            <stage> · <substage>            <last updated>
  <slug>            <stage> · <substage>            <last updated>

Standalone:
  <slug>            <stage> · <substage>            <last updated>
───────────────────────────────────────────────

If no features are work-group-sourced, use the flat format (no grouping):

───────────────────────────────────────────────
📋 ACTIVE FEATURES
───────────────────────────────────────────────
  <slug>            <stage> · <substage>            <last updated>
───────────────────────────────────────────────

Sort by last updated (most recent first) within each group. If no features exist, display: No active features. Start one with /feature "<description>" or /feature-quick "<description>"

Stop. Do not continue to other steps.

Step 0a — Progress tracking

Use TodoWrite to show progress in the Claude Code UI (visible via Ctrl+T). Each TodoWrite call replaces the full list — always include all items.

After reading status.md (Step 1), build a pipeline-level checklist showing where the feature currently is. Mark stages based on status.md data.

If auto-invoke triggers (Step 3), add the invoked command as a new item and let the invoked command take over TodoWrite from there.

Example:

[
  {"id": "pipeline-scoping", "content": "Scoping", "status": "completed", "priority": "medium"},
  {"id": "pipeline-domains", "content": "Domain analysis", "status": "completed", "priority": "medium"},
  {"id": "pipeline-planning", "content": "Work planning", "status": "completed", "priority": "medium"},
  {"id": "pipeline-testing", "content": "Test writing", "status": "completed", "priority": "medium"},
  {"id": "pipeline-implementation", "content": "Implementation", "status": "in_progress", "priority": "high",
   "activeForm": "Resuming — 3/5 tests passing"},
  {"id": "pipeline-refactor", "content": "Refactor & review", "status": "pending", "priority": "medium"},
  {"id": "pipeline-pr", "content": "PR draft", "status": "pending", "priority": "medium"}
]

Step 1 — Read status

Check .feature/<slug>/status.md. If it does not exist:

No status file found for '<slug>'.

Options:
  - If this is a new feature: /feature "<slug description>"
  - If status.md was accidentally deleted: run each stage command — they will
    check for their prerequisite files and tell you what is missing.

Stop.

Reconcile against durable artifacts

.feature/<slug>/ is gitignored. When a sibling WD authors a spec that this WD's produces: declares, the manifest learns about it but this feature's status.md does not — the local cache lives only on whoever ran the spec-authoring session. Re-entering on a fresh machine then misreads "Spec Authoring pending" even though the spec is APPROVED and committed.

Run the reconciler before reading status.md so it reflects durable truth:

bash .claude/scripts/feature-state-reconcile.sh "<slug>"

The script:

• Detects work-group features (status.md work_group: field or <group>--<wd> slug pattern). No-op for plain features.
• Reads the WD's produces: list and looks up each spec's state in the manifest.
• If every produced spec is APPROVED: flips the Spec Authoring row in status.md to complete with today's date, leaving the Estimated/Actual token columns alone.
• Idempotent — a re-run on already-reconciled state writes nothing and prints "current".

If the script reported drift, surface that one-line summary above the "CURRENT POSITION" header so the user sees what was reconciled.

Step 1b — Mode dispatch

If --share flag: run --status mode, then condense output to share format (see Step 5b). If --status flag: skip to Step 5 — Session briefing. Otherwise: continue to Step 2 — Navigation mode.

Step 1c — Work group context

If this feature is work-group-sourced (status.md has work_group field, or slug matches <group>--<wd> pattern), show work group progress after the header in Step 2:

Work group: <group-slug> · <complete>/<total> work definitions complete

This is a single line of context — don't run the full resolver here, just count WD files and their statuses via work_fm on each WD file.

Step 2 — Display the full status report

───────────────────────────────────────────────
🔄 FEATURE RESUME · <slug>
───────────────────────────────────────────────

CURRENT POSITION
Stage:      <stage>
Substage:   <substage>
Last checkpoint: <last successful checkpoint>
Last updated:    <timestamp>
Automation: <autonomous | manual | not-set (will ask on next /feature-implement)>
<If execution_strategy is balanced or speed:>
EXECUTION: parallel (<balanced|speed>)

STAGE PROGRESS
  ✓ Scoping        complete    <date>
  ✓ Domains        complete    <date>
  ✓ Planning       complete    <date>
  ↻ Testing        in-progress  cycle 1 — tests written, verifying failures
  · Implementation not-started
  · Refactor       not-started

TOKEN USAGE (from Stage Completion table in status.md)
  Read the Stage Completion table and display estimated vs actual:

  | Stage          | Est.   | Actual         | Δ       |
  |----------------|--------|----------------|---------|
  | Scoping        | ~5K    | 4.2K in / 3K out | -16%  |
  | Domains        | ~6K    | 8.1K in / 2K out | +35%  |
  | Planning       | ~8K    | 7.5K in / 5K out | -6%   |
  | Testing        | ~5K    | —              | —       |
  | Implementation | —      | —              | —       |
  | Refactor       | —      | —              | —       |
  | **Total**      | **~24K** | **19.8K in / 10K out** | |

  The Δ column compares estimated tokens to actual input tokens.
  Calculate as: ((actual_input - estimate) / estimate × 100), rounded.
  Only show for completed stages with both values present.

  If token-log.md also exists, additionally run:
  `bash -c '[[ -f .claude/scripts/token-usage.sh ]] && source .claude/scripts/token-usage.sh && token_report ".feature/<slug>"'`
  and display below the comparison table.

DOMAIN STATUS (if domains stage was reached)
  ✓ <domain>   resolved    ADR: .decisions/<adr>/adr.md
  ✓ <domain>   resolved    KB: .kb/<topic>/<cat>/<subject>.md
  ✗ <domain>   pending     commissioned <date> — not yet complete

TDD CYCLES (if testing was reached)
  Cycle 1: tests <date> | passing <date or "—"> | refactor <date or "—"> | missing: <n>
  Cycle 2: ...

<If .decisions/.decision-candidates has status: new entries:>
  ℹ <n> decision candidates pending review (/decisions candidates)
───────────────────────────────────────────────

Step 2b — Work unit next-command resolution

If work_units: none in status.md: skip this section.

If work units are defined, determine the precise next command:

1. Find the first unit that is in-progress → that unit needs its current stage continued (check substage in status.md)
2. If no in-progress unit, find the first not-started unit → that unit needs /feature-test "<slug>" --unit WU-<n>
3. If all units are complete → feature is ready for /feature-pr
4. If a unit is blocked → its dependencies need to complete first

If execution_strategy is balanced or speed: read per-unit units/WU-N/status.md for each unit's current stage/substage and display with batch grouping:

Work units:
  Batch 1 (complete):
    ✓ WU-1: <name>
  Batch 2 (in-progress):
    ↻ WU-2: <name> — implementing (cycle 1)
    ↻ WU-3: <name> — testing (cycle 1)
  Batch 3 (waiting):
    ○ WU-4: <name> — blocked (waiting on WU-2, WU-3)

Otherwise (sequential/cost mode): display the work unit table with dependency info as part of the resume output:

Work units:
  ✓ WU-1: <name> — complete
  → WU-2: <name> — in-progress (implementing, cycle 1)   ← active
    └─ depends on: WU-1
  ○ WU-3: <name> — blocked (waiting on WU-2)
    └─ depends on: WU-1, WU-2

  Progress: <n complete> / <n total>

The "Next command" line must include the --unit flag (sequential mode) or use the coordinator (parallel mode):

<sequential:> Next: /feature-implement "<slug>" --unit WU-2
<parallel:>   Next: /feature-coordinate "<slug>"

Step 3 — Determine and display what to run next

Read the Pipeline mode field from status.md (default: full).

Full mode routing (pipeline_mode: full)

Specification mode routing (pipeline_mode: specification)

This mode stops after spec authoring. Used when a work definition produces specification artifacts rather than implementing behavior.

Note: Planning, Testing, Hardening, Implementation, and Refactor stages are skipped in specification mode. After spec authoring completes, the specification phase is done. Do NOT proceed to /feature-retro or /feature-complete — those run after implementation via /work-start.

Implementation mode routing (pipeline_mode: implementation)

This mode starts at planning. Used when specification was done in a prior phase and artifacts already exist.

Note: Scoping, Domains, and Spec Authoring stages are skipped in implementation mode. Planning reads specification artifacts directly.

If automation_mode: autonomous and the feature is mid-implementation or mid-refactor: note this in the Next Step display:

NOTE: This feature is in autonomous mode. Stages will chain automatically.
Type stop at any time during a run to pause.

Display the specific next command clearly:

NEXT STEP
  <command to run>
  <one sentence explaining why>

Auto-invoke rules (apply after displaying the NEXT STEP block):

• If the next step resolves to /feature-domains (stage is scoping/complete): invoke /feature-domains "<slug>" as a sub-agent immediately. Domain analysis requires no external action to proceed.

• If the next step resolves to /feature-plan (stage is domains/complete or planning/in-progress): invoke /feature-plan "<slug>" as a sub-agent immediately. Planning requires no external action to proceed.

• If automation_mode: autonomous AND execution_strategy is balanced or speed AND work units remain incomplete: invoke /feature-coordinate "<slug>" as a sub-agent immediately.

• If automation_mode: autonomous AND the next step resolves to /feature-implement or /feature-refactor (stages testing/complete, implementation/in-progress, or implementation/complete): invoke the appropriate command as a sub-agent immediately. A crash should not break the autonomous loop — resuming after a crash is equivalent to re-entering the same stage that was interrupted.

• If the next step resolves to /feature-pr (stage is refactor/complete):

  Feature is ready for PR.
  

  Use AskUserQuestion with options:

  • "Draft PR"
  • "Stop"

  If "Draft PR": invoke /feature-pr "<slug>" as a sub-agent immediately. If "Stop": display Next: /feature-pr "<slug>" and stop.

• If the next step resolves to /feature-retro (stage is pr/created and cycle-log.md has no retro-complete entry): prompt for retrospective.

  PR is open. A retrospective captures what worked and what didn't while
  the feature is fresh — it writes back to the KB and decisions store.
  

  Use AskUserQuestion with options:

  • "Run retrospective"
  • "Skip"

  If "Run retrospective": invoke /feature-retro "<slug>" as a sub-agent immediately. If "Skip": display When the PR merges: /feature-complete "<slug>" and stop.

  If cycle-log.md already has a retro-complete entry: skip the retro prompt and display When the PR merges: /feature-complete "<slug>" instead.

For pending domain commissions, list each:

PENDING DOMAINS — complete these before re-running /feature-domains:
  1. <domain> — Run: /research "<subject>"
  2. <domain> — Run: /architect "<problem statement>"

Step 4 — Show recent cycle-log entries (last 3)

If cycle-log.md exists, display the last three entries to provide context on what actually happened most recently. This is especially useful after a crash where the substage in status.md might be stale.

RECENT ACTIVITY (from cycle-log.md)
<last 3 entries>

Step 5 — Session briefing (--status mode)

Load additional context beyond status.md:

1. .feature/<slug>/brief.md or status.md Description (quick tasks)
2. .feature/<slug>/cycle-log.md — full history
3. .feature/<slug>/work-plan.md if it exists — construct completion
4. .feature/<slug>/test-plan.md if it exists — test coverage

Display:

───────────────────────────────────────────────
📊 FEATURE STATUS · <slug>
<YYYY-MM-DD> | <full pipeline / quick task>
───────────────────────────────────────────────

WHAT THIS IS
<2–3 sentences from brief summary.>

── Progress ───────────────────────────────────
  ✓ Scoping        <date>
  ✓ Domains        <date> — <n> domains resolved, <n> ADRs consulted
  ✓ Planning       <date> — <n> constructs
  ↻ Testing        in progress — cycle <n>
  · Implementation not started
  · Refactor       not started

<If work units:>
── Work Units ─────────────────────────────────
  Read the Work Units table from status.md. For each unit, read the
  Depends On column to build the dependency graph.

  Display units grouped by dependency layer (topological order):

  Layer 0 (no dependencies):
    ✓ WU-1: <name> — complete
    ✓ WU-4: <name> — complete

  Layer 1 (depends on layer 0):
    → WU-2: <name> — implementing (cycle 1, 4/7 tests passing)
      └─ depends on: WU-1

  Layer 2 (depends on layer 1):
    ○ WU-3: <name> — blocked (waiting on WU-2)
      └─ depends on: WU-1, WU-2

  If execution_strategy is balanced or speed, also show batch info:
    Batch 1 (complete): WU-1, WU-4
    Batch 2 (in-progress): WU-2
    Batch 3 (waiting): WU-3
    Critical path: <n> sequential batches

  Progress: <n complete> / <n total> units
  Est. remaining sessions: <n>

── What Was Done Last Session ─────────────────
<Synthesise the most recent 3–5 cycle-log entries into plain English.
Not a raw dump — a readable summary of what actually happened.
Example: "The Work Planner identified 4 constructs and wrote stubs.
The Test Writer wrote 12 tests covering the happy path and 3 error
conditions — all verified failing.">

── Current Blocker ────────────────────────────
<If active escalation in cycle-log.md: describe in one paragraph.
If no blocker: "None — ready to continue.">

── Next Session Agenda ────────────────────────
<3–5 concrete bullet points. Not "continue implementation" but
"implement TokenBucket.consume() and RateLimitMiddleware.handle() —
these are the two remaining failing tests.">
  1. <specific task>
  2. <specific task>
  3. ...

TO CONTINUE: <exact command to run>
───────────────────────────────────────────────

<If work-plan.md exists, append construct completion table:>

CONSTRUCTS
  ✓ <ConstructName>   <src/path>   tests passing
  ↻ <ConstructName>   <src/path>   <n> tests failing
  · <ConstructName>   <src/path>   not started

Determine construct status from: work-plan.md (planned), cycle-log.md implemented entries (completed), test-plan.md (test mapping). If results aren't in the log, mark "status unknown — run tests to confirm".

Step 5b — Share format (--share)

Condense the session briefing to standup/team format:

📋 <slug> — <one-line summary>
Stage: <stage> | Cycle: <n><  | Units: <n>/<total>>

Done: <bullet points of completed stages>
Next: <1–2 sentences on what's next>
Blocker: <one sentence or "none">

Full details: .feature/<slug>/