---
name: brief-driven-shipping
description: >
  The shipping workflow for this product: a written brief drives every unit of work,
  one coding agent owns one repo at a time, and the OWNER holds three gates —
  database migrations, visual sign-off, and releases. Use this skill at the start of
  ANY implementation session in these repos, and whenever a task involves a
  migration, a deploy, a release/ZIP, a visual/design deliverable, or handing work
  between agents (Codex, Claude Code, or any CLI agent). Complements
  agent-working-protocol (session/git discipline) — this skill covers what to build
  and who approves it; that one covers how to behave in the checkout.
---

# Brief-driven shipping

This project ships through a division of labor that works because everyone stays in
their lane. Breaking a lane has repeatedly cost real time (lost sessions, wrong-repo
work, near-miss deploys). The lanes:

- **The brief is the contract.** Work starts from a written brief (docs/brief-*.md
  or docs/ops/*.md). If the brief and reality conflict, or the brief is silent on
  something consequential, STOP and report — do not improvise scope. Deviations get
  written back into the brief, not silently implemented.
- **One agent, one repo.** Never work in a repo another agent session owns. At
  session start prove location: `pwd` + `git remote -v` + `git branch --show-current`,
  and confirm before any work. If anything is unexpected (dirty tree, unknown
  branch, stash), STOP and report — never reconcile on your own.
- **Feature branches, push-only.** New work goes on an intentionally-declared new
  branch. Push so nothing exists only on one machine. No merges to main without the
  owner's explicit go.

## The owner's three gates (never cross them)

1. **Migrations.** Agents WRITE migration + rollback files; only the owner applies
   them, in the Supabase SQL editor, verifying the project ref in the URL first.
   Ordering is migration-first: schema lands in production BEFORE the code that
   needs it deploys — deploy-first 503s every user. Never apply, never assume
   applied; report the filename and wait.
2. **Visual sign-off.** For anything a human looks at (pages, games, reports,
   emails), "done" means the owner has eyeballed it on a preview URL and said so.
   Importing another surface's stylesheet is not visual parity — mount the same
   components. Ship your own QA pass first so the owner's pass finds nothing.
3. **Releases.** No ZIP builds, no version bumps, no Freemius/store deploys, never
   touch config-freemius*.php or release credentials. The owner controls releases.

## Reporting

- **Completion report:** branch + hash pushed, files touched, test results, UI copy
  verbatim if any, and what the owner must do next (apply migration X, eyeball URL
  Y, say "merge").
- **Blocked report:** what you tried, the exact error/observation, your best
  hypothesis, and the smallest question whose answer unblocks you. A crisp blocked
  report beats an hour of guessing — this codebase's worst bugs (a crypto failure
  mislabeled as token expiry) came from trusting a plausible-looking error message.

## Honesty rules carry into the work itself

This product's brand is honest measurement (`measured` vs `not_stored` vs
`pending`; `rendered` vs `stored_fallback`). Apply the same standard to engineering
claims: never report a number, state, or success you did not verify; distinguish
"tests pass" from "I believe it works"; label every estimate as an estimate.
