azclaude-copilot 0.5.9 → 0.6.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "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",
+      "version": "0.6.0",
       "source": {
         "source": "github",
         "repo": "haytamAroui/AZ-CLAUDE-COPILOT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "azclaude",
-  "version": "0.5.9",
+  "version": "0.6.0",
   "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",
   "author": {
     "name": "haytamAroui",

package/README.md

@@ -624,11 +624,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.
+1836 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: 1836 passed, 0 failed, 1836 total
 ```
 
 ---

package/package.json

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

package/templates/commands/parallel.md

@@ -115,7 +115,9 @@ This file survives context compaction. If the session dies mid-wave, the next se
 
 ---
 
-## Step 5: Dispatch All Agents Simultaneously
+## Step 5: Dispatch All Agents Simultaneously (DAG Mode)
+
+**Pre-read shared files** — read files referenced by 2+ agents (models, schemas, configs) and inject their content into each agent's prompt. This eliminates redundant file reads across agents.
 
 Spawn all milestone-builder agents **in a single message** (true parallel — one Task call per agent in the same response):
 
@@ -124,56 +126,60 @@ For each milestone, Task with `isolation: "worktree"`:
 ```
 Task: Implement Milestone {N} — {title}
 
-[PARALLEL MODE — WORKTREE ISOLATED]
+[PARALLEL MODE — WORKTREE ISOLATED — DAG DISPATCH]
 Branch: parallel/{milestone-slug}
+Test scope: {test-dir} — run ONLY these tests
 
 Agent role: {from Team Spec}
 Directories owned: {from Team Spec}
 
+## Pre-loaded Context (do NOT re-read these files)
+{content of shared files injected by orchestrator}
+
 {standard context from orchestrator Step 4}
 
 Worktree rules (MANDATORY):
 - Only write files within your "Directories owned"
 - DO NOT run git push — commit locally only
+- Run ONLY tests in your Test scope — not the full suite
 - If you see errors in files outside your directories: STOP, report "scope violation"
 - End your report with: "Branch: parallel/{slug}"
 ```
 
+**Max parallel agents:** 6 (default). Test-only milestones don't count toward the limit.
+
 ---
 
-## Step 6: Wait and Monitor
+## Step 6: Merge-on-Complete + Monitor
 
-After all agents complete:
-- Collect all completion reports
-- Mark each as COMPLETE or FAILED in ownership.md
-- **Update `.claude/parallel-wave-state.md`** — set each milestone's Status to `done`/`failed`, fill Commit hash
+**Default (DAG mode, max_parallel > 3):** As each agent reports done, merge immediately:
+1. `git checkout main && git merge parallel/{slug} --no-ff`
+2. Run scoped tests for the merged module
+3. Update ownership.md and `.claude/parallel-wave-state.md` (status → `done`, fill commit hash)
+4. **Check DAG for newly-unblocked milestones** → dispatch them immediately (back to Step 3)
 
----
+**Fallback (max_parallel <= 3 or merge conflict):** Wait for all, then merge sequentially.
 
-## Step 7: Merge Sequentially
+Mark FAILED agents as `blocked` in plan.md — do NOT hold up other agents.
 
-Follow the Merge Protocol from `capabilities/shared/parallel-coordination.md`:
+---
 
-```bash
-git checkout main
+## Step 7: Final Verification + Push
 
-# Merge branches one at a time (simplest first)
-git merge parallel/{slug-1} --no-ff -m "merge: M{N} {title} [parallel wave]"
-# Run tests after each merge
-{test command} 2>&1 | tail -10
+After all agents in this dispatch have completed and been merged:
 
-git merge parallel/{slug-2} --no-ff -m "merge: M{N} {title} [parallel wave]"
-{test command} 2>&1 | tail -10
+```bash
+# Run full test suite on merged main (covers cross-module interactions)
+{test command} 2>&1 | tail -20
 
-# Push once all merges pass
+# If all pass → push
 git push origin main
 
-# Cleanup
-git branch -d parallel/{slug-1} parallel/{slug-2}
+# Clean up any remaining worktree branches
+git branch -d parallel/{slug-1} parallel/{slug-2} 2>/dev/null
 ```
 
-**If merge conflict**: read both versions, apply correct merge (keep both feature additions), continue.
-**If tests fail after a merge**: identify which merge broke it → revert that branch → add milestone to blocked.
+**If full suite fails**: identify which merge introduced the break → revert that branch → add to blocked.
 
 ---
 

package/templates/commands/tasks.md

@@ -70,12 +70,12 @@ Check file collisions:
 
 ---
 
-## Step 4: Identify Parallel Groups
+## Step 4: Identify Parallel Groups (DAG Analysis)
 
 Tasks with no dependencies between them AND no file collisions can run in parallel.
-Group them into "waves":
+Group them into "waves" for visualization (the orchestrator uses the DAG directly, not wave numbers):
 
-**Wave = a set of tasks that can all run simultaneously**
+**Wave = a set of tasks that can all run simultaneously (informational grouping)**
 
 Algorithm:
 1. Wave 1 = tasks with no `Depends:` and status `pending`
@@ -83,6 +83,8 @@ Algorithm:
 3. Wave N = tasks that only depend on tasks in waves 1 through N-1
 4. A wave cannot contain tasks that share files
 
+**DAG dispatch note:** The orchestrator dispatches based on `Depends:` satisfaction, not wave numbers. A task in "Wave 3" may launch as soon as its specific dependencies are done — it does NOT wait for all of Wave 2.
+
 ---
 
 ## Step 5: Output the Task Graph
@@ -119,14 +121,15 @@ Total tasks: {N}  |  Done: {N}  |  Pending: {N}  |  Blocked: {N}
 ```
 Parallelism Analysis
 ════════════════════
-Max parallel at once: {N tasks in largest wave}
+Max parallel at once: {N tasks in largest wave} (default limit: 6)
 Critical path length: {N waves minimum to complete}
 File collision pairs: {N pairs that cannot run simultaneously}
+DAG dispatch mode: merge-on-complete (agents unblock dependents immediately)
 
 Suggested dispatch order for /copilot:
-  1. Start Wave 1 tasks simultaneously (or sequentially if no orchestrator)
-  2. On Wave 1 complete → start Wave 2
-  3. ...
+  1. Foundation first (shared files: models, schemas) — sequential
+  2. Launch all ready tasks simultaneously (DAG readiness, not wave number)
+  3. As each task completes → merge → check for newly-unblocked → dispatch immediately
 ```
 
 ---
@@ -134,10 +137,10 @@ Suggested dispatch order for /copilot:
 ## Copilot Mode Integration
 
 If `.claude/agents/orchestrator.md` exists:
-→ Note: "The orchestrator will use this graph to dispatch milestone-builder agents in parallel"
+→ Note: "The orchestrator uses DAG dispatch — each milestone launches when its Depends: are satisfied, with merge-on-complete to unblock dependents immediately"
 
 If no orchestrator:
-→ Note: "Copilot will process waves sequentially — Wave 1 first, then Wave 2, etc."
+→ Note: "Copilot will process tasks by wave grouping — Wave 1 first, then Wave 2, etc."
 
 ---