azclaude-copilot 0.4.40 → 0.5.1

package/.claude-plugin/marketplace.json

@@ -8,8 +8,8 @@
   "plugins": [
     {
       "name": "azclaude",
-      "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 37 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.4.40",
+      "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.0",
       "source": {
         "source": "github",
         "repo": "haytamAroui/AZ-CLAUDE-COPILOT",

package/.claude-plugin/plugin.json

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

package/README.md

@@ -627,7 +627,7 @@ evidence_count: 6
 
 ---
 
-## All 37 Commands
+## All 39 Commands
 
 ### Build and Ship
 
@@ -758,11 +758,11 @@ An agent is a sub-process. Use one when work must happen **in parallel** or **in
 
 ## Verified
 
-1609 tests. Every template, command, capability, agent, hook, and CLI feature verified.
+1758 tests. Every template, command, capability, agent, hook, and CLI feature verified.
 
 ```bash
 bash tests/test-features.sh
-# Results: 1609 passed, 0 failed, 1609 total
+# Results: 1758 passed, 0 failed, 1758 total
 ```
 
 ---

package/bin/cli.js

@@ -441,6 +441,48 @@ function installScripts(projectDir, cfg) {
   ok(`Scripts installed/updated (${cfg}/scripts/)`);
 }
 
+// ─── Statusline (auto-updating cost/context bar) ─────────────────────────────
+
+function installStatusline(projectDir, cfg) {
+  const scriptSrc = path.join(TEMPLATE_DIR, 'scripts', 'statusline.js');
+  if (!fs.existsSync(scriptSrc)) return;
+
+  // Copy statusline script to ~/.claude/statusline.js (global — shared across projects)
+  const globalDir = path.join(os.homedir(), '.claude');
+  const scriptDst = path.join(globalDir, 'statusline.js');
+  fs.mkdirSync(globalDir, { recursive: true });
+  fs.copyFileSync(scriptSrc, scriptDst);
+
+  // Remove old .sh version if it exists (migrating from v0.5.0)
+  const oldSh = path.join(globalDir, 'statusline.sh');
+  try { if (fs.existsSync(oldSh)) fs.unlinkSync(oldSh); } catch {}
+
+  // Configure in global settings.json (statusLine is a global Claude Code setting)
+  const nodeExe = process.execPath;
+  const settingsPath = path.join(globalDir, 'settings.json');
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch {}
+  }
+
+  // Always update the command to use Node.js (migrates from old .sh version)
+  const scriptPath = scriptDst.replace(/\\/g, '/');
+  const nodePath   = nodeExe.replace(/\\/g, '/');
+  const needsUpdate = !settings.statusLine
+    || (settings.statusLine.command && settings.statusLine.command.includes('statusline.sh'));
+  if (needsUpdate) {
+    settings.statusLine = {
+      type: 'command',
+      command: `"${nodePath}" "${scriptPath}"`,
+      padding: 1
+    };
+    atomicWriteFileSync(settingsPath, JSON.stringify(settings, null, 2));
+    ok('Statusline installed (Node.js) — context %, rate limit, session time visible after every turn');
+  } else {
+    info('Statusline already configured — script refreshed');
+  }
+}
+
 // ─── Agents ───────────────────────────────────────────────────────────────────
 
 const AGENTS = ['orchestrator-init', 'code-reviewer', 'test-writer', 'loop-controller', 'cc-template-author', 'cc-cli-integrator', 'cc-test-maintainer', 'orchestrator', 'problem-architect', 'milestone-builder', 'security-auditor', 'spec-reviewer', 'constitution-guard', 'devops-engineer', 'qa-engineer'];
@@ -955,6 +997,20 @@ function runDoctor() {
     chk(`${cli.rulesFile} filled (no {{placeholders}})`,    !r.includes('{{'));
   }
 
+  // ── Statusline ──────────────────────────────────────────────────────────
+  console.log('\n[ Statusline ]');
+  const statuslineScript = path.join(os.homedir(), '.claude', 'statusline.js');
+  chk('statusline.js exists (~/.claude/statusline.js)',        fs.existsSync(statuslineScript));
+  if (cli.hooksDir) {
+    const globalSettingsPath = path.join(cli.hooksDir, 'settings.json');
+    if (fs.existsSync(globalSettingsPath)) {
+      try {
+        const gs = JSON.parse(fs.readFileSync(globalSettingsPath, 'utf8'));
+        chk('statusLine configured in settings.json',          !!gs.statusLine);
+      } catch { chk('statusLine configured in settings.json', false); }
+    }
+  }
+
   // ── Commands ─────────────────────────────────────────────────────────────
   console.log('\n[ Commands ]');
   const cmdDir    = path.join(projectDir, cfg, 'commands');
@@ -1126,6 +1182,7 @@ installCapabilities(projectDir, cli.cfg, fullInstall);
 installCommands(projectDir, cli.cfg);
 installSkills(projectDir, cli.cfg);
 installScripts(projectDir, cli.cfg);
+installStatusline(projectDir, cli.cfg);
 installAgents(projectDir, cli.cfg);
 installRulesFile(projectDir, cli.cfg, cli.rulesFile);
 createDirectories(projectDir, cli.cfg);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "azclaude-copilot",
-  "version": "0.4.40",
+  "version": "0.5.1",
   "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/CLAUDE.md

@@ -58,6 +58,40 @@ When running parallel agents (/copilot with parallel waves, or /parallel):
 
 Unknown capability → grep manifest.md by description, load match
 
+## Agent Auto-Dispatch
+Agents live in `.claude/agents/`. Spawn them via the Agent tool with the matching `subagent_type`.
+**You MUST spawn the matching agent when these conditions are met — do not handle these tasks yourself.**
+
+| Condition | Agent to spawn | Why |
+|-----------|---------------|-----|
+| Task touches 3+ files or crosses module boundaries | `problem-architect` | Pre-flight analysis: team spec, risks, file ownership |
+| Architecture decision between 2+ real options | `architecture-advisor` (skill) | Evidence-based trade-off analysis, not gut feeling |
+| Code was written or modified | `code-reviewer` | Catches bugs, security issues, style violations |
+| Code needs test coverage | `test-writer` | Generates tests matching project framework + patterns |
+| Task spans 2+ milestones or needs parallel work | `orchestrator` | Owns plan.md, dispatches milestone-builder agents |
+| Security-sensitive change (auth, keys, hooks, deploy) | `security-auditor` | 111-rule scan, structured report with file:line refs |
+| Infrastructure, CI/CD, Docker, deploy config | `devops-engineer` | Pipeline, container, cloud infrastructure specialist |
+| Test strategy, E2E, release readiness | `qa-engineer` | Risk-based coverage, acceptance criteria validation |
+| Spec file provided for planning | `spec-reviewer` | Validates spec quality before /blueprint uses it |
+| Milestone about to be implemented | `constitution-guard` | Checks milestone against constitution.md non-negotiables |
+
+**Mandatory pipeline for ALL code tasks (enforced by hook on every message):**
+1. **ALWAYS** spawn `problem-architect` FIRST → get Team Spec (agents, skills, files, risks)
+2. Follow Team Spec exactly: load listed skills, pre-read listed files, in order
+3. If structural decision flagged → spawn `architecture-advisor` skill or run /debate
+4. Implement following Team Spec patterns
+5. **ALWAYS** spawn `code-reviewer` after implementation
+6. **ALWAYS** spawn `test-writer` if tests are needed
+
+**Skip pipeline only if:** message is a pure question with no action verb (e.g., "what does this function do?").
+**Never skip for:** any code change, no matter how small. The pipeline catches bugs in 1-line changes too.
+
+**Self-healing:** If problem-architect's Team Spec lists a MISSING skill or agent (domain expertise not installed):
+- Use `skill-creator` to generate the missing skill before implementation
+- Use `agent-creator` to generate the missing agent before implementation
+- The created skill/agent is immediately available and persists for all future tasks
+- Example: task needs GraphQL expertise → no GraphQL skill exists → skill-creator generates one → use it
+
 ## Trade-Off Hierarchies
 When priorities conflict:
 1. {{PRIORITY_1}}

package/templates/agents/cc-cli-integrator.md

@@ -12,10 +12,13 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 disallowedTools: [Agent]
 permissionMode: acceptEdits
 maxTurns: 40
+tags: [cli, install, hook, routing, copilot-runner]
 ---
 
 ## Layer 1: PERSONA
 
+<instructions>
+
 CLI integration specialist. Wires new commands and features into the AZCLAUDE
 CLI toolchain (`bin/cli.js`, `bin/copilot.js`). Ensures new template commands
 are routable, new agents are installable, and the copilot runner handles all
@@ -97,6 +100,8 @@ SKILLS            = ['session-guard', 'test-first', 'env-scanner', 'debate', 'se
 The `installAgents()` function copies from `templates/agents/{name}.md` to
 `{project}/.claude/agents/{name}.md` with path substitution.
 
+</instructions>
+
 ## Self-Correction
 
 If CLI changes break tests: read the failing test assertion, compare with

package/templates/agents/cc-template-author.md

@@ -12,8 +12,13 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 disallowedTools: [Agent]
 permissionMode: acceptEdits
 maxTurns: 40
+tags: [template, command, capability, markdown, azclaude]
 ---
 
+# CC Template Author
+
+<instructions>
+
 ## Layer 1: PERSONA
 
 Template author for AZCLAUDE Copilot. Writes precise, machine-readable markdown
@@ -107,3 +112,5 @@ that Claude Code follows during autonomous sessions (no human in the loop).
 If tests fail after template change: re-read the test expectations from
 `tests/test-features.sh`, fix the template to match, re-run.
 After 2 attempts: stop and report what the test expects vs what the template has.
+
+</instructions>

package/templates/agents/cc-test-maintainer.md

@@ -12,10 +12,13 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 disallowedTools: [Agent]
 permissionMode: acceptEdits
 maxTurns: 40
+tags: [test, grep, assertion, test-features, coverage]
 ---
 
 ## Layer 1: PERSONA
 
+<instructions>
+
 Test maintainer for AZCLAUDE Copilot. Writes and maintains grep-based tests
 in `tests/test-features.sh`. Every template, command, capability, and CLI
 feature must have test coverage before commit.
@@ -94,6 +97,8 @@ echo "  Results: $PASS passed, $FAIL failed, $((PASS + FAIL)) total"
 
 **Current test count: 862. Every new feature adds to this.**
 
+</instructions>
+
 ## Self-Correction
 
 If a new test fails: read the file it's testing, verify the grep pattern

package/templates/agents/code-reviewer.md

@@ -10,8 +10,13 @@ tools: [Read, Glob, Grep, Bash]
 disallowedTools: [Write, Edit, Agent]
 permissionMode: plan
 maxTurns: 30
+tags: [review, pr, quality, lint, feedback]
 ---
 
+# Code Reviewer
+
+<instructions>
+
 ## Layer 1: PERSONA
 
 Code review specialist. Read-only — never modifies code, only reports findings.
@@ -113,6 +118,10 @@ if [ -f pytest.ini ] || [ -f pyproject.toml ]; then python -m pytest 2>&1 | tail
 - If uncertain after re-reading, downgrade BLOCKING to NOTE
 - Only BLOCKING findings you would bet on survive this step
 
+</instructions>
+
+<output_format>
+
 ## Output Format
 
 ```
@@ -131,6 +140,8 @@ if [ -f pytest.ini ] || [ -f pyproject.toml ]; then python -m pytest 2>&1 | tail
 ### Verdict: APPROVE | REQUEST_CHANGES | NEEDS_TESTS
 ```
 
+</output_format>
+
 ## Self-Correction
 If test command fails to run: try alternative test runners.
 After 2 attempts: report the test setup issue as a BLOCKING finding.

package/templates/agents/constitution-guard.md

@@ -8,10 +8,13 @@ description: >
   Spawned by /copilot before each milestone is dispatched to milestone-builder.
 model: haiku
 tools: [Read, Grep, Glob]
+tags: [constitution, compliance, non-negotiable, gate, block]
 ---
 
 # Constitution Guard — Pre-Implementation Compliance Gate
 
+<instructions>
+
 You read the constitution. You check the milestone. You block violations before they ship.
 You never write code. You never modify anything. You return a verdict.
 
@@ -93,6 +96,10 @@ Does the milestone `Commit:` field suggest the definition of done will NOT be me
 
 ---
 
+</instructions>
+
+<output_format>
+
 ## Verdict Format
 
 ```
@@ -113,6 +120,8 @@ If APPROVED: `VERDICT: APPROVED` and nothing else.
 If VIOLATION: list only the violated rules with one-line explanation each.
 A VIOLATION causes /copilot to log the milestone to blockers.md and skip it pending human review.
 
+</output_format>
+
 ---
 
 ## After Completing

package/templates/agents/devops-engineer.md

@@ -11,10 +11,13 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 disallowedTools: [Agent]
 permissionMode: acceptEdits
 maxTurns: 40
+tags: [ci, docker, deploy, kubernetes, pipeline, infrastructure]
 ---
 
 ## Layer 1: PERSONA
 
+<instructions>
+
 DevOps specialist. Owns CI/CD pipelines, containerization, infrastructure as code,
 monitoring, and deployment procedures. Makes deployments boring and outages rare.
 Never introduces manual steps in deployment — everything is code and automation.
@@ -151,6 +154,10 @@ act --list 2>&1 | head -20
 grep -r "password\|secret\|api_key\|token" --include="*.yml" --include="*.yaml" . | grep -v "env\.\|secrets\.\|#"
 ```
 
+</instructions>
+
+<output_format>
+
 ## Output Format
 
 ```
@@ -173,6 +180,8 @@ Open questions (if any):
 - {question that requires project-specific knowledge}
 ```
 
+</output_format>
+
 ## Self-Correction
 If a pipeline config can't be validated locally: document the assumption clearly.
 If the stack is ambiguous: read CLAUDE.md and package.json before asking.

package/templates/agents/loop-controller.md

@@ -12,10 +12,13 @@ description: >
 model: opus
 tools: [Read, Write, Edit, Bash, Glob, Grep, Agent]
 maxTurns: 100
+tags: [evolve, iterate, gap-detect, topology, knowledge]
 ---
 
 ## Loop Controller — Level 10
 
+<instructions>
+
 This agent runs autonomously. All logic lives in the capability files — this agent
 loads them on demand and orchestrates the sequence. It does not duplicate content.
 
@@ -96,6 +99,9 @@ Skip if: Cycle 1 PLAN was empty AND no topology friction detected.
 
 ## Completion Rule
 
+</instructions>
+
+<output_format>
 Show the full cycle report:
 ```
 Evolution Cycle Complete
@@ -116,3 +122,4 @@ Next actions: {top 3}
 
 Update `.claude/memory/goals.md` with next actions.
 Never say "evolution complete" without showing the metrics.
+</output_format>

package/templates/agents/milestone-builder.md

@@ -9,10 +9,13 @@ description: >
 model: sonnet
 permissionMode: acceptEdits
 tools: [Read, Write, Edit, Bash, Grep, Glob]
+tags: [implement, build, code, commit, milestone]
 ---
 
 # Milestone Builder — The Builder
 
+<instructions>
+
 You implement. You receive complete context before starting.
 You never decide what to build — orchestrator and architect decided that.
 You decide HOW to build it.
@@ -134,6 +137,7 @@ git push
 
 Report to orchestrator:
 
+<output_format>
 ```
 ## Milestone {N} — {title}: COMPLETE
 
@@ -154,6 +158,7 @@ PASS — {N} tests passing
 ### New Anti-Patterns Discovered
 {anti-pattern description} — or "none"
 ```
+</output_format>
 
 **Worktree coordination errors** (errors in files outside your declared scope):
 - DO NOT attempt to fix them
@@ -170,3 +175,5 @@ PASS — {N} tests passing
 - **ALWAYS show test output.** Never say "tests should pass."
 - **NEVER commit without passing tests.** Failing tests → report to orchestrator.
 - Commit message: `{type}: {what} — {why}`
+
+</instructions>

package/templates/agents/orchestrator-init.md

@@ -5,9 +5,12 @@ description: >
   Analyzes the project, fills CLAUDE.md, creates goals.md, installs capabilities.
   Does NOT persist between sessions — not a routing agent.
 tokens: ~400
+tags: [setup, init, onboarding, first-run, project-scan]
 ---
 
-## Project Initialization
+# Project Initialization
+
+<instructions>
 
 This agent runs once. After setup is complete, it exits.
 It does NOT sit in memory between sessions. There is no persistent orchestrator.
@@ -191,6 +194,11 @@ Create `knowledge-index.md`:
 ---
 
 ## Completion Rule
+
+</instructions>
+
+<output_format>
 Print the filled CLAUDE.md content.
 Print goals.md content.
 Show both files as proof — do not say "setup complete" without showing them.
+</output_format>

package/templates/agents/orchestrator.md

@@ -8,10 +8,13 @@ description: >
   Model: sonnet by default — use --deep flag for opus on complex projects.
 model: sonnet
 tools: [Read, Grep, Glob, Bash, Task, AskUserQuestion]
+tags: [copilot, dispatch, milestone, autonomous, tech-lead]
 ---
 
 # Orchestrator — The Tech Lead
 
+<instructions>
+
 You direct. You never code. Your job is DECISIONS, not implementation.
 
 ## Session Loop
@@ -211,3 +214,5 @@ After all non-blocked milestones complete:
 - **ALWAYS run /debate** for technology choices that lock future milestones.
 - You OWN plan.md. No other agent modifies milestone status.
 - You CAN create new agents if /evolve reveals a gap mid-run.
+
+</instructions>

package/templates/agents/problem-architect.md

@@ -7,11 +7,14 @@ description: >
   NEVER implements. NEVER writes to project files. Read-only analysis only.
   Spawned by orchestrator before every milestone dispatch.
 model: sonnet
-tools: [Read, Grep, Glob, Bash]
+tools: [Read, Grep, Glob, Bash, WebSearch, WebFetch]
+tags: [analyze, scope, team-spec, complexity, pre-flight]
 ---
 
 # Problem Architect — The Analyst
 
+<instructions>
+
 You analyze. You never build.
 Given a milestone, you return exactly what the implementation team needs.
 
@@ -53,6 +56,20 @@ Also read:
 
 ---
 
+### Step 2b: Web Research (MANDATORY for unfamiliar technologies)
+
+If the milestone involves ANY technology, framework, API, or library:
+1. **WebSearch** for "{technology} best practices {current year}" and "{technology} common pitfalls"
+2. **WebFetch** the official documentation page for the specific API/library version in use
+3. Note any breaking changes, deprecations, or migration guides that affect this milestone
+
+**Why this step is mandatory:** Claude's training data is frozen. APIs change, libraries release breaking
+versions, and best practices evolve. A 30-second web search prevents hours of debugging deprecated code.
+
+**Skip only if:** the technology is pure internal code with no external dependencies.
+
+---
+
 ### Step 3: Identify What's Needed
 
 **Agents:**
@@ -65,6 +82,9 @@ If milestone crosses 2+ agent boundaries → recommend sequential: agent-A first
 - Touches auth/payments/secrets? → security
 - Architecture decision? → architecture-advisor
 - Domain-specific knowledge? → domain advisor (if exists in .claude/skills/)
+- **GAP DETECTION:** If this milestone needs domain expertise not covered by any installed skill
+  (e.g., GraphQL, Stripe, i18n, accessibility, ML pipeline), mark it as MISSING in the Team Spec.
+  The orchestrator will use skill-creator to generate it before dispatch.
 
 **Pre-Read Files:**
 - Schema files (if touching DB)
@@ -95,6 +115,9 @@ A missed file here causes silent data loss.
 
 ### Step 4: Return Team Spec
 
+</instructions>
+
+<output_format>
 Output this EXACT format — the orchestrator parses it:
 
 ```
@@ -108,6 +131,10 @@ Output this EXACT format — the orchestrator parses it:
 ### Skills to Load
 - {skill-name}: because {specific reason tied to this milestone}
 
+### Missing Skills (GAP — create before dispatch)
+- {domain/technology}: needed because {reason} — use skill-creator to generate
+  (omit this section if all needed skills are installed)
+
 ### Pre-Read Files
 - {file-path}: for {specific context reason}
 
@@ -135,6 +162,7 @@ If NO: reason = {specific conflict — shared file, schema dependency, runtime o
 The orchestrator uses this to decide whether to use worktree isolation or sequential dispatch.
 Parallel Safe = YES requires: isolated directories, no shared config/schema, no runtime dependency on a sibling milestone.
 ```
+</output_format>
 
 ---
 

package/templates/agents/qa-engineer.md

@@ -12,10 +12,13 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 disallowedTools: [Agent]
 permissionMode: acceptEdits
 maxTurns: 50
+tags: [qa, e2e, playwright, acceptance, regression, release]
 ---
 
 ## Layer 1: PERSONA
 
+<instructions>
+
 QA specialist. Owns test strategy, risk-based coverage, E2E automation, and release
 readiness. Goes beyond writing tests — defines what to test, at which level, and
 whether the product is ready to ship. Never blocks a release without documented evidence.
@@ -150,6 +153,10 @@ npx cypress run 2>&1 | tail -30
 npx playwright test --repeat-each=3 2>&1 | grep -E "passed|failed|flaky"
 ```
 
+</instructions>
+
+<output_format>
+
 ## Output Format
 
 **E2E tests:**
@@ -181,6 +188,8 @@ Result: {N} passed, {N} failed
 Blocked by: {issue title + severity} (if applicable)
 ```
 
+</output_format>
+
 ## Self-Correction
 If test framework is unknown: detect from package.json before writing any tests.
 If tests fail after writing: read the error, fix the test, re-run once. Report if still failing.

package/templates/agents/security-auditor.md

@@ -14,10 +14,13 @@ tools: [Read, Grep, Glob, Bash]
 disallowedTools: [Write, Edit, Agent]
 permissionMode: plan
 maxTurns: 40
+tags: [security, scan, secrets, permissions, mcp, supply-chain]
 ---
 
 ## Layer 1: PERSONA
 
+<instructions>
+
 Security auditor. Read-only — never modifies files, never executes arbitrary code.
 Scans Claude Code environments for security issues using native tools only.
 Reports findings as `file:line — rule-id — description`. No speculation — only flag what is confirmed in files.
@@ -399,6 +402,10 @@ Include supply chain findings in the report under "### SUPPLY CHAIN (advisory)"
 
 ---
 
+</instructions>
+
+<output_format>
+
 ## Scoring & Output
 
 After all 5 categories:
@@ -449,3 +456,5 @@ PROCEED  → grade C or D, zero BLOCKED findings
 - If a category has no findings: write `{category}: clean`
 - Never write "likely" or "possibly" — only confirmed findings
 - Each BLOCKED finding must include a one-line Fix instruction
+
+</output_format>

package/templates/agents/spec-reviewer.md

@@ -7,10 +7,13 @@ description: >
   Spawned by /blueprint when a spec file is provided as input.
 model: haiku
 tools: [Read, Grep, Glob]
+tags: [spec, validate, acceptance-criteria, quality-gate]
 ---
 
 # Spec Reviewer — Quality Gate Before Planning
 
+<instructions>
+
 You read specs. You validate them. You never write code, never modify the spec.
 Your job: prevent /blueprint from planning against an ambiguous or incomplete spec.
 
@@ -89,6 +92,10 @@ and machine implementation. Your standards:
 
 ---
 
+</instructions>
+
+<output_format>
+
 ## Verdict Format
 
 Return EXACTLY this block:
@@ -114,6 +121,8 @@ VERDICT: APPROVED
 If APPROVED: output `VERDICT: APPROVED` and nothing else.
 If not APPROVED: list ONLY the failing criteria with one-line gap description each.
 
+</output_format>
+
 ---
 
 ## After Completing