azclaude-copilot 0.4.1 → 0.4.3

package/README.md

@@ -21,7 +21,7 @@
 
 ## What is AZCLAUDE?
 
-An AI coding environment you install into any project. It gives Claude Code (or Gemini CLI, Codex, OpenCode, Cursor) **26 commands, 8 auto-invoked skills, 7 agents, memory across sessions, learned reflexes, and self-evolving infrastructure**.
+An AI coding environment you install into any project. It gives Claude Code (or Gemini CLI, Codex, OpenCode, Cursor) **26 commands, 8 auto-invoked skills, 10 agents, memory across sessions, learned reflexes, and self-evolving infrastructure**.
 
 Zero dependencies. One install. Works on any stack.
 
@@ -115,13 +115,21 @@ npx azclaude-copilot .              # resume existing copilot run
 |  Restarts Claude Code sessions until COPILOT_COMPLETE.    |
 |  Reads nothing. Decides nothing. Just loops.              |
 +-----------------------------------------------------------+
-|  LAYER 2: THE BRAIN (AZCLAUDE inside each session)        |
+|  LAYER 2: THE TEAM (intelligent copilot, v0.4+)           |
+|  Orchestrator: reads plan.md, consults architect,         |
+|  dispatches builders, monitors results, triggers /evolve  |
+|  Problem-Architect: analyzes each milestone before work   |
+|  (Team Spec: agents, skills, files, risks, complexity)    |
+|  Milestone-Builder: pre-reads, implements, verifies,      |
+|  self-corrects, commits, reports back                     |
++-----------------------------------------------------------+
+|  LAYER 3: THE BRAIN (all commands, every session)         |
 |  Reads goals.md, plan.md, checkpoint, patterns,           |
 |  blockers, decisions, reflexes, context artifacts          |
-|  Decides what to do next. Builds. Tests. Commits.         |
-|  Updates all state files before session ends.             |
+|  intelligent-dispatch: pre-flight before /add /fix        |
+|  /dream /audit /refactor /ship — no more blind jumps      |
 +-----------------------------------------------------------+
-|  LAYER 3: THE ENVIRONMENT (accumulates across sessions)   |
+|  LAYER 4: THE ENVIRONMENT (accumulates across sessions)   |
 |  Project agents emerge from git evidence (/evolve)        |
 |  Reflexes learned from tool-use observations              |
 |  Skills created when patterns repeat                      |
@@ -130,30 +138,33 @@ npx azclaude-copilot .              # resume existing copilot run
 +-----------------------------------------------------------+
 ```
 
-Runner loops. AZCLAUDE accumulates. Claude thinks.
+Runner loops. Team thinks. AZCLAUDE accumulates. Claude builds.
 
 ---
 
-## The Pipeline
+## The Intelligent Copilot Pipeline (v0.4+)
 
 Every command detects copilot mode automatically (`[ -f .claude/copilot-intent.md ]`) and skips human interaction -- no approval gates, no prompts, no pauses.
 
 ```
-Session 1:  /dream -> /blueprint -> /add M1 -> /add M2 -> /add M3 -> /snapshot
-Session 2:  /evolve -> /add M4 -> /add M5 -> /add M6 -> /snapshot
-Session 3:  /evolve -> /add M7 -> /add M8 -> /add M9 -> /snapshot
+Session 1:  /dream -> /blueprint (problem-architect annotates each milestone)
+                   -> orchestrator dispatches milestone-builder M1,M2,M3 -> /snapshot
+Session 2:  /evolve (new agents created -> orchestrator unblocks plan)
+                   -> orchestrator dispatches M4,M5 (parallel) -> M6 -> /snapshot
+Session 3:  /evolve -> orchestrator dispatches M7,M8,M9 -> /snapshot
 Session 4:  /evolve -> /audit -> /ship -> COPILOT_COMPLETE
 ```
 
-### Per Milestone
+### Per Milestone (Intelligent Dispatch)
 
-1. Read milestone from `plan.md` (description, expected files, dependencies)
-2. Implement using `/add` (follows `patterns.md`, reads context artifacts, uses project agents)
-3. Run tests -- fix if failing (2 attempts max)
-4. If still failing -- log to `blockers.md`, skip, continue
-5. Commit: `{type}: {what} -- {why}`
-6. Push + update `plan.md` status to `done`
-7. `/snapshot` (compaction protection)
+1. **Orchestrator** reads plan.md, selects next milestone wave
+2. **Problem-Architect** analyzes the milestone → returns Team Spec:
+   agents needed, skills to load, files to pre-read, files to write (parallel safety), risks, complexity
+3. **Orchestrator** dispatches **Milestone-Builder** with fully packaged context
+4. **Milestone-Builder** pre-reads all specified files, implements, runs tests
+5. Fix if failing (2 attempts SIMPLE/MEDIUM, 3 for COMPLEX)
+6. If budget exhausted → log to `blockers.md`, orchestrator moves to next milestone
+7. Commit: `{type}: {what} -- {why}` + push + update plan.md status → `done`
 
 ### Self-Healing
 
@@ -266,7 +277,27 @@ Session 4:
   Full evolved environment. /audit -> /ship -> deploy. COPILOT_COMPLETE
 ```
 
-System agents (code-reviewer, test-writer, orchestrator-init) run the framework. Project agents emerge from the work. Two separate layers.
+System agents (orchestrator, problem-architect, milestone-builder, code-reviewer, test-writer, orchestrator-init) run the framework. Project agents (cc-*) emerge from the work. Two separate layers.
+
+### Intelligent Dispatch — Pre-Flight for Every Command
+
+`shared/intelligent-dispatch.md` is the universal pre-flight protocol. Every non-trivial command loads it before touching code.
+
+**Commands that now spawn problem-architect before acting:**
+
+| Command | What pre-analysis adds |
+|---------|----------------------|
+| `/add` | What files to pre-read, which skills to load, pre-conditions, patterns to follow |
+| `/fix` | Bug scope (which files are involved), relevant antipatterns, pre-conditions |
+| `/dream` | Scan existing codebase before generating vision (what already exists, established patterns) |
+| `/audit` | Inject decisions.md + patterns.md + antipatterns.md as the review checklist |
+| `/refactor` | Full dependency graph before touching code (catches missed references) |
+| `/ship` | Risk scan — unmet pre-conditions block the push |
+| `/blueprint` | Annotates every plan.md milestone with: Complexity, Files Written, Pre-conditions, Risks |
+| `/evolve` | After creating new agents: orchestrator re-evaluates plan.md, unblocks blocked milestones |
+| `/setup` | Cold-start: problem-architect recommends agents when < 5 git commits exist |
+
+Every command used to jump in blind. Now they ask "what do I need to know first?"
 
 ### Context Artifacts
 
@@ -469,7 +500,7 @@ azclaude-copilot/
 ├── DOCS.md                          <- full user guide
 ├── SECURITY.md                      <- security policy + architecture
 ├── tests/
-│   └── test-features.sh          ← 1107 tests
+│   └── test-features.sh          ← 1135 tests
 ```
 
 ---
@@ -495,11 +526,11 @@ The runner is stateless. These files ARE the state.
 
 ## Verified
 
-1107 tests. Every template, command, capability, agent, and CLI feature verified.
+1135 tests. Every template, command, capability, agent, and CLI feature verified.
 
 ```bash
 bash tests/test-features.sh
-# Results: 1107 passed, 0 failed, 1107 total
+# Results: 1135 passed, 0 failed, 1135 total
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "azclaude-copilot",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "AI coding environment — 26 commands, 8 skills, 10 agents, memory, reflexes, evolution. Install once, works on any stack.",
   "bin": {
     "azclaude": "./bin/cli.js",

package/templates/capabilities/manifest.md

@@ -25,6 +25,7 @@ Load only the files that match the current task. Never load the full list.
 | shared/context-artifacts.md | Project has DB schemas, API specs, infra configs, or knowledge/ dir — discover and use non-code knowledge before implementing | ~200 |
 | shared/semantic-boundary-check.md | /evolve Cycle 3 or boundary validator warns — detect deeper behavioral duplication across extension types that grep misses | ~300 |
 | shared/domain-advisor-generator.md | Non-tech domain detected (compliance, marketing, finance, medical, legal, research) — generates domain-specific advisor skill | ~400 |
+| shared/intelligent-dispatch.md | About to build, fix, refactor, audit, or ship — non-trivial scope (3+ files or structural) — pre-flight analysis via problem-architect | ~300 |
 
 ## Level Builders — load ONE at a time
 | File | When to load | Tokens |

package/templates/capabilities/shared/intelligent-dispatch.md

@@ -0,0 +1,79 @@
+# Intelligent Dispatch — Pre-Flight Protocol
+
+Load before any non-trivial build, fix, refactor, audit, or plan task.
+Invokes problem-architect for structured analysis BEFORE touching code.
+
+---
+
+## When to Run Problem-Architect
+
+Run pre-analysis if ANY of these is true:
+- Task will touch 3+ files
+- Task involves a structural change (schema, API contract, auth, architecture)
+- Task crosses directory boundaries (multiple modules or layers)
+- First time working in this part of the codebase this session
+
+Skip if:
+- Only 1-2 files, clearly scoped
+- Pure config/docs change with no code impact
+- Already in copilot mode with annotated plan.md (milestones already have Team Spec)
+
+---
+
+## How to Invoke
+
+```bash
+ls .claude/agents/problem-architect.md 2>/dev/null && echo "ARCHITECT_AVAILABLE" || echo "NOT_INSTALLED"
+```
+
+If ARCHITECT_AVAILABLE — spawn problem-architect with:
+```
+Task: {command name} — {what you're doing}
+Current state: {what files/dirs exist relevant to this task}
+Available agents: {output of: ls .claude/agents/ 2>/dev/null}
+Available skills: {output of: ls .claude/skills/ 2>/dev/null}
+```
+
+---
+
+## What to Do with the Returned Team Spec
+
+| Field | Action |
+|-------|--------|
+| Skills to Load | Load each skill before implementing |
+| Pre-Read Files | Read every file listed, in order: schema → source → tests → patterns → antipatterns |
+| Pre-Conditions | Verify each; STOP if any unmet |
+| Files Written | Note for parallel safety — no concurrent work on same files |
+| Structural Decision: YES | Run /debate before proceeding; log result to `.claude/memory/decisions.md` |
+| Risks | Read mitigation; apply to implementation approach |
+
+---
+
+## Implementation Protocol (milestone-builder)
+
+For any implementation task (3+ files or MEDIUM/COMPLEX):
+
+1. **Pre-read** all files from Team Spec — no exceptions
+2. **Implement** following patterns.md exactly — never invent patterns
+3. **Verify** — run full test suite, show actual output (never summarize)
+4. **Self-correct** — re-read error + check antipatterns.md → ONE alternative approach
+5. **Budget** — 2 fix attempts for SIMPLE/MEDIUM, 3 for COMPLEX
+   - Budget exhausted → report exact error + what was tried → do not guess again
+
+---
+
+## When to Escalate to Orchestrator
+
+If `.claude/agents/orchestrator.md` exists:
+- Task spans 2+ milestones in plan.md → delegate to orchestrator
+- Multiple independent workstreams → orchestrator manages parallel dispatch
+- Structural decision needed → orchestrator triggers /debate
+
+---
+
+## Rules
+
+- NEVER skip pre-read. Context-blind implementation is the most common failure mode.
+- NEVER invent patterns. patterns.md says use X → use X.
+- NEVER exceed fix attempt budget. Stop and report when exhausted.
+- ALWAYS show test output. Never say "tests should pass."

package/templates/commands/add.md

@@ -18,6 +18,19 @@ Load: shared/tdd.md + shared/completion-rule.md
 
 ---
 
+## Pre-Flight Analysis (intelligent-dispatch)
+
+Load `shared/intelligent-dispatch.md`.
+
+If task will touch 3+ files OR crosses module boundaries:
+→ Spawn problem-architect (see intelligent-dispatch protocol)
+→ Use returned Team Spec: load skills, pre-read files, check pre-conditions, note risks
+→ If Structural Decision: YES → run /debate before Phase 4
+
+If problem-architect not installed: proceed with Phase 1 as normal (manual scan in Phase 2).
+
+---
+
 ## Copilot Mode Detection
 
 ```bash

package/templates/commands/audit.md

@@ -48,6 +48,27 @@ If `COPILOT_MODE`:
 
 ---
 
+## Step 1b: Structural Context (intelligent-dispatch)
+
+Load `shared/intelligent-dispatch.md`.
+
+If problem-architect available — spawn it before reviewing:
+```
+Task: audit — structural context for spec compliance review
+Current state: {what's changed, what the diff covers}
+Available agents: {list}
+Available skills: {list}
+```
+Use returned Team Spec to inject:
+- `decisions.md` rulings to check against (architectural commitments)
+- `patterns.md` conventions the code should follow
+- `antipatterns.md` known failure patterns to scan for
+- Risks flagged by architect → include in audit checklist
+
+If problem-architect not installed: proceed with manual review using available memory files.
+
+---
+
 ## Step 2: Spec Compliance (REQUIRED FIRST)
 
 **Assume the implementation may be incomplete or optimistic. Verify independently.**

package/templates/commands/dream.md

@@ -57,6 +57,23 @@ Read `.claude/capabilities/manifest.md` if it exists.
 
 Detect current level (0–7) from what's present.
 
+**Existing project deep scan (intelligent-dispatch):**
+
+If `.claude` directory exists and project has code files — load `shared/intelligent-dispatch.md` and spawn problem-architect:
+```
+Task: dream — analyze existing codebase before generating vision
+Current state: {what files, agents, skills already exist}
+Available agents: {list}
+Available skills: {list}
+```
+Use returned Team Spec to understand:
+- What agents/skills already cover (don't regenerate what exists)
+- Co-change clusters (candidate future agents)
+- Established patterns (vision must not conflict with them)
+- Structural decisions already made (decisions.md)
+
+If clean slate (no .claude dir): skip problem-architect, proceed to Phase 3.
+
 **ExitPlanMode** — ready to build.
 
 ---

package/templates/commands/fix.md

@@ -14,6 +14,20 @@ Load: shared/tdd.md + shared/completion-rule.md before starting.
 
 ---
 
+## Pre-Flight Analysis (intelligent-dispatch)
+
+Load `shared/intelligent-dispatch.md`.
+
+After reproducing the error — before investigating — spawn problem-architect if available:
+→ Task: "fix — {error description}"
+→ Current state: {files involved in the failure}
+→ Use returned Team Spec: pre-read the affected files, load patterns/antipatterns for this area
+→ Pre-conditions check prevents fixing a symptom instead of the root cause
+
+If problem-architect not installed: proceed with Phase 2 manual investigation as normal.
+
+---
+
 ## Phase 1: REPRODUCE
 
 **First: check IDE diagnostics (instant, no build needed)**

package/templates/commands/refactor.md

@@ -18,6 +18,27 @@ Load: shared/completion-rule.md
 
 ---
 
+## Pre-Flight Analysis (intelligent-dispatch)
+
+Load `shared/intelligent-dispatch.md`.
+
+Spawn problem-architect before any scan:
+```
+Task: refactor — {what's being refactored}
+Current state: {target file/function + surrounding directory}
+Available agents: {list}
+Available skills: {list}
+```
+Use returned Team Spec:
+- Pre-Read Files → read these BEFORE grepping for references (architect already knows the dependency graph)
+- Risks → structural risks the refactor may trigger (e.g., type exports used downstream)
+- Files Written → exhaustive list of files the refactor will touch
+- If Structural Decision: YES → run /debate (refactors sometimes expose architectural choices)
+
+If problem-architect not installed: proceed with Phase 1 manual scan.
+
+---
+
 ## Phase 1: Understand Current State
 
 If $ARGUMENTS is blank, use **AskUserQuestion**:

package/templates/commands/ship.md

@@ -15,6 +15,26 @@ $ARGUMENTS
 
 ---
 
+## Step 0: Risk Scan (intelligent-dispatch)
+
+Load `shared/intelligent-dispatch.md`.
+
+If problem-architect available — spawn it for a pre-ship risk scan:
+```
+Task: ship — pre-ship risk assessment
+Current state: {output of: git diff --stat HEAD}
+Available agents: {list}
+Available skills: {list}
+```
+Use returned Team Spec:
+- Risks → must address before shipping (not suggestions)
+- Structural Decision: YES → a decision was made without /debate → log it to decisions.md now
+- Pre-Conditions → any unmet condition blocks ship (e.g., migration not run, env var not set)
+
+If problem-architect not installed OR git diff is only docs/config: skip and proceed to Pre-Ship Gate.
+
+---
+
 ## Pre-Ship Gate (runs before any commit)
 
 **1. IDE diagnostics** — use `mcp__ide__getDiagnostics` if available.