Pipeline Gates & Transitions
Relevant source files
The following files were used as context for generating this wiki page:
Roughly utilizes a gated, subagent-per-task architecture to implement structured development workflows. A "gate" is a mandatory human confirmation point situated between pipeline stages, designed to ensure no silent transitions occur and that every stage's output is verified before proceeding to the next.
The orchestrator (such as the build or fix skill) coordinates the overall flow but delegates implementation to fresh subagents. This design prevents context overflow by providing each task with a clean environment while maintaining human control through explicit "yes/adjust/abort" decisions at every transition.
Sources: README.md:12-16, README.md:104-106, README.md:158-160
Pipeline Architecture
Roughly pipelines are composed of eight distinct stages, each separated by a gate. The primary orchestrators for these pipelines are the build (for additive features) and fix (for corrective work) skills.
Sequential Stage Flow
The flow follows a strict linear progression. For example, in the fix pipeline, the sequence is:
- Intake: Parsing arguments and confirming the issue scope.
- Investigate: Diagnosing the root cause using the investigator agent or inline logic.
- Plan: Drafting a discrete task-based plan.
- Review Plan: Mandatory automated verification of the plan.
- Implement: Executing tasks via fresh subagents.
- Review: Parallel code review by multiple agents.
- Verify: Running type checks, tests, and build commands.
- Wrap-up: Committing changes and marking plans as historical.
Sources: README.md:162-178, skills/fix/SKILL.md:27-142
Visualizing the Pipeline Flow
The following diagram illustrates the standard 8-stage gated progression used in Roughly pipelines.
Sources: README.md:162-178, skills/fix/SKILL.md:27-142
Gate Mechanics & Logic
Gates are implemented as inline conversation prompts that pause execution. The user must provide a valid response to advance or terminate the process.
Decision Options
Users typically have three primary options at any given gate:
- yes: Advances the pipeline to the next stage.
- Middle Option: Context-dependent actions such as "revise plan," "investigate further," or "adjust scope."
- abort: Stops the pipeline immediately, preserving work done but preventing further automated actions.
Sources: README.md:108-120, skills/fix/SKILL.md:52, skills/fix/SKILL.md:68
Plan Review Gate (Stage 4)
Stage 4 is unique because it contains a mandatory subagent dispatch (review-plan) that must return a PASS verdict before the human gate is even presented.
Subagent Transitions
A key philosophy of Roughly is "Subagent-per-task." This means that when the pipeline transitions to the Implementation stage (Stage 5), it does not use a single agent. Instead, it iterates through a list of tasks defined in the plan, dispatching a "fresh" subagent for each one.
Implementation Loop & Two-Stage Review
Each task transition within Stage 5 includes its own micro-gate involving a two-stage review:
- Stage 1 (Spec Compliance): The orchestrator checks if the subagent modified only the listed files and followed the task description.
- Stage 2 (Quality Check): The orchestrator runs type checks, linting, and tests.
Sources: README.md:82-84, skills/fix/SKILL.md:131-158
Context Compaction
To manage token usage and prevent context overflow—the #1 failure mode for long AI sessions—the orchestrator performs "context compaction" at specific transition points.
| Transition Point | Purpose |
|---|---|
| Before Stage 2 | Preserve headroom for extensive codebase searching during investigation. |
| Before Stage 5 | Clear history before implementation tasks begin. |
| Before Stage 6/7/8 | Ensure focused context for review and verification steps. |
Sources: README.md:204-206, skills/fix/SKILL.md:58, skills/fix/SKILL.md:117-120
Failure Handling & Abort Transitions
When a transition cannot be completed due to failure or user choice, the system enters a defined abort or escalation state.
Escalation Conditions
Transitions may fail automatically if certain thresholds are met, resulting in escalation to the human:
- Stage 4: Two consecutive
NEEDS REVISIONverdicts from thereview-planagent without reachingPASS. - Stage 5c: Two failed attempts by a subagent to answer clarifying questions or four failed auto-fix attempts for quality checks.
- Stage 6: Two failed review-fix cycles.
Sources: skills/fix/SKILL.md:111-115, skills/fix/SKILL.md:154-162, skills/fix/SKILL.md:173-176
Abort Procedure
If a user selects "abort" at any gate, the pipeline triggers a standardized abort handling procedure. This includes logic for git state management (e.g., git reset or git checkout) and instructions for handling orphaned plan files.
Sources: skills/shared/abort-handling.md:1-10, skills/fix/SKILL.md:220
Configuration & Hooks
Transitions are also governed by system-level hooks and project maturity levels.
Maturity-Based Gates
During setup, the project is classified (Greenfield, Scaffolded, or Established). This classification determines which transitions are available. For example, the investigator agent transition in the fix pipeline is only offered for "Established" projects (50+ files).
Sources: skills/setup/SKILL.md:11-23, README.md:214-222
Operational Hooks
A UserPromptSubmit hook (plan-mode-gate.sh) is used to block transitions into the build or fix pipelines if the user's IDE (Claude Code) is currently in "plan mode." This ensures the orchestrator has full control over the conversational flow.
Sources: skills/setup/SKILL.md:94-96, CLAUDE.md:111-113
Conclusion
Pipeline Gates & Transitions form the "loud" and "opinionated" core of the Roughly plugin. By enforcing human-in-the-loop confirmation at eight key stages and utilizing automated subagent-per-task dispatches, the system provides a robust framework for complex software development tasks while minimizing the risks of AI context drift or silent implementation errors.