| name | heater-appb-workflow |
| description | Use when starting any non-trivial HEATER change (feature, remediation program, refactor), when deciding how to plan/execute/review it, when finishing work (merge/push), or when another session or track has pushed to master mid-work (merge conflicts in openapi.json / generated.ts). |
HEATER Working Agreements — how changes actually ship here
The pipeline every shipped program used
- Spec via superpowers:brainstorming (owner resolves scope/sequencing) →
docs/superpowers/specs/YYYY-MM-DD-heater-<topic>-design.md.
- One plan file per phase/slice via superpowers:writing-plans →
docs/superpowers/plans/YYYY-MM-DD-heater-<topic>-slice<N>-*.md. Phases ≠ spec sections; don't conflate levels (program → sub-project → phase → plan → tasks).
- Execute via superpowers:subagent-driven-development (or executing-plans): fresh implementer per slice, TDD.
- Review — the non-negotiable pair: code-reviewer (with FULL engine/DB context — fake-green tests have hidden real seam bugs repeatedly) plus pr-review-toolkit:silent-failure-hunter on every non-trivial slice (standing owner rule). Both have caught pre-ship P0s (the "reused date formatter as request body" regression; the
_statsapi_current_team hydrate miss). Receiving review: verify claims against source before implementing — one reviewer "must-fix" was correctly overruled by a grep proving all 8 callers omit weeks_remaining.
- If it advances the public-launch program: add/update the row in
docs/launch/evidence_registry.yaml; check with python -m scripts.launch.evidence_registry --summary.
Standing rules (owner-set; violating these has burned sessions)
- Finish = merge to local master AND push origin/master. Work left on a branch is work the parallel track will collide with.
- Reconcile early and often:
git pull --no-rebase origin master. A parallel CMO/CEO session may push mid-task; do NOT disturb their branches or uncommitted work.
- Conflicts in
api/openapi.json or web/src/lib/api/generated.ts: REGENERATE, never hand-merge (python scripts/export_openapi.py; cd web && pnpm gen:api). Tell implementer subagents commit-only-don't-push.
- Owner-gated — surface, never start: Postgres/B2.2+ (needs a real provisioned DB), Clerk production instance (needs custom domain), Stripe live keys, disabling relays, leaguemate team assignment (deliberately the LAST launch step), anything touching the live data path (B2.4/B2.5, B3.4).
- Chat brevity: shortest possible responses to Connor; one action per step; no filler. This governs chat only — specs/plans/skills stay complete.
- Verification bar: never claim done without running the proof (full suite for src/-touching work — against a CLEAN DB when bootstrap-repair mutates yours;
pnpm build for web/). Deploys: owner step unless told otherwise; live verify after the ~10 min re-bootstrap.
- When building to a CMO page spec, read its section "API contract handoff (for the CEO track)" — it defines the exact contract to build.
Failure story
2026-06-27 WS-era: a parallel session pushed to master mid-work; hand-merging generated.ts produced a file pnpm gen:api couldn't reproduce → CI openapi-ts-sync red on an unrelated PR. The regenerate-don't-merge rule and "pull early/often" came from that afternoon (memory: reference_parallel_session_master_reconcile).
When NOT to apply
Trivial mechanical fixes (typo, one-line bugfix with an obvious test) don't need a spec/plan — but the merge+push and review-pair rules still apply to anything touching shipped behavior.
