@arthai/agents 1.0.5 → 1.0.6

package/dist/plugins/prime/agents/troubleshooter.md

@@ -0,0 +1,132 @@
+---
+name: troubleshooter
+description: "Specialized debugging agent for when other agents get stuck. Performs root cause analysis using error context, knowledge base, git history, and CLAUDE.md. Produces structured diagnosis with confidence level and recommended fix."
+model: sonnet
+---
+
+# Troubleshooter Agent
+
+You are a specialized debugging agent. You are called when another agent or workflow
+has failed multiple times and needs expert diagnosis.
+
+## When You Are Spawned
+
+Another agent has hit a wall — they've tried 2-3 fixes and keep failing. Your job
+is to diagnose the root cause and provide a fix with confidence rating.
+
+## Your Process (follow in order)
+
+### 1. Understand the Problem (DO NOT SKIP)
+
+Read the error context provided in your spawn prompt. Extract:
+- **Exact error message** (not paraphrased)
+- **What was being attempted** (the goal, not just the command)
+- **What has already been tried** (and why each attempt failed)
+- **The file(s) involved**
+
+### 2. Consult Knowledge Base (BEFORE forming any hypothesis)
+
+Check these sources in order:
+
+```
+.claude/knowledge/qa-knowledge/         → past incidents with error signatures
+.claude/knowledge/shared/conventions.md → project-specific gotchas and rules
+.claude/knowledge/shared/patterns.md    → architecture patterns that may explain the error
+.claude/knowledge/agents/               → per-agent learning files
+CLAUDE.md                               → project configuration, test commands, services
+```
+
+Search for:
+- The exact error message (or key phrases)
+- The file/module involved
+- The command that failed
+- Similar past incidents
+
+**If you find a match:** Follow the documented fix. Do not reinvent.
+**If no match:** Proceed to step 3.
+
+### 3. Gather Fresh Evidence
+
+Read the actual source code around the error:
+- The file mentioned in the error (read 50+ lines of context, not just the error line)
+- Related files (imports, callers, configuration)
+- Recent changes: `git log --oneline -10 -- <file>` and `git diff HEAD -- <file>`
+
+Check the environment:
+- `git status` — are there uncommitted changes that might cause the issue?
+- Check if the right dependencies are installed (node_modules, venv, etc.)
+- Check if services are running (ports, Docker containers)
+- Check environment variables that the code expects
+
+### 4. Form Hypothesis (evidence-based only)
+
+Based on steps 2-3, form ONE primary hypothesis and optionally one alternative.
+Each hypothesis MUST cite evidence:
+
+```
+HYPOTHESIS: [what I think is wrong]
+EVIDENCE:
+  - [source]: [what I found that supports this]
+  - [source]: [what I found that supports this]
+CONFIDENCE: HIGH / MEDIUM / LOW
+  - HIGH: evidence directly explains the error, fix is clear
+  - MEDIUM: evidence is consistent but not conclusive
+  - LOW: best guess based on limited evidence
+```
+
+### 5. Recommend Fix
+
+Provide a specific, actionable fix:
+
+```
+RECOMMENDED FIX:
+  File: [exact file path]
+  Change: [what to modify — be specific, not vague]
+  Why: [how this addresses the root cause]
+  Verify: [command to run to confirm the fix works]
+
+ALTERNATIVE FIX (if confidence < HIGH):
+  File: [exact file path]
+  Change: [what to modify]
+  Why: [different hypothesis this addresses]
+```
+
+### 6. Output Format
+
+Always produce this structured output:
+
+```markdown
+## Troubleshooter Diagnosis
+
+**Error:** [exact error]
+**Root Cause:** [1-2 sentence explanation]
+**Confidence:** HIGH / MEDIUM / LOW
+
+### Evidence
+- [source 1]: [finding]
+- [source 2]: [finding]
+- Knowledge base: [match found / no match]
+
+### Recommended Fix
+- File: [path]
+- Change: [specific change]
+- Verify: [command]
+
+### What Was Wrong With Previous Attempts
+- Attempt 1: [why it didn't work — specific reason]
+- Attempt 2: [why it didn't work — specific reason]
+
+### If This Doesn't Work
+- [Next diagnostic step to try]
+- [What data to gather]
+- [Whether to escalate to user — and what to ask them]
+```
+
+## Rules
+
+1. **Never guess.** Every claim must cite evidence from code, logs, KB, or git history.
+2. **Check KB first.** If a past incident matches, use that fix. Don't reinvent.
+3. **Be specific.** "Check the config" is not a fix. "Change line 42 of config.ts from X to Y" is.
+4. **Explain why previous attempts failed.** This is as valuable as the fix itself.
+5. **Know when to escalate.** If confidence is LOW and you can't gather more evidence, say so. Recommend what data to ask the user for.
+6. **Don't try the fix yourself.** Your job is diagnosis. The calling agent implements the fix.

package/dist/plugins/prime/commands/calibrate.md

@@ -72,6 +72,26 @@ This goes far deeper than `/scan`. Read **actual source code** to understand HOW
 
 #### Step 1.1: Foundation Scan
 
+**Managed block check (belt-and-suspenders — runs before anything else):**
+
+Check if CLAUDE.md has the toolkit managed block. If missing, inject it before proceeding:
+
+```bash
+MANAGED_START="<!-- >>> claude-agents toolkit (DO NOT EDIT THIS BLOCK) >>> -->"
+if [ -f "$CLAUDE_PROJECT_DIR/CLAUDE.md" ]; then
+    grep -qF "$MANAGED_START" "$CLAUDE_PROJECT_DIR/CLAUDE.md" || echo "MISSING_BLOCK"
+fi
+```
+
+If the managed block is missing:
+1. Read `~/.claude-agents/templates/CLAUDE.md.managed-block` (or `$CLAUDE_PROJECT_DIR/.claude/hooks/../templates/CLAUDE.md.managed-block` if installed via plugin)
+2. Inject it at the end of CLAUDE.md using the markers:
+   - Start: `<!-- >>> claude-agents toolkit (DO NOT EDIT THIS BLOCK) >>> -->`
+   - End: `<!-- <<< claude-agents toolkit <<< -->`
+3. Report: "Injected toolkit managed block into CLAUDE.md (was missing)"
+
+This catches any install path that missed the injection — clone installs, manual setups, or projects that predate the managed block feature.
+
 Run `/scan` first if CLAUDE.md has `<!-- TODO -->` placeholders or doesn't exist. This populates
 the basics (tech stack, services, test commands, infrastructure). Then proceed to deep scan.
 

package/dist/plugins/prime/commands/ci-fix.md

@@ -160,6 +160,42 @@ gh run view <FAILED_RUN_ID> --log-failed 2>&1 | tail -200
 | **Build failures** | build errors | Read error, fix import/export/config |
 | **Migration** | Alembic/Django errors | Fix migration file |
 | **Dependency** | pip/npm install failures | Fix requirements/package.json |
+| **Toolkit tests** | 15/20-skill-runtime-safety, manifest-coverage | See Toolkit Test Fixes below |
+
+#### Toolkit-Specific Test Fixes (claude-agents repo)
+
+When CI fails on the mechanical test suite (`tests/run.sh`), these are the common failures and auto-fixes:
+
+| Test | Failure message | Root cause | Auto-fix |
+|------|----------------|-----------|----------|
+| `20-skill-runtime-safety` | "regex-unsafe [brackets] in descriptions" | SKILL.md `description:` or `arguments:` field contains `[text]` | Replace `[text]` with `<text>` in the frontmatter field. Brackets break regex matching in Claude Code. |
+| `20-skill-runtime-safety` | "Skills missing required frontmatter fields" | SKILL.md missing `user-invocable: true` or `arguments:` | Add missing field to the YAML frontmatter between `---` markers. Check `git show HEAD~1:path/to/SKILL.md` for the original. |
+| `15-manifest-coverage` | "entries mapped to categories" | New file in `portable.manifest` not listed in any `get_category_items()` category in `install.sh` | Add the manifest entry to the appropriate category in `install.sh:get_category_items()`. |
+| `15-manifest-coverage` | "Install creates all expected symlinks" | New file in `portable.manifest` but install didn't create the symlink | Usually follows from the category mapping fix above. |
+| `15-manifest-coverage` | "Entry counts are consistent" | Mismatch between manifest entries and installed files | Check that new manifest entries have matching source files. |
+| `19-brownfield-assessment` | "classify_file returns IDENTICAL" | Agent fixture is stale after editing an agent `.md` file | Update fixture: `cp agents/{name}.md tests/fixtures/claude-setups/poweruser/.claude/agents/` |
+
+**Auto-fix sequence for toolkit tests:**
+
+```bash
+# 1. Get the exact failure
+gh run view <ID> --log-failed 2>&1 | grep -E "FAIL|✗" | head -5
+
+# 2. For bracket issues — find and fix ALL bracket descriptions
+grep -rn 'description:.*\[' skills/*/SKILL.md
+# Replace [text] with <text> in each match
+
+# 3. For missing frontmatter — compare against last known good
+git show HEAD~1:path/to/SKILL.md | head -6
+# Restore missing fields
+
+# 4. For manifest coverage — add to install.sh categories
+grep "get_category_items" install.sh
+# Add new entries to the right category
+
+# 5. Verify locally before pushing
+bash tests/run.sh --suite 15,20 --scenario a
+```
 
 **Attempt escalation:**
 - Attempt 1: Apply the obvious fix (auto-fix tools, direct code fix)

package/dist/plugins/prime/commands/fix.md

@@ -476,6 +476,29 @@ Select the right agent based on which layer the bug is in:
 If `.claude/project-profile.md` exists, read it to determine the platform and pick the right agent.
 If `/calibrate` generated custom agents (e.g., `ios-developer.md`), use those for platform-specific bugs.
 
+**4.2b: Escalation protocol for fix agents**
+
+Include this in the implementation agent's prompt:
+
+```
+## When Your Fix Doesn't Work (MANDATORY)
+
+1. After first failed attempt: re-read the root cause analysis from Step 1.
+   Is the root cause correct? If not, go back to Step 1.
+2. After second failed attempt: consult knowledge base:
+   - .claude/knowledge/qa-knowledge/ (error keywords)
+   - .claude/knowledge/shared/conventions.md (project gotchas)
+   - git log --all --grep="<error keyword>" --oneline -10
+3. After third failed attempt: STOP. Do not try another fix.
+   Generate a STUCK REPORT and send to team-lead:
+   - Error: [exact message]
+   - Root cause hypothesis: [from Step 1]
+   - Fix attempts: [1, 2, 3 with results]
+   - KB consultation results: [what you found]
+   - Recommendation: [re-investigate root cause / ask user for X / try different approach]
+4. If a troubleshooter agent is available, team-lead may spawn one.
+```
+
 **Agent prompt includes:**
 ```
 1. Root cause analysis from Step 1

package/dist/plugins/prime/commands/implement.md

@@ -27,9 +27,15 @@ If no feature name is provided, use AskUserQuestion to get it.
 If the plan file exists:
 - Read it with the Read tool.
 - Parse the YAML frontmatter to extract the `layers` array (`frontend`, `backend`, or both).
+- Parse the `spec` field from frontmatter (e.g., `spec: specs/feature-name.md`).
 - Use `layers` to determine which agents to spawn (see Agent Selection below).
 - Use the full file content as `PLAN`.
 
+**Also check for a spec file** at `.claude/specs/{feature-name}.md` (written by `/planning` Phase 0):
+- If it exists, read it and store as `FEATURE_SPEC`.
+- Extract `USER_STORIES` (the ## User Stories section) and `EDGE_CASES` (the ## Edge Cases section).
+- These are passed to implementation agents and QA for better coverage.
+
 If the plan file does NOT exist:
 - Check conversation history for a recent `/planning` output. If found, use it as `PLAN` and infer layers from task breakdown.
 - If neither exists, ask the user with AskUserQuestion:
@@ -134,6 +140,43 @@ Include the results in the shared context block below so agents match existing
 patterns instead of inventing new ones. This is 60x cheaper than having each
 Sonnet agent independently explore the codebase.
 
+### 3c. Consult Knowledge Base (before agents start)
+
+Before spawning implementation agents, check the knowledge base for relevant context:
+
+```
+1. .claude/knowledge/shared/conventions.md — coding rules and project gotchas
+2. .claude/knowledge/shared/patterns.md — architecture patterns to follow
+3. .claude/knowledge/qa-knowledge/ — past incidents in the same area
+4. git log --all --grep="fix:" --oneline -10 — recent bug fixes that may be relevant
+```
+
+Include any relevant findings in the shared context block as `KNOWLEDGE_CONTEXT`.
+This prevents agents from repeating past mistakes or contradicting established patterns.
+
+### 3d. Escalation Protocol for Implementation Agents
+
+Add this to every implementation agent's prompt:
+
+```
+## When You Get Stuck (MANDATORY PROTOCOL)
+
+If a command fails or a fix doesn't work:
+1. DO NOT retry the same approach more than twice
+2. After 2 failures with same error: STOP and consult knowledge base
+   - .claude/knowledge/shared/conventions.md
+   - .claude/knowledge/qa-knowledge/ (search for error keywords)
+   - git log --all --grep="<error keyword>" --oneline -10
+3. After 3 failures: escalate with a STUCK REPORT:
+   - Error: [exact message]
+   - Attempts: [what you tried, why each failed]
+   - Evidence: [logs, state, KB results]
+   - What you need: [access/data/decision]
+   - Recommendation: [your best option]
+4. Send the stuck report to team-lead via SendMessage
+5. If a troubleshooter agent is available, team-lead may spawn one to help
+```
+
 ### 4. Build Shared Context Block
 
 ```
@@ -146,6 +189,16 @@ Auth: {AUTH_APPROACH}
 ## Implementation Plan
 {PLAN}
 
+## User Stories (from spec — trace your work to these)
+{USER_STORIES}
+
+(If no spec exists, this section is omitted.)
+
+## Edge Cases (from spec — handle these in your implementation)
+{EDGE_CASES}
+
+(If no spec exists, this section is omitted.)
+
 ## API Contract
 {API_CONTRACT}
 
@@ -204,7 +257,7 @@ Check `.claude/project-profile.md` first (if /calibrate has run). Otherwise the
 
 **Always spawn:**
 - **qa** (subagent_type="qa", model="sonnet", name="qa")
-  - Prompt: "{SHARED_CONTEXT}\n\nYou are QA. Your job: (1) Review backend and frontend implementations as they complete. (2) Ask teammates 'why did you do X?' when something looks wrong. (3) Run validation checks (linters, type checkers, build commands). (4) Report issues back to the responsible teammate. (5) Mark your tasks done when all checks pass. Do NOT write code — only review and validate."
+  - Prompt: "{SHARED_CONTEXT}\n\nYou are QA. Your job: (1) Review backend and frontend implementations as they complete. (2) Verify each user story from the spec is covered by the implementation — flag any story that has no corresponding code. (3) Verify each edge case from the spec is handled — flag any unhandled edge case. (4) Ask teammates 'why did you do X?' when something looks wrong. (5) Run validation checks (linters, type checkers, build commands). (6) Report issues back to the responsible teammate. (7) Mark your tasks done when all checks pass. Do NOT write code — only review and validate.\n\nWhen reviewing, trace each acceptance criterion back to its user story ID (US-1, US-2, etc.) and confirm the implementation satisfies it. Check edge cases (EC-1, EC-2, etc.) have explicit handling in the code."
 
 ### 5b. Red Team Phase
 
@@ -339,6 +392,7 @@ After PASS (or user override of BLOCK):
 
 ### 6. Monitor + Coordinate
 
+**Standard coordination:**
 - Watch TaskList for progress.
 - If backend finishes API endpoints, nudge frontend to unblock.
 - If a teammate is stuck, relay context from the other teammate.
@@ -347,6 +401,50 @@ After PASS (or user override of BLOCK):
 - If `REDTEAM_MODE=once`, defer Step 5b until all implementation steps are complete.
 - Track `REDTEAM_CYCLE`. If a BLOCK verdict is returned from Step 5b.4, pause all progress and escalate to the user before continuing.
 
+**Escalation handling (when an agent sends a STUCK REPORT):**
+
+When an agent reports they're stuck (via SendMessage with stuck report format):
+
+1. **Assess scope:** Is this a local issue (one file, one test) or systemic (architecture problem, wrong approach)?
+
+2. **If local issue (single file/test failure):**
+   - Check if another teammate can help (e.g., backend stuck on a frontend integration → ask frontend agent)
+   - Spawn a troubleshooter agent with the stuck report + error context
+   - Relay the troubleshooter's diagnosis back to the stuck agent
+   - If troubleshooter confidence is LOW → escalate to user with structured options
+
+3. **If systemic issue (architecture problem, multiple agents affected):**
+   - PAUSE all agents (don't let them keep building on a broken foundation)
+   - Escalate to user immediately:
+     ```
+     IMPLEMENTATION BLOCKED
+
+     What happened: [agent] hit [error] after [N] attempts
+     Scope: [local/systemic] — [why you think so]
+     Impact: [which tasks are blocked]
+     Troubleshooter says: [diagnosis if spawned]
+
+     Options:
+       [1] Fix the root cause (I'll explain what needs to change)
+       [2] Adjust the plan (scope down to avoid this area)
+       [3] Abort implementation (save work done so far)
+     ```
+
+4. **If two agents are stuck simultaneously:**
+   - This is almost always a systemic issue → treat as systemic
+   - Do NOT spawn two troubleshooters — diagnose once, fix at the root
+
+5. **If a task shows no progress for 3+ consecutive idle cycles:**
+   - Check in with the agent: "What's your status on Task #N?"
+   - If no meaningful progress → treat as stuck (even without explicit stuck report)
+
+**Red team finding escalation:**
+
+When red team finds issues that the developer can't fix:
+- If the fix requires changes outside their file ownership → orchestrator makes the cross-cutting change
+- If the fix requires a plan change → escalate to user: "Red team found [issue] that requires changing the plan. Original plan said [X], but we need [Y]. Approve?"
+- If the fix is beyond the team's capability → acknowledge, log it, and add to the PR description as a known limitation
+
 ### 7. Cleanup Implementation Team
 
 - Send shutdown_request to all teammates.

package/dist/plugins/prime/commands/planning.md

@@ -58,7 +58,86 @@ Map user choices:
 
 Store the resolved mode as `DEBATE_MODE` (values: `lite`, `fast`, `full`).
 
-### 3. Codebase Scan
+### 3. Phase 0: Spec Generation (before debate)
+
+Before any debate rounds, the PM generates a **spec doc** that becomes the foundation for all subsequent work. This ensures user stories and edge cases are defined BEFORE architecture decisions.
+
+**Create the specs directory:**
+```bash
+mkdir -p .claude/specs
+```
+
+**Spawn PM agent (subagent_type="product-manager", model="sonnet") for spec generation only:**
+
+Prompt:
+```
+You are a Product Manager generating a spec doc for the feature "{feature-name}".
+
+Feature brief: {FEATURE_BRIEF}
+
+Generate a spec doc with these sections:
+
+## User Stories
+Write 3-7 user stories covering the happy path and key error states.
+Format: "As a [user type], I want [action], so that [outcome]"
+Each story must have:
+- **Story ID**: US-1, US-2, etc.
+- **Priority**: P0 (must-have for launch) or P1 (important but deferrable)
+- **Acceptance**: specific testable condition that proves this story is done
+
+Example:
+  US-1 [P0]: As a new developer, I want to install the toolkit with one command,
+  so that I can start using it without manual configuration.
+  Acceptance: `npx @arthai/agents install forge .` succeeds and skills are available.
+
+## User Journey
+Step-by-step flow from the user's first interaction to completion.
+Include:
+- **Happy path**: numbered steps (1. User does X → 2. System responds Y → ...)
+- **Decision points**: where the user makes a choice (mark with ◆)
+- **Error branches**: where things can go wrong (mark with ✗ and show recovery path)
+
+Format as a text flowchart:
+```
+1. User discovers feature
+2. User does [action]
+   ◆ Decision: [choice A] or [choice B]
+   → Choice A: proceed to step 3
+   → Choice B: proceed to step 5
+3. System responds with [result]
+   ✗ Error: [what went wrong] → Recovery: [how to fix]
+4. ...
+```
+
+## Edge Cases
+Structured list of what can go wrong. For each:
+- **ID**: EC-1, EC-2, etc.
+- **Scenario**: what triggers this edge case
+- **Expected behavior**: what should happen (not crash, not hang)
+- **Severity**: Critical (blocks user) / High (degrades experience) / Medium (inconvenience)
+- **Linked story**: which user story this edge case relates to
+
+## Success Criteria
+Measurable outcomes tied to user stories. These become the acceptance criteria
+that /implement and /qa use to validate the implementation.
+- Each criterion references a story ID
+- Each criterion is binary: pass or fail, no subjective judgment
+```
+
+**Write the output to `.claude/specs/{feature-name}.md`** with this frontmatter:
+
+```markdown
+---
+feature: {feature-name}
+generated: {ISO date}
+stories: {count}
+edge_cases: {count}
+---
+```
+
+**Store the spec content as `FEATURE_SPEC`** — this is injected into the shared context block for all debate participants.
+
+### 4. Codebase Scan
 
 Spawn an `explore-light` subagent (model: haiku) to scan for relevant files:
 
@@ -68,7 +147,7 @@ prompt: "For a feature called '{feature-name}', find: (1) related backend routes
 
 Store the result as `CODEBASE_CONTEXT`.
 
-### 4. Create Team + Tasks
+### 5. Create Team + Tasks
 
 Create team: `planning-{feature-name}`
 
@@ -76,12 +155,13 @@ Create these tasks:
 
 | Task | Owner | Subject |
 |------|-------|---------|
-| 1 | product-manager | Define product spec for {feature-name} |
+| 0 | product-manager | Generate spec doc for {feature-name} (Phase 0 — already done above) |
+| 1 | product-manager | Define product scope for {feature-name} (uses spec as input) |
 | 2 | architect | Design technical plan for {feature-name} |
 | 3 (if --design) | design-thinker | Create design brief for {feature-name} |
 | 4 (if not --lite) | devils-advocate | Challenge scope and feasibility for {feature-name} |
 
-### 5. Build Shared Context Block
+### 6. Build Shared Context Block
 
 Compose this block to inject into every teammate's spawn prompt:
 
@@ -95,6 +175,11 @@ Auth: {AUTH_APPROACH}
 ## Feature: {feature-name}
 {FEATURE_BRIEF}
 
+## Spec Doc (from Phase 0)
+{FEATURE_SPEC}
+
+(Full spec at: .claude/specs/{feature-name}.md)
+
 ## Relevant Codebase
 {CODEBASE_CONTEXT}
 
@@ -114,13 +199,13 @@ This planning session runs in {DEBATE_MODE} mode.
 - If DA recommends KILL and user overrides, record as USER OVERRIDE in the plan.
 ```
 
-### 6. Spawn Teammates (ALL IN ONE MESSAGE — parallel)
+### 7. Spawn Teammates (ALL IN ONE MESSAGE — parallel)
 
 Spawn all teammates in a **single message** with multiple Task tool calls:
 
 **Always spawn:**
 - **product-manager** (subagent_type="product-manager", model="opus")
-  - Prompt: "{SHARED_CONTEXT}\n\nYou are the PM. Own the 'what' and 'why'.\n\nIn Round 1, you LEAD with your scope claim. Format your must-haves as:\n  [M1] requirement — BECAUSE reason\n  [M2] ...\nMaximum 5 MUST-HAVEs. Also list NICE-TO-HAVEs with CUT-IF conditions, EXPLICIT EXCLUSIONS, and success metrics.\n\nIn Round 2, you COUNTER the architect's approach: does it deliver user value, is it over-engineered, what is the time-to-value?\n\nIn Round 3 (full mode only), you DEFEND against the devil's advocate's risk case. Accept or reject each risk with evidence."
+  - Prompt: "{SHARED_CONTEXT}\n\nYou are the PM. Own the 'what' and 'why'. You generated the spec doc in Phase 0 — your user stories and edge cases are in the shared context above. Use them as the foundation for your scope claim.\n\nIn Round 1, you LEAD with your scope claim. Each must-have should trace to one or more user stories (reference by ID, e.g., 'US-1, US-3'). Format your must-haves as:\n  [M1] requirement — BECAUSE reason (traces to US-X)\n  [M2] ...\nMaximum 5 MUST-HAVEs. Also list NICE-TO-HAVEs with CUT-IF conditions, EXPLICIT EXCLUSIONS, and success metrics.\n\nIn Round 2, you COUNTER the architect's approach: does it deliver the user journey as specified? Is it over-engineered? What is the time-to-value? Reference edge cases the approach doesn't handle.\n\nIn Round 3 (full mode only), you DEFEND against the devil's advocate's risk case. Accept or reject each risk with evidence. Reference user stories to justify why a must-have cannot be cut."
 
 - **architect** (subagent_type="architect", model="opus")
   - Prompt: "{SHARED_CONTEXT}\n\nYou are the Architect. Own the 'how'.\n\nIn Round 1, you COUNTER the PM's scope from a feasibility lens. Challenge feasibility, flag hidden complexity, identify scope creep vectors, propose a counter-scope.\n\nIn Round 2, you LEAD with your technical approach: API contract, DB changes, architecture decision + WHY, task breakdown with S/M/L/XL estimates, implementation cost, dependencies, risks.\n\nIn Round 3 (full mode only), you DEFEND against the devil's advocate's risk case. Accept or reject each risk with evidence. Keep it simple for early-stage. Push back on scope that doesn't match the development stage."
@@ -140,7 +225,7 @@ Spawn all teammates in a **single message** with multiple Task tool calls:
 - **gtm-expert** (subagent_type="gtm-expert", model="sonnet")
   - Prompt: "{SHARED_CONTEXT}\n\nYou are the GTM Expert. Own distribution and launch strategy. Advise on positioning, viral mechanics, and launch sequencing. Challenge the team on how users will discover and adopt this feature. Your output feeds into Round 3 as additional evidence for the devil's advocate."
 
-### 7. Structured Debate Protocol
+### 8. Structured Debate Protocol
 
 Facilitate the following rounds in sequence. Each phase completes before the next begins.
 
@@ -279,7 +364,7 @@ Each matched item is flagged as a RISK NOTE in the plan.
 
 ---
 
-### 8. Convergence Logic
+### 9. Convergence Logic
 
 **Plan is APPROVED when ALL of the following are true after all applicable rounds complete:**
 - Rounds 1 and 2 have zero UNRESOLVED items
@@ -296,7 +381,7 @@ If user overrides a KILL recommendation, record as `USER OVERRIDE` in the plan.
 
 In lite and fast modes, skip convergence checks for rounds that were not run. Apply only the checks applicable to completed rounds.
 
-### 9. Scope Lock
+### 10. Scope Lock
 
 After convergence, compute a `scope_hash`:
 - Concatenate all locked MUST-HAVE strings from Round 1 in order
@@ -305,7 +390,7 @@ After convergence, compute a `scope_hash`:
 
 When `/implement` loads the plan, it can verify the hash against the locked must-haves to detect tampering.
 
-### 10. Write Plan File + Present to User
+### 11. Write Plan File + Present to User
 
 Synthesize teammate outputs into a structured plan and **write it to `.claude/plans/{feature-name}.md`** using the Write tool. This file is read by `/implement` to auto-configure the implementation team.
 
@@ -317,6 +402,7 @@ feature: {feature-name}
 debate_mode: {DEBATE_MODE}
 scope_hash: {SHA-256 of locked must-haves}
 da_confidence: {HIGH|MEDIUM|LOW|N/A}
+spec: specs/{feature-name}.md
 layers:
   - frontend  # include if ANY frontend tasks exist
   - backend   # include if ANY backend tasks exist
@@ -324,6 +410,9 @@ layers:
 
 # Planning Summary: {feature-name}
 
+## Spec Reference
+See `.claude/specs/{feature-name}.md` for user stories, user journey, edge cases, and success criteria.
+
 ## Problem & User Segment (from PM)
 ...
 
@@ -394,7 +483,7 @@ layers:
 
 Present the plan to the user for review.
 
-### 11. Cleanup
+### 12. Cleanup
 
 After user reviews the plan:
 - Send shutdown_request to all teammates.

package/dist/plugins/prime/commands/qa-incident.md

@@ -40,6 +40,60 @@ affected_files:
 
 4. **Confirm to user**: "Incident logged. Next `/qa` run will generate a regression test targeting this issue."
 
+## Auto-Logging from Escalation (Circuit Breaker Resolution)
+
+When an agent resolves a stuck situation (circuit breaker was tripped, then the issue was fixed),
+the resolution should be logged automatically. This enables future agents to find the fix
+without repeating the same debugging journey.
+
+**Trigger:** Any workflow that resolves an error after the escalation guard tripped (3+ consecutive failures).
+
+**Auto-log format** — create `.claude/qa-knowledge/incidents/{date}-escalation-{slug}.md`:
+
+```markdown
+---
+date: {today YYYY-MM-DD}
+severity: medium
+status: covered
+type: escalation-resolution
+error_signature: {from .claude/.escalation-state.json}
+affected_files:
+  - {files that were modified to fix the issue}
+---
+# Escalation: {brief description of what was stuck}
+
+## Error
+{exact error message that triggered the circuit breaker}
+
+## What Was Tried (failed)
+1. {attempt 1 from escalation state} → {result}
+2. {attempt 2} → {result}
+3. {attempt 3} → {result}
+
+## Root Cause
+{what was actually wrong}
+
+## Fix Applied
+{what change resolved the issue}
+
+## How to Prevent
+{if applicable — what convention or check would catch this earlier}
+
+## Search Keywords
+{error message fragments, file names, command patterns — for future KB searches}
+```
+
+**Also update** `.claude/qa-knowledge/bug-patterns.md` if this represents a new pattern:
+```
+## {Pattern name}
+- **Signature:** {error message or command pattern}
+- **Root cause:** {common reason}
+- **Fix:** {standard resolution}
+- **First seen:** {date}
+```
+
+This closes the learning loop: stuck → escalate → fix → log → future agents find it instantly.
+
 ## If No Description Provided
 
 Ask: "Describe the issue you want to log (e.g., 'admin page crashes when user has no sessions')"