Spec & Epic Formats
Relevant source files
The following files were used as context for generating this wiki page:
Roughly utilizes structured Markdown files to define project requirements, implementation strategies, and bug fixes. These formats act as the primary input for Roughly's gated pipelines, enabling subagents to perform research, planning, and implementation with high precision. By standardizing these formats, Roughly ensures that requirements are testable and implementation artifacts are traceable.
The primary document types include Epics for feature sets, Issues for bug reports, and Plans for discrete implementation steps. These documents are stored within specific directories like docs/epics/ and .roughly/plans/ to maintain project organization.
Sources: README.md:162-164, README.md:188-190, CONTRIBUTING.md:144-147
Epic Format
Epics serve as the high-level specification for features in Roughly. They are typically stored in docs/epics/ and consist of multiple stories, each with specific acceptance criteria (AC). While the project does not enforce a rigid schema, a recommended structure is used to optimize agent performance during discovery and planning.
Epic Structure
A standard Epic includes a title, story breakdowns, and technical requirements.
| Component | Description |
|---|---|
| Title | An H1 heading defining the epic (e.g., # E02: User Authentication). |
| Story ID/Title | H2 headings for discrete units of work (e.g., ## Story 1: Login Flow). |
| Acceptance Criteria | A list of testable conditions prefixed with **AC:**. |
| Technical Approach | Optional notes on architecture or constraints. |
Sources: README.md:162-177, skills/audit-epic/SKILL.md:40-45
Acceptance Criteria (AC) Conventions
Acceptance criteria must be specific, testable, and complete. Roughly enforces strict conventions for how ACs are written to avoid ambiguity during implementation and review:
- Quoted-Wording Markers: When an AC quotes example wording containing metasyntactic notation (e.g.,
<placeholder>,...), it must useverbatim:for byte-for-byte matches orform:for illustrative structures. - Mutual Satisfiability: ACs that reference overlapping surfaces (same file, step, or prose region) must be jointly satisfiable. Conflicting ACs are flagged by the
epic-reviewerorreview-planagents. - Back-pointers: When an AC is amended in a later epic, the original epic must contain a back-pointer note:
**Amended in <new-story-id> — see <new-story-id> for the corrected contract.**.
Sources: CONTRIBUTING.md:104-124, agents/epic-reviewer.md:27-33, skills/review-plan/SKILL.md:144-149
Epic Lifecycle Flow
The following diagram illustrates how an Epic document moves through the Roughly ecosystem from review to audit.
The epic-reviewer (using the Opus model) checks for overengineering and technical accuracy before implementation begins. After implementation, audit-epic verifies the results against the original spec.
Sources: skills/review-epic/SKILL.md:47-50, skills/audit-epic/SKILL.md:131-135, agents/epic-reviewer.md:5-10
Implementation Plan Format
Plans are generated automatically by the build and fix pipelines and stored in .roughly/plans/. They translate high-level Epic stories or Issue descriptions into actionable, discrete tasks for subagents.
Plan Components
Every plan contains a file table, a list of tasks (T1, T2, etc.), and a "Blast Radius" assessment.
| Section | Required Data |
|---|---|
| Metadata | Includes Plan-format-version: 1. |
| File Table | Maps files to specific actions (Modify/Create) and Task IDs. |
| Tasks | Includes Title, Files, Action, Details, Verify command, and a UI flag. |
| Verification | Every task must have a Verify: command (e.g., grep, npm test) to confirm success. |
| Status Block | Prepended to the plan after implementation to mark it as "Historical". |
Sources: README.md:195-200, skills/fix/SKILL.md:76-114, CONTRIBUTING.md:144-150
Plan Review Requirements
Plans are subjected to a mandatory review by the review-plan agent, which performs up to 3 iterations to check for:
- Enumeration: Every edit site (line numbers, ranges) must be listed as a separate entry.
- Runtime Signals: Tasks performing detection must name the observable signal source (specific file or command output).
- Grep Hazards: Use of
grep -Fcis flagged if same-line co-location of patterns is plausible;grep -Fo | wc -lis preferred for accurate counts.
Sources: skills/review-plan/SKILL.md:46-55, skills/review-plan/SKILL.md:79-85, skills/review-plan/SKILL.md:120-125
Issue Format
Used primarily by the fix pipeline, Issue formats provide the context needed for the investigator agent to diagnose bugs. Issues can be provided as direct text arguments or as file references.
Recommended Issue Content
When using an issue file (e.g., docs/issues/bug-001.md), the following information is recommended:
- Symptoms: Detailed description of the failure.
- Reproduction Steps: Commands or actions to trigger the bug.
- Known Context: Relevant logs, environment details, or recent changes.
Sources: README.md:179-186, skills/fix/SKILL.md:40-45
Historical Documentation
Roughly maintains the integrity of the project's history by marking implementation artifacts as historical once they are no longer active.
Plan Historical Marking
At the end of a build or fix run, a second commit is created to mark the plan file. The orchestrator prepends a status block formatted exactly as follows:
> **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.
Sources: CONTRIBUTING.md:152-156, skills/shared/stage-8-wrap-up.md:32-40
Conclusion
The Spec and Epic formats in Roughly provide a robust framework for AI-driven development. By enforcing specific conventions—such as testable acceptance criteria in Epics and enumerated edit sites in Plans—Roughly minimizes the risk of context overflow and implementation drift. These documents serve as the source of truth that guides agents through discovery, planning, and verification, ensuring that the software evolved meets the intended architectural standards.