cyclone/.superpowers/skills/cyclone-spec/SKILL.md

---
name: cyclone-spec
description: "Cyclone SP-N superpowers increment flow — spec → plan → implement → merge. Use when: starting a new numbered feature increment, naming a branch, opening a SP-N PR, or doing the merge dance into main."
---

# cyclone-spec

The Cyclone repo ships every new feature as a numbered **SP-N increment**:
a spec, a plan, an implementation branch, and a single atomic merge commit
into `main`. This skill encodes the conventions so every increment follows
the same shape and the commit history stays auditable.

As of this writing: **16 specs** in `docs/superpowers/specs/`, **12 plans**
in `docs/superpowers/plans/`, and SP numbers used through **SP21** (the
universal-drilldown design in progress). The next increment is **SP22**.

## When to use

- **Starting a new feature increment.** You are about to add a numbered
  feature, fix that crosses subsystem boundaries, or anything bigger than
  a one-line change. Before you write code, reserve the next SP number and
  write the spec.
- **Naming the spec / plan files or the branch.** You have a topic, a
  date, and a number — and you need the exact path / branch shape so
  existing scripts and reviewers can find the artifacts.
- **Opening the SP-N PR.** You are about to push the branch and need the
  PR title format and the commit-prefix conventions so the merge commit
  reads cleanly.
- **Doing the merge dance.** Review is approved and you're about to land
  the branch into `main`. Use this skill to confirm the merge shape — no
  squash, no rebase, one atomic merge commit.

## Conventions

1. **Numbering.** Reserve the next SP-N number — the next integer after
   the highest `SP<n>` already used in `git log`. Never reuse a number,
   even after deletion. Numbering is monotonic and lives in the merge
   history.
2. **Branch.** `sp<N>-<short-kebab-topic>` — e.g. `sp22-line-reconciliation`,
   `sp9-multi-payer-npi`. Kebab-case, lowercase, no spaces, no slashes.
   The branch name is the canonical handle for the increment.
3. **Spec path.** `docs/superpowers/specs/YYYY-MM-DD-cyclone-<topic>-design.md`
   with header `Status: Draft, pending user review`. One spec per
   increment. Real examples: `2026-06-19-cyclone-db-reconciliation-design.md`
   (SP3), `2026-06-20-cyclone-multi-payer-npi-sftp-design.md` (SP9).
4. **Plan path.** `docs/superpowers/plans/YYYY-MM-DD-cyclone-<topic>.md`.
   Header per the upstream `superpowers:writing-plans` skill: a
   `For agentic workers:` line that names
   `superpowers:subagent-driven-development` or
   `superpowers:executing-plans`, plus a `Goal / Architecture / Tech
   Stack / Spec` metadata block, then numbered tasks with
   `- [ ] Step N:` checkboxes.
5. **Commit prefix.** All commits on the branch follow these prefixes —
   they make the SP-N merge commit readable and let `git log --grep`
   filter cleanly:
   - `feat(sp<N>): …` — implementation commits (e.g. `feat(sp20): NPI Luhn checksum + Tax ID format validation`).
   - `docs(spec): …` — landing the spec (e.g. `docs(spec): design for CycloneStore split (Step 4)`).
   - `docs(plan): …` — landing the plan.
   - `merge: SP<N> <topic> into main` — the merge commit itself (e.g. `merge: SP14 5-lane Inbox UI + acknowledge action into main`).
6. **PR title.** `SP<N> <Topic>` — e.g. `SP22 Line reconciliation`.
   Matches the merge-commit subject so GitHub's "merged PR" view and the
   `git log` entry are identical strings.
7. **Merge shape.** A single atomic merge commit into `main` after
   review. **No squash** — squash collapses the per-commit history and
   breaks the SP-N audit trail. **No rebase** — rebase rewrites the SHAs
   the PR review was performed against. The SP-N merge commit *is* the
   record of the increment landing.

## Patterns

### Spec header (canonical SP-N shape, post-SP9)

This is the canonical header for new specs. Older specs (pre-SP9) deviate
slightly — different title style, no Branch or Aesthetic direction line —
and have not been retroactively normalized. **Use this template for any
new SP-N spec.**

```markdown
# Sub-project <N> — <Topic>: Design Spec

 **Date:** YYYY-MM-DD
 **Status:** Draft, awaiting user sign-off
 **Branch:** `sp<N>-<short-kebab-topic>`
 **Aesthetic direction:** <one line — e.g. "No new UI" or "Modern (geometric sans + bold borders + electric blue accent)">

 ## 1. Scope
 <2-6 lines: what's in, what's out, with explicit out-of-scope list>
```

Worked example (matches this template): `docs/superpowers/specs/2026-06-20-cyclone-multi-payer-npi-sftp-design.md`.

### Plan header (every SP-N plan starts with this)

```markdown
# <Topic> Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use
> superpowers:subagent-driven-development (recommended) or
> superpowers:executing-plans to implement this plan task-by-task. Steps
> use checkbox (`- [ ]`) syntax for tracking.

 **Goal:** <one sentence — the outcome>
 **Architecture:** <one paragraph — how it's structured>
 **Tech Stack:** <comma-separated list>
 **Spec:** [`docs/superpowers/specs/YYYY-MM-DD-cyclone-<topic>-design.md`](../specs/...)

 ---

 ## File structure
 <tree of new / modified files>

 ## Task 0: <setup>
 ## Task 1: <first user-visible step>
 …
```

Real examples: `docs/superpowers/plans/2026-06-21-cyclone-skill-catalog.md`,
`docs/superpowers/plans/2026-06-21-cyclone-store-split.md`.

## Anti-patterns

- **Don't skip the spec ("it's a small fix").** Small fixes still get a
  3-line spec when they introduce a new numbered increment. The spec is
  the *what* and the audit trail; the plan is the *how*. Without a spec
  the merge commit has no anchor.
- **Don't squash the merge commit.** The SP-N merge commit is the audit
  trail — it tells future you exactly which feature landed and which
  commits composed it. Squash collapses that into one opaque commit and
  the per-commit history is lost.
- **Don't put code in the spec — the spec is the *what*, the plan is the
  *how*.** Specs describe scope, goals, non-goals, and decisions. Code
  snippets belong in the plan (with checkbox steps) or in the diff, not
  in the spec. SP-N specs in this repo routinely have **zero** code
  blocks.

## Related skills

- **`cyclone-tests`** — every spec lists test impact; load this when
  drafting or reviewing the spec to confirm fixture / `.test.tsx`
  implications.
- **`cyclone-edi`** — load when the SP-N increment touches an EDI parser,
  validator rule, or CAS mapping.
- **`cyclone-tail`** — load when the increment changes the live-tail wire
  format or adds a streaming page.
- **`cyclone-store`** — load when the increment adds a write-path,
  touches `store.py`, or wires a new `<entity>_written` event.
- **`cyclone-api-router`** — load when the increment adds or changes an
  HTTP endpoint in `api_routers/`.
- **`cyclone-frontend-page`** — load when the increment adds or
  refactors a page in `src/pages/`.
- **`cyclone-cli`** — load when the increment adds a CLI subcommand or
  changes exit codes.
- **`superpowers:brainstorming`** (global) — run before the spec to lock
  the scope / decisions in the spec's `## Decisions (locked during
  brainstorming)` section.
- **`superpowers:writing-plans`** (global) — produces the plan header
  format every SP-N plan follows.