komlukkomluk/scaffolding/CLAUDE.md

scaffolding

CLAUDE.md16 starsChanged 5 days agoMITView on GitHub

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. Delegate via: Task(subagent_type="scaffolding:<agent>", prompt="...", description="...") Response format: [Agent: name] Task -> Result (1-2 lines) Delegate real engineering work; trivial/factual/conversational questions may be answered directly. Multi-step chains:

In this repository39 other files it gives its agents.
- agent-commsSkill
- agent-memorySkill
- api-designSkill
- context-engineeringSkill
- database-optimizationSkill
- distillSkill
- docker-templatesSkill
- error-handlingSkill
- frontend-designSkill
- github-actions-templateSkill
- git-operationsSkill
- logging-standardsSkill
- mcp-toolsSkill
- monitoring-observabilitySkill
- mui-stylingSkill
- necessity-firstSkill
- pattern-recognitionSkill
- planning-methodologySkill
- python-patternsSkill
- quality-validationSkill
- react-patternsSkill
- research-methodologySkill
- reverse-engineer-anythingSkill
- security-review-checklistsSkill
- semantic-memory-mcpSkill
- skill-authoringSkill
- sofa-searchSkill
- spec-designSkill
- spec-developSkill
- spec-researchSkill
- spec-reviewSkill
- spec-workflowSkill
- state-managementSkill
- systematic-debuggingSkill
- testing-strategySkill
- ui-ux-pro-maxSkill
- verification-before-completionSkill
- watch-patternsSkill
- worktree-managementSkill

The file

We split this CLAUDE.md into the rules it gives an agent

7 rules. About 0 are common, 5 are distinctive, and 2 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
NEVER use explore for planning/analysis: - Only for quick file searches
line 6
Distinctive:
Auto-route: - Treat engineering requests as tasks.
line 15
Distinctive:
After ANY worktree agent completes -> gitops (commit + merge + push)
line 59
Distinctive:
Default -> developer if scope is clear and small.
line 61
Very specific:
When delegating analysis, design or debugging (analyst, architect, debugger, optimizer, reviewer), tell the specialist to start from the …
line 62
Distinctive:
tech-writer owns docs: - Only tech-writer modifies README/CHANGELOG
line 71
Distinctive:
developer owns code: - Only developer modifies source files
line 72

≈ “Common” is an estimate: at least 1 in 5 of the 26,980 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

CLAUDE.md

Protocol

<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>

<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:

Auto-route - Treat engineering requests as tasks. Route to the right agent.
No confirmation - For real work, don't ask. Just delegate.
Concise responses - Short status. No verbose explanations unless asked.

Delegate via: Task(subagent_type="scaffolding:<agent>", prompt="...", description="...") Response format: [Agent: name] Task -> Result (1-2 lines)

Agents (13)

Agent	Tier	When to Use
scaffolding:analyst	opus	Ambiguous requests, requirements, scope assessment, feasibility, proposal writing
scaffolding:architect	opus	System design, API design, implementation planning, multi-file refactoring, agent orchestration
scaffolding:researcher	sonnet	New API integration, library questions, best practices (gate: score >= 80)
scaffolding:developer	sonnet	Implementation, bug fixes, features, tests, UI/styling (gate: validation passes)
scaffolding:debugger	opus	Bug reports, unexpected behavior, errors
scaffolding:reviewer	sonnet	After code changes, security analysis, threat modeling (gate: no criticals)
scaffolding:optimizer	sonnet	Performance issues, database design, schema, migrations, queries
scaffolding:prompt-engineer	sonnet	System prompts, prompt templates, guardrail rules, prompt evals, LLM-judge rubrics, injection defense
scaffolding:mcp-builder	sonnet	Build/modify MCP servers, tool schema design, stdio/http transport, MCP auth/secret launchers
scaffolding:tech-writer	haiku	Documentation, CHANGELOG updates
scaffolding:devops	sonnet	CI/CD, deployment, infrastructure
scaffolding:gitops	haiku	Branch management, conflict resolution, git history, worktree recovery, push to remote
scaffolding:coordinator	sonnet	Analyzes tasks, decomposes into agent step sequences for dynamic execution

Decision Tree

Delegate real engineering work; trivial/factual/conversational questions may be answered directly. Multi-step chains:

Bug fix -> debugger -> developer
Complex feature (multi-file / new system) -> analyst -> architect -> developer
Small change (single file, clear scope) -> developer directly (skip analyst/architect)
Docs / library -> researcher -> tech-writer
Simple feature / tests / UI / code question -> developer
Architecture question -> architect
Requirements / scope / planning / ambiguous -> analyst
Routine review -> reviewer (sonnet); security/threat-model -> reviewer with opus model override · 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 -> developer if scope is clear and small; analyst only when genuinely ambiguous
When delegating analysis, design or debugging (analyst, architect, debugger, optimizer, reviewer), tell the specialist to start from the project graph (mcp__graphify__*), then LSP, and use grep/Read only for exact lines

Key Rules

Files < 500 lines; split any single Edit > 200 lines into sequential edits (large edits crash the CLI)
Types in types/index.ts - Centralized TypeScript types
Validate before commit - enforced by hooks/pre-commit-validation.sh (framework-agnostic: runs the first detected validation entrypoint — Makefile/justfile/package.json/pytest/cargo/go/etc.; warns and passes if none found)
tech-writer owns docs - Only tech-writer modifies README/CHANGELOG
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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free