Spec Amendment Process
Relevant source files
The following files were used as context for generating this wiki page:
Sploosh is a spec-first programming language, meaning the documentation serves as the authoritative source of truth for the language's behavior. The Spec Amendment Process ensures that every behavioral change in the language is documented in the core specification before, or simultaneously with, implementation in the compiler. This prevents silent behavior changes and ensures that the compiler bootstrap remains aligned with the language design goals of being AI-native and safety-first.
The process is governed by a strict "Definition of Done" that requires updates to the primary LANGUAGE_SPEC.md, its prompt-sized mirrors, and an entry in the changelog. This methodology ensures that AI coding agents, which rely on prompt-sized references, always have access to the latest correct language rules.
Sources: CONTRIBUTING.md:4-8, AGENTS.md:58-61, VISION.md:89-93
Proposal and Design Phase
Before a large design change is implemented, contributors must open a spec change issue using the prescribed template. This phase focuses on identifying the specific sections of the LANGUAGE_SPEC.md that are affected and providing a clear rationale for the change.
The Spec Change Issue
The issue template requires a detailed summary of the proposed change, the motivation behind it, and a list of specific spec sections (e.g., §4.4a) that will be modified.
This diagram represents the initial stage of proposing a language change before any code or documentation is modified.
Sources: .github/ISSUE_TEMPLATE/spec_change.md, CONTRIBUTING.md:14-20
Implementation and Synchronization
Once a proposal is accepted, the implementation must follow the "Universal Conventions" of the project. A Pull Request (PR) must contain both the documentation updates and the corresponding compiler changes.
The Sacred Git Rules
- No Direct Commits: Work must be done in a topic branch (e.g.,
spec/<topic>). - Atomic PRs: Behavioral changes to
LANGUAGE_SPEC.mdmust land in the same PR as compiler or mirror-doc changes. - Syncing Mirrors: Updates to the core spec require immediate updates to all prompt-sized mirrors to prevent "drift."
Sources: AGENTS.md:33-40, CONTRIBUTING.md:65-67
Required Documentation Mirrors
When the authoritative spec is changed, the following mirrors must be updated:
| Mirror Type | Path | Token Ceiling |
|---|---|---|
| Core Prompt | docs/spec-plans/LANGUAGE_SPEC_PROMPT_CORE.md | 5,600 tokens |
| Web3 Prompt | docs/spec-plans/LANGUAGE_SPEC_PROMPT_WEB3.md | 1,500 tokens |
| Reference | docs/reference/ | N/A |
| Stdlib | docs/stdlib/ | N/A |
Sources: AGENTS.md:64-75, CONTRIBUTING.md:71-74
Automated Validation (CI)
The Spec Amendment Process includes automated enforcement of "Principle 7" from the project vision: the language must fit in a system prompt. The project uses a Python utility to verify that the prompt-sized mirrors do not exceed their token budgets using the cl100k_base encoding.
This diagram illustrates the CI-enforced check that prevents the language specification from growing beyond the capacity of an LLM system prompt.
Sources: scripts/check_prompt_budget.py:7-15, VISION.md:65-71
Definition of Done (DoD)
A spec amendment is only considered complete when it satisfies the following checklist:
- Authoritative Update:
LANGUAGE_SPEC.mdreflects the new behavior. - Mirror Parity: All prompt-sized mirrors are synced and under budget.
- Changelog: An entry is added to Appendix D of the spec for material changes.
- Compiler Alignment: If compiler crates exist for the feature, they must match the spec; otherwise, parser behavior is updated.
- Review:
cubic-dev-aibot comments are addressed or refuted based on spec logic.
Sources: AGENTS.md:92-101, CONTRIBUTING.md:52-61, crates/AGENTS.md:6-10
Summary
The Spec Amendment Process is the cornerstone of Sploosh's "Documentation is the Language" philosophy. By requiring that documentation changes lead or accompany all code changes, the project maintains a high degree of technical accuracy and LLM-compatibility. This process ensures that the language remains a stable target for AI coding agents while allowing for rigorous systems-grade evolution.
Sources: VISION.md:73-80, CONTRIBUTING.md:4-8