CI Integration
Relevant source files
The following files were used as context for generating this wiki page:
CI Integration in the Roughly project primarily centers around the automated "dogfooding" of the plugin's own pipelines and the enforcement of structural invariants. The system uses a specialized non-interactive mode triggered by the --ci flag, allowing the gated development pipelines (build and fix) to run within automated environments like GitHub Actions. This integration ensures that every contribution adheres to project standards, such as file length limits and byte-identity checks, without requiring human intervention at every stage gate.
The CI environment utilizes specific scripts, such as scripts/ci-dogfood.sh, to simulate real-world usage scenarios within a clean worktree. This process verifies the stability of the orchestrator and subagent dispatch model, ensuring that the "loud" and "gated" philosophy of the project is maintained even in automated contexts.
Sources: CONTRIBUTING.md:275-300, README.md:120-140
The --ci Flag and Non-Interactive Mode
The --ci flag is the primary mechanism for enabling non-interactive execution of the build and fix pipelines. When detected in the $ARGUMENTS of a skill, it sets an internal CI_MODE=true variable which alters the behavior of human gates and error handling.
CI Mode Behavior Alterations
| Feature | Interactive Behavior | CI Mode Behavior (--ci) |
|---|---|---|
| Human Gates | Pauses for user input (yes/no/abort) | Auto-proceeds with default (yes) |
| Stage 4 Review | Allows human override or revision loop | Runs review-plan; exits non-zero on failure |
| Error Escalation | Prompts user for recovery | Emits structured log and exits non-zero |
| Commit Approval | Requires manual approval of message | Auto-progresses commits without gate |
In CI_MODE, Stage 4 is modified to maintain rigor. For the fix pipeline, the system dispatches the review-plan subagent and exits immediately if a NEEDS REVISION verdict is returned, whereas the build pipeline may attempt a revision loop before exiting.
Sources: skills/fix/SKILL.md:46-55, CONTRIBUTING.md:290-295, CLAUDE.md:75-80
CI Workflow Architecture
The CI integration follows a specific flow to ensure the plugin can safely modify a target project. The ci-dogfood.sh script orchestrates this by setting up a minimal target project and invoking the /roughly:build --ci command.
The diagram shows the lifecycle of a CI "dogfood" run, from initial authentication checks to the automated completion of a build cycle.
Sources: CONTRIBUTING.md:275-285, skills/fix/SKILL.md:48-60
Structural Invariants and Stop Hooks
A critical component of the CI strategy is the verify-all.sh stop hook, which is installed during the /roughly:setup process. This script enforces seven structural invariants after every Claude turn.
Enforced Invariants
- Path Drift: Prevents references to legacy
.ruckus/paths in theagents/directory. - Skill Line Cap: Ensures every
skills/*/SKILL.mdfile remains ≤ 300 lines. - Agent Word Cap: Ensures every
agents/*.mdfile remains ≤ 650 words. - HTML Integrity: Validates the structure of
agents/agent-preamble.md. - Pre-flight Byte-Identity: Ensures hard-abort skills share identical migration check blocks.
- Plan-mode Gate Identity: Ensures the plan-mode-gate hook is identical to its template.
- Pitfalls Threshold: Triggers a reorganization suggestion if
known-pitfalls.mdexceeds 80 lines.
Sources: CONTRIBUTING.md:315-335, skills/setup/SKILL.md:150-180
Automated Wrap-up and Commits
In CI mode, the wrap-up procedure documented in skills/shared/stage-8-wrap-up.md is automated. This includes drafting the commit message based on the pipeline type and marking the plan file as historical.
CI Sequence for Wrap-up
The sequence illustrates how the CI system handles the dual-commit wrap-up process without human intervention.
Sources: skills/shared/stage-8-wrap-up.md:5-25, skills/fix/SKILL.md:215-220
Authentication and Security
The CI integration relies on the ANTHROPIC_API_KEY for executing subagents via Claude Code. In GitHub Actions, this is managed through repository secrets. The smoke test step specifically consumes the secret via step-scoped environment mappings to prevent global exposure. If the key is missing or invalid, the CI script exits with a diagnostic message rather than hanging.
Sources: CONTRIBUTING.md:280-285, CONTRIBUTING.md:305-310
Conclusion
CI Integration in Roughly is designed to replace human oversight with automated strictness. By leveraging the --ci flag, the project ensures that its complex 8-stage pipelines can be validated continuously. The combination of non-interactive execution, structural invariant checks via stop hooks, and automated historical marking of artifacts allows the project to maintain high quality and consistency across its subagent-driven architecture.