Spec Steward Auto-Reviewer Droid

The Spec Steward Auto-Reviewer Droid, identified in the Sploosh repository as the cubic-dev-ai bot, is a specialized AI agent responsible for maintaining the integrity and consistency of the Sploosh language specification. Because Sploosh is a spec-first project, the Steward ensures that every Pull Request (PR) adheres to the authoritative language rules defined in docs/spec-plans/LANGUAGE_SPEC.md and its associated prompt-sized mirrors.

The droid acts as a mandatory reviewer in the development workflow, validating code changes, documentation updates, and specification amendments. Its primary mission is to prevent "silent behavior changes" where the compiler implementation drifts from the documented language design. Developers are required to address every comment from the Steward or provide a technical justification based on the spec if they believe a comment is invalid.

Sources: AGENTS.md:39-40, CONTRIBUTING.md:4-7, VISION.md:73-75

Core Responsibilities and Workflow

The Spec Steward operates within a strict "Definition of Done" framework. It monitors changes across three primary areas: the authoritative specification, the prompt-sized mirrors, and the Rust compiler bootstrap crates.

PR Validation Pipeline

When a PR is opened, the Steward performs a multi-step validation to ensure the language remains internally consistent. This includes checking that any behavioral change in the compiler is preceded or accompanied by a change in the primary LANGUAGE_SPEC.md.

The diagram shows the iterative validation loop performed by the Steward to ensure all project pillars remain in sync.

Sources: AGENTS.md:54-63, CONTRIBUTING.md:45-53, .factory/droids/sploosh-spec-steward.md

Enforcement of Sacred Rules

The Steward enforces specific repository constraints that are non-negotiable for project maintainers:

• No Direct Commits to Main: All work must pass through branch-protected PRs.
• Spec-First Implementation: Material changes must be documented in LANGUAGE_SPEC.md Appendix D.
• No AI Footers: The droid flags any commits containing "Generated with", "Co-authored-by" AI trailers, or session tokens.
• Mirror Synchronization: Any change to the core spec must be reflected in LANGUAGE_SPEC_PROMPT_CORE.md and LANGUAGE_SPEC_PROMPT_WEB3.md.

Sources: AGENTS.md:31-38, CONTRIBUTING.md:46-51, VISION.md:45-48

Token Budget Monitoring

A unique aspect of the Spec Steward's role is enforcing "Principle 7" of the Sploosh design philosophy: the language core must stay prompt-loadable. The droid utilizes the scripts/check_prompt_budget.py utility to monitor the size of the prompt mirrors using the cl100k_base encoding.

Budget Constraints

Sources: scripts/check_prompt_budget.py:12-16, VISION.md:51-53, README.md:15-18

The Steward will flag a PR as "Failed" if these ceilings are exceeded, requiring the developer to either optimize the documentation or remove an existing feature to make room for a new one.

Sources: scripts/check_prompt_budget.py:27-31, VISION.md:77-78

Architecture and Integration

The Spec Steward is integrated into the Sploosh CI/CD pipeline via GitHub Actions. It interacts with several key crates and scripts to perform its analysis.

The sequence diagram illustrates the droid's interaction with CI scripts and the Rust source code during a review cycle.

Sources: README.md:65-72, scripts/check_prompt_budget.py:47-66, AGENTS.md:40-42

Relevant Components

• Compiler Alignment: The Steward checks that the sploosh-lexer and sploosh-parser crates implement the grammar as defined in the spec.
• NDJSON Diagnostics: The Steward facilitates the generation of diagnostics designed for tool-loop consumption rather than just human reading.
• Change Tracking: It ensures that "Appendix D" changelog entries are added for every material spec change.

Sources: README.md:19-21, AGENTS.md:57, crates/AGENTS.md:7-11

Conclusion

The Spec Steward Auto-Reviewer Droid is the cornerstone of Sploosh's AI-native development model. By strictly enforcing the spec-first rule and maintaining a portable prompt budget, it ensures the language remains perfectly suited for LLM generation. Its presence guarantees that the project's documentation remains the "sole behavioral source of truth," preventing the technical debt common in human-centric language development.

Sources: VISION.md:55-58, README.md:7-12, AGENTS.md:44-46