cyclone/docs/superpowers/specs/2026-06-21-cyclone-skill-catalog-design.md

Cyclone Skill Catalog — Design Spec

Date: 2026-06-21 Status: Draft, pending user review Branch: main Scope: A catalog of 8 project-scoped Grok skills under cyclone/.superpowers/skills/ that codify Cyclone's conventions layer-by-layer. No code changes; pure guidance artifacts.

Context

Cyclone is now a substantial codebase — api.py (~111KB) and store.py (~95KB) are monoliths being actively split, ~30 EDI parsers, 21 pages / 30 components / 35 hooks on the frontend, 90+ pytest tests, 14 specs and 8 plans already on disk. There is enough surface area that an AI agent (or a new contributor) repeatedly re-derives the same conventions: where the live-tail wire format lives, which validator file owns which rule, how a new SP-N spec is named, where prodfiles fixtures go.

This spec introduces a catalog of 8 skills, one per major subsystem, that encode those conventions so they are loaded on demand instead of re-derived each time. Each skill is auto-discovered by description match (no slash command). The success criterion is consistency across modules — when adding a new EDI parser, a new streaming page, a new API router, etc., the skill hands the AI the established conventions for that subsystem so additions stay consistent with what's already there.

Decisions (locked during brainstorming)

1. Scope: 8 skills, layer-mapped (one skill per subsystem). Not workflow-anchored, not reference-plus-convention hybrid. Layer-mapped was chosen because each subsystem has exactly one owner and the success criterion is consistency per layer.
2. Location: Project-scoped, under cyclone/.superpowers/skills/. Auto-discovered whenever anyone works in this repo. Not global.
3. Categories covered: Code-pattern / domain skills + Process / workflow skills. Testing-fixture and operational-CLI skills deferred (none selected).
4. Success criterion: Consistency across modules (selected over faster onboarding / process discipline / navigability).
5. No hub skill. The catalog itself lives in this spec and (later) in the README's skills section. The AI doesn't load a runtime index.
6. No loading graph. Each skill cross-references the others it pairs with, but no prescriptive load order is encoded. Auto-discovery fires per-description.

The catalog

#	Skill	Owns
1	cyclone-spec	The SP-N superpowers flow as a one-shot: branch naming, docs/superpowers/specs/…-design.md + …-plan.md templates, PR title format.
2	cyclone-tests	pytest + vitest fixture patterns; backend/tests/fixtures/ layout; .test.tsx sibling convention; prodfiles drop-in procedure.
3	cyclone-edi	Parser/validator conventions across 837P/835/999/270/271/277CA/TA1; segment-walk pattern; validator rule format (R200/R210, NPI Luhn, EIN, CAS); fixture discovery.
4	cyclone-tail	Live-tail wire format (item / snapshot_end / heartbeat / item_dropped / error), useTailStream + useMergedTail + per-resource hook triplet, StatusPill states.
5	cyclone-store	Write-path conventions in store.py; the pubsub event contract (claim_written / remittance_written / activity_recorded); snapshot shape; SP21 store-split boundary map.
6	cyclone-api-router	FastAPI router conventions (api_routers/), api_helpers.py reuse, response shapes, error envelopes.
7	cyclone-frontend-page	Page-component pattern (TanStack Query + tail + drawer + URL state), use<X> hook convention, Layout / PageHeader / Sidebar usage.
8	cyclone-cli	CLI subcommand conventions in cli.py (serve/parse/backup/rotate-key/validate), argparse style, exit codes, smoke-test patterns.

Per-skill structure

Every skill lives at .superpowers/skills/<name>/SKILL.md and follows this skeleton:

---
name: <kebab-case>
description: "<one-sentence trigger, with Use when: … keywords>"
---

# <Title>

## When to use
2–5 bullets of concrete situations. ("adding a new EDI parser"
beats "working on EDI".)

## Conventions
Numbered, testable rules. Each rule is something a reviewer can
check.

## Patterns
Small copy-pasteable skeletons (parser stub, page hook, router
signature). Concrete code blocks, not prose.

## Anti-patterns
Tempting-but-wrong moves. ("Don't write a new useX hook per page —
extend the existing one.")

## Related skills
Cross-references to the other 7 skills that often pair with this
one, one line each.

References subdirs: <skill>/references/<file>.md for long pattern catalogs (e.g. a per-parser mapping in cyclone-edi, a wire-format reference in cyclone-tail). Linked from SKILL.md. SKILL.md itself stays under ~200 lines; long content goes to references so the auto-load is fast.

No code in skills. Skills are guidance for the AI, not runnable artifacts. Optional <skill>/scripts/ only for things that genuinely need automation (e.g. a fixture-discovery script in cyclone-edi). Most skills won't ship scripts.

Skill size budget: ~150–250 lines for SKILL.md, plus zero or a few references. Anything bigger is a sign the skill is trying to do two things.

Loading & cross-references

Trigger model. Every skill is auto-discovered by description match. The description field is the only thing the loader sees before deciding to fire, so each gets one carefully tuned sentence. Example drafts:

• cyclone-edi — "Cyclone EDI parser/validator conventions (837P/835/999/270/271/277CA/TA1). Use when: adding or changing a parser, a validator rule, or a CAS code mapping."
• cyclone-tail — "Cyclone live-tail streaming wire format and the useTailStream / useMergedTail hook triplet. Use when: adding a new streaming list page, changing the wire format, or debugging stalled/reconnecting state."
• cyclone-store — "Cyclone store write-paths, the pubsub event contract, and the SP21 store-split boundary map. Use when: touching store.py, adding a new entity, or wiring a new write event."
• cyclone-api-router — "Cyclone FastAPI router conventions (api_routers/, api_helpers.py, response shapes, error envelopes). Use when: adding or changing an HTTP endpoint."
• cyclone-frontend-page — "Cyclone React page conventions (TanStack Query, use hook, drawer, URL state, .test.tsx sibling). Use when: adding a new page or refactoring an existing one."
• cyclone-cli — "Cyclone CLI subcommand conventions (cli.py, serve/parse/backup/rotate-key/validate, exit codes, smoke tests). Use when: adding a CLI subcommand or working on operator-facing commands."
• cyclone-spec — "Cyclone SP-N superpowers increment flow — spec → plan → implement → merge. Use when: starting a new numbered feature increment or doing the merge dance."
• cyclone-tests — "Cyclone pytest + vitest fixture patterns, prodfiles layout, backend/tests/fixtures/ conventions. Use when: adding a test or wiring in a real-EDI sample."

Descriptions are tuned so the right one fires and the others stay quiet. The "Use when:" half is the disambiguator.

Cross-references live in two places per skill:

1. A ## Related skills section (per the template) — short list, one line each.
2. An explicit If you are also touching X, also load skill Y line at the top of the relevant section.

Loading order isn't prescriptive. The AI loads what's relevant; if two skills conflict, the more-specific one wins.

Build order / phasing

8 skills shipped one-per-PR, grouped into 4 phases:

Phase	Skill	Rationale
1. Foundations	cyclone-spec	Already implicit in the SP-N flow; codify first because every later feature goes through it. Smallest, fastest.
	cyclone-tests	Referenced by every other skill (fixture layout, vitest sibling pattern). Must land before any domain skill can ship its ## Anti-patterns cleanly.
2. Domain hot spots	cyclone-edi	30 parsers, scattered validators, fixture sprawl. Highest leverage per line of skill text.
	cyclone-tail	Wire format documented in README but consumed across 3 page-hook pairs; drift risk is concrete.
3. Backend layers	cyclone-store	Aligns with SP21 (CycloneStore split, currently in plan stage).
	cyclone-api-router	Pairs with store; api_routers/ already exists.
4. Frontend + CLI	cyclone-frontend-page	Generalizes what cyclone-tail already covers.
	cyclone-cli	Standalone, lowest urgency.

Per-skill PR shape: single commit adding one .superpowers/skills/<name>/SKILL.md (+ optional references/). No code changes. Reviewable in isolation. If a description turns out wrong, the fix is one line.

Out of scope

• Testing & fixture skills (deferred per user selection).
• Operational / CLI safety-sequence skills beyond the basic cyclone-cli conventions skill (deferred per user selection).
• Skills outside cyclone/.superpowers/skills/. Global skills (e.g. ~/.grok/...) are not touched.
• Any changes to existing code, tests, README, or specs.
• A hub/index skill.

Verification

After all 8 skills are landed:

1. Pick a sample task from each phase (e.g. "add a new EDI parser", "add a new streaming list page") and verify the matching skill fires by description match alone (no slash command).
2. Verify cross-references resolve — every "If you are also touching X, also load skill Y" line points to a skill that exists and whose description would actually fire for that scenario.
3. Verify each SKILL.md stays under the ~200-line budget (long content goes to references/).
4. Verify the catalog as a whole covers every subsystem with monolith risk (api.py, store.py, parsers/, hooks/) and the operator-facing surface (CLI).