Hierarchical Agent Guides
Relevant source files
The following files were used as context for generating this wiki page:
Hierarchical Agent Guides in the Sploosh project serve as the primary documentation and instruction set for AI coding agents and human developers. Because Sploosh is an AI-native language designed to be written accurately by LLMs on the first try, these guides provide the necessary context, rules, and local constraints required for effective contribution.
The hierarchy follows a "nearest-wins" principle, where a root-level AGENTS.md provides universal conventions, while sub-folders contain their own AGENTS.md files to provide context specific to that sub-tree (e.g., compiler crates vs. language specifications). This structure ensures that agents stay within their technical boundaries and adhere to the project's Spec-First Rule.
Sources: AGENTS.md:1-10, CONTRIBUTING.md:12-16, VISION.md:7-13
Architecture of Information
The project documentation is organized to support a specialized development workflow where the specification is the ultimate authority.
Nearest-Wins Hierarchy
Agents are instructed to read the root AGENTS.md first, followed by the specific AGENTS.md file located in the subdirectory they are modifying. This allows for granular instructions that do not clutter the universal project rules.
The diagram shows how universal rules flow into specialized contexts, where the local guide overrides or supplements the root.
Sources: AGENTS.md:3-5, AGENTS.md:76-88
JIT Index and Scopes
The guides categorize project areas to help agents find the correct authority for their task.
| Topic | Directory | Primary Document |
|---|---|---|
| Compiler Crates | crates/ | crates/AGENTS.md |
| Language Spec | docs/spec-plans/ | LANGUAGE_SPEC.md |
| Reference Docs | docs/reference/ | docs/reference/AGENTS.md |
| Standard Library | docs/stdlib/ | docs/stdlib/AGENTS.md |
| Tooling | docs/tooling/ | docs/tooling/AGENTS.md |
Sources: AGENTS.md:76-88, crates/AGENTS.md:10-15
Spec-First Development
The most critical rule enforced by the Agent Guides is that Sploosh is "spec-first." The documentation is the language. If the compiler implementation and the specification disagree, the compiler is considered buggy unless a spec amendment is landed first.
The Development Loop
This loop ensures that the language core remains prompt-loadable and that mirrors never drift from the authoritative spec.
Sources: AGENTS.md:52-54, CONTRIBUTING.md:43-46, VISION.md:85-90
Mirror Syncing Requirements
Agents must keep multiple mirrors in sync to ensure the language remains accessible to LLMs with different context window constraints.
- LANGUAGE_SPEC_PROMPT_CORE.md: Must remain ≤ 5,600 tokens.
- LANGUAGE_SPEC_PROMPT_WEB3.md: Must remain ≤ 1,500 tokens.
- Reference Docs: Grammar, keywords, and operator precedence mirrors.
Sources: AGENTS.md:56-67, CONTRIBUTING.md:50-54
Universal Conventions for Agents
The guides define strict rules for how agents interact with the repository, specifically regarding Git hygiene and code style.
Git and PR Rules
- No Direct Commits:
mainis branch-protected. - Branch Naming: Must use prefixes like
spec/,docs/,feature/, orfix/. - No AI Footers: The maintainers strictly prohibit "Generated by AI" footers,
Co-Authored-Bytrailers, or Claude session lines in commits or PR bodies. - Rebase over Merge: Branches must be kept up to date via rebase to maintain a clean history.
Sources: AGENTS.md:38-49, CONTRIBUTING.md:31-40
Wording and Documentation Style
- Tone: Terse, declarative, and present tense.
- Clarity: "One canonical way" to express every operation to reduce LLM ambiguity.
- Syntax: Keywords and operators must be drawn from the top 12 most-trained languages.
Sources: AGENTS.md:32-36, VISION.md:56-61, README.md:12-15
Compiler-Specific Guidance
For agents working within the crates/ directory, the crates/AGENTS.md file provides technical constraints for the Rust-based bootstrap.
Component Map
| Crate | Responsibility |
|---|---|
sploosh-ast | Shared source spans and Abstract Syntax Tree nodes. |
sploosh-lexer | UTF-8 lexer for tokens defined in §2 and §16.1 of the spec. |
sploosh-parser | Recursive-descent parser targeting the §16 EBNF grammar. |
Sources: crates/AGENTS.md:10-15, README.md:100-105
Implementation Constraints
Agents working on the compiler must adhere to specific implementation rules:
- Preserve Spans: Public syntax nodes and diagnostics must maintain source spans.
- Contextual Keywords: The lexer classifies reserved keywords, while the parser handles contextual spellings (like
send,mut, orwhere). - Dependency-Light: Crates must remain small and avoid unnecessary dependencies during the bootstrap phase.
- Fixture Usage: New grammar shapes must be accompanied by
.spfixture files in the corpus.
Sources: crates/AGENTS.md:46-51, crates/AGENTS.md:53-56
Summary
Hierarchical Agent Guides provide the structural backbone for Sploosh's development, ensuring that both human and AI contributors follow a spec-first methodology. By utilizing a nested hierarchy of AGENTS.md files, the project maintains strict control over language design, token budgets for LLM prompts, and compiler implementation standards, ultimately driving toward the goal of a language that AI agents can write correctly on the first attempt.