Folders Turn LLMs into Specialized Agents
Specialize LLMs by pointing them at project folders with CLAUDE.md instructions, docs, runbooks, and skills—creating agents that inherit your codebase's context. Scale to 44 parallel agents via a file-based dispatch layer using /hey for status and /orchestrate for task routing.
Build Folder-Based Agents with Layered Context
Point any LLM like Claude Opus at a project folder to instantiate a specialist agent: the folder provides all necessary context, turning a general model into an expert without re-explaining basics each time. Core components include a CLAUDE.md file defining conventions (e.g., Rails naming, deploy workflows, database patterns), docs/developer-docs/ for architecture reports and pipelines, docs/runbooks/ and docs/investigations/ for operational memory from incidents, and .claude/agents/ for refined specialists like reviewers or planners.
Specify a reading order—e.g., CLAUDE.md first, then architecture doc, system reports, prompts—to ensure consistent onboarding. Separate folders create distinct agents: ~/cora/ for feature building (inherits full app code and knowledge), ~/cora-agent/ for ops (no production code; includes skills for AppSignal error querying, Render log tailing, Postgres read-replica access, Intercom ticket reading, GitHub deploy correlation, plus bin/ daemons for scheduling/inbox/health, postmortems, and deploy journals). This yields role-specific behavior: Rails engineer in one folder, ops engineer in another, all on the same model.
Result: Agents inherit months of compound engineering accumulation, enabling reliable work without swarms' coordination overhead. Anthropic research confirms multi-agent setups with Opus lead + Sonnet subs outperform single Opus by 90% on research but burn 15x tokens and struggle on coding's fewer parallel steps.
Scale with File-Based Dispatch Layer
Manually juggling 44 agents across folders overwhelms humans (fine at 5 tabs, unsustainable at 44). Build a lightweight Ruby daemon as dispatch layer: watches a spawn-request directory, routes via file-based messaging (no custom protocols/networking). Workflow: /orchestrate "Fix GitHub issue #1765" spawns lead agent to decompose into subtasks (written as files); daemon assigns to appropriate folder-workers; workers report via files; daemon polls status every 60s.
Key commands replace 20 tabs:
- /hey: Morning briefing scans projects for completed/errored/blocked tasks + high-priority issues, giving full attention map across codebases/ops/orchestration.
- /orchestrate: Delegates to context-aware workers; outputs PRs/GitHub comments for async review.
Monitor via tmux panes for live agent views and agent-tree dashboard (statuses: working/waiting/done/error). Humans retain control: decide tasks/routes, review outputs—dispatch just tracks.
Avoid Failures by Building Trust First
Scale exposes issues: encoding bugs (e.g., em-dashes/curly quotes crash US-ASCII daemons), context drift (stale/dupe tasks requiring manual prune), agent stalls (indefinite 'working' from API floods/input waits). Core rule: Never 'vibe orchestrate'—mimic vibe-coding pitfalls. For new projects: Manually setup folder, iterate compound engineering loop (plan/use/trust), run flows yourself until predictable, then dispatch. Skipping yields dupe PRs/issues.
Trade-offs: Folders scale simply (no Rube Goldberg swarms after 3 months failure), but demand upfront investment in context. Future: Pairs with managed services like Anthropic's Claude Managed Agents for sandboxing/state/tools, focusing humans on specialization.