azclaude-copilot 0.5.6 → 0.5.8

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.6",
+      "version": "0.5.8",
       "source": {
         "source": "github",
         "repo": "haytamAroui/AZ-CLAUDE-COPILOT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "azclaude",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "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

@@ -12,6 +12,7 @@
     <a href="#how-it-works-the-execution-pipeline">Pipeline</a> ·
     <a href="#install">Install</a> ·
     <a href="#what-you-get">What You Get</a> ·
+    <a href="#structured-for-claude-frontmatter--xml-tags">Structure</a> ·
     <a href="#architecture-philosophy">Architecture</a> ·
     <a href="#autonomous-mode">Autonomous Mode</a> ·
     <a href="#parallel-execution">Parallel</a> ·
@@ -93,7 +94,6 @@ AZCLAUDE sits as a mandatory middleware firewall between your input and Claude.
 ┌──────────────────────────────────────────────────────────────┐
 │ 5. OUTBOUND SECURITY & MEMORY TRACKING                       │
 │  ├─► pre-tool-use.js: blocks curl|bash, secrets, traversal   │
-│  ├─► Native execution: Claude runs the approved command      │
 │  └─► post-tool-use.js: writes breadcrumb to goals.md         │
 └──────────────────────────────────────────────────────────────┘
 ```
@@ -117,6 +117,7 @@ One command, no flags. Auto-detects whether this is a fresh install or an upgrad
 ```bash
 npx azclaude-copilot@latest doctor   # 32 checks — verify everything is wired correctly
 ```
+│  ├─► Native execution: Claude runs the approved command      │
 
 ---
 
@@ -155,6 +156,87 @@ npx azclaude-copilot@latest doctor   # 32 checks — verify everything is wired
 
 ---
 
+## Structured for Claude: Frontmatter + XML Tags
+
+Anthropic's research shows Claude comprehends structured content significantly better when it uses two patterns natively built into Claude Code: **YAML frontmatter** for metadata and **`<instructions>` XML tags** for content. AZCLAUDE applies both to every agent and skill file — not as convention, but because it measurably changes how Claude reads, routes, and executes them.
+
+### Why this matters
+
+Claude was trained on XML-structured content. Tags like `<instructions>`, `<context>`, and `<examples>` signal boundaries Claude parses reliably — unlike prose headings which are ambiguous. Frontmatter gives Claude Code the metadata it needs to route, describe, and invoke agents without any extra configuration.
+
+### What AZCLAUDE agent files look like
+
+```yaml
+---                                    ← YAML frontmatter block
+name: code-reviewer                    ← agent identifier (used by subagent_type=)
+description: >                         ← Claude Code reads this to decide when to spawn
+  Autonomous code review agent.
+  Use when: review, audit, PR review,
+  find bugs, security check.
+model: opus                            ← which model this agent runs on
+tools: [Read, Glob, Grep, Bash]        ← allowed tools (principle of least privilege)
+disallowedTools: [Write, Edit, Agent]  ← explicit deny list — no write access
+permissionMode: plan                   ← read-only by default
+maxTurns: 30                           ← bounded execution
+tags: [review, pr, quality]            ← semantic routing hints
+---
+
+# Code Reviewer
+
+<instructions>                         ← XML tag: Claude parses this as structured directives
+
+## Layer 1: PERSONA
+Code review specialist. Read-only — never modifies code.
+
+## Layer 2: SCOPE
+- Reviews staged/unstaged changes via `git diff`
+- Checks for bugs, logic errors, edge cases
+- Identifies security issues (injection, XSS, OWASP top 10)
+
+</instructions>
+```
+
+### What AZCLAUDE skill files look like
+
+```yaml
+---                                    ← YAML frontmatter
+name: test-first
+description: >                         ← auto-invocation trigger — Claude reads this
+  Guides test-driven development.
+  Use when about to write code, implement a feature, fix a bug,
+  refactor, add an endpoint, or modify business logic.
+tags: [tdd, testing, coverage]
+---
+
+# Test-First
+
+<instructions>                         ← structured content block
+
+## Check before enforcing
+TDD is opt-in. Check BOTH signals:
+1. CLAUDE.md has a TDD rule
+2. Test files exist (*.test.*, *.spec.*)
+
+Both present → TDD protocol active.
+Either missing → suggest TDD, don't block.
+
+</instructions>
+```
+
+### Why this architecture works
+
+| Pattern | What it does |
+|---------|-------------|
+| `description:` frontmatter | Claude Code reads this to decide when to auto-invoke a skill or which agent to spawn. No code required. |
+| `model: opus` frontmatter | Routes complex review tasks to the most capable model automatically. |
+| `tools:` + `disallowedTools:` | Principle of least privilege — code-reviewer cannot Write, milestone-builder cannot call Agent. |
+| `<instructions>` XML tag | Signals to Claude "parse this as directives" — not prose, not documentation, not commentary. |
+| `permissionMode: plan` | Agents that only read run in plan mode — no accidental writes, no permission prompts. |
+
+All 15 AZCLAUDE agents and all 10 skills use this exact format. Claude Code routes them, describes them in `/help`, and invokes them via `subagent_type=` — all from the frontmatter, zero extra config.
+
+---
+
 ## Architecture Philosophy
 
 **AZCLAUDE uses Markdown files and lifecycle hooks — not MCP servers — as its core architecture.** This is a deliberate engineering decision, not a gap.
@@ -542,11 +624,11 @@ AZCLAUDE is a lazy-loaded environment of 48 capability modules. It only loads wh
 
 ## Verified
 
-1794 tests. Every template, command, capability, agent, hook, and CLI feature verified.
+1805 tests. Every template, command, capability, agent, hook, and CLI feature verified.
 
 ```bash
 bash tests/test-features.sh
-# Results: 1794 passed, 0 failed, 1794 total
+# Results: 1805 passed, 0 failed, 1805 total
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "azclaude-copilot",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "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

@@ -36,6 +36,25 @@ If CLAUDE.md unfilled → run `/setup` with intent from copilot-intent.md first.
 
 ---
 
+### Step 1b: Resume Interrupted Parallel Wave
+
+```bash
+cat .claude/parallel-wave-state.md 2>/dev/null
+```
+
+If the file exists with `status: in-flight` → a previous session was interrupted mid-parallel-dispatch.
+
+**Do NOT skip this. Do NOT start a new wave until the interrupted wave is resolved.**
+
+Follow the Resume Protocol from `capabilities/shared/parallel-coordination.md`:
+1. Read the wave state file — it lists every milestone, branch, and last-known status
+2. For each `running` milestone: check if `parallel/{slug}` branch exists and has commits
+3. Branches with commits → mark `done`, proceed to merge
+4. Branches without commits or missing → re-dispatch those milestones
+5. After all milestones resolved → merge → delete `.claude/parallel-wave-state.md` → continue
+
+---
+
 ### Step 2: Select Next Milestone Wave
 
 **If plan.md has `Wave:` fields** (blueprint wrote them — read directly):

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

@@ -166,6 +166,78 @@ These rules are injected by orchestrator into every parallel milestone-builder p
 
 ---
 
+## Wave State File — Context Loss Protection
+
+During parallel execution, the orchestrator writes `.claude/parallel-wave-state.md` **before dispatching any agents**. This file survives context compaction and enables session resume.
+
+### Format
+
+```markdown
+---
+wave: {N}
+started: {ISO timestamp}
+status: in-flight
+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 |
+```
+
+### Lifecycle
+
+1. **Created** — by `/parallel` Step 4 or orchestrator Step 4, before agent dispatch
+2. **Updated** — as each agent reports completion (status → `done`/`failed`, commit hash filled)
+3. **Deleted** — by orchestrator Step 8 or `/parallel` Step 8, after all branches merged and cleanup done
+
+### Rules
+
+- The file MUST exist whenever parallel agents are in-flight
+- If this file exists at session start → a previous wave was interrupted → trigger Resume Protocol
+- Only the orchestrator or `/parallel` command writes this file — builders never touch it
+
+---
+
+## Resume Protocol — Recovering Interrupted Waves
+
+When the orchestrator or `/parallel` finds `.claude/parallel-wave-state.md` at session start:
+
+### Step 1: Read Wave State
+```bash
+cat .claude/parallel-wave-state.md
+```
+
+### Step 2: Check Each Branch
+For every milestone with `status: running` (was in-flight when session died):
+```bash
+# Does the branch exist?
+git branch --list "parallel/{slug}"
+
+# Does it have commits beyond the fork point?
+git log main..parallel/{slug} --oneline 2>/dev/null | head -5
+```
+
+### Step 3: Classify Each Milestone
+
+| Branch exists? | Has commits? | Action |
+|---------------|-------------|--------|
+| Yes | Yes | Mark `done` in wave state — ready to merge |
+| Yes | No | Agent never started — re-dispatch |
+| No | — | Branch was cleaned up or never created — re-dispatch |
+
+### Step 4: Resume
+- Milestones marked `done` or with commits → proceed to Merge Protocol
+- Milestones needing re-dispatch → spawn new agents (same parameters as original dispatch)
+- Update `.claude/parallel-wave-state.md` with new statuses before re-dispatching
+
+### Step 5: Continue Normal Flow
+After resume completes, continue with Merge Protocol → Plan Update → Cleanup as usual.
+
+---
+
 ## Ownership Map Cleanup
 
 After wave merge is complete:
@@ -173,4 +245,7 @@ After wave merge is complete:
 # Remove ownership.md entries for the completed wave
 # (or replace the table with a merge record)
 echo "## Wave {N} merged — {timestamp}" >> .claude/ownership.md
+
+# CRITICAL: Delete wave state file — prevents false resume on next session
+rm -f .claude/parallel-wave-state.md
 ```

package/templates/commands/parallel.md

@@ -21,6 +21,18 @@ Load: `capabilities/shared/parallel-coordination.md`
 
 ---
 
+## Step 0: Check for Interrupted Wave
+
+```bash
+cat .claude/parallel-wave-state.md 2>/dev/null
+```
+
+If the file exists with `status: in-flight` → a previous parallel session was interrupted.
+Follow the **Resume Protocol** from `parallel-coordination.md` before starting a new wave.
+Only proceed to Step 1 after the interrupted wave is fully resolved (merged or re-dispatched).
+
+---
+
 ## Step 1: Parse Targets
 
 ```bash
@@ -68,9 +80,9 @@ If any milestone returns `Parallel Safe: NO` → exclude from parallel wave, run
 
 ---
 
-## Step 4: Write Ownership Map
+## Step 4: Write Ownership Map + Wave State
 
-Create or update `.claude/ownership.md`:
+**4a. Ownership map** — create or update `.claude/ownership.md`:
 
 ```
 ## Active Parallel Session — {ISO timestamp}
@@ -83,6 +95,24 @@ Initiated by: /parallel command
 | P2 | M{N} — {title} | parallel/m{n}-{slug} | {dirs from spec} | pending |
 ```
 
+**4b. Wave state file** — write `.claude/parallel-wave-state.md` BEFORE dispatching agents:
+
+```markdown
+---
+wave: {N}
+started: {ISO timestamp}
+status: in-flight
+milestones: [{list}]
+---
+
+| Milestone | Branch | Status | Commit | Notes |
+|-----------|--------|--------|--------|-------|
+| M{N} — {title} | parallel/m{n}-{slug} | running | — | P1 slot |
+| M{N} — {title} | parallel/m{n}-{slug} | running | — | P2 slot |
+```
+
+This file survives context compaction. If the session dies mid-wave, the next session reads this file to resume.
+
 ---
 
 ## Step 5: Dispatch All Agents Simultaneously
@@ -116,6 +146,7 @@ Worktree rules (MANDATORY):
 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
 
 ---
 
@@ -150,6 +181,7 @@ git branch -d parallel/{slug-1} parallel/{slug-2}
 
 Update `.claude/plan.md` — set merged milestones to `status: done`.
 Update `.claude/ownership.md` — replace active table with merge record.
+**Delete `.claude/parallel-wave-state.md`** — wave is complete, prevent false resume on next session.
 
 Show final report:
 ```

package/templates/commands/snapshot.md

@@ -17,6 +17,14 @@ This is different from `/persist` (end-of-session). Checkpoint = mid-flight snap
 
 Read `.claude/memory/goals.md` — scan the "In progress" entries and "Current threads."
 
+**Step 1b: Detect Active Parallel Wave**
+
+```bash
+cat .claude/parallel-wave-state.md 2>/dev/null
+```
+
+If the file exists → a parallel wave is active. Read it and include wave status in the checkpoint (Step 2).
+
 ---
 
 ## Step 2: Write Checkpoint File
@@ -48,6 +56,9 @@ files_in_progress: [{list from goals.md ## In progress}]
 
 ## Risk / open question
 {Anything uncertain that needs resolution — or "None"}
+
+## Active parallel wave (if any)
+{Copy the full contents of .claude/parallel-wave-state.md here, or "No active wave"}
 ```
 
 Create the directory if needed: `.claude/memory/checkpoints/`

package/templates/hooks/user-prompt.js

@@ -233,21 +233,34 @@ try {
         if (fs.existsSync(goalsPath)) {
           const goalsContent = fs.readFileSync(goalsPath, 'utf8');
           const header = `---\ndate: ${new Date().toISOString()}\nlabel: auto-compaction-guard-${pct}pct\nfiles_in_progress: []\n---\n\n`;
-          fs.writeFileSync(cpPath, header + '## Auto-saved before compaction\n\n' + goalsContent);
+          let cpContent = '## Auto-saved before compaction\n\n' + goalsContent;
+
+          // Include parallel wave state if an active wave exists
+          const waveStatePath = path.join(cfg, 'parallel-wave-state.md');
+          if (fs.existsSync(waveStatePath)) {
+            const waveContent = fs.readFileSync(waveStatePath, 'utf8');
+            cpContent += '\n\n## Active Parallel Wave (saved by compaction guard)\n\n' + waveContent;
+          }
+
+          fs.writeFileSync(cpPath, header + cpContent);
           fs.writeFileSync(autoSaveMarker, '');
         }
 
         console.log('');
         console.log(`--- COMPACTION GUARD (${pct}%) ---`);
         console.log(`Context at ${pct}% — AUTO-SAVED checkpoint to ${path.basename(cpPath)}`);
+        if (fs.existsSync(waveStatePath)) {
+          console.log('PARALLEL WAVE STATE INCLUDED — interrupted wave will auto-resume on next session.');
+        }
         console.log('Run /snapshot NOW to save your reasoning and decisions (goals.md alone is not enough).');
         console.log('--- END GUARD ---');
       }
     } else if (pct >= 70) {
       console.log('');
-      console.log(`--- COMPACTION WARNING (${pct}%) ---`);
-      console.log(`Context at ${pct}% — compaction approaching. Run /snapshot to save session state.`);
-      console.log('--- END WARNING ---');
+      console.log(`!!! SNAPSHOT REQUIRED (${pct}% context used) !!!`);
+      console.log(`Run /snapshot NOW — Claude will compact and lose your session reasoning soon.`);
+      console.log(`This warning repeats every message until you run /snapshot or context resets.`);
+      console.log(`!!! /snapshot !!! /snapshot !!! /snapshot !!!`);
     }
   }
 } catch (_) {}