azclaude-copilot 0.4.33 → 0.4.36

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.33",
+      "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 37 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.36",
       "source": {
         "source": "github",
         "repo": "haytamAroui/AZ-CLAUDE-COPILOT",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "azclaude",
-  "version": "0.4.33",
-  "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.36",
+  "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 37 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 37 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, 10 skills, memory, reflexes)
+- **First time** → full install (37 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,12 +131,12 @@ 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**
+**37 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...)
+├── 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)
@@ -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 37 Commands
 
 ### Build and Ship
 
@@ -653,6 +707,10 @@ 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. |
+| `/driven` | Generate `.claude/code-rules.md` — 6-question interview → DO/DO NOT coding contract. Read by every /add and /fix before writing code. |
+| `/verify` | Audit existing code against `code-rules.md`. Reports violations at `file:line`. Auto-fix mode. Falls back to per-stack rule libraries when no contract exists. |
 
 ### Think and Improve
 
@@ -807,11 +865,11 @@ Run `/level-up` at any time to see your current level and build the next one.
 
 ## Verified
 
-1473 tests. Every template, command, capability, agent, hook, and CLI feature verified.
+1558 tests. Every template, command, capability, agent, hook, and CLI feature verified.
 
 ```bash
 bash tests/test-features.sh
-# Results: 1473 passed, 0 failed, 1473 total
+# Results: 1558 passed, 0 failed, 1558 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', 'verify'];
+const ADVANCED_COMMANDS = ['evolve', 'debate', 'level-up', 'copilot', 'reflexes', 'parallel'];
 const COMMANDS          = [...CORE_COMMANDS, ...EXTENDED_COMMANDS, ...ADVANCED_COMMANDS];
 
 function ok(msg)   { console.log(`  ✓ ${msg}`); }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "azclaude-copilot",
-  "version": "0.4.33",
-  "description": "AI coding environment — 34 commands, 10 skills, 15 agents, memory, reflexes, evolution. Install: npx azclaude-copilot@latest, then open Claude Code.",
+  "version": "0.4.36",
+  "description": "AI coding environment — 37 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,21 @@ 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)
+  - /verify → audits existing code against code-rules.md (file:line violations + auto-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 +65,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 · /verify

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/manifest.md

@@ -58,6 +58,16 @@ Load only the files that match the current task. Never load the full list.
 | intelligence/pipeline.md | 3+ agents must chain output — context bleed is a risk | ~350 |
 | intelligence/experiment.md | Trying a risky approach that must not touch main branch — "try this safely" | ~80 |
 
+## Code Rules — per-stack rule libraries (load matching stack only)
+| File | When to load | Tokens |
+|------|-------------|--------|
+| shared/rules/typescript.md | Writing or verifying TypeScript code — load for /add, /fix, /verify when TS detected | ~250 |
+| shared/rules/react.md | Writing or verifying React/Next.js components — load when JSX/TSX detected | ~250 |
+| shared/rules/python.md | Writing or verifying Python/FastAPI/Django code — load when .py detected | ~250 |
+| shared/rules/node.md | Writing or verifying Node.js/Express backend code — load when Node stack detected | ~250 |
+
+**When to load:** `/verify` (rule source), `/driven` (default rule generation), `/add` and `/fix` (when no code-rules.md exists and stack is detected). Load only the matching stack file, never all four.
+
 ## Spec-Driven Workflow — load in sequence
 | Command | Purpose | Loads |
 |---------|---------|-------|

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/capabilities/shared/rules/node.md

@@ -0,0 +1,70 @@
+# Node.js / Express Code Rules — Curated DO/DO NOT Reference
+
+**Load when**: stack contains Node.js, Express, Fastify, or similar backend JS/TS; generating code-rules.md for Node projects; or verifying Node/Express files.
+
+---
+
+## Async Patterns
+
+- DO: use `async/await` throughout — no callback-style code in new files
+- DO: always `await` Promises or chain `.catch()` — unhandled rejections crash Node
+- DO: wrap `await` calls in `try/catch` at the service boundary
+- DO NOT: mix `async/await` and `.then()/.catch()` in the same function
+- DO NOT: use `Promise.all` without handling individual rejections — use `Promise.allSettled` when partial failure is acceptable
+
+## Route Structure
+
+- DO: split routes into separate files by resource — `routes/users.ts`, `routes/orders.ts`
+- DO: use a router factory pattern — `export function usersRouter(deps: Deps): Router`
+- DO: validate all request input at the route entry — use zod, joi, or class-validator
+- DO: return semantically correct HTTP status codes:
+  - `201` for successful resource creation
+  - `204` for successful delete with no body
+  - `400` for validation failures
+  - `404` for not found
+  - `409` for conflicts
+  - `422` for unprocessable entity
+- DO NOT: put business logic in route handlers — delegate to a service layer
+- DO NOT: return stack traces in error responses — log server-side, return a generic message
+
+## Middleware
+
+- DO: register middleware in order: security → logging → parsing → auth → routes → errors
+- DO: error-handling middleware uses 4 parameters exactly: `(err, req, res, next)`
+- DO: always call `next(err)` on errors in async middleware — never swallow silently
+- DO NOT: call both `next()` and `res.send()` in the same middleware path
+- DO NOT: use synchronous file I/O in middleware (`fs.readFileSync`) — blocks the event loop
+
+## Database and Queries
+
+- DO: use parameterized queries or an ORM — never concatenate user input into SQL
+- DO: define a data access layer (repository) — routes and services never call the DB directly
+- DO: use database transactions for multi-step writes
+- DO NOT: select `*` — list columns explicitly in queries
+- DO NOT: put connection logic inside route handlers — use a shared pool or ORM connection
+
+## Security
+
+- DO: load secrets from `process.env` — never hardcode keys, tokens, or passwords in source
+- DO: validate and sanitize all user input before use
+- DO: set security headers — use `helmet` for Express
+- DO: apply rate limiting to all public endpoints
+- DO NOT: log request bodies containing passwords or tokens
+- DO NOT: expose internal error messages to clients — wrap in a safe error response
+
+## Configuration
+
+- DO: validate all required env vars at startup — fail fast with a clear message if missing
+  ```ts
+  const PORT = Number(process.env.PORT) || 3000;
+  if (!process.env.DATABASE_URL) throw new Error("DATABASE_URL required");
+  ```
+- DO: use a config module — centralize all `process.env` access in one file
+- DO NOT: use `process.env.X` scattered throughout the codebase
+
+## Testing
+
+- DO: test routes with supertest against the real Express app — not mocked handlers
+- DO: use a test database — never run tests against production or development databases
+- DO: reset database state between tests using transactions or table truncation
+- DO NOT: mock the database layer in route integration tests — it hides real issues