diff --git a/CLAUDE.md b/CLAUDE.md index ab4cec1..502016b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,15 +1,28 @@ -## Invent your own programming language. +## AILang — a language for LLM authors -- The language may take any form you want. The language is for LLMs like you. Only you should produce it and only you need to understand it. -- Any conceivable concept is allowed. Pick what is best suited for LLMs. -- The language must, in the end, be linkable to LLVM. Performance is extremely important. -- Consider the typical strengths and weaknesses of LLMs. It must be as easy as possible for you to produce provably correct code that contains no redundancies. -- Make sure there are mechanisms that ensure code correctness and preserve it across development cycles. -- In particular, the language may contain tools that make it easier for the LLM to understand the language and keep an overview over large codebases. -- The language does not have to be self-explanatory. It does not even have to be text. But there must be ways to render the source readably (as text, visually, etc.). -- Do not forget that debugging will also be done by LLMs. +AILang's only author is an LLM, not a human. It is designed for: -- Organise yourself. Design your own agents when needed. Use git. Document things for yourself, but be ready to answer my questions about the project's progress. +- **Machine readability over human readability.** Source is structured + data (`.ail.json`), not text. +- **Local reasoning.** Every definition carries its full type and + effect set, so a signature can be trusted without reading the body. +- **Provability.** Pure core, explicit algebraic effects. +- **Robustness against hallucinations.** Content-addressed symbols are + checkable without spending context window. + +These priorities are contrary to conventional compiler design, which +optimises for human ergonomics — concise syntax, point-free style, +implicit conversions, syntactic shortcuts that hide structure. AILang +keeps none of those. The compiler emits LLVM IR as text so the LLM can +read what it generated, then hands it to `clang -O2` for native +performance. + +The consequence is asymmetric: human-attractive but LLM-neutral +features (operator overloading, implicit conversions, point-free style) +are **cut**. Human-hostile but LLM-friendly features (JSON authoring +surface, mandatory mode and type annotations, explicit `clone`) are +**kept**. A feature ships only if an LLM reaches for it unprompted AND +it measurably improves correctness or removes redundancy. ## Code layout @@ -25,22 +38,15 @@ | `bench/` | Regression harnesses (`check.py`, `compile_check.py`, `cross_lang.py`) and the throughput-and-latency runner (`run.sh`); `bench/reference/` holds the hand-C corpus for cross-language ratios | | `examples/` | AILang fixtures used by tests and benches | | `docs/` | Canonical specs and decisions log — `docs/DESIGN.md`, `docs/JOURNAL.md`, `docs/specs/` (per-milestone design specs), `docs/plans/` (per-iteration plans), `PROSE_ROUNDTRIP.md` | -| `skills/` | Project-local skill definitions: `brainstorm`, `plan`, `implement`, `audit`, `debug`. Each skill bundles its dispatched agents under `skills//agents/`. `skills/README.md` is the index (skill table + agent roster + discovery). | +| `skills/` | Project-local skill definitions and their agents. See `skills/README.md` for the skill table, agent roster, and discovery layout. | ## Skill system -Day-to-day discipline lives under `skills//SKILL.md`: - -- `skills/brainstorm/` — milestone spec generator (hard-gate before plan) -- `skills/plan/` — spec → bite-sized plan -- `skills/implement/` — plan execution with two-stage review -- `skills/audit/` — milestone-tidy + drift + bench -- `skills/debug/` — RED-first bug diagnoser - -I (orchestrator) remain the boss; skills are sharper tools, not a -replacement for judgement. Skipping rules are codified in each -`SKILL.md` — ad-hoc skipping is forbidden by design. Specs go to -`docs/specs/.md`, plans to `docs/plans/.md`. +Day-to-day discipline lives under `skills//SKILL.md`; see +`skills/README.md` for the trigger table and skipping rules. Skills +are sharper tools, not a replacement for orchestrator judgement. +Specs go to `docs/specs/.md`, plans to +`docs/plans/.md`. ## My role: orchestrator @@ -177,45 +183,21 @@ exception, not the rule. ## Bug fixes — TDD, always -Bug fixes are RED-first, autonomous, no orchestrator gate. The -trigger and handoff are in `skills/debug/SKILL.md`; the full -discipline (Iron Law, four phases, Phase 4.5 architecture trigger, -common rationalisations) lives in -`skills/debug/agents/ailang-debugger.md` — that is the file the -dispatched subagent reads. Headline: - -1. **RED first** — write a failing test that pins down the symptom, - commit it as `test: red for ` BEFORE any fix. -2. **GREEN second** — minimal change to turn the test green; no - surrounding cleanup. -3. **Keep the test** — never deleted; future iterations exercise it. - -A bug fix without a regression test is a code change, not a fix. +Bug fixes are RED-first, autonomous, no orchestrator gate. See +`skills/debug/SKILL.md` (trigger + handoff) and +`skills/debug/agents/ailang-debugger.md` (Iron Law, four phases, +Phase 4.5 architecture trigger). ## Milestone cycle -Work clusters into **milestones** (formerly "families", e.g. 18a–f -delivered the RC + uniqueness memory model as one milestone). Each -milestone runs through the skill pipeline: +Work clusters into **milestones**, each subdivided into +**iterations**. Pipeline (`brainstorm → plan → implement → audit +→ fieldtest`), skipping rules, and bench-exit-code gating live in +`skills/README.md` and the per-skill `SKILL.md` files. -``` -brainstorm → plan → implement → audit -``` - -Inside a milestone, work proceeds as **iterations** (formerly -"iters"). Each iteration goes through `plan` then `implement` and -adds a JOURNAL entry. At milestone close, `audit` runs mandatorily -— architect drift review against `docs/DESIGN.md` plus the three -regression scripts (`bench/check.py`, `bench/compile_check.py`, -`bench/cross_lang.py`). Detailed discipline: - -- Mandatory tidy at milestone close (and how to defer it): - `skills/audit/SKILL.md`. -- Performance-regression gating with exit codes 0/1/2: - `skills/audit/SKILL.md`. -- Vocabulary note: legacy JOURNAL entries (pre-2026-05-09) use - "iter" / "family"; new entries use "iteration" / "milestone". - Existing entries are not retroactively renamed. +Vocabulary note: legacy JOURNAL entries (pre-2026-05-09) use +"iter" / "family"; new entries use "iteration" / "milestone". +Existing entries are not retroactively renamed. ## Roles of `docs/JOURNAL.md`, `docs/DESIGN.md`, `docs/specs/`, `docs/plans/`