--- 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: SP numbers used through **SP41** (the in-window rebill pipeline); **SP42** is this doc-pass. **SP23** shipped the Ubuntu + Docker + RBAC + auth LAN-bind product fork; **SP24** is the reissue-claims + auth-docs alignment; SPs **25–40** cover the resubmissions, `claim_acks`, rendering/service NPI, transaction-set control numbers, additional live-tail streams, dashboards, and rebill prerequisites shipped between SP24 and SP41. The next free increment after SP42 is **SP43**. ## Auth-aware spec template (post-SP23) The threat-model section in the canonical SP-N spec template (`## 1. Scope`, second-to-last bullet) used to read "no second party to authenticate; no second host to harden against." **That phrasing is stale since SP23 landed (2026-06-23)** — every backend endpoint now requires login (`cyclone.auth.*`, `Depends(matrix_gate)` on every `APIRouter`), the React app ships a `Login` page, RBAC roles `admin / user / viewer` gate individual endpoints, and the host still binds `0.0.0.0:8000` (reachability controlled by the host firewall / compose port publishing). The dev/test escape hatch is `CYCLONE_AUTH_DISABLED=1`, which logs a WARNING at boot. New specs should instead state the auth boundary explicitly: "the auth boundary is HTTP (login required, bcrypt + HttpOnly session cookie); file-system threats remain the LAN-only threat model (SQLCipher at rest, macOS Keychain). SP23 expanded the threat model to a remote operator on the LAN." Reference: [`docs/superpowers/specs/2026-06-22-cyclone-ubuntu-docker-deployment-design.md`](../../../docs/superpowers/specs/2026-06-22-cyclone-ubuntu-docker-deployment-design.md). ## 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` already used in `git log`. Never reuse a number, even after deletion. Numbering is monotonic and lives in the merge history. 2. **Branch.** `sp-` — 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--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-.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): …` — 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 into main` — the merge commit itself (e.g. `merge: SP14 5-lane Inbox UI + acknowledge action into main`). 6. **PR title.** `SP ` — 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 — : Design Spec **Date:** YYYY-MM-DD **Status:** Draft, awaiting user sign-off **Branch:** `sp-` **Aesthetic direction:** ## 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 # 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:** **Architecture:** **Tech Stack:** **Spec:** [`docs/superpowers/specs/YYYY-MM-DD-cyclone--design.md`](../specs/...) --- ## File structure ## Task 0: ## Task 1: … ``` 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 `_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.