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.