getting-started.md

Getting started — your first story, step by step

One small feature (a CSV export for invoices) through the whole workflow. Setup is assumed — see the README if not.

Up front: you don't operate the workflow like a machine. You talk to Claude normally; the skills and gates structure how Claude works, and the hook reminds both of you when a gate isn't satisfied. Your job is the decision points — answering questions, approving drafts, judging findings.

1. Capture the idea. Say "users want to export their invoices as CSV" (or paste a voice transcript — German is fine). The intake skill turns it into a story: problem, outcome, ≥3 checkable acceptance criteria, which AGENTS.md invariants it touches, and a profile — how risky this is (trivial|standard|high), how security-relevant (none|standard|high), and the validation mode derived from the two. It proposes both axes and the derived mode with a reason; you confirm or correct the axes, and any change to the mode is an override that carries its own reason and is logged. The two axes decide which extra questions the review gates ask; the derived mode decides what evidence you owe before Gate B, and the levels accumulate: a green battery, then a check that fails without the change, then a named verification of the risk path on top of both. At security high one more is added — a named abuse scenario and evidence that the control rejects or contains it. Too thin → it asks once and waits; it refuses to invent what you didn't say. You approve the draft (the criteria are what "done" will mean), and it lands as a committed file under docs/superpowers/stories/.

2. Design. Proceed with the story (intake names the exact next step). superpowers:brainstorming explores approaches with you; the output is a spec — settled decisions with rationale, not a wish list.

3. Gate A on the spec. Claude sends the spec text to Codex (mcp__codex__exec) — a different model family, so it doesn't share Claude's blind spots. Blocker/Major findings get fixed, the review reruns on the revised spec: three passes minimum, final pass clean — the one early exit is a pass that comes back with zero findings. Hook messages like ⚠ Codex Gate A below floor (1/3) are the counter, not an error. Your job: arbitrate disputed findings — Codex is advisory, and a dismissed finding needs a one-line reason.

4. Plan, and Gate A again. superpowers:writing-plans turns the spec into a task-by-task plan (each task starts with a failing test); the same 3-pass loop runs on the plan. A flaw caught here never reaches code.

5. Implement. superpowers:executing-plans works through the plan, test-first, progress claims backed by test runs. If the Gate-A floor wasn't met, the hook says so right when execution starts.

6. Quality battery. The one command you wired at init (typecheck + lint + dead code + duplication + tests) must be green locally. CI runs the same command, so skipping locally only postpones the red.

7. Gate B on the diff. Claude makes a WIP:-prefixed commit (gives Codex a range to read; the hook knows WIP doesn't end the cycle), then loops mcp__codex__review the same way: three passes, final clean. Verification is by content — any change to included content present when the hook runs, even from a formatter, flips it back to unsatisfied; .context/ and untracked ignored paths are excluded, and staging counts, because the fingerprint covers the index and that is what a commit carries. On ✓ Codex Gate B satisfied (3/3 cycle, 3 on current fingerprint), the real commit replaces the WIP via git commit --amend.

8. PR and bots. Open the PR as usual; once the bots have commented, run /dev-workflow:process-pr-review. Every comment is validated against code and invariants — usually by a fresh-context dev-workflow:finding-triage subagent per claim, so the agent that formed a belief is not the one grading it; on a PR that edits instruction files the command checks them itself instead, and says so. Triage judges only whether a claim is true; the command then decides separately whether fixing it belongs in this PR. Each comment is answered on the thread, and, if accepted and actionable, fixed (substantial fixes go through Gate B again). Nothing silently ignored, nothing blindly applied.

9. Close the class, not the instance. Any finding from steps 3, 7, or 8 that could recur: run harden-finding. It becomes the strongest durable guard that fits — lint rule, type constraint, test, or documented convention — plus one row in docs/hardening-log.md. A recurring class escalates one rung harder, so the workflow gets stricter exactly where your project actually fails.

In practice

The rhythm: minutes of questions and approval (1–2), two review loops where you mostly arbitrate (3–4), hands-off implementation (5–6), one more loop (7), PR close-out (8–9). Trivial changes travel lighter, within limits: Gate B may be skipped only when the change is behaviourally trivial and the story is eligible — a profiled one at effective level 0 (risk trivial and security none), an unprofiled one by the prior judgement call. The profile supplies eligibility, never the skip itself; the battery is still owed and Gate A's floor is unchanged at every level. The caution bias is for non-trivial work, judgment is allowed. Two knobs: .context/codex-gate.floor (any positive integer) moves the 3-pass floor, and touch .context/codex-gate.off silences the reminders in a scratch workspace (delete to re-enable; state keeps tracking while off, so nothing goes stale).

The hook is installed once per machine but speaks only in projects you initialized — everywhere else it stays quiet, so nothing above happens in a repo where you never ran /workflow-init. If a project of yours goes unexpectedly silent, that's the first thing to check: the gates need .context/codex-gate.on or §5 in its CLAUDE.md.

Opting out

The workflow is opt-in per project, and leaving it has clean levels — pick the smallest that matches your intent:

1. Don't adopt: never run /workflow-init in a project → the plugin does nothing there.
2. One trivial change: the hook warns, it never blocks. What §5 permits depends on the story: an unprofiled one keeps the old judgement call, while a profiled one may skip Gate B only at effective level 0 (risk trivial and security none), still owes the battery, and records both the skip reason and its evidence entry in the commit body. Gate A is not skippable at any level.
3. Pause a project: touch .context/codex-gate.off (delete to re-enable; state keeps tracking, so nothing goes stale).
4. Leave for good: remove §5 from the project's CLAUDE.md (and .context/codex-gate.on) — the project reads as not adopted again. The other scaffolds (ledger, CI, AGENTS.md) work fine without the gates.
5. Machine-wide: claude plugin disable dev-workflow.

One honest rule of thumb: if .off stays in a project for weeks, level 4 is the truthful choice. A project officially without gates beats one that has them and ignores them.