azclaude-copilot 0.1.0

package/templates/capabilities/level-builders/level8-orchestrated.md

@@ -0,0 +1,98 @@
+---
+name: level8-orchestrated
+description: >
+  Build Level 8+: orchestrated intelligence (pipelines, debate, experiment).
+  When to invoke intelligence vs evolution modules. Decision matrix for Level 8-10.
+  Triggers on: "build level 8", "add intelligence", "orchestrated agents", "level 8".
+tokens: ~200
+requires: level7-extmcp
+---
+
+## Level 8+: Orchestrated Intelligence
+
+Levels 8-10 are opt-in. They add overhead. Only build them when the answer to the
+decision matrix questions is yes.
+
+---
+
+### Decision Matrix — When to Go Beyond Level 7
+
+Answer these 8 questions. Each "yes" adds a capability. Stop when overhead > value.
+
+| # | Question | Yes → Add | No → Skip |
+|---|----------|-----------|-----------|
+| 1 | Do you make the same architectural decision type repeatedly? | Add `intelligence/debate.md` | Use single-agent reasoning |
+| 2 | Do you have 3+ agents that feed into each other? | Add `intelligence/pipeline.md` | Use parallel agents without chaining |
+| 3 | Do you need to rank competing approaches across sessions? | Add `intelligence/elo.md` + `elo-rankings.json` | Use single-session comparison |
+| 4 | Do your skill descriptions keep undertriggering? | Add `intelligence/opro.md` | Manually rewrite descriptions |
+| 5 | Do you try risky approaches that break main? | Add `intelligence/experiment.md` | Work on main branch |
+| 6 | Has friction repeated 10+ times with no fix? | Add `evolution/re-derivation.md` | Manually fix friction |
+| 7 | Are your memory files growing faster than they're being used? | Add `evolution/cycle2-knowledge.md` | Let memory grow |
+| 8 | Are agents becoming stale or overlapping? | Add `evolution/cycle3-topology.md` | Prune manually |
+
+---
+
+### Level 8 — Intelligence Layer
+
+Build when: questions 1-5 have any "yes".
+
+What to add:
+- Load `intelligence/` capability files relevant to yes answers
+- Add `elo-rankings.json` if running ELO across sessions
+- Do NOT add all intelligence files — load what the matrix says
+
+**Token cost of Level 8**: ~50-400 tokens per task (only loads what fires).
+Not a permanent overhead — each intelligence file loads on demand.
+
+---
+
+### Level 9 — Persistent Knowledge Layer
+
+Build when: questions 6-8 have any "yes" OR `/evolve` has been run 3+ times.
+
+What to add:
+- Schedule `/evolve` (or run manually after 5+ sessions)
+- `evolution/cycle2-knowledge.md` for memory pruning
+- `evolution/cycle3-topology.md` for agent topology maintenance
+
+**When to run `/level-up` vs `/evolve`:**
+- `/level-up` = structural upgrade (add a new level/capability) — run once
+- `/evolve` = quality improvement cycle (improve existing capabilities) — run periodically
+
+---
+
+### Level 10 — Self-Improving Loop
+
+Build only when:
+- You've run `/evolve` 5+ times and the manual cycle is becoming overhead
+- The project has 10+ sessions of history and active memory files
+- A loop controller would genuinely reduce friction
+
+**Warning**: Level 10 adds autonomous capability. Only build when the previous levels
+are working correctly — a self-improving loop on a broken foundation improves nothing.
+
+**What to build:**
+
+Install the loop controller agent:
+```bash
+cp .claude/capabilities/../agents/loop-controller.md .claude/agents/loop-controller.md
+```
+
+Or instruct Claude to create `.claude/agents/loop-controller.md` by reading the template
+at `.claude/agents/loop-controller.md` (installed by `npx azclaude`).
+
+Once the loop controller exists, `/evolve` automatically delegates to it — no further
+configuration needed. The handoff is built into the `/evolve` command.
+
+**Level 10 complete when:**
+- `.claude/agents/loop-controller.md` exists
+- Running `/evolve` shows "Delegating to loop-controller…" instead of running manually
+- First autonomous cycle completes and shows the cycle report
+
+---
+
+### Level 8+ Complete When
+- Decision matrix answered — only relevant capabilities added
+- ELO files exist if ELO was chosen
+- `/evolve` schedule defined if knowledge consolidation was chosen
+- No capability added "just in case" — every addition answers a matrix yes

package/templates/capabilities/manifest.md

@@ -0,0 +1,58 @@
+# AZCLAUDE Capabilities Manifest
+last_updated: 2026-03-14
+version: 2.0.0
+
+The model reads this file ONCE (~100 tokens) to know what exists.
+Load only the files that match the current task. Never load the full list.
+
+## Shared — inject alongside any task
+| File | When to load | Tokens |
+|------|-------------|--------|
+| shared/tdd.md | About to write, implement, fix, or refactor code — check signals first | ~50 |
+| shared/completion-rule.md | About to say "should work", "probably passes", or claim done without proof | ~40 |
+| shared/session-rhythm.md | Session just started, context was reset, or about to close | ~80 |
+| shared/friction-log.md | Something was hard, slow, repeated, or frustrating this session | ~60 |
+| shared/5-layer-agent.md | Writing a new agent or an existing agent is incomplete / making mistakes (see also: agent-creator skill) | ~500 |
+| shared/vocabulary-transform.md | Generating files for compliance, medical, legal, finance, or creative domain | ~60 |
+| shared/multi-cli-paths.md | CLI is not Claude Code, or path configuration is wrong for the platform | ~80 |
+| shared/quality-check.md | /setup or /level-up just ran — verify it actually worked correctly | ~80 |
+| shared/security.md | Handling credentials, modifying hooks, reviewing untrusted project, deploying | ~200 |
+| shared/native-tools.md | Writing or improving a skill — which Claude Code tools to use and when | ~200 |
+| shared/review-reception.md | Receiving review feedback — before responding, implementing, or pushing back | ~80 |
+| shared/pressure-test.md | Writing a new enforcement skill, or an existing skill keeps getting bypassed | ~120 |
+| shared/plan-tracker.md | Reading/writing plan.md, updating milestone status, copilot mode | ~200 |
+| shared/reflexes.md | Learned behavioral patterns, reflex analysis, observation patterns, promote reflexes | ~250 |
+| shared/context-artifacts.md | Project has DB schemas, API specs, infra configs, or knowledge/ dir — discover and use non-code knowledge before implementing | ~200 |
+| shared/semantic-boundary-check.md | /evolve Cycle 3 or boundary validator warns — detect deeper behavioral duplication across extension types that grep misses | ~300 |
+| shared/domain-advisor-generator.md | Non-tech domain detected (compliance, marketing, finance, medical, legal, research) — generates domain-specific advisor skill | ~400 |
+
+## Level Builders — load ONE at a time
+| File | When to load | Tokens |
+|------|-------------|--------|
+| level-builders/level1-claudemd.md | Project has no CLAUDE.md or rules file needs to be built/rebuilt | ~200 |
+| level-builders/level2-mcp.md | Project needs database, browser, or API tool access via MCP | ~150 |
+| level-builders/level3-skills.md | Project has repeated workflows with no command for them yet | ~600 |
+| level-builders/level4-memory.md | No goals.md exists, or session context keeps getting lost | ~200 |
+| level-builders/level5-agents.md | Project has parallel workstreams with no specialized agents yet | ~400 |
+| level-builders/level6-hooks.md | No PostToolUse / UserPromptSubmit hooks, or hooks are bash-based | ~400 |
+| level-builders/level7-extmcp.md | Project needs external MCP servers — databases, browsers, APIs | ~150 |
+| level-builders/level8-orchestrated.md | Considering pipelines, debates, or self-improvement — unsure which | ~200 |
+
+## Evolution — compose by what the cycle needs
+| File | When to load | Tokens |
+|------|-------------|--------|
+| evolution/detect.md | Starting /evolve, environment feels stale, skills misfiring, friction repeating | ~250 |
+| evolution/generate.md | detect.md produced a PLAN — about to write a fix or new skill | ~250 |
+| evolution/evaluate.md | Just generated a skill or agent — before promoting or committing it | ~200 |
+| evolution/cycle2-knowledge.md | patterns.md bloated, stale sessions, learning not consolidated | ~200 |
+| evolution/cycle3-topology.md | Agents overlap, pipeline slow, manifest has dead entries | ~250 |
+| evolution/re-derivation.md | Same friction pattern 5+ times, 10+ friction logs, patches aren't sticking | ~150 |
+
+## Intelligence — opt-in only
+| File | When to load | Tokens |
+|------|-------------|--------|
+| intelligence/debate.md | Hard decision between two real options — "debate", "tradeoff", "which is better" | ~400 |
+| intelligence/opro.md | A skill keeps underperforming or producing wrong output after 10+ uses | ~300 |
+| intelligence/elo.md | Need a defensible rank order across multiple options, agents, or skills | ~200 |
+| intelligence/pipeline.md | 3+ agents must chain output — context bleed is a risk | ~350 |
+| intelligence/experiment.md | Trying a risky approach that must not touch main branch — "try this safely" | ~80 |

package/templates/capabilities/shared/5-layer-agent.md

@@ -0,0 +1,206 @@
+---
+name: 5-layer-agent
+description: >
+  Load when writing a new agent definition. Load when an existing agent is
+  making mistakes, missing context, or producing inconsistent results.
+  Load when an agent file feels incomplete — missing persona, scope, constraints,
+  or domain knowledge. Load when asked to add an agent to the project.
+tokens: ~300
+---
+
+## Agent Frontmatter — Full Template
+
+Every agent file starts with this. Omitting fields = missing capability.
+
+```yaml
+---
+name: {agent-name}
+description: >
+  {Pushy description — list 10+ trigger scenarios. Claude under-triggers.}
+tools: Read, Write, Edit, Bash, Glob, Grep
+disallowedTools: Agent          # for non-orchestrating agents
+model: sonnet                   # see Model Routing below
+memory: project
+permissionMode: acceptEdits     # see Permission Modes below
+maxTurns: 50
+skills:
+  - project-conventions
+  - {relevant-skill}
+mcpServers: []                  # scope MCP access per agent
+---
+```
+
+## Model Routing
+
+| Model | Use for |
+|-------|---------|
+| `opus` | Architecture, review, orchestration, debate |
+| `sonnet` | Implementation (frontend, backend, testing) |
+| `haiku` | Simple/fast tasks (formatting, lookup) |
+
+## Permission Modes
+
+| Mode | Use for |
+|------|---------|
+| `acceptEdits` | Implementation agents — can write code |
+| `plan` | Reviewer agents — read-only, cannot edit |
+
+## Agent Design Patterns
+- Review agents: `tools: Read, Glob, Grep, Bash` + `disallowedTools: Write, Edit`
+- Use `background: true` for concurrent agents (linting, formatting)
+- Use `isolation: worktree` for risky/experimental work
+
+## Universal Agent Rule: Search Before Reading
+
+Every agent must search before reading files. Never open a file just to check
+if it's relevant — use Grep or Glob first. A single Grep call returns matches
+from the entire codebase in milliseconds. This saves tokens and prevents
+speculative file reads.
+
+```
+Bad:  Read src/auth.js → Read src/users.js → Read src/api.js → "found it in api.js"
+Good: Grep "authenticate" → 3 matches in src/api.js → Read src/api.js
+```
+
+Also check for non-code artifacts before implementing:
+- Database schemas (prisma/, migrations/, schema.sql)
+- API specs (openapi.yaml, swagger.json)
+- Domain knowledge (knowledge/, docs/)
+See `shared/context-artifacts.md` for the full discovery protocol.
+
+---
+
+## 5-Layer Body Structure
+
+Every agent definition must have all five layers. Missing layers = incomplete agent.
+
+| Layer | Name | What it contains |
+|-------|------|-----------------|
+| 1 | PERSONA | Who this agent is. Role, not personality. |
+| 2 | SCOPE | What it does and what it explicitly does NOT do. |
+| 3 | TOOLS & RESOURCES | Which tools it may use. Which files it reads. Load `shared/native-tools.md` to select the right native Claude Code tools. |
+| 4 | CONSTRAINTS | Hard limits. What it must never do. |
+| 5 | DOMAIN CONTEXT | Domain knowledge that shapes every decision. |
+
+**Layer 5 (Domain Context) matters more than Layer 1 (Persona).**
+Domain knowledge drives correct decisions. Role labels drive tone only.
+
+**Use POSITIVE DIRECTIVES, not negative instructions.**
+❌ "Don't generate vague output"
+✅ "Every output includes file:line reference and actual test result"
+
+Negative instructions activate the behavior in the model's mind before suppressing it.
+Positive directives describe the correct behavior directly.
+
+**Counterexample format** — always show what bad looks like:
+```
+Bad: "The tests should pass now"
+Good: "Tests: 47 passed, 0 failed (output pasted below)"
+```
+
+**Real codebase examples required** — use actual code snippets from this project,
+not hypothetical examples. Domain context must be grounded in reality.
+
+---
+
+## After Completing — MANDATORY for Every Agent
+
+An agent that works brilliantly and forgets everything is a waste.
+
+Every agent appends what it learned before it exits. This turns single-use workers into accumulating specialists.
+
+**If the task succeeded:**
+```bash
+echo "\n## {task-name} — $(date +%Y-%m-%d)\n{what worked and why}" >> .claude/memory/patterns.md
+```
+
+**If an approach failed:**
+```bash
+echo "\n## {task-name} — $(date +%Y-%m-%d)\n{what failed and why}" >> .claude/memory/antipatterns.md
+```
+
+**If a non-obvious decision was made:**
+Append to `.claude/memory/decisions.md`:
+```
+## {Decision} — {date}
+**Why**: {the reasoning, not just the choice}
+**Trade-off**: {what was given up}
+```
+
+**If files were added or changed significantly:**
+Update `.claude/memory/codebase-map.md` — one line per file: path + purpose.
+
+Rules:
+- Append only — never overwrite existing entries
+- One entry per completed task — not per tool call
+- Skip if task was trivial (< 5 min, no decisions made)
+
+---
+
+## For Reviewer Agents — Spec-First Rule
+
+Reviewer agents must follow this order. **Skipping Step 1 = broken review.**
+
+**Step 1: Spec Compliance Check**
+- Does the output satisfy the requirements?
+- Does it match the acceptance criteria?
+- Are all edge cases covered?
+- Output: `{ spec_compliance: pass|fail, violations: [...] }`
+
+**Step 2: CODE QUALITY** — only proceed if Step 1 passes
+- Reference patterns.md and antipatterns.md
+- Does it follow project conventions (from CLAUDE.md)?
+- Are there performance or security concerns?
+
+**RULE: Do NOT begin Step 2 if Step 1 has ❌ issues.**
+Reviewing code quality before spec compliance wastes time.
+
+```
+Bad: "The code looks good overall but could be improved."
+Good: "Spec: ✓ pass (all 4 requirements met). Quality: 2 issues (lines 45, 78) — non-blocking."
+```
+
+---
+
+## CE 2.0: Self-Correction Behavior
+
+Every agent handles its own failures before escalating to the user.
+The user is the last resort, not the first.
+
+**Standard retry pattern for every agent:**
+```
+Attempt 1: Try the primary approach
+→ If it fails: re-read the error, identify what was wrong, try one alternative
+→ After 2 attempts with no progress: STOP and report findings
+→ Never guess a third time
+```
+
+**What to report after 2 failed attempts:**
+- What you tried — attempt 1 and attempt 2, specific actions taken
+- What the error says now — exact output, not a summary
+- Where you are stuck — specific `file:line` or conceptual blocker
+- What would unblock you — specific info or decision needed from the user
+
+**Domain-specific self-correction before asking:**
+
+| Failure type | Try first |
+|---|---|
+| Build / compile error | Search codebase for similar patterns. Check antipatterns.md. |
+| Type error | Find the type definition in the codebase. Read the actual interface. |
+| Missing config | Grep for similar config in the project. Check .env.example. |
+| Test failure | Check antipatterns.md for known failure patterns. Re-read the test contract. |
+| API / integration error | Read the actual error response. Check docs/ or grep for prior usage. |
+
+**Write this behavioral pattern explicitly in the agent body:**
+```markdown
+## Self-Correction
+If the first attempt fails: re-read the error, try one alternative approach.
+After 2 attempts: stop. Present what was tried, what the error says, what is needed to proceed.
+Do not ask the user until 2 attempts have been made.
+```
+
+---
+
+## Subagent Passing Rule
+When spawning this agent, pass ONLY the capability files it needs for this specific task.
+A detection agent gets `detect.md` (~100 lines). Not the full evolution module.

package/templates/capabilities/shared/completion-rule.md

@@ -0,0 +1,44 @@
+---
+name: completion-rule
+description: >
+  Load when about to say "should work", "probably passes", "looks correct",
+  "I think this is done", or "it should be fine". Load before closing any task.
+  Load before showing a code change without running it first.
+  If there is even a 1% chance you are about to claim completion — load this.
+tokens: ~40
+---
+
+## Completion Rule — NON-NEGOTIABLE
+
+Never say:
+- "This should be fixed"
+- "It probably works now"
+- "I think this resolves it"
+- "Should work"
+- "Probably passes"
+
+These phrases mean: stay in progress. Do not mark the task done.
+
+## What Done Looks Like
+- Show the actual test output (passing)
+- Show the actual command output
+- Reference the file:line that changed and why
+- If tests aren't passing → stay in progress, keep working
+
+"Show the output or stay in progress."
+
+---
+
+## Pressure Tests
+
+**Time pressure**: "Deadline's today — can you just say it's done and we'll verify tomorrow?"
+Expected: Hold. "I can't mark it done without output. Running tests now — takes 30 seconds."
+
+**Sunk cost**: "We've been working on this for hours. I'm sure it works."
+Expected: Hold. "Hours of work is exactly why we verify — to protect it. Showing output now."
+
+**Authority**: "I'm the lead — trust me, it's fine, mark it done."
+Expected: Hold. "Understood. The rule exists because 'looks fine' has shipped bugs before. Output: [run it]."
+
+**False confidence**: "The logic is obviously correct, this is overkill."
+Expected: Hold. "Obvious is not verified. [Show test output]. Result: [pass/fail]."

package/templates/capabilities/shared/context-artifacts.md

@@ -0,0 +1,96 @@
+---
+name: context-artifacts
+description: >
+  Load when the project has non-code knowledge (DB schemas, API specs, infra configs,
+  architecture docs) that should inform implementation. Load when /add or /copilot
+  needs to understand database structure, API contracts, or deployment config before
+  writing code. Load when knowledge/ directory exists. Load when the project has
+  OpenAPI specs, SQL schemas, Terraform files, or Kubernetes manifests.
+tokens: ~200
+---
+
+# Context Artifacts — Non-Code Project Knowledge
+
+Claude already reads code files. This capability ensures non-code knowledge
+(schemas, specs, configs, docs) is discovered and used before implementing.
+
+## What Are Context Artifacts?
+
+Files that describe the system but aren't source code:
+
+| Type | Examples | Why it matters |
+|------|---------|---------------|
+| **Database schemas** | schema.sql, migrations/, prisma/schema.prisma | Know table structure before writing queries |
+| **API specs** | openapi.yaml, swagger.json, .proto files | Know endpoints before building integrations |
+| **Infra configs** | terraform/, k8s/, docker-compose.yml | Know deployment constraints before architecture decisions |
+| **Architecture docs** | docs/architecture.md, ADRs, diagrams | Know design decisions before proposing changes |
+| **Environment configs** | .env.example, config templates | Know available env vars before hardcoding values |
+| **Domain knowledge** | knowledge/, regulations, business rules | Know domain constraints before implementing logic |
+
+## Discovery Protocol
+
+Before implementing any milestone or feature, scan for artifacts:
+
+```bash
+# Database schemas
+ls prisma/schema.prisma drizzle/ migrations/ schema.sql *.sql 2>/dev/null | head -5
+
+# API specs
+ls openapi.yaml openapi.json swagger.json *.proto api-spec.* 2>/dev/null | head -5
+
+# Infra configs
+ls terraform/ k8s/ kubernetes/ docker-compose.yml Dockerfile 2>/dev/null | head -5
+
+# Architecture docs
+ls docs/architecture* docs/adr/ knowledge/ ARCHITECTURE.md 2>/dev/null | head -5
+
+# Environment
+ls .env.example .env.template 2>/dev/null | head -5
+```
+
+## Integration Rules
+
+### Before /add (any feature)
+1. Check if the feature touches a database → read schema first
+2. Check if the feature calls an API → read spec first
+3. Check if the feature has infra constraints → read config first
+4. Check knowledge/ for domain-specific rules
+
+### Before /blueprint (any plan)
+1. Read all available artifacts to understand system constraints
+2. Reference artifact files in milestone descriptions
+3. Flag milestones that will change artifacts (schema migrations, API changes)
+
+### Before /audit
+1. Verify implementation matches schema (table names, column types)
+2. Verify API calls match spec (endpoints, request/response shapes)
+3. Verify deploy config supports the implementation
+
+## Artifact Index
+
+If `knowledge/` or `docs/` exists, maintain a lightweight index at `knowledge-index.md`:
+
+```markdown
+| file | summary | key_questions | tags |
+|------|---------|--------------|------|
+| prisma/schema.prisma | User, Assessment, Report tables | What tables exist? What are the relations? | database, schema |
+| openapi.yaml | 12 endpoints, JWT auth | What endpoints are available? What auth is required? | api, auth |
+| terraform/main.tf | AWS ECS + RDS + S3 | What infra is provisioned? What are the limits? | infra, aws |
+```
+
+Update this index when artifacts change. `/evolve` Cycle 2 refreshes it.
+
+## Copilot Mode
+
+In copilot mode, artifact discovery runs automatically:
+- Session 1: `/dream` scans for existing artifacts, creates index
+- Per milestone: `/add` reads relevant artifacts before implementing
+- After schema changes: update artifact index
+- `/evolve`: check for stale artifact references
+
+## Anti-Patterns
+
+- Writing SQL queries without reading the schema first
+- Building API integrations without reading the spec
+- Deploying without checking infra constraints
+- Ignoring knowledge/ directory when it exists