Flow Guide
Use $flow-guide <help|route|rules|next|close> [query] to answer one workflow
question. The guide is advisory: it records evidence and hands work to the
owner through the shared neutral handoff contract; it does not acquire the
owner's authority.
When NOT to Use
- Implementing a bounded task: invoke
$flow-drive <task-text|task-file|confirmed-spec-or-change-id> directly.
- Reviewing a completed diff: use
change-verdict.
- Tracing code or diagnosing a failure: use
code-trace.
Actions
| Action |
Use when |
Completion criterion |
help |
Codex usage grammar or available skills is unclear |
A catalog or one usage card is returned without loading target procedure text. |
route |
One workflow owner must be selected |
A validated dhpk.route-result.v3 report names the target, availability, evidence, and next action. |
rules |
A phase or policy question needs the repository source of truth |
The applicable policy pointer and gates are reported; no downstream workflow starts. |
next |
Progression from the current worktree or change is unclear |
One next route is recommended from current evidence. |
close |
The edit boundary is complete and handoff readiness must be checked |
Changed files, required gates, open risks, and the handoff state are accounted for. |
Choose exactly one action. Load only the references named by that action, and
keep required, skipped, unavailable, and failed evidence distinct.
help
Run node ${CLAUDE_SKILL_DIR}/scripts/action-runner.js help or node ${CLAUDE_SKILL_DIR}/scripts/usage-card.js for the generated Codex catalog, or add one public skill name for a single usage card.
${CLAUDE_SKILL_DIR} is the directory containing this SKILL.md. Claude substitutes it in these commands and in allowed-tools. Hosts that do not substitute it, and references that write $SKILL_DIR, resolve that same directory. Keep the working directory on the consumer repository; do not cd into the package to inspect that repository.
Help is metadata only: it never invokes the named skill, loads procedural references, or grants workspace/Git/external-write authority.
Unknown and known non-Codex skill names receive different diagnostics.
route
- Parse the action query with
node ${CLAUDE_SKILL_DIR}/scripts/action-runner.js; its route branch
delegates to scripts/route-result.js.
- Match
references/route-table.json with bash ${CLAUDE_SKILL_DIR}/scripts/pre-route.sh; the
first precise match wins. A miss remains a deliberate-classification case. pre-route.sh may run Python internally; that child process is not a separate host pre-approval.
- Apply the selected policy kernel first
(
references/execution-bundle/rules/execution-policy-kernel.md), then only
the conditional section the route needs, and the target's invocation class.
- Without
--go, return advice only. With --go, produce at most one
bounded handoff for an available implicit-eligible target. An explicit-only
target is reported as explicit-required; it is never dispatched here.
- Validate and emit the closed
dhpk.route-result.v3 object. A route report
is not implementation, review, commit, merge, archive, release, or deploy
evidence.
The result has exactly schema, action, host, cleanedQuery, options,
target, availability, diagnostics, disposition, requiredEvidence, and
nextAction. options is exactly {go: boolean}. The target is either null or
{id, publicName, invocationClass, command}.
rules
Read the selected policy kernel first
(references/execution-bundle/rules/execution-policy-kernel.md). Load a
conditional section of
references/execution-bundle/rules/execution-policy.md only after the kernel
and only when the question needs that section. Listing a reference does not
load it. Resolve these paths through the installed Skill's existing per-Host
bundle (references/execution-bundle/).
Use references/execution-bundle/skills/flow-guide/references/invocation-precedence.md
when more than one owner appears to match, and load the phase-specific delivery
reference only after the phase is known.
Return the source pointer, applicable gate, and one next handoff.
next
Run node ${CLAUDE_SKILL_DIR}/scripts/action-runner.js next (which delegates to
the package-local analyzer) and parse its JSON. Report the
current branch/worktree evidence, each required or unavailable gate, and one
next route. A recorded passed value applies to the current change only when
its head equals the analyzer's current HEAD and, if the worktree differs
from HEAD, its diff (or scope.diff) equals the current diff identity.
The same HEAD alone does not prove an uncommitted diff is unchanged. Unbound,
stale, and scope-changed records stay readable and are not a current pass;
unobserved, failed, and skipped stay distinct. For next, pass --host codex-cli on Codex, --host cursor on Cursor, or --host agy on AGY; the omitted Host defaults to claude-code. Supported Host names match the shared handoff contract (claude-code, codex-cli, agy, cursor, claude, codex). The Host changes invocation formatting and handoff evidence only. If the script cannot run, record the fallback evidence and the
reason instead of treating the missing check as a pass.
When the request is an inbound issue with unsettled intent or acceptance, use
the bounded read-only intake in
references/execution-bundle/skills/flow-guide/references/premise-verification.md.
Settled specifications, approved tasks, and resumptions skip that intake and
continue from their existing evidence.
close
Account for changed files, TDD evidence when behavior changed, applicable
reviewers, triggered security/database/frontend/runtime checks, unresolved
risks, and the next handoff. Use references/handoff-and-verification.md only when its conditional detail is
needed. Never claim commit, merge, release, deployment, or archive completion
from a local closeout report.
The action runner emits a manual-evidence-required report for rules and
close; this is a pointer and evidence boundary, not a gate PASS.
Output
Action → Route or gate → Required evidence → PASS/FAIL/NOT NEEDED/BLOCKED → Next action
The report must name one action, one next route, and the evidence boundary.
route --go still ends at a handoff; the selected target owns its own
execution and completion evidence.
References
references/execution-bundle/ holds maintainer-synchronized policy copies; never edit them here.
The selected policy file defines its bundle base, and every required policy
resource resolves beneath it. Listing a reference does not load it. Runtime lookup is fail-closed and Skill-local:
missing resources report BLOCKED_RESOURCE_MISSING; no checkout, sibling Skill,
repository inventory, environment variable, or upward search is consulted.
references/route-table.json, references/route-result.schema.json,
scripts/pre-route.sh, scripts/route-result.js, and
scripts/action-runner.js — deterministic route contract and matcher.
references/execution-bundle/scripts/lib/flow-handoff-contract.js — shared
neutral handoff and evidence contract; it never grants execution authority.
scripts/usage-card.js and references/codex-usage-catalog.json —
progressively disclosed Codex grammar.
references/execution-bundle/skills/flow-guide/references/invocation-precedence.md — competing-owner resolution.
references/projects-index.md — project-specific policy references.
references/progression-tables.md — generated agent fallback for next; canonical frontmatter owns progression.
references/handoff-and-verification.md — conditional handoff evidence.
rules: load references/execution-bundle/skills/flow-guide/references/deterministic-first.md,
references/dispatch-and-gates.md, references/execution-bundle/skills/flow-guide/references/implementation-dispatch.md,
references/execution-bundle/skills/flow-guide/references/testing-policy.md, or references/execution-bundle/skills/flow-guide/references/component-addition-policy.md
only for the matching policy question; use
references/execution-bundle/skills/flow-guide/references/invocation-classification.md or references/codex-mode.md only
when invocation or Codex delegation is the disputed boundary.
next: after classification, choose at most one of
references/workflow-analysis.md, references/workflow-bugfix.md,
references/workflow-feature-delivery.md, or
references/workflow-lightweight.md. Load
references/task-modes.md, references/execution-bundle/skills/flow-guide/references/premise-verification.md,
references/work-item-and-gates.md, references/delivery-core.md, or
references/delivery-loop-gate.md only when that selected branch points to
it. Project overrides use references/profile-and-project-overrides.md and
references/projects-generic.md.
close: use references/output-shape.md, references/anti-loop.md, and
references/squash-merge-hygiene.md only for their named closeout checks.
references/workflow-checklists.md and references/script-operations.md
remain conditional detail, not initial context.
- Legacy deterministic helpers
scripts/openspec_gate_check.py,
scripts/prepare_dev_scope.py, scripts/prepare_workflow_profile.py, and
scripts/workflow_gate_check.py are run only when a selected rule or next
branch explicitly requires their existing input/output contract. They are not
pre-approved; an unlisted command uses the host's normal permission flow.
Verification
1---2name: flow-guide3argument-hint: '<help|route|rules|next|close> [--go] [--host <host>] [<query>]'4description: 'Read-only workflow guidance and bounded routing. Use when work needs a route, policy lookup, next action, closeout gate, or Codex usage help. Not for implementation, review, code tracing, or skill authoring. Output: one typed report with evidence and a clear handoff.'5allowed-tools: 'Read, Grep, Glob, Skill, Agent, Bash(node ${CLAUDE_SKILL_DIR}/scripts/action-runner.js:*), Bash(node ${CLAUDE_SKILL_DIR}/scripts/usage-card.js:*), Bash(bash ${CLAUDE_SKILL_DIR}/scripts/pre-route.sh:*)'6metadata:7 source: https://skillmd.com/skills/hmj1026/flow-guide8 dhpk-capability-id: dhpk.skill.flow-guide9 dhpk-name-style: portable-family10 dhpk-invocation-class: implicit-eligible11---1213# Flow Guide1415Use `$flow-guide <help|route|rules|next|close> [query]` to answer one workflow16question. The guide is advisory: it records evidence and hands work to the17owner through the shared neutral handoff contract; it does not acquire the18owner's authority.1920## When NOT to Use2122- Implementing a bounded task: invoke `$flow-drive <task-text|task-file|confirmed-spec-or-change-id>` directly.23- Reviewing a completed diff: use `change-verdict`.24- Tracing code or diagnosing a failure: use `code-trace`.2526## Actions2728| Action | Use when | Completion criterion |29| --- | --- | --- |30| `help` | Codex usage grammar or available skills is unclear | A catalog or one usage card is returned without loading target procedure text. |31| `route` | One workflow owner must be selected | A validated `dhpk.route-result.v3` report names the target, availability, evidence, and next action. |32| `rules` | A phase or policy question needs the repository source of truth | The applicable policy pointer and gates are reported; no downstream workflow starts. |33| `next` | Progression from the current worktree or change is unclear | One next route is recommended from current evidence. |34| `close` | The edit boundary is complete and handoff readiness must be checked | Changed files, required gates, open risks, and the handoff state are accounted for. |3536Choose exactly one action. Load only the references named by that action, and37keep required, skipped, unavailable, and failed evidence distinct.3839## `help`4041Run `node ${CLAUDE_SKILL_DIR}/scripts/action-runner.js help` or `node ${CLAUDE_SKILL_DIR}/scripts/usage-card.js` for the generated Codex catalog, or add one public skill name for a single usage card.42`${CLAUDE_SKILL_DIR}` is the directory containing this `SKILL.md`. Claude substitutes it in these commands and in `allowed-tools`. Hosts that do not substitute it, and references that write `$SKILL_DIR`, resolve that same directory. Keep the working directory on the consumer repository; do not `cd` into the package to inspect that repository.43Help is metadata only: it never invokes the named skill, loads procedural references, or grants workspace/Git/external-write authority.44Unknown and known non-Codex skill names receive different diagnostics.4546## `route`47481. Parse the action query with `node ${CLAUDE_SKILL_DIR}/scripts/action-runner.js`; its route branch49 delegates to `scripts/route-result.js`.502. Match `references/route-table.json` with `bash ${CLAUDE_SKILL_DIR}/scripts/pre-route.sh`; the51 first precise match wins. A miss remains a deliberate-classification case. `pre-route.sh` may run Python internally; that child process is not a separate host pre-approval.523. Apply the selected policy kernel first53 (`references/execution-bundle/rules/execution-policy-kernel.md`), then only54 the conditional section the route needs, and the target's invocation class.554. Without `--go`, return advice only. With `--go`, produce at most one56 bounded handoff for an available implicit-eligible target. An explicit-only57 target is reported as `explicit-required`; it is never dispatched here.585. Validate and emit the closed `dhpk.route-result.v3` object. A route report59 is not implementation, review, commit, merge, archive, release, or deploy60 evidence.6162The result has exactly `schema`, `action`, `host`, `cleanedQuery`, `options`,63`target`, `availability`, `diagnostics`, `disposition`, `requiredEvidence`, and64`nextAction`. `options` is exactly `{go: boolean}`. The target is either null or65`{id, publicName, invocationClass, command}`.6667## `rules`6869Read the selected policy kernel first70(`references/execution-bundle/rules/execution-policy-kernel.md`). Load a71conditional section of72`references/execution-bundle/rules/execution-policy.md` only after the kernel73and only when the question needs that section. Listing a reference does not74load it. Resolve these paths through the installed Skill's existing per-Host75bundle (`references/execution-bundle/`).76Use `references/execution-bundle/skills/flow-guide/references/invocation-precedence.md`77when more than one owner appears to match, and load the phase-specific delivery78reference only after the phase is known.79Return the source pointer, applicable gate, and one next handoff.8081## `next`8283Run `node ${CLAUDE_SKILL_DIR}/scripts/action-runner.js next` (which delegates to84the package-local analyzer) and parse its JSON. Report the85current branch/worktree evidence, each required or unavailable gate, and one86next route. A recorded `passed` value applies to the current change only when87its `head` equals the analyzer's current HEAD and, if the worktree differs88from HEAD, its `diff` (or `scope.diff`) equals the current diff identity.89The same HEAD alone does not prove an uncommitted diff is unchanged. Unbound,90stale, and scope-changed records stay readable and are not a current pass;91unobserved, failed, and skipped stay distinct. For `next`, pass `--host codex-cli` on Codex, `--host cursor` on Cursor, or `--host agy` on AGY; the omitted Host defaults to `claude-code`. Supported Host names match the shared handoff contract (`claude-code`, `codex-cli`, `agy`, `cursor`, `claude`, `codex`). The Host changes invocation formatting and handoff evidence only. If the script cannot run, record the fallback evidence and the92reason instead of treating the missing check as a pass.9394When the request is an inbound issue with unsettled intent or acceptance, use95the bounded read-only intake in96`references/execution-bundle/skills/flow-guide/references/premise-verification.md`.97Settled specifications, approved tasks, and resumptions skip that intake and98continue from their existing evidence.99100## `close`101102Account for changed files, TDD evidence when behavior changed, applicable103reviewers, triggered security/database/frontend/runtime checks, unresolved104risks, and the next handoff. Use `references/handoff-and-verification.md` only when its conditional detail is105needed. Never claim commit, merge, release, deployment, or archive completion106from a local closeout report.107108The action runner emits a `manual-evidence-required` report for `rules` and109`close`; this is a pointer and evidence boundary, not a gate PASS.110111## Output112113```text114Action → Route or gate → Required evidence → PASS/FAIL/NOT NEEDED/BLOCKED → Next action115```116117The report must name one action, one next route, and the evidence boundary.118`route --go` still ends at a handoff; the selected target owns its own119execution and completion evidence.120121## References122123`references/execution-bundle/` holds maintainer-synchronized policy copies; never edit them here.124The selected policy file defines its bundle base, and every required policy125resource resolves beneath it. Listing a reference does not load it. Runtime lookup is fail-closed and Skill-local:126missing resources report `BLOCKED_RESOURCE_MISSING`; no checkout, sibling Skill,127repository inventory, environment variable, or upward search is consulted.128129- `references/route-table.json`, `references/route-result.schema.json`,130 `scripts/pre-route.sh`, `scripts/route-result.js`, and131 `scripts/action-runner.js` — deterministic route contract and matcher.132- `references/execution-bundle/scripts/lib/flow-handoff-contract.js` — shared133 neutral handoff and evidence contract; it never grants execution authority.134- `scripts/usage-card.js` and `references/codex-usage-catalog.json` —135 progressively disclosed Codex grammar.136- `references/execution-bundle/skills/flow-guide/references/invocation-precedence.md` — competing-owner resolution.137- `references/projects-index.md` — project-specific policy references.138- `references/progression-tables.md` — generated agent fallback for `next`; canonical frontmatter owns progression.139- `references/handoff-and-verification.md` — conditional handoff evidence.140- `rules`: load `references/execution-bundle/skills/flow-guide/references/deterministic-first.md`,141 `references/dispatch-and-gates.md`, `references/execution-bundle/skills/flow-guide/references/implementation-dispatch.md`,142 `references/execution-bundle/skills/flow-guide/references/testing-policy.md`, or `references/execution-bundle/skills/flow-guide/references/component-addition-policy.md`143 only for the matching policy question; use144 `references/execution-bundle/skills/flow-guide/references/invocation-classification.md` or `references/codex-mode.md` only145 when invocation or Codex delegation is the disputed boundary.146- `next`: after classification, choose at most one of147 `references/workflow-analysis.md`, `references/workflow-bugfix.md`,148 `references/workflow-feature-delivery.md`, or149 `references/workflow-lightweight.md`. Load150 `references/task-modes.md`, `references/execution-bundle/skills/flow-guide/references/premise-verification.md`,151 `references/work-item-and-gates.md`, `references/delivery-core.md`, or152 `references/delivery-loop-gate.md` only when that selected branch points to153 it. Project overrides use `references/profile-and-project-overrides.md` and154 `references/projects-generic.md`.155- `close`: use `references/output-shape.md`, `references/anti-loop.md`, and156 `references/squash-merge-hygiene.md` only for their named closeout checks.157 `references/workflow-checklists.md` and `references/script-operations.md`158 remain conditional detail, not initial context.159- Legacy deterministic helpers `scripts/openspec_gate_check.py`,160 `scripts/prepare_dev_scope.py`, `scripts/prepare_workflow_profile.py`, and161 `scripts/workflow_gate_check.py` are run only when a selected rule or next162 branch explicitly requires their existing input/output contract. They are not163 pre-approved; an unlisted command uses the host's normal permission flow.164165## Verification166167- [ ] Exactly one action was selected and its completion criterion is met; only action-relevant references and scripts were loaded.168- [ ] Required, skipped, unavailable, and failed gates are distinct; a route report was validated as `dhpk.route-result.v3`.169- [ ] Raw issue intake ran only for unsettled intent, reused relevant170 discussion and decisions, and left tracker state unchanged.171- [ ] No target was executed and no target authority was inherited.