Installation & Quick Start
Relevant source files
The following files were used as context for generating this wiki page:
Roughly is a Claude Code plugin designed to implement gated, subagent-per-task development pipelines. It facilitates a structured workflow by dispatching specialized subagents for discovery, planning, implementation, and review, with human confirmation gates required between every stage. This approach prevents context overflow and ensures high-quality code through mandatory plan reviews and two-stage quality checks.
The installation process involves adding the plugin via the Claude Code marketplace, followed by a guided setup skill that tailors the environment to the project's specific maturity level and technical stack. Once installed, users can leverage commands like /roughly:build and /roughly:fix to manage complex feature development and bug fixes.
Sources: README.md:1-10, README.md:82-95
Installation Procedure
Installing Roughly requires Claude Code v1.0+. The primary installation method is via the /plugin command within a Claude Code session.
/plugin marketplace add nickkirkes/roughly
/plugin install roughly@nickkirkes
Sources: README.md:12-16
If the standard installation fails, users can manually clone the repository into the ~/.claude/plugins/roughly/ directory as a fallback.
Sources: README.md:18-20
Migration for Legacy Users
Projects migrating from the legacy ruckus (v0.1.3) plugin must run the upgrade skill to transition their metadata and configurations to the new .roughly/ structure.
Sources: README.md:46-55
Initial Project Setup
After installation, the /roughly:setup command must be run once per project. This skill bootstraps Roughly by detecting the project's "maturity level" and collecting essential technical context.
Maturity Detection Logic
Roughly classifies projects based on the count of source files (excluding node_modules, vendor, .git, etc.). This classification determines which automated agents and hooks are offered to the user.
| Level | File Count | Behavior Adjustments |
|---|---|---|
| Greenfield | < 10 | Skips investigator agent; simplifies verification; omits Stop hook. |
| Scaffolded | 10 - 50 | Standard configuration; full setup applied. |
| Established | 50+ | Offers Investigator agent for /roughly:fix and Stop hooks for type-checking. |
| Sources: skills/setup/SKILL.md:20-33, README.md:179-188 |
Required Context Collection
The setup process blocks completion until six mandatory fields are provided. These fields are used to populate the CLAUDE.md file, which serves as the canonical project context for all Roughly agents.
- Stack: Tech stack details (e.g., TypeScript, Next.js).
- Build command: Command to build the project.
- Type check: Command to run type checking (or "none").
- Test command: Command to run tests (or "none yet").
- Convention: A primary pattern or convention agents must follow.
- Domain: A one-sentence description of the project's purpose.
Sources: skills/setup/SKILL.md:65-87
Configuration Files Created
Upon successful setup, Roughly creates several files in the project root and the .roughly/ directory.
| File Path | Description |
|---|---|
CLAUDE.md | Primary project context including stack, commands, and conventions. |
.roughly/known-pitfalls.md | A log of project-specific issues and patterns to avoid. |
.roughly/workflow-upgrades | Tracks plugin versions and user maturity decisions. |
.claudeignore | Prevents unnecessary files from bloating agent context. |
.claude/settings.json | Configures Claude Code hooks, such as plan-mode gates or formatters. |
| Sources: skills/setup/SKILL.md:112-140, README.md:32-44 |
System Flow: Setup & Execution
The following diagram illustrates the lifecycle of a Roughly project from initial setup through to the start of a development task.
The diagram shows how the setup skill establishes the foundation (files and hooks) necessary for the primary development pipelines (build and fix) to function correctly, specifically highlighting the ADR-009 plan-mode protection.
Sources: skills/setup/SKILL.md:143-150, README.md:26-30, README.md:236-240
Quick Start: Building a Feature
Roughly builds features based on "Epic" files—Markdown specifications typically stored in docs/epics/.
1. Create a Specification
A minimal spec should include a story title and Acceptance Criteria (AC).
# Add Health Endpoint
## Story 1: GET /health
**AC:**
- Returns 200 with `{ "status": "ok" }`
Sources: README.md:65-74
2. Execute the Build Pipeline
Run the build command pointing to the spec file:
/roughly:build docs/epics/add-health-endpoint.md
Roughly then guides the user through the following 8 gates:
- Intake: Confirm the scope of the feature.
- Discover: Review existing patterns and "blast radius" found by the discovery agent.
- Plan: Approve the generated implementation plan (tasks T1, T2, etc.).
- Review Plan: Mandatory subagent verification of the plan against the codebase.
- Implement: Monitor subagents as they implement tasks one-by-one.
- Review: Parallel 3-agent code review (bugs, security, conventions).
- Verify: Automated verification via
verify-all(build/test/typecheck). - Wrap-up: Finalize commit messages and update project documentation.
Sources: README.md:78-80, README.md:236-246
Summary
Roughly provides a robust, gated environment for AI-assisted development. By starting with /roughly:setup, users ensure that specialized agents have the context required to maintain project standards. The transition from a simple Markdown spec to a verified code commit is managed through a sequence of human-in-the-loop gates, ensuring transparency and control throughout the development lifecycle.
Sources: README.md:280-285, skills/setup/SKILL.md:11-16