RUNE is a specification pattern that acts as a contract between what you want and what AI generates. It works in two formats: YAML files or Markdown sections. It works with any programming language.
Upload skills/rune-writer/SKILL.md to your AI tool. This teaches the AI the RUNE pattern.
| Tool | How to load |
|---|---|
| Claude Code | Copy to .claude/skills/ |
| Claude Projects | Upload to Project Knowledge |
| Cursor | Copy to .cursorrules |
| Aider | aider --read skills/rune-writer/SKILL.md |
| Any tool | Paste content into conversation |
For detailed setup per tool, see Using Skills with AI Tools.
Tell the AI:
“I need a function that greets someone by name. Formal mode says ‘Good day, Name.’ Informal mode says ‘Hey Name!’ Empty name should raise an error. Generate a RUNE spec.”
The AI generates:
### greet
**SIGNATURE:** `def greet(name: str, formal: bool = False) -> str`
**INTENT:** Generates a greeting message. Formal or informal based on parameter.
**BEHAVIOR:**
- WHEN name is empty THEN raise error "Name cannot be empty"
- WHEN formal is True THEN return "Good day, {name}."
- OTHERWISE return "Hey {name}!"
**TESTS:**
- `greet('Alice') == 'Hey Alice!'`
- `greet('Bob', formal=True) == 'Good day, Bob.'`
- `greet('') raises error`
**EDGE_CASES:**
- Name with spaces: works correctly
- Name with special characters: works correctly
Tell the AI:
“Implement the greet spec in Python”
Or in any other language:
“Implement the greet spec in Go”
The AI generates code + tests that follow the spec exactly.
As a Markdown section (embed in AGENTS.md or any doc):
### greet
**SIGNATURE:** `def greet(name: str, formal: bool = False) -> str`
**BEHAVIOR:**
- WHEN name is empty THEN raise error "Name cannot be empty"
- WHEN formal is True THEN return "Good day, {name}."
- OTHERWISE return "Hey {name}!"
**TESTS:**
- `greet('Alice') == 'Hey Alice!'`
As a .rune file (standalone YAML):
---
meta:
name: greet
language: python
---
RUNE: greet
SIGNATURE: |
def greet(name: str, formal: bool = False) -> str
BEHAVIOR:
- WHEN name is empty THEN raise error "Name cannot be empty"
- WHEN formal is True THEN return "Good day, {name}."
- OTHERWISE return "Hey {name}!"
TESTS:
- "greet('Alice') == 'Hey Alice!'"
Both produce code with the same behavior. Use whichever fits your workflow.
Runestone provides 7 skills. The writer is enough to start. Add others as your workflow grows.
Requirements ──▶ Writer ──▶ Validator ──▶ Refiner ──▶ Writer (implement) + Test Generator
│
▼
Diff (audit over time)
| Skill | File | What it does |
|---|---|---|
| Writer | rune-writer/SKILL.md |
Create specs and implement code from them |
| Validator | rune-validator/SKILL.md |
Check if a spec is complete and well-formed |
| Refiner | rune-refiner/SKILL.md |
Suggest missing tests, edge cases, and clarifications |
| Test Generator | rune-test-generator/SKILL.md |
Generate runnable test files from a spec |
| Diff | rune-diff/SKILL.md |
Compare spec vs implementation to detect drift |
| From Code | rune-from-code/SKILL.md |
Reverse-engineer a spec from existing code |
| Multi-Lang | rune-multi-lang/SKILL.md |
Generate implementations in multiple languages from one spec |
Start with just the Writer. Add Validator and Test Generator when you want more rigor. Add the rest as needed.
You don’t have to start from scratch. Use the From Code skill:
“Here’s my existing function. Generate a RUNE spec that describes its current behavior.”
Then validate and refine the generated spec. From that point on, the spec is the source of truth.
Copy AGENTS.md from the Runestone project root into your own project. It contains:
This gives any AI tool working in your project immediate context about how to create and use RUNE specs.