azclaude-copilot 0.5.9 → 0.7.0

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 39 commands, 10 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.5.9",
+      "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.0",
       "source": {
         "source": "github",
         "repo": "haytamAroui/AZ-CLAUDE-COPILOT",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "azclaude",
-  "version": "0.5.9",
-  "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 39 commands, 10 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.7.0",
+  "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",
     "url": "https://github.com/haytamAroui"

package/README.md

@@ -40,7 +40,7 @@ Repeats the same mistakes.            antipatterns.md prevents known failures.
 Forgets what was decided.             decisions.md logs every architecture choice.
 Loses reasoning mid-session.          /snapshot saves WHY — auto-injected next session.
 Can't work autonomously.              /copilot builds, tests, commits, ships — unattended.
-Agents run serially, one at a time.   Task Classifier + parallel waves run agents simultaneously.
+Agents run serially, one at a time.   DAG dispatch + merge-on-complete runs 6 agents simultaneously.
 ```
 
 One install. Any stack. Zero dependencies.
@@ -110,7 +110,7 @@ npx azclaude-copilot@latest
 
 One command, no flags. Auto-detects whether this is a fresh install or an upgrade:
 
-- **First time** → full install (39 commands, 4 hooks, 15 agents, 10 skills, memory, reflexes). Creates folders, instructions, and hooks — **no manual setup required.**
+- **First time** → full install (40 commands, 5 hooks, 15 agents, 10 skills, memory, reflexes). Creates folders, instructions, and hooks — **no manual setup required.**
 - **Already installed, older version** → auto-upgrades everything to latest templates
 - **Already up to date** → verifies, no overwrites
 
@@ -123,7 +123,7 @@ npx azclaude-copilot@latest doctor   # 32 checks — verify everything is wired
 
 ## What You Get
 
-**39 commands** · **10 auto-invoked skills** · **15 agents** · **4 hooks** · **memory across sessions** · **learned reflexes** · **self-evolving environment**
+**40 commands** · **10 auto-invoked skills** · **15 agents** · **5 hooks** · **memory across sessions** · **learned reflexes** · **self-evolving environment**
 
 ```
 .claude/
@@ -272,7 +272,7 @@ Claude Code
   │   └── stop.js         → Session cleanup, friction logging
   │
   └── Markdown files (capability — Claude reads natively, zero overhead)
-      ├── 39 commands     → Claude reads the .md, follows instructions
+      ├── 40 commands     → Claude reads the .md, follows instructions
       ├── 15 agents       → Claude spawns as subagents with Task tool
       ├── 10 skills       → Auto-invoked when relevant context detected
       ├── 48 capabilities → Lazy-loaded via manifest.md (~100 tokens overhead)
@@ -357,19 +357,19 @@ Never writes code     Never implements
 
 ## Parallel Execution
 
-AZCLAUDE runs multiple Claude Code agents simultaneously — without file corruption or test interference. Each agent works in an isolated git worktree on its own branch.
+AZCLAUDE runs up to 6 Claude Code agents simultaneously using **DAG-based dispatch** — each milestone launches the moment its dependencies are satisfied, not when an entire wave completes. Merge-on-complete means finished agents unblock dependents immediately.
 
 ```
-M1 (schema) → done
-                 ↓
-    ┌────────────┬────────────┬────────────┬──────────────┐
-    M2 (auth)   M3 (profile) M4 (email)   M5 (dashboard)   ← all run simultaneously
-    └────────────┴────────────┴────────────┴──────────────┘
-                 ↓
-              M6 (E2E tests)
+M0 (foundation) → done                          ← auto-detected shared files
+                     ↓
+    ┌────────────┬────────────┬────────────┬────────────┬────────────┬──────────────┐
+    M1 (auth)   M2 (profile) M3 (email)   M4 (tests)  M5 (NIST)   M6 (dashboard)
+    └���────┬──────┴────────────┴─────┬──────┴────────────┴────────────┴──────────────┘
+          ↓                         ↓                    ← merge-on-complete: M1 done → M7 starts
+    M7 (API routes)           M8 (integration)             immediately, doesn't wait for M2-M6
 ```
 
-3 sequential waves instead of 6 sequential milestones. Same output, fraction of the time.
+DAG dispatch instead of sequential waves. Same output, ~50% faster wall clock.
 
 ### Real case — ShopFlow e-commerce sprint
 
@@ -410,13 +410,26 @@ What the classifier caught: M1 and M2 were separate plan milestones but both wro
 
 **On tokens:** You will notice the token counts look large. You would spend the same tokens building this sequentially — the work is identical. What changes is wall-clock time. Sequential execution: each agent waits for the previous one to finish → ~2 hours. Parallel waves: agents run simultaneously → ~15 minutes. Same total tokens. Same output. One-eighth the time.
 
-### Four-layer safety model
+### v0.6.0: What changed in parallel execution
+
+| Before (wave-based) | After (DAG-based) |
+|---------------------|-------------------|
+| Wave 2 waits for ALL of Wave 1 | Each milestone launches when its `Depends:` are satisfied |
+| Max 3 agents at once | Max 6 agents (test-only agents uncapped) |
+| Manual Wave 0 for shared files | Auto-foundation detection extracts shared-file edits |
+| Agents re-read shared files independently | Pre-read injection: shared files read once, injected inline |
+| Agents run full test suite | Scoped tests: each agent runs only its module's tests |
+| Merge after entire wave completes | Merge-on-complete: each branch merges immediately, unblocks dependents |
+| Context loss kills the wave | Wave state file survives compaction, auto-resumes on next session |
+
+### Five-layer safety model
 
 Parallel execution is safe only when agents don't write to the same files. The key insight: **Layer 0 makes conflicts impossible by design** before any safety checking begins.
 
 | Layer | When | What |
 |-------|------|------|
 | **0 — Task Classifier** | `/blueprint`, before milestones exist | Groups coupled work into single milestones. Conflicts become impossible by construction. |
+| **0b — Foundation Detection** | Before dispatch | Auto-detects shared files (models, schemas) → sequential Wave 0 before any parallel agents |
 | **1 — Directory + import check** | `/blueprint`, post-plan | Fast grep: same dirs? shared utility imports? |
 | **2 — problem-architect file scan** | Post-plan, per milestone | Returns exact `Files Written:` paths + `Parallel Safe: YES/NO` |
 | **3 — Orchestrator dispatch gate** | Runtime, final | Overlap check before spawning. Cannot be bypassed. |
@@ -427,12 +440,12 @@ Claude Code's `isolation: "worktree"` in the Task tool is a raw primitive — li
 
 | Without AZCLAUDE | With AZCLAUDE |
 |------------------|---------------|
-| Which tasks to parallelize? | **Task Classifier** — groups coupled work, splits independent work |
-| Is it safe to parallelize? | **Four-layer safety** — classifier + dir check + file scan + dispatch gate |
-| What context does each agent need? | **Problem-Architect** — builds full Team Spec per milestone |
+| Which tasks to parallelize? | **Task Classifier + DAG dispatch** — groups coupled work, launches on dependency satisfaction |
+| Is it safe to parallelize? | **Five-layer safety** — classifier + foundation + dir check + file scan + dispatch gate |
+| What context does each agent need? | **Problem-Architect** — Team Spec + pre-read injection (shared files read once) |
 | What conventions to follow? | **patterns.md / antipatterns.md** — injected automatically |
-| What if one agent fails? | **Blocker recovery + /debate escalation** |
-| What happens when the session ends? | **goals.md + checkpoints + plan.md** — resumes exactly |
+| What if one agent fails? | **Blocker recovery + /debate escalation** (other agents continue) |
+| What happens when the session ends? | **DAG state file + checkpoints** — auto-resumes interrupted waves |
 | How do we improve over time? | **/evolve** — new agents from git evidence every 3 milestones |
 
 **Claude Code is the engine. AZCLAUDE is the transmission, the steering, and the GPS — the system that makes those cylinders produce coordinated forward motion instead of random spinning.**
@@ -624,11 +637,11 @@ AZCLAUDE is a lazy-loaded environment of 48 capability modules. It only loads wh
 
 ## Verified
 
-1810 tests. Every template, command, capability, agent, hook, and CLI feature verified.
+1868 tests. Every template, command, capability, agent, hook, and CLI feature verified.
 
 ```bash
 bash tests/test-features.sh
-# Results: 1810 passed, 0 failed, 1810 total
+# Results: 1868 passed, 0 failed, 1868 total
 ```
 
 ---

package/bin/cli.js

@@ -8,7 +8,7 @@ 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', 'mcp', 'verify', 'inoculate', 'ghost-test'];
+const EXTENDED_COMMANDS = ['dream', 'refactor', 'doc', 'loop', 'migrate', 'deps', 'find', 'create', 'reflect', 'hookify', 'sentinel', 'clarify', 'spec', 'analyze', 'constitute', 'tasks', 'issues', 'driven', 'mcp', 'verify', 'inoculate', 'ghost-test', 'visualize'];
 const ADVANCED_COMMANDS = ['evolve', 'debate', 'level-up', 'copilot', 'reflexes', 'parallel'];
 const COMMANDS          = [...CORE_COMMANDS, ...EXTENDED_COMMANDS, ...ADVANCED_COMMANDS];
 
@@ -118,7 +118,7 @@ function substitutePaths(content, cfg) {
 
 // ─── Hook Scripts ─────────────────────────────────────────────────────────────
 
-const HOOK_SCRIPTS = ['user-prompt.js', 'stop.js', 'post-tool-use.js', 'pre-tool-use.js'];
+const HOOK_SCRIPTS = ['user-prompt.js', 'stop.js', 'post-tool-use.js', 'pre-tool-use.js', 'visualizer-hook.js'];
 
 function copyHookScripts(dstDir) {
   fs.mkdirSync(dstDir, { recursive: true });
@@ -140,11 +140,15 @@ function buildHookEntries(scriptsDir) {
   const stopScript        = path.join(scriptsDir, 'stop.js');
   const postToolUseScript = path.join(scriptsDir, 'post-tool-use.js');
   const preToolUseScript  = path.join(scriptsDir, 'pre-tool-use.js');
+  const vizScript = path.join(scriptsDir, 'visualizer-hook.js');
   return {
     UserPromptSubmit: [{ matcher: '',                           hooks: [{ type: 'command', command: `"${nodeExe}" "${userPromptScript}"` }]  }],
     Stop:             [{ matcher: '',                           hooks: [{ type: 'command', command: `"${nodeExe}" "${stopScript}"` }]         }],
     PreToolUse:       [{ matcher: 'Write|Edit|MultiEdit',      hooks: [{ type: 'command', command: `"${nodeExe}" "${preToolUseScript}"` }]  }],
     PostToolUse:      [{ matcher: 'Write|Edit|Read|Bash|Grep', hooks: [{ type: 'command', command: `"${nodeExe}" "${postToolUseScript}"` }] }],
+    Notification:     [{ matcher: '',                           hooks: [{ type: 'command', command: `"${nodeExe}" "${vizScript}"` }]         }],
+    SubagentStart:    [{ matcher: '',                           hooks: [{ type: 'command', command: `"${nodeExe}" "${vizScript}"` }]         }],
+    SubagentStop:     [{ matcher: '',                           hooks: [{ type: 'command', command: `"${nodeExe}" "${vizScript}"` }]         }],
   };
 }
 
@@ -441,6 +445,23 @@ function installScripts(projectDir, cfg) {
   ok(`Scripts installed/updated (${cfg}/scripts/)`);
 }
 
+// ─── Visualizer (real-time pipeline dashboard) ──────────────────────────────
+
+function installVisualizer(projectDir, cfg) {
+  const src = path.join(TEMPLATE_DIR, 'visualizer');
+  if (!fs.existsSync(src)) return;
+  const dst = path.join(projectDir, cfg, 'visualizer');
+  if (fs.existsSync(dst)) {
+    // Refresh files
+    copyDir(src, dst);
+    info('Visualizer files refreshed');
+    return;
+  }
+  fs.mkdirSync(dst, { recursive: true });
+  copyDir(src, dst);
+  ok(`Visualizer installed (${cfg}/visualizer/) — start with: AZCLAUDE_VISUALIZER=8765 node ${cfg}/visualizer/server.js`);
+}
+
 // ─── Statusline (auto-updating cost/context bar) ─────────────────────────────
 
 function installStatusline(projectDir, cfg) {
@@ -1116,6 +1137,42 @@ function copyDir(src, dst) {
 if (process.argv[2] === 'doctor' && process.argv[3] === '--audit') { runAudit(); process.exit(0); }
 if (process.argv[2] === 'doctor') { runDoctor(); process.exit(0); }
 if (process.argv[2] === 'demo')   { runDemo();   process.exit(0); }
+if (process.argv[2] === 'visualize') {
+  const action = process.argv[3] || 'start';
+  const detectedCli = detectCLI();
+  const vizCfg = detectedCli.cfg;
+  const serverPath = path.join(process.cwd(), vizCfg, 'visualizer', 'server.js');
+  if (!fs.existsSync(serverPath)) {
+    console.error('Visualizer not installed. Run: npx azclaude-copilot');
+    process.exit(1);
+  }
+  if (action === 'stop') {
+    const pidFile = path.join(os.tmpdir(), '.azclaude-visualizer.pid');
+    if (fs.existsSync(pidFile)) {
+      const pid = parseInt(fs.readFileSync(pidFile, 'utf8'), 10);
+      try { process.kill(pid); } catch (_) {}
+      try { fs.unlinkSync(pidFile); } catch (_) {}
+      ok('Visualizer stopped');
+    } else {
+      info('No running visualizer found');
+    }
+  } else {
+    const port = process.argv[4] || '8765';
+    const { spawn } = require('child_process');
+    const child = spawn(process.execPath, [serverPath], {
+      detached: true, stdio: 'ignore',
+      env: Object.assign({}, process.env, { AZCLAUDE_VISUALIZER: port })
+    });
+    child.unref();
+    const pidFile = path.join(os.tmpdir(), '.azclaude-visualizer.pid');
+    fs.writeFileSync(pidFile, String(child.pid));
+    ok(`Visualizer started on port ${port} (PID: ${child.pid})`);
+    info(`Open: http://localhost:${port}`);
+    info(`Set env: AZCLAUDE_VISUALIZER=${port}`);
+  }
+  process.exit(0);
+}
+
 if (process.argv[2] === 'copilot') {
   // Delegate to copilot runner
   const copilotScript = path.join(__dirname, 'copilot.js');
@@ -1182,6 +1239,7 @@ installCapabilities(projectDir, cli.cfg, fullInstall);
 installCommands(projectDir, cli.cfg);
 installSkills(projectDir, cli.cfg);
 installScripts(projectDir, cli.cfg);
+installVisualizer(projectDir, cli.cfg);
 installStatusline(projectDir, cli.cfg);
 installAgents(projectDir, cli.cfg);
 installRulesFile(projectDir, cli.cfg, cli.rulesFile);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "azclaude-copilot",
-  "version": "0.5.9",
-  "description": "AI coding environment — 39 commands, 10 skills, 15 agents, memory, reflexes, evolution. Install: npx azclaude-copilot@latest, then open Claude Code.",
+  "version": "0.7.0",
+  "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",
     "azclaude-copilot": "bin/copilot.js"

package/templates/agents/orchestrator.md

@@ -55,23 +55,51 @@ Follow the Resume Protocol from `capabilities/shared/parallel-coordination.md`:
 
 ---
 
-### Step 2: Select Next Milestone Wave
+### Step 2: Select Next Milestones (DAG Dispatch)
+
+**DAG readiness check** — a milestone is **ready** when:
+1. `status = pending` in plan.md
+2. ALL milestones listed in its `Depends:` field have `status = done`
+
+That's it. Ignore `Wave:` fields for dispatch decisions — they are informational (for visualization and estimation only). The dependency graph is the truth.
 
-**If plan.md has `Wave:` fields** (blueprint wrote them — read directly):
 ```bash
-grep "Wave:" .claude/plan.md
+# Find all ready milestones
+grep -B2 "Status: pending" .claude/plan.md | grep "^## M"
+# For each, check its Depends: are all done
+```
+
+**Step 2a: Foundation Detection (auto-Wave 0)**
+
+Before dispatching any parallel agents, scan ALL ready milestones' Team Specs for shared files:
+
 ```
-Find the lowest wave number where all milestones have `status = pending` and all `Depends:` are `done`.
-This is the next wave to dispatch.
+For each pair (A, B) in ready milestones:
+  shared_files = Files Written(A) ∩ Files Written(B)
+  If shared_files is not empty:
+    → Extract shared file edits into a FOUNDATION milestone
+    → Dispatch foundation sequentially FIRST
+    → Remove shared-file edits from A and B's scope
+    → Re-check readiness after foundation completes
+```
+
+If no shared files → skip foundation, go directly to parallel dispatch.
+
+**Step 2b: Parallel safety check**
 
-**If plan.md has NO `Wave:` fields** (older plan format — compute from scratch):
-Find milestones where `status = pending` AND all dependencies have `status = done`.
+From the ready set (after foundation), verify `Files Written` from problem-architect for each pair don't overlap. `Files Written` is more precise than `Files:` — use it.
+If any two candidates share a written file → dispatch the conflicting one sequentially after the other.
 
-**Parallel candidates:** milestones in the same wave with `Parallel: yes` (or computed as independent).
+**Step 2c: Classify milestones**
 
-**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.
+| Type | Definition | Dispatch rule |
+|------|-----------|---------------|
+| Foundation | Touches files needed by 2+ milestones | Sequential, before all others |
+| Test-only | Creates new test files, never writes production code | Safe alongside ANY milestone |
+| Standard | Writes to unique files | Parallel with worktree isolation |
+
+**Max parallel agents:** 6 (default). Override with `max_parallel` in plan.md frontmatter.
+If ready milestones exceed max_parallel → dispatch highest-priority first, queue the rest.
 
 - All done → SHIP
 - All remaining blocked → BLOCKER RECOVERY
@@ -123,16 +151,19 @@ 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):**
+**Parallel dispatch (2+ ready milestones with disjoint Files Written):**
 
 Load `capabilities/shared/parallel-coordination.md` first.
 Load `capabilities/shared/context-inoculation.md` and prepend its Required Preamble to every agent prompt below.
 
-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
+1. Write `.claude/ownership.md` table (branch, directories, status) for every agent in this batch
+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 inject their content inline into each agent's prompt — eliminates redundant file reads across agents
+4. 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)
+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)
 
 **Sequential dispatch (single milestone OR overlapping files):**
 
@@ -173,13 +204,18 @@ Dependent milestones, overlapping `Files Written`, or `Parallel Safe: NO` → sp
 
 ---
 
-### Step 5: Monitor Results
+### Step 5: Monitor Results + Merge-on-Complete
+
+**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
 
-**PASS:**
+**When an agent reports PASS (sequential mode):**
 - Approve commit
 - Update plan.md status → `done`
-- New pattern emerged? → append to patterns.md
-- Compromise made? → append to antipatterns.md
 
 **FAIL — attempt 1:**
 - Read exact error
@@ -190,6 +226,11 @@ Dependent milestones, overlapping `Files Written`, or `Parallel Safe: NO` → sp
 - Log to blockers.md with full context
 - Set plan.md status → `blocked`
 - Move to next milestone
+- In parallel mode: do NOT block other agents — continue merging completed branches
+
+**Merge conflict during merge-on-complete:**
+- Read both versions, apply correct merge (keep both feature additions)
+- If unresolvable: fall back to batch-merge for remaining agents in this dispatch
 
 ---
 

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

@@ -40,26 +40,35 @@ Rules:
 
 ---
 
-## Dispatch Protocol (Orchestrator)
+## Dispatch Protocol (DAG-Based)
 
-### Step 1: Confirm Parallel Safety
+### Step 1: Build Dependency Graph + Confirm Parallel Safety
 
-Before spawning any parallel agents for a wave, verify from problem-architect Team Specs:
+Parse `plan.md` into a DAG. A milestone is **ready** when all its `Depends:` have `status = done`.
+
+Before spawning any parallel agents, verify from problem-architect Team Specs:
 
 ```
-For each pair (A, B) in the wave:
+For each pair (A, B) in ready milestones:
   - 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
+If any check fails → remove the conflicting milestone from parallel batch, dispatch sequentially after
 ```
 
 ### Step 2: Write Ownership Map
 
 Write `.claude/ownership.md` before spawning any agents.
 
+### Step 2b: Foundation Detection (Auto-Wave 0)
+
+Scan all ready milestones for shared-file bottlenecks:
+- If 2+ milestones need to write the same file → extract those changes into a foundation milestone
+- Dispatch foundation sequentially FIRST, before any parallel agents
+- After foundation completes: re-check readiness (more milestones may now be ready)
+
 ### Step 3: Dispatch with Worktree Isolation
 
 Spawn each agent via Task with `isolation: "worktree"`:
@@ -69,9 +78,13 @@ Task: Implement Milestone {N} — {title}
 
 [worktree mode]
 Branch: parallel/{milestone-slug}
+Test scope: {test-dir} — run ONLY these tests, not the full suite
 Do NOT push to origin. Commit locally only.
 Report branch name in completion message.
 
+## Pre-loaded Context (do NOT re-read these files)
+{orchestrator pre-reads shared files and injects content here}
+
 {standard milestone context from orchestrator Step 4}
 ```
 
@@ -79,50 +92,74 @@ 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
+- Run ONLY tests in your Test scope — not the full suite
 - 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
+**Max parallel agents:** 6 (default). Test-only milestones do NOT count toward the limit.
+
+### Step 4: Merge-on-Complete (Default) or Batch-Merge (Fallback)
+
+**Merge-on-complete (default when max_parallel > 3):**
+As each agent reports `COMPLETE`, merge immediately:
+1. `git checkout main && git merge parallel/{slug} --no-ff -m "merge: M{N} {title} [dag]"`
+2. Run scoped tests: `{test command} tests/{scope}/ 2>&1 | tail -10`
+3. Update plan.md status → `done`, update DAG state file
+4. **Check DAG for newly-unblocked milestones** → dispatch them immediately (back to Step 1)
+5. Clean up branch: `git branch -d parallel/{slug}`
+
+**Batch-merge fallback (max_parallel <= 3 OR merge conflict detected):**
+Wait for ALL dispatched agents to complete, then merge sequentially (simplest first).
 
-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
+When agent reports `FAILED`:
+- Do NOT block other agents — continue merging completed branches
+- Log failure to blockers.md, set plan.md status → `blocked`
 
 ---
 
 ## Merge Protocol (Orchestrator)
 
-After all parallel agents report done, merge sequentially:
+Two modes, selected automatically based on `max_parallel` and conflict state:
+
+### Mode A: Merge-on-Complete (default, max_parallel > 3)
+
+Each agent's branch is merged as soon as it completes — no waiting for others:
 
 ```bash
-# Step 1: Return to main branch
-git checkout main  # or master / development
+# Agent M3 reports COMPLETE:
+git checkout main
+git merge parallel/m3-auth --no-ff -m "merge: M3 auth endpoints [dag]"
+{test command} tests/auth/ 2>&1 | tail -10  # scoped test only
+git branch -d parallel/m3-auth
+
+# Check DAG: M5 depends on M3 → M5 is now ready → dispatch M5 immediately
+# Meanwhile M4 is still running in its worktree — no interference
+```
 
-# 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]"
+**After all agents in batch complete:** run full test suite once on merged main.
+If full suite passes → `git push origin main`.
 
-# 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
+### Mode B: Batch-Merge (fallback, max_parallel <= 3 or conflict detected)
 
-# Step 4: Run full test suite on merged main
-npm test 2>&1 | tail -20
+Wait for ALL dispatched agents, then merge sequentially:
 
-# Step 5: If tests pass → push
+```bash
+git checkout main
+git merge parallel/m3-auth --no-ff -m "merge: M3 auth endpoints [dag]"
+git merge parallel/m4-profile --no-ff -m "merge: M4 user profile [dag]"
+{test command} 2>&1 | tail -20  # full suite after all merges
 git push origin main
-
-# Step 6: Clean up worktree branches
-git branch -d parallel/m3-auth parallel/m4-profile parallel/m5-email
+git branch -d parallel/m3-auth parallel/m4-profile
 ```
 
-**Merge order matters**: merge the branch with the fewest cross-dependencies first.
-When uncertain: sort by `Estimated Complexity` ascending (simpler merges first).
+### Merge Rules (both modes)
+
+- **Merge order**: simplest milestone first (sort by `Estimated Complexity` ascending)
+- **If merge conflict**: read both versions, apply correct merge (keep both feature additions)
+- **If conflict is unresolvable**: switch from Mode A to Mode B for remaining branches
+- **If tests fail after merge**: identify which merge broke it → revert that branch → add to blocked
 
 ---
 
@@ -134,7 +171,7 @@ These rules are injected by orchestrator into every parallel milestone-builder p
 
 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 .`
+3. **Test in isolation** — run ONLY the tests in your `Test scope` (injected by orchestrator). Example: `pytest tests/auth/ -v` not `pytest .`. Cross-cutting failures are expected from other agents' work.
 
 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."
 
@@ -240,17 +277,18 @@ During parallel execution, the orchestrator writes `.claude/parallel-wave-state.
 
 ```markdown
 ---
-wave: {N}
+dispatch_mode: dag
 started: {ISO timestamp}
 status: in-flight
+max_parallel: 6
 milestones: [M3, M4, M5]
 ---
 
-| Milestone | Branch | Status | Commit | Notes |
-|-----------|--------|--------|--------|-------|
-| M3 — Auth endpoints | parallel/m3-auth | running | — | P1 slot |
-| M4 — User profile | parallel/m4-profile | done | a1b2c3d | merged to worktree |
-| M5 — Email service | parallel/m5-email | failed | — | timeout on test suite |
+| Milestone | Branch | Status | Commit | Depends | Unblocks |
+|-----------|--------|--------|--------|---------|----------|
+| M3 — Auth endpoints | parallel/m3-auth | running | — | [M0] | [M5, M6] |
+| M4 — User profile | parallel/m4-profile | done | a1b2c3d | [M0] | [] |
+| M5 — Email service | parallel/m5-email | failed | — | [M3] | [M7] |
 ```
 
 ### Lifecycle

package/templates/commands/blueprint.md

@@ -229,7 +229,7 @@ runs after plan.md is written and handles the cases Layer 1 misses.
 - 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}
+- Wave:     {N} (informational — orchestrator uses Depends: for dispatch, not Wave:)
 ```
 
 A well-designed plan for a 6-feature product: