# Compiling Intent - further reading

Companion to the keynote. The eight tools mentioned on slide 5, plus the
research and primary sources behind the demos.

## The eight spec-first tools (slide 5)

| Tool | What it is | Where to start |
|------|-----------|----------------|
| **GitHub Spec Kit** | A spec-driven scaffolding tool from GitHub for use with Copilot. | https://github.com/github/spec-kit |
| **AWS Kiro** | An IDE from AWS built around the spec → plan → tasks → build loop. | https://kiro.dev |
| **OpenSpec** | Open-source spec format and toolchain, vendor-neutral. | https://github.com/openspec |
| **BMAD-METHOD** | "Breakthrough Method for Agile AI-Driven Development." | https://github.com/bmadcode/BMAD-METHOD |
| **Claude Code** | Anthropic's coding agent; honours `SPEC.md` and `CLAUDE.md` files in repo. | https://docs.claude.com/en/docs/claude-code |
| **Cursor rules** | `.cursor/rules` files act as a per-repo spec the editor enforces. | https://docs.cursor.com |
| **Tessl** | Commercial spec-first development platform. | https://www.tessl.io |
| **Antigravity** | Google's agent-native development environment. | https://antigravity.google |

## Demo 1 - Symphony

- **Repo:** https://github.com/releasedgroup/symphony
- **Licence:** MIT
- **Stack:** .NET 9, cross-platform; runs against any OpenAI-compatible
  model via Codex CLI.
- **Key files in any Symphony repo:**
  - `SPEC.md` - the source of truth (see the example bundled with this page)
  - `WORKFLOW.md` - engine configuration and the prompt template
  - `.work/issue-{N}/` - the isolated, path-contained workspace per issue

## Demo 2 - Microsoft BASIC for the 6502

- **Original source:** Bill Gates & Paul Allen, 1976. The hand-written
  `m6502.asm` listing has been public for years and is widely mirrored on
  GitHub. Search for `microsoft basic 6502 asm`.
- **Why it works as a demo:** the implementation is small (~7 KB), the
  semantics are well understood, and a cycle-accurate 6502 emulator
  provides a ground-truth oracle to verify any regenerated implementation
  against.
- **The recovered spec:** a single short Markdown file describing operator
  precedence, the numeric model (40-bit float in the original), the error
  taxonomy and the I/O surface. Slide 14 shows an excerpt; the full file is
  about 4 pages.
- **The one-line edit (slide 17):**

  ```diff
  - The AST is walked and evaluated directly.        # interpreter
  + The AST is lowered to .NET IL and JIT-compiled
  +   to a managed assembly before execution.        # compiler
  ```

  Two lines added, one removed. No other human edits. The agent regenerated
  the parser, the IL emitter, the JIT bridge and the test harness.

## The four habits (slide 20)

1. **Write testable specs.** If a line in the spec cannot become an
   automated check, it is decoration. Delete it or sharpen it. "Payments
   should be reliable" is a wish. "A retried `POST /payments` with the same
   idempotency key settles exactly once; 50 concurrent retries produce one
   ledger row" is testable.
2. **Keep one living spec, in version control.** Reviewed like code. The
   only door change comes through. The failure mode is: the spec is in
   Confluence, the truth is in the code, and the real answer is in
   someone's head.
3. **Humans own decisions, agents own mechanics.** Architecture,
   trade-offs and "what done means" are still yours. Scaffolding, wiring,
   tests and regeneration belong to the agent.
4. **Treat code as a build output.** If you are afraid to regenerate a
   file, that fear is a metric. It means intent is hiding inside the code
   that should be in the spec. Move it up.

## Where this still bites (slide 22)

- **Thin specs still fail.** Garbage in, garbage out. The bottleneck moves
  from typing speed to clarity of thought. That is a feature, but it's a
  feature you have to be willing to live with.
- **Non-determinism.** Two regenerations differ. Pin model versions, lock
  the test suite, treat the build as reproducible rather than magic.
- **Specs rot too.** A spec can drift from reality just like a comment.
  It needs review and pruning like any code artifact.
- **Review still matters.** The agent is fast and confident, including
  when wrong. Human review is a feature, not friction.
- **Hot paths need hands.** Performance-critical or exotic code (custom
  allocators, lock-free data structures, hardware-specific kernels) still
  wants a human. Know which 5% of your codebase to keep hand-written.

## The bundled artifacts on this page

- `Compiling-Intent-Keynote.pptx` - the full 18-minute keynote deck.
- `SPEC-payments-example.md` - the example specification Demo 1 was
  built from, including the mid-build dual-approval change.
- `WORKFLOW-example.md` - the `WORKFLOW.md` Symphony reads to configure
  itself for a repo.
- `Compiling-Intent-Further-Reading.md` - this file.

- Nick Beaugeard, Released