Governance Agents
Relevant source files
The following files were used as context for generating this wiki page:
Governance Agents within the Roughly ecosystem are specialized subagents designed to maintain project integrity, enforce conventions, and manage technical knowledge across the development lifecycle. Unlike implementation agents that focus on creating code, Governance Agents provide oversight through research, diagnostic investigation, multi-dimensional code review, and automated documentation updates.
These agents are orchestrated by core pipeline skills like build and fix, ensuring that every change is validated against project-specific standards documented in CLAUDE.md and .roughly/known-pitfalls.md. By isolating these concerns into distinct agents, the system prevents context overflow and maintains a high bar for technical accuracy and best practices.
Sources: README.md:124-142, agents/agent-preamble.md:16-19
Governance Agent Roles
The project defines several specialized agents that fulfill governance functions. These are summarized in the table below:
| Agent Name | Model | Primary Function | Core Context Files |
|---|---|---|---|
epic-reviewer | Opus | Pre-implementation holistic review of epics | CLAUDE.md, known-pitfalls.md |
code-reviewer | Sonnet | Post-implementation review for bugs and conventions | CLAUDE.md, known-pitfalls.md |
doc-writer | Sonnet | Automated documentation maintenance | CLAUDE.md, known-pitfalls.md |
discovery | Sonnet | Pre-planning research and blast radius mapping | CLAUDE.md, known-pitfalls.md |
investigator | Sonnet | Diagnostic root-cause analysis for bug fixes | CLAUDE.md, known-pitfalls.md |
Sources: README.md:204-213, agents/epic-reviewer.md:1-10, agents/doc-writer.md:1-10
Pre-Implementation Governance
Before implementation begins, governance is exercised through the discovery and epic-reviewer agents. These agents ensure that the proposed work is feasible and aligned with the existing codebase.
Epic Reviewer Agent
The epic-reviewer is the only agent that utilizes the Opus model, reflecting its role in high-level reasoning and cross-story analysis. It validates that stories within an epic are technically sound, well-ordered, and contain testable acceptance criteria (AC).
Review Dimensions:
- Technical Accuracy: Validates feasibility against the actual codebase.
- AC Mutual Satisfiability: Ensures overlapping ACs (same file path, same step, etc.) do not create structural impossibilities.
- Overengineering: Identifies complexities beyond current requirements.
Sources: agents/epic-reviewer.md:11-28, README.md:205
Discovery Agent
The discovery agent researches features before planning. It identifies existing patterns to leverage and maps the "blast radius" of potential changes to prevent unintended side effects in protected files.
Sources: agents/discovery.md:14-23
Post-Implementation and Diagnostic Governance
Governance continues during and after implementation to ensure code quality and capture new knowledge.
Multi-Agent Code Review
Roughly implements a parallel three-agent review process. The code-reviewer is a primary component of this, focusing on logic errors, security vulnerabilities, and consistency with project conventions.
This diagram illustrates the parallel review flow used to synthesize a unified report grouped by severity.
Sources: skills/review/SKILL.md:18-50, agents/code-reviewer.md:13-22
Investigator Agent
For the fix pipeline, the investigator agent is utilized in projects with 50+ source files. It traces execution paths and forms hypotheses to identify the root cause of issues, providing evidence-based proposals for fixes.
Sources: agents/investigator.md:15-22, README.md:175-180
Knowledge Persistence: The Doc Writer
The doc-writer agent is the final gate in the governance process. It ensures that discoveries made during build or fix cycles—such as new pitfalls or architectural decisions—are persisted for future AI runs.
Update Targets:
.roughly/known-pitfalls.md: New traps or failure patterns discovered.CLAUDE.md: Updated project conventions or stack changes.docs/adrs/: Significant architectural decisions.
The doc-writer follows a strict template for its return summary, indicating exactly which paths were successfully updated or providing specific failure reasons.
Sources: agents/doc-writer.md:12-70
Core Governance Logic: The Preamble
A critical aspect of all Governance Agents is the "Agent Preamble." This is a canonical sync reference that mandates agents read two specific files before performing any task:
CLAUDE.md: For project conventions, commands, and tech stack..roughly/known-pitfalls.md: For known issues and domain-specific risks.
This shared context ensures that governance is not generic but deeply rooted in the specific project's history and requirements.
Sources: agents/agent-preamble.md:1-19
Conclusion
Governance Agents form a robust oversight layer in the Roughly framework. By separating discovery, diagnosis, review, and documentation into specialized subagents, the system maintains high technical standards and ensures that the project's knowledge base evolves alongside its code. This gated approach prevents the common AI failure mode of context overflow while enforcing human-approved quality gates at every critical juncture.
Sources: README.md:124-142, agents/doc-writer.md:1-11