CLAUDE.md · diff
git:20260627.cc934da to git:20260627.0187545
12 added, 7 removed. Audit A to A.
## Protocol
- **BLOCKED SUBAGENT TYPES:**
+ <important>
+ **BLOCKED SUBAGENT TYPES (hard rule — enforced by `hooks/block-subagent.sh`):**
- **NEVER use `general-purpose` subagent** - Conflicts with custom agents
- **NEVER use `explore` for planning/analysis** - Only for quick file searches
- `plan` (for planning mode) is allowed
+ </important>
- **MANDATORY BEHAVIOR:**
- 1. **Auto-route** - Every message is a task. Route to agent immediately.
- 2. **No confirmation** - Don't ask. Just delegate.
+ <important>
+ **DELEGATION MANDATE:** Trivial, conversational, or factual questions MAY be answered directly. Real engineering work — writing or modifying code, system/API design, debugging, or any multi-step task — MUST be delegated via `Task(subagent_type="scaffolding:<agent>", prompt="...", description="...")`. Never edit code/docs directly as part of engineering work.
+ </important>
+
+ **BEHAVIOR:**
+ 1. **Auto-route** - Treat engineering requests as tasks. Route to the right agent.
+ 2. **No confirmation** - For real work, don't ask. Just delegate.
3. **Concise responses** - Short status. No verbose explanations unless asked.
- 4. **Agent-first** - NEVER edit code/docs directly. ALWAYS delegate.
**Delegate via:** `Task(subagent_type="scaffolding:<agent>", prompt="...", description="...")`
**Response format:** `[Agent: name] Task -> Result (1-2 lines)`
---
## Agents (13)
| Agent | When to Use |
|-------|-------------|
| **scaffolding:analyst** | Ambiguous requests, requirements, scope assessment, feasibility, proposal writing |
| **scaffolding:architect** | System design, API design, implementation planning, multi-file refactoring, agent orchestration |
| **scaffolding:researcher** | New API integration, library questions, best practices (gate: score >= 80) |
| **scaffolding:developer** | Implementation, bug fixes, features, tests, UI/styling (gate: validation passes) |
| **scaffolding:debugger** | Bug reports, unexpected behavior, errors |
| **scaffolding:reviewer** | After code changes, security analysis, threat modeling (gate: no criticals) |
| **scaffolding:optimizer** | Performance issues, database design, schema, migrations, queries |
| **scaffolding:prompt-engineer** | System prompts, prompt templates, guardrail rules, prompt evals, LLM-judge rubrics, injection defense |
| **scaffolding:mcp-builder** | Build/modify MCP servers, tool schema design, stdio/http transport, MCP auth/secret launchers |
| **scaffolding:tech-writer** | Documentation, CHANGELOG updates |
| **scaffolding:devops** | CI/CD, deployment, infrastructure |
| **scaffolding:gitops** | Branch management, conflict resolution, git history, worktree recovery, push to remote |
| **scaffolding:coordinator** | Analyzes tasks, decomposes into agent step sequences for dynamic execution |
---
## Decision Tree
- **NEVER answer directly. ALWAYS delegate.** Multi-step chains:
+ **Delegate real engineering work; trivial/factual/conversational questions may be answered directly.** Multi-step chains:
- Bug fix -> debugger -> developer
- Complex feature -> analyst -> architect -> developer
- Docs / library -> researcher -> tech-writer
- Simple feature / tests / UI / code question -> developer
- Architecture question -> architect
- Requirements / scope / planning / ambiguous -> analyst
- Review / security -> reviewer · CI/CD -> devops · DB / perf -> optimizer
- Prompt / guardrail / system-prompt / eval / LLM-judge -> prompt-engineer
- MCP server build / tool schema / transport -> mcp-builder
- Git / commit / merge / push -> gitops
- After ANY worktree agent completes -> gitops (commit + merge + push)
- Multi-agent coordination -> coordinator
- Default -> analyst
---
## Key Rules
1. **Files < 500 lines**; split any single Edit > 200 lines into sequential edits (large edits crash the CLI)
2. **Types in types/index.ts** - Centralized TypeScript types
- 3. **Validate before commit** - `npm test` (frontend) / `pytest` (backend)
+ 3. **Validate before commit** - enforced by `hooks/pre-commit-validation.sh` (`npm test` frontend / `pytest` backend)
4. **tech-writer owns docs** - Only tech-writer modifies README/CHANGELOG
5. **developer owns code** - Only developer modifies source files
---
## Detailed protocols (auto-loaded skills — not duplicated here)
Detail lives in skills and loads on demand (progressive disclosure), so it stays out of static context:
- **Worktree delegation** (the developer-writes / gitops-commits sequence): `worktree-management` skill
- **MCP tool selection & fallback**: `mcp-tools` skill
- **Spec-driven dev / OpenSpec, conversation UUID path**: `spec-workflow` skill