language-spec-author

name

language-spec-author

description

Turn a rough idea for a language into a complete, implementable specification — a DSL, query, config/data, template, or protocol language — by interviewing the author dimension by dimension until another developer could build a conforming implementation from the document alone. It grills for the decisions authors skip: lexical rules (whitespace, case, comments, literals), grammar with precedence and ambiguity resolution, a semantic/type model, validation rules with counter-examples, execution algorithms and the error model, the output/serialization format, and RFC 2119 conformance. The completeness bar and formal notation (lexical vs syntactic grammar, function-style algorithms) are distilled from the GraphQL specification. Trigger on "spec out my language", "design a DSL / query language", "write a language or grammar spec", "formalize this syntax", or when someone has a language idea that needs to become an implementable spec — even if they only say "spec" or "grammar".

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 <[e-mail]>"

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

File	Read it when
references/spec-anatomy.md	Framing scope (Phase 0) and checking completeness — the eight parts of an implementable spec, what each answers, and the done-bar for each
references/formal-notation.md	Writing the grammar (Phases 2–3) and semantics (Phases 5–6) — lexical vs syntactic notation, algorithm notation, data collections, RFC 2119 keywords
references/interview-playbook.md	Running the interview — the grilling stance, the three rejection tests, underspecification detectors, and the per-phase question bank

Scripts

Script	What it does
scripts/new-spec.sh	Scaffolds a spec draft from the template, filling title/date/version/goal-symbol. Run with -h for usage.
scripts/check-spec.sh	Lints a draft for structural holes (missing sections, unresolved placeholders, grammar notation, conformance keywords, counter-examples) → PASS/WARN/FAIL, non-zero exit on any FAIL.

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).