@slamb2k/mad-skills 2.0.7 → 2.0.8

package/skills/brace/SKILL.md

@@ -1,13 +1,8 @@
 ---
 name: brace
-description: >
-  Initialize any project directory with the GOTCHA/BRACE framework for agentic
-  AI systems. Creates the 6-layer structure (Goals, Orchestration, Tools,
-  Context, Hard prompts, Args), BRACE build methodology, and a project
-  CLAUDE.md. Recommends claude-mem for persistent memory. Idempotent — safe
-  to run on existing projects. Triggers: "init gotcha", "setup brace", "brace",
-  "initialize framework", "bootstrap gotcha".
-argument-hint: [--no-brace] [--force]
+description: 'Initialize any project directory with the GOTCHA/BRACE framework for agentic AI systems. Creates the 6-layer structure (Goals, Orchestration, Tools, Context, Hard prompts, Args), BRACE build methodology, and a project CLAUDE.md. Recommends claude-mem for persistent memory. Idempotent — safe to run on existing projects. Triggers: "init gotcha", "setup brace", "brace", "initialize framework", "bootstrap gotcha".'
+argument-hint: "[--no-brace] [--force]"
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
 ---
 
 # Brace - GOTCHA/BRACE Framework Bootstrap
@@ -37,15 +32,246 @@ Taglines:
 - Structural integrity confirmed!
 - Brace for impact!
 
-Follow instructions in: [instructions.md](instructions.md)
+---
+
+Initialize any project directory with the GOTCHA/BRACE framework. Idempotent —
+safe to re-run on existing projects. Content templates and subagent prompts
+are in `references/`.
 
-## Subagent Architecture
+**Key principle:** Scan first, present plan, get approval, then act.
 
-- Phase 1 (scan): **Bash** subagent, **haiku** model
-- Phase 4 (scaffold): **general-purpose** subagent (content generation)
-- Phase 5 (verify): **Bash** subagent, **haiku** model
+Phase prompts: `references/phase-prompts.md`
+Scaffold manifest: `references/scaffold-manifest.md`
+Report format: `references/report-template.md`
+
+---
 
 ## Flags
 
-- `--no-brace` — Skip BRACE build methodology
+Parse optional flags from the request:
+- `--no-brace` — Skip BRACE build methodology (goals/build_app.md)
 - `--force` — Overwrite existing files without prompting
+
+---
+
+## Pre-flight
+
+Before starting, check all dependencies in this table:
+
+| Dependency | Type | Check | Required | Resolution | Detail |
+|-----------|------|-------|----------|------------|--------|
+| claude-mem | plugin | — | no | ask | `claude plugin install claude-mem` |
+
+For each row, in order:
+1. Run the Check command (for cli/npm) or test file existence (for agent/skill)
+2. If found: continue silently
+3. If missing: apply Resolution strategy
+   - **stop**: notify user with Detail, halt execution
+   - **url**: notify user with Detail (install link), halt execution
+   - **install**: notify user, run the command in Detail, continue if successful
+   - **ask**: notify user, offer to run command in Detail, continue either way (or halt if required)
+   - **fallback**: notify user with Detail, continue with degraded behavior
+4. After all checks: summarize what's available and what's degraded
+
+1. Capture **FLAGS** from the user's request
+2. Create a task list tracking all 5 phases
+
+---
+
+## Phase 1: Directory Scan
+
+Launch **Bash** subagent (**haiku**):
+
+```
+Task(
+  subagent_type: "Bash",
+  model: "haiku",
+  description: "Scan directory for existing GOTCHA structure",
+  prompt: <read from references/phase-prompts.md#phase-1>
+)
+```
+
+Parse SCAN_REPORT. Extract:
+- `directory_name` (used as default project name)
+- `existing_dirs` / `missing_dirs`
+- `existing_files` / `missing_files`
+- `has_claude_md` / `has_gitignore`
+- `has_atlas` (legacy ATLAS naming detected)
+- `has_forge` (legacy FORGE naming detected)
+- `has_legacy_memory` (old tools/memory system detected)
+
+---
+
+## Phase 1b: Legacy Upgrade Detection
+
+**Skip if none of `has_atlas`, `has_forge`, or `has_legacy_memory` is true.**
+
+Build a description of what was found:
+- If `has_atlas` or `has_forge`: "Legacy ATLAS/FORGE naming detected"
+- If `has_legacy_memory`: "Legacy memory system (tools/memory/, memory/) detected"
+
+Ask the user via AskUserQuestion:
+
+   Question: "Legacy components detected: {description}. Upgrade and clean up?"
+   Options:
+   - "Yes, upgrade all" — Replace legacy naming with BRACE and remove old memory system
+   - "No, leave as-is" — Keep existing naming and memory system
+
+Store result as `upgrade_legacy: true|false` in USER_CONFIG.
+
+---
+
+## Phase 2: Project Inquiry
+
+**Runs on primary thread** (user interaction required).
+
+1. Derive default project name from SCAN_REPORT `directory_name`
+2. Present via AskUserQuestion:
+
+   Question: "What to include in GOTCHA setup?"
+   Options:
+   - "Full GOTCHA + BRACE (Recommended)"
+   - "GOTCHA structure only (no BRACE methodology)"
+   - "Cancel"
+
+3. If not cancelled, ask for project description (one sentence) via
+   AskUserQuestion with free text.
+
+4. Ask installation level via AskUserQuestion:
+
+   Question: "Where should global preferences and universal principles go?"
+   Options:
+   - "Both — global + project (Recommended)" → portable AND global coverage
+   - "Global (~/.claude/CLAUDE.md) only" → applies to all projects
+   - "Project level only" → self-contained, portable
+
+5. Store as USER_CONFIG:
+   - project_name: from directory name or user override
+   - description: from user input
+   - include_brace: true/false (based on selection and `--no-brace`)
+   - install_level: "both" | "global" | "project"
+
+**If cancelled, stop here.**
+
+---
+
+## Phase 3: Present Plan & Approve
+
+Build the ACTION_PLAN from SCAN_REPORT + USER_CONFIG + FLAGS.
+
+For each item in `references/scaffold-manifest.md`:
+- If component not selected in USER_CONFIG → status: "not selected"
+- If item already exists (from SCAN_REPORT) and no `--force` → status: "skip"
+- If item exists and `--force` → status: "overwrite"
+- If CLAUDE.md exists → status: "merge" (append GOTCHA section)
+- If .gitignore exists → status: "merge" (append missing entries)
+- Otherwise → status: "create"
+
+If `upgrade_legacy` is true in USER_CONFIG, set status "upgrade" for:
+- CLAUDE.md (replaces "merge" or "skip" — upgrade takes priority)
+- goals/build_app.md (replaces "skip")
+- goals/manifest.md (replaces "skip")
+
+If `upgrade_legacy` is true AND `has_legacy_memory` is true, additionally:
+- `tools/memory/` → status: "remove"
+- `memory/` → status: "remove"
+- CLAUDE.md also gets memory section replacement (handled alongside upgrade)
+- `tools/manifest.md` → status: "cleanup" (remove memory tool rows)
+- `.gitignore` → status: "cleanup" (remove memory/*.npy entry)
+
+Present plan summary to user via AskUserQuestion:
+
+```
+GOTCHA Framework Setup for: {project_name}
+
+Will create:  {list of items with status "create"}
+Will merge:   {list of items with status "merge"}
+Will upgrade: {list of items with status "upgrade" — legacy → BRACE}
+Will remove:  {list of items with status "remove" — legacy memory system}
+Will clean:   {list of items with status "cleanup" — remove legacy references}
+Will skip:    {count} existing items
+Not selected: {count} items
+Global config: {install_level description}
+
+Proceed?
+```
+
+Options: "Yes, proceed" / "Cancel"
+
+**If cancelled, stop here.**
+
+---
+
+## Phase 4: Scaffold Structure
+
+Launch **general-purpose** subagent:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Create GOTCHA framework structure",
+  prompt: <read from references/phase-prompts.md#phase-4>
+)
+```
+
+Before sending the prompt, substitute these variables:
+- `{ACTION_PLAN}` — the action plan from Phase 3
+- `{PROJECT_NAME}` — from USER_CONFIG
+- `{PROJECT_DESCRIPTION}` — from USER_CONFIG
+- `{INSTALL_LEVEL}` — from USER_CONFIG ("both", "global", or "project")
+- `{CLAUDE_MD_TEMPLATE}` — read from `references/claude-md-template.md`
+  (the section between BEGIN TEMPLATE and END TEMPLATE)
+- `{GITIGNORE_CONTENT}` — read from `assets/gitignore-template`
+- `{GOALS_MANIFEST}` — read from `references/scaffold-manifest.md`
+  (the goals/manifest.md content block)
+- `{TOOLS_MANIFEST}` — read from `references/scaffold-manifest.md`
+  (the tools/manifest.md content block)
+- `{BRACE_WORKFLOW}` — read from `references/brace-workflow.md`
+  (the section after the header, used for goals/build_app.md)
+- `{GLOBAL_PREFERENCES_CONTENT}` — read from `assets/global-preferences-template.md`
+  (the section between BEGIN TEMPLATE and END TEMPLATE)
+
+Parse SCAFFOLD_REPORT. If status is "failed", report to user and stop.
+
+---
+
+## Phase 5: Verification & Report
+
+Launch **Bash** subagent (**haiku**):
+
+```
+Task(
+  subagent_type: "Bash",
+  model: "haiku",
+  description: "Verify GOTCHA structure",
+  prompt: <read from references/phase-prompts.md#phase-5>
+)
+```
+
+Parse VERIFY_REPORT. Present the final summary using the format in
+`references/report-template.md`.
+
+---
+
+## Idempotency Rules
+
+- **Skip** directories and files that already exist (unless `--force`)
+- **Merge** CLAUDE.md: append GOTCHA section if file exists but lacks it
+- **Merge** .gitignore: append missing entries only
+- **Never delete** user content
+- **Never overwrite** without `--force` or explicit user approval
+
+---
+
+## Error Handling
+
+Standard escalation pattern:
+1. If retryable (permission issue after mkdir): retry once
+2. If persistent: report to user with specific error
+3. Offer: skip and continue / abort
+4. Never silently swallow errors
+
+Common issues:
+- Permission denied → report, suggest checking directory permissions
+- CLAUDE.md merge conflict → show both versions, let user choose
+- Directory is read-only → abort with clear message

package/skills/brace/assets/gitignore-template

@@ -15,9 +15,6 @@ data/
 # Temp & scratch
 .tmp/
 
-# Memory embeddings cache
-memory/*.npy
-
 # Python
 __pycache__/
 *.pyc

package/skills/brace/references/phase-prompts.md

@@ -47,6 +47,12 @@ Limit your SCAN_REPORT to 20 lines maximum.
      fi
    done
 
+7. Check for legacy memory system:
+   legacy_memory=false
+   if [ -d "tools/memory" ] || [ -f "memory/MEMORY.md" ]; then
+     legacy_memory=true
+   fi
+
 ## Output Format
 
 SCAN_REPORT:
@@ -60,6 +66,7 @@ SCAN_REPORT:
   has_gitignore: true|false
   has_atlas: true|false
   has_forge: true|false
+  has_legacy_memory: true|false
 ```
 
 ---
@@ -114,6 +121,25 @@ legacy methodology references with BRACE equivalents while preserving all other
 - **goals/build_app.md:** Replace the entire file with the BRACE workflow content below.
 - **goals/manifest.md:** Replace "ATLAS" or "FORGE" with "BRACE" in the description column.
 
+### For "remove" items (legacy memory cleanup):
+
+1. Before deleting `memory/MEMORY.md`, check if it contains a "## Key Decisions"
+   section. If so, extract that section content into `preserved_content` for the
+   SCAFFOLD_REPORT so the user can relocate it.
+2. Remove `tools/memory/` — use `git rm -r tools/memory` if tracked, otherwise `rm -rf tools/memory`
+3. Remove `memory/` — use `git rm -r memory` if tracked, otherwise `rm -rf memory`
+
+### For "cleanup" items (legacy memory references):
+
+- **tools/manifest.md:** Remove any rows referencing `memory/` tools (e.g. search, embed, store scripts)
+- **.gitignore:** Remove the `memory/*.npy` line and its `# Memory embeddings cache` comment if present
+- **CLAUDE.md:** If a `## Memory System` section exists, replace it with:
+  ```
+  ## Memory
+  This project uses claude-mem for persistent cross-session memory.
+  ```
+  Also remove `tools/memory/` and `memory/` from any directory tree listings in CLAUDE.md.
+
 ### Global preferences (conditional)
 
 If INSTALL_LEVEL is "global" or "both":
@@ -178,6 +204,9 @@ SCAFFOLD_REPORT:
   created: [list of files/dirs created]
   merged: [list of files merged]
   upgraded: [list of files upgraded to BRACE]
+  removed: [list of legacy items removed]
+  cleaned: [list of files cleaned of legacy references]
+  preserved_content: [any key decisions extracted from memory/MEMORY.md, or empty]
   skipped: [list of items skipped]
   global_updated: true|false|skipped
   errors: [any errors encountered]
@@ -216,6 +245,13 @@ Limit your VERIFY_REPORT to 15 lines maximum.
    done
    echo "gitignore entries: $entries/2"
 
+5. If legacy memory cleanup was performed, verify removal:
+   if [ -d "tools/memory" ]; then echo "legacy: tools/memory still exists"; fi
+   if [ -d "memory" ]; then echo "legacy: memory/ still exists"; fi
+   if [ -f "CLAUDE.md" ] && grep -q "tools/memory" CLAUDE.md; then
+     echo "legacy: CLAUDE.md still references tools/memory"
+   fi
+
 ## Output Format
 
 VERIFY_REPORT:
@@ -224,5 +260,6 @@ VERIFY_REPORT:
   files_verified: {count}/{expected}
   claude_md_has_gotcha: true|false
   gitignore_entries: {count}/{expected}
+  legacy_memory_cleaned: true|false|not_applicable
   issues: [any problems found]
 ```

package/skills/brace/references/report-template.md

@@ -25,6 +25,10 @@ Brace Complete!
     {status} goals/build_app.md
     {status} tools/manifest.md
 
+  Removed: (only if legacy memory was cleaned up)
+    {status} tools/memory/     Legacy memory scripts
+    {status} memory/           Legacy memory directory
+
   Notes:
     {any warnings or skipped items}
 
@@ -35,4 +39,4 @@ Brace Complete!
     4. Start building with the BRACE methodology
 ```
 
-Status indicators: [created] [exists] [merged] [upgraded] [skipped] [failed]
+Status indicators: [created] [exists] [merged] [upgraded] [removed] [skipped] [failed]

package/skills/build/SKILL.md

@@ -1,12 +1,8 @@
 ---
 name: build
-description: >
-  Context-isolated feature development pipeline. Takes a detailed design/plan
-  as argument and executes the full feature-dev lifecycle (explore, question,
-  architect, implement, review, ship) inside subagents so the primary
-  conversation stays compact. Use when you have a well-defined plan and want
-  autonomous execution with minimal context window consumption.
-argument-hint: Detailed design/plan to implement
+description: Context-isolated feature development pipeline. Takes a detailed design/plan as argument and executes the full feature-dev lifecycle (explore, question, architect, implement, review, ship) inside subagents so the primary conversation stays compact. Use when you have a well-defined plan and want autonomous execution with minimal context window consumption.
+argument-hint: <detailed design/plan to implement> [--skip-questions] [--skip-review] [--no-ship] [--parallel-impl]
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
 ---
 
 # Build - Context-Isolated Feature Development
@@ -36,13 +32,296 @@ Taglines:
 - 🧱 Bricks, mortar, and semicolons!
 - 🏎️ Let's see what this baby can do!
 
-Follow instructions in: [instructions.md](instructions.md)
+---
+
+Execute a detailed design/plan through the full feature-dev lifecycle with
+maximum context isolation. Every heavy stage runs in a subagent so the primary
+conversation only accumulates structured reports.
 
-Architecture, agent types, and report budgets are documented in `references/`.
+Stage prompts: `references/stage-prompts.md`
+Report budgets: `references/report-contracts.md`
+Agent selection: `references/architecture-notes.md`
+Project detection: `references/project-detection.md`
 
 ## Flags
 
-- `--skip-questions`: Skip clarifying questions (plan is fully specified)
-- `--skip-review`: Skip code review stage
-- `--no-ship`: Stop after docs update (don't commit/push/PR)
-- `--parallel-impl`: Allow parallel implementation agents
+Parse optional flags from the request:
+- `--skip-questions`: Skip Stage 2 (clarifying questions)
+- `--skip-review`: Skip Stage 5 (code review)
+- `--no-ship`: Stop after Stage 8 docs update
+- `--parallel-impl`: Split implementation into parallel agents when independent
+
+---
+
+## Pre-flight
+
+Before starting, check all dependencies in this table:
+
+| Dependency | Type | Check | Required | Resolution | Detail |
+|-----------|------|-------|----------|------------|--------|
+| ship | skill | `.claude/skills/ship/SKILL.md` | yes | stop | Install with: npx skills add slamb2k/mad-skills --skill ship |
+| feature-dev:code-explorer | agent | — | no | fallback | Uses general-purpose agent |
+| feature-dev:code-architect | agent | — | no | fallback | Uses general-purpose agent |
+| feature-dev:code-reviewer | agent | — | no | fallback | Uses general-purpose agent |
+
+For each row, in order:
+1. Run the Check command (for cli/npm) or test file existence (for agent/skill)
+2. If found: continue silently
+3. If missing: apply Resolution strategy
+   - **stop**: notify user with Detail, halt execution
+   - **url**: notify user with Detail (install link), halt execution
+   - **install**: notify user, run the command in Detail, continue if successful
+   - **ask**: notify user, offer to run command in Detail, continue either way (or halt if required)
+   - **fallback**: notify user with Detail, continue with degraded behavior
+4. After all checks: summarize what's available and what's degraded
+
+1. Capture **PLAN** (the user's argument) and **FLAGS**
+2. Detect project type using `references/project-detection.md` to populate
+   **PROJECT_CONFIG** (language, test_runner, test_setup)
+3. Check for outstanding questions from previous work:
+   - Search CLAUDE.md for a "Known Issues" or "Open Questions" section
+   - Search `goals/` for files containing "open_question" or "unresolved"
+   - Search memory (if available) for recent items of type "task" or
+     "open_question" that are unresolved
+   - Check for `DEBRIEF_ITEMS` in any recent build logs
+4. If outstanding items found, present via AskUserQuestion:
+   ```
+   "Found {count} outstanding items from previous work:"
+   {numbered list with summary of each}
+   "Address any of these before starting the build?"
+   ```
+   Options:
+   - **"Yes, let me choose which ones"** → present each; options:
+     "Incorporate into this build" / "Skip for now" / "Explain more"
+     Items marked "incorporate" get appended to the PLAN as additional
+     requirements for Stage 1 to explore.
+   - **"No, proceed with the build"** → continue normally
+5. Create a task list tracking all stages
+
+---
+
+## Stage 1: Explore
+
+Launch **feature-dev:code-explorer** (fallback: general-purpose):
+
+```
+Task(
+  subagent_type: "feature-dev:code-explorer",
+  description: "Explore codebase for build plan",
+  prompt: <read from references/stage-prompts.md#stage-1>
+)
+```
+
+Substitute `{PLAN}` into the prompt.
+Parse EXPLORE_REPORT. Extract `questions` for Stage 2.
+
+---
+
+## Stage 2: Clarifying Questions
+
+**Skip if `--skip-questions` or no questions found.**
+
+Runs on the **primary thread** (requires user interaction).
+
+1. Review EXPLORE_REPORT `questions` and `potential_issues`
+2. Present questions to user via AskUserQuestion
+3. Store answers as CLARIFICATIONS
+
+---
+
+## Stage 3: Architecture Design
+
+Launch **feature-dev:code-architect** (fallback: general-purpose):
+
+```
+Task(
+  subagent_type: "feature-dev:code-architect",
+  description: "Design implementation architecture",
+  prompt: <read from references/stage-prompts.md#stage-3>
+)
+```
+
+Substitute `{PLAN}`, `{EXPLORE_REPORT}`, `{CLARIFICATIONS}`.
+Parse ARCH_REPORT. Present `approach_summary` to user for confirmation.
+
+If rejected, incorporate feedback and re-run.
+
+---
+
+## Stage 4: Implementation
+
+If `--parallel-impl` and ARCH_REPORT has independent `parallel_groups`,
+launch **multiple general-purpose subagents in parallel**.
+
+Otherwise launch **one general-purpose subagent**:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Implement plan",
+  prompt: <read from references/stage-prompts.md#stage-4>
+)
+```
+
+Substitute `{PLAN}`, `{ARCH_REPORT}`, conventions, `{PROJECT_CONFIG.test_runner}`.
+Parse IMPL_REPORT(s). If any failed, assess retry or abort.
+
+---
+
+## Stage 5: Code Review
+
+**Skip if `--skip-review`.**
+
+Launch **3 feature-dev:code-reviewer subagents in parallel** (fallback: general-purpose):
+
+1. Simplicity & DRY
+2. Bugs & Correctness
+3. Conventions & Integration
+
+Prompts in `references/stage-prompts.md#stage-5`.
+
+Consolidate reports. Present **only critical and high severity findings**.
+Ask: "Fix these now, or proceed as-is?"
+
+---
+
+## Stage 6: Fix Review Findings
+
+**Only if Stage 5 found issues AND user wants them fixed.**
+
+Launch **general-purpose subagent**:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Fix review findings",
+  prompt: <read from references/stage-prompts.md#stage-6>
+)
+```
+
+---
+
+## Stage 7: Verify
+
+Launch **Bash subagent** (haiku):
+
+```
+Task(
+  subagent_type: "Bash",
+  model: "haiku",
+  description: "Run verification tests",
+  prompt: <read from references/stage-prompts.md#stage-7>
+)
+```
+
+Substitute `{PROJECT_CONFIG.test_runner}` and `{PROJECT_CONFIG.test_setup}`.
+
+If tests fail:
+- First failure: launch general-purpose agent to fix, retry
+- Second failure: report to user and stop
+
+---
+
+## Stage 8: Update Progress Documentation
+
+**Skip if EXPLORE_REPORT has no `source_docs`.**
+
+Launch **general-purpose subagent**:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Update progress documentation",
+  prompt: <read from references/stage-prompts.md#stage-8>
+)
+```
+
+**If `--no-ship`: Stop here and present final summary.**
+
+---
+
+## Stage 9: Ship
+
+Invoke the `/ship` skill:
+
+```
+/ship {approach_summary from ARCH_REPORT}. Files: {files from IMPL_REPORT}
+```
+
+---
+
+## Stage 10: Debrief
+
+**Always runs** on the primary thread (requires user interaction).
+
+1. Scan all stage reports for unresolved items:
+   - EXPLORE_REPORT: `potential_issues` not addressed by implementation
+   - ARCH_REPORT: `risks` with deferred mitigations
+   - REVIEW_REPORT: `medium`/`low` findings not fixed in Stage 6
+   - TEST_REPORT: warnings, skipped tests, flaky results
+   - DOCS_REPORT: `docs_skipped` items
+   - IMPL_REPORT: `issues_encountered` that were worked around
+
+2. Compile into DEBRIEF_ITEMS (see `references/stage-prompts.md#stage-10`).
+   Categorise each as: unresolved_risk, deferred_fix, open_question,
+   assumption, or tech_debt.
+
+3. **If no items found, skip to Final Report.**
+
+4. Present numbered summary via AskUserQuestion grouped by category.
+   Each item shows: `[category] summary (effort)`.
+
+   Options:
+   - **"Fix now"** → create a task list of resolution activities for
+     each item; present for user confirmation, then work through them
+   - **"Create goals for future sessions"** → write goal files to `goals/`
+     (if GOTCHA structure exists) or append to CLAUDE.md as Known Issues
+   - **"Note and continue"** → acknowledge items without formal tracking;
+     log to memory (if exists) or as source file comments. No further action.
+   - **"Let me choose per item"** → present each individually with full
+     description, evidence, and impact. Options per item:
+     "Fix now" / "Add to goals" / "Explain more" / "Note and continue".
+     "Explain more" reads source files cited in evidence, provides
+     expanded context, then re-presents the item for decision.
+
+5. After resolution, include debrief summary in the Final Report.
+
+---
+
+## Final Report
+
+```
+Build complete
+
+  Plan:     {first line of PLAN}
+  Approach: {approach_summary}
+
+  Files modified: {count}
+  Files created:  {count}
+  Tests:          {passed}/{total}
+
+  Docs updated: {count or "none"}
+
+  PR: {pr_url} (merged at {merge_commit})
+
+  Key decisions:
+  - {decision 1}
+  - {decision 2}
+
+  Review findings addressed: {count fixed} / {count found}
+
+  Debrief: {count resolved} / {count surfaced} items addressed
+    {list of items created as goals or tasks, if any}
+```
+
+If any stage failed, report the failure point and what was accomplished.
+
+---
+
+## Rollback
+
+If implementation succeeds but later stages fail:
+- Tests fail: fix agent attempts repair, then reports to user
+- Review critical: user decides fix or proceed
+- Ship fails: code is still committed locally; user can manually push
+- Never silently revert completed implementation work