azclaude-copilot 0.1.0

package/templates/capabilities/intelligence/debate.md

@@ -0,0 +1,104 @@
+---
+name: intelligence-debate
+description: >
+  Structured adversarial debate for hard architectural decisions.
+  Opt-in only — not the default for every decision.
+  Triggers on: "debate", "tradeoff", "should we", "which is better", "decide between".
+tokens: ~400
+---
+
+## Structured Debate Protocol [AceMAD]
+
+Use when a decision is genuinely uncertain, multi-criteria, and wrong choice costs real time.
+Do NOT use for routine decisions — Claude's direct answer is faster and equally good.
+
+---
+
+### Phase 1: Define the Question
+State the decision as a binary or small option set:
+"Should we do A or B?"
+"Which architecture: X or Y?"
+Not: "What should we do about the general problem?"
+
+---
+
+### Phase 2: Advocate A — MAXIMALIST
+Argue the strongest possible case FOR the leading option.
+- Make the best arguments you can — do not sandbag
+- N ≤ 10 arguments maximum
+- Each argument: one claim + one piece of evidence
+- Label evidence: [VERIFIED] / [PARTIAL] / [UNVERIFIED] / [FALSE]
+
+---
+
+### Phase 3: Advocate B — SKEPTIC
+Argue the strongest possible case AGAINST the leading option (or FOR the alternative).
+- N ≤ 10 arguments maximum
+- T ≤ 5 total rounds across both advocates
+- Same evidence labeling rules apply
+- Must address MAXIMALIST's strongest verified argument
+
+---
+
+### Phase 4: FACT CHECK — NON-NEGOTIABLE
+Before synthesis, tag every claim:
+
+| Tag | Meaning |
+|-----|---------|
+| [VERIFIED] | Confirmed by code, docs, or direct test |
+| [PARTIAL] | Directionally correct but incomplete |
+| [UNVERIFIED] | Asserted without evidence |
+| [FALSE] | Contradicted by evidence |
+
+**Disqualified claim language** — any argument containing:
+"should work" / "probably" / "I believe" / "I think" → mark [UNVERIFIED], reduce weight.
+
+If ≥ 30% of an advocate's claims are UNVERIFIED → confidence stays LOW regardless of score.
+Adjusted evidence scores replace raw argument counts.
+
+Truth wins. Not volume.
+
+---
+
+### Phase 5: Synthesis
+
+**5a. Draft synthesis** — pick the winner, state the margin (0-100 confidence).
+
+**5b. Second-Order Cognition Check [AceMAD]**:
+Did the synthesis address the strongest *verified* claim from the losing side?
+If not → revise. Confidence stays LOW until addressed.
+
+**5b. Self-refine** — critique the draft:
+- Did I favor the side with more words? (higher word-count ≠ stronger case)
+- Did I ignore any [VERIFIED] claim?
+- Is the margin honest?
+Max 2 rounds of self-refine.
+
+**5c. Order-Independence Check [PeerRank]**:
+If margin < 10 points: run synthesis again with advocates in reversed order.
+If conclusion reverses → result is INCONCLUSIVE. Present both sides to user.
+Position bias accounts for 0.39 correlation with first-presented argument.
+
+**5d. Deliver** — state winner, confidence, and the one verified claim that decided it.
+
+---
+
+### Phase 6: Length-Independence [Elo-Evolve]
+Score on **evidence-density** (verified claims per 100 words), NOT raw word count.
+Flag any advocate whose argument exceeds 2× the median length — the excess is noise.
+
+**Comparative Binary Framing [Elo-Evolve]**: Use pairwise comparison (which is better: A or B?)
+not absolute ratings (rate A /10). Pairwise reduces noise from σ_abs=35.65 to σ_comp=7.85.
+
+---
+
+### Phase 7: Record the Decision
+Append to `.claude/memory/decisions.md`:
+```
+## {Decision Title} — {date}
+**Question**: {the decision}
+**Options**: {A} vs {B}
+**Winner**: {chosen approach} (confidence: {level})
+**Deciding claim**: {the one verified claim that settled it}
+**Dissent**: {strongest verified argument for the loser}
+```

package/templates/capabilities/intelligence/elo.md

@@ -0,0 +1,122 @@
+---
+name: intelligence-elo
+description: >
+  ELO quality ranking across options, agents, or skills. Use when comparing
+  multiple candidates and need a defensible rank order.
+  Triggers on: "rank these", "which is best", "compare quality".
+tokens: ~200
+---
+
+## ELO Quality Ranking [PeerRank + Elo-Evolve]
+
+---
+
+### Authoritative Ownership [Elo-Evolve]
+The loop controller (the model running this skill) owns the authoritative ELO scores.
+Subagents that produce provisional scores feed into this controller — they do not own the final rank.
+Provisional scores from subagents are inputs, not decisions.
+
+Self-evaluation reliability: r=0.538 (self-scored) vs r=0.905 (loop controller reconciliation).
+Never let an agent self-rank as authoritative.
+
+---
+
+### Pairwise Comparison Protocol
+
+**Comparative Binary Framing**: Compare pairs, not absolutes.
+"Is A better than B for this criterion?" — not "Rate A from 1 to 10."
+
+For N candidates: run N×(N-1)/2 pairwise comparisons.
+Each comparison: one winner, one loser. No ties unless evidence is genuinely equal.
+
+---
+
+### ELO Schema
+
+For each candidate, track:
+```json
+{
+  "id": "{candidate-id}",
+  "elo": 1000,
+  "wins": 0,
+  "losses": 0,
+  "adjusted_evidence_score": 0,
+  "fact_check": {
+    "verified": 0,
+    "partial": 0,
+    "unverified": 0,
+    "false": 0
+  }
+}
+```
+
+ELO update after each comparison:
+- Winner: elo += 32 × (1 - expected_score)
+- Loser: elo -= 32 × expected_score
+- expected_score = 1 / (1 + 10^((opponent_elo - this_elo) / 400))
+
+---
+
+### Adjusted Evidence Score
+
+Do not rank on raw ELO alone. Adjust for fact-check quality:
+- `adjusted_evidence_score = verified_claims / (verified + unverified + false)`
+- If adjusted_evidence_score < 0.5: cap ELO at 1100 regardless of wins
+- A candidate that wins on volume but loses on evidence quality is not the best candidate
+
+---
+
+### Output
+
+Rank candidates by final ELO descending.
+For the winner: state the one pairwise comparison that determined the rank.
+Record in `.claude/memory/decisions.md` with the full ranking table.
+
+---
+
+### Persistent ELO — elo-rankings.json
+
+Write rankings to `.claude/memory/elo-rankings.json` so scores accumulate across sessions:
+
+```json
+{
+  "last_updated": "YYYY-MM-DD",
+  "debate_elo": [
+    {
+      "position": "{argument-id}",
+      "context": "{decision-topic}",
+      "elo": 1000,
+      "wins": 0,
+      "losses": 0,
+      "adjusted_evidence_score": 0.0
+    }
+  ],
+  "agent_elo": [
+    {
+      "agent": "{agent-name}",
+      "elo": 1000,
+      "tasks_completed": 0,
+      "wins": 0,
+      "losses": 0,
+      "last_task": "YYYY-MM-DD"
+    }
+  ],
+  "pattern_elo": [
+    {
+      "pattern": "{pattern-description}",
+      "source": ".claude/memory/patterns.md",
+      "elo": 1000,
+      "times_applied": 0,
+      "times_succeeded": 0,
+      "times_failed": 0
+    }
+  ]
+}
+```
+
+**Update rules:**
+- `debate_elo`: updated after each `/debate` cycle — one entry per argued position
+- `agent_elo`: updated after each pipeline run — winner = agent whose output was accepted without revision
+- `pattern_elo`: updated after each task — pattern succeeded if the approach worked, failed if re-derivation was triggered
+
+Read `elo-rankings.json` at the start of each debate or agent spawn. Pass as context so prior performance informs the current run.

package/templates/capabilities/intelligence/experiment.md

@@ -0,0 +1,86 @@
+---
+name: intelligence-experiment
+description: >
+  Experiment agent with worktree isolation. Use when testing a risky approach
+  that must not affect the main branch until proven. Triggers on: "try this approach",
+  "experiment with", "test this idea safely", "isolated experiment", "worktree".
+tokens: ~80
+---
+
+## Experiment Agent
+
+Run risky explorations in an isolated git worktree. Main branch is never touched.
+
+---
+
+### When to Use
+
+- Refactoring with uncertain outcome
+- Trying a new library or framework approach
+- Architectural change that might break things
+- Any "I want to try X but not break the main branch" scenario
+
+If the experiment succeeds → merge. If it fails → discard the worktree. Zero cleanup.
+
+---
+
+### Agent Definition Template
+
+```yaml
+---
+name: experiment-{task-name}
+description: >
+  Isolated experiment for {task}. Runs in worktree, cannot affect main branch.
+model: claude-sonnet-4-6
+maxTurns: 30
+tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+permissionMode: acceptEdits
+isolation: worktree
+background: false
+---
+```
+
+The `isolation: worktree` field is what creates a separate git branch automatically.
+The agent operates on a copy — main branch is read-only from the experiment's perspective.
+
+---
+
+### Experiment Protocol
+
+**Before starting**: define the hypothesis and success criteria.
+```
+Hypothesis: {what you believe will happen}
+Success:    {measurable outcome that proves it worked}
+Failure:    {measurable outcome that proves it didn't}
+```
+
+**After completing** — log the outcome:
+
+If experiment succeeded:
+```bash
+echo "\n## {task} — $(date +%Y-%m-%d)\n{what worked and why — include hypothesis}" >> .claude/memory/patterns.md
+```
+
+If experiment failed:
+```bash
+echo "\n## {task} — $(date +%Y-%m-%d)\n{what failed, why, what to try instead}" >> .claude/memory/antipatterns.md
+```
+
+**Never discard without logging.** A failed experiment that teaches something is a successful experiment.
+
+---
+
+### Merge Decision
+
+After experiment completes:
+- Tests pass + success criteria met → merge to main
+- Tests fail or success criteria not met → discard worktree, log antipattern
+- Partial success → extract the working parts before discarding
+
+Do NOT merge experiments that pass tests but fail success criteria. Tests prove correctness; success criteria prove value.

package/templates/capabilities/intelligence/opro.md

@@ -0,0 +1,84 @@
+---
+name: intelligence-opro
+description: >
+  OPRO + APE prompt optimization. Improves skill instructions by learning
+  from history. Use when a skill underperforms or after 10+ uses.
+  Triggers on: "optimize prompts", "improve skill", "skill isn't working".
+tokens: ~300
+---
+
+## Prompt Optimization [OPRO + APE]
+
+---
+
+### Step 1: Read History [OPRO]
+```bash
+cat .claude/memory/prompt-history.json 2>/dev/null
+```
+
+If it exists:
+- Top 5 scoring instructions → positive signal (what worked)
+- Bottom 2 scoring instructions → negative signal (what failed)
+- These signals shape the new instruction variants
+
+If it doesn't exist: create it after this optimization run.
+
+---
+
+### Step 2: Generate 3 Variants [APE]
+
+Write 3 instruction variants for the target skill:
+
+**Variant A — Few-shot enrichment**:
+Add 2-3 concrete examples of correct behavior from this project.
+The examples are real, not hypothetical.
+
+**Variant B — Chain-of-thought**:
+Add explicit reasoning steps before the action.
+"First identify X, then check Y, then do Z."
+
+**Variant C — Domain context**:
+Add domain-specific vocabulary and constraints at the top.
+Ground the instruction in the project's actual language.
+
+Save all 3 to `.claude/memory/prompt-versions/{skill}-{date}/`:
+- `variant-a.md`
+- `variant-b.md`
+- `variant-c.md`
+
+---
+
+### Step 3: Score and Select
+
+Apply each variant to 3 real inputs from the current project (k=3 gate).
+Score on:
+- Correctness of output (0-10)
+- Token efficiency (output length vs. information density)
+- Self-applicability (would an unfamiliar agent apply it correctly?)
+
+Keep the winner. Discard the others (don't delete — archive).
+
+---
+
+### Step 4: Update History [OPRO]
+
+Append to `.claude/memory/prompt-history.json`:
+```json
+{
+  "skill": "{skill-name}",
+  "date": "{ISO date}",
+  "winner": "{variant-a|b|c}",
+  "score": {0-10},
+  "why": "{one sentence: what made it better}"
+}
+```
+
+This entry feeds the next OPRO cycle. The history grows, the signal sharpens.
+
+---
+
+### Step 5: Deploy Winner
+
+Replace the skill body with the winning variant.
+Keep the frontmatter (name, description, tokens) unchanged.
+Update the token estimate if the new body is significantly different.

package/templates/capabilities/intelligence/pipeline.md

@@ -0,0 +1,149 @@
+---
+name: intelligence-pipeline
+description: >
+  Pipeline agent design. Use when 3+ agents chain output to input.
+  Ensures clean context passing, no context bleed between agents.
+  Triggers on: "chain agents", "pipeline", "agent A feeds agent B".
+tokens: ~250
+---
+
+## Pipeline Agent Design
+
+Use when work genuinely requires sequential agents where each feeds the next.
+Do NOT use for work one agent can do with tools directly.
+
+---
+
+### Pipeline Building Blocks
+
+Six primitives. Every pipeline is a composition of these.
+
+| Block | What it does | When to use |
+|-------|-------------|-------------|
+| **Sequential** | A → B → C | Each step needs the previous result |
+| **Parallel** | A + B + C → merge | Independent tasks that can run simultaneously |
+| **Reflect** | Agent reviews its own output before passing it | High-stakes output, expensive to fix downstream |
+| **Debate** | Two agents argue a position → synthesizer picks winner | Architectural decisions, tradeoffs |
+| **Summarize** | Compresses large context before passing to next agent | When Agent A output would overflow Agent B context |
+| **Tool-use** | Agent calls scripts/tools and passes JSON result | Programmatic data (never raw tool transcripts) |
+
+**Compose by need**: most pipelines are Sequential + Summarize. Add Reflect only for high-risk steps.
+Adding Debate to every pipeline wastes tokens — reserve for genuine tradeoffs.
+
+---
+
+### Pre-Built Pipeline Templates
+
+#### Feature Pipeline (new feature implementation)
+```
+Agents: planner → implementer → reviewer
+Planner input:  feature description + CLAUDE.md
+Planner output: { files_to_change, test_plan, approach }
+Implementer input: planner output + tdd.md
+Implementer output: { files_changed, tests_written, test_results }
+Reviewer input:  implementer output + spec
+Reviewer output: { spec_compliance: pass|fail, issues: [...] }
+Block types: Sequential + Reflect (implementer self-reviews tests before passing)
+```
+
+#### Fix Pipeline (bug investigation)
+```
+Agents: investigator → hypothesizer → fixer
+Investigator input:  error description + relevant files
+Investigator output: { root_cause, affected_files, reproduction_steps }
+Hypothesizer input:  investigator output
+Hypothesizer output: { hypothesis, fix_approach, risk: low|medium|high }
+Fixer input:         hypothesizer output (high risk → add Debate block before fix)
+Fixer output:        { files_changed, tests_passing, fix_summary }
+Block types: Sequential (+ Debate if risk = high)
+```
+
+#### Review Pipeline (code review)
+```
+Agents: spec-checker → quality-checker
+Spec-checker input:  PR diff + spec/requirements
+Spec-checker output: { spec_compliance: pass|fail, violations: [...] }
+Quality-checker input: PR diff + spec-checker output
+  GATE: if spec_compliance = fail → stop, return spec-checker output (do not proceed)
+Quality-checker output: { quality_issues: [...], suggestions: [...] }
+Block types: Sequential with hard gate
+```
+
+#### Architecture Pipeline (major design decision)
+```
+Agents: analyst → maximalist → skeptic → synthesizer
+Analyst input:   problem statement + codebase signals
+Analyst output:  { options: [A, B, C], constraints, tradeoffs }
+Maximalist input: analyst output → argues for best option
+Skeptic input:    analyst output → argues against best option
+Synthesizer input: maximalist + skeptic outputs → picks winner with reasoning
+Block types: Sequential → Parallel (maximalist + skeptic run together) → Sequential
+```
+
+---
+
+### Pipeline Validity Check
+Before building a pipeline, confirm:
+1. Can a single agent do this with Read/Write/Bash tools? If yes → don't pipeline.
+2. Is the output of Agent A genuinely the input of Agent B? If output needs human review first → don't pipeline.
+3. Is each agent's task parallelizable instead? If yes → spawn parallel agents, not a pipeline.
+
+Pipeline = sequential dependency. Parallel = independent tasks. Don't confuse them.
+
+---
+
+### Context Passing Rule
+Each agent receives ONLY:
+- The output of the previous agent (not the previous agent's full context)
+- Its own capability file (the micro-section for its specific task)
+- Shared rules if relevant (tdd.md, completion-rule.md)
+
+**NEVER pass the full context window of Agent A to Agent B.**
+Agent B's context starts fresh. It gets a summary, not a transcript.
+
+---
+
+### Pipeline Schema
+Define before building:
+```
+Pipeline: {name}
+
+Agent 1: {task}
+  Input:  {what it receives}
+  Output: {what it produces — this is Agent 2's input}
+
+Agent 2: {task}
+  Input:  {Agent 1's output format}
+  Output: {what it produces — this is Agent 3's input}
+
+Agent 3: {task}
+  Input:  {Agent 2's output format}
+  Output: {final result format}
+```
+
+The output format of each agent must exactly match the input format of the next.
+If they don't match: the pipeline has a bug before it's built.
+
+---
+
+### Knowledge Passing [AutoAgent]
+When passing knowledge between agents:
+- Pass structured objects (JSON), not prose summaries
+- Include only fields the next agent actually uses
+- Compress intermediate results: script runs → summary output only
+
+Intermediate tool call results stay in the script's scope, not in Claude's context.
+Only the final structured output crosses the agent boundary.
+
+---
+
+### Pipeline Map
+Document in `.claude/memory/pipeline-map.md`:
+```
+{pipeline-name}:
+  A → B → C
+  A output: {format}
+  B output: {format}
+  C output: {format}
+  Total token budget: ~{estimate}
+```

package/templates/capabilities/level-builders/level1-claudemd.md

@@ -0,0 +1,52 @@
+---
+name: level1-claudemd
+description: >
+  Build Level 1: create or improve the project CLAUDE.md.
+  Triggers on: "build level 1", "set up CLAUDE.md", "configure project rules".
+tokens: ~200
+---
+
+## Level 1: CLAUDE.md
+
+CLAUDE.md is the only always-hot file. It must be lightweight (~30 lines).
+Do not embed logic here. Use pointers to capability files.
+
+---
+
+### What Goes In CLAUDE.md
+1. **Identity** — project name, domain, stack, scale (3 lines max)
+2. **Rules** — 2-3 non-negotiable rules only. No lists of guidelines.
+3. **Session state** — pointer to goals.md (2 lines)
+4. **Task routing** — quick dispatch table + pointer to manifest.md (~10 lines)
+5. **Trade-Off Hierarchies** — what wins when priorities conflict (3 lines)
+6. **Available commands** — one line list
+
+Total: ~30 lines. If it grows past 40 lines, move content to a capability file.
+
+---
+
+### What Does NOT Go In CLAUDE.md
+- Detailed instructions (those go in capability files)
+- Level builder logic (that's in level-builders/)
+- Memory of past sessions (that's in goals.md, injected via hook)
+- Domain knowledge (that's in knowledge-index.md)
+
+---
+
+### Fill the Template
+Replace these placeholders in templates/CLAUDE.md:
+- `{{PROJECT_NAME}}` — actual project name
+- `{{PROJECT_DESCRIPTION}}` — 1-2 sentence description
+- `{{DOMAIN}}` — detected domain (developer/writer/researcher/compliance)
+- `{{STACK}}` — detected stack
+- `{{SCALE}}` — STANDARD/SKIM/MINIMAL/STRUCTURE-ONLY
+- `{{TDD_RULE}}` — insert TDD Iron Law if developer domain, else remove line
+- `{{PRIORITY_1/2/3}}` — trade-off hierarchy from domain signals
+
+---
+
+### Trade-Off Hierarchies — Pre-fill from Domain Signals
+- Developer project → correctness > speed > elegance
+- Compliance project → regulatory conformity > completeness > efficiency
+- Writer project → clarity > structure > length
+- Research project → evidence quality > comprehensiveness > recency

package/templates/capabilities/level-builders/level2-mcp.md

@@ -0,0 +1,58 @@
+---
+name: level2-mcp
+description: >
+  Build Level 2: configure MCP servers for this project.
+  Triggers on: "build level 2", "add MCP", "configure MCP servers".
+tokens: ~150
+requires: level1-claudemd
+---
+
+## Level 2: MCP Servers
+
+MCP servers extend Claude's tool set. They are deferred-loaded — only connect
+when an agent needs that specific capability.
+
+---
+
+### Detect What's Needed
+Read signals from the project:
+- Database files (sqlite, postgres connection strings) → database MCP
+- Browser/web tasks mentioned in README → browser/playwright MCP
+- File system operations beyond the project → filesystem MCP
+- External APIs in dependencies → relevant API MCPs
+
+Only install what the project actually needs. Not a default list.
+
+---
+
+### Configure `.mcp.json`
+```json
+{
+  "mcpServers": {
+    "{server-name}": {
+      "command": "{command}",
+      "args": ["{args}"],
+      "env": {
+        "{KEY}": "${ENV_VAR}"
+      }
+    }
+  }
+}
+```
+
+Place `.mcp.json` in the project root.
+
+---
+
+### Deferred Loading Rule
+MCPs are NOT loaded at session start. Each subagent connects only when it needs
+that capability. Do not list all MCPs in CLAUDE.md — they appear in manifest.md
+if they need to be explicitly dispatched.
+
+---
+
+### Verification
+After configuring:
+- Run `claude mcp list` to confirm servers are registered
+- Test one tool from each server before declaring Level 2 complete
+- Document each server in manifest.md if it needs to be discoverable by agents