Introduction to Roughly
Relevant source files
The following files were used as context for generating this wiki page:
- README.md
- CLAUDE.md
- skills/setup/SKILL.md
- skills/build/SKILL.md (Referenced via documentation in README/CLAUDE)
- skills/fix/SKILL.md
- CONTRIBUTING.md
Roughly is a Claude Code plugin designed to implement gated, subagent-per-task development pipelines. It serves as an orchestrator that manages complex software development workflows—such as building new features or fixing bugs—by decomposing them into discrete tasks executed by specialized subagents. This approach is designed to prevent context overflow, a common failure mode in long-form AI development sessions, by ensuring each subagent operates with a clean and focused context.
The system is built on the philosophy of being "Loud," "Gated," and "Opinionated." Every stage of a pipeline requires human confirmation (gates), ensuring no silent transitions or unverified code changes occur. Roughly adapts to the project's maturity level, providing different tools and checks depending on whether a project is greenfield, scaffolded, or established.
Sources: README.md:3-8, README.md:214-222, CLAUDE.md:3-6
Core Architectural Concepts
Roughly's architecture is centered around four key ideas that govern how it interacts with the codebase and the user.
Subagent-per-task Execution
Instead of a single long-running conversation, Roughly dispatches a fresh Claude process (subagent) for every specific task (discovery, planning, implementation, review). The main skill acts only as an orchestrator, maintaining the high-level state while subagents handle the "heavy lifting" of code manipulation.
Gated Pipelines
Pipelines are divided into stages (e.g., Intake, Plan, Implement, Verify). A "gate" is a human confirmation point between these stages. The orchestrator presents the results of the previous stage and requires a "yes," "adjust," or "abort" decision before proceeding.
Two-Stage Review
After every implementation task, the orchestrator performs two checks:
- Spec Compliance: Ensuring the subagent followed the specific plan instructions.
- Quality Check: Running automated tools like type checkers, linters, and tests to verify code integrity.
Shared Context Files
Roughly utilizes specific files to maintain project-wide knowledge across multiple subagent dispatches:
CLAUDE.md: Stores project stack, commands, and conventions..roughly/known-pitfalls.md: A catalog of "gotchas" and recurring issues discovered during development.
Sources: README.md:58-82, README.md:95-104, CLAUDE.md:12-25
System Workflow
The following diagram illustrates the high-level flow of the Roughly implementation pipeline, specifically the /roughly:build command.
This diagram shows the 8-stage pipeline where human intervention is required at multiple checkpoints to ensure quality and alignment with the original specification.
Sources: README.md:131-137, skills/fix/SKILL.md:40-230
Key Components and Agents
Roughly employs several specialized agents and skills to manage different aspects of the development lifecycle.
Specialized Agents
| Agent | Model | Purpose |
|---|---|---|
| Discovery | Sonnet | Researches codebase for patterns/reuse before planning. |
| Investigator | Sonnet | Diagnoses bugs by tracing code paths (Fix pipeline). |
| Epic-Reviewer | Opus | Performs high-level technical accuracy and risk reviews of epics. |
| Code-Reviewer | Sonnet | Standard review for bugs, security, and conventions. |
| Doc-Writer | Sonnet | Updates CLAUDE.md and known-pitfalls.md at wrap-up. |
Sources: README.md:158-168, agents/discovery.md:1-10, agents/epic-reviewer.md:1-12
Primary User Commands
| Command | Usage |
|---|---|
/roughly:setup | Initial bootstrap; detects maturity and configures docs. |
/roughly:build | Orchestrates new feature implementation (8-stage pipeline). |
/roughly:fix | Orchestrates bug fixes with root-cause investigation. |
/roughly:review | Runs parallel reviews (Code, Static Analysis, Failure Hunter). |
/roughly:verify-all | Standalone loop for type-check, tests, and build verification. |
Sources: README.md:107-128, skills/help/SKILL.md:20-40
Project Maturity and Evolution
Roughly adapts its behavior based on the size and complexity of the project, determined by source file count during the setup phase.
The system "grows" with the project, offering more advanced automation like the Investigator agent or automated Stop hooks as the codebase matures.
Sources: README.md:195-204, skills/setup/SKILL.md:31-48
Configuration and Metadata
Roughly stores state and configuration in the project root to ensure persistence across sessions.
File Structure
CLAUDE.md: The canonical source of truth for the project context, read by all agents..roughly/workflow-upgrades: Tracks which maturity checks (likeinvestigator-v1) have been accepted or declined..claude/settings.json: Configures Claude Code hooks, such as theplan-mode-gate.shwhich prevents pipeline invocation while in Claude's native plan mode..roughly/plans/: Contains historical and active implementation plans.
Sources: README.md:33-41, CLAUDE.md:12-25, skills/setup/SKILL.md:120-150
Required Setup Context
During /roughly:setup, the system mandates six specific pieces of information to function effectively:
- Stack: Tech stack details (e.g., TypeScript, FastAPI).
- Build Command: How to compile/build the project.
- Type Check: Command for static analysis (or 'none').
- Test Command: How to run the test suite.
- Convention: The single most important project rule for agents.
- Domain: A one-sentence description of the project's purpose.
Sources: skills/setup/SKILL.md:65-88
Summary
Roughly provides a structured, multi-agent framework for interacting with Claude Code. By enforcing a gated workflow and utilizing specialized agents for research, planning, and review, it ensures that AI-driven development remains accurate, high-quality, and manageable even as projects scale in complexity. Its ability to adapt through maturity levels and maintain a persistent knowledge base via CLAUDE.md and known-pitfalls.md makes it a robust tool for professional software engineering.