Language Spec Author

Author an Implementable Language Specification

Take an author from a rough language idea to a specification precise enough that a developer with zero access to the author can build a conforming implementation from the document alone. The output is a spec in the mold of the GraphQL specification — grammar, semantics, validation, execution, and conformance — that other devs can implement and interoperate against.

The hard part of a language spec is not prose; it is eliminating the ambiguities the author does not know they are leaving. Two implementers reading a vague sentence produce two incompatible languages. So this skill's method is grilling: ask one sharp question at a time, recommend a default, and refuse to write down any answer that fails the stranger / edge-case / two-implementers tests. It bundles a scaffold script, a completeness linter, and reference docs for the anatomy, the formal notation, and the interview itself.

When to Apply

• The user wants to design or formalize a language: a DSL, query language, config or data format, template language, expression language, or wire protocol.
• The user has a working idea or prototype and needs a written spec others can implement against — "spec out my query language", "formalize this syntax".
• The user asks for a grammar, a language spec, or an implementable definition and needs the lexical/syntactic/semantic structure worked out, not just examples.
• The user has a spec draft that implementers keep asking questions about — the holes need to be found and closed.

Do not use this for: authoring a Python language proposal (use python-pep-author), an internal company RFC or design doc (use dev-rfc / feature-spec), or documenting an API surface that already has a fixed definition.

Prerequisites

• Bash + coreutils (awk, sed, grep, date) for the two scripts — present by default on macOS/Linux. No language runtime is required to draft or lint.
• The author available to answer questions. This skill is an interview; it cannot invent the language's decisions, only extract, pressure-test, and record them.

Workflow Overview

The interview walks the pipeline every implementable spec must describe — source text → tokens → tree → validated tree → result — grilling at each stage. Phase 0 decides which parts apply; not every language needs all of them.

0. Frame ──► 1. Purpose &   ──► 2. Lexical   ──► 3. Syntactic
   the         principles        grammar          grammar
   language    (tie-breakers)    (chars→tokens)   (tokens→AST)
                                                       │
                                                       ▼
8. Conformance ◄─ 7. Output & ◄─ 6. Execution ◄─ 5. Validation ◄─ 4. Semantic model
   (MUST/SHOULD/    error format   (algorithms +    (static rules +   / type system
    MAY, normative) (result+errors) error model)    counter-examples) (optional)
        │
        ▼
   Scaffold (new-spec.sh) filled section by section ──► Lint (check-spec.sh) ──► Cold-read test

Scaffold once, early, so answers land in a structured document as they are settled:

scripts/new-spec.sh --title "AcmeQL" --goal-symbol "Document" --editors "R. User <r@x.io>"

0. Frame the language

Before any grammar, establish what kind of language this is — query, config, imperative, declarative, protocol, template — because that decides which anatomy parts apply. A pure config format may have no execution section; a query language needs all eight. Ask the Phase-0 questions in references/interview-playbook.md and read references/spec-anatomy.md to see the eight parts and mark which are in scope. Absent parts must be a stated choice, never a silent gap.

1. Purpose & design principles

Pin the purpose, the non-goals, and 3–5 design principles. Principles are the tie-breakers that resolve every ambiguity the spec did not foresee, so grill each one: "what future decision does this principle pre-resolve?"

2–3. Lexical then syntactic grammar

Define tokens (::, characters → tokens) before structure (:, tokens → AST). Read references/formal-notation.md first — the two-colon discipline and the shorthands (?, +, but not, lookahead) are what keep the grammar unambiguous. This is where authors under-specify most: whitespace significance, case sensitivity, comment syntax, exact literal patterns, and — the classic hole — operator precedence and associativity. Actively hunt ambiguity; an ambiguous grammar is not implementable.

4. Semantic model / type system (if applicable)

If the language talks about typed entities, schemas, or resources, define that model separately from the grammar, with its constraints and (optionally) introspection.

5. Validation (static semantics)

Enumerate every way a document can parse yet still be invalid. Write each as a named rule with a formal specification, explanatory text, and a counter-example (the smallest invalid document). The counter-example doubles as a test case and proves the rule is decidable.

6. Execution (dynamic semantics)

Specify evaluation as named, function-style algorithms (formal-notation.md), not prose. Force the three decisions authors skip: evaluation order (only where observable), coercion rules, and above all the error model — does an error abort, propagate to a boundary, or yield a partial result? Every algorithm path must return or raise a defined error.

7. Output & error format

The observable result shape, the error object shape (message, location, path, extensions), and at least one concrete serialization. Under-specifying the error format is a top interop failure — clients written against one implementation break on another.

8. Conformance

Adopt RFC 2119 keywords, declare the normative/non-normative split, and include the observably-equivalent clause so implementations can optimize. The template's conformance section is pre-filled to the GraphQL convention.

Finish: lint, then cold-read

Run the linter to catch structural holes, fix every FAIL, then apply the real test:

scripts/check-spec.sh acmeql-spec.md

check-spec.sh finds mechanical gaps (missing sections, unresolved TODOs, missing grammar notation, absent conformance keywords). It cannot judge whether the semantics are correct — that is the cold-read test: hand the draft to a developer with no context. Every question they must ask you is a defect; fold the answer back in.

Reference Files

Scripts

The template the scaffold fills lives at assets/templates/spec-template.md — copy it directly if you would rather fill the sections by hand.

Gotchas

See gotchas.md. The recurring ones: authors describe the happy path and skip the error model; lexical (::) and syntactic (:) grammar get conflated; evaluation order is specified everywhere or nowhere (specify it only where observable); and a spec that reads complete still fails the cold-read test.

Related Skills

• radical-simplification — its clarify-interview-one-at-a-time move is the interview discipline this skill applies to language design.
• python-pep-author — proposing a feature to upstream Python (a governance process, not a from-scratch language spec).
• dev-rfc / feature-spec — internal RFCs, design docs, and feature specs (not formal language definitions).