Bootstrapping & Upgrading
Relevant source files
The following files were used as context for generating this wiki page:
The Roughly project utilizes a dedicated lifecycle management system to initialize and maintain project-specific context. Bootstrapping (via /roughly:setup) initializes the environment by detecting project maturity and collecting essential technical metadata. Upgrading (via /roughly:upgrade) ensures that local project configurations remain synchronized with the latest plugin templates while preserving user-defined customizations.
These processes manage critical files like CLAUDE.md and .roughly/known-pitfalls.md, which serve as the shared context for all subagents in the Roughly pipeline. By centralizing this configuration, Roughly avoids context overflow and ensures agents are project-aware without bloated prompts.
Sources: README.md:14-25, CLAUDE.md:46-51
Project Bootstrapping (/roughly:setup)
The setup skill is the entry point for any new project using Roughly. It follows a multi-step sequence to determine how "established" a project is and what level of automation is appropriate.
Step 1: Maturity Detection
Roughly classifies projects based on the count of source files (excluding node_modules, .git, etc.).
| Level | Source File Count | Description |
|---|---|---|
| Greenfield | < 10 | Simplified setup; skips investigator agent and Stop hooks. |
| Scaffolded | 10 - 50 | Standard setup; all verification checks active. |
| Established | 50+ | Full setup; offers specialized agents like the investigator. |
Sources: skills/setup/SKILL.md:14-38, README.md:172-184
Step 2: Context Collection
The setup process enforces a "Gate" where six required technical fields must be provided before proceeding.
A flowchart showing the sequential logic of the project bootstrapping process.
Sources: skills/setup/SKILL.md:59-105
Required Configuration Fields
The following fields are mandatory for initializing the Roughly environment:
- Stack: Technical stack (e.g., TypeScript, Next.js).
- Build command: Command to build the project.
- Type check: Command for type-checking (or "none").
- Test command: Command to run tests (or "none yet").
- Convention: A single critical pattern or rule agents must follow.
- Domain: A one-sentence description of the project's purpose.
Sources: skills/setup/SKILL.md:82-105
Project Upgrading (/roughly:upgrade)
The upgrade skill synchronizes local project files with current plugin templates. It is designed to be idempotent and safe, never overwriting user data without explicit permission.
Migration Logic
Roughly has undergone several structural renames (e.g., from ruckus to roughly). The upgrade skill handles legacy path migrations automatically.
A flowchart illustrating the migration and template synchronization logic within the upgrade skill.
Sources: skills/upgrade/SKILL.md:10-85
File Classification
During an upgrade, files are categorized into four states to determine the necessary action:
- New: Exists in the plugin but not in the project (Offer to install).
- Changed: Plugin source has structural updates (Show diff and merge).
- Unchanged: Local matches plugin structure.
- Local-only: Project-specific files (Leave alone).
Sources: skills/upgrade/SKILL.md:162-171
Preservation of Customizations
The upgrade system distinguishes between Structural changes (new sections, updated ignore patterns) and Project customizations (filled placeholders, custom conventions). Only structural changes are merged; project-specific values are always preserved.
Sources: skills/upgrade/SKILL.md:183-195
Core Project Artifacts
Both bootstrapping and upgrading manage a standard set of files that define the Roughly environment.
| File Path | Managed By | Purpose |
|---|---|---|
CLAUDE.md | Setup/Upgrade | Canonical project context read by all agents. |
.roughly/known-pitfalls.md | Setup/Upgrade | Catalog of project-specific gotchas discovered during builds. |
.roughly/workflow-upgrades | Setup/Upgrade | Internal ledger tracking versioning and maturity decisions. |
.claudeignore | Setup/Upgrade | Excludes heavy directories from agent context. |
.claude/settings.json | Setup/Upgrade | Registers Claude Code hooks (e.g., plan-mode-gate). |
Sources: README.md:27-38, CLAUDE.md:8-20
Hooks and Security Gates
A critical component of bootstrapping is the installation of Claude Code hooks.
Plan-Mode Gate
Installed at .claude/hooks/plan-mode-gate.sh, this hook prevents Roughly pipelines from running while Claude Code is in "Plan Mode." This is a safety mechanism to ensure pipeline gates are handled correctly within the standard chat interface.
Sources: skills/setup/SKILL.md:139-145, skills/fix/SKILL.md:12-16
Stop Hook (verify-all.sh)
For "Established" projects with type-checking configured, setup offers to install a Stop hook. This hook executes the project's type-check after every Claude turn. It is intended to be silent on success and only surface errors when code drift occurs.
Sources: skills/setup/SKILL.md:173-247, CONTRIBUTING.md:238-250
Conclusion
The Bootstrapping and Upgrading systems ensure that Roughly remains a "loud" and "gated" environment. By enforcing strict context collection during setup and providing a safe migration path during upgrades, the project maintains high technical accuracy across its distributed subagent architecture. These processes transform a standard repository into a Roughly-compatible project capable of driving automated feature and fix pipelines.