diff --git a/.superpowers/skills/cyclone-spec/SKILL.md b/.superpowers/skills/cyclone-spec/SKILL.md new file mode 100644 index 0000000..345a303 --- /dev/null +++ b/.superpowers/skills/cyclone-spec/SKILL.md @@ -0,0 +1,153 @@ +--- +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/`, **11 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` 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 (every SP-N spec starts with this) + +```markdown +# Sub-project — : Design Spec + + **Date:** YYYY-MM-DD + **Status:** Draft, pending user review + **Branch:** `sp-` + **Aesthetic direction:** + + ## 1. Scope + <2-6 lines: what's in, what's out, with explicit out-of-scope list> +``` + +Real examples: `docs/superpowers/specs/2026-06-19-cyclone-db-reconciliation-design.md`, +`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.