Tyler
00f11f84b6
Replaces every stale 'no auth' / 'no authentication' / 'no second party to authenticate' claim in the three top-level docs with the v1 posture: the auth boundary is HTTP (bcrypt + HttpOnly session cookie; first admin bootstrapped from CYCLONE_ADMIN_USERNAME + CYCLONE_ADMIN_PASSWORD env vars); the file-system posture (SQLCipher at rest, macOS Keychain) is unchanged; the threat model is still a stolen/imaged drive. Closes requirements §11 R-1 (was Open; now Closed by SP24 — auth shipped via the origin/main merge on 2026-06-23, SP24 reconciled the docs). Also: - backend/src/cyclone/__main__.py — emit WARNING when AUTH_DISABLED is True at boot so a misconfigured production deploy fails loudly - §6.1 migrations table in ARCHITECTURE.md — list 0013 (auth_users_and_ sessions) and 0014 (audit_log_user_id) with the renumbering note - §4.2 module map — add the cyclone.auth.* package - Three skills addenda: cyclone-tests (AUTH_DISABLED conftest bypass is mandatory context), cyclone-api-router (every router needs Depends(matrix_gate)), cyclone-spec (spec template threat-model is now auth-aware) This also tracks CLAUDE.md in git for the first time (was previously untracked; the SP24 doc updates are in scope for the increment). Spec: docs/superpowers/specs/2026-06-23-cyclone-auth-posture-alignment-design.md Plan: docs/superpowers/plans/2026-06-23-cyclone-auth-posture-alignment.md
164 lines
8.1 KiB
Markdown
164 lines
8.1 KiB
Markdown
---
|
|
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: **17 specs** in `docs/superpowers/specs/`, **13 plans**
|
|
in `docs/superpowers/plans/`, and SP numbers used through **SP22**. **SP23**
|
|
is the Ubuntu + Docker + RBAC product fork (awaiting user decision);
|
|
**SP24** is the auth-posture alignment (docs-only). The next free increment
|
|
is **SP25** after SP24 lands.
|
|
|
|
## Auth-aware spec template (SP24)
|
|
|
|
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 as of 2026-06-23** — the auth work landed in `main` and every backend endpoint requires login. 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 local-only threat model (SQLCipher at rest, macOS Keychain). SP23 changes the threat model to LAN-bound remote operator." Reference: [`docs/superpowers/specs/2026-06-23-cyclone-auth-posture-alignment-design.md`](../../../docs/superpowers/specs/2026-06-23-cyclone-auth-posture-alignment-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.**
|
|
|
|
```markdown
|
|
# 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)
|
|
|
|
```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.
|