Help Utility
Relevant source files
The following files were used as context for generating this wiki page:
The Help Utility is a core component of the Roughly plugin designed to provide users with an In-CLI overview of commands, pipeline states, and system metadata. It serves as a central hub for navigating the various development clusters—such as implementation, review, and setup—while also surfacing information about installed components and project maturity decisions.
In the context of the Roughly ecosystem, the Help Utility acts as a read-only reporting tool that allows developers to quickly ascertain the status of in-progress plans and the configuration of maturity-based agents like the investigator.
Sources: README.md:124-126, README.md:144
Command Architecture and Clusters
The Help Utility organizes Roughly's functionality into logical clusters, making it easier for users to identify which skill to use based on their current development phase. This structure is mirrored in the /roughly:help output.
Functional Clusters
Roughly commands are grouped into specific workflows:
| Cluster | Commands | Purpose |
|---|---|---|
| Setup & Maintenance | setup, upgrade, help | Bootstrapping, migrating, and system information. |
| Development Pipelines | build, fix | Primary 8-stage implementation and correction loops. |
| Review & Audit | review, review-epic, audit-epic, verify-all | Code quality verification and specification compliance. |
Sources: README.md:129-145, CLAUDE.md:14-25
User-Invocable Surfaces
Not all skills are directly invocable via slash commands. The Help Utility documents the public API surface while omitting internal coordinator-only skills like review-plan.
User-invocable skills include:
/roughly:setup/roughly:upgrade/roughly:help/roughly:build/roughly:fix
Sources: CONTRIBUTING.md:104-113
State and Component Tracking
A primary function of the Help Utility is surfacing the current state of the Roughly environment within a specific project. It derives this information from various runtime files and configurations.
In-Progress Plan Detection
The Help Utility reports on active implementation or fix plans by checking the .roughly/plans/ directory. This provides visibility into the "active build/fix artifact" currently driving the orchestrator.
Sources: README.md:144, CONTRIBUTING.md:195-197
Installed Components
The utility includes an "Installed components" section that reflects the state of project-specific enhancements. This is primarily driven by markers in the .roughly/workflow-upgrades file.
The following diagram illustrates how Roughly determines which components are active:
Logic and Implementation Conventions
The Help Utility adheres to specific project-wide conventions for skill authoring, particularly regarding how logic is dispatched and how information is presented to the user.
Dispatch Logic
For multi-branch case dispatching (such as categorizing command help), Roughly employs a mutually-exclusive case partition. The utility must evaluate conditions in order from top-to-bottom and execute only the first matching case's logic.
Sources: CONTRIBUTING.md:84-93
Pre-flight Safety Checks
Like the primary pipelines, the Help Utility includes a pre-flight migration check. This check prevents the utility from operating on projects with legacy .ruckus/ states or un-migrated plans from pre-v0.1.6 versions.
Technical Summary Table
| Metadata Field | Source Location | Description |
|---|---|---|
| Plugin Version | .claude-plugin/plugin.json | Current version of the Roughly installation. |
| Maturity Decisions | .roughly/workflow-upgrades | Records of yes/no/never decisions for agents and hooks. |
| Project Commands | CLAUDE.md | Build, test, and type-check commands for the current project. |
| Known Pitfalls | .roughly/known-pitfalls.md | Project-specific anti-patterns and conventions. |
Sources: CLAUDE.md:18-24, skills/setup/SKILL.md:472-474, skills/upgrade/SKILL.md:95-98
The Help Utility provides essential visibility into the Roughly system, ensuring that users can manage their development pipelines and maturity upgrades with clear, centralized information. It bridges the gap between the static documentation of the plugin and the dynamic, evolving state of a project's Roughly implementation.