Plan File Management
Relevant source files
The following files were used as context for generating this wiki page:
Plan File Management within the Roughly project refers to the structured lifecycle, storage, and verification of implementation plans generated during build and fix pipelines. These plans act as intermediate artifacts that bridge discovery/investigation and final code implementation, ensuring that changes are scoped, verified, and historically recorded.
Plans are primarily stored in the .roughly/plans/ directory (migrated from docs/plans/ in v0.1.6). They follow a specific Markdown schema that includes task breakdowns, file tables, and blast radius assessments. The management system ensures that plans are not only created but also reviewed by subagents, associated with active Git branches, and marked as historical once merged to prevent drift and ambiguity.
Sources: README.md:126-130, CONTRIBUTING.md:143-150, skills/fix/SKILL.md:65-71
Plan Lifecycle and Storage
Plans move through distinct stages from creation to archival. Orchestrator skills like /roughly:build and /roughly:fix manage the initialization and implementation based on these files.
Creation and Naming
Plans are generated during Stage 3 of the pipelines. The orchestrator ensures the storage directory exists using mkdir -p .roughly/plans/. Naming conventions depend on the pipeline type:
- Build Plans: Named using the pattern
<feature>-plan.md. - Fix Plans: Named using the pattern
fix-<issue-id-or-name>-plan.md.
Sources: skills/fix/SKILL.md:65-103, CONTRIBUTING.md:148-151
Storage Location Evolution
The project moved plan storage to consolidate runtime state.
- Legacy Location:
docs/plans/ - Current Location:
.roughly/plans/
The presence of*-plan.mdfiles in the legacy directory alongside a.roughly/installation triggers a migration warning, requiring the user to run/roughly:upgrade.
Sources: CONTRIBUTING.md:143-147, skills/review-plan/SKILL.md:17-19
Lifecycle Flow
The following diagram illustrates the transition of a plan file through the pipeline stages.
The diagram shows the sequence from generation in Stage 3 to historical marking in Stage 8.
Sources: skills/fix/SKILL.md:65-188, skills/shared/stage-8-wrap-up.md:16-25
Plan Structure and Verification
A plan must adhere to a strict Markdown schema to be processable by implementation subagents and the review-plan agent.
Required Components
| Component | Description |
|---|---|
| Plan-format-version | Must be set to 1. |
| File Table | A Markdown table listing Files, Actions, and associated Tasks. |
| Tasks Section | Discrete tasks (T1, T2...) with titles, file lists, actions, details, and verify commands. |
| UI Flag | Per-task UI: yes/no indicator to load specific design subagents. |
| Blast Radius | Section documenting files to NOT modify and potential side effects. |
Sources: skills/fix/SKILL.md:73-101, README.md:108-112
Mandatory Verification
Before implementation, the review-plan subagent verifies the plan against the codebase. It checks for:
- Completeness: Every requirement must have a task and every edit site must be enumerated.
- Assumptions: Validates file paths and API signatures.
- Overengineering: Ensures tasks are not unnecessarily complex.
- Grep Hazards: Detects
grep -Fcco-location issues and self-defeating verify patterns.
Sources: skills/review-plan/SKILL.md:32-113
Plan State Tracking
Roughly provides tools to identify the current "in-progress" plan and track maturity decisions.
Branch Association
The /roughly:help command uses a heuristic to associate plan files with the current Git branch.
- Normalization: It strips prefixes (e.g.,
feat/,fix/) and replaces dots with dashes. - Matching: It checks if the normalized branch name is a substring of the normalized plan filename.
- Status Reporting: If exactly one match is found, it is flagged as the in-progress plan. If multiple matches occur, the user is prompted to select the current plan.
Sources: skills/help/SKILL.md:86-113
Plan State Summary
| State | Detection Logic |
|---|---|
| In-Progress | Branch name matches plan filename via heuristic. |
| Historical | First line starts with > **Status:** Historical. |
| Legacy | Located in docs/plans/ rather than .roughly/plans/. |
Sources: skills/help/SKILL.md:115-145, CONTRIBUTING.md:153-158
Archival and Historical Marking
To prevent implementation actuals from drifting into "stale prose" that confuses review tools, plans are finalized during the wrap-up stage.
The Status Block
In Stage 8, the orchestrator prepends a Status block to the plan file in a second wrap-up commit. The format is strictly defined:
> **Status:** Historical — implemented and merged in commit <SHA> on <YYYY-MM-DD>. This plan was an active build/fix artifact; treat as historical reference only.
- SHA: The implementation commit SHA (parent of the wrap-up commit).
- Date: The ISO
YYYY-MM-DDdate of completion.
Sources: skills/shared/stage-8-wrap-up.md:16-25, CONTRIBUTING.md:159-165
Implementation Sequence
The archival process ensures the implementation is committed before the plan is marked historical.
The sequence diagram illustrates the two-commit process for implementation and plan archival.
Sources: skills/shared/stage-8-wrap-up.md:16-25
Conclusion
Plan File Management in Roughly is a robust system that treats documentation as a first-class citizen of the development lifecycle. By enforcing a strict structure, mandatory subagent review, and a formal archival process, it ensures that AI-driven implementations remain transparent, verifiable, and historically traceable. This prevents the accumulation of stale, confusing documentation and maintains a clear audit trail for every feature and fix.