---
name: dragon-spec-author
description: |
  Author a new Dragon Platform spec (under `dragon-platform/specs/NNN-<slug>/`)
  that conforms to the seven invariants of the Dragon Constitution. Produces
  the three-file SDD bundle (spec.md + plan.md + tasks.md) with sections
  pre-populated against the constitution, suggests the next sequence number,
  and emits the GitHub PR body. Use when starting any work that's ≥4 hours
  or touches ≥2 Dragon-stack repos.
argument-hint: "<one-line feature description>"
user-invocable: true
---

# Dragon Spec Author

You are writing a new spec under `dragon-platform/specs/`. Ryan's
Dragon Constitution (`dragon-platform/.specify/memory/constitution.md`)
governs every spec. The seven invariants are non-negotiable:

I.  **LOCAL-FIRST** — no operator telemetry, scan data, IOCs, or memory
    leaving the box without operator-set env vars.
II. **TWO-COLOUR THEME** — teal `#00B89F` + red `#ff5a55`, Inter sans,
    h1 weight 900 / 2.5rem / -0.02em. No black-and-green.
III.**CROSS-OS SINGLE BINARY** — Rust binary, Python package, Next.js
    app. Every OS-specific block has a `not(target_os=...)` fallback.
    Never hardcode `/home/`.
IV. **OPERATOR OWNS DATA** — `~/.dragonkeep/`, `~/.copilot/`,
    `<repo>/reports/`. No opaque binary blobs.
V.  **NGAV-GRADE OR DON'T SHIP** — defensive engines beat Falcon on
    local-first, source-readable rules, or operator-tuneable.
VI. **SPEC BEFORE CODE** — this skill is the operationalization of
    this rule.
VII.**STORY-DRIVEN COMMITS** — commits cite spec task IDs. PR bodies
    quote acceptance criteria.

## Workflow

### 1. Decide the next spec number

Read the index in `dragon-platform/README.md` ("Active specs"). Take the
highest number, add one. Use 3 digits (`014`, `015`, …, `999`, then
`1000`+).

### 2. Pick the slug

Short, lowercased, hyphen-separated, ≤4 words.
Examples: `wyrm-token-budgeting`, `dragonkeep-windows-etw`, `wall-escape`.

### 3. Create three files under `specs/NNN-<slug>/`

**`spec.md`** — what + why + acceptance + non-goals. *No implementation
details.* Use the template:

```markdown
# Spec NNN · <Title Case>

**Status:** 🟢 ready to implement YYYY-MM-DD — defaults locked
**Repos:** <comma-separated repo names>
**Targets:** <models/platforms if relevant>

## Problem
<2-4 paragraphs. What's broken or missing. Concrete operator pain.>

## Why now
<1-2 paragraphs. What changed to make this matter today.>

## Acceptance criteria
1. **<criterion name>.** <Testable specific behavior.>
2. <…>

## Non-goals
- <Explicitly out of scope, so reviewers don't ask.>

## Decisions
<If reviewer asked questions during draft, the answers go here.>

## Constitution check
- **I · Local-first** — <how this complies>
- **VI · Spec before code** — this is the spec
- **VII · Story-driven commits** — task commits will reference T-numbers
```

**`plan.md`** — architecture + phases + risks.

```markdown
# Plan NNN · <Title>

## Architecture
<Modules / tables / APIs being added. Inline code blocks ok.>

## Phases
| Phase | Work | Effort | Status |
|---|---|---|---|
| 1 | <atomic chunk> | 2h | pending |

## Risks
1. **<risk>.** Mitigation: <…>.

## Definition of done
- All acceptance criteria pass
- Ship as <repo>@<version>
- This spec moves to ✅ shipped YYYY-MM-DD · <repo>@<commit>
```

**`tasks.md`** — numbered atomic tasks.

```markdown
# Tasks NNN · <Title>

## Phase 1 · <name>
- [ ] T001 · <do exactly one thing>
- [ ] T002 · <…>
```

### 4. Update `dragon-platform/README.md`

Add the new row to the Active specs table:

```markdown
| NNN | <slug> | 🟡 drafted YYYY-MM-DD | <repo(s)> |
```

(Status flips to `🟢 ready` after open questions are resolved, then `✅
shipped` after release.)

### 5. Branch + commit + PR

```bash
cd ~/repos/personal/dragon-platform
git checkout main && git pull --ff-only
git checkout -b spec/NNN-<slug>
git add specs/NNN-<slug>/ README.md
git commit -m "spec(NNN): <subject>

<2-3 sentences explaining what + why. Mention if open questions remain.>

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>"
git push -u origin spec/NNN-<slug>
gh pr create --title "spec(NNN): <subject>" --body "<reference spec/plan/tasks files; list open questions; constitution check>"
```

## Anti-patterns

- ❌ Mixing implementation into spec.md ("we'll use a HashMap…"). Goes
  in plan.md only.
- ❌ Vague acceptance criteria ("the feature works"). Each criterion
  must be testable.
- ❌ Skipping non-goals. Reviewers will ask. Pre-empt.
- ❌ Forgetting constitution check. Every spec proves it doesn't
  violate the seven invariants.
- ❌ Pushing the spec branch directly to main. Always PR.
- ❌ More than ~10 phases or ~50 tasks. If the scope is bigger,
  decompose into multiple specs.

## When to skip this skill

For ≤4-hour surgical fixes (rule VI), skip the spec; document the
bug in the commit message instead.