Agent Overview
Relevant source files
The following files were used as context for generating this wiki page:
Roughly utilizes a "subagent-per-task" architecture where specialized Claude processes are dispatched for isolated development activities. This design keeps individual agent contexts focused and prevents the context overflow commonly encountered in long, monolithic AI sessions. The system consists of seven distinct agents, each tailored with specific tools, models, and process instructions to handle phases like discovery, investigation, implementation review, and documentation.
Sources: README.md:46-52, CLAUDE.md:12-20
Core Agent Architecture
The Roughly framework distinguishes between Orchestrator Skills (which coordinate pipelines) and Subagents (which perform specific tasks). Most agents are powered by the Claude 3.5 Sonnet model, while high-level reasoning for epic reviews is reserved for Claude 3 Opus.
Shared Context Pattern
Every agent follows a "canonical sync reference" pattern for project context. Before executing their specific jobs, agents are instructed to read CLAUDE.md for project conventions and .roughly/known-pitfalls.md to avoid repeating documented errors. This ensures that even though agents are dispatched with fresh contexts, they remain project-aware.
Sources: agents/agent-preamble.md:16-20, README.md:61-66, CLAUDE.md:32-35
Dispatch Workflow
This diagram illustrates how an orchestrator (like the build or fix skill) dispatches various agents throughout the lifecycle of a feature or bug fix.
The Orchestrator skill coordinates the pipeline but relies on specialized subagents for technical execution and documentation updates.
Sources: README.md:139-166, CLAUDE.md:43-51
Detailed Agent Catalog
Roughly maintains a set of specialized agents, each defined by a YAML frontmatter containing their name, description, tools, and model.
| Agent | Model | Tools | Primary Purpose |
|---|---|---|---|
| Discovery | Sonnet | Glob, Grep, Read, Bash | Researching existing patterns and blast radius before planning. |
| Investigator | Sonnet | Glob, Grep, Read, Bash | Diagnosing bugs by tracing code execution paths. |
| Epic Reviewer | Opus | Glob, Grep, Read, Bash | Cross-story technical review and risk assessment for entire epics. |
| Code Reviewer | Sonnet | Glob, Grep, Read, Bash | Reviewing specific code changes for bugs and convention violations. |
| Static Analysis | Sonnet | N/A | Running type checks, lints, and builds via CLAUDE.md commands. |
| Silent Failure Hunter | Sonnet | N/A | Identifying swallowed errors and domain-specific risk patterns. |
| Doc Writer | Sonnet | Glob, Grep, Read, Write, Edit | Updating project docs (CLAUDE.md, pitfalls) after development. |
Sources: README.md:204-212, agents/discovery.md:1-7, agents/investigator.md:1-7, agents/epic-reviewer.md:1-7, agents/code-reviewer.md:1-7, agents/doc-writer.md:1-8
Discovery Agent
The Discovery agent is dispatched during build Stage 2. Its goal is to find reuse opportunities and map the "blast radius" of a proposed feature. It provides the orchestrator with the necessary technical context to draft an implementation plan.
- Key Output: Discovery Report including existing patterns, reuse opportunities, and identified risks.
Sources: agents/discovery.md:11-44, README.md:205
Investigator Agent
The Investigator is a specialized debugging agent offered to projects that have reached the "Established" maturity level (50+ source files). It performs root cause analysis by forming hypotheses and tracing code paths.
- Key Process: Forms 2-3 likely root causes and validates them against evidence before proposing a fix.
Sources: agents/investigator.md:11-50, README.md:237-240
Code Reviewer Agent
This agent is part of a parallel 3-agent review dispatch (alongside static-analysis and silent-failure-hunter). It focuses on logic, security, and project convention adherence.
- Review Dimensions: Correctness (null handling, race conditions), Security (OWASP top 10), and Pitfalls (domain-specific risks).
Sources: agents/code-reviewer.md:11-40, README.md:208
Doc Writer Agent
The Doc Writer maintains the project's living documentation. It is dispatched at the wrap-up stage if new pitfalls or conventions are identified. It is unique among agents for having Write and Edit tool access to specific files.
- Update Targets:
.roughly/known-pitfalls.md,CLAUDE.md, anddocs/adrs/. - Organization Logic: If
known-pitfalls.mdexceeds 80 lines, the agent suggests reorganization.
Sources: agents/doc-writer.md:12-40, README.md:211
Reasoning and Evaluation: Epic Reviewer
The epic-reviewer is the only agent utilizing the Claude 3 Opus model, selected for its superior cross-story reasoning capabilities. It evaluates an entire epic file before implementation begins to catch structural impossibilities and overengineering.
The sequence demonstrates the high-level validation performed by the Epic Reviewer, including codebase verification to ensure proposed approaches are feasible.
Sources: agents/epic-reviewer.md:11-65, CLAUDE.md:65
AC Mutual Satisfiability Check
A critical function of the Epic Reviewer is checking "AC Mutual Satisfiability." It looks for pairs of Acceptance Criteria (AC) that reference overlapping surfaces (same file, step, or prose region) to ensure they do not create a structural impossibility. For example, it flags if AC1 requires a modification while AC2 simultaneously forbids it.
Sources: agents/epic-reviewer.md:27-33
Conclusion
Roughly's agent system is built on specialized isolation and shared context. By using Sonnet for most tasks and Opus for complex epic reviews, the project optimizes for both speed and deep reasoning. The mandatory use of the agent preamble ensures all subagents adhere to the project's established rules, while the orchestrator skills manage the human-in-the-loop gates that govern agent transitions.