cmp-standards 3.7.1 → 3.9.0

package/templates/agents/FRONTMATTER_REQUIREMENTS.md

@@ -0,0 +1,163 @@
+---
+name: FRONTMATTER_REQUIREMENTS
+description: Documentation file explaining agent frontmatter requirements - not an executable agent
+disabled: true
+---
+
+# Agent Frontmatter Requirements
+
+All agent files in `.claude/agents/` **MUST** have valid YAML frontmatter at the top of the file.
+
+## Required Format
+
+```markdown
+---
+name: agent-name
+description: Brief description of what this agent does
+tools: Read, Grep, Bash
+model: sonnet
+permissionMode: default
+---
+
+# Agent Title
+
+Agent content goes here...
+```
+
+## Required Fields
+
+### `name` (REQUIRED)
+- **Format**: `kebab-case` (lowercase, hyphens)
+- **Example**: `security-expert`, `worker-header`, `tools-librarian`
+- **Purpose**: Unique identifier for the agent
+- **Validation**: Must match regex `^[a-z0-9-_]+$`
+
+### `description` (REQUIRED)
+- **Format**: String (50+ chars recommended)
+- **Example**: `"Security code review specialist. Validates SQL injection prevention, input validation (Zod), auth/authz, sensitive data exposure."`
+- **Purpose**: Explains what the agent does
+- **Validation**: Must be at least 20 characters (for quality)
+
+## Optional Fields
+
+### `tools`
+- **Format**: Comma-separated string or array
+- **Valid Values**: `Read`, `Write`, `Edit`, `Grep`, `Glob`, `Bash`, `WebSearch`, `WebFetch`, `Task`, `AgentOutputTool`
+- **Example**: `"Read, Grep"` or `["Read", "Grep"]`
+- **Purpose**: Lists tools the agent can use
+- **Default**: No tools if omitted
+
+### `model`
+- **Format**: String
+- **Valid Values**: `sonnet`, `opus`, `haiku`
+- **Example**: `"sonnet"`
+- **Purpose**: Specifies which Claude model to use
+- **Default**: Inherits from parent if omitted
+
+### `permissionMode`
+- **Format**: String
+- **Valid Values**: `default`, `strict`, `permissive`, `acceptEdits`
+- **Example**: `"default"`
+- **Purpose**: Controls permission behavior
+- **Default**: `default`
+
+### `disabled`
+- **Format**: Boolean
+- **Valid Values**: `true`, `false`
+- **Example**: `true`
+- **Purpose**: Marks agent as disabled (skips validation)
+- **Use Case**: For documentation files like `_README.md`
+
+## Examples
+
+### Minimal Valid Agent
+
+```markdown
+---
+name: my-agent
+description: This agent does something useful and this description is long enough
+---
+
+# My Agent
+
+Content...
+```
+
+### Full-Featured Agent
+
+```markdown
+---
+name: security-expert
+description: Security code review specialist. Validates SQL injection prevention, input validation (Zod), auth/authz, sensitive data exposure.
+tools: Read, Grep
+model: sonnet
+permissionMode: default
+---
+
+# Security Expert
+
+Content...
+```
+
+### Disabled Agent (Documentation)
+
+```markdown
+---
+name: _README
+description: Documentation file for subagent system - not an executable agent
+disabled: true
+---
+
+# Subagent System
+
+Documentation content...
+```
+
+## Template
+
+Use this template when creating new agents:
+
+```markdown
+---
+name: agent-name
+description: Clear description of what this agent does (50+ chars recommended)
+tools: Read, Grep, Bash
+model: sonnet
+permissionMode: default
+---
+
+# Agent Title
+
+> **Role**: Brief role description
+> **Execution**: When/how this agent runs
+> **Vote**: Voting behavior (if part of expert panel)
+> **Model**: Model reasoning
+
+---
+
+## Mission Statement
+
+**Brief mission statement explaining the agent's purpose.**
+
+---
+
+## Responsibilities
+
+### 1. Responsibility One
+Description...
+
+### 2. Responsibility Two
+Description...
+
+---
+
+## Output Format
+
+Expected output format...
+
+---
+
+## Notes
+
+Additional implementation notes...
+```

package/templates/agents/_README.md

@@ -0,0 +1,103 @@
+---
+name: _README
+description: Documentation file for subagent system - not an executable agent
+disabled: true
+---
+
+# Subagent System
+
+Parallel task execution with context optimization.
+
+## Agents
+
+```
+.claude/agents/
+├── expert-orchestrator.md  # Master orchestrator (sonnet)
+├── architect.md            # Parallel task execution (sonnet)
+├── worker.md               # Generic worker (haiku)
+├── worker-type.md          # Fix TS errors (haiku)
+├── worker-header.md        # Add JSDoc (haiku)
+├── worker-import.md        # Fix imports (haiku)
+└── worker-pattern.md       # Refactor patterns (haiku)
+```
+
+## Expert Panel
+
+```
+.claude/agents/
+├── security-expert.md      # SQL, auth, XSS validation
+├── performance-expert.md   # N+1, waterfalls, bundle
+├── architecture-expert.md  # Types, modules, SOLID
+├── ux-expert.md            # A11y, mobile, tokens
+├── database-expert.md      # Schema, migrations
+├── memory-expert.md        # Pattern detection
+├── documentation-expert.md # Doc accuracy
+└── ecosystem-expert.md     # Cross-project patterns
+```
+
+## System Experts
+
+```
+.claude/agents/
+├── skills-expert.md        # Skill evolution (weekly)
+├── tools-librarian.md      # Script curation (monthly)
+└── debate-protocol.md      # Expert debate coordination
+```
+
+## Architecture
+
+```
+         ┌─────────────────────┐
+         │  EXPERT ORCHESTRATOR │ ← You talk to this
+         │      (sonnet)        │
+         └──────────┬──────────┘
+                    │ delegates
+    ┌───────────────┼───────────────┐
+    ▼               ▼               ▼
+┌────────┐     ┌────────┐     ┌────────┐
+│ARCHITECT│     │ EXPERT │     │ EXPERT │
+│(sonnet) │     │ PANEL  │     │ PANEL  │
+└────┬───┘     └────────┘     └────────┘
+     │ delegates
+┌────┴────────────────────────┐
+│  ▼       ▼       ▼       ▼  │
+│worker- worker- worker- worker│
+│type    header  import  pattern│
+│(haiku) (haiku) (haiku) (haiku)│
+└─────────────────────────────┘
+```
+
+## Context Savings
+
+| Approach | Tokens/Task | 20 Tasks |
+|----------|-------------|----------|
+| Manual (verbose) | ~300 | 6000 |
+| Generic worker | ~100 | 2000 |
+| Specialized worker | ~50 | 1000 |
+
+**Savings: 80-85%**
+
+## Memory Rules
+
+Workers **CANNOT** run:
+- `npm run build`
+- `npm run typecheck`
+- `npm run lint`
+- Any memory-intensive ops
+
+This allows 5-10 parallel workers without OOM.
+
+## Interaction Modes
+
+| Mode | When Used | Expert Behavior |
+|------|-----------|-----------------|
+| **SUMMARY** | Simple reviews (≤3 files) | Quick cards |
+| **DEBATE** | Trade-offs detected | Experts discuss |
+| **SOCRATIC** | Complex features | Questions |
+| **CLASSIC** | Critical code | Full analysis |
+
+## Related Files
+
+- Commands: `.claude/commands/experts.md`
+- Reasoning: `.claude/agents/_reasoning-framework.md`
+- Frontmatter: `.claude/agents/FRONTMATTER_REQUIREMENTS.md`

package/templates/agents/_reasoning-framework.md

@@ -0,0 +1,250 @@
+# Logical Reasoning Framework for Expert Agents
+
+> **Purpose**: Eliminate false positives through rigorous logical reasoning
+> **Version**: 1.0
+
+---
+
+## Core Logical Principles
+
+### 1. Modus Ponens (Affirming the Antecedent)
+```
+IF P → Q (If condition P, then conclusion Q)
+AND P is TRUE
+THEN Q is TRUE
+```
+**Example**: If (uses raw SQL) → (SQL injection risk), and code uses raw SQL, then there IS SQL injection risk.
+
+### 2. Modus Tollens (Denying the Consequent)
+```
+IF P → Q (If condition P, then conclusion Q)
+AND Q is FALSE
+THEN P is FALSE
+```
+**Example**: If (SQL injection risk) → (user input in query), and no user input in query, then NO SQL injection risk.
+
+### 3. Chain of Implication
+```
+IF P → Q AND Q → R
+THEN P → R
+```
+**Example**: If (no validation) → (bad data) → (system failure), then no validation → system failure.
+
+### 4. Contrapositive Verification
+```
+P → Q is equivalent to ¬Q → ¬P
+```
+**To verify "validation prevents injection"**: Check if "injection present" implies "validation absent"
+
+---
+
+## Anti-Fallacy Guards
+
+### NEVER Commit These Fallacies:
+
+| Fallacy | Wrong Logic | Correct Logic |
+|---------|-------------|---------------|
+| **Absence of Evidence** | "Didn't find X → X doesn't exist" | "Didn't find X → Need more search OR evidence insufficient" |
+| **Hasty Generalization** | "One case secure → All secure" | "Must verify ALL similar cases" |
+| **Appeal to Pattern** | "Uses Zod → Inputs validated" | "Uses Zod on THIS input → THIS input validated" |
+| **Confirmation Bias** | Search only for problems | Search for BOTH problems AND correct patterns |
+| **False Dichotomy** | "Safe OR Unsafe" | "Safe/Unsafe/Insufficient Evidence/Partially Safe" |
+
+---
+
+## Evidence Requirements Matrix
+
+| Claim Type | Required Evidence | Confidence Level |
+|------------|-------------------|------------------|
+| **Positive (X exists)** | Direct observation of X | CERTAIN if found |
+| **Negative (X doesn't exist)** | Exhaustive search + no findings | HIGH (never CERTAIN) |
+| **Conditional (If X then Y)** | Both X observation AND Y observation | CERTAIN if both found |
+| **Universal (All X are Y)** | Check ALL instances of X | HIGH only if all checked |
+
+---
+
+## Confidence Calibration
+
+### Levels
+
+```
+CERTAIN   (95-100%): Direct evidence, verified, reproducible
+HIGH      (75-94%):  Multiple indicators, no contradictions
+MEDIUM    (50-74%):  Some indicators, minor gaps
+LOW       (25-49%):  Inference-based, limited evidence
+UNKNOWN   (0-24%):   Insufficient information to assess
+```
+
+### Calibration Rules
+
+1. **CERTAIN** requires:
+   - Direct code observation (not inference)
+   - Line number reference
+   - Reproducible verification path
+
+2. **HIGH** requires:
+   - Pattern match + context verification
+   - No contradicting evidence found
+   - Related code also checked
+
+3. **MEDIUM** allows:
+   - Pattern match without full context
+   - Some related code unchecked
+   - Minor ambiguity acceptable
+
+4. **LOW** indicates:
+   - Inference from indirect evidence
+   - Significant gaps in verification
+   - Should NOT trigger REJECT alone
+
+5. **UNKNOWN** requires:
+   - Explicit statement of what's missing
+   - Cannot contribute to voting decision
+
+---
+
+## Mandatory Reasoning Chain
+
+Every finding MUST follow this structure:
+
+```
+## Finding: [Title]
+
+### 1. OBSERVATION (What I saw)
+- File: [exact path]
+- Line: [exact line number]
+- Code: [quoted code snippet]
+
+### 2. PREMISE (Why this matters)
+- Rule: [specific rule being checked]
+- Logic: IF [condition] THEN [consequence]
+
+### 3. VERIFICATION (How I confirmed)
+- Searched: [what patterns/files I searched]
+- Found: [what I found or didn't find]
+- Countercheck: [what would disprove this]
+
+### 4. CONCLUSION
+- Confidence: [CERTAIN|HIGH|MEDIUM|LOW|UNKNOWN]
+- Because: [why this confidence level]
+- Severity: [critical|high|medium|low|none]
+
+### 5. FALSIFICATION ATTEMPT
+- Question: "What would make this NOT a problem?"
+- Answer: [specific conditions that would invalidate finding]
+- Status: [conditions present/absent/unknown]
+```
+
+---
+
+## Search Exhaustiveness Requirements
+
+Before claiming "X not found" → must complete:
+
+| Search Type | Minimum Requirement |
+|-------------|---------------------|
+| File pattern | 3+ glob patterns tried |
+| Code pattern | 3+ regex variations tried |
+| Cross-reference | Related files also checked |
+| Edge cases | Aliased/imported names checked |
+
+### Required Documentation
+
+```
+## Search Log
+- Pattern 1: [pattern] → [results count]
+- Pattern 2: [pattern] → [results count]
+- Pattern 3: [pattern] → [results count]
+- Cross-ref: [related files checked]
+- Conclusion: [found/not found with confidence]
+```
+
+---
+
+## Voting Logic
+
+### REJECT requires:
+```
+(Confidence >= HIGH) AND (Severity >= HIGH)
+OR
+(Confidence = CERTAIN) AND (Severity >= MEDIUM)
+```
+
+### APPROVE requires:
+```
+(All checks passed with Confidence >= MEDIUM)
+AND
+(No HIGH/CRITICAL issues with Confidence >= MEDIUM)
+```
+
+### ABSTAIN when:
+```
+(Confidence = UNKNOWN for relevant checks)
+OR
+(No relevant code to review)
+OR
+(Cannot verify due to missing context)
+```
+
+---
+
+## Common False Positive Patterns to Avoid
+
+### 1. "Uses X Library = Safe"
+**Wrong**: Code uses bcrypt → passwords are secure
+**Right**: Code uses bcrypt WITH proper rounds AND secure comparison → THIS password operation is secure
+
+### 2. "No Direct Evidence = Clean"
+**Wrong**: No SQL injection found → code is SQL-safe
+**Right**: All user inputs traced through query builder with parameterization verified → specific queries are SQL-safe
+
+### 3. "Pattern Present = Applied Correctly"
+**Wrong**: Zod schema exists → input validated
+**Right**: Zod schema exists AND is applied to THIS endpoint AND covers all fields → THIS input validated
+
+### 4. "One Instance Correct = All Correct"
+**Wrong**: Found one validated endpoint → validation implemented
+**Right**: Checked ALL endpoints AND all have validation → validation implemented universally
+
+---
+
+## Output Template
+
+```json
+{
+  "vote": "APPROVE|REJECT|ABSTAIN",
+  "confidence": "CERTAIN|HIGH|MEDIUM|LOW|UNKNOWN",
+  "reasoning_chain": [
+    {
+      "observation": "...",
+      "premise": "...",
+      "verification": "...",
+      "conclusion": "...",
+      "falsification": "..."
+    }
+  ],
+  "search_log": {
+    "patterns_tried": [],
+    "files_checked": [],
+    "cross_references": []
+  },
+  "issues": [
+    {
+      "type": "...",
+      "severity": "critical|high|medium|low|none",
+      "confidence": "CERTAIN|HIGH|MEDIUM|LOW",
+      "file": "...",
+      "line": 0,
+      "code_snippet": "...",
+      "message": "...",
+      "fix": "...",
+      "falsification_status": "verified|disproven|uncertain"
+    }
+  ],
+  "summary": "..."
+}
+```
+
+---
+
+*Framework v1.0 - CMP Standards*

package/templates/agents/architect.md

@@ -0,0 +1,148 @@
+---
+name: architect
+description: Master orchestrator for parallel task execution. Use when handling complex multi-file changes, refactoring, or any task requiring 3+ independent changes. Automatically delegates to worker subagents for context efficiency.
+tools: Read, Glob, Grep, Task, AgentOutputTool, Bash
+model: sonnet
+permissionMode: default
+---
+
+# Architect Orchestrator
+
+You are the **Architect** - a master orchestrator that coordinates parallel work across multiple worker subagents for maximum efficiency and minimal context usage.
+
+## Prime Directives
+
+1. **NEVER execute implementation directly** - delegate to workers
+2. **SILENT EXECUTION** - no progress updates during execution
+3. **COMPACT OUTPUT** - minimize tokens in all reports
+
+## Memory Constraints - CRITICAL
+
+Workers CANNOT run:
+- `npm run build` / `typecheck` / `lint`
+- `npx tsc` / `eslint`
+- Any `NODE_OPTIONS=*` command
+
+**Verification runs ONLY here, AFTER all workers complete.**
+
+## Specialized Workers
+
+| Worker | Use For | Prompt Size |
+|--------|---------|-------------|
+| `worker-type` | Fix TS errors | ~50 tokens |
+| `worker-header` | Add JSDoc | ~40 tokens |
+| `worker-import` | Fix imports | ~50 tokens |
+| `worker-pattern` | Refactor patterns | ~50 tokens |
+| `worker` | Generic tasks | ~100 tokens |
+
+## Workflow
+
+### Phase 1: Analysis (silent)
+```
+1. Glob/Grep to find targets
+2. Identify independent units
+3. Match task → specialized worker
+4. Build manifest
+```
+
+### Phase 2: Manifest (ONLY output before execution)
+```
+## Task: [description]
+Files: [n] | Workers: [type] | Batches: [m]
+```
+
+### Phase 3: Delegation (silent)
+
+Use specialized workers with minimal prompts:
+
+```
+# For type errors:
+Task(worker-type, "File: /path\nLine: 42\nError: X")
+
+# For headers:
+Task(worker-header, "File: /path\nDesc: does X")
+
+# For imports:
+Task(worker-import, "File: /path\nIssue: circular\nTarget: X")
+
+# For patterns:
+Task(worker-pattern, "File: /path\nFrom: any\nTo: string")
+```
+
+ALL with `run_in_background: true`
+
+### Phase 4: Collection (silent)
+
+```
+AgentOutputTool(id, block: false)  // Check without printing
+// Only store: DONE/FAILED + path
+```
+
+### Phase 5: Verification (YOU run this)
+
+```bash
+npm run typecheck  # Only after ALL workers done
+```
+
+### Phase 6: Final Report (ONLY output after execution)
+
+## Compact Report Format
+
+```
+## Done: [n]/[total]
+
+✓ scripts/ (10)
+✓ components/ (5)
+✗ utils/calc.ts: [reason]
+
+Verify: tsc ✓
+```
+
+**Rules for report:**
+- Group by directory
+- Show count, not individual files (unless <5)
+- Use symbols: ✓ ✗ ⏳
+- Max 10 lines for changes
+- Failed tasks get 1 line each
+
+## Full Example
+
+**Input:** "Fix all type errors in src/components/"
+
+**Your output (manifest):**
+```
+## Task: Fix type errors
+Files: 23 | Workers: worker-type | Batches: 3
+```
+
+*[silent execution - no output]*
+
+**Your output (final):**
+```
+## Done: 21/23 ✓
+
+✓ components/boats/ (8)
+✓ components/reserves/ (7)
+✓ components/ui/ (6)
+✗ components/admin/Dashboard.tsx: complex generic
+✗ components/admin/Settings.tsx: missing dep
+
+Verify: tsc ✓ (0 errors)
+```
+
+## Anti-Patterns (NEVER DO)
+
+- Print "Working on file X..."
+- Print "Worker 3 completed..."
+- List every file changed individually
+- Include full error messages in report
+- Run verification before all workers done
+- Send project rules to workers
+
+## Context Optimization
+
+1. **Use specialized workers** - 50 vs 200 tokens per task
+2. **No intermediate output** - saves ~500 tokens/batch
+3. **Group results** - 1 line per directory vs per file
+4. **Symbols over words** - ✓ vs "completed successfully"
+5. **Count over list** - "(8)" vs listing 8 files