azclaude-copilot 0.4.37 → 0.4.38

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "azclaude",
       "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 37 commands, 9 auto-invoked skills, 15 specialized agents, 4 hooks, and a persistent memory system — in one command.\n\nKey features:\n• Memory across sessions — goals.md + checkpoints injected automatically before every session\n• Self-improving loop — /reflect fixes stale CLAUDE.md rules, /reflexes learns from tool-use patterns, /evolve creates agents from git evidence\n• Autonomous copilot mode — /copilot runs a three-tier team (orchestrator → problem-architect → milestone-builder) across sessions until the product ships\n• Spec-driven workflow — /constitute writes project rules, /spec writes structured ACs, /analyze detects plan drift and ghost milestones, /blueprint traces every milestone to a spec\n• Security layer — 111-rule environment scan (/sentinel), pre-write secret blocking, pre-ship credential audit\n• Progressive levels 0–10 — start with CLAUDE.md, grow into multi-agent pipelines and self-evolving environments\n• Zero dependencies — no npm packages, no external APIs, no vector databases. Plain markdown files and Claude Code's native architecture.\n• Smart install — npx azclaude-copilot@latest auto-detects first install vs upgrade vs verify. Context-aware onboarding shows the right next command for your project state.\n\nExample use cases:\n• /setup — scan an existing project, detect stack + domain + scale, fill CLAUDE.md, generate project-specific skills and agents automatically\n• /copilot \"Build a compliance SaaS with trilingual support\" — walk away, come back to working code across multiple sessions\n• /sentinel — run a scored security audit (0–100, grade A–F) across hooks, permissions, MCP servers, agent configs, and secrets\n• /evolve — detect gaps in the environment, generate new skills and agents from git co-change evidence, report score delta (e.g. 42/100 → 68/100)\n• /constitute — write your project's constitution (non-negotiables, architectural commitments, definition of done) — gates all future AI actions\n• /analyze — cross-artifact consistency check: ghost milestones, spec vs. code drift, unplanned commits\n• /reflect — find stale, missing, or contradicting rules in CLAUDE.md and propose exact fixes\n• /debate \"REST vs GraphQL for this project\" — adversarial evidence-based decision with order-independent scoring, logged to decisions.md",
-      "version": "0.4.37",
+      "version": "0.4.38",
       "source": {
         "source": "github",
         "repo": "haytamAroui/AZ-CLAUDE-COPILOT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "azclaude",
-  "version": "0.4.37",
+  "version": "0.4.38",
   "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 37 commands, 9 auto-invoked skills, 15 specialized agents, 4 hooks, and a persistent memory system — in one command.\n\nKey features:\n• Memory across sessions — goals.md + checkpoints injected automatically before every session\n• Self-improving loop — /reflect fixes stale CLAUDE.md rules, /reflexes learns from tool-use patterns, /evolve creates agents from git evidence\n• Autonomous copilot mode — /copilot runs a three-tier team (orchestrator → problem-architect → milestone-builder) across sessions until the product ships\n• Spec-driven workflow — /constitute writes project rules, /spec writes structured ACs, /analyze detects plan drift and ghost milestones, /blueprint traces every milestone to a spec\n• Security layer — 111-rule environment scan (/sentinel), pre-write secret blocking, pre-ship credential audit\n• Progressive levels 0–10 — start with CLAUDE.md, grow into multi-agent pipelines and self-evolving environments\n• Zero dependencies — no npm packages, no external APIs, no vector databases. Plain markdown files and Claude Code's native architecture.\n• Smart install — npx azclaude-copilot@latest auto-detects first install vs upgrade vs verify. Context-aware onboarding shows the right next command for your project state.\n\nExample use cases:\n• /setup — scan an existing project, detect stack + domain + scale, fill CLAUDE.md, generate project-specific skills and agents automatically\n• /copilot \"Build a compliance SaaS with trilingual support\" — walk away, come back to working code across multiple sessions\n• /sentinel — run a scored security audit (0–100, grade A–F) across hooks, permissions, MCP servers, agent configs, and secrets\n• /evolve — detect gaps in the environment, generate new skills and agents from git co-change evidence, report score delta (e.g. 42/100 → 68/100)\n• /constitute — write your project's constitution (non-negotiables, architectural commitments, definition of done) — gates all future AI actions\n• /analyze — cross-artifact consistency check: ghost milestones, spec vs. code drift, unplanned commits\n• /reflect — find stale, missing, or contradicting rules in CLAUDE.md and propose exact fixes\n• /debate \"REST vs GraphQL for this project\" — adversarial evidence-based decision with order-independent scoring, logged to decisions.md",
   "author": {
     "name": "haytamAroui",

package/README.md

@@ -15,7 +15,7 @@
     <a href="#spec-driven-workflow">Spec-Driven</a> ·
     <a href="#memory-system">Memory</a> ·
     <a href="#self-improving-loop">Self-Improving Loop</a> ·
-    <a href="#all-36-commands">Commands</a> ·
+    <a href="#all-37-commands">Commands</a> ·
     <a href="#parallel-execution">Parallel</a> ·
     <a href="#mcp-integration">MCP</a> ·
     <a href="#autonomous-mode">Autonomous Mode</a> ·
@@ -47,6 +47,7 @@ Can't work autonomously.              /copilot builds, tests, commits, ships —
 Plans without requirements.           /spec writes structured specs before any code is planned.
 Milestones violate project rules.     constitution-guard blocks non-compliant milestones.
 Plan drifts from what was built.      /analyze catches ghost milestones before they ship.
+Agents run serially, one at a time.   Task Classifier + parallel waves run agents simultaneously.
 ```
 
 One install. Any stack. Zero dependencies.
@@ -106,19 +107,18 @@ Day 30 — you finish the project:
 CLAUDE.md → read manifest.md → load ONLY the files for this task (~380 tokens)
 ```
 
-Claude reads the manifest (one file), finds which 1-3 capability files apply, loads only those. Adding a new agent or skill doesn't increase the cost of unrelated tasks. The environment grows without bloating context.
+Claude reads the manifest (one file), finds which 1–3 capability files apply, loads only those. Adding a new agent or skill doesn't increase the cost of unrelated tasks. The environment grows without bloating context.
 
 ---
 
 ## Install
 
-**Step 1 — Install globally from your terminal:**
-
 ```bash
 npx azclaude-copilot@latest
 ```
 
-That's it. One command, no flags. Auto-detects whether this is a fresh install or an upgrade:
+One command, no flags. Auto-detects whether this is a fresh install or an upgrade:
+
 - **First time** → full install (37 commands, 4 hooks, 15 agents, 10 skills, memory, reflexes)
 - **Already installed, older version** → auto-upgrades everything to latest templates
 - **Already up to date** → verifies, no overwrites
@@ -131,15 +131,15 @@ npx azclaude-copilot@latest doctor   # 32 checks — verify everything is wired
 
 ## What You Get
 
-**37 commands** · **9 auto-invoked skills** · **15 agents** · **4 hooks** · **memory across sessions** · **learned reflexes** · **self-evolving environment**
+**37 commands** · **10 auto-invoked skills** · **15 agents** · **4 hooks** · **memory across sessions** · **learned reflexes** · **self-evolving environment**
 
 ```
 .claude/
 ├── CLAUDE.md                 ← dispatch table: conventions, stack, routing
-├── commands/                 ← 36 slash commands (/add, /fix, /copilot, /parallel, /mcp, /sentinel...)
+├── commands/                 ← 37 slash commands (/add, /fix, /copilot, /parallel, /mcp, /sentinel...)
 ├── skills/                   ← 10 skills (test-first, security, architecture-advisor, frontend-design...)
 ├── agents/                   ← 15 agents (orchestrator, spec-reviewer, constitution-guard...)
-├── capabilities/             ← 37 files, lazy-loaded via manifest.md (~380 tokens/task)
+├── capabilities/             ← 43 files, lazy-loaded via manifest.md (~380 tokens/task)
 ├── hooks/
 │   ├── user-prompt.js        ← injects goals.md + checkpoint before your first message
 │   ├── pre-tool-use.js       ← blocks hardcoded secrets before any file write
@@ -173,65 +173,51 @@ Scans your codebase, detects domain + stack + scale, fills CLAUDE.md, creates go
 /dream "Build a compliance SaaS — FastAPI, Supabase, trilingual"
 ```
 
-One command builds everything from scratch:
+Builds everything from scratch in four phases:
 
 ```
 Phase 1: Asks 4 questions (what, stack, who uses it, what's out of scope)
 Phase 2: Scans existing environment — won't regenerate what already exists
 Phase 3: Builds level by level:
-         L1 → CLAUDE.md (project rules + routing)
-         L2 → MCP config
-         L3 → Skills (project-specific commands)
-         L4 → Memory (goals.md + patterns + antipatterns)
-         L5 → Agents (specialized for your stack, from git evidence)
-         L6 → Hooks (stateful session tracking)
+         L1 → CLAUDE.md       L2 → MCP config
+         L3 → Skills          L4 → Memory
+         L5 → Agents          L6 → Hooks
 Phase 3b: Domain advisor skill — auto-generated if non-dev domain detected
           (compliance, finance, medical, legal, logistics, research, marketing)
 Phase 4: Quality gate — won't say "ready" without passing all checks
 ```
 
-If your domain is compliance, finance, or medical — it generates a domain-specific advisor skill with decision matrices, thresholds, and anti-patterns automatically.
-
-### 4. Spec-Driven Workflow — build what you actually meant to build
-
-The biggest cause of wasted work: building the wrong thing correctly. `/dream` gives you an environment. The spec-driven workflow ensures you build what the environment is *for*.
+### 3. `/copilot` — walk away, come back to a product
 
+```bash
+npx azclaude-copilot . "Build a compliance SaaS with trilingual support"
+# or resume:
+npx azclaude-copilot .
 ```
-/constitute    — define ground rules before any planning
-                 Non-negotiables, required patterns, definition of done.
-                 Copilot checks this before every milestone. Violations are blocked, not ignored.
-
-/spec          — write a structured spec before /blueprint
-                 User stories, acceptance criteria (3+), out-of-scope, failure modes.
-                 spec-reviewer (haiku) validates quality — if incomplete, /blueprint is blocked.
 
-/clarify       — resolve open questions in a spec
-                 Structured interrogation (max 5 questions). Writes answers back into the spec.
+Node.js runner restarts Claude Code sessions in a loop until `COPILOT_COMPLETE`. Each session reads state, picks next milestone, implements, tests, commits, evolves. No human input needed. [Details below.](#autonomous-mode)
 
-/blueprint     — derive a milestone plan from the spec
-                 Each milestone traces to an acceptance criterion.
-                 spec-reviewer gates quality before planning starts.
+---
 
-/analyze       — cross-artifact consistency check
-                 Detects ghost milestones (marked done, files missing),
-                 spec vs. implementation drift, plan vs. reality gaps.
-                 Runs automatically in /ship and /audit.
+## Spec-Driven Workflow
 
-/tasks         — build a dependency graph from plan.md
-                 Shows parallelizable wave groups and critical path length.
-                 Tells orchestrator which milestones can run simultaneously.
+The biggest cause of wasted work: building the wrong thing correctly. The spec-driven workflow ensures you build what you actually meant to build.
 
-/issues        — convert plan.md milestones to GitHub Issues
-                 Creates labels (azclaude, copilot-milestone), deduplicates,
-                 writes issue numbers back to plan.md for traceability.
-```
-
-**The full sequence:**
 ```
 /constitute → /spec → /clarify → /blueprint → /copilot → /analyze → /ship
 ```
 
-**What the gates actually prevent:**
+| Command | Purpose |
+|---------|---------|
+| `/constitute` | Define ground rules before any planning. Non-negotiables, required patterns, definition of done. Copilot enforces on every milestone. |
+| `/spec` | Write a structured spec: user stories (≥2), acceptance criteria (≥3), out-of-scope, failure modes. spec-reviewer validates quality — if incomplete, `/blueprint` is blocked. |
+| `/clarify` | Structured interrogation (max 5 questions). Resolves open questions in a spec. Required before `/blueprint` if questions remain. |
+| `/blueprint` | Derive a milestone plan from the spec. Each milestone traces to an acceptance criterion. Task classifier groups coupled work for parallel safety. |
+| `/analyze` | Cross-artifact consistency check. Finds ghost milestones (marked done, files missing), spec vs. implementation drift, plan vs. reality gaps. |
+| `/tasks` | Build dependency graph from plan.md. Shows parallelizable wave groups and critical path length. |
+| `/issues` | Convert plan.md milestones to GitHub Issues. Deduplicates, creates labels, writes issue numbers back to plan.md. |
+
+**What the gates prevent:**
 
 | Without spec-driven | With spec-driven |
 |---------------------|-----------------|
@@ -242,77 +228,28 @@ The biggest cause of wasted work: building the wrong thing correctly. `/dream` g
 
 ---
 
-### 3. `/copilot` — walk away, come back to a product
-
-```bash
-npx azclaude-copilot . "Build a compliance SaaS with trilingual support"
-# or resume existing run:
-npx azclaude-copilot .
-```
-
-Node.js runner restarts Claude Code sessions in a loop until `COPILOT_COMPLETE`. Each session reads state, picks next milestone, implements, tests, commits, evolves. No human input needed.
-
-### Day-to-day
-
-```bash
-/add [feature]    # add a feature — pre-analyzes scope, follows patterns
-/fix [bug]        # reproduce → investigate → fix → verify
-/audit            # spec-first code review, read-only
-/test             # framework detection, exit-code gate, failure classification
-/evolve           # scan for gaps, generate fixes, create agents from evidence
-/ship             # tests → secrets scan → commit → push → deploy
-/sentinel         # security scan — scored 0–100, grade A–F, 5 layers, 102 rules
-/pulse            # health check — recent changes, current level, next steps
-/debate [topic]   # adversarial decision protocol with evidence scoring
-/snapshot         # save WHY you made decisions — auto-injected next session
-/reflect          # find and fix stale/missing rules in CLAUDE.md
-/reflexes         # view learned behavioral patterns with confidence scores
-/parallel M2 M3   # run multiple milestones simultaneously (worktree isolation + auto-merge)
-/mcp              # recommend and install MCP servers based on your stack
-```
-
----
-
 ## Memory System
 
-The core insight: **Claude needs to see two things at the start of every session — what changed, and why decisions were made.** Everything else is noise.
+Claude needs two things at the start of every session — **what changed** and **why decisions were made**. Everything else is noise.
 
-### How it works (zero user input)
+### Automatic (zero user input)
 
 ```
-Every edit:  pre-tool-use.js  → blocks hardcoded secrets before write
-             post-tool-use.js → breadcrumb appended to goals.md
-             (timestamp, file, diff stats, one-line summary)
-
-Session end: stop.js → In-progress migrates to Done
-             Trims to 20 Done entries, archives overflow
-             Resets counters
-
-Session start: user-prompt.js → injects before your first message:
-               ┌─ goals.md (capped: 30 in-progress + 20 done)
-               ├─ latest checkpoint (capped at 50 lines)
-               ├─ plan status: X/N done, Y in-progress, Z blocked  [copilot mode]
-               └─ learned reflexes with confidence ≥ 0.8, max 5    [strict profile]
+Every edit:    post-tool-use.js → breadcrumb in goals.md (timestamp, file, diff stats)
+Before write:  pre-tool-use.js  → blocks hardcoded secrets
+Session end:   stop.js          → In-progress migrates to Done, trims to 20 entries
+Session start: user-prompt.js   → injects goals.md + latest checkpoint + plan status
 ```
 
 **Token cost: ~500 tokens fixed.** goals.md auto-rotates at 30 entries — oldest 15 archived, newest 15 kept. Same cost at session 5 or session 500.
 
-### Manual layer (you control)
+### Manual (you control)
 
 ```bash
-/snapshot     # save reasoning snapshot — captures:
-              #   • What you're doing right now (specific task, not project description)
-              #   • WHY each decision was made this session
-              #   • What you know that isn't written down yet  ← the key section
-              #   • Top 3 next actions
-              #   • Risks and open questions
-              # Run every 15–20 turns. Auto-injected at next session start.
-              # Protects against context compaction losing mid-session reasoning.
-
+/snapshot     # save WHY decisions were made — auto-injected next session
+              # run every 15–20 turns to protect against context compaction
 /persist      # end-of-session: update goals.md, write session narrative
-              # run before closing
-
-/pulse        # read current state — what's healthy, what needs attention
+/pulse        # health check — recent changes, blockers, next steps
 ```
 
 ### Hook profiles
@@ -323,15 +260,6 @@ AZCLAUDE_HOOK_PROFILE=standard claude   # all features (default)
 AZCLAUDE_HOOK_PROFILE=strict   claude   # all + reflex guidance injection
 ```
 
-| Feature | minimal | standard | strict |
-|---------|---------|----------|--------|
-| goals.md tracking + memory rotation | ✓ | ✓ | ✓ |
-| Checkpoint injection | ✓ | ✓ | ✓ |
-| Reflex observations (observations.jsonl) | — | ✓ | ✓ |
-| Cost tracking | — | ✓ | ✓ |
-| Plan status (copilot mode) | — | ✓ | ✓ |
-| Reflex guidance (confidence ≥ 0.8) | — | — | ✓ |
-
 ### State files — the runner is stateless, these files ARE the state
 
 | File | Written by | Read by | Purpose |
@@ -345,23 +273,21 @@ AZCLAUDE_HOOK_PROFILE=strict   claude   # all + reflex guidance injection
 | `memory/blockers.md` | /copilot | /copilot, /debate | What's stuck and why |
 | `memory/reflexes/` | Hooks, /reflexes | /evolve, agents | Learned behavioral patterns |
 | `plan.md` | /blueprint | /copilot, /add | Milestone tracker with status |
-| `copilot-report.md` | /copilot | Human | Final autonomous run summary |
 
 ---
 
 ## Self-Improving Loop
 
-AZCLAUDE doesn't just remember — it learns and corrects itself. Three commands form a loop that runs every few sessions:
+AZCLAUDE doesn't just remember — it learns and corrects itself. Three commands form a feedback loop:
 
 ```
 /reflect   →   Reads friction logs + session history
-               Finds missing rules, dead rules, vague rules, contradicting rules
-               Proposes exact CLAUDE.md edits, one finding per change
-               You approve → CLAUDE.md gets smarter
+               Finds missing rules, dead rules, vague rules, contradictions
+               Proposes exact CLAUDE.md edits. You approve. CLAUDE.md corrects itself.
 
 /reflexes  →   Reads observations.jsonl (captured automatically by post-tool-use.js)
-               Finds tool sequences, file co-access, error→fix pairs, naming patterns
-               Creates confidence-scored reflex files (0.3 tentative → 0.9 near-certain)
+               Finds tool sequences, file co-access, error→fix pairs
+               Creates confidence-scored reflex files (0.3 tentative → 0.9 certain)
                Strong reflexes (≥ 0.7) feed into /add behavior automatically
 
 /evolve    →   Detects gaps: stale data, missing capabilities, context rot
@@ -376,26 +302,22 @@ AZCLAUDE doesn't just remember — it learns and corrects itself. Three commands
 ```
 /reflect found:
   MISSING RULE  — Wrong agent routing causing silent failures every session
-  MISSING RULE  — Domain-specific legal term (CAO 98) kept drifting back into code
-  STALE DATA    — Design tokens in CLAUDE.md were wrong hex values (not matching codebase)
+  MISSING RULE  — Domain-specific legal term kept drifting back into code
+  STALE DATA    — Design tokens in CLAUDE.md were wrong hex values
   MISSING ROUTE — Most frequent task had no slash command dispatch
 
 /reflexes found (from 78 observations, 3 sessions):
-  i18n-all-6-locales     (confidence 0.85) → always edit all 6 locale files atomically
-  page-tsx-read-before-edit (0.75)          → re-read before touching — changes too often
-  next-config-build-verify  (0.70)          → run tsc --noEmit after next.config.ts edits
-  vertex-assess-co-edit     (0.60)          → vertex_client.py and assess_paid.py always coupled
+  i18n-all-6-locales        (confidence 0.85) → always edit all 6 locale files atomically
+  page-tsx-read-before-edit  (0.75)            → re-read before touching — changes too often
+  next-config-build-verify   (0.70)            → run tsc --noEmit after next.config.ts edits
 
 /evolve found:
   plan.md frozen at 9/9 done — actually 18 milestones, M12–M18 active
   No i18n-sync skill despite 6-locale changes in every commit
-  eu-ai-act-engine skill had no test recipe for zero-coverage modules
   Score: 42/100 → 68/100
 ```
 
-All of this without human diagnosis. The system found it, proposed fixes, applied them.
-
-**The same loop runs on AZCLAUDE itself.** When sentinel.md had a Windows path bug and a broken agent dispatch — a real project test exposed both. AZCLAUDE diagnosed them, fixed `sentinel.md`, tests went from 1195/1197 to 1197/1197, and shipped v0.4.9.
+All without human diagnosis. The system found it, proposed fixes, applied them.
 
 ---
 
@@ -403,23 +325,14 @@ All of this without human diagnosis. The system found it, proposed fixes, applie
 
 `/evolve` finds gaps in the environment and fixes them. Three cycles:
 
-**Cycle 1 — Environment Evolution**
-- Detects: stale patterns, friction signals, context rot (poisoning / distraction / confusion / clash)
-- Generates: fixes for each gap
-- Evaluates: quality-gates before merging (syntax, self-applicability, pressure-test resilience)
+**Cycle 1 — Environment Evolution:** Detects stale patterns, friction signals, context rot. Generates fixes. Quality-gates before merging.
 
-**Cycle 2 — Knowledge Consolidation** (every 2+ sessions)
-- Harvests patterns.md and sessions/ by recency + importance
-- Prunes stale entries, consolidates redundant patterns
-- Enriches agent definitions with accumulated learnings
-- Auto-prunes reflexes where confidence < 0.15
+**Cycle 2 — Knowledge Consolidation** (every 2+ sessions): Harvests patterns by recency + importance. Prunes stale entries. Auto-prunes reflexes where confidence < 0.15.
 
-**Cycle 3 — Topology Optimization** (when friction detected)
-- Measures agent influence in pipelines
-- Identifies merge candidates (overlapping agents)
-- Tests changes in isolated worktree before adopting
+**Cycle 3 — Topology Optimization** (when friction detected): Measures agent influence. Identifies merge candidates. Tests in isolated worktree before adopting.
 
 **Agent emergence from git evidence:**
+
 ```
 Session 1: 0 project agents. Build basic structure.
            Git: 3 commits touching fastapi/, next/, supabase/
@@ -438,146 +351,36 @@ Skills and agents that are project-generic get promoted to `~/shared-skills/`
 
 ---
 
-## Security
-
-Zero dependencies in `package.json`. The only external binary is `claude` (installed separately). No supply-chain risk.
-
-**6 layers, 4 enforcement points:**
-
-| Layer | Where it runs | What it blocks |
-|-------|--------------|----------------|
-| Hook integrity | Every session start | SHA-256 mismatch → hooks tampered |
-| Secret blocking | `pre-tool-use.js` — before every write | `AKIA*`, `sk-*`, `ghp_*`, `glpat-*`, `xoxb-*`, `-----BEGIN PRIVATE KEY` |
-| Prompt injection defense | `user-prompt.js` — before context injection | `curl\|bash`, `ignore previous instructions`, base64 payloads in goals.md/checkpoints |
-| Environment audit | `/sentinel` — on-demand, 102 rules | Scored 0–100, grade A–F across 5 layers |
-| Pre-ship scan | `/ship` — before every commit | Secrets in staged files, failing tests, IDE errors |
-| Agent scoping | All review agents | Reviewer/auditor agents are read-only — no Write/Edit permissions |
+## Autonomous Mode
 
-### `/sentinel` — Environment Security Scan
+### `/copilot` — describe a product, come back to working code
 
 ```bash
-/sentinel          # full scan (default)
-/sentinel --hooks  # Layer 1+2: hook integrity + permissions
-/sentinel --mcp    # Layer 3: MCP server secrets and unknown packages
-/sentinel --agents # Layer 4: prompt injection in agent files
-/sentinel --secrets # Layer 5: credentials in committed code
-```
-
-Produces a scored report with verdict: `BLOCKED` / `CLEAR` / `PROCEED WITH CAUTION`.
-
-```
-╔══════════════════════════════════════════════════╗
-║          SENTINEL — Environment Security         ║
-╚══════════════════════════════════════════════════╝
-
-Layer 1 — Hook Integrity       25/25   ✓ verified
-Layer 2 — Permission Audit     12/20   ⚠ Bash(rm:*) too broad
-Layer 3 — MCP Server Scan      20/20   ✓ clean
-Layer 4 — Agent Config Review  15/15   ✓ no injection found
-Layer 5 — Secrets Scan         18/20   ⚠ API key in settings
-──────────────────────────────────────────────────
-Total: 90/100   Grade: A   Verdict: CLEAR
+npx azclaude-copilot . "Build a compliance SaaS with trilingual support"
 ```
 
-Any hardcoded secret → `BLOCKED` — `/ship` will not proceed until resolved.
-
-See [SECURITY.md](SECURITY.md) for full details.
-
----
-
-## Intelligence Layer
-
-### 8 Skills (auto-invoked — no slash command needed)
-
-| Skill | Triggers on |
-|-------|------------|
-| `session-guard` | Session start, context reset, idle detection |
-| `test-first` | Writing/fixing code in TDD projects (signal-based — only if project has tests) |
-| `env-scanner` | Project setup, stack detection |
-| `security` | Credentials, auth, payments, .env files, secrets, before /ship |
-| `debate` | Decisions, trade-offs, "which is better", architecture comparisons |
-| `skill-creator` | "Create a skill", repeated workflows, new capability |
-| `agent-creator` | "Create an agent", agent boundaries, 5-layer structure |
-| `architecture-advisor` | Architecture decisions, DB choice, rendering strategy, testing approach — by project scale |
-
-### Architecture Advisor — 8 Evidence-Based Decision Matrices
-
-Not "which is popular" — which is right for **your project's scale**:
-
-| Decision | SMALL (< 50 files) | MEDIUM (50-500 files) | LARGE (500+ files) |
-|----------|-------------------|----------------------|-------------------|
-| Architecture | Flat modules | Modular monolith | Monolith + targeted microservices |
-| Database | SQLite | PostgreSQL | PostgreSQL + Redis + search |
-| Testing | Test-after critical paths | TDD for business logic | Full TDD |
-| API | tRPC (internal) | REST | REST + GraphQL (mobile) |
-| Auth | Clerk / Supabase | Auth0 | Keycloak (self-hosted) |
-| State | useState | TanStack Query | Zustand + XState |
-| Rendering | SSG or SPA | SSR / ISR | ISR + edge caching |
-| Deploy | Vercel / Railway | Managed containers | AWS/GCP with IaC |
-
-Every recommendation includes the threshold where it changes and the anti-pattern to avoid at that scale.
-
-### Domain Advisor Generator — 7 Non-Tech Domains
-
-When `/dream` or `/setup` detects a non-developer domain, a domain-specific advisor skill is generated automatically — with decision matrices, thresholds, and anti-patterns:
-
-| Domain | What gets generated |
-|--------|-------------------|
-| Compliance | Regulation mapping, evidence strategy, article-level traceability, audit trail |
-| Finance | Event-sourced data model, integer-cents precision, reconciliation, risk model |
-| Medical | FHIR vs HL7, HIPAA vs GDPR privacy model, clinical workflow, terminology |
-| Marketing | Channel strategy, funnel design, pricing model, metric focus by revenue stage |
-| Research | Literature scope, methodology, experiment design, statistical rigor |
-| Legal | Contract structure, clause tracking, jurisdiction, risk classification |
-| Logistics | Routing, inventory model, tracking granularity |
-
-### Reflexes — Learned Behavioral Patterns
+Node.js runner restarts Claude Code sessions in a loop until `COPILOT_COMPLETE`.
 
-Every tool use is observed. Patterns that repeat become reflexes:
+**Four-phase execution loop:**
 
-```yaml
-id: i18n-all-6-locales
-trigger: "any src/messages/*.json file is edited"
-action: "edit all 6 locale files in the same operation — never fewer"
-confidence: 0.85      # 0.3 tentative → 0.9 near-certain
-evidence_count: 6
-domain: workflow
-scope: project        # promote to global when seen in 2+ projects at ≥ 0.8
 ```
+Phase 1 — Intelligence gathering (parallel agents)
+  Multiple analyst agents run simultaneously — arch, UX, market, compliance.
+  Each returns findings. Orchestrator synthesizes.
 
-- `post-tool-use.js` captures observations to `reflexes/observations.jsonl` automatically
-- 3+ occurrences creates a reflex at confidence 0.3
-- Confidence rises with confirming observations, decays -0.02/week without use
-- Strong clusters (3+ reflexes, avg confidence > 0.7) evolve into skills or agents
-- Global promotion when seen in 2+ projects at confidence ≥ 0.8
-
-### Context Artifacts — Non-Code Project Knowledge
-
-Before implementing, AZCLAUDE discovers and reads non-code knowledge that informs implementation:
-
-| Type | Examples | Why it matters |
-|------|---------|---------------|
-| Database schemas | `prisma/schema.prisma`, `schema.sql` | Know table structure before writing queries |
-| API specs | `openapi.yaml`, `swagger.json`, `.proto` | Know endpoints before building integrations |
-| Infra configs | `terraform/`, `docker-compose.yml` | Know deployment constraints before architecture decisions |
-| Architecture docs | `docs/architecture.md`, ADRs | Know design decisions before proposing changes |
-| Domain knowledge | `knowledge/`, business rules, regulations | Know domain constraints before implementing logic |
-
----
-
-## Autonomous Mode
+Phase 2 — Debate synthesis
+  /debate resolves tensions with evidence scoring. Produces prioritized action list.
 
-### `/copilot` — describe a product, come back to working code
+Phase 3 — Blueprint (parallel explore agents)
+  /blueprint runs explore agents in parallel. Writes file:line plan.
+  Task Classifier groups coupled work → safe parallel dispatch by design.
 
-```bash
-npx azclaude-copilot . "Build a compliance SaaS with trilingual support"
-# or resume existing run:
-npx azclaude-copilot .
+Phase 4 — Execution (parallel milestone agents, worktree-isolated)
+  Orchestrator dispatches same-wave milestones simultaneously.
+  Each agent owns its scope. Orchestrator merges on completion.
 ```
 
-Node.js runner restarts Claude Code sessions in a loop until `COPILOT_COMPLETE`.
-
-**Three-tier intelligent team (v0.4+):**
+**Three-tier intelligent team (Phase 4):**
 
 ```
 Orchestrator          Problem-Architect          Milestone-Builder
@@ -585,17 +388,15 @@ Orchestrator          Problem-Architect          Milestone-Builder
 Reads plan.md    →    Analyzes milestone    →     Pre-reads all files
 Selects wave          Returns Team Spec:          Implements
 Dispatches            • agents needed             Runs tests
-Monitors              • skills to load            Self-corrects (2 fix attempts)
-Triggers /evolve      • files to pre-read         Commits + reports back
-Never writes code     • Files Written (parallel
-                        safety — prevents
-                        concurrent file corruption)
-                      • pre-conditions, risks
-                      • complexity (SIMPLE/MEDIUM/COMPLEX)
+Monitors              • skills to load            Self-corrects (2 attempts)
+Triggers /evolve      • Files Written (parallel   Commits + reports back
+Never writes code       safety check)
+                      • complexity estimate
                       Never implements
 ```
 
-**Self-healing protocol — every failure teaches the environment:**
+**Self-healing — every failure teaches the environment:**
+
 ```
 Build step fails →
   1. Re-read the exact error (not a summary)
@@ -607,16 +408,15 @@ Build step fails →
 ```
 
 **Copilot pipeline (with spec-driven workflow):**
+
 ```
-Session 0:  /constitute → /spec → /clarify → /blueprint (spec-reviewed, constitution-checked)
-Session 1:  /copilot → constitution-guard validates each milestone → M1, M2, M3 → /snapshot
+Session 0:  /constitute → /spec → /clarify → /blueprint
+Session 1:  /copilot → constitution-guard validates → M1, M2, M3 → /snapshot
 Session 2:  /evolve → M4+M5 parallel → M6 → /analyze (ghost check) → /snapshot
 Session 3:  /evolve → M7, M8, M9 → /snapshot
 Session 4:  /evolve → /analyze → /audit → /ship → COPILOT_COMPLETE
 ```
 
-**Every 3 milestones:** `/reflexes analyze` + `/evolve` + orchestrator re-evaluates blocked milestones.
-
 **Exit conditions:**
 
 | Condition | Exit code |
@@ -629,29 +429,122 @@ Session 4:  /evolve → /analyze → /audit → /ship → COPILOT_COMPLETE
 
 ## Parallel Execution
 
-AZCLAUDE runs multiple Claude Code agents simultaneously on the same codebase — without file corruption or test interference. Each agent works in an isolated git worktree on its own branch. Changes merge sequentially after all agents complete.
+AZCLAUDE runs multiple Claude Code agents simultaneously on the same codebase — without file corruption or test interference. Each agent works in an isolated git worktree on its own branch.
 
 ```
 M1 (schema) → done
                  ↓
-    ┌────────────┬────────────┬────────────┐
+    ┌────────────┬────────────┬────────────┬──────────────┐
     M2 (auth)   M3 (profile) M4 (email)   M5 (dashboard)   ← all run simultaneously
-    ↓            ↓            ↓            ↓
-    └────────────┴────────────┴────────────┘
+    └────────────┴────────────┴────────────┴──────────────┘
                  ↓
               M6 (E2E tests)
 ```
 
-**Automatic — via `/copilot`:** The orchestrator reads `Wave:` fields in plan.md (written by `/blueprint`), dispatches same-wave milestones with `isolation: "worktree"` in a single message, then merges sequentially.
+3 sequential waves instead of 6 sequential milestones. Same output, fraction of the time.
+
+**Real session — Systems Registry sprint (compliance SaaS, 5 milestones):**
+
+```
+Phase 1 — Intelligence (4 agents, parallel)
+  arch-analyst  → found broken auto-link bug in assess-paid/page.tsx
+  ux-analyst    → identified save-to-registry conversion hole
+  market-intel  → found FRIA + Art. 49 regulatory blue ocean
+  compliance    → mapped 13 fields present vs 66 required
+  Time: ~9 minutes. Equivalent human analyst work: full day.
+
+Phase 2 — Debate synthesis (1 agent)
+  4 tensions resolved with verdicts. Prioritized action list produced.
+
+Phase 3 — Blueprint (3 explore agents, parallel)
+  Read assess-paid page, systems pages, and API routes simultaneously.
+  Produced file:line plan across 5 milestones.
+
+Phase 4 — Execution (2 agents, parallel — classifier applied)
+  dev-frontend (M1+M2)  64.5k tokens   assess-paid/page.tsx + save-registry UI
+  dev-backend  (M4)     37.5k tokens   systems.py + DB migration SQL
+
+Classifier merged M1+M2 automatically — both touch assess-paid/page.tsx.
+M4 backend ran in parallel — completely independent file set, zero conflict risk.
+```
+
+**Four-layer safety model:**
+
+```
+Layer 0 — Task Classifier (blueprint, before milestones exist)
+  Groups coupled work (same schema, config, utility module) into single milestones.
+  Conflicts become impossible by design — before any safety checking begins.
+
+Layer 1 — Directory check + shared-utility grep (blueprint, pre-plan)
+  Fast, no agents spawned. Catches ~80% of remaining conflicts.
+
+Layer 2 — Problem-architect exact file scan (post-plan, per milestone)
+  Returns Files Written: exact paths + Parallel Safe: YES/NO.
+  Corrects Layer 1 when it finds shared utilities across directories.
+
+Layer 3 — Orchestrator dispatch gate (runtime, unconditional)
+  Final overlap check before spawning. Cannot be bypassed.
+```
+
+**Automatic** via `/copilot`: the orchestrator reads `Wave:` fields in plan.md, dispatches same-wave milestones with `isolation: "worktree"` in a single message, then merges sequentially.
+
+**Manual** via `/parallel M2 M3 M4 M5`: dispatch specific milestones simultaneously.
+
+See [docs/parallel-execution.md](docs/parallel-execution.md) for the complete reference.
+
+### Why coordination matters
+
+Claude Code's `isolation: "worktree"` in the Task tool is a raw primitive — like `pthread_create`. You have threads, but threads alone aren't a concurrent system.
+
+| Raw capability | AZCLAUDE coordination layer |
+|---|---|
+| Task tool spawns agents | Orchestrator decides WHEN and HOW MANY |
+| Worktree isolates files | Blueprint classifier ensures they're safe to isolate |
+| Agents can read files | Problem-architect pre-packages the exact context each needs |
+| Agents can write code | Patterns/antipatterns constrain what they write |
+| Agents can fail | Blocker recovery + /debate escalation handles the failure |
+| Sessions end | goals.md + checkpoints + plan.md resume exactly where it stopped |
+| Code accumulates | /evolve turns git evidence into new agents for next time |
+
+6 desks is not a team. AZCLAUDE turns 6 desks into a coordinated team.
+
+---
+
+## Security
+
+Zero dependencies in `package.json`. The only external binary is `claude` (installed separately). No supply-chain risk.
+
+**4 enforcement points, always active:**
+
+| Layer | Where | What it blocks |
+|-------|-------|----------------|
+| Secret blocking | `pre-tool-use.js` — before every write | `AKIA*`, `sk-*`, `ghp_*`, `glpat-*`, `xoxb-*`, `-----BEGIN PRIVATE KEY` |
+| Prompt injection | `user-prompt.js` — before context injection | `curl\|bash`, `ignore previous instructions`, base64 payloads |
+| Pre-ship scan | `/ship` — before every commit | Secrets in staged files, failing tests, IDE errors |
+| Agent scoping | All review agents | Reviewer/auditor agents are read-only — no Write/Edit permissions |
+
+### `/sentinel` — on-demand security scan
 
-**Manual — via `/parallel`:**
 ```bash
-/parallel M2 M3 M4 M5    # dispatch these milestones simultaneously
+/sentinel          # full scan — 5 layers, 102 rules, scored 0–100 (grade A–F)
+/sentinel --hooks  # hook integrity + permissions only
+/sentinel --secrets # credential scan only
 ```
 
-**Four-layer safety:** Before creating any milestones, `/blueprint` runs a **Task Classifier** (Layer 0) — groups coupled work (same schema table, same config file, same utility module) into single milestones so conflicts are impossible by design. Then: directory isolation + shared-utility grep (Layer 1, no agents spawned). `problem-architect` returns exact `Files Written:` and `Parallel Safe:` per milestone (Layer 2). Orchestrator re-checks file overlap at dispatch time (Layer 3 — unconditional final gate).
+```
+╔══════════════════════════════════════════════════╗
+║          SENTINEL — Environment Security         ║
+╚══════════════════════════════════════════════════╝
+Layer 1 — Hook Integrity       25/25   ✓ verified
+Layer 2 — Permission Audit     12/20   ⚠ Bash(rm:*) too broad
+Layer 3 — MCP Server Scan      20/20   ✓ clean
+Layer 4 — Agent Config Review  15/15   ✓ no injection found
+Layer 5 — Secrets Scan         18/20   ⚠ API key in settings
+──────────────────────────────────────────────────
+Total: 90/100   Grade: A   Verdict: CLEAR
+```
 
-See `docs/parallel-feature.md` for the complete reference.
+Any hardcoded secret → `BLOCKED`. `/ship` will not proceed until resolved. See [SECURITY.md](SECURITY.md) for full details.
 
 ---
 
@@ -660,20 +553,77 @@ See `docs/parallel-feature.md` for the complete reference.
 AZCLAUDE recommends MCP servers based on your stack and wires them into daily-use commands.
 
 ```bash
-/mcp    # detect stack → recommend universal MCPs → show install commands
+/mcp    # detect stack → recommend → show install commands
 ```
 
-**Universal (free, no API key — recommended for every project):**
-- `Context7` — `/add` fetches live library docs before writing any library calls. Prevents stale API usage.
-- `Sequential Thinking` — `/blueprint` and `/copilot` use iterative reasoning for milestone planning.
+**Universal (free, no API key):** `Context7` (live library docs before writing code), `Sequential Thinking` (iterative reasoning for planning).
+
+**Stack-specific:** `GitHub MCP`, `Playwright MCP`, `Supabase MCP`, `Brave Search`.
+
+---
+
+## Intelligence Layer
+
+### 10 Skills (auto-invoked)
 
-**Stack-specific:**
-- `GitHub MCP` — any GitHub repo: richer `/ship` and PR creation
-- `Playwright MCP` — any web project: E2E testing with qa-engineer
-- `Supabase MCP` — Supabase in deps: schema introspection, migrations
-- `Brave Search` — `/fix` looks up external library errors before guessing root cause
+| Skill | Triggers on |
+|-------|------------|
+| `session-guard` | Session start, context reset, idle detection |
+| `test-first` | Writing/fixing code in TDD projects |
+| `env-scanner` | Project setup, stack detection |
+| `security` | Credentials, auth, payments, secrets |
+| `debate` | Decisions, trade-offs, architecture comparisons |
+| `skill-creator` | Repeated workflows, new capability needed |
+| `agent-creator` | Agent boundaries, 5-layer structure |
+| `architecture-advisor` | DB choice, rendering strategy, testing approach — by project scale |
+| `frontend-design` | UI components, styling, layout decisions |
+| `mcp` | MCP server recommendations based on stack |
+
+### Architecture Advisor — 8 Decision Matrices
+
+Not "which is popular" — which is right for **your project's scale**:
 
-`/setup` checks MCP status at the end and nudges if none are configured.
+| Decision | SMALL | MEDIUM | LARGE |
+|----------|-------|--------|-------|
+| Architecture | Flat modules | Modular monolith | Monolith + targeted microservices |
+| Database | SQLite | PostgreSQL | PostgreSQL + Redis + search |
+| Testing | Test-after critical paths | TDD for business logic | Full TDD |
+| API | tRPC (internal) | REST | REST + GraphQL (mobile) |
+| Auth | Clerk / Supabase | Auth0 | Keycloak (self-hosted) |
+| Deploy | Vercel / Railway | Managed containers | AWS/GCP with IaC |
+
+Every recommendation includes the **threshold where it changes** and the **anti-pattern** to avoid.
+
+### Domain Advisors — Auto-Generated for 7 Domains
+
+When `/dream` or `/setup` detects a non-developer domain, a domain-specific advisor skill is generated automatically:
+
+| Domain | What gets generated |
+|--------|-------------------|
+| Compliance | Regulation mapping, evidence strategy, article-level traceability |
+| Finance | Event-sourced data model, integer-cents precision, reconciliation |
+| Medical | FHIR vs HL7, HIPAA vs GDPR, clinical workflow |
+| Marketing | Channel strategy, funnel design, pricing model |
+| Research | Literature scope, methodology, statistical rigor |
+| Legal | Contract structure, clause tracking, risk classification |
+| Logistics | Routing, inventory model, tracking granularity |
+
+### Reflexes — Learned Behavioral Patterns
+
+Every tool use is observed. Patterns that repeat become reflexes:
+
+```yaml
+id: i18n-all-6-locales
+trigger: "any src/messages/*.json file is edited"
+action: "edit all 6 locale files in the same operation — never fewer"
+confidence: 0.85      # 0.3 tentative → 0.9 certain
+evidence_count: 6
+```
+
+- 3+ occurrences creates a reflex at confidence 0.3
+- Confidence rises with confirming observations, decays -0.02/week without use
+- Strong clusters evolve into skills or agents via `/evolve`
+- Global promotion when seen in 2+ projects at confidence ≥ 0.8
 
 ---
 
@@ -684,179 +634,120 @@ AZCLAUDE recommends MCP servers based on your stack and wires them into daily-us
 | Command | What it does |
 |---------|-------------|
 | `/copilot` | Autonomous milestone execution. Delegates to orchestrator team. Zero human input. |
-| `/dream` | Idea → full project scaffold. CLAUDE.md, memory, skills, agents — built level by level. |
+| `/dream` | Idea → full project scaffold. CLAUDE.md, memory, skills, agents — level by level. |
 | `/setup` | Analyze existing project. Detect domain + stack + scale. Build environment. |
 | `/add` | Add a feature. Pre-analyzes scope via intelligent-dispatch before touching code. |
-| `/fix` | REPRODUCE → INVESTIGATE → HYPOTHESIZE → FIX. Show passing tests. Never guesses. |
-| `/audit` | Spec-first code review (read-only). Ghost milestone check + decisions.md + patterns.md. |
-| `/test` | IDE diagnostics, framework detection, exit-code gate, failure classification. |
-| `/blueprint` | Read-only analysis → structured plan.md. spec-reviewer gates quality before planning. |
-| `/ship` | Ghost check → risk scan → tests → secrets scan → commit → push. Auto-deploys in copilot mode. |
-| `/refactor` | Safe restructuring. Constitution pre-flight. Tests before + after. Worktree for high-risk. |
+| `/fix` | REPRODUCE → INVESTIGATE → HYPOTHESIZE → FIX. Show passing tests. |
+| `/audit` | Spec-first code review (read-only). Ghost milestone check. |
+| `/test` | Framework detection, exit-code gate, failure classification. |
+| `/blueprint` | Read-only analysis → structured plan.md. Task classifier + parallel optimization. |
+| `/ship` | Ghost check → risk scan → tests → secrets scan → commit → push → deploy. |
+| `/refactor` | Safe restructuring. Constitution pre-flight. Tests before + after. |
 | `/doc` | Generate docs from code. Matches existing style. |
-| `/migrate` | Upgrade deps/frameworks. Researches breaking changes. Worktree for major versions. |
+| `/migrate` | Upgrade deps/frameworks. Researches breaking changes. |
 | `/deps` | Audit: outdated, vulnerable, unused packages. |
 
 ### Spec-Driven Development
 
 | Command | What it does |
 |---------|-------------|
-| `/constitute` | Define project ground rules before any planning. Non-negotiables, required patterns, definition of done. Copilot enforces on every milestone. |
-| `/spec` | Write a structured spec: goal, user stories (≥2), acceptance criteria (≥3), out-of-scope, failure modes. spec-reviewer validates before /blueprint. |
-| `/clarify` | Structured interrogation loop (max 5 questions). Resolves open questions in a spec file. Required before /blueprint if any questions remain open. |
-| `/analyze` | Cross-artifact consistency check. Finds ghost milestones (marked done, files missing), spec vs. code drift, plan vs. reality gaps. Read-only. |
-| `/tasks` | Build dependency graph from plan.md. Shows parallelizable wave groups and critical path. Tells orchestrator which milestones can run simultaneously. |
-| `/issues` | Convert plan.md milestones to GitHub Issues. Deduplicates, creates labels, writes issue numbers back to plan.md for traceability. |
-| `/parallel` | Run multiple milestones simultaneously. Worktree isolation per agent. Auto-merges after all complete. Three-layer file collision safety. |
-| `/mcp` | Recommend and install MCP servers based on detected stack. Wires Context7, Sequential Thinking, GitHub, Playwright, Brave Search, Supabase. |
-| `/driven` | Generate `.claude/code-rules.md` — 6-question interview → DO/DO NOT coding contract. Read by every /add and /fix before writing code. |
-| `/verify` | Audit existing code against `code-rules.md`. Reports violations at `file:line`. Auto-fix mode. Falls back to per-stack rule libraries when no contract exists. |
+| `/constitute` | Define ground rules. Non-negotiables, required patterns, definition of done. |
+| `/spec` | Structured spec: user stories, acceptance criteria, out-of-scope, failure modes. |
+| `/clarify` | Resolve open questions in a spec (max 5 questions). |
+| `/analyze` | Cross-artifact consistency. Ghost milestones, spec drift, plan gaps. |
+| `/tasks` | Dependency graph from plan.md. Wave groups + critical path. |
+| `/issues` | Convert milestones to GitHub Issues with traceability. |
+| `/parallel` | Run multiple milestones simultaneously. Worktree isolation + auto-merge. |
+| `/mcp` | Recommend and install MCP servers for your stack. |
+| `/driven` | Generate code-rules.md — DO/DO NOT coding contract. |
+| `/verify` | Audit code against code-rules.md. Reports violations at `file:line`. |
 
 ### Think and Improve
 
 | Command | What it does |
 |---------|-------------|
-| `/debate` | Adversarial debate with evidence scoring (AceMAD). Order-independent, length-independent. |
-| `/evolve` | Detect gaps → generate fixes → quality-gate → create agents from evidence. Drift analysis. |
-| `/sentinel` | Security scan — 5 layers, 102 rules, scored 0–100 (grade A–F). Blocks /ship on findings. |
-| `/reflexes` | View, analyze, promote learned behavioral patterns. Confidence scoring. |
-| `/reflect` | Self-improve CLAUDE.md. Reads friction logs + session history. Proposes exact rule edits. |
-| `/level-up` | Show current level (0-10), build the next one progressively. |
-| `/find` | Search across commands, `~/shared-skills/`, capabilities manifest. |
-| `/create` | Build a new command with frontmatter, trigger variants, and tests. |
-| `/hookify` | Generate hooks from friction patterns. 5 hook types (block / warn / remind / inject / track). |
+| `/debate` | Adversarial debate with evidence scoring (AceMAD protocol). |
+| `/evolve` | Detect gaps → generate fixes → quality-gate → create agents from evidence. |
+| `/sentinel` | Security scan — 5 layers, 102 rules, scored 0–100 (grade A–F). |
+| `/reflexes` | View, analyze, promote learned behavioral patterns. |
+| `/reflect` | Self-improve CLAUDE.md from friction logs + session history. |
+| `/level-up` | Show current level (0–10), build the next one. |
+| `/find` | Search across commands, `~/shared-skills/`, capabilities. |
+| `/create` | Build a new command with frontmatter and tests. |
+| `/hookify` | Generate hooks from friction patterns. 5 hook types. |
 
 ### Memory and Session
 
 | Command | What it does |
 |---------|-------------|
-| `/snapshot` | Mid-session: WHY + decisions + what isn't written down yet + top 3 next actions. Auto-injected next session. |
-| `/persist` | End-of-session: update goals.md, write session narrative to `sessions/`. |
-| `/pulse` | Health check — recent changes, current level, reflexes, blockers, next steps. |
-| `/explain` | Code or error to plain language. 2-3 paragraphs max. |
+| `/snapshot` | Save WHY you made decisions. Auto-injected next session. |
+| `/persist` | End-of-session: update goals.md, write session narrative. |
+| `/pulse` | Health check — recent changes, level, reflexes, blockers. |
+| `/explain` | Code or error to plain language. |
 | `/loop` | Repeat any command on an interval via CronCreate. |
 
 ---
 
-## 15 Agents
-
-**Framework agents** (ship with AZCLAUDE, always available):
-
-| Agent | Role |
-|-------|------|
-| `orchestrator` | Tech lead for `/copilot`. Owns plan.md. Reads constitution.md. Runs constitution-guard before every dispatch. Never writes code. |
-| `problem-architect` | Pre-flight analyst. Returns Team Spec (agents/skills/files/risks/complexity) before every dispatch. Never implements. |
-| `milestone-builder` | Base builder. Reads constitution.md FIRST. Pre-reads all files, implements, verifies, self-corrects, commits. |
-| `spec-reviewer` | **New — haiku model.** Validates spec quality before /blueprint runs. 7 criteria. Verdict: APPROVED / NEEDS_CLARIFY / INCOMPLETE. Read-only gate. |
-| `constitution-guard` | **New — haiku model.** Checks each milestone against constitution.md before dispatch. Verdict: APPROVED / VIOLATION. Blocks on violations. Read-only gate. |
-| `orchestrator-init` | Runs once during `/setup`. Scans project, fills CLAUDE.md, creates goals.md. Exits permanently. |
-| `loop-controller` | Level 10 autonomous agent. 3 cycles: evolution, knowledge consolidation, topology optimization. |
-| `evolution-module` | Called by orchestrator to run /evolve and /level-up at Level 10. Delegates to loop-controller. |
-| `intelligence-module` | Optional Level 8-9 agent. Pipeline isolation, debate engine, prompt optimization (OPRO), ELO ranking. |
-| `code-reviewer` | Spec-first review. Stage 1: spec compliance. Stage 2: quality. Read-only. Never modifies files. |
-| `security-auditor` | Pre-ship security scan. 102 rules across 5 layers. Verdict: APPROVE / REQUEST CHANGES / BLOCKED. |
-| `test-writer` | Reads existing test patterns. Matches framework, style, naming. Writes and runs tests. |
-| `cc-template-author` | Writes AZCLAUDE template files with proper structure. |
-| `cc-cli-integrator` | Integrates new features into `bin/cli.js`. |
-| `cc-test-maintainer` | Maintains `tests/test-features.sh` with correct grep patterns. |
-
-**Project agents** (emerge from your git history via `/evolve`):
-- Named `cc-{area}`, scoped to specific directories
-- Created when 3+ files in the same area change together across 2+ commits
-- Every agent has exactly 5 layers: persona, scope, tools, constraints, domain knowledge
-- `cc-` prefix prevents framework collisions (langgraph, crewai, autogen)
-
----
-
 ## Skills vs Agents — The Right Tool
 
-Claude Code is already capable. The goal is guidance, not instructions. Before creating an agent, understand what each tool is actually for.
-
 ### Skills: project-specific guidance
 
-A skill is a markdown file that fires automatically when Claude needs context it can't derive from the code alone. The best skill answers one question: **"In this project, when doing X, what do you need to know that you can't read from the files?"**
-
-Skills are NOT:
-- Generic instructions Claude already knows ("write clean code", "add error handling")
-- Boilerplate copied from another project without reading this one first
-- A wrapper around knowledge Claude already has by default
+A skill fires automatically when Claude needs context it can't derive from code alone. The best skill answers: **"In this project, when doing X, what do you need to know that you can't read from the files?"**
 
-Skills ARE:
-- "In this compliance project, every obligation must be traced to an article number — here's the format"
-- "Our auth module uses RS256 not HS256 — here's why and where that decision lives"
-- "The 6 locale files must always be edited atomically — here's the co-edit pattern"
-
-`/setup` and `/evolve` generate skills by running `problem-architect` first — it reads your actual file structure, co-change patterns, and conventions, then builds skills around the gaps it finds. Generic skill templates are not installed.
+Skills are NOT generic instructions Claude already knows ("write clean code"). Skills ARE project-specific knowledge: "Our auth uses RS256 not HS256 — here's why" or "The 6 locale files must always be edited atomically."
 
 ### Agents: only for parallelism and isolation
 
-An agent is a sub-process. Use one when you need work to happen **in parallel** or **in a separate context** from the main session. Not for organizing knowledge — skills do that cheaper.
-
-**Create an agent when:**
-- Two workstreams can run concurrently (parallel dispatch saves real time)
-- A task must be isolated from main context (experiments, reviews, security scans)
-- There's enough domain depth to justify a dedicated context window (5+ files, unique conventions, a clear scope boundary)
-
-**Don't create an agent when:**
-- A tight skill + Claude's native capability already handles it
-- You'd create it just to "have one for auth" or "have one for the frontend"
-- The agent's instructions are things Claude already knows without being told
+An agent is a sub-process. Use one when work must happen **in parallel** or **in a separate context**. Not for organizing knowledge — skills do that cheaper.
 
-**The test:** Would removing this agent and writing a skill instead produce worse results? If no — use a skill. Agents cost tokens every time they're loaded. A skill that gives Claude the right context is lighter and often better.
-
-### The right order
+**The test:** Would removing this agent and writing a skill produce worse results? If no — use a skill.
 
 ```
-1. Craft a skill that gives Claude the project-specific context it's missing
-2. Watch if the same workflow keeps recurring across sessions (/reflexes will detect it)
-3. If work can be parallelized OR isolated → promote to an agent
-4. Let /evolve make the call from git evidence — it sees what actually co-changes
+1. Craft a skill for the project-specific context Claude is missing
+2. Watch if the same workflow keeps recurring (/reflexes will detect it)
+3. If work can be parallelized or isolated → promote to an agent
+4. Let /evolve make the call from git evidence
 ```
 
 ---
 
 ## Progressive Levels (0–10)
 
-AZCLAUDE builds capability progressively — start simple, grow into complexity:
-
 | Level | What gets built | Trigger |
 |-------|----------------|---------|
 | 0 | Nothing yet | Fresh project |
 | 1 | CLAUDE.md — project rules + dispatch | `/setup` or `/dream` |
-| 2 | MCP config — database, browser, API access | `/level-up` |
+| 2 | MCP config | `/level-up` |
 | 3 | Skills — project-specific commands | `/setup` generates ≥ 2 |
 | 4 | Memory — goals.md, patterns, antipatterns | `/setup` |
 | 5 | Agents — from git co-change analysis | `/evolve` after 5+ commits |
 | 6 | Hooks — stateful session tracking | `npx azclaude-copilot` |
 | 7 | External MCP servers | `/level-up` |
-| 8 | Orchestrated pipeline — multi-agent with problem-architect | `/level-up` |
-| 9 | Intelligence — debate, OPRO, ELO, pipeline isolation | `npx azclaude-copilot` |
-| 10 | Self-evolving — loop-controller, 3-cycle autonomous evolution | `/evolve` sustained |
-
-Run `/level-up` at any time to see your current level and build the next one.
+| 8 | Orchestrated pipeline — multi-agent | `/level-up` |
+| 9 | Intelligence — debate, OPRO, ELO | `npx azclaude-copilot` |
+| 10 | Self-evolving — loop-controller | `/evolve` sustained |
 
 ---
 
 ## What Makes It Different
 
-| Feature | Claude Code alone | AZCLAUDE |
-|---------|------------------|---------|
+| | Claude Code alone | AZCLAUDE |
+|---|---|---|
 | Project memory | Starts fresh every session | goals.md + checkpoints injected automatically |
-| Conventions | Ad-hoc, re-explained each time | CLAUDE.md — loaded before every task |
-| Mid-session reasoning | Lost on context compaction | /snapshot saves WHY — auto-injected next session |
-| Learned behavior | None | Reflexes extracted from tool-use, confidence-scored |
-| CLAUDE.md quality | Drifts, never updated | /reflect finds stale/missing/dead rules and fixes them |
+| Conventions | Re-explained each time | CLAUDE.md — loaded before every task |
+| Mid-session reasoning | Lost on compaction | /snapshot saves WHY — auto-injected next session |
+| Learned behavior | None | Reflexes from tool-use, confidence-scored |
+| CLAUDE.md quality | Drifts, never updated | /reflect finds and fixes stale rules |
 | Architecture decisions | Re-debated every time | decisions.md — logged once, referenced forever |
 | Failed approaches | Repeated | antipatterns.md — agents read before implementing |
-| Security | Manual | 4-layer enforcement: write-time blocking, context scan, audit, pre-ship |
-| Domain knowledge | Generic | Domain advisors generated for compliance, finance, medical, legal... |
-| Agent specialization | None | Project agents emerge from git evidence, not guessing |
+| Security | Manual | 4-layer enforcement: write-time blocking + audit + pre-ship |
+| Agent specialization | None | Project agents emerge from git evidence |
 | Autonomous building | Not possible | /copilot — three-tier intelligent team |
-| Self-improvement | Not possible | /evolve + /reflect + /reflexes — 3-layer environment evolution |
-| Requirements traceability | None | /spec + acceptance criteria → every milestone traces to a requirement |
-| Governance enforcement | None | constitution-guard blocks milestones that violate non-negotiables |
-| Plan vs. reality drift | Invisible | /analyze detects ghost milestones before they ship |
-| Spec quality gate | None | spec-reviewer (haiku) validates before /blueprint starts planning |
+| Self-improvement | Not possible | /evolve + /reflect + /reflexes loop |
+| Requirements traceability | None | /spec → acceptance criteria → every milestone |
+| Governance | None | constitution-guard blocks non-compliant milestones |
+| Plan drift | Invisible | /analyze catches ghost milestones before they ship |
+| Parallel safety | Raw worktree primitive | Four-layer classifier + safety model |
 | Any stack | Yes | Yes |
 | You own the code | Yes | Yes |
 | Zero dependencies | — | Yes (0 in package.json) |
@@ -876,4 +767,4 @@ bash tests/test-features.sh
 
 ## License
 
-MIT — [haytamAroui](https://github.com/haytamAroui)
+MIT — [haytamAroui](https://github.com/haytamAroui)

package/hooks/hooks.json

@@ -12,9 +12,21 @@
         ]
       }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/templates/hooks/pre-tool-use.js\"",
+            "async": false
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
-        "matcher": "Write|Edit",
+        "matcher": "Write|Edit|MultiEdit|Read|Bash|Grep",
         "hooks": [
           {
             "type": "command",

package/package.json

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

package/templates/hooks/post-tool-use.js

@@ -29,8 +29,9 @@ try {
   toolName   = data.tool_name || '';
   filePath   = data.tool_input?.file_path || data.tool_input?.path || data.tool_input?.command || '';
   // Extract change summary from old_string/new_string diff hint (Edit tool)
-  const oldStr = data.tool_input?.old_string || '';
-  const newStr = data.tool_input?.new_string || '';
+  // MultiEdit: edits[] array — use first edit's new_string
+  const oldStr = data.tool_input?.old_string || data.tool_input?.edits?.[0]?.old_string || '';
+  const newStr = data.tool_input?.new_string || data.tool_input?.edits?.[0]?.new_string || '';
   if (oldStr && newStr) {
     // Summarize: first non-empty line of new content (what was added)
     const firstNew = newStr.split('\n').find(l => l.trim().length > 0) || '';
@@ -50,7 +51,7 @@ const goalsPath = path.join(cfg, 'memory', 'goals.md');
 if (!fs.existsSync(goalsPath)) process.exit(0); // not an AZCLAUDE project
 
 // For non-file tools (Bash, Grep without file_path), still capture observations but skip goals tracking
-const isFileTool = toolName === 'Write' || toolName === 'Edit' || (!toolName && filePath);
+const isFileTool = toolName === 'Write' || toolName === 'Edit' || toolName === 'MultiEdit' || (!toolName && filePath);
 const rel = filePath ? path.relative(process.cwd(), path.resolve(filePath)) : toolName || 'unknown';
 
 if (isFileTool) {