vict00r99/rune-stone/rune-writer

For the full RUNE pattern reference, see SPEC.md.

The Pattern

Every RUNE spec defines these fields:

Rules

• SIGNATURE must use the target language's actual syntax, not pseudocode
• BEHAVIOR must use WHEN/THEN format — each business rule = one clause
• TESTS must have at least 3 cases: one happy path, one boundary, one error
• INTENT must be 1-3 sentences, clear enough for a docstring
• Every BEHAVIOR rule must have at least one corresponding test
• Error messages in BEHAVIOR must be specific, not generic

Format: YAML (.rune files)

Use standalone .rune files when you want formal, parseable specs. The SIGNATURE uses the target language's real syntax:

---
meta:
  name: validate_coupon
  language: python
  version: 1.0
  tags: [e-commerce, validation]
---
 
RUNE: validate_coupon
 
SIGNATURE: |
  def validate_coupon(code: str, coupons: list[dict], current_date: str) -> tuple[bool, str]
 
INTENT: |
  Validates a coupon code against active coupons. Checks existence,
  expiration, and discount value. Case-insensitive matching.
 
BEHAVIOR:
  - WHEN code is empty THEN return (False, "Coupon code cannot be empty")
  - WHEN code not found (case-insensitive) THEN return (False, "Coupon code not found")
  - WHEN coupon has expired THEN return (False, "Coupon has expired")
  - OTHERWISE return (True, matching_coupon)
 
TESTS:
  - "validate_coupon('SAVE10', [...], '2025-01-15')[0] == True"
  - "validate_coupon('save10', [...], '2025-01-15')[0] == True"
  - "validate_coupon('INVALID', [...], '2025-01-15')[0] == False"
  - "validate_coupon('', [], '2025-01-15')[0] == False"

The pattern is the same in every language. Only the SIGNATURE syntax and naming conventions change.

Format: Markdown (embedded in any .md)

Use markdown sections when embedding specs inside AGENTS.md or other docs:

### validate_coupon
 
**SIGNATURE:** `def validate_coupon(code: str, coupons: list[dict], current_date: str) -> tuple[bool, str]`
 
**INTENT:** Validates a coupon code against active coupons. Checks existence, expiration, and discount value. Case-insensitive matching.
 
**BEHAVIOR:**
-WHEN code is empty THEN return (False, "Coupon code cannot be empty")
-WHEN code not found (case-insensitive) THEN return (False, "Coupon code not found")
-WHEN coupon has expired THEN return (False, "Coupon has expired")
-OTHERWISE return (True, matching_coupon)
 
**TESTS:**
-`validate_coupon('SAVE10', [...], '2025-01-15')[0] == True`
-`validate_coupon('', [], '2025-01-15')[0] == False`

Both formats contain the same information. The AI treats them identically.

Generating Specs from Requirements

When a user describes what they need in plain language, generate a RUNE spec.

Process

1. Extract from the requirement:

• What is the function's purpose?
• What are the inputs and outputs?
• What are the business rules?
• What could go wrong? (edge cases)

1. Map each business rule to a WHEN/THEN clause in BEHAVIOR

1. Derive CONSTRAINTS from input descriptions ("must be positive", "between 0 and 100")

1. Derive EDGE_CASES from boundaries (empty input, zero, max value, invalid types)

1. Write TESTS that verify each BEHAVIOR rule plus edge cases. Minimum 3, aim for 8-15.

1. Ask the user which format they want (YAML .rune file or Markdown section). If unclear, default to the same format used elsewhere in their project.

1. Validate the spec against the checklist below before presenting it.

Validating Specs

When asked to validate a spec, or before presenting one you generated, check:

Structure

• [ ] All required fields present: SIGNATURE, INTENT, BEHAVIOR, TESTS
• [ ] If YAML: valid YAML syntax, meta section with name and language
• [ ] If Markdown: headers use bold field names, code in backticks

Content

• [ ] SIGNATURE uses actual language syntax (not pseudocode)
• [ ] BEHAVIOR uses WHEN/THEN format
• [ ] TESTS has at least 3 cases (happy path, boundary, error)
• [ ] INTENT is 1-3 sentences
• [ ] Every BEHAVIOR rule has at least one test
• [ ] Every EDGE_CASE has a corresponding test
• [ ] Error messages are specific (not generic "invalid input")

Implementing from Specs

When given a RUNE spec (in either format) to implement, generate code that follows it exactly.

Process

1. Use the exact SIGNATURE — function name, parameters, types, return type
2. Implement each BEHAVIOR rule in order — each WHEN/THEN becomes a conditional branch in the target language
3. Add input validation from CONSTRAINTS
4. Handle every EDGE_CASE
5. Add a doc comment from INTENT (docstring, JSDoc, GoDoc, rustdoc, etc.)
6. Generate tests from TESTS using the target language's testing framework

Rules

• Never deviate from the SIGNATURE
• Implement ALL BEHAVIOR rules, not just some
• Every item in TESTS must have a corresponding test function
• Error messages must match those specified in BEHAVIOR
• Follow the target language's conventions