Maturity Levels
Relevant source files
The following files were used as context for generating this wiki page:
Maturity Levels in Roughly represent a framework for adapting the plugin's behavior, agents, and enforcement mechanisms based on the size and complexity of the target project. This classification is primarily driven by the count of source files, allowing Roughly to scale its development pipelines—such as Build and Fix—from small, rapid prototypes to large, established codebases.
The system ensures that overhead remains low for new projects while providing robust diagnostic and verification tools for mature ones. Maturity detection occurs during the initial bootstrap process and is re-evaluated during pipeline wrap-ups to offer progressive upgrades.
Sources: README.md:213-215, skills/setup/SKILL.md:12-23
Detection and Classification
Roughly classifies project maturity during Step 1 of the /roughly:setup skill. It uses a find command to count relevant source files (e.g., .ts, .py, .go, .rs) while explicitly excluding build artifacts and dependency directories like node_modules, vendor, and dist.
Classification Thresholds
| Level | Source Files | Characteristics & Adaptations |
|---|---|---|
| Greenfield | < 10 | Skips investigator agent; simplifies verify-all (omits test/typecheck if not configured); no Stop hook offered. |
| Scaffolded | 10 - 50 | Standard configuration. All verification checks active if commands provided. doc-writer agent active at wrap-up. |
| Established | 50+ | Offers investigator agent for /roughly:fix. Offers Stop hook if verify-all has 2+ meaningful checks. |
Sources: README.md:217-221, skills/setup/SKILL.md:14-25
Detection Logic Flow
The following diagram illustrates how Roughly determines the maturity level during the setup phase.
The system also detects the specific test framework, formatter, and CI configuration present in the environment to further tailor the setup.
Sources: skills/setup/SKILL.md:14-30
Maturity-Based Features
Maturity levels determine the availability of specific agents and automation hooks.
Investigator Agent
The investigator agent is designed to trace code paths and diagnose bugs during the /roughly:fix pipeline. It is only offered when a project reaches the Established level (50+ files). If accepted, the decision is recorded as investigator-v1-added in .roughly/workflow-upgrades.
Sources: skills/fix/SKILL.md:227-234, README.md:228-230
Stop Hook (stop-hook-v1)
The Stop hook is a UserPromptSubmit hook that runs project type-checks after every Claude turn. It is offered when:
- The project is Established (or has 50+ files during a later wrap-up).
verify-allcontains 2+ meaningful checks.- A valid type-check command is configured in
CLAUDE.md.
Sources: skills/setup/SKILL.md:267-279, skills/fix/SKILL.md:236-242
Verification Enforcement
Projects at the Greenfield level receive a simplified version of verify-all that may skip tests or type-checking if no commands were provided, focusing only on the build command to maintain development speed.
Sources: README.md:219, skills/setup/SKILL.md:22
Lifecycle and Upgrades
Maturity is not static. Roughly performs "Maturity Checks" at the end (Stage 8) of every /roughly:build and /roughly:fix run.
Upgrade Path
When a project crosses a file count threshold (e.g., growing from 40 to 60 files), Roughly detects the change and offers the relevant upgrades (like the Investigator agent). These decisions are tracked in .roughly/workflow-upgrades using versioned IDs to ensure that previously declined offers are only re-prompted if the plugin version or check logic is updated.
Component Tracking
Maturity and installation states are visible via the /roughly:help command, which partitions markers into Maturity-check state and Installed components.
| Marker Type | Example ID | Description |
|---|---|---|
| Active Maturity | investigator-v1, stop-hook-v1 | High-level behavioral toggles. |
| Installed Component | plan-mode-gate-v1 | Specific structural additions like hooks. |
| Retired | test-verify-v1 | Legacy checks no longer offered. |
Sources: skills/help/SKILL.md:58-86
Roughly's maturity level system ensures the project environment evolves alongside the codebase, providing appropriate levels of oversight and assistance as complexity increases.