Flow — Risk-Tiered Workflow Router

Classify the incoming work by risk, confirm the tier, run the matching workflow, and record gate evidence under .claude/harness-tier/.flow/ so the git commit hook enforces the tier's required gates.

Source of truth: risk-tiers.md (criteria, skill gate, gates) and flow-tiers.yaml (tier→gates the commit hook enforces). risk-tiers.md is already in context — the SessionStart hook injects it — but read flow-tiers.yaml, which is not injected and carries the gate list you must report in Phase 1. On a promotion also read promotion.md, the promotion-only half of the rule, which nothing injects either.

Branch names referenced below come from flow-config.branches (integration / staging / production). Domain-review items come from flow-config.review_checklist and per-module pre-checks from flow-config.modules.

Interaction. Wherever this skill asks the user something, use the host's blocking question tool already in your tool list, matched by capability rather than by a host-specific name; if it is listed but not loaded, load it first with the host's tool-discovery primitive; only when no such tool is listed, or a question call errors, offer numbered options in chat and end your turn to wait for the reply — never answer the question yourself or skip it.

Four tiers, two axes:

• Day-to-day task (this skill's main job): Docs (no code) or Dev (any code).
• Promotion (run when cutting a release): Staging (integration → staging) and Release (staging → production) — see "Promotion" below.

Input

• $ARGUMENTS — a free-text request. If empty, ask the user what the task is.
• Carry that request text forward as the task for every later phase — the task Phase 3 hands to superpowers:using-superpowers, and the reference for the commit scope.

Phase 1 — Classify the task (Docs or Dev)

A promotion is not a day-to-day task. A request to promote a branch, cut a release candidate, or release — integration → staging, staging → production — has no tier to classify: the target branch decides it. Invoke skill release-commit and stop here. The rubric below is the wrong instrument for that ask.

The line is simple: code, or no code. Inspect the real change, do not guess:

git diff --name-only HEAD                       # already-changed files
git ls-files --others --exclude-standard        # new files

• No source code (.md / docs / comments / pure config-text only) → Docs.
• Any change to .py / .js / .ts … (however small), or new feature / DB schema / cross-service shared package / business logic·node·workflow·validator / dependency change / 2+ services → Dev. (Full rubric in risk-tiers.md.)

Output the verdict — tier, reason, gates (from flow-tiers.yaml):

## Tier Classification
- Tier: DEV
- Reason: changes src/*.py (source code)
- Gates: precommit, review, doc-sync, wiki, doc-style

Phase 2 — Confirm the tier & switch to a work branch (human gate)

Ask the user (structured choice) to confirm the tier, allowing an override. Do not start before confirmation. When uncertain, default one tier up.

Then ensure you are on a work branch — before writing the marker. Day-to-day work (Docs and Dev) lives on feature/* / fix/*, never directly on an integration/staging/production branch (flow-config.branches):

cur=$(git branch --show-current)
case "$cur" in
  feature/*|fix/*|hotfix/*) ;;                       # already a work branch — stay (idempotent)
  *)
    # On integration/staging/production → cut a work branch. Prefix follows the
    # Conventional type (feat → feature/, fix → fix/); <slug> from the task, English.
    # Confirm the branch name with the user first.
    if git diff --quiet && git diff --cached --quiet; then
      git fetch origin                                # clean tree → branch off fresh integration
      git switch -c <feature|fix>/<slug> "origin/<integration-branch>"
    else
      git switch -c <feature|fix>/<slug>              # uncommitted changes → carry them off current HEAD
    fi
    ;;
esac

Record the tier marker after switching, so it binds to the work branch (the commit gate is branch-bound). When the work lives in a git worktree, the gate reads every marker from that worktree, while this marker, each .done and every relative path below land in the shell's directory. A worktree inside the project directory: cd into it first and stay there. One outside it: the shell returns to the project directory after each call, so put the worktree's path in front of every marker path and of .gitignore instead.

# Ensure the evidence directory is never exposed to git (idempotent). Safe even
# without running /flow-init first: add the ignore rule *before* writing the tier
# marker to close the untracked-exposure window. `tr` drops the CR a CRLF .gitignore ends
# each line with, which `-x` would otherwise never match, adding the line on every run.
tr -d '\r' 2>/dev/null < .gitignore | grep -qxF '.claude/harness-tier/.flow/' || printf '\n.claude/harness-tier/.flow/\n' >> .gitignore
mkdir -p .claude/harness-tier/.flow
echo "<tier>:$(git branch --show-current)" > .claude/harness-tier/.flow/tier   # docs | dev

On Codex, the session hooks come first. The Codex plugin carries no lifecycle hook; /flow-init registers them in .codex/hooks.json. When that file does not name harness-tier/hooks/invalidate-gate-markers.sh, stop and have the user run $flow-init: without that hook an edit after a review leaves the review's evidence standing, and the commit passes on it.

Phase 3 — Dispatch

Record each completed gate as .claude/harness-tier/.flow/<gate>.done. precommit (every-commit module checks of changed modules) and security-scan (promotion module checks of all modules) are executed by the commit hook itself — no marker (both are ordinary gates entries and timing buckets over flow-config.modules[].checks, routed by each check's when; removing one from a tier's list in flow-tiers.yaml disables it for that tier). wiki and doc-style are two more gates needing no marker — neither is a timing bucket; the hook's gate script runs both in-process, wiki_graph.py --verify whenever flow-config.wiki is enabled and the prose lint whenever flow-config.doc_style is (each a no-op otherwise). doc-style only ever warns; doc-style.yml in CI holds the verdict. Do not touch .claude/harness-tier/.flow/wiki.done or doc-style.done, and do not go looking for a skill behind either — none exists; the hook runs the checks.

Precondition (Dev) — the superpowers plugin must be installed. If superpowers:using-superpowers is not among the available skills, STOP: tell the user to install it (superpowers@claude-plugins-official, e.g. via /plugin) and re-run /flow. Do not fall back to manual implementation.

Docs — no code (superpowers OFF)

1. Make the edit directly. Do not invoke superpowers. precommit not needed (no code).
2. Invoke the doc-sync skill to harmonize the doc set (index CLAUDE.md + per-service docs + rule dirs from flow-config.doc_sync; also reconciles code↔doc drift). On pass → touch .claude/harness-tier/.flow/doc-sync.done.
3. Commit through the commit skill — invoke skill commit with the tier and what changed; it stages, picks the type, and applies the 50/72 rule (rule 4). Then merge applying merge-strategy.md (rule 3 — not a plain merge). (The commit hook blocks until doc-sync.done exists.) When flow-config.merge_workflow.pull_request includes daily, open a PR instead of merging: rebase → integration-test human gate (unchanged) → push → gh pr create → hand over the PR URL and name the merge method it must use — "Squash and merge" from a feature/* branch, "Rebase and merge" from fix/* (Merge strategy rows 1·2; the integration ruleset allows both and cannot tell them apart, so this one is on you) — then stop. Without gh, print the compare URL and let the user create it — never block.

Dev — any code (superpowers ON)

1. Load the wiki context first (skip silently when there is no wiki — both commands print nothing and exit 0): name the files you are about to change to python3 .claude/harness-tier/scripts/wiki_graph.py --nodes-for <paths…>, then for each printed id run python3 .claude/harness-tier/scripts/wiki_graph.py --neighbors <id> and read the documents it lists before planning. An empty result is a normal answer (the code is undocumented) — proceed without it. When that produces nothing — no wiki, or no node owns the paths — read docs/sds/README.md and docs/srs/README.md directly if they exist (harness-rules.md 8 fixes those locations). Neither existing is normal — proceed. Docs tier skips this: reading a design document to change a paragraph is the process-to-risk mismatch the tiers exist to prevent.

2. Record a new requirement in the SRS first — skip silently when docs/srs/ is absent (the command prints nothing and exits 0). This runs only for a new customer requirement; implementing an existing one, a bug, or a refactor skips it. Route with python3 .claude/harness-tier/scripts/srs_check.py --areas, then take the number from --next-id docs/srs/<area>.md --kind FR and add the FR to that file, plus a C-NNN in docs/srs/README.md (--next-id docs/srs/README.md --kind C) when the request names a customer need the SRS does not yet carry. You judge two things only — whether this is a new requirement, and which area it belongs to; the number comes from --next-id, the integrity from --verify. FAIL-OPEN: a failure here warns and does not block the commit — the srs-verify workflow holds the verdict.

   A new area file is a wiki node, and only half of that is fail-CLOSED. Where the host has a wiki, give it front matter: wiki_id from python3 .claude/harness-tier/scripts/wiki_graph.py --derive-id docs/srs/<area>.md, a title, and the related edge the template leaves commented out — uncomment it once docs/srs/README.md carries front matter of its own, since an edge to a document that is no node dangles and blocks. Then rebuild with python3 .claude/harness-tier/scripts/wiki_graph.py --build and stage graph.yaml alongside it. Write the front matter and skip the rebuild, and the commit gate's --verify blocks with a reason naming the graph rather than this step. Omit the front matter and nothing blocks — a file carrying none is no node, so the gate has nothing to compare and the area stays out of the wiki in silence. That is the likelier slip, and it is on you rather than the gate.

3. Invoke skill superpowers:using-superpowers — its injected text is a reminder, not execution: the pipeline starts only on the invocation, which picks the entry skill by task and chains the rest. Never open brainstorming or any other stage yourself before it. Feed the request from Input in as the task.
4. Apply the project overlays superpowers does not know about:
   • Spec and plan commit as Docs, the code as Dev — before the first code edit, commit the spec and plan under a docs:<branch> marker (doc-sync → commit), then write dev:<branch> back. Under dev that commit waits on a review of code not yet written. The swap is mechanical, not a reclassification: the Dev tier Phase 2 confirmed still holds, so write dev:<branch> back without asking the user again.
   • Implementation minimalism — right after the plan, before writing code, climb the reuse-before-build ladder (YAGNI → codebase → stdlib → native → dependency → one line → minimum code) and stop at the earliest rung. Detail and non-negotiable floor in dev-overlays.md.
   • Record the design before the code — right after the plan, alongside the reuse ladder: a new module, an integration-point contract, or a structural change goes into docs/sds/ now, with its Implemented requirements linking the FR anchors it satisfies. This is the structure half; doc-sync reconciles the rest (sources · stale · orphans) after the code. Placed after doc-sync instead, the PostToolUse hook would delete doc-sync.done and review.done on that edit, so both would have to run again — a loop.
   • Selective TDD — only business logic / core nodes / validators / workflow orchestration (see dev-overlays.md), not every change.
   • invoke the doc-sync skill (not part of superpowers) → touch .claude/harness-tier/.flow/doc-sync.done.
   • Domain review — dispatch subagent (general) as an independent review agent (separate context; it runs shell commands). git is the authority on the changed-file list — every file is reviewed and the count is reported — judged against flow-config.review_checklist (regression, cross-service contract, DB/migration & transactions, async task idempotency & queue routing, API error conventions), plus the callers of every changed public symbol. Read dev-overlays.md Domain review before dispatching and hand the reviewer its ① command verbatim — git diff HEAD alone misses what is already committed on the branch. On pass → touch .claude/harness-tier/.flow/review.done. Every edit after that pass voids it — the fixes the review itself asked for included. A PostToolUse hook deletes review.done and doc-sync.done the moment a file changes, so passing is a fixpoint: both recorded, nothing edited since. A fix therefore re-runs doc-sync and then this review, over a recomputed changed-file list. An edit the hook never saw (a terminal command, another tool) leaves the markers standing — rm -f .claude/harness-tier/.flow/review.done .claude/harness-tier/.flow/doc-sync.done. A host that sets flow-config.gate_evidence.invalidate_on_edit: false turns the hook's deletion off, so in its tree an edit after the pass commits unreviewed (dev-overlays.md).
5. Commit through the commit skill — invoke skill commit with the tier and what changed (rule 4) → merge applying merge-strategy.md (rule 3 — not a plain merge). (The commit hook blocks until review.done and doc-sync.done.) When flow-config.merge_workflow.pull_request includes daily, open a PR instead of merging: rebase → integration-test human gate (unchanged) → push → gh pr create → hand over the PR URL and name the merge method it must use — "Squash and merge" from a feature/* branch, "Rebase and merge" from fix/* (Merge strategy rows 1·2; the integration ruleset allows both and cannot tell them apart, so this one is on you) — then stop. Without gh, print the compare URL and let the user create it — never block. A hotfix/* branch merges into production instead: invoke skill release-commit and run its Hotfix procedure, which owns that merge, the release check and the back-merge after it.

Promotion — Staging (integration → staging) / Release (staging → production)

Promotions are gated at the commit on the target branch, so they need no tier marker — the branch drives it. Read promotion.md first — nothing injects it. The procedure itself lives in release-commit: which bump-level mechanism the host's release CI is on, the gates and their markers, the merge shape each promotion takes, and the end state the three branches settle into. Invoke skill release-commit rather than restating any of it here — one fact, one place.

Phase 4 — Finalize

After the commit/merge completes, clear the flow state. The command below removes the evidence directory whole — every marker in it, never a selected subset. Phase 4 is the day-to-day task's finalize step, and a promotion never reaches it: those markers are release-commit's to clear at its own end state, where the post-release back-merges also happen — production → integration (not optional) and production → staging (fast-forward only, skipped when refused).

Under PR mode, clear only after the PR is merged. A review-feedback commit pushed to the PR branch is gated like any other, and the gate reads whether the tier marker and each gate's evidence file exists. Clearing at PR-creation time leaves that commit unclassified and blocked.

rm -rf .claude/harness-tier/.flow

Critical rules

1. Always classify before working — confirm with the user (Phase 2), then write the tier marker.
2. Record gate evidence honestly — touch .claude/harness-tier/.flow/<gate>.done only after the gate genuinely passes. A marker is a forcing function, not a stamp. It is a plain file that outlives the commit that used it, so a gate whose subject changed after it passed is no longer recorded honestly. The PostToolUse hook enforces that for review and doc-sync — any edit deletes both, unless the host turned that off (Dev step 4) — so what is left to you is the edit it cannot see (a terminal command, another tool): delete the marker yourself and earn it again.
3. Apply the documented Merge strategy — direct commit + merge, but do not default to a plain / --no-ff merge. For every merge, look up its branch-flow row in merge-strategy.md and follow it exactly — the required strategy varies by flow (rebase / squash / --no-ff merge). Commit types & the 50/72 rule live in commit-discipline.md. Several of merge-strategy.md's rows are enforced by the hook: a merge whose flags violate its row is blocked (exit 2) naming the flag it wants. That table's Gate column says which rows fire — the rest still depend on you following them.
4. Every commit goes through the commit skill — invoke skill commit, which owns staging, the type choice, and the 50/72 rule so this skill does not restate them. It inherits the pre-commit gate like any other commit: never --no-verify.
5. Commit from a git worktree with git -C <worktree> commit … — the -C names the tree in the command itself, even with the shell already inside it (Phase 2), since the hook's cwd is only a guess at it. CLAUDE_PROJECT_DIR is fixed at session start, so when the commit runs in a worktree, the gate re-points to it by branch-key (flow_gate_check.py --classify); the explicit git -C <worktree> is the deterministic signal that keeps that detection unambiguous, and the markers it reads there are the ones Phase 2 wrote into the worktree. (No worktree → no change.) The commit skill issues it that way (rule 4), and owns "never --no-verify" and "stage only affected files" with it.
6. Worker / service-process safety — Dev+ changes touching long-running worker processes: inspect for in-flight tasks and require explicit user approval before restarting.
7. On conflict, risk-tiers.md and flow-tiers.yaml win — where this skill disagrees with them, follow them, and tell the user this skill has drifted.