/nai-spec-drafter — evidence-anchored spec drafting

You drop a set of model instances — a client's undocumented in-house notation, an export from your own modeling tooling, anything with no written grammar — into 10 Spec Drafts/inputs/<slug>/instances/, optionally an existing-spec.md beside it, and type /nai-spec-drafter <slug>. It detects the format and whether this is a fresh draft or an update to that existing spec, derives rules from what the instances actually show, and hands you a draft in which every rule is anchored to a verbatim quote from a dropped instance file — and every quote has been re-checked by a second agent whose only job is to break it. You walk away with a spec informed entirely by evidence; adopting or publishing it is yours to decide.

This system mirrors /nai-review's shape almost exactly: one verify pass, no loop. A rule whose evidence does not hold is flagged for the human, never sent back for redrafting — iterating would let the drafter rewrite rules until they slip past the checker. What's genuinely different here is the first wave: the scoper doesn't just inventory the drop, it decides — from whether existing-spec.md is present — whether this run drafts a spec from scratch (create mode) or drafts only the delta against one that already exists (update mode), and that decision governs everything downstream.

%%{init: {'theme':'neutral', 'flowchart':{'htmlLabels':false,'nodeSpacing':45,'rankSpacing':55}}}%%
flowchart TD
    H["Human types /nai-spec-drafter"] --> C

    subgraph L1 ["1 - Orchestrator (.claude/commands)"]
        C["/nai-spec-drafter<br/>three waves, one pass each<br/>then synthesizes"]
    end

    C -->|"Wave 1"| S["spec-context-scoper<br/>detects format + create/update mode"]
    S -.->|"scoping-brief.md"| C

    subgraph L2 ["2 - One pass, no loop"]
        D["spec-rule-drafter<br/>no quote, no rule"]
        V["spec-rule-checker<br/>tries to break each citation"]
    end

    C -->|"Wave 2"| D
    D -.->|"rules.md"| V
    V -.->|"verification.md: CONFIRMED / UNSUPPORTED"| C
    C ==> OUT["spec-draft.md + spec-draft.html<br/>you decide whether to adopt it"]

    S --> T1
    D --> T1
    V --> T1
    subgraph L3 ["3 - Tools (the only route out)"]
        T1["Read / Write / Glob / Grep<br/>dropped instance files only — no web, anywhere"]
    end

    classDef orch fill:#dcefe9,stroke:#0f6f63,stroke-width:2px
    classDef tool fill:#f4f1ea,stroke:#8a7a5a
    classDef human fill:#fdf3e0,stroke:#8a5a00,stroke-width:2px
    class C orch
    class T1 tool
    class H,OUT human

The boundary has two edges. First, the evidence rule is absolute: spec-rule-drafter may not record a rule without a verbatim quote and a full file path — a pattern it cannot anchor becomes an open question for the human instead. Second, no agent in this system has web tools. A spec drafted here is grounded in what the instances actually show, not in what a written grammar for "this kind of notation" usually looks like elsewhere. Drafter and checker are separate agents for the same reason finding-drafter and finding-checker are: coverage and skepticism don't share a grader.