Workflow Upgrades & State
Relevant source files
The following files were used as context for generating this wiki page:
Roughly manages its internal state and evolution through a decentralized architecture that resides within the user's project. The system tracks project maturity, handles version-to-version migrations, and maintains historical records of implementation plans. By centralizing state in the .roughly/ directory, the plugin ensures that its subagents remain project-aware and that the development pipeline remains robust as the codebase grows.
The core of this system is the workflow-upgrades file, which acts as a registry for plugin versions and "maturity check" decisions. This mechanism allows the plugin to offer new capabilities (like the investigator agent or post-turn Stop hooks) only when the project reaches specific technical thresholds.
Sources: README.md:16-24, CLAUDE.md:16-17, skills/setup/SKILL.md:417-428
State Storage & Structure
Roughly consolidates all runtime state and configuration under a single root directory at the project base. This structure is designed to be lean, keeping irrelevant context out of agent processing while providing necessary metadata for the development pipeline.
The .roughly/ Directory
This directory serves as the primary data store for the plugin's local state.
| Path | Purpose |
|---|---|
.roughly/workflow-upgrades | Tracks the last reviewed plugin version and decisions on optional maturity features. |
.roughly/known-pitfalls.md | A living document of anti-patterns and project-specific gotchas discovered during builds. |
.roughly/plans/ | A directory containing historical implementation plans (e.g., build-<name>-plan.md). |
Sources: README.md:20-24, CLAUDE.md:16-17, CONTRIBUTING.md:154-159
Plan Lifecycle & Historical Marking
Implementation plans are active build/fix artifacts that transition to a "Historical" state once a pipeline completes. This is enforced during the WRAP-UP stage (Stage 8) of the build and fix pipelines.
- Implementation Commit: The code changes are committed first.
- Historical Marking: The orchestrator reads the plan file, generates a status block containing the implementation commit SHA and current date, and prepends it to the plan file.
- Reference-Only Signal: This marker informs downstream tools (like cubic) that the plan is no longer an active specification.
Diagram 1: The process of transitioning an active implementation plan to a historical state.
Sources: skills/shared/stage-8-wrap-up.md:16-33, CONTRIBUTING.md:164-180
Maturity Checks & Decision Tracking
Roughly uses "Maturity Checks" to evolve its features based on the size and complexity of the project. Project maturity is detected during /roughly:setup by counting source files.
Maturity Thresholds
The plugin classifies projects into three levels:
- Greenfield (<10 files): Simplified verification; no investigator agent or Stop hook.
- Scaffolded (10-50 files): Standard configuration; all verification checks active.
- Established (50+ files): Full setup including investigator agent and post-turn Stop hooks.
Sources: skills/setup/SKILL.md:18-30, README.md:181-190
Versioned Decisions
Decisions to enable or decline features (like the investigator-v1 or stop-hook-v1) are stored in .roughly/workflow-upgrades. These IDs are versioned; if the plugin updates a feature, the ID version bumps (e.g., to -v2), and the user is re-prompted even if they previously declined the older version.
| Decision Type | Logic |
|---|---|
| yes | Applies the feature and records [id]-added YYYY-MM-DD. |
| not yet | No record; feature is re-offered during the next /roughly:build or /roughly:fix run. |
| never | Records [id]-declined YYYY-MM-DD and suppresses future prompts for that version. |
Sources: skills/fix/SKILL.md:231-240, README.md:196-205, skills/setup/SKILL.md:465-475
Migration & Upgrade Pipelines
The /roughly:upgrade skill is responsible for moving legacy state to the modern structure and keeping installed templates in sync with the plugin's source code.
Legacy State Detection
The system specifically looks for state from previous versions:
- v0.1.2:
docs/claude/(Migrated to.roughly/) - v0.1.3 (ruckus):
.ruckus/(Migrated to.roughly/) - v0.1.5:
docs/plans/(Migrated to.roughly/plans/)
Sources: skills/upgrade/SKILL.md:13-35, skills/upgrade/SKILL.md:105-115, README.md:52-64
Upgrade Flow
The upgrade process follows a classification and merge strategy to ensure project-specific customizations are never lost.
Diagram 2: The sequence of events during a plugin upgrade to synchronize local files with new templates.
Sources: skills/upgrade/SKILL.md:133-146, skills/upgrade/SKILL.md:175-188, skills/upgrade/SKILL.md:214-220
Transactional Hook Installation
During setup or upgrades, installing hooks (like the Stop hook for type-checking) is treated as a transactional operation to prevent corrupting settings.json. The process uses a staging file (.verify-all.sh.new) and snapshots the existing configuration before using jq to apply changes. If any step fails, the system rolls back to the snapshot.
Sources: skills/setup/SKILL.md:255-275, skills/setup/SKILL.md:315-330
State Maintenance Summary
The "Workflow Upgrades & State" system ensures the long-term health of a project's Roughly installation. By utilizing a central .roughly/ directory and a versioned decision log, the plugin can provide context-aware automation that matures alongside the codebase. This architectural approach prevents the accumulation of "stale prose" in plan files and ensures that architectural decisions and known pitfalls are always accessible to the plugin's subagents.
Sources: CONTRIBUTING.md:164-168, README.md:15-19, CLAUDE.md:105-110