azclaude-copilot 0.4.32 → 0.4.35

package/.claude-plugin/marketplace.json

@@ -8,8 +8,8 @@
   "plugins": [
     {
       "name": "azclaude",
-      "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 34 commands, 9 auto-invoked skills, 15 specialized agents, 4 hooks, and a persistent memory system — in one command.\n\nKey features:\n• Memory across sessions — goals.md + checkpoints injected automatically before every session\n• Self-improving loop — /reflect fixes stale CLAUDE.md rules, /reflexes learns from tool-use patterns, /evolve creates agents from git evidence\n• Autonomous copilot mode — /copilot runs a three-tier team (orchestrator → problem-architect → milestone-builder) across sessions until the product ships\n• Spec-driven workflow — /constitute writes project rules, /spec writes structured ACs, /analyze detects plan drift and ghost milestones, /blueprint traces every milestone to a spec\n• Security layer — 111-rule environment scan (/sentinel), pre-write secret blocking, pre-ship credential audit\n• Progressive levels 0–10 — start with CLAUDE.md, grow into multi-agent pipelines and self-evolving environments\n• Zero dependencies — no npm packages, no external APIs, no vector databases. Plain markdown files and Claude Code's native architecture.\n• Smart install — npx azclaude-copilot@latest auto-detects first install vs upgrade vs verify. Context-aware onboarding shows the right next command for your project state.\n\nExample use cases:\n• /setup — scan an existing project, detect stack + domain + scale, fill CLAUDE.md, generate project-specific skills and agents automatically\n• /copilot \"Build a compliance SaaS with trilingual support\" — walk away, come back to working code across multiple sessions\n• /sentinel — run a scored security audit (0–100, grade A–F) across hooks, permissions, MCP servers, agent configs, and secrets\n• /evolve — detect gaps in the environment, generate new skills and agents from git co-change evidence, report score delta (e.g. 42/100 → 68/100)\n• /constitute — write your project's constitution (non-negotiables, architectural commitments, definition of done) — gates all future AI actions\n• /analyze — cross-artifact consistency check: ghost milestones, spec vs. code drift, unplanned commits\n• /reflect — find stale, missing, or contradicting rules in CLAUDE.md and propose exact fixes\n• /debate \"REST vs GraphQL for this project\" — adversarial evidence-based decision with order-independent scoring, logged to decisions.md",
-      "version": "0.4.32",
+      "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 36 commands, 9 auto-invoked skills, 15 specialized agents, 4 hooks, and a persistent memory system — in one command.\n\nKey features:\n• Memory across sessions — goals.md + checkpoints injected automatically before every session\n• Self-improving loop — /reflect fixes stale CLAUDE.md rules, /reflexes learns from tool-use patterns, /evolve creates agents from git evidence\n• Autonomous copilot mode — /copilot runs a three-tier team (orchestrator → problem-architect → milestone-builder) across sessions until the product ships\n• Spec-driven workflow — /constitute writes project rules, /spec writes structured ACs, /analyze detects plan drift and ghost milestones, /blueprint traces every milestone to a spec\n• Security layer — 111-rule environment scan (/sentinel), pre-write secret blocking, pre-ship credential audit\n• Progressive levels 0–10 — start with CLAUDE.md, grow into multi-agent pipelines and self-evolving environments\n• Zero dependencies — no npm packages, no external APIs, no vector databases. Plain markdown files and Claude Code's native architecture.\n• Smart install — npx azclaude-copilot@latest auto-detects first install vs upgrade vs verify. Context-aware onboarding shows the right next command for your project state.\n\nExample use cases:\n• /setup — scan an existing project, detect stack + domain + scale, fill CLAUDE.md, generate project-specific skills and agents automatically\n• /copilot \"Build a compliance SaaS with trilingual support\" — walk away, come back to working code across multiple sessions\n• /sentinel — run a scored security audit (0–100, grade A–F) across hooks, permissions, MCP servers, agent configs, and secrets\n• /evolve — detect gaps in the environment, generate new skills and agents from git co-change evidence, report score delta (e.g. 42/100 → 68/100)\n• /constitute — write your project's constitution (non-negotiables, architectural commitments, definition of done) — gates all future AI actions\n• /analyze — cross-artifact consistency check: ghost milestones, spec vs. code drift, unplanned commits\n• /reflect — find stale, missing, or contradicting rules in CLAUDE.md and propose exact fixes\n• /debate \"REST vs GraphQL for this project\" — adversarial evidence-based decision with order-independent scoring, logged to decisions.md",
+      "version": "0.4.35",
       "source": {
         "source": "github",
         "repo": "haytamAroui/AZ-CLAUDE-COPILOT",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "azclaude",
-  "version": "0.4.32",
-  "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 34 commands, 9 auto-invoked skills, 15 specialized agents, 4 hooks, and a persistent memory system — in one command.\n\nKey features:\n• Memory across sessions — goals.md + checkpoints injected automatically before every session\n• Self-improving loop — /reflect fixes stale CLAUDE.md rules, /reflexes learns from tool-use patterns, /evolve creates agents from git evidence\n• Autonomous copilot mode — /copilot runs a three-tier team (orchestrator → problem-architect → milestone-builder) across sessions until the product ships\n• Spec-driven workflow — /constitute writes project rules, /spec writes structured ACs, /analyze detects plan drift and ghost milestones, /blueprint traces every milestone to a spec\n• Security layer — 111-rule environment scan (/sentinel), pre-write secret blocking, pre-ship credential audit\n• Progressive levels 0–10 — start with CLAUDE.md, grow into multi-agent pipelines and self-evolving environments\n• Zero dependencies — no npm packages, no external APIs, no vector databases. Plain markdown files and Claude Code's native architecture.\n• Smart install — npx azclaude-copilot@latest auto-detects first install vs upgrade vs verify. Context-aware onboarding shows the right next command for your project state.\n\nExample use cases:\n• /setup — scan an existing project, detect stack + domain + scale, fill CLAUDE.md, generate project-specific skills and agents automatically\n• /copilot \"Build a compliance SaaS with trilingual support\" — walk away, come back to working code across multiple sessions\n• /sentinel — run a scored security audit (0–100, grade A–F) across hooks, permissions, MCP servers, agent configs, and secrets\n• /evolve — detect gaps in the environment, generate new skills and agents from git co-change evidence, report score delta (e.g. 42/100 → 68/100)\n• /constitute — write your project's constitution (non-negotiables, architectural commitments, definition of done) — gates all future AI actions\n• /analyze — cross-artifact consistency check: ghost milestones, spec vs. code drift, unplanned commits\n• /reflect — find stale, missing, or contradicting rules in CLAUDE.md and propose exact fixes\n• /debate \"REST vs GraphQL for this project\" — adversarial evidence-based decision with order-independent scoring, logged to decisions.md",
+  "version": "0.4.35",
+  "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 36 commands, 9 auto-invoked skills, 15 specialized agents, 4 hooks, and a persistent memory system — in one command.\n\nKey features:\n• Memory across sessions — goals.md + checkpoints injected automatically before every session\n• Self-improving loop — /reflect fixes stale CLAUDE.md rules, /reflexes learns from tool-use patterns, /evolve creates agents from git evidence\n• Autonomous copilot mode — /copilot runs a three-tier team (orchestrator → problem-architect → milestone-builder) across sessions until the product ships\n• Spec-driven workflow — /constitute writes project rules, /spec writes structured ACs, /analyze detects plan drift and ghost milestones, /blueprint traces every milestone to a spec\n• Security layer — 111-rule environment scan (/sentinel), pre-write secret blocking, pre-ship credential audit\n• Progressive levels 0–10 — start with CLAUDE.md, grow into multi-agent pipelines and self-evolving environments\n• Zero dependencies — no npm packages, no external APIs, no vector databases. Plain markdown files and Claude Code's native architecture.\n• Smart install — npx azclaude-copilot@latest auto-detects first install vs upgrade vs verify. Context-aware onboarding shows the right next command for your project state.\n\nExample use cases:\n• /setup — scan an existing project, detect stack + domain + scale, fill CLAUDE.md, generate project-specific skills and agents automatically\n• /copilot \"Build a compliance SaaS with trilingual support\" — walk away, come back to working code across multiple sessions\n• /sentinel — run a scored security audit (0–100, grade A–F) across hooks, permissions, MCP servers, agent configs, and secrets\n• /evolve — detect gaps in the environment, generate new skills and agents from git co-change evidence, report score delta (e.g. 42/100 → 68/100)\n• /constitute — write your project's constitution (non-negotiables, architectural commitments, definition of done) — gates all future AI actions\n• /analyze — cross-artifact consistency check: ghost milestones, spec vs. code drift, unplanned commits\n• /reflect — find stale, missing, or contradicting rules in CLAUDE.md and propose exact fixes\n• /debate \"REST vs GraphQL for this project\" — adversarial evidence-based decision with order-independent scoring, logged to decisions.md",
   "author": {
     "name": "haytamAroui",
     "url": "https://github.com/haytamAroui"

package/README.md

@@ -15,7 +15,9 @@
     <a href="#spec-driven-workflow">Spec-Driven</a> ·
     <a href="#memory-system">Memory</a> ·
     <a href="#self-improving-loop">Self-Improving Loop</a> ·
-    <a href="#all-33-commands">Commands</a> ·
+    <a href="#all-36-commands">Commands</a> ·
+    <a href="#parallel-execution">Parallel</a> ·
+    <a href="#mcp-integration">MCP</a> ·
     <a href="#autonomous-mode">Autonomous Mode</a> ·
     <a href="DOCS.md">Full Docs</a>
   </p>
@@ -61,7 +63,7 @@ AZCLAUDE inverts this. **You start with almost nothing. The environment builds i
 npx azclaude-copilot@latest   # one command. that's it.
 ```
 
-No agent files to write. No skills to configure. No prompt engineering. `npx azclaude-copilot` installs 34 commands, 4 hooks, memory structure, and a manifest. The rest is generated from your actual codebase as you work. Run the same command again later — it auto-detects whether to skip, install, or upgrade.
+No agent files to write. No skills to configure. No prompt engineering. `npx azclaude-copilot` installs 36 commands, 4 hooks, memory structure, and a manifest. The rest is generated from your actual codebase as you work. Run the same command again later — it auto-detects whether to skip, install, or upgrade.
 
 **What the environment looks like across sessions:**
 
@@ -117,7 +119,7 @@ npx azclaude-copilot@latest
 ```
 
 That's it. One command, no flags. Auto-detects whether this is a fresh install or an upgrade:
-- **First time** → full install (34 commands, 4 hooks, 15 agents, 9 skills, memory, reflexes)
+- **First time** → full install (36 commands, 4 hooks, 15 agents, 10 skills, memory, reflexes)
 - **Already installed, older version** → auto-upgrades everything to latest templates
 - **Already up to date** → verifies, no overwrites
 
@@ -129,13 +131,13 @@ npx azclaude-copilot@latest doctor   # 32 checks — verify everything is wired
 
 ## What You Get
 
-**34 commands** · **9 auto-invoked skills** · **15 agents** · **4 hooks** · **memory across sessions** · **learned reflexes** · **self-evolving environment**
+**36 commands** · **9 auto-invoked skills** · **15 agents** · **4 hooks** · **memory across sessions** · **learned reflexes** · **self-evolving environment**
 
 ```
 .claude/
 ├── CLAUDE.md                 ← dispatch table: conventions, stack, routing
-├── commands/                 ← 33 slash commands (/add, /fix, /copilot, /spec, /sentinel...)
-├── skills/                   ← 9 skills (test-first, security, architecture-advisor, frontend-design...)
+├── commands/                 ← 36 slash commands (/add, /fix, /copilot, /parallel, /mcp, /sentinel...)
+├── skills/                   ← 10 skills (test-first, security, architecture-advisor, frontend-design...)
 ├── agents/                   ← 15 agents (orchestrator, spec-reviewer, constitution-guard...)
 ├── capabilities/             ← 37 files, lazy-loaded via manifest.md (~380 tokens/task)
 ├── hooks/
@@ -265,6 +267,8 @@ Node.js runner restarts Claude Code sessions in a loop until `COPILOT_COMPLETE`.
 /snapshot         # save WHY you made decisions — auto-injected next session
 /reflect          # find and fix stale/missing rules in CLAUDE.md
 /reflexes         # view learned behavioral patterns with confidence scores
+/parallel M2 M3   # run multiple milestones simultaneously (worktree isolation + auto-merge)
+/mcp              # recommend and install MCP servers based on your stack
 ```
 
 ---
@@ -623,7 +627,57 @@ Session 4:  /evolve → /analyze → /audit → /ship → COPILOT_COMPLETE
 
 ---
 
-## All 33 Commands
+## Parallel Execution
+
+AZCLAUDE runs multiple Claude Code agents simultaneously on the same codebase — without file corruption or test interference. Each agent works in an isolated git worktree on its own branch. Changes merge sequentially after all agents complete.
+
+```
+M1 (schema) → done
+                 ↓
+    ┌────────────┬────────────┬────────────┐
+    M2 (auth)   M3 (profile) M4 (email)   M5 (dashboard)   ← all run simultaneously
+    ↓            ↓            ↓            ↓
+    └────────────┴────────────┴────────────┘
+                 ↓
+              M6 (E2E tests)
+```
+
+**Automatic — via `/copilot`:** The orchestrator reads `Wave:` fields in plan.md (written by `/blueprint`), dispatches same-wave milestones with `isolation: "worktree"` in a single message, then merges sequentially.
+
+**Manual — via `/parallel`:**
+```bash
+/parallel M2 M3 M4 M5    # dispatch these milestones simultaneously
+```
+
+**Three-layer safety:** `/blueprint` checks directory isolation + shared-utility imports before writing plan.md (Layer 1 — no agents spawned). `problem-architect` returns exact `Files Written:` and `Parallel Safe:` per milestone after plan.md (Layer 2). The orchestrator checks file overlap again at dispatch time (Layer 3 — final gate, cannot be bypassed).
+
+See `docs/parallel-feature.md` for the complete reference.
+
+---
+
+## MCP Integration
+
+AZCLAUDE recommends MCP servers based on your stack and wires them into daily-use commands.
+
+```bash
+/mcp    # detect stack → recommend universal MCPs → show install commands
+```
+
+**Universal (free, no API key — recommended for every project):**
+- `Context7` — `/add` fetches live library docs before writing any library calls. Prevents stale API usage.
+- `Sequential Thinking` — `/blueprint` and `/copilot` use iterative reasoning for milestone planning.
+
+**Stack-specific:**
+- `GitHub MCP` — any GitHub repo: richer `/ship` and PR creation
+- `Playwright MCP` — any web project: E2E testing with qa-engineer
+- `Supabase MCP` — Supabase in deps: schema introspection, migrations
+- `Brave Search` — `/fix` looks up external library errors before guessing root cause
+
+`/setup` checks MCP status at the end and nudges if none are configured.
+
+---
+
+## All 36 Commands
 
 ### Build and Ship
 
@@ -653,6 +707,8 @@ Session 4:  /evolve → /analyze → /audit → /ship → COPILOT_COMPLETE
 | `/analyze` | Cross-artifact consistency check. Finds ghost milestones (marked done, files missing), spec vs. code drift, plan vs. reality gaps. Read-only. |
 | `/tasks` | Build dependency graph from plan.md. Shows parallelizable wave groups and critical path. Tells orchestrator which milestones can run simultaneously. |
 | `/issues` | Convert plan.md milestones to GitHub Issues. Deduplicates, creates labels, writes issue numbers back to plan.md for traceability. |
+| `/parallel` | Run multiple milestones simultaneously. Worktree isolation per agent. Auto-merges after all complete. Three-layer file collision safety. |
+| `/mcp` | Recommend and install MCP servers based on detected stack. Wires Context7, Sequential Thinking, GitHub, Playwright, Brave Search, Supabase. |
 
 ### Think and Improve
 
@@ -807,11 +863,11 @@ Run `/level-up` at any time to see your current level and build the next one.
 
 ## Verified
 
-1462 tests. Every template, command, capability, agent, hook, and CLI feature verified.
+1526 tests. Every template, command, capability, agent, hook, and CLI feature verified.
 
 ```bash
 bash tests/test-features.sh
-# Results: 1462 passed, 0 failed, 1462 total
+# Results: 1526 passed, 0 failed, 1526 total
 ```
 
 ---

package/bin/cli.js

@@ -8,8 +8,8 @@ const { execSync }  = require('child_process');
 
 const TEMPLATE_DIR = path.join(__dirname, '..', 'templates');
 const CORE_COMMANDS     = ['setup', 'fix', 'add', 'audit', 'test', 'blueprint', 'ship', 'pulse', 'explain', 'snapshot', 'persist'];
-const EXTENDED_COMMANDS = ['dream', 'refactor', 'doc', 'loop', 'migrate', 'deps', 'find', 'create', 'reflect', 'hookify', 'sentinel', 'clarify', 'spec', 'analyze', 'constitute', 'tasks', 'issues', 'driven'];
-const ADVANCED_COMMANDS = ['evolve', 'debate', 'level-up', 'copilot', 'reflexes'];
+const EXTENDED_COMMANDS = ['dream', 'refactor', 'doc', 'loop', 'migrate', 'deps', 'find', 'create', 'reflect', 'hookify', 'sentinel', 'clarify', 'spec', 'analyze', 'constitute', 'tasks', 'issues', 'driven', 'mcp'];
+const ADVANCED_COMMANDS = ['evolve', 'debate', 'level-up', 'copilot', 'reflexes', 'parallel'];
 const COMMANDS          = [...CORE_COMMANDS, ...EXTENDED_COMMANDS, ...ADVANCED_COMMANDS];
 
 function ok(msg)   { console.log(`  ✓ ${msg}`); }
@@ -373,7 +373,7 @@ function installCommands(projectDir, cfg) {
 
 // ─── Skills (SKILL.md — model-auto-invoked) ──────────────────────────────────
 
-const SKILLS = ['session-guard', 'test-first', 'env-scanner', 'debate', 'security', 'skill-creator', 'agent-creator', 'architecture-advisor', 'frontend-design'];
+const SKILLS = ['session-guard', 'test-first', 'env-scanner', 'debate', 'security', 'skill-creator', 'agent-creator', 'architecture-advisor', 'frontend-design', 'mcp'];
 
 function installSkills(projectDir, cfg) {
   const skillsDir = path.join(projectDir, cfg, 'skills');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "azclaude-copilot",
-  "version": "0.4.32",
-  "description": "AI coding environment — 34 commands, 9 skills, 15 agents, memory, reflexes, evolution. Install: npx azclaude-copilot@latest, then open Claude Code.",
+  "version": "0.4.35",
+  "description": "AI coding environment — 36 commands, 10 skills, 15 agents, memory, reflexes, evolution. Install: npx azclaude-copilot@latest, then open Claude Code.",
   "bin": {
     "azclaude": "bin/cli.js",
     "azclaude-copilot": "bin/copilot.js"

package/templates/CLAUDE.md

@@ -40,9 +40,20 @@ Extended (load command file on use):
   - /tasks: dependency graph + parallel wave groups from plan.md
   - /issues: convert plan.md milestones to GitHub Issues
 - Standards: /driven → generates .claude/code-rules.md (coding contract for /add and /fix)
+- MCP: /mcp → recommends and installs MCP servers based on your stack
 
 Advanced (Level 5+):
 - /evolve · /debate · /level-up
+- Parallel execution: /parallel → dispatch multiple milestones simultaneously (worktree isolation + auto-merge)
+  - /tasks → shows which milestones can run in parallel (wave groups)
+
+## Parallel Agent Rules
+When running parallel agents (/copilot with parallel waves, or /parallel):
+1. **Own your scope** — only write files in your declared directories. Touch nothing outside.
+2. **Errors in files you didn't modify** → do not fix them. Report "scope violation: {file}" to orchestrator.
+3. **Never push from a worktree** — commit locally only. Orchestrator merges after all agents complete.
+4. **Test in isolation** — run `{test framework} tests/{your-area}/` not the full suite. Cross-cutting failures are expected during parallel execution.
+5. **Report your branch** — always end completion report with "Branch: parallel/{slug}".
 
 Unknown capability → grep manifest.md by description, load match
 
@@ -53,4 +64,4 @@ When priorities conflict:
 3. {{PRIORITY_3}}
 
 ## Available Commands
-/dream · /setup · /fix · /add · /audit · /test · /blueprint · /evolve · /debate · /snapshot · /persist · /level-up · /ship · /pulse · /explain · /loop · /refactor · /doc · /migrate · /deps · /find · /create · /reflect · /hookify · /spec · /clarify · /analyze · /constitute · /tasks · /issues · /driven
+/dream · /setup · /fix · /add · /audit · /test · /blueprint · /evolve · /debate · /snapshot · /persist · /level-up · /ship · /pulse · /explain · /loop · /refactor · /doc · /migrate · /deps · /find · /create · /reflect · /hookify · /spec · /clarify · /analyze · /constitute · /tasks · /issues · /driven · /mcp · /parallel

package/templates/agents/milestone-builder.md

@@ -111,8 +111,21 @@ Tests must PASS before reporting done. Show actual output — never summarize.
 
 ### Step 5: Commit and Report Back
 
-On success:
+**Detect execution mode:**
+```bash
+# Am I in a worktree (parallel mode)?
+git worktree list 2>/dev/null | grep -c "$(pwd)" | grep -q "^1$" \
+  && echo "WORKTREE_MODE" || echo "MAIN_MODE"
+```
 
+**If WORKTREE_MODE** (parallel dispatch with worktree isolation):
+```bash
+git add {files changed}
+git commit -m "{type}: {what} — {why}"
+# DO NOT push — orchestrator merges all parallel branches after wave completes
+```
+
+**If MAIN_MODE** (sequential dispatch):
 ```bash
 git add {files changed}
 git commit -m "{type}: {what} — {why}"
@@ -124,6 +137,10 @@ Report to orchestrator:
 ```
 ## Milestone {N} — {title}: COMPLETE
 
+### Execution Mode
+WORKTREE | MAIN
+Branch: {current branch name}  ← required for orchestrator merge tracking
+
 ### Files Changed
 - {file}: {create|modify} — {one-line description}
 
@@ -138,6 +155,11 @@ PASS — {N} tests passing
 {anti-pattern description} — or "none"
 ```
 
+**Worktree coordination errors** (errors in files outside your declared scope):
+- DO NOT attempt to fix them
+- Report: "Scope violation detected: {file} outside my directories — possible parallel agent interference"
+- Orchestrator handles resolution
+
 ---
 
 ## Rules

package/templates/agents/orchestrator.md

@@ -35,13 +35,21 @@ If CLAUDE.md unfilled → run `/setup` with intent from copilot-intent.md first.
 
 ### Step 2: Select Next Milestone Wave
 
+**If plan.md has `Wave:` fields** (blueprint wrote them — read directly):
+```bash
+grep "Wave:" .claude/plan.md
+```
+Find the lowest wave number where all milestones have `status = pending` and all `Depends:` are `done`.
+This is the next wave to dispatch.
+
+**If plan.md has NO `Wave:` fields** (older plan format — compute from scratch):
 Find milestones where `status = pending` AND all dependencies have `status = done`.
 
-**Parallel candidates:** milestones with independent dependencies.
+**Parallel candidates:** milestones in the same wave with `Parallel: yes` (or computed as independent).
 
-**REQUIRED parallel safety check:** Before dispatching in parallel, get `Files Written`
-from problem-architect for each candidate. If any two candidates share a written file
-→ dispatch sequentially. Silent file corruption otherwise.
+**REQUIRED parallel safety check:** Even if `Parallel: yes`, verify `Files Written` from problem-architect
+for each candidate don't overlap. `Files Written` is more precise than `Files:` — use it.
+If any two candidates share a written file → dispatch sequentially. Silent file corruption otherwise.
 
 - All done → SHIP
 - All remaining blocked → BLOCKER RECOVERY
@@ -93,6 +101,18 @@ If verdict is `APPROVED` or `APPROVED (no constitution found)`: proceed to Step
 
 ### Step 4: Dispatch Milestone Builder(s)
 
+**Parallel dispatch (2+ milestones in wave with disjoint Files Written):**
+
+Load `capabilities/shared/parallel-coordination.md` first.
+
+1. Write `.claude/ownership.md` table (branch, directories, status) for every agent in this wave
+2. Spawn each builder via Task with `isolation: "worktree"` in the same message (true parallel)
+3. Include worktree rules in every parallel prompt (see parallel-coordination.md Step 3)
+4. Wait for ALL agents in the wave before merging
+5. Merge branches sequentially (simplest milestone first) following the Merge Protocol
+
+**Sequential dispatch (single milestone OR overlapping files):**
+
 Spawn milestone-builder via Task with fully packaged context:
 
 ```
@@ -123,8 +143,8 @@ Fix attempts: {2 for SIMPLE/MEDIUM, 3 for COMPLEX}
 When done, report: files changed + test status + new patterns/anti-patterns.
 ```
 
-Independent milestones with disjoint `Files Written` → spawn in parallel.
-Dependent milestones OR overlapping `Files Written` → spawn sequentially.
+Independent milestones with disjoint `Files Written` AND `Parallel Safe: YES` → spawn in parallel with worktree isolation.
+Dependent milestones, overlapping `Files Written`, or `Parallel Safe: NO` → spawn sequentially.
 
 ---
 

package/templates/agents/problem-architect.md

@@ -128,6 +128,12 @@ If YES: topic = {what orchestrator must /debate before dispatching}
 ### Estimated Complexity
 SIMPLE (< 3 files) | MEDIUM (3-8 files) | COMPLEX (8+ files)
 COMPLEX → orchestrator gives builder 3 fix attempts instead of 2
+
+### Parallel Safe
+YES | NO
+If NO: reason = {specific conflict — shared file, schema dependency, runtime ordering}
+The orchestrator uses this to decide whether to use worktree isolation or sequential dispatch.
+Parallel Safe = YES requires: isolated directories, no shared config/schema, no runtime dependency on a sibling milestone.
 ```
 
 ---

package/templates/capabilities/shared/parallel-coordination.md

@@ -0,0 +1,176 @@
+# Parallel Agent Coordination
+
+This file is loaded by the orchestrator when dispatching milestone-builder agents in parallel.
+It defines the worktree isolation protocol, ownership map format, and merge sequence.
+
+---
+
+## Why Worktrees Are Required for Parallel Dispatch
+
+Without worktree isolation, two agents writing to the same repo simultaneously cause:
+- **File corruption**: agent A's partial write is read by agent B mid-implementation
+- **Test interference**: A's failing tests pollute B's test run, causing false failures
+- **Commit races**: both agents commit, one overwrites the other's changes on push
+
+Worktree isolation gives each parallel agent a private copy of the repo on its own branch.
+The orchestrator merges completed branches sequentially once all agents report done.
+
+---
+
+## Ownership Map
+
+The orchestrator maintains `.claude/ownership.md` during parallel sessions.
+Format — one entry per active parallel agent:
+
+```
+## Active Parallel Session — {ISO timestamp}
+
+| Agent Slot | Milestone | Branch | Directories Owned | Status |
+|------------|-----------|--------|-------------------|--------|
+| P1 | M3 — Auth endpoints | parallel/m3-auth | src/auth/, tests/auth/ | running |
+| P2 | M4 — User profile | parallel/m4-profile | src/users/, tests/users/ | running |
+| P3 | M5 — Email service | parallel/m5-email | src/email/, tests/email/ | done |
+```
+
+Rules:
+- Two agents cannot share a directory in "Directories Owned"
+- Orchestrator writes this table before dispatching; builders do NOT modify it
+- `parallel/{milestone-slug}` is the branch naming convention
+- Delete the table when the wave is merged (replace with "Wave N merged — {timestamp}")
+
+---
+
+## Dispatch Protocol (Orchestrator)
+
+### Step 1: Confirm Parallel Safety
+
+Before spawning any parallel agents for a wave, verify from problem-architect Team Specs:
+
+```
+For each pair (A, B) in the wave:
+  - Files Written(A) ∩ Files Written(B) = empty set?    → safe
+  - Parent directories of A and B do not overlap?        → safe
+  - No shared schema/config files (prisma.schema, package.json, tsconfig)?  → safe
+  - No runtime dependency (A's output is B's input)?    → safe
+
+If any check fails → remove the conflicting milestone from the wave, dispatch sequentially
+```
+
+### Step 2: Write Ownership Map
+
+Write `.claude/ownership.md` before spawning any agents.
+
+### Step 3: Dispatch with Worktree Isolation
+
+Spawn each agent via Task with `isolation: "worktree"`:
+
+```
+Task: Implement Milestone {N} — {title}
+
+[worktree mode]
+Branch: parallel/{milestone-slug}
+Do NOT push to origin. Commit locally only.
+Report branch name in completion message.
+
+{standard milestone context from orchestrator Step 4}
+```
+
+Include in every parallel dispatch:
+```
+Worktree rules:
+- You are in an isolated git worktree on branch: parallel/{slug}
+- Run all tests — they test YOUR changes in isolation only
+- If you see errors in files outside your owned directories: STOP, report to orchestrator
+- Do NOT run git push — commit locally only
+- Your completion message MUST include: "Branch: parallel/{slug}" for merge tracking
+```
+
+### Step 4: Wait for All Agents in the Wave
+
+Do NOT start the merge until ALL parallel agents in this wave have reported:
+- `COMPLETE` → proceed with merge
+- `FAILED` → merge all completed branches first, then handle the failure as a blocked milestone
+
+---
+
+## Merge Protocol (Orchestrator)
+
+After all parallel agents report done, merge sequentially:
+
+```bash
+# Step 1: Return to main branch
+git checkout main  # or master / development
+
+# Step 2: Merge each branch in completion order
+git merge parallel/m3-auth --no-ff -m "merge: M3 auth endpoints [parallel wave N]"
+git merge parallel/m4-profile --no-ff -m "merge: M4 user profile [parallel wave N]"
+
+# Step 3: If merge conflict on step N:
+# - Identify which files conflict
+# - Read both versions
+# - Apply the correct merge (usually: keep both feature additions, not one-or-other)
+# - Mark conflict resolved, continue with remaining branches
+
+# Step 4: Run full test suite on merged main
+npm test 2>&1 | tail -20
+
+# Step 5: If tests pass → push
+git push origin main
+
+# Step 6: Clean up worktree branches
+git branch -d parallel/m3-auth parallel/m4-profile parallel/m5-email
+```
+
+**Merge order matters**: merge the branch with the fewest cross-dependencies first.
+When uncertain: sort by `Estimated Complexity` ascending (simpler merges first).
+
+---
+
+## Agent Coordination Rules (for Milestone Builder in Parallel Mode)
+
+These rules are injected by orchestrator into every parallel milestone-builder prompt:
+
+1. **Own your scope** — only write files in your declared "Directories Owned". If the task requires touching a file outside your scope, STOP and report to orchestrator.
+
+2. **Never push** — commit locally on your worktree branch. Do not run `git push`.
+
+3. **Test in isolation** — your test run should only test what you changed. If the test suite has cross-cutting failures, filter to your files: `pytest tests/auth/ -v` not `pytest .`
+
+4. **Errors outside your files = not your problem** — if you see compilation errors or test failures in files you didn't modify, that's a parallel agent's in-progress state. Report to orchestrator: "Test failures in {file} — outside my scope, may be parallel agent interference."
+
+5. **Report branch on completion** — always end your report with: `Branch: parallel/{slug}`
+
+---
+
+## Conflict Resolution Ladder
+
+| Conflict type | Resolution |
+|---------------|-----------|
+| Two agents wrote to the same file (despite safety check) | Orchestrator reads both versions, applies correct merge manually |
+| Merge conflict on shared config (package.json, tsconfig) | Merge both dependency lists; the second merge wins on formatting |
+| Merge conflict on shared schema | STOP — run /debate before merging; schema changes are architectural |
+| Test suite broken after merge | Identify which merge introduced the break; revert that branch, add to blocked |
+| Agent reports "errors in files outside my scope" | Orchestrator pauses that agent, lets the other agent stabilize first |
+
+---
+
+## When NOT to Use Parallel Dispatch
+
+| Condition | Reason |
+|-----------|--------|
+| Milestone touches `package.json` / `requirements.txt` | Dependency changes affect the full build — sequential only |
+| Milestone touches database schema | Schema migrations must run in order |
+| Milestone has `Structural Decision Required: YES` | Architecture must be resolved before implementation |
+| Project has < 3 milestones total | Sequential is simpler; parallel overhead exceeds gain |
+| No worktree support (bare repo, certain CI environments) | Falls back to sequential automatically |
+
+---
+
+## Ownership Map Cleanup
+
+After wave merge is complete:
+```bash
+# Remove ownership.md entries for the completed wave
+# (or replace the table with a merge record)
+echo "## Wave {N} merged — {timestamp}" >> .claude/ownership.md
+```

package/templates/capabilities/shared/plan-tracker.md

@@ -18,14 +18,20 @@ Every plan.md must follow this structure exactly. The copilot runner parses it.
 
 ### M1: {title}
 - Status: {pending|in-progress|done|blocked|skipped}
-- Files: {expected files to create/modify}
+- Wave: {1|2|3|...} — execution wave (same wave = runs in parallel)
+- Files: {expected files to create/modify — be specific, e.g. src/auth/login.ts}
+- Dirs: {top-level directories this milestone owns — e.g. src/auth/, tests/auth/}
 - Depends: {M-numbers this depends on, or "none"}
+- Parallel: {yes|no} — yes = safe to run alongside other same-wave milestones
 - Commit: {expected commit message}
 
 ### M2: {title}
 - Status: pending
+- Wave: 2
 - Files: ...
+- Dirs: src/users/, tests/users/
 - Depends: M1
+- Parallel: yes
 - Commit: ...
 
 ## Summary
@@ -33,8 +39,19 @@ Total: {N} milestones
 Done: {N}/{total}
 In progress: {N}/{total}
 Blocked: {N}/{total}
+Waves: {N} (max parallel in one wave: {N})
 ```
 
+### Field Definitions
+
+| Field | Purpose |
+|-------|---------|
+| `Wave:` | Which execution wave. Same number = can run simultaneously. Wave 1 always first. |
+| `Dirs:` | Directories this milestone exclusively owns. Two milestones in the same wave MUST have non-overlapping `Dirs:`. |
+| `Files:` | Expected file paths to create/modify. Blueprint's estimate — problem-architect refines to `Files Written:`. |
+| `Parallel: yes` | Orchestrator may dispatch with worktree isolation alongside other Wave N milestones. |
+| `Parallel: no` | Reasons: touches shared config, schema change, or has runtime dep on sibling milestone. |
+
 ## Status Values
 
 | Status | Meaning |

package/templates/commands/add.md

@@ -29,8 +29,14 @@ Load: shared/tdd.md + shared/completion-rule.md
 
 # Check if $ARGUMENTS is a spec file
 [ -f "$ARGUMENTS" ] && grep -q "Acceptance Criteria" "$ARGUMENTS" && echo "spec-mode" || echo "inline-mode"
+
+# Check if Context7 MCP is available (live library docs — prevents stale API usage)
+claude mcp list 2>/dev/null | grep -q "context7" && echo "context7=active" || echo "context7=inactive"
 ```
 
+**If context7=active**: before writing any library calls, use `mcp__context7__resolve-library-id` then `mcp__context7__get-library-docs` to fetch current docs. Pass `use context7` in the tool call.
+**If context7=inactive**: proceed normally — consider running `/mcp` after this task to prevent stale API usage in future sessions.
+
 **If constitution found:**
 Read `## Non-Negotiables` and `## Required Patterns` before implementing.
 Keep these rules visible throughout Phases 2-4. Flag any implementation choice that would violate them.

package/templates/commands/blueprint.md

@@ -191,14 +191,76 @@ When running inside `/copilot` (detected by: `.claude/copilot-intent.md` exists)
 - Include `Commit:` with conventional commit format
 - Write `## Summary` with counts at the bottom
 
-### Problem-Architect Validation (if available)
+### Parallel Optimization Pass — Layer 1 (REQUIRED before writing plan.md)
 
-After writing plan.md, check:
+**Design note — two-layer safety model:**
+This pass is Layer 1: fast, directory-level, runs before plan.md is written.
+Layer 2 is problem-architect (after plan.md): exact file paths, catches shared utilities.
+Layer 3 is the orchestrator at dispatch: final `Files Written:` overlap check.
+
+Layer 1 catches ~80% of conflicts cheaply. Layer 2 catches the rest (shared utils, shared config).
+Layer 1 does NOT spawn agents — it uses grep only.
+
+**Step 1: Assign waves**
+```
+Wave 1 = milestones with Depends: none
+Wave 2 = milestones that only depend on Wave 1
+Wave N = milestones that only depend on waves 1..N-1
+```
+
+**Step 2: Directory-level isolation check (Layer 1a)**
+
+For each wave with 2+ milestones:
+- Does each milestone own a distinct top-level directory? (e.g., `src/auth/` vs `src/users/` vs `src/email/`)
+- Does any milestone touch shared config (`package.json`, `prisma/schema.prisma`, `tsconfig.json`, `go.mod`, `Cargo.toml`)?
+
+If two milestones share a top-level directory → add `Depends:` to split them into different waves.
+
+**Step 3: Shared-utility grep (Layer 1b)**
+
+For each same-wave pair, check if they likely share utility files:
+```bash
+# Find shared utility dirs that multiple features import from
+grep -r "from.*utils\|import.*utils\|require.*utils\|from.*shared\|from.*common\|from.*lib" \
+  src/ --include="*.ts" --include="*.py" --include="*.js" -l 2>/dev/null | head -20
+```
+
+If a `utils/`, `shared/`, `common/`, or `lib/` directory exists AND two parallel milestones
+both need to CREATE or MODIFY files there → set `Parallel: no` for both and add a Depends: relationship.
+
+**Do NOT spawn problem-architect here.** The grep is sufficient for Layer 1. Problem-architect
+runs after plan.md is written and handles the cases Layer 1 misses.
+
+**Step 4: Set Dirs: and Parallel: fields, write plan.md**
+
+```
+- Dirs:     top-level directories this milestone exclusively owns
+- Parallel: yes — safe at directory level + no shared utility writes
+- Parallel: no  — touches shared config, shared utility, schema, or depends on sibling
+- Wave:     {N}
+```
+
+A well-designed plan for a 6-feature product:
+```
+Wave 1: M1 (foundation/schema) — Parallel: no
+Wave 2: M2, M3, M4, M5 (independent features) — Parallel: yes (4 agents simultaneously)
+Wave 3: M6 (integration/E2E) — Parallel: no
+```
+
+---
+
+### Problem-Architect Validation — Layer 2 (after plan.md is written)
+
+Layer 2 refines Layer 1 with exact file-level analysis. Catches shared utilities that
+Layer 1's directory check missed (e.g., `src/utils/jwt.ts` shared by M2 and M3 even though
+their `Dirs:` are `src/auth/` and `src/users/`).
+
+Check if problem-architect is available:
 ```bash
 ls .claude/agents/problem-architect.md 2>/dev/null
 ```
 
-If problem-architect.md exists — spawn it for EACH milestone in plan.md:
+If available, spawn it for EACH milestone:
 ```
 Analyze this milestone for the Team Spec:
 Milestone: {description from plan.md}
@@ -207,16 +269,28 @@ Available agents: {list of .claude/agents/}
 Available skills: {list of .claude/skills/}
 ```
 
-For each milestone, append the returned Team Spec fields directly into plan.md:
+For each milestone, append the returned Team Spec fields to plan.md:
+- `Files Written:` exact paths (this is the authoritative list — supersedes `Files:`)
+- `Parallel Safe:` YES/NO with reason
 - `Complexity:` SIMPLE / MEDIUM / COMPLEX
-- `Files Written:` exact paths the builder will touch (critical for parallel safety)
-- `Pre-conditions:` checklist before starting
+- `Pre-conditions:` checklist
 - `Risks:` and mitigation
-- `Structural Decision:` YES/NO (if YES → orchestrator must /debate before dispatching)
+- `Structural Decision:` YES/NO
+
+**Correction pass — when Layer 2 contradicts Layer 1:**
+
+If problem-architect returns `Parallel Safe: NO` for milestone M_X but Layer 1 wrote `Parallel: yes`:
 
-This pre-annotation makes orchestrator dispatch faster and prevents parallel file collision.
+1. Read the reason: `Parallel Safe: NO — reason: {both M_X and M_Y write src/utils/jwt.ts}`
+2. Identify the conflicting pair (M_X and M_Y)
+3. Update plan.md:
+   - Add `Depends: M_X` to M_Y (or vice versa — whichever is simpler first)
+   - Update `Wave:` for M_Y to the next wave
+   - Change `Parallel: yes` → `Parallel: no` for affected milestones
+   - Update `## Summary` wave count
+4. This is a plan.md correction, not a failure — blueprint is refining its initial estimate
 
-After all milestones annotated — return control to /copilot.
+After all milestones annotated and corrections applied → return control to /copilot.
 
 ---
 

package/templates/commands/fix.md

@@ -67,6 +67,12 @@ Read the code. Do not guess.
 - Check recent changes: `git log --oneline -10 -- {file}`
 - Read test framework config: `package.json` / `requirements.txt` / `Cargo.toml`
 
+**If the error involves an external library or unknown error code**: check if Brave Search MCP is available:
+```bash
+claude mcp list 2>/dev/null | grep -q "brave" && echo "brave=active" || echo "brave=inactive"
+```
+If active: use `mcp__brave-search__brave_web_search` to look up the exact error message — often finds GitHub issues, Stack Overflow answers, or library changelogs that resolve ambiguity before you guess at a root cause.
+
 Antipattern check — if `antipatterns.md` exists, read it before proceeding.
 
 Rules:

package/templates/commands/mcp.md

@@ -0,0 +1,22 @@
+---
+name: mcp
+description: >
+  MCP server recommendations and setup for Claude Code projects. Use when the user
+  asks "what MCP should I use", "add MCP", "set up MCP", "improve Claude Code",
+  "Context7", "sequential thinking", "GitHub MCP", "Playwright MCP", "Supabase MCP",
+  "Brave Search", "add web search", "add browser control", "add database access",
+  "Claude doesn't know the latest API", "wrong library version", "stale docs",
+  "hallucinating API", or "which MCP works best for my stack".
+argument-hint: "[optional: stack or specific MCP name]"
+disable-model-invocation: true
+allowed-tools: Read, Bash, Glob
+---
+
+# /mcp — MCP Integration
+
+$ARGUMENTS
+
+Load skill: `skills/mcp/SKILL.md`
+
+Follow all steps in the skill: detect stack → recommend universal MCPs → recommend
+stack-specific MCPs → show install commands → apply security rules → verify.

package/templates/commands/parallel.md

@@ -0,0 +1,175 @@
+---
+name: parallel
+description: >
+  Dispatch multiple milestones simultaneously using git worktree isolation.
+  Each agent runs on its own branch, changes are merged sequentially after all complete.
+  Use when: "run these milestones in parallel", "build M1 M2 M3 simultaneously",
+  "parallel execution", "spawn multiple agents", "run agents in parallel",
+  "dispatch in parallel", "work on multiple milestones at once", "parallel build",
+  "run simultaneously", "multiple agents at once".
+  Do NOT trigger for: a single milestone, sequential work, or when milestones share files.
+argument-hint: "[M1 M2 M3 — milestone IDs from plan.md]"
+disable-model-invocation: true
+allowed-tools: Read, Bash, Glob, Grep, Task
+---
+
+# /parallel — Parallel Milestone Execution
+
+$ARGUMENTS
+
+Load: `capabilities/shared/parallel-coordination.md`
+
+---
+
+## Step 1: Parse Targets
+
+```bash
+# Read plan.md to find the specified milestones
+cat .claude/plan.md 2>/dev/null | head -200
+```
+
+From $ARGUMENTS, extract milestone IDs (e.g., "M1 M2 M3" or "1 2 3").
+If no arguments → show current pending milestones and ask which to parallelize.
+
+---
+
+## Step 2: Safety Check
+
+For each pair of target milestones, verify they are safe to parallelize:
+
+```bash
+# Check Files: fields in plan.md for each milestone
+grep -A5 "^## M{N}" .claude/plan.md | grep "^Files:"
+```
+
+**Reject and abort if any two milestones:**
+- Share a file in their `Files:` field
+- Both touch `package.json`, `requirements.txt`, `Cargo.toml`, `go.mod`, or any schema file
+- Have a `Depends:` relationship between them (one depends on the other)
+- Either has status `blocked` or `done`
+
+If safety check fails: show which pairs conflict and suggest sequential order instead.
+
+---
+
+## Step 3: Consult Problem Architect
+
+For each milestone, spawn problem-architect to get Team Spec + `Parallel Safe` verdict:
+
+```
+Task: Analyze milestone for parallel dispatch
+Milestone: {description from plan.md}
+Current state: {what exists}
+Available agents: {list .claude/agents/}
+Return Team Spec with Parallel Safe field.
+```
+
+If any milestone returns `Parallel Safe: NO` → exclude from parallel wave, run sequentially after.
+
+---
+
+## Step 4: Write Ownership Map
+
+Create or update `.claude/ownership.md`:
+
+```
+## Active Parallel Session — {ISO timestamp}
+Milestones: {M1, M2, ...}
+Initiated by: /parallel command
+
+| Agent Slot | Milestone | Branch | Directories Owned | Status |
+|------------|-----------|--------|-------------------|--------|
+| P1 | M{N} — {title} | parallel/m{n}-{slug} | {dirs from spec} | pending |
+| P2 | M{N} — {title} | parallel/m{n}-{slug} | {dirs from spec} | pending |
+```
+
+---
+
+## Step 5: Dispatch All Agents Simultaneously
+
+Spawn all milestone-builder agents **in a single message** (true parallel — one Task call per agent in the same response):
+
+For each milestone, Task with `isolation: "worktree"`:
+
+```
+Task: Implement Milestone {N} — {title}
+
+[PARALLEL MODE — WORKTREE ISOLATED]
+Branch: parallel/{milestone-slug}
+
+Agent role: {from Team Spec}
+Directories owned: {from Team Spec}
+
+{standard context from orchestrator Step 4}
+
+Worktree rules (MANDATORY):
+- Only write files within your "Directories owned"
+- DO NOT run git push — commit locally only
+- If you see errors in files outside your directories: STOP, report "scope violation"
+- End your report with: "Branch: parallel/{slug}"
+```
+
+---
+
+## Step 6: Wait and Monitor
+
+After all agents complete:
+- Collect all completion reports
+- Mark each as COMPLETE or FAILED in ownership.md
+
+---
+
+## Step 7: Merge Sequentially
+
+Follow the Merge Protocol from `capabilities/shared/parallel-coordination.md`:
+
+```bash
+git checkout main
+
+# Merge branches one at a time (simplest first)
+git merge parallel/{slug-1} --no-ff -m "merge: M{N} {title} [parallel wave]"
+# Run tests after each merge
+{test command} 2>&1 | tail -10
+
+git merge parallel/{slug-2} --no-ff -m "merge: M{N} {title} [parallel wave]"
+{test command} 2>&1 | tail -10
+
+# Push once all merges pass
+git push origin main
+
+# Cleanup
+git branch -d parallel/{slug-1} parallel/{slug-2}
+```
+
+**If merge conflict**: read both versions, apply correct merge (keep both feature additions), continue.
+**If tests fail after a merge**: identify which merge broke it → revert that branch → add milestone to blocked.
+
+---
+
+## Step 8: Update Plan + Report
+
+Update `.claude/plan.md` — set merged milestones to `status: done`.
+Update `.claude/ownership.md` — replace active table with merge record.
+
+Show final report:
+```
+/parallel — Wave Complete
+═══════════════════════════════════════
+Milestones dispatched: {N}
+  ✓ M{N} — {title} (merged, tests pass)
+  ✓ M{N} — {title} (merged, tests pass)
+  ✗ M{N} — {title} (merge conflict → added to blocked)
+
+Tests: PASS — {N} passing after merge
+Time saved vs sequential: ~{N} build cycles
+```
+
+---
+
+## Completion Rule
+
+Do not say "parallel complete" without showing:
+1. Each agent's completion status
+2. Merge result for each branch (pass/conflict)
+3. Final test output after all merges
+4. Updated plan.md milestone statuses

package/templates/commands/setup.md

@@ -209,6 +209,24 @@ If all three exist:
   ✓ Constitution, coding rules, and specs found. Ready for /copilot.
 ```
 
+Always append MCP check (regardless of other states):
+```bash
+claude mcp list 2>/dev/null | grep -c "." || echo "0"
+```
+
+```
+  · MCP servers configured: {N}
+    Run: /mcp
+    Why: Context7 fixes stale API docs in /add and /copilot.
+         Sequential Thinking improves /blueprint and /copilot planning.
+         Both are free — no API key needed.
+```
+
+If N ≥ 1, show instead:
+```
+  · {N} MCP server(s) active. Run /mcp to check stack-specific recommendations.
+```
+
 ---
 
 ## If Running Again on an Existing Project

package/templates/skills/mcp/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: mcp
+description: >
+  MCP server recommendations and setup for Claude Code projects. Use when the user
+  asks "what MCP should I use", "add MCP", "set up MCP", "improve Claude Code",
+  "Context7", "sequential thinking", "GitHub MCP", "Playwright MCP", "Supabase MCP",
+  "Brave Search", "add web search", "add browser control", "add database access",
+  "Claude doesn't know the latest API", "wrong library version", "stale docs",
+  "hallucinating API", or when /setup detects a stack and needs to recommend
+  integrations. Also use when user wants to configure .mcp.json, add tools to
+  Claude Code, or asks which MCP works best for their stack.
+  Do NOT trigger when: user is asking about AZCLAUDE's own security scanner for
+  MCP configs (use security skill). Do NOT trigger for generic npm package questions.
+---
+
+# MCP Integration
+
+MCP servers extend Claude Code with live capabilities: real-time docs, web search,
+browser control, database access. AZCLAUDE recommends MCPs based on your stack —
+it never bundles them (zero-dep rule).
+
+## Step 0: Detect Stack
+
+Read these before recommending:
+```bash
+cat package.json 2>/dev/null | grep -E '"next"|"react"|"supabase"|"prisma"|"postgres"|"playwright"' | head -10
+cat CLAUDE.md 2>/dev/null | grep -E "Stack:|Domain:" | head -5
+ls .mcp.json ~/.claude/claude_desktop_config.json 2>/dev/null && echo "mcp=configured" || echo "mcp=none"
+```
+
+## Step 1: Universal — Recommend for Every Project
+
+These improve ALL AZCLAUDE workflows regardless of stack:
+
+| MCP | What it fixes | Install |
+|-----|--------------|---------|
+| **Context7** | `/copilot` and `/add` write code against stale training data — wrong API signatures, deprecated methods. Context7 injects current docs at prompt time. | `claude mcp add context7 npx @upstash/context7-mcp` |
+| **Sequential Thinking** | Orchestrator, milestone-builder, and `/blueprint` make better multi-step decisions when they can reason iteratively with branching. | `claude mcp add sequential-thinking npx @modelcontextprotocol/server-sequential-thinking` |
+
+Always recommend both. They cost nothing (free, no API key) and improve every session.
+
+## Step 2: Stack-Specific — Recommend Based on Detection
+
+| If stack contains | Recommend | Why |
+|------------------|-----------|-----|
+| Any GitHub repo | **GitHub MCP** | Richer than `gh` CLI for `/issues`, `/ship`, PR reviews, repo search |
+| Any web project | **Playwright MCP** | E2E testing — pairs with qa-engineer agent and `/test` |
+| `supabase` in deps | **Supabase MCP** | Schema introspection, migrations, Edge Functions from within Claude Code |
+| `postgres`/`prisma` in deps | **PostgreSQL MCP** | Natural language queries, schema exploration during development |
+| Debugging / `/fix` heavy | **Brave Search** | Real-time error lookup, CVE research for `/sentinel`, library issue tracking |
+| Design-to-code workflow | **Figma MCP** | Translate Figma components directly to code |
+
+## Step 3: Install Commands
+
+```bash
+# Universal — install these for every project
+claude mcp add context7 npx @upstash/context7-mcp
+claude mcp add sequential-thinking npx @modelcontextprotocol/server-sequential-thinking
+
+# GitHub (no API key needed with Claude Code auth)
+claude mcp add github npx @modelcontextprotocol/server-github
+
+# Playwright (Microsoft official)
+claude mcp add playwright npx @playwright/mcp@latest
+
+# Brave Search (requires BRAVE_API_KEY)
+claude mcp add brave-search npx @modelcontextprotocol/server-brave-search \
+  --env BRAVE_API_KEY=${BRAVE_API_KEY}
+
+# Supabase (requires SUPABASE_ACCESS_TOKEN)
+claude mcp add supabase npx @supabase/mcp-server-supabase \
+  --env SUPABASE_ACCESS_TOKEN=${SUPABASE_ACCESS_TOKEN}
+
+# PostgreSQL
+claude mcp add postgres npx @modelcontextprotocol/server-postgres \
+  postgresql://localhost/mydb
+```
+
+## Step 4: Security Rules (Always Apply)
+
+Before writing any `.mcp.json`:
+- **Never hardcode secrets** — use `${ENV_VAR}` syntax always
+- **Pin versions** — use `@1.2.3` not `@latest` in production
+- **Scope to project** — use `claude mcp add --scope project` not global when possible
+- Run `/sentinel` after adding MCPs to verify the config scores cleanly
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@1.0.0"]
+    },
+    "brave-search": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+      "env": { "BRAVE_API_KEY": "${BRAVE_API_KEY}" }
+    }
+  }
+}
+```
+
+## Step 5: Verify Installation
+
+```bash
+claude mcp list                    # shows configured servers
+claude mcp get context7            # shows context7 config
+```
+
+Then test in Claude Code: ask Claude "use context7 to get the latest React docs" — if it returns live docs, it's working.
+
+For full MCP catalog: `references/mcp-catalog.md`

package/templates/skills/mcp/references/mcp-catalog.md

@@ -0,0 +1,54 @@
+# MCP Catalog — Full Reference
+
+## Universal (all projects)
+
+| Name | Package | API Key | Use in AZCLAUDE |
+|------|---------|---------|-----------------|
+| Context7 | `@upstash/context7-mcp` | None | Inject live library docs into /add, /fix, /copilot |
+| Sequential Thinking | `@modelcontextprotocol/server-sequential-thinking` | None | Better reasoning in orchestrator, /blueprint, /debate |
+
+## Developer Tools
+
+| Name | Package | API Key | Use in AZCLAUDE |
+|------|---------|---------|-----------------|
+| GitHub | `@modelcontextprotocol/server-github` | `GITHUB_TOKEN` (optional) | /issues, /ship, PR creation, repo search |
+| Playwright | `@playwright/mcp` | None | E2E tests with qa-engineer, /test |
+| Brave Search | `@modelcontextprotocol/server-brave-search` | `BRAVE_API_KEY` | /fix error lookup, /sentinel CVE research |
+| Firecrawl | `firecrawl-mcp` | `FIRECRAWL_API_KEY` | Scrape live docs, competitor analysis |
+| Sentry | `@sentry/mcp-server` | `SENTRY_TOKEN` | Pipe production errors into /fix sessions |
+
+## Database
+
+| Name | Package | API Key | Use in AZCLAUDE |
+|------|---------|---------|-----------------|
+| Supabase | `@supabase/mcp-server-supabase` | `SUPABASE_ACCESS_TOKEN` | Schema exploration, migrations, Edge Functions |
+| PostgreSQL | `@modelcontextprotocol/server-postgres` | DB URL | Natural language queries during dev |
+| SQLite | `@modelcontextprotocol/server-sqlite` | None | Local DB for prototypes |
+
+## Design & Content
+
+| Name | Package | API Key | Use in AZCLAUDE |
+|------|---------|---------|-----------------|
+| Figma | figma-mcp | `FIGMA_TOKEN` | Design-to-code with frontend-design skill |
+
+---
+
+## Install All Universal MCPs
+
+```bash
+claude mcp add context7 npx @upstash/context7-mcp
+claude mcp add sequential-thinking npx @modelcontextprotocol/server-sequential-thinking
+```
+
+## Verify
+
+```bash
+claude mcp list
+```
+
+## Security Checklist
+
+- [ ] No plaintext secrets in `.mcp.json` — use `${ENV_VAR}`
+- [ ] Versions pinned (not `@latest`) for production
+- [ ] Run `/sentinel` after changes to score MCP config
+- [ ] `.mcp.json` in `.gitignore` if it contains env refs to local paths