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

name, description

name	description
cyclone-spec	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.

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.

# 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)

# <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.