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.