Migration from Ruckus
Relevant source files
The following files were used as context for generating this wiki page:
Migration from Ruckus refers to the structural transition of the project from its legacy name "Ruckus" (v0.1.3) to its current identity "Roughly" (v0.1.4+). This process involves renaming directories, updating file paths, and rewriting internal identifiers within project configuration and documentation files.
The migration is a "hard cut" with no backwards-compatibility shims or aliases. It is primarily managed by the /roughly:upgrade command, which automates the transfer of legacy state from the .ruckus/ directory to the new .roughly/ directory while preserving user customizations.
Sources: README.md:43-46, README.md:58-60, skills/upgrade/SKILL.md:21-23
Migration Detection and Pre-flight Checks
The system employs "pre-flight" checks to detect legacy states and prevent pipeline execution until the project is migrated. These checks are embedded in multiple skills including build, fix, review, and setup.
Detection Logic
The migration check triggers if any of the following are detected:
- Existence of the
.ruckus/directory. - Existence of legacy files:
.ruckus/known-pitfalls.mdor.ruckus/workflow-upgrades. - Existence of an incomplete migration marker:
.ruckus/.migration-in-progress. - Presence of legacy plans in
docs/plans/alongside a new.roughly/installation.
Sources: skills/setup/SKILL.md:41-45, tests/fixtures/canonical-preflight-block.txt:1-5
Pre-flight Workflow
The following diagram illustrates how the system handles the detection of legacy Ruckus state during standard operations:
A .ruckus/ directory containing only user-extras (post-upgrade "leave" state) is permitted to allow users to handle non-standard files manually.
Sources: tests/fixtures/canonical-preflight-block.txt:5-7, skills/upgrade/SKILL.md:104-106
Migration Execution Process
The migration is executed in a series of idempotent steps within the /roughly:upgrade skill. It uses a marker file to track progress and allow for resumption in case of failure.
Step-by-Step Migration Logic
| Step | Action | Description |
|---|---|---|
| 1 | Method Choice | Detects git status; uses git mv for repositories and mv for non-git projects. |
| 2 | Conflict Check | Checks if both .ruckus/ and .roughly/ exist; prompts for resolution if no marker is found. |
| 3 | Marker Creation | Writes .ruckus/.migration-in-progress with date and version to track active migration. |
| 4 | Legacy Cleanup | Handles cases where both docs/claude/ (v0.1.2) and .ruckus/ (v0.1.3) exist. |
| 5 | Idempotent Move | Moves files from .ruckus/ to .roughly/. Existing destinations are preserved in resume cases. |
| 6 | Content Rewrites | Updates ruckus-version to roughly-version and replaces /ruckus:* command references in boilerplate. |
| 7 | Path Updates | Replaces substring references of .ruckus/ paths in the root CLAUDE.md. |
| 8 | Extra Files | Interactively prompts to move non-standard files remaining in .ruckus/. |
| 9 | Cleanup | Removes markers and deletes .ruckus/ if empty. |
Sources: skills/upgrade/SKILL.md:25-108
State Transitions and Resumption
The migration uses a state-machine approach with a .migration-in-progress marker. If the process is interrupted, the marker allows the system to resume from the point of failure.
Key Structural Changes
The migration enforces a specific mapping of directories and internal identifiers. This consolidation ensures all runtime state is housed under a single root.
File and Directory Mapping
| Legacy Path (Ruckus) | New Path (Roughly) |
|---|---|
.ruckus/ | .roughly/ |
.ruckus/known-pitfalls.md | .roughly/known-pitfalls.md |
.ruckus/workflow-upgrades | .roughly/workflow-upgrades |
docs/claude/ | .roughly/ |
docs/plans/ | .roughly/plans/ |
Sources: README.md:50-55, skills/upgrade/SKILL.md:21-23, CONTRIBUTING.md:430-432
Content Substitutions
Internal references within files are updated to reflect the new namespace:
- Version Identifiers:
ruckus-versionbecomesroughly-version. - Command Boilerplate:
/ruckus:buildand/ruckus:fixare replaced with/roughly:buildand/roughly:fixinknown-pitfalls.md. - CLAUDE.md References: Path substrings like
.ruckus/known-pitfalls.mdare updated to.roughly/known-pitfalls.md.
Sources: skills/upgrade/SKILL.md:82-96
Summary
The Migration from Ruckus is a critical one-time operation for legacy projects to align with the project's v0.1.4+ naming and directory structure. By centralizing runtime state in .roughly/ and providing an idempotent, marker-based upgrade path, the system ensures that project-specific knowledge (pitfalls, version history) is preserved across the rename. Completion of this migration is a prerequisite for using any Roughly-namespaced pipeline skills.
Sources: README.md:58-60, skills/upgrade/SKILL.md:25-28