azclaude-copilot 0.1.0

package/templates/capabilities/evolution/cycle2-knowledge.md

@@ -0,0 +1,87 @@
+---
+name: evolution-cycle2-knowledge
+description: >
+  Load when patterns.md has 10+ entries that haven't been reviewed. Load when
+  goals.md has stale sessions older than 2 weeks. Load when the same pattern
+  appears in multiple session files and hasn't been consolidated. Load after
+  detect+generate+evaluate as part of /evolve to close the learning loop.
+tokens: ~200
+---
+
+## Cycle 2: Knowledge Consolidation
+
+---
+
+### HARVEST — 3-layer retrieval (same as detect.md Layer 1-3)
+Read only what's recent and relevant:
+- Session summaries from last 5 sessions
+- Friction logs from last 3 sessions
+- Any learnings files modified in last 10 commits
+
+---
+
+### CONSOLIDATE
+Group harvested content by pattern:
+- Same friction appearing in 3+ sessions → candidate for re-derivation
+- Same workflow appearing in 3+ sessions → candidate for skill
+- Same fact referenced in 3+ files → candidate for knowledge-index entry
+
+Rules:
+- Do not consolidate single-occurrence items — they are noise
+- Consolidation writes ONE new file or updates ONE existing file
+- Never write to a file that is > 7 days old without reading it first
+
+---
+
+### PRUNE — Importance Scoring
+
+Before archiving, score each memory file:
+
+```
+importance = (frequency × 3) + (recency × 2) + (impact × 5)
+```
+
+| Factor | How to measure | Scale |
+|--------|---------------|-------|
+| frequency | How many session logs reference this file | 0-10 |
+| recency | Days since last reference (0=today, 10=never) | 0-10 (inverted) |
+| impact | Did this file change a decision? (grep decisions.md) | 0-10 |
+
+**Thresholds:**
+- importance ≥ 30 → promote to core memory (load every session)
+- importance 15-29 → keep, load on demand
+- importance < 15 → archive candidate
+
+Check git history:
+```bash
+git log --oneline -20 -- .claude/memory/
+```
+
+If importance < 15 AND not referenced in last 10 sessions → archive:
+```bash
+mkdir -p .claude/memory/archive
+mv .claude/memory/{file}.md .claude/memory/archive/{file}.md
+```
+
+Do NOT delete — archive. Deleted knowledge cannot be recovered.
+
+---
+
+### ENRICH knowledge-index.md
+If a `knowledge/` directory exists:
+```
+| file | summary | key_questions | tags |
+```
+
+- `key_questions`: 2-3 actual questions this file answers (not tags — real questions the model would ask)
+- Purpose: grep-based retrieval. The model searches key_questions to find which file to read.
+- DO NOT load these files into memory. Use the index to find which file to read on demand.
+
+---
+
+### LOG
+Append to `.claude/memory/sessions/{date}-cycle2.md`:
+- What was harvested
+- What was consolidated
+- What was pruned (archived)
+- What was added to knowledge-index

package/templates/capabilities/evolution/cycle3-topology.md

@@ -0,0 +1,128 @@
+---
+name: evolution-cycle3-topology
+description: >
+  Load when agents overlap in scope and you're not sure which handles what. Load
+  when a pipeline feels slow or agents are passing too much context to each other.
+  Load when manifest.md has capabilities that never get loaded. Load during /level-up
+  or when the user says "too many agents" or "agents are getting confused".
+tokens: ~250
+---
+
+## Cycle 3: Topology Optimization
+
+---
+
+### INVENTORY
+Map the current environment:
+```bash
+ls .claude/capabilities/
+ls .claude/capabilities/evolution/ .claude/capabilities/intelligence/ .claude/capabilities/shared/
+ls .claude/commands/
+ls .claude/agents/ 2>/dev/null
+wc -l .claude/capabilities/**/*.md
+```
+
+For each capability file:
+- Record line count
+- Record token estimate (lines × 12 approx)
+- Record last modified date
+
+---
+
+### MEASURE
+Score each file on two axes:
+
+**Usage score (1-10)**: How often is this file loaded per session?
+- Check friction logs for references
+- Check session summaries for mentions
+- Score 1 = never referenced, Score 10 = every session
+
+**Quality score (1-10)**: Does it pass Five Quality Criteria?
+- Run Five Quality Criteria from evaluate.md on each file
+- Score = number of criteria passed × 2
+
+**ELO rank**: Sort files by (usage × quality) descending.
+High score → keep and improve. Low score → candidate for pruning.
+
+---
+
+### OPTIMIZE
+For each file scoring below threshold (usage < 3 AND quality < 6):
+
+1. Is it referenced in manifest.md? If not → it's dead weight. Archive it.
+2. Is it too long (> 150 lines)? Split it into two focused files.
+3. Is its description in manifest.md accurate? If not → update manifest row.
+4. Does it overlap with another file? Merge or clarify boundary.
+
+**Pipeline check** (if agents chain):
+- Does each agent receive only what it needs?
+- Is any agent passing its full context window to the next? That's a violation.
+- Fix: pass only the output, not the context that produced it.
+
+---
+
+### RECORD
+Update manifest.md token estimates based on actual line counts.
+Append topology report to `.claude/memory/sessions/{date}-cycle3.md`.
+
+---
+
+### PRUNE AGENTS
+For any custom agent in `.claude/agents/`:
+- Does it have all 5 layers? (see agent-creator skill or shared/5-layer-agent.md)
+- Is it still needed, or has a skill replaced it?
+- If obsolete: archive to `.claude/agents/archive/`
+
+---
+
+### UPDATE PIPELINES
+If 3+ agents chain (A → B → C):
+- Verify B receives only A's output, not A's full context
+- Verify C receives only B's output
+- Document the chain in `.claude/memory/pipeline-map.md`
+
+---
+
+### Topology Map Schema
+
+Write / update `.claude/memory/topology-map.json` after every Cycle 3 run:
+
+```json
+{
+  "last_updated": "YYYY-MM-DD",
+  "pipelines": [
+    {
+      "name": "{pipeline-name}",
+      "chain": ["agent-a", "agent-b", "agent-c"],
+      "uses": 0,
+      "quality_score": 0,
+      "influence_score": 0,
+      "last_used": "YYYY-MM-DD"
+    }
+  ],
+  "agents": [
+    {
+      "name": "{agent-name}",
+      "file": ".claude/agents/{name}.md",
+      "uses": 0,
+      "elo": 1000,
+      "last_used": "YYYY-MM-DD",
+      "status": "active|archived"
+    }
+  ],
+  "capabilities": [
+    {
+      "file": "capabilities/{path}.md",
+      "usage_score": 0,
+      "quality_score": 0,
+      "tokens": 0,
+      "status": "active|archived"
+    }
+  ]
+}
+```
+
+`influence_score` = how many other pipelines depend on this one's output.
+`elo` = updated from intelligence/elo.md pairwise comparisons when agents compete.
+
+After updating topology-map.json → also update the relevant rows in manifest.md token estimates.

package/templates/capabilities/evolution/detect.md

@@ -0,0 +1,103 @@
+---
+name: evolution-detect
+description: >
+  Load at the start of /evolve. Load when the environment feels stale or broken.
+  Load when skills aren't triggering correctly, agents are making repeated mistakes,
+  or friction logs mention the same pain 3+ times. Load when you suspect something
+  was built weeks ago and may no longer match how the project actually works.
+tokens: ~250
+---
+
+## DETECT
+
+### Step 1: 3-Layer Memory Retrieval
+
+**Layer 1 — Search** (grep keywords, don't read files yet):
+```bash
+git log --oneline -10
+ls .claude/memory/learnings/ 2>/dev/null
+ls ops/observations/ 2>/dev/null
+grep -rl "friction\|gap\|repeated\|failed" .claude/memory/ 2>/dev/null
+```
+
+**Layer 2 — Filter** (recency and relevance):
+- Last 5 commits — what was recently touched?
+- Friction logs from the last 3 sessions only
+- Memory files whose filenames match current task keywords
+
+**Layer 3 — Read** (only what passed Layer 2):
+- Read matched files — not all of them. Layer 1+2 cost ~100 tokens. Layer 3 costs per file.
+- Session summaries: `tail -50 .claude/memory/sessions/*.md`
+- Frontmatter filter: read `topics:` field before reading full session file.
+
+---
+
+### Step 2: Friction Scan
+
+```bash
+ls ops/observations/ 2>/dev/null
+grep -r "harder than\|repeated from\|took longer\|missing" ops/observations/ 2>/dev/null
+```
+
+Classify signals:
+- **Repetition signals** — same task appears in ≥ 2 friction logs
+- **Correction signals** — Claude output corrected by user in ≥ 2 sessions
+- **Speed signals** — "took longer than expected" for same task type
+- **Missing signals** — "environment is missing" repeated
+
+Domain-specific friction signals:
+- Developer: test failures, missing scaffolding
+- Writer: continuity errors, structure resets
+- Researcher: unsourced claims, repeated lookups
+- Compliance: wrong vocabulary, missing obligation documentation
+
+Compute friction score alongside structural score. High friction = high priority fix.
+
+---
+
+### Step 3: CONTEXT ROT CLASSIFICATION [CE Pyramid]
+
+Before patching any context problem, classify the rot type:
+
+| Rot Type | Symptom | Fix |
+|----------|---------|-----|
+| Poisoning | Agent believes wrong facts | Remove or correct the false source |
+| Distraction | Irrelevant context consuming window | Filter or summarize |
+| Confusion | Agent receives contradictory instructions | Resolve conflict, enforce one rule |
+| Clash | Context from multiple sources conflicts | Establish priority order |
+
+Rule: **classify first, patch second.** Never patch without a rot type label.
+
+---
+
+### Step 4: SEQUENCE SCAN [AutoAgent]
+
+Look for patterns that repeat across 3+ sessions:
+```bash
+grep -r "description:" .claude/memory/sessions/ 2>/dev/null | head -20
+```
+
+A sequence candidate = same 3+ steps done manually in 3+ separate sessions.
+
+Rules:
+- Flag candidates only — don't build the skill yet
+- If it maps to an existing skill: skip
+- If it's a project-specific one-off: skip
+- If it's a general workflow pattern: flag for GENERATE
+
+---
+
+### Step 5: INTENTION-OUTCOME SCAN [AutoAgent]
+
+```bash
+grep "description:" .claude/memory/*.md 2>/dev/null
+grep -r "friction\|gap\|missed" ops/observations/ 2>/dev/null
+```
+
+Compare what agents were supposed to do (description field) vs. what friction logs say happened.
+
+- Gap = capability described but friction says it doesn't work
+- Only flag gaps that appear in ≥ 2 friction entries (single-occurrence = noise)
+- Gap action must be specific: "add X to file Y" — not "improve agent"
+
+Add flagged gaps to PLAN alongside structural gaps.

package/templates/capabilities/evolution/evaluate.md

@@ -0,0 +1,90 @@
+---
+name: evolution-evaluate
+description: >
+  Load after generate.md has produced a new skill, agent, or capability.
+  Load before promoting, committing, or merging any generated file.
+  Load when a new skill was just written and you are unsure if it is good enough.
+  Never promote generated output without running this — generated files fail silently.
+tokens: ~200
+---
+
+## EVALUATE
+
+Run for every file produced in GENERATE before it ships.
+
+---
+
+### Step 1: Five Quality Criteria [CE Pyramid]
+
+Check all five. Fail any one → fix first, ship second. No exceptions.
+
+| Criterion | Question | Pass condition |
+|-----------|----------|---------------|
+| Relevance | Does this context help with the current task? | Directly used in this task |
+| Sufficiency | Does it contain everything needed to act? | No missing steps or undefined terms |
+| Isolation | Does it stand alone without unstated dependencies? | Self-contained for its scope |
+| Economy | Can any word be removed without losing meaning? | Minimum words for maximum clarity |
+| Provenance | Is the source of this knowledge traceable? | Source referenced or derivation clear |
+
+Pass all 5 → proceed to TAG.
+Fail any 1 → fix it. Do not move forward until all 5 pass.
+
+---
+
+### Step 2: Pass-k Thresholds [DUCTILE]
+
+A single passing test proves nothing.
+
+- **k=3 dev gate**: Apply the generated skill to 3 different real inputs from the current project. k=3 catches prompt sensitivity.
+- **k=10 deploy gate**: Before promoting to shared-skills, apply to 10 inputs. k=10 catches edge-case failures that k=3 misses.
+
+Never mark a skill done after one successful application.
+Never promote to shared-skills without passing k=10.
+
+---
+
+### Step 3: TAG
+
+Classify every generated skill:
+
+**GENERAL skill** — applies across projects:
+- Works for any developer project, any writer project, etc.
+- Does not depend on this project's specific code or structure
+- Add frontmatter: `skill_type: general`
+- After passing k=10: copy to `~/shared-skills/` for reuse across projects
+- Add `discovered_in: {project}` to frontmatter before promoting
+
+**NARROW skill** — specific to this project:
+- Depends on this project's domain, stack, or structure
+- Do NOT promote to shared-skills
+- Stays in `.claude/commands/` only
+- Narrow skills never go to shared-skills, even if they seem reusable
+
+When uncertain: default to NARROW. Promote to GENERAL only with evidence across projects.
+
+---
+
+### Step 4: GOALS UPDATE
+
+After evaluating all generated files:
+1. Update `.claude/memory/goals.md` — mark completed items, add next actions
+2. Top 3 concrete next actions only — not a wish list
+3. Remove blockers that were resolved
+
+---
+
+### Step 5: SESSION SUMMARY
+
+Write `{date}-cycle-{N}.md` to `.claude/memory/sessions/`:
+```yaml
+---
+date: {ISO date}
+cycle: {N}
+topics: [list of what was detected, generated, evaluated]
+gaps_fixed: [list]
+skills_created: [list]
+promoted_to_shared: [list or none]
+---
+
+{2-3 sentence summary of what changed and why}
+```

package/templates/capabilities/evolution/generate.md

@@ -0,0 +1,123 @@
+---
+name: evolution-generate
+description: >
+  Load after detect.md has produced a PLAN with specific gaps listed. Load when
+  about to write a new skill, agent, or capability file. Load when detect found
+  a stale doc, a missing capability, or a broken skill and you are about to fix it.
+  Do NOT load before detect — generate without a PLAN produces noise.
+tokens: ~250
+---
+
+## GENERATE
+
+Run for each item in the PLAN that passed DETECT.
+
+---
+
+### Step 1: Contract-First [DUCTILE]
+
+Before writing any skill or agent, define the contract:
+
+```
+Component: {name}
+
+Input:    What context this component receives to do its job
+Output:   What it produces in the success case
+Failures: What happens when input is wrong or incomplete
+```
+
+The contract is the acceptance test. If you cannot fill all three fields clearly,
+the component is under-specified. Do not generate it yet — clarify first.
+
+---
+
+### Step 2: Documentation-Quality-as-Signal [DUCTILE]
+
+Before generating, read any existing documentation for this capability:
+- < 2 sentences of docs = under-specified component → clarify before building
+- Contradictory docs = Confusion rot → classify and resolve first
+- No docs at all = treat as net-new, contract-first applies fully
+
+Sparse documentation is a signal, not a gap to fill with code.
+
+---
+
+### Step 3: Generate the File
+
+Write the capability file following the architecture rules:
+- ≤ 150 lines
+- YAML frontmatter required (name, description, tokens estimate)
+- One capability per file — if it's growing beyond 150 lines, split it
+- No file reads another file by default — explicit pointers only
+
+**Frontmatter format:**
+```yaml
+---
+name: {capability-name}
+description: >
+  One paragraph: what this does, when it fires, trigger words.
+tokens: ~{estimate}
+---
+```
+
+---
+
+### Step 4: Self-Applicability Check [QChunker]
+
+After writing the file, read it as if you are an unfamiliar agent seeing it for the first time:
+- Can an unfamiliar agent apply this immediately, without reading other files?
+- Is it self-contained for its scope?
+- Binary: **pass** or **fail**. No partial credit.
+
+If it fails: revise until it passes. Do not ship a file that fails self-applicability.
+
+---
+
+### Step 4.5: Pressure-Test Scenarios (enforcement skills only)
+
+If the skill enforces a process gate (completion, review, TDD, checkpoint):
+Load `shared/pressure-test.md` and add a `## Pressure Tests` section to the skill.
+
+Write one scenario per pressure type: time pressure, sunk cost, authority, false confidence.
+A skill that can be argued out of is not a skill — it's a suggestion.
+
+Skip this step only if the skill is purely guidance (vocabulary, patterns, reference material).
+
+---
+
+### Step 5: Consider Hook Generation [Hookify]
+
+If the detected friction is **behavioral** (user keeps correcting the same mistake,
+Claude keeps producing unwanted output), generate a hook instead of rewriting a prompt.
+
+**When to generate a hook instead of a skill/agent:**
+- Same correction appears 3+ times across sessions → PreToolUse or PostToolUse hook
+- Pattern is mechanical (e.g., "always run tests after edit") → PostToolUse hook
+- Pattern is preventive (e.g., "never use eval()") → PreToolUse hook with matcher
+
+**Hook generation template:**
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Edit|Write",
+      "hooks": [{"type": "command", "command": "bash .claude/hooks/check-pattern.sh"}]
+    }]
+  }
+}
+```
+
+**Rule:** Hooks are for mechanical enforcement. Skills are for guided workflows.
+If the fix requires reasoning, write a skill. If it requires pattern matching, write a hook.
+
+---
+
+### Step 6: Add to Manifest
+
+After generating a new capability file, add one row to `capabilities/manifest.md`:
+```
+| {file-path} | {trigger description} | ~{tokens} |
+```
+
+This is the ONLY change to existing files. Nothing else needs to change.
+The dispatch in CLAUDE.md already says "read manifest.md for unknown capabilities."

package/templates/capabilities/evolution/re-derivation.md

@@ -0,0 +1,77 @@
+---
+name: evolution-re-derivation
+description: >
+  Re-Derivation Protocol. Triggered when friction logs exceed threshold.
+  Not a patch — a full architectural rethink of a broken design.
+  Load when: friction logs >= 10 AND same pattern appears >= 5 times.
+tokens: ~150
+---
+
+## RE-DERIVATION PROTOCOL
+
+This fires when patching has stopped working. This is an architectural problem — not a content problem.
+Adding more rules to a broken architecture makes it worse, not better.
+
+### Trigger Threshold
+```bash
+ls ops/observations/ | wc -l
+grep -r "{pattern}" ops/observations/ | wc -l
+```
+
+If friction logs ≥ 10 AND same pattern appears in ≥ 5 logs:
+→ Do NOT patch again.
+→ Do NOT add another rule.
+→ Run this protocol.
+
+---
+
+### Step 1: Summarize Friction
+Read all matching friction logs. Write a 3-sentence summary:
+- What keeps failing
+- What has already been tried
+- What the current design assumed that turned out to be wrong
+
+---
+
+### Step 2: Identify the Pattern
+Name the architectural assumption that is failing.
+Not the symptom — the root assumption.
+
+Example: "We assumed agents would read their full instruction file. They don't — they skim."
+
+---
+
+### Step 3: Propose Architectural Change
+One specific change to the structure, not the content.
+Examples:
+- Split a monolithic file into micro-sections
+- Move a rule from agent instructions to CLAUDE.md (always-hot)
+- Replace agent-spawning with direct skill execution
+- Add a manifest entry instead of embedding logic in CLAUDE.md
+
+---
+
+### Step 4: Present to User Before Changing
+Write a Re-Derivation Proposal:
+```
+## Re-Derivation Proposal
+
+**Pattern**: {what keeps failing}
+**Root assumption that failed**: {what the design assumed}
+**Proposed change**: {one architectural change}
+**Files affected**: {list}
+**Expected result**: {what improves}
+```
+
+Do NOT implement until the user approves. Architectural changes affect everything.
+
+---
+
+### Step 5: Implement if Approved
+Make the change. Archive processed friction logs:
+```bash
+mkdir -p ops/observations/archive
+mv ops/observations/{matching-logs} ops/observations/archive/
+```
+
+Reset friction counter. The architectural change starts a new baseline.