azclaude-copilot 0.1.0

package/templates/capabilities/level-builders/level3-skills.md

@@ -0,0 +1,276 @@
+---
+name: level3-skills
+description: >
+  Build Level 3: create project-specific skills and commands.
+  Triggers on: "build level 3", "add skill", "create command", "automate workflow".
+tokens: ~250
+requires: level2-mcp
+---
+
+## Level 3: Skills and Commands
+
+Skills are invoked by the user (/command). Each skill is a self-contained instruction set.
+Skills are Layer 2 in the progressive disclosure model — loaded only when invoked.
+
+---
+
+### 3-Level Progressive Disclosure
+
+Skills load in layers. Never dump the full body into context prematurely.
+
+| Layer | What loads | When |
+|-------|-----------|------|
+| 1 — Metadata | Frontmatter description only (~20 words) | Session start — always |
+| 2 — Body | Full skill instructions (≤ 500 lines) | When skill is invoked |
+| 3 — References | `references/` subdirectory files | Only when body explicitly links to them |
+
+**The `references/` subdir**: complex skills can have a `references/` folder next to the skill file containing large lookup tables, code templates, or spec extracts. The skill body links to these — they never auto-load.
+
+```
+.claude/commands/
+  add-endpoint.md          ← Layer 2 body
+  references/
+    endpoint-template.ts   ← Layer 3 (only loads if body says "read references/endpoint-template.ts")
+```
+
+---
+
+### The Pushy Description Rule
+
+**Claude undertriggers skills.** The description is the only thing read at Layer 1 — it must aggressively list every scenario that should activate the skill.
+
+**Bad description (undertriggers):**
+```yaml
+description: >
+  Add a new React component to the project.
+```
+This only fires when the user says "add a React component". Misses: "new page", "new screen", "build a form", "create a UI for X".
+
+**Good description (pushes back):**
+```yaml
+description: >
+  Add a new React component, page, screen, or UI element.
+  Triggers on: "new component", "new page", "new screen", "build a form",
+  "create a UI", "add a view", "make a <anything> component".
+  Use this whenever a new .tsx file needs to be created with project conventions.
+```
+
+Rule: **List 10+ trigger scenarios. Overtriggering is better than undertriggering.**
+
+---
+
+### RECIPE vs REFERENCE — The Fundamental Distinction
+
+**CLAUDE.md = what exists (REFERENCE)**
+**Skills = how to do things (RECIPE)**
+
+| If the sentence starts with… | It belongs in… |
+|------------------------------|----------------|
+| "The project has…" / "This repo uses…" | CLAUDE.md (REFERENCE) |
+| "To add a…" / "When creating a…" / "Run these steps to…" | Skill file (RECIPE) |
+
+**Test before writing**: Ask "Is this describing the state of the project, or the steps to accomplish something?" State → CLAUDE.md. Steps → Skill.
+
+Mixing them creates skills that read like documentation and documents that read like instructions — both become useless.
+
+---
+
+### Anatomy of a Skill File
+
+Every skill file requires:
+```yaml
+---
+name: {skill-name}
+description: [One clear sentence — what it does and when]
+argument-hint: "[what arguments it expects]"      # shows in autocomplete
+disable-model-invocation: true                    # omit for auto-triggered skills
+allowed-tools: Read, Grep, Bash                   # scoped permissions for this skill
+---
+
+## /{skill-name} — Title
+
+$ARGUMENTS
+
+[body — ≤ 500 lines]
+[reference pointers if needed: "For endpoint template, read references/endpoint-template.ts"]
+```
+
+**All frontmatter fields:**
+
+| Field | Required | Use when |
+|-------|----------|----------|
+| `name` | No | Defaults to filename. Set to override. |
+| `description` | Yes | One sentence — what it does. Claude uses this for auto-triggering. |
+| `argument-hint` | Recommended | Skill takes arguments — shows in `/` autocomplete. |
+| `disable-model-invocation: true` | For manual commands | Prevents auto-triggering. Use for destructive or session-ending commands. |
+| `allowed-tools` | Recommended | Scope permissions. Read-only skills: `Read, Grep`. Build skills: `Read, Write, Edit, Bash`. |
+| `context: fork` | For heavy commands | Runs in isolated subagent. Use for long autonomous tasks (/evolve, /dream). |
+| `user-invocable: false` | For background knowledge | Hides from `/` menu. Use for internal reference-only skills. |
+
+**Dynamic injection** — inject real data before Claude reads the skill:
+```markdown
+## Current state
+!`git log --oneline -5`
+!`bash .claude/scripts/env-scan.sh 2>/dev/null`
+```
+The `!`command`` syntax runs the shell command immediately. Claude only sees the output — not the command. Use for `/pulse`, `/setup`, any skill that needs live project data.
+
+**`ultrathink`** — include this word anywhere in the skill body to enable extended thinking for that skill.
+
+**Body must include** (for RECIPE skills):
+- Step-by-step instructions with exact commands
+- Code templates (inline if short, reference link if long)
+- Decision trees (if X then Y else Z)
+- Anti-patterns with explicit "do NOT" labels
+- Completion rule: what the user sees as proof of completion
+
+---
+
+### What Makes a Good Skill
+
+1. **Single responsibility** — one skill does one thing
+2. **Self-contained** — reads what it needs explicitly, doesn't assume other files are loaded
+3. **Thin router or direct executor**:
+   - Thin router: "load capabilities/X.md and run it" (evolve.md, debate.md)
+   - Direct executor: contains the full instruction (fix.md, persist.md)
+4. **Pushy description** — 3+ trigger variants listed
+5. **Completion Rule enforced** — every skill ends with a concrete output requirement
+6. **Self-correction wired in** — see CE 2.0 Self-Correction below
+
+---
+
+### CE 2.0 Self-Correction — Three Layers
+
+Written instructions alone drift. These three layers make self-correction structural:
+
+**Layer 1 — Bash exit-code gate (automatic, no judgment required)**
+```bash
+{command}; EXIT=$?
+if [ $EXIT -ne 0 ]; then echo "FAILED — do not proceed"; fi
+```
+Use in any skill that runs a command and must not proceed on failure.
+The gate catches the failure mechanically — Claude cannot "feel" that it passed.
+
+**Layer 2 — Structured checkpoint (forced self-assessment before proceeding)**
+```
+Root cause: [file:line]
+Mechanism:  [why it breaks]
+Fix:        [what will change]
+Confidence: [high / medium / low]
+```
+Placed at Phase 3 of diagnostic skills. If confidence = low → skill loops back.
+Forces Claude to commit to a hypothesis before writing code.
+
+**Layer 3 — Structured escalation after 2 attempts (not prose)**
+```
+Attempt 1: [file:line — what was changed]
+Result 1:  [exact error output]
+
+Attempt 2: [file:line — what was changed]
+Result 2:  [exact error output]
+
+Stuck at:  [file:line]
+Need:      [specific info or decision that would unblock this]
+```
+After 2 failed attempts, report this format — not "I'm sorry, I couldn't fix it."
+Structured output lets the user unblock the agent in one reply.
+
+**When to apply each layer:**
+| Layer | Apply when |
+|-------|-----------|
+| Exit-code gate | Any skill that runs bash and must not proceed on failure |
+| Structured checkpoint | Diagnostic skills (fix, debug, investigate) |
+| Structured escalation | Any skill with a retry loop |
+
+---
+
+### Command Design — Encode Decisions, Not Delegation
+
+**Test**: If deleting the command and telling the agent directly gives the same result → the command adds no value. Rewrite it.
+
+**Bad command (thin delegator):**
+```
+## /add-feature
+Tell the user to plan the feature, write tests, implement it, and open a PR.
+```
+This delegates work back to Claude with no constraints. Claude will ask clarifying questions instead of acting.
+
+**Good command (encodes the decision tree):**
+```
+## /add-feature
+1. Read CLAUDE.md → identify domain and stack
+2. If domain = developer → check tdd.md Iron Law first (tests before code)
+3. Identify affected modules from $ARGUMENTS
+4. Check co-change history: git log --follow -p -- {module} | grep "^+++ b/"
+5. Write failing test → implement → green → commit
+6. Output: test count before/after, files changed, ready for /ship
+```
+
+**Standard commands to always generate for developer projects:**
+
+These three are installed by `npx azclaude` into `.claude/commands/` automatically.
+
+Check they exist — if not, the install is incomplete:
+```bash
+ls .claude/commands/add.md .claude/commands/audit.md .claude/commands/test.md 2>/dev/null \
+  || echo "Missing — re-run: npx azclaude"
+```
+
+If this project is a **Code** category (has package.json / Cargo.toml / etc.) — all three must be present. No exceptions.
+
+| Command | What it encodes |
+|---------|----------------|
+| `add.md` | Feature addition: scope intake → understand pattern → TDD → implement → verify |
+| `audit.md` | Spec compliance first → code quality second — uses EnterPlanMode |
+| `test.md` | IDE diagnostics → run suite → interpret failures → apply /fix |
+
+**Stack-specific commands to generate when stack detected:**
+| Stack | Generate |
+|-------|---------|
+| Next.js / React | `new-page.md`, `new-component.md` |
+| Express / FastAPI | `new-endpoint.md` |
+| Any DB | `migrate.md` |
+| Any deploy config | `deploy.md` |
+
+---
+
+### Native Tools in Skills
+
+Before writing any new skill: load `capabilities/shared/native-tools.md`.
+Every skill that collects user input, tracks progress, or runs commands must use the appropriate native tool — not simulate it with prose.
+
+Quick check before writing:
+- Does this skill ask questions? → `AskUserQuestion`
+- Does this skill have multiple steps? → `TaskCreate/TaskUpdate`
+- Does this skill do analysis before action? → `EnterPlanMode/ExitPlanMode`
+- Does this skill run risky changes? → `EnterWorktree`
+- Does this skill run a command and check result? → exit-code gate
+
+---
+
+### Check shared-skills First
+Before creating a new skill:
+```bash
+ls ~/shared-skills/ 2>/dev/null
+```
+
+If a matching skill exists and its tech stack matches this project → import it:
+```bash
+cp ~/shared-skills/{skill}.md .claude/commands/{skill}.md
+```
+Log which portable skills were imported and from which project.
+
+---
+
+### Skill Placement
+- `.claude/commands/{skill}.md` — project-specific skills
+- `~/shared-skills/{skill}.md` — general skills that work across projects (after k=10 gate)
+
+---
+
+### Level 3 Complete When
+- At least 3 project-specific skills exist
+- Each has a pushy description (3+ trigger variants)
+- Each passes RECIPE vs REFERENCE test
+- Body ≤ 500 lines (overflow goes to references/ subdir)
+- shared-skills checked and relevant ones imported

package/templates/capabilities/level-builders/level4-memory.md

@@ -0,0 +1,72 @@
+---
+name: level4-memory
+description: >
+  Build Level 4: memory system with goals.md, session logs, friction logs.
+  Triggers on: "build level 4", "add memory", "set up session tracking".
+tokens: ~200
+requires: level3-skills
+---
+
+## Level 4: Memory System
+
+Memory has 6 layers in Claude Code. AZCLAUDE uses layers 1-3 natively.
+
+| Layer | What | Always loaded? |
+|-------|------|----------------|
+| 1 | CLAUDE.md | ✅ Yes |
+| 2 | Auto memory (.claude/memory/) | ❌ On-demand |
+| 3 | Modular rules (.claude/rules/) | ❌ On-demand |
+| 4 | Skill metadata (frontmatter) | ✅ Lightweight |
+| 5 | Skill bodies | ❌ On-demand |
+| 6 | External memory (goals.md via hook) | ✅ Via hook |
+
+---
+
+### Create Memory Directories
+```bash
+mkdir -p .claude/memory/sessions
+mkdir -p .claude/memory/learnings
+mkdir -p ops/observations
+mkdir -p shared-skills
+```
+
+---
+
+### Create goals.md
+Write `.claude/memory/goals.md`:
+```markdown
+# Goals — {project_name}
+Updated: {date}
+
+## Current threads
+(describe what's in progress)
+
+## Done this session
+- Initial setup complete
+
+## Next actions
+1. {first concrete action}
+2. {second concrete action}
+3. {third concrete action}
+
+## Open blockers
+(none)
+```
+
+---
+
+### Memory Access Pattern (3-layer)
+Never read all memory files eagerly. Use the 3-layer pattern:
+1. **Search** — grep keywords, list files (no content read)
+2. **Filter** — recency (last 5 sessions), relevance (keyword match)
+3. **Read** — only files that passed filter
+
+Cost: Layer 1+2 ≈ 100 tokens. Layer 3: only matched files.
+
+---
+
+### Level 4 Complete When
+- `.claude/memory/goals.md` exists with correct structure
+- `ops/observations/` directory exists for friction logs
+- `shared-skills/` directory exists for portable skills
+- Hook injects goals.md automatically (set up in Level 6)

package/templates/capabilities/level-builders/level5-agents.md

@@ -0,0 +1,123 @@
+---
+name: level5-agents
+description: >
+  Build Level 5: project-specific custom agents.
+  Triggers on: "build level 5", "create agent", "add custom agent".
+tokens: ~300
+requires: level4-memory
+---
+
+## Level 5: Custom Agents
+
+Custom agents are defined in `.claude/agents/{name}.md`.
+They fire when spawned via the Agent tool from a skill or CLAUDE.md routing.
+
+Load shared/5-layer-agent.md for the full structure definition.
+
+---
+
+### When to Create a Custom Agent
+
+Create an agent when:
+- The task genuinely requires isolation (fresh context window)
+- The task is parallelizable with other agents (multiple files to analyze simultaneously)
+- The task is too long to run in the parent context without polluting it
+
+Do NOT create an agent when:
+- A skill with direct tool calls can do the same work
+- The "agent" would just read one file and return its content
+- You're using agents as a routing mechanism (routing belongs in CLAUDE.md)
+
+---
+
+### Co-Change Analysis — Determine Agent Boundaries
+
+Do NOT create one agent per directory. Check what changes together:
+
+```bash
+# Files frequently edited together in the same commits
+git log --name-only --format="" --diff-filter=M \
+  | sort | uniq -c | sort -rn | head -30
+```
+
+**Rule**: Directories in the same commits → same agent.
+Example: if `api/routes/` and `extraction/` always change together,
+one agent owns both — not two.
+
+**Rule**: Testing is a responsibility, not a role.
+The agent that owns `engine/` also owns `tests/engine/`.
+Do NOT create a separate tester agent unless tests are truly
+independent from the code they test (rare).
+
+3 focused agents with clear boundaries > 6 overlapping agents.
+
+**Good agent split** (files that change independently):
+```
+agent: frontend-agent  → src/components/, src/pages/  (UI changes alone)
+agent: api-agent       → src/api/, src/middleware/    (backend changes alone)
+```
+
+**Bad agent split** (files that always change together):
+```
+agent: schema-agent    → src/db/schema/   (these always change
+agent: migration-agent → src/db/migrations/  ← with schema — merge them)
+```
+
+### Framework Collision Detection
+
+```bash
+grep -r "langgraph\|crewai\|autogen\|langchain.*agent" \
+  pyproject.toml package.json 2>/dev/null | head -5
+```
+
+If found: prefix ALL Claude Code agents with `cc-` (e.g., `cc-frontend`).
+Add to every agent description: `# Claude Code Development Agent (not a {framework} application agent)`
+
+This prevents Claude from confusing the application's LangGraph agents with Claude Code agents.
+
+---
+
+### Agent File Structure
+```yaml
+---
+name: {agent-name}
+description: >
+  What this agent does. When to spawn it.
+  Include: what input it receives, what output it produces.
+---
+
+## Layer 1: PERSONA
+{Who this agent is — role, not personality}
+
+## Layer 2: SCOPE
+{What it does. What it explicitly does NOT do.}
+
+## Layer 3: TOOLS & RESOURCES
+{Which tools it may use. Which capability files to load for this task.}
+
+## Layer 4: CONSTRAINTS
+{Hard limits. What it must never do.}
+
+## Layer 5: DOMAIN CONTEXT
+{Domain knowledge specific to this project that shapes every decision.}
+```
+
+---
+
+### Context Passing to Agents
+
+When spawning this agent, pass ONLY:
+- The specific capability file for its task (not the full module)
+- The output from the previous step (not the full conversation)
+- Shared rules if the task requires them (tdd.md, completion-rule.md)
+
+Pass micro-sections, not monoliths. A detection agent gets detect.md (~100 lines).
+Not a full module file — pass only the micro-section for the specific task.
+
+---
+
+### Level 5 Complete When
+- At least 1 custom agent exists for a genuine parallel/isolation use case
+- Each agent has all 5 layers
+- Each agent passes self-applicability check
+- Agents are listed in manifest.md if they need to be discoverable

package/templates/capabilities/level-builders/level6-hooks.md

@@ -0,0 +1,119 @@
+---
+name: level6-hooks
+description: >
+  Build Level 6: lifecycle hooks for automatic context injection.
+  Triggers on: "build level 6", "add hooks", "automate session start".
+tokens: ~200
+requires: level5-agents
+---
+
+## Level 6: Lifecycle Hooks
+
+Hooks are PUSH-based, not PULL-based. They fire automatically on events.
+Claude does not need to remember to read goals.md — the hook injects it.
+
+---
+
+### Global vs Project-Level
+
+| Type | What | Where | When |
+|------|------|-------|------|
+| Global | UserPromptSubmit + Stop | `~/.claude/settings.json` | Every project, installed once |
+| Project | Formatter, linter, project-specific | `.claude/settings.json` | This project only |
+
+Global hooks are installed by the `npx azclaude` command.
+Project hooks are added here if needed beyond the global defaults.
+
+---
+
+### Defense in Depth — 3-Layer Session Safety
+
+Three independent layers ensure session state is never lost. Any single layer can fail
+and the other two catch it. This is not redundancy — each layer covers a different failure mode.
+
+```
+Layer 1: CLAUDE.md instruction
+  ↓ "Read .claude/memory/goals.md at session start"
+  Failure mode: Claude ignores it (instruction drift)
+  Coverage: always in context — lowest reliability
+
+Layer 2: UserPromptSubmit hook
+  ↓ Injects goals.md content into every prompt automatically
+  Failure mode: Node.js not in PATH (rare — Node ≥ 16 required, same as npm)
+  Coverage: PUSH-based, doesn't depend on Claude following instructions
+
+Layer 3: Stop hook
+  ↓ Creates friction stub when session ends without /persist
+  Failure mode: hook not installed, session crashes
+  Coverage: catches unclean exits that Layer 1+2 cannot
+```
+
+**Why all 3 are required**: Layer 1 alone = broken when Claude is busy. Layer 2 alone = broken if Node.js unavailable (extremely rare). Layer 3 alone = reactive not proactive. Together = session state survives all common failure modes.
+
+**Installing Layer 2+3**: `npx azclaude` installs global hooks to `~/.claude/settings.json`.
+**Installing Layer 1**: `/setup` writes the instruction into CLAUDE.md.
+
+CLAUDE.md creates goals.md if it doesn't exist yet.
+The hook injects it if it does exist and is stale.
+Both layers cover the same need — defense in depth.
+
+---
+
+### PostToolUse Auto-Format Hooks (Project-Level)
+
+After detecting the project stack, generate a `.claude/settings.json` with auto-format:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [{ "type": "command", "command": "case \"$CLAUDE_FILE_PATH\" in *[';''|''&''`''$''('')''>''<']*) exit 0 ;; esac && {stack-specific command}" }]
+      }
+    ]
+  }
+}
+```
+
+> **Security**: Sanitize `$CLAUDE_FILE_PATH` using a `case...in` guard — rejects paths
+> containing shell metacharacters before the formatter runs. A path like `; rm -rf /;.ts`
+> exits silently instead of executing. See `shared/security.md` for full details.
+
+**Format command by stack:**
+
+| Stack detected | Format command |
+|---------------|----------------|
+| Node/TypeScript | `npx prettier --write "$CLAUDE_FILE_PATH" 2>/dev/null \|\| true` |
+| Python | `ruff format "$CLAUDE_FILE_PATH" 2>/dev/null \|\| black "$CLAUDE_FILE_PATH" 2>/dev/null \|\| true` |
+| Go | `gofmt -w "$CLAUDE_FILE_PATH" 2>/dev/null \|\| true` |
+| Rust | `rustfmt "$CLAUDE_FILE_PATH" 2>/dev/null \|\| true` |
+| Ruby | `rubocop --autocorrect "$CLAUDE_FILE_PATH" 2>/dev/null \|\| true` |
+
+All commands end with `|| true` — format errors must never fail the tool call.
+Only add if the formatter is confirmed installed (`which prettier` etc.).
+
+**The split**:
+- `~/.claude/settings.json` → lifecycle hooks (UserPromptSubmit, Stop) — global, installed once by `npx azclaude`
+- `.claude/settings.json` → formatter hooks (PostToolUse) — project-specific, per stack, generated by `/setup`
+
+---
+
+### Global Hook Behavior
+
+The exact hook commands are defined in `bin/cli.js` — that is the source of truth.
+Do not duplicate the hook code here; reference it instead.
+
+**UserPromptSubmit** — runs `~/.claude/hooks/user-prompt.js` (Node.js, cross-platform). Injects `goals.md` once at session start using `os.tmpdir()/.azclaude-session-{ppid}`. Fires on the first prompt only — not on every subsequent prompt.
+
+**Stop** — runs `~/.claude/hooks/stop.js` (Node.js, cross-platform). Fires when session ends:
+- Stamps `goals.md` with today's date
+- Creates friction stub in `ops/observations/` if `/persist` was not run
+- Warns: "session state not persisted — run /persist before closing"
+
+---
+
+### Level 6 Complete When
+- Global hooks confirmed in `~/.claude/settings.json` (`_azclaude: true`)
+- goals.md is auto-injected at session start
+- Stop hook creates friction stubs on unclean exits

package/templates/capabilities/level-builders/level7-extmcp.md

@@ -0,0 +1,60 @@
+---
+name: level7-extmcp
+description: >
+  Build Level 7: external MCP servers and advanced tool composition.
+  Triggers on: "build level 7", "external MCP", "advanced tools".
+tokens: ~150
+requires: level6-hooks
+---
+
+## Level 7: External MCP Servers
+
+Level 7 extends Claude's capabilities beyond the project boundary.
+External MCPs connect Claude to the world: databases, browsers, APIs, services.
+
+---
+
+### What Qualifies as Level 7
+
+- External data sources (production database, analytics, monitoring)
+- Browser automation (Playwright, Puppeteer)
+- Communication tools (Slack, email, GitHub issues)
+- Cloud services (AWS, GCP, deployment pipelines)
+- Cross-project memory (azrole-memory or equivalent)
+
+---
+
+### Validation Before Installing
+
+For each external MCP:
+1. Does the project actually need this capability?
+2. Is the MCP server trusted? (check source, not just npm package name)
+3. What data does it access? Document it.
+4. Does it require credentials? Store in env, never in .mcp.json plaintext.
+
+---
+
+### Cross-Project Memory (optional)
+
+If working across multiple projects and want shared patterns:
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "node",
+      "args": ["/path/to/memory-server.js"]
+    }
+  }
+}
+```
+
+Cross-project memory stores: goals, friction patterns, ELO scores, portable skills.
+It does NOT replace project-level memory — it supplements it.
+
+---
+
+### Level 7 Complete When
+- External MCPs installed and verified with test calls
+- Credentials in environment variables, not in committed files
+- Each server documented in manifest.md or .mcp.json comments
+- No external MCP accesses data it doesn't need (principle of least access)