feat(sp-skill-catalog): add cyclone-spec skill (SP-N flow)
This commit is contained in:
Tyler
@@ -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<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 (every SP-N spec starts with this)
|
||||
|
||||
```markdown
|
||||
# Sub-project <N> — <Topic>: Design Spec
|
||||
|
||||
**Date:** YYYY-MM-DD
|
||||
**Status:** Draft, pending user review
|
||||
**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>
|
||||
```
|
||||
|
||||
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
|
||||
# <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.
|
||||
Reference in New Issue
Block a user