azclaude-copilot 0.7.3 → 0.7.5

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "azclaude",
       "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 40 commands, 10 auto-invoked skills, 15 specialized agents, 5 hooks, a real-time pipeline visualizer, 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.7.3",
+      "version": "0.7.5",
       "source": {
         "source": "github",
         "repo": "haytamAroui/AZ-CLAUDE-COPILOT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "azclaude",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 40 commands, 10 auto-invoked skills, 15 specialized agents, 5 hooks, a real-time pipeline visualizer, 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",

package/README.md

@@ -637,11 +637,11 @@ AZCLAUDE is a lazy-loaded environment of 48 capability modules. It only loads wh
 
 ## Verified
 
-1902 tests. Every template, command, capability, agent, hook, and CLI feature verified.
+1958 tests. Every template, command, capability, agent, hook, and CLI feature verified.
 
 ```bash
 bash tests/test-features.sh
-# Results: 1902 passed, 0 failed, 1902 total
+# Results: 1958 passed, 0 failed, 1958 total
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "azclaude-copilot",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "description": "AI coding environment — 40 commands, 10 skills, 15 agents, real-time visualizer, memory, reflexes, evolution. Install: npx azclaude-copilot@latest, then open Claude Code.",
   "bin": {
     "azclaude": "bin/cli.js",

package/templates/CLAUDE.md

@@ -12,6 +12,11 @@
 {{PROJECT_DESCRIPTION}}
 Domain: {{DOMAIN}} | Stack: {{STACK}} | Scale: {{SCALE}}
 
+## Verify
+Quick: {{QUICK_VERIFY}}
+Test: {{TEST_VERIFY}}
+Build: {{BUILD_VERIFY}}
+
 ## Rules
 1. **Completion** — Never say "should work" or "probably passes." Show the output or stay in progress.
 2. **Precision** — Reference code as `file:line`. Never describe in prose.

package/templates/agents/milestone-builder.md

@@ -79,19 +79,66 @@ Rules:
 
 ---
 
-### Step 3: Verify
+### Step 3: Verify — Toolchain Exit Gate (MANDATORY)
 
+Load `capabilities/shared/toolchain-gate.md` for the stack-to-command mapping.
+Read the `Verify:` field from the Team Spec injected in your prompt. If missing, read CLAUDE.md `## Verify`.
+
+Create the logs directory:
+```bash
+mkdir -p .claude/logs
+```
+
+**Tier 1: Static verification (MANDATORY — always run)**
+```bash
+# Use the Quick command from Team Spec Verify: field
+{quick_verify_cmd} 2>&1 | tee .claude/logs/verify-log-M{N}.md
+echo "TIER1_EXIT=$?" >> .claude/logs/verify-log-M{N}.md
+```
+- Errors in YOUR files → fix them (counts as a self-correction attempt)
+- Errors in OTHER files → append to verify log: `"Scope violation: {file} — outside my directories"` — do NOT fix
+- Tool not installed → skip with warning: `"Tier 1 SKIPPED: {tool} not available"`
+
+**Tier 2: Scoped test verification (MANDATORY)**
+```bash
+# Use the Test command from Team Spec Verify: field
+{scoped_test_cmd} 2>&1 | tee -a .claude/logs/verify-log-M{N}.md
+echo "TIER2_EXIT=$?" >> .claude/logs/verify-log-M{N}.md
+```
+- In parallel mode: run ONLY tests in your Test scope — not the full suite
+- In sequential mode: run full test suite
+
+**Tier 2b: Runtime verification (ONLY if Team Spec Verify: Runtime ≠ SKIP)**
 ```bash
-# Run tests — detect framework from project
-npm test 2>&1 | tail -20 || \
-pytest 2>&1 | tail -20 || \
-cargo test 2>&1 | tail -20 || \
-go test ./... 2>&1 | tail -20
+# Run the app briefly, capture crashes
+timeout 15 {run_command} 2>&1 | tee .claude/logs/runtime-M{N}.log; exit 0
+```
+The `exit 0` prevents Claude Code from treating a crash as a Bash failure.
+If the runtime log contains stack traces or crash output → read it, diagnose, fix if in your scope.
+
+**Write the verify log summary at the top of the file:**
+```markdown
+## Verify Log — M{N}: {title}
 
-echo "Exit: $?"
+### Tier 1: Static ({command})
+Status: PASS | FAIL
+Errors: {count} | Warnings: {count}
+
+### Tier 2: Scoped Tests ({command})
+Status: PASS | FAIL
+Tests: {pass}/{total}, {duration}
+
+### Tier 2b: Runtime
+Status: PASS | SKIP | CRASH
+{stack trace summary if crash}
+
+### Self-Correction History
+Attempt 1: {what happened}
+  Fix: {what was changed}
+Attempt 2: {result}
 ```
 
-Tests must PASS before reporting done. Show actual output — never summarize.
+Tests and Tier 1 must PASS before reporting done. Show actual output — never summarize.
 
 ---
 
@@ -148,9 +195,16 @@ Branch: {current branch name}  ← required for orchestrator merge tracking
 ### Files Changed
 - {file}: {create|modify} — {one-line description}
 
-### Test Status
-PASS — {N} tests passing
-{first 5 lines of test output}
+### Verify Status
+Tier 1 (static): PASS | FAIL | SKIPPED — {error count} errors, {warning count} warnings
+Tier 2 (tests): PASS | FAIL — {pass}/{total} tests, {duration}
+Runtime: PASS | SKIP | CRASH
+Verify log: .claude/logs/verify-log-M{N}.md
+Runtime log: .claude/logs/runtime-M{N}.log (if exists)
+
+### Self-Correction Summary
+Attempts used: {N} / {budget}
+{one-line per fix if any}
 
 ### New Patterns Discovered
 {pattern description} — or "none"

package/templates/agents/orchestrator.md

@@ -36,6 +36,37 @@ If CLAUDE.md unfilled → run `/setup` with intent from copilot-intent.md first.
 
 ---
 
+### Step 1a: Toolchain Bootstrap (MANDATORY before first dispatch)
+
+Load `capabilities/shared/toolchain-gate.md` for the full protocol.
+
+```bash
+# Check if Verify field exists in CLAUDE.md
+grep -q "^## Verify" CLAUDE.md 2>/dev/null && echo "verify=configured" || echo "verify=missing"
+```
+
+If `verify=missing` → run the Toolchain Detection Protocol from toolchain-gate.md:
+1. Detect stack files (`package.json`, `Cargo.toml`, `go.mod`, etc.)
+2. Check tool availability (`command -v node`, `command -v cargo`, etc.)
+3. If tool missing AND installer available → install automatically (copilot mode is autonomous)
+4. Install dependencies if missing (`npm install`, `cargo fetch`, etc.)
+5. Write `## Verify` section to CLAUDE.md
+6. Log all output to `.claude/logs/bootstrap.log`
+
+```bash
+mkdir -p .claude/logs
+```
+
+**Smoke test** — run the quick verify command once:
+```bash
+{quick_verify_cmd} 2>&1 | tee .claude/logs/bootstrap.log
+```
+- PASS → proceed to dispatch
+- FAIL → fix the build BEFORE dispatching any agents. This IS the foundation.
+- Tool unavailable → log warning: `"⚠ Verification degraded: {tool} not available"` — proceed with reduced verification
+
+---
+
 ### Step 1b: Resume Interrupted Parallel Wave
 
 ```bash
@@ -161,9 +192,11 @@ Load `capabilities/shared/context-relay.md` for relay protocol and role-based fi
 2. Write `.claude/parallel-wave-state.md` with `dispatch_mode: dag` (see parallel-coordination.md)
 3. **Pre-read shared files** (models, schemas, configs referenced by 2+ agents) and relay their content via a `## Pre-loaded Context` block in each agent's prompt — builders MUST NOT re-read relayed files
 4. If problem-architect returned a `## Relay` section, include it in the builder prompt as-is
-5. Spawn each builder via Task with `isolation: "worktree"` in the same message (true parallel)
-5. Include worktree rules + **test scope** (`Test scope: {test-dir}`) in every parallel prompt
-6. **Merge-on-complete**: as each agent reports done, merge its branch immediately (don't wait for all)
+5. **Skill consistency** — collect the UNION of all skills from all Team Specs in this wave. Every agent in the wave loads the SAME skill set (not just its own). This ensures consistent patterns across parallel agents.
+6. **Include Verify commands** from each Team Spec in the agent prompt — the builder uses these in its exit gate
+7. Spawn each builder via Task with `isolation: "worktree"` in the same message (true parallel)
+8. Include worktree rules + **test scope** (`Test scope: {test-dir}`) in every parallel prompt
+9. **Merge-on-complete**: as each agent reports done, merge its branch immediately (don't wait for all)
 7. After each merge: check if newly-unblocked milestones exist → dispatch them immediately
 8. If `max_parallel <= 3` or merge conflicts detected: fall back to batch-merge (wait for all, then merge)
 
@@ -215,14 +248,67 @@ Dependent milestones, overlapping `Files Written`, or `Parallel Safe: NO` → sp
 
 ---
 
-### Step 5: Monitor Results + Merge-on-Complete
+### Step 5: Monitor Results + Merge-on-Complete + Verification Wave
 
 **When an agent reports PASS (parallel mode):**
 1. Merge its branch to main immediately: `git merge parallel/{slug} --no-ff`
 2. Run tests for the merged module: `{test command} tests/{agent-scope}/ 2>&1 | tail -10`
 3. If tests pass → update plan.md status → `done`, update `.claude/parallel-wave-state.md`
-4. **Check DAG for newly-unblocked milestones** — any milestone whose `Depends:` are now ALL `done` becomes ready. Dispatch it immediately (back to Step 3 → Step 4).
-5. New pattern emerged? → append to patterns.md
+4. New pattern emerged? → append to patterns.md
+
+**When ALL agents in a wave complete → VERIFICATION WAVE (mandatory):**
+
+Read `capabilities/shared/toolchain-gate.md` for the Tier 3 command and log protocol.
+Before dispatching ANY next-wave agents:
+
+```bash
+# 1. Tier 3: Full build — write to build log
+{build_command} 2>&1 | tee .claude/logs/build-wave{N}.log
+echo "EXIT=$?" >> .claude/logs/build-wave{N}.log
+
+# 2. Full test suite (not scoped — the FULL suite)
+{test_command} 2>&1 | tee -a .claude/logs/build-wave{N}.log
+```
+
+**3. Read all agent verify logs for this wave:**
+```bash
+cat .claude/logs/verify-log-M*.md 2>/dev/null
+cat .claude/logs/runtime-M*.log 2>/dev/null
+```
+Collect warnings across agents — relay relevant ones to next-wave agents.
+
+**4. If build or tests fail → dispatch a FIX agent with log relay:**
+```
+Task: Fix post-Wave {N} build failure
+
+## Build Log (last 100 lines)
+{tail -100 .claude/logs/build-wave{N}.log}
+
+## Agent Verify Logs Summary
+{for each agent: M{X} — PASS/FAIL, errors, warnings}
+
+## Runtime Logs (if any)
+{contents of .claude/logs/runtime-M{X}.log for this wave}
+
+## Diagnosis
+Build error at {file}:{line} was introduced by M{X}'s merge.
+M{X}'s verify log shows: {relevant warning}
+
+Fix the errors. The logs above give you full context — do NOT re-investigate from scratch.
+```
+
+- Build failure → integration error from parallel agents. Fix it now — it multiplies if ignored.
+- Test failure → identify which merge broke it from the build log. Revert that branch or fix in place.
+- **Only after verification passes → check DAG for newly-unblocked milestones → dispatch.**
+- This applies to EVERY wave transition. No exceptions.
+
+**Context refresh for Wave 3+ (mandatory):**
+
+When dispatching Wave 3 or later, agents work on a codebase modified by many prior agents.
+Before writing agent prompts for Wave N ≥ 3:
+1. Re-read ALL files that Wave N agents will import or depend on — use FRESH reads, not cached
+2. Include fresh file contents in `## Pre-loaded Context` — not stale copies from earlier waves
+3. Add to every Wave 3+ agent prompt: `"Note: {count} milestones have modified the codebase. Pre-loaded Context reflects CURRENT state. Trust it over plan.md assumptions."`
 
 **When an agent reports PASS (sequential mode):**
 - Approve commit

package/templates/agents/problem-architect.md

@@ -53,6 +53,7 @@ Also read:
 - `.claude/memory/patterns.md` — established conventions for this area
 - `.claude/memory/antipatterns.md` — known failure patterns to avoid
 - Context artifacts: `prisma/schema.prisma`, `openapi.yaml`, `.env.example`
+- CLAUDE.md `## Verify` section — for the `Verify:` field in Team Spec (see `capabilities/shared/toolchain-gate.md`)
 
 ---
 
@@ -156,11 +157,21 @@ If YES: topic = {what orchestrator must /debate before dispatching}
 SIMPLE (< 3 files) | MEDIUM (3-8 files) | COMPLEX (8+ files)
 COMPLEX → orchestrator gives builder 3 fix attempts instead of 2
 
+### Verify
+Read CLAUDE.md `## Verify` field for the project's commands. Scope them to this milestone:
+- Quick: `{Tier 1 command}` — static check, MANDATORY before done
+- Test: `{Tier 2 command scoped to this milestone's directories}`
+- Runtime: `{run command if this milestone affects startup/routes/jobs}` — or SKIP
+Example: `Quick: cargo check | Test: cargo test tests/auth/ | Runtime: SKIP`
+The milestone-builder uses these exact commands in its exit gate.
+
 ### Parallel Safe
-YES | NO
+YES | NO | SEQUENTIAL-ONLY
 If NO: reason = {specific conflict — shared file, schema dependency, runtime ordering}
+If SEQUENTIAL-ONLY: reason = {migration, cross-cutting refactor, 15+ files, pattern-setting}
 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.
+Parallel Safe = SEQUENTIAL-ONLY means: this milestone must NEVER be split across agents — see sizing rules below.
 
 ### Relay (for milestone-builder — do not re-read)
 {Include condensed contents of key files you read during analysis.
@@ -175,6 +186,32 @@ Maximum ~4000 tokens for this section.}
 
 ---
 
+## Agent Sizing Rules — When to Force Sequential
+
+A milestone MUST be marked `Parallel Safe: SEQUENTIAL-ONLY` if ANY of these apply:
+
+| Signal | Why it can't be split |
+|--------|----------------------|
+| Touches 15+ files | Too many interdependencies for one agent to track in isolation |
+| Framework/library migration | Every file depends on the pattern set by the first file edited |
+| Store/state management rewrite | All consumers depend on the new store shape |
+| Global type rename or API contract change | Callers can't be split from the definition |
+| Build tool or bundler change | Config affects every file's compilation |
+| Auth/middleware rewrite | Everything downstream depends on the new interface |
+
+**When a milestone is too large but must stay sequential, recommend decomposition:**
+```
+Recommend: Split into 3 SEQUENTIAL sub-milestones:
+  1. {foundation — sets the pattern} → Parallel Safe: SEQUENTIAL-ONLY
+  2. {consumers group A — follows the pattern} → Depends: sub-1
+  3. {consumers group B — follows the pattern} → Depends: sub-2
+```
+Each sub-milestone has a checkpoint. Still sequential, but with clear boundaries and rollback points.
+
+**Key insight:** The fix for an oversized milestone is better decomposition, not more agents. Splitting a migration across parallel agents produces inconsistent patterns that are harder to fix than doing it sequentially.
+
+---
+
 ## Rules
 
 - **NEVER implement.** NEVER write to project files. Tools: Read, Grep, Glob, Bash only.
@@ -183,4 +220,5 @@ Maximum ~4000 tokens for this section.}
 - **Be specific.** "Load security skill" is weak.
   "Load security skill because M4 handles Stripe webhook HMAC signatures" is strong.
 - **Files Written must be exhaustive.** A missed file causes silent parallel corruption.
+- **ALWAYS apply agent sizing rules.** A 32-file migration marked Parallel Safe: YES causes cascading failures.
 - If unsure whether an agent exists → Grep .claude/agents/ for it. Never assume.

package/templates/capabilities/manifest.md

@@ -30,6 +30,7 @@ Load only the files that match the current task. Never load the full list.
 | shared/reward-hack-detection.md | /audit, /ship, post-milestone review — detect reward hacking patterns in test modifications | ~150 |
 | shared/ultrathink.md | $ARGUMENTS contains --deep, or command needs extended thinking for complex analysis | ~80 |
 | shared/context-relay.md | About to spawn a subagent — pass pre-read files to eliminate redundant reads across agent boundaries | ~300 |
+| shared/toolchain-gate.md | /copilot dispatch, /parallel, agent verify, env-scan — stack detection, verify commands, toolchain bootstrap, 3-tier verification, log protocol | ~500 |
 
 ## Level Builders — load ONE at a time
 | File | When to load | Tokens |

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

@@ -342,6 +342,122 @@ After resume completes, continue with Merge Protocol → Plan Update → Cleanup
 
 ---
 
+## Universal Parallel Execution Rules
+
+These rules are technology-agnostic. They apply to every parallel dispatch regardless of stack, framework, or language.
+
+### Rule 1: Verification Wave — Mandatory Between Every Parallel Batch
+
+After ALL agents in a wave complete and merge, run a **verification step** before dispatching the next wave:
+
+```
+Wave N agents complete → merge all branches → VERIFICATION:
+  1. Run full build (compile/transpile/lint — whatever the project uses)
+  2. Run full test suite (not scoped — the FULL suite)
+  3. If build fails → fix before next wave (these are integration errors from parallel agents)
+  4. If tests fail → identify which merge broke it → revert or fix before next wave
+  5. Only after verification passes → dispatch Wave N+1
+```
+
+**Why:** Parallel agents can't verify integration — they only see their own worktree. Without verification, errors accumulate across waves. A type change in Wave 1 that breaks a Wave 2 consumer won't surface until the end, when fixing is 10x harder.
+
+**The verification agent is lightweight:** it runs build + tests, nothing else. No implementation. Budget ~2 minutes per wave.
+
+### Rule 2: Sweet Spot Is 3–5 Parallel Agents Per Wave
+
+| Agent count | Risk | Recommendation |
+|------------|------|----------------|
+| 1–2 | Low | Sequential is simpler — skip parallel overhead |
+| 3–5 | Optimal | Best ratio of speed gain to coordination cost |
+| 6 | Maximum | Only if all 6 own completely disjoint directories |
+| 7+ | Diminishing returns | Prompt quality degrades, merge complexity spikes |
+
+**Why:** Beyond 5 agents, the orchestrator's ability to write precise-enough prompts degrades. Each prompt needs exact file ownership, patterns, and anti-patterns. More agents = more surface area for conflicts that safety checks miss.
+
+### Rule 3: Wave 1 Sets the Contract
+
+The first wave establishes types, APIs, schemas, and patterns that ALL subsequent waves depend on. If Wave 1 gets something wrong, the error **multiplies** across every later agent.
+
+**Rules for Wave 1:**
+- Wave 1 should be the **smallest, most carefully specified wave**
+- Wave 1 milestones define shared types, base schemas, core configs
+- Wave 1 agents get **extra fix attempts** (3 instead of 2)
+- Wave 1 MUST pass verification before Wave 2 dispatches — no exceptions
+- If Wave 1 introduces a new pattern (e.g., error type, response shape), document it in `patterns.md` BEFORE dispatching Wave 2
+
+### Rule 4: Agent Size Limits — When NOT to Split
+
+A milestone that touches **15+ files** or performs a **cross-cutting change** (framework migration, global refactor, store pattern rewrite) should NOT be split across agents.
+
+**Signs a milestone must stay as one agent (sequential):**
+- Framework/library migration (every file depends on the pattern set by the first file edited)
+- Store/state management rewrite (all consumers depend on the new store shape)
+- Global type rename or API contract change (callers can't be split from the definition)
+- Auth/middleware rewrite (everything downstream depends on the new interface)
+
+**The fix is better decomposition, not more agents:**
+```
+BAD:  Split Svelte 5 migration into 5 parallel agents → inconsistent patterns
+GOOD: Split into 3 SEQUENTIAL sub-milestones:
+      1. Stores + shared state (sets the pattern)
+      2. Pages (follows the pattern)
+      3. Components (follows the pattern)
+      Each sub-milestone has checkpoints. Still sequential, but with clear boundaries.
+```
+
+**Rule: If a milestone can't be split without creating pattern inconsistency → keep it as one agent, sequential.**
+
+### Rule 5: Context Drift Mitigation for Later Waves
+
+By Wave 3+, agents work on a codebase modified by 5–15 previous agents. Assumptions about types, APIs, and file contents may be stale.
+
+**Mitigation protocol for Wave N (N ≥ 3):**
+1. Orchestrator re-reads ALL files that Wave N agents will import/depend on
+2. Orchestrator includes **fresh file contents** in the `## Pre-loaded Context` block — not cached from earlier waves
+3. Every Wave 3+ agent prompt includes: `"Warning: {N} milestones have modified the codebase since plan.md was written. Pre-loaded Context below reflects the CURRENT state. Trust it over plan.md assumptions."`
+4. If a type/interface was changed by a prior wave, include the **new** definition explicitly
+
+**Why:** Agents don't communicate with each other. An agent in Wave 4 that assumes `Result<_, String>` when Wave 2 changed it to `CmdResult<_>` will produce code that compiles in its worktree but fails on merge.
+
+### Rule 6: Skills Are the Consistency Layer
+
+Parallel agents never communicate, but they must produce consistent code. **Skills are how.**
+
+**Rules:**
+- ALL agents in the same wave MUST load the same skill set (from problem-architect's Team Spec)
+- If a project uses a specific pattern (e.g., Svelte 5 runes, Rust async, clean architecture), the matching skill MUST be loaded by every agent that touches that layer
+- If no skill exists for the project's core pattern → create it with `skill-creator` BEFORE dispatching the first wave
+- Skills ensure: consistent error handling, consistent naming, consistent imports, consistent test patterns
+
+**Why:** 5 agents in separate rooms producing code in 5 different styles is worse than 3 agents producing consistent code. Skills are the shared style guide that makes parallel agents act like a coordinated team.
+
+### Rule 7: Framework Migrations Are Always Sequential
+
+Any milestone classified as a **migration** (framework upgrade, language version bump, build system change, ORM migration) MUST run sequentially — never in a parallel wave.
+
+**Detection — a milestone is a migration if it:**
+- Changes `package.json` / `requirements.txt` / `Cargo.toml` / `go.mod` major versions
+- Rewrites import patterns across 10+ files
+- Changes a store/state pattern that all components consume
+- Upgrades a UI framework (React class→hooks, Svelte 4→5, Vue Options→Composition)
+- Switches a build tool (webpack→vite, setuptools→poetry)
+
+**Why:** Migrations are inherently cross-cutting. Every file depends on the pattern established by the first file migrated. Splitting a migration across agents produces inconsistent patterns that are harder to fix than doing it sequentially.
+
+### Rule Summary Table
+
+| # | Rule | Enforced by |
+|---|------|-------------|
+| 1 | Verification wave between batches | Orchestrator Step 5 |
+| 2 | 3–5 agents per wave (6 max) | Orchestrator Step 2 |
+| 3 | Wave 1 = smallest, most careful | Blueprint Task Classifier |
+| 4 | 15+ file milestones stay sequential | Problem Architect Team Spec |
+| 5 | Fresh context for Wave 3+ agents | Orchestrator Step 4 |
+| 6 | Same skills for all wave agents | Orchestrator Step 4 |
+| 7 | Migrations always sequential | Blueprint Task Classifier |
+
+---
+
 ## Ownership Map Cleanup
 
 After wave merge is complete:

package/templates/capabilities/shared/toolchain-gate.md

@@ -0,0 +1,326 @@
+# Toolchain Gate — Verify Before Ship
+
+This capability is loaded by the orchestrator, milestone-builder, and /setup.
+It defines how agents detect, install, and verify the project's toolchain — and how
+logs flow between agents as context for fix dispatches.
+
+---
+
+## Stack-to-Command Mapping
+
+The source of truth for every verification command. Agents never guess — they look up.
+
+| Stack signal | Quick verify (Tier 1) | Scoped test (Tier 2) | Full build (Tier 3) | Install deps | Install tool |
+|-------------|----------------------|---------------------|--------------------|--------------|----|
+| `Cargo.toml` | `cargo check 2>&1` | `cargo test {scope} 2>&1` | `cargo build 2>&1` | `cargo fetch` | `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh -s -- -y` |
+| `package.json` + TS | `npx tsc --noEmit 2>&1` | `npm test -- --testPathPattern={scope} 2>&1` | `npm run build 2>&1` | `npm install` | `curl -fsSL https://fnm.vercel.app/install \| bash && fnm install --lts` |
+| `package.json` (JS only) | `npx eslint src/ 2>&1 \|\| true` | `npm test 2>&1` | `npm run build 2>&1` | `npm install` | same as above |
+| `pyproject.toml` / `requirements.txt` | `python -m py_compile {files} 2>&1` | `python -m pytest {scope} -x 2>&1` | `python -m pytest 2>&1` | `pip install -r requirements.txt` or `pip install -e .` | `curl -fsSL https://pyenv.run \| bash` |
+| `go.mod` | `go vet ./... 2>&1` | `go test ./{scope}/... 2>&1` | `go build ./... 2>&1` | `go mod download` | `curl -fsSL https://go.dev/dl/ (manual)` |
+| `Gemfile` | `ruby -c {files} 2>&1` | `bundle exec rspec {scope} 2>&1` | `bundle exec rspec 2>&1` | `bundle install` | `curl -fsSL https://get.rvm.io \| bash` |
+| `pubspec.yaml` | `dart analyze 2>&1` | `dart test {scope} 2>&1` | `dart compile exe 2>&1` | `dart pub get` | manual |
+| `Makefile` (C/C++) | `make -n 2>&1` | `make test 2>&1` | `make 2>&1` | — | system package manager |
+| `*.sln` / `*.csproj` | `dotnet build --no-restore 2>&1` | `dotnet test {scope} 2>&1` | `dotnet build 2>&1` | `dotnet restore` | `winget install Microsoft.DotNet.SDK.8` |
+
+**Multi-stack projects:** If both `Cargo.toml` and `package.json` exist, chain: `cargo check && npx tsc --noEmit`.
+Store all applicable commands in the `Verify:` field, joined by `&&`.
+
+**Custom overrides:** If the project has a `Makefile` with a `check` target, or `package.json` has a `"check"` script, prefer those over the table above. Project conventions beat defaults.
+
+---
+
+## Toolchain Detection Protocol
+
+Run by env-scan.sh and /setup. Output determines the `Verify:` field in CLAUDE.md.
+
+### Step 1: Detect stack files
+```bash
+ls package.json Cargo.toml go.mod pyproject.toml requirements.txt Gemfile pubspec.yaml *.sln *.csproj Makefile 2>/dev/null
+```
+
+### Step 2: Check tool availability
+```bash
+# For each detected stack, check the runtime
+command -v node   2>/dev/null && node --version   || echo "node=missing"
+command -v cargo  2>/dev/null && cargo --version   || echo "cargo=missing"
+command -v python3 2>/dev/null && python3 --version || echo "python=missing"
+command -v go     2>/dev/null && go version         || echo "go=missing"
+command -v ruby   2>/dev/null && ruby --version     || echo "ruby=missing"
+command -v dotnet 2>/dev/null && dotnet --version   || echo "dotnet=missing"
+```
+
+### Step 3: Check dependencies installed
+```bash
+[ -d node_modules ] && echo "node_deps=installed" || echo "node_deps=missing"
+[ -d target ]       && echo "rust_deps=fetched"   || echo "rust_deps=missing"
+[ -d venv ] || [ -d .venv ] && echo "py_venv=found" || echo "py_venv=missing"
+[ -d vendor ]       && echo "vendor=found"         || echo "vendor=missing"
+```
+
+### Step 4: Check for custom verify scripts
+```bash
+# package.json custom scripts
+node -e "const p=require('./package.json'); console.log(p.scripts?.check || p.scripts?.typecheck || p.scripts?.lint || 'none')" 2>/dev/null
+# Makefile targets
+grep -q '^check:' Makefile 2>/dev/null && echo "makefile_check=true"
+```
+
+### Step 5: Compose verify command
+Use the mapping table + any custom overrides detected in Step 4.
+Write result to CLAUDE.md `Verify:` field.
+
+---
+
+## Toolchain Bootstrap Protocol
+
+Run by orchestrator before first dispatch, or by /setup at project init.
+
+### Mode: Interactive (/setup, /add, /fix)
+```
+1. Detect missing tools (Step 2 above)
+2. If missing: WARN user, ASK before installing
+   "cargo is not installed but Cargo.toml exists. Install Rust via rustup? (y/n)"
+3. If user says no → log: "Verification disabled for Rust — cargo not available"
+4. If user says yes → install, verify, continue
+5. Install dependencies if missing (npm install, cargo fetch, etc.)
+6. Run quick_verify once as smoke test
+```
+
+### Mode: Autonomous (/copilot)
+```
+1. Detect missing tools
+2. If missing AND installer available → install automatically
+   Log to .claude/logs/bootstrap.log
+3. If missing AND no installer → WARN in goals.md, continue without verification
+   "⚠ Verification degraded: {tool} not available. Agents will skip Tier 1 checks."
+4. Install dependencies
+5. Run quick_verify
+6. FAIL → fix before ANY agent dispatches (this IS the foundation)
+```
+
+### Bootstrap log
+All install output goes to `.claude/logs/bootstrap.log`:
+```bash
+{install_command} 2>&1 | tee .claude/logs/bootstrap.log
+```
+
+---
+
+## Verification Tiers
+
+### Tier 1: Static Verification (MANDATORY — every agent, every mode)
+
+**What:** Type-check, lint, or syntax-check without building or running tests.
+**Cost:** 2–30 seconds.
+**Catches:** Type errors, missing imports, syntax errors, undeclared variables.
+
+```bash
+# Agent runs this BEFORE reporting done
+{quick_verify_cmd} 2>&1 | tee .claude/logs/verify-log-M{N}.md
+```
+
+**Rules:**
+- If errors exist in YOUR files → fix them (counts as a self-correction attempt)
+- If errors exist in OTHER files → report but do NOT fix
+- If tool is not installed → skip with warning in verify log
+- MUST run even in worktree mode — the worktree has its own clean state
+
+### Tier 2: Scoped Test Verification (MANDATORY — every agent)
+
+**What:** Run tests scoped to the agent's files only.
+**Cost:** 10–60 seconds.
+**Catches:** Logic errors, regression, missing test coverage.
+
+```bash
+# Parallel mode: scoped to agent's directory
+{scoped_test_cmd} 2>&1 | tee -a .claude/logs/verify-log-M{N}.md
+
+# Sequential mode: full test suite
+{full_test_cmd} 2>&1 | tee -a .claude/logs/verify-log-M{N}.md
+```
+
+### Tier 3: Full Build Verification (verification waves only — NOT per-agent)
+
+**What:** Full compilation, bundling, linking.
+**Cost:** 30–300 seconds.
+**Catches:** Linking errors, bundle issues, cross-module type mismatches.
+
+```bash
+# Orchestrator runs this after merging ALL agents in a wave
+{full_build_cmd} 2>&1 | tee .claude/logs/build-wave{N}.log
+```
+
+**Tier 3 is NEVER run by individual agents.** It's too slow and in parallel mode it would verify a partial codebase.
+
+---
+
+## Log Protocol
+
+### Log directory structure
+
+```
+.claude/logs/
+├── bootstrap.log              ← Level 1: toolchain install output
+├── verify-log-M1A.md          ← Level 2: per-agent Tier 1+2 output
+├── verify-log-M1B.md
+├── verify-log-M2A.md
+├── runtime-M1A.log            ← runtime crash output (when agent runs the app)
+├── runtime-M2C.log
+├── build-wave1.log            ← post-merge full build (Tier 3)
+├── build-wave2.log
+├── integration-final.log      ← final integration test output
+└── session-summary.log        ← stop.js writes final tally
+```
+
+### Log Type 1: Verify Logs (per agent)
+
+Written by milestone-builder after running Tier 1+2. Format:
+
+```markdown
+## Verify Log — M{N}: {title}
+
+### Tier 1: Static ({command})
+Status: PASS | FAIL
+Errors: {count}
+Warnings: {count}
+{first 50 lines of output if errors or warnings}
+
+### Tier 2: Scoped Tests ({command})
+Status: PASS | FAIL
+Tests: {pass}/{total}, {failures} failures, {duration}
+{first 30 lines of output if failures}
+
+### Tier 3: Build
+Status: SKIPPED (per-agent — runs in verification wave only)
+
+### Self-Correction History
+Attempt 1: {what happened}
+  Fix: {what was changed}
+Attempt 2: {result}
+```
+
+### Log Type 2: Runtime Logs (crash capture)
+
+Written when an agent runs the application and it crashes. The agent captures stderr:
+
+```bash
+# Run app with timeout, capture all output, don't let crash stop execution
+timeout 15 {run_command} 2>&1 | tee .claude/logs/runtime-M{N}.log; exit 0
+```
+
+The `exit 0` prevents Claude Code from treating the crash as a Bash tool failure.
+The agent then reads the log and has full stack trace context to diagnose the issue.
+
+**When to capture runtime logs:**
+- Agent's milestone involves a new endpoint, route, or page → run the app briefly
+- Agent's milestone changes startup logic → run the app to verify it starts
+- Agent's milestone changes a background job → run it once to verify
+- Do NOT run the full app for every milestone — only when the milestone directly affects runtime behavior
+
+### Log Type 3: Build Logs (verification wave)
+
+Written by the orchestrator after merging all agents in a wave:
+
+```bash
+# After all Wave N branches merged:
+{full_build_cmd} 2>&1 | tee .claude/logs/build-wave{N}.log
+echo "EXIT=$?" >> .claude/logs/build-wave{N}.log
+```
+
+If the build fails, the orchestrator reads the log, identifies which file caused the error,
+traces it back to which agent's merge introduced it, and dispatches a fix agent.
+
+---
+
+## Log Relay — Logs as Context for Fix Agents
+
+**This is the key architectural insight: logs are not just records — they are inputs to future agents.**
+
+When the orchestrator dispatches a fix agent after a post-merge failure, it constructs the prompt from logs:
+
+```markdown
+## Fix Agent — Post-Wave {N} Build Failure
+
+### Build Log
+<build-log>
+{contents of .claude/logs/build-wave{N}.log — last 100 lines}
+</build-log>
+
+### Agent Verify Logs Summary
+{for each agent in this wave:}
+- M{A}: {PASS/FAIL} — {error count} errors, {warning count} warnings
+  {any warnings that look related to the build failure}
+
+### Runtime Logs (if any)
+{contents of .claude/logs/runtime-M{X}.log if it exists for this wave}
+
+### Diagnosis
+The build error at {file}:{line} was introduced by M{X}'s merge.
+M{X}'s verify log shows: {relevant warning or pass-despite-issue}
+The type mismatch suggests {analysis}.
+
+### Your Task
+Fix the errors in the build log. The verify logs and diagnosis above give you
+full context. Do NOT re-investigate — the logs tell the story.
+```
+
+**Rules for log relay:**
+- Include only the RELEVANT portion of each log (last 100 lines of build, relevant warnings from verify)
+- Never relay the full bootstrap.log — it's only useful for debugging install issues
+- Verify logs are small (< 2KB each) — safe to include in full
+- Build logs can be large — tail to last 100 lines
+- Runtime logs can be large — include only the stack trace (grep for "Error:", "panic:", "FATAL")
+
+---
+
+## CLAUDE.md Verify Field
+
+`/setup` writes this to the project's CLAUDE.md after running toolchain detection:
+
+```markdown
+## Verify
+Quick: {Tier 1 command}
+Test: {Tier 2 command}
+Build: {Tier 3 command}
+```
+
+Example for a Rust + Svelte project:
+```markdown
+## Verify
+Quick: cargo check && npx svelte-check
+Test: cargo test && npm test
+Build: cargo build --release && npm run build
+```
+
+Every agent reads this field. No agent guesses the verify command.
+If the field is missing → agent runs toolchain detection inline (slower but safe).
+
+---
+
+## Cleanup Protocol
+
+Logs accumulate across waves. Clean up after ship:
+
+```bash
+# After /ship completes successfully:
+mkdir -p .claude/logs/archive
+mv .claude/logs/*.log .claude/logs/*.md .claude/logs/archive/ 2>/dev/null
+echo "Archived $(date -u +%Y-%m-%dT%H:%M:%S)" > .claude/logs/archive/README.md
+```
+
+**Do NOT delete logs before ship** — they may be needed for fix agents.
+**Do NOT commit logs to git** — add `.claude/logs/` to `.gitignore`.
+
+---
+
+## Integration Points
+
+| Component | How it uses toolchain-gate |
+|-----------|--------------------------|
+| `/setup` | Runs detection protocol, writes `Verify:` to CLAUDE.md |
+| `env-scan.sh` | Outputs `toolchain` + `verify_cmd` in JSON |
+| `problem-architect` | Reads `Verify:` field, adds `Verify:` to Team Spec per milestone |
+| `milestone-builder` | Runs Tier 1+2 exit gate, writes verify-log, captures runtime logs |
+| `orchestrator` | Runs bootstrap, runs Tier 3 between waves, relays logs to fix agents |
+| `blueprint` | Includes toolchain check in Wave 0 foundation |
+| `.gitignore` | Must include `.claude/logs/` |

package/templates/commands/blueprint.md

@@ -160,9 +160,43 @@ echo "source_files=$SRC_COUNT"
 ```
 If source_files < 10 → greenfield project. Force Wave 1 = all foundation work (schema, config, shared utils, types) as a SINGLE milestone regardless of feature count. Parallel only unlocks from Wave 2 onward, after the foundation exists and greps have real files to scan.
 
+**Step 0b: Toolchain check (load `capabilities/shared/toolchain-gate.md`)**
+```bash
+# Check Verify field in CLAUDE.md
+grep -q "^Quick:" CLAUDE.md 2>/dev/null && echo "verify=configured" || echo "verify=missing"
+```
+If `verify=missing` → run toolchain detection protocol from toolchain-gate.md and write `## Verify` to CLAUDE.md.
+If tools are missing → warn in the plan: `"⚠ Toolchain gap: {tool} not installed. Agents cannot run Tier 1 verification. Run: {install command}"`
+
+Wave 0 (foundation) MUST include a toolchain bootstrap step:
+```
+## M0: Foundation — Toolchain + Schema + Shared Types
+- Install missing tools and dependencies
+- Run smoke test: {quick_verify_cmd}
+- Create shared types, base schemas, core config
+```
+
 **Step 1: List raw work items**
 From the intent/spec, enumerate ALL features, endpoints, models, UI pages, and background jobs as raw items. Do not group yet — just list everything the project needs.
 
+**Step 1b: Migration detection (before coupling analysis)**
+For each raw work item, check if it is a **migration or cross-cutting refactor**:
+- Framework/library upgrade (React class→hooks, Svelte 4→5, Vue Options→Composition, Angular versions)
+- Language version bump that changes syntax or stdlib APIs
+- Build tool change (webpack→vite, setuptools→poetry, Maven→Gradle)
+- Store/state management rewrite (Redux→Zustand, Vuex→Pinia, writable→runes)
+- ORM or database driver migration
+- Auth/middleware pattern rewrite
+
+**If detected → force SEQUENTIAL-ONLY.** Never split a migration across parallel agents.
+Mark the milestone: `Parallel: no (migration — SEQUENTIAL-ONLY)`.
+If the migration touches 15+ files, recommend sequential sub-milestones:
+```
+Sub-1: {foundation — sets the new pattern} → SEQUENTIAL-ONLY
+Sub-2: {consumers group A — follows pattern} → Depends: Sub-1
+Sub-3: {consumers group B — follows pattern} → Depends: Sub-2
+```
+
 **Step 2: Coupling analysis — merge rule**
 For each pair of raw work items, check if they share ANY of:
 - Same database table (both CREATE or ALTER the same table)
@@ -200,6 +234,14 @@ Wave 2 = milestones that only depend on Wave 1
 Wave N = milestones that only depend on waves 1..N-1
 ```
 
+**Wave 1 contract rule:** Wave 1 sets the types, APIs, schemas, and patterns for all later waves.
+- Wave 1 should be the **smallest, most carefully specified wave**
+- Wave 1 milestones define shared types, base schemas, core configs, foundational patterns
+- Wave 1 agents get 3 fix attempts (not 2) — errors here multiply across every later wave
+- Wave 1 MUST pass full build+test verification before Wave 2 dispatches
+- If Wave 1 introduces a new pattern → document it in `patterns.md` before Wave 2 dispatch
+- **Max agents in Wave 1:** 3 (even if more milestones are ready) — precision over speed
+
 **Step 2: Directory-level isolation check (Layer 1a)**
 
 For each wave with 2+ milestones:

package/templates/scripts/env-scan.sh

@@ -40,6 +40,40 @@ cat <<EOF
     "commands_count":      $(count_files .claude/commands 2>/dev/null),
     "agents_count":        $(count_files .claude/agents 2>/dev/null)
   },
+  "toolchain": {
+    "node":   { "installed": $(command -v node   >/dev/null 2>&1 && echo true || echo false), "version": "$(node --version 2>/dev/null || echo null)" },
+    "cargo":  { "installed": $(command -v cargo  >/dev/null 2>&1 && echo true || echo false), "version": "$(cargo --version 2>/dev/null | head -1 || echo null)" },
+    "python": { "installed": $(command -v python3 >/dev/null 2>&1 && echo true || echo false), "version": "$(python3 --version 2>/dev/null || echo null)" },
+    "go":     { "installed": $(command -v go     >/dev/null 2>&1 && echo true || echo false), "version": "$(go version 2>/dev/null || echo null)" },
+    "dotnet": { "installed": $(command -v dotnet >/dev/null 2>&1 && echo true || echo false), "version": "$(dotnet --version 2>/dev/null || echo null)" },
+    "ruby":   { "installed": $(command -v ruby   >/dev/null 2>&1 && echo true || echo false), "version": "$(ruby --version 2>/dev/null || echo null)" }
+  },
+  "deps": {
+    "node_modules": $(has_dir node_modules),
+    "target":       $(has_dir target),
+    "venv":         $([ -d venv ] || [ -d .venv ] && echo true || echo false),
+    "vendor":       $(has_dir vendor)
+  },
+  "verify_cmd": "$(
+    V=""
+    if [ -f Cargo.toml ]; then
+      command -v cargo >/dev/null 2>&1 && V="cargo check" || V="# cargo missing"
+    fi
+    if [ -f package.json ]; then
+      if command -v npx >/dev/null 2>&1; then
+        grep -q '"typescript"' package.json 2>/dev/null && V="${V:+$V && }npx tsc --noEmit" || V="${V:+$V && }npx eslint src/ || true"
+      else
+        V="${V:+$V && }# node missing"
+      fi
+    fi
+    if [ -f pyproject.toml ] || [ -f requirements.txt ]; then
+      command -v python3 >/dev/null 2>&1 && V="${V:+$V && }python3 -m py_compile" || V="${V:+$V && }# python missing"
+    fi
+    if [ -f go.mod ]; then
+      command -v go >/dev/null 2>&1 && V="${V:+$V && }go vet ./..." || V="${V:+$V && }# go missing"
+    fi
+    echo "${V:-echo no-stack-detected}"
+  )",
   "git_log": "$(git log --oneline -5 2>/dev/null | head -5 | tr '\n' '|' | sed 's/"/\\"/g' || echo 'none')",
   "readme_head": "$(head -10 README.md 2>/dev/null | tr '\n' '|' | sed 's/"/\\"/g' || echo 'none')"
 }

package/templates/visualizer/public/app.js

@@ -404,7 +404,7 @@
     if (event.event === 'SubagentStop') { feed.appendChild(createSessionMarker('Subagent Finished')); scrollToBottom(); return; }
 
     // Fallback
-    const card = createEventCard(event); feed.appendChild(card); scrollToBottom();
+    var fallbackCard = createEventCard(event); feed.appendChild(fallbackCard); scrollToBottom();
   }
 
   // SSE

package/templates/visualizer/server.js

@@ -198,7 +198,7 @@ function handleStatic(req, res) {
 
   fs.readFile(filePath, (err, data) => {
     if (err) { res.writeHead(404); res.end('Not found'); return; }
-    res.writeHead(200, { 'Content-Type': mime });
+    res.writeHead(200, { 'Content-Type': mime, 'Cache-Control': 'no-cache, no-store, must-revalidate' });
     res.end(data);
   });
 }