Philosophy & Key Principles
Relevant source files
The following files were used as context for generating this wiki page:
- README.md
- CLAUDE.md
- CONTRIBUTING.md
- skills/build/SKILL.md (Referenced via README and CLAUDE.md structure)
- skills/review-plan/SKILL.md
- agents/agent-preamble.md
Roughly is a Claude Code plugin designed to implement gated, subagent-per-task development pipelines. The core philosophy centers on maintaining high code quality and context integrity by breaking down complex implementation tasks into smaller, verifiable units executed by specialized AI agents. This approach addresses the common failure mode of "context overflow" in long AI sessions by ensuring each subagent operates within a clean, focused context window.
Sources: README.md:1-5, README.md:76-80
Core Architectural Pillars
The Roughly system is built upon four primary architectural ideas that govern how features are built and bugs are fixed within a project.
Subagent-per-Task Execution
Roughly avoids the use of a single, long-running agent for complex features. Instead, the orchestrator (the build or fix skill) decomposes an implementation plan into discrete tasks. For every task, a fresh subagent is dispatched with a clean context, preventing the accumulation of "cruft" or irrelevant history that typically leads to AI confusion.
Sources: README.md:82-85, CLAUDE.md:73-75
Mandatory Gated Transitions
The pipeline is designed to be "loud" and "gated." No stage in a development pipeline starts until the previous one has been verified and approved by the human user. These gates serve as confirmation points where the user must explicitly decide to proceed, adjust the current work, or abort.
Sources: README.md:8-10, README.md:106-115
Two-Stage Review and Verification
After every individual task implementation, Roughly performs a dual check:
- Spec Compliance: Did the subagent adhere strictly to the plan and modify only the intended files?
- Quality Check: Does the new code pass the project's internal quality gates, such as type checks and builds?
Sources: README.md:87-90, CLAUDE.md:79-80
Shared Project Context
All agents, regardless of their specific task, are anchored by a set of shared context files. These provide project-specific awareness without requiring the orchestrator to pass the entire codebase into every prompt.
- CLAUDE.md: Contains project stack, commands, and coding conventions.
- .roughly/known-pitfalls.md: A living document of "gotchas" and anti-patterns discovered during development.
Sources: README.md:97-101, agents/agent-preamble.md:1-20
Development Pipeline Flow
The following diagram illustrates the standard build pipeline, highlighting the gated transitions and subagent dispatches.
The pipeline drives implementation from initial intake to final commit, ensuring every step is validated.
Sources: README.md:144-154, skills/review-plan/SKILL.md
Agent Specialization & Model Selection
Roughly employs a specialized agent model where different AI models are selected based on the complexity and cognitive requirements of the task.
| Agent | Default Model | Primary Responsibility |
|---|---|---|
| Discovery | Sonnet | Researching codebase for existing patterns and reuse opportunities. |
| Epic Reviewer | Opus | High-level holistic review of epics to catch structural/architectural issues. |
| Code Reviewer | Sonnet | Identifying bugs, logic errors, and security vulnerabilities in diffs. |
| Investigator | Sonnet | Tracing code paths to diagnose the root cause of reported bugs. |
| Doc Writer | Sonnet | Maintaining CLAUDE.md and known-pitfalls.md based on pipeline outcomes. |
Sources: README.md:182-192, CLAUDE.md:81-82
Maturity-Based Adaptation
The project's "Maturity Level" is a key principle that dictates how Roughly interacts with a codebase. The system adapts its behavior based on the number of source files detected during setup.
Roughly scales its complexity alongside the project it manages.
Sources: README.md:231-238, skills/setup/SKILL.md:11-30
Maturity Levels and Behaviors
| Level | Trigger | Behavioral Changes |
|---|---|---|
| Greenfield | < 10 files | Skips tests/type-checks if not configured; avoids complex maturity agents. |
| Scaffolded | 10-50 files | Enables doc-writer to suggest reorganization once known-pitfalls.md exceeds 80 lines. |
| Established | 50+ files | Offers the investigator agent for bugs and a Stop hook for continuous type-checking. |
Sources: README.md:231-238, skills/setup/SKILL.md:11-30
Principle of "Loud" Failure
A critical design decision (ADR-009) is the implementation of the plan-mode-gate. Roughly intentionally prevents users from running implementation pipelines while Claude Code's native "Plan Mode" is active. This ensures that the orchestrator's gated logic is not bypassed or confused by the internal planning mechanisms of the underlying LLM interface.
Furthermore, if a verification step fails (e.g., a type-check drift), the verify-all hook produces immediate, non-blocking feedback after every turn to ensure developers are aware of regressions as soon as they occur.
Sources: CLAUDE.md:83-84, README.md:281-285, CONTRIBUTING.md:195-205
Conclusion
The philosophy of Roughly is rooted in the belief that AI-assisted development is most effective when constrained by rigorous structure and human oversight. By enforcing a subagent-per-task model and mandatory validation gates, Roughly transforms the LLM from an unpredictable collaborator into a structured engine for reliable code implementation.
Sources: README.md:313-322