Build Pipeline
Relevant source files
The following files were used as context for generating this wiki page:
The Build Pipeline in Roughly is a gated, 8-stage development workflow designed to implement new features or stories. It utilizes a "subagent-per-task" architecture where a central orchestrator coordinates specialized Claude processes for discovery, planning, implementation, and review. This separation of concerns prevents context overflow and ensures high-quality output by requiring human confirmation at critical "gates" between stages.
The pipeline is primarily driven by the /roughly:build command and operates on "epic files"—plain Markdown specifications typically stored in docs/epics/. It emphasizes rigorous verification, including a mandatory plan review stage before any code is written and a two-stage review process (spec compliance and technical quality) after every individual task completion.
Sources: README.md:129-137, README.md:143-150, CLAUDE.md:61-68
Pipeline Architecture and Stages
The pipeline follows a sequential 8-stage flow. Each stage must be confirmed by the user before the next begins. If a user aborts at any gate, work is preserved but the pipeline stops.
High-Level Flow Diagram
The following diagram illustrates the linear progression and human gates of the build pipeline.
Sources: README.md:139-142, README.md:152-167
Summary of Stages
| Stage | Name | Purpose | Key Subagent/Agent |
|---|---|---|---|
| 1 | Intake | Parse epic files or feature descriptions and confirm scope. | Orchestrator |
| 2 | Discover | Research codebase for patterns, reuse, and blast radius. | discovery agent |
| 3 | Plan | Generate a structured implementation plan with discrete tasks. | Orchestrator |
| 4 | Review Plan | Mandatory verification of the plan against the actual codebase. | review-plan subagent |
| 5 | Implement | Execute tasks sequentially using fresh subagents for each. | sonnet subagents |
| 6 | Review | Perform parallel 3-agent code review (Logic, Static, Security). | code-reviewer, static-analysis, silent-failure-hunter |
| 7 | Verify | Run full project verification loop (Type check + Test + Build). | verify-all skill |
| 8 | Wrap-up | Commit changes and mark the implementation plan as historical. | Orchestrator / doc-writer |
Sources: README.md:141-142, README.md:195-207, skills/fix/SKILL.md:46-240
Discovery and Planning (Stages 1-3)
The pipeline begins by analyzing the input specification. Stage 2 dispatches the discovery agent, which explores the codebase to find existing patterns, utilities, and potential risks (blast radius). It specifically checks .roughly/known-pitfalls.md to avoid repeating past mistakes.
In Stage 3, the orchestrator writes a structured Plan File to .roughly/plans/. This plan must include:
- File Table: Listing every file to be modified or created.
- Discrete Tasks (T1, T2...): Specific instructions, verification commands, and a
UI: yes/noflag. - Blast Radius: Areas to watch or avoid modifying.
Sources: agents/discovery.md:14-25, skills/fix/SKILL.md:88-124, README.md:244-249
Mandatory Plan Review (Stage 4)
Stage 4 is a critical blocking stage where the implementation plan is verified against the codebase by a specialized subagent. This subagent runs up to 3 iterations to ensure:
- Completeness: Every requirement in the spec is covered by a task.
- Assumptions: File paths, function signatures, and types exist or are valid.
- Enumeration: Every edit site must be separately numbered in the plan.
- Verify Commands: The commands provided to verify tasks are not "self-defeating" and accurately match the spec scope.
If the subagent issues a NEEDS REVISION verdict, the orchestrator applies edits and re-reviews until it passes or reaches the iteration limit.
Sources: skills/review-plan/SKILL.md:25-88, skills/fix/SKILL.md:131-158, README.md:92-95
Implementation and Task Verification (Stage 5)
Implementation occurs task-by-task. For each task, the orchestrator dispatches a fresh subagent with a clean context window.
Two-Stage Task Review
After each subagent completes a task, a two-stage review is performed before moving to the next:
- Spec Compliance: The orchestrator verifies that the subagent modified only the listed files and that the specific task verification command passed.
- Quality Check: The orchestrator runs project-wide type checks and lints. It may attempt auto-fixes (up to 4 for type checks, 2 for tests).
Sources: skills/fix/SKILL.md:162-212, README.md:86-90
Final Review and Wrap-up (Stages 6-8)
Once all tasks are implemented, the pipeline enters project-wide review and verification.
Parallel Review (Stage 6)
The pipeline dispatches three agents in parallel:
- code-reviewer: Checks for logic, security, and project conventions.
- static-analysis: Runs full build/lint commands.
- silent-failure-hunter: Searches for swallowed errors and missing handlers.
Wrap-up and Historical Marking (Stage 8)
In the final stage, the orchestrator performs the following:
- Commit: Creates a feature commit with a structured message.
- Historical Marking: Prepends a Status block to the plan file (e.g.,
> **Status:** Historical — implemented and merged in commit <SHA>...). This ensures the plan is no longer treated as an active specification. - Pitfall Triage: Asks if any new pitfalls were discovered. If so, it dispatches the
doc-writeragent to update.roughly/known-pitfalls.md.
Sources: README.md:200-205, skills/shared/stage-8-wrap-up.md:10-40, agents/doc-writer.md:14-22
Conclusion
The Build Pipeline provides a high-integrity path for feature development by enforcing strict isolation between implementation tasks and mandating multiple layers of automated and human review. By utilizing specialized subagents and project-specific context (CLAUDE.md), it minimizes context drift and prevents common AI implementation errors.