---
name: using-spec-first
description: "Use before substantial work in a spec-first project, and when users ask what spec-first workflow or command to run next. Decide whether to route into a public spec-first workflow before non-trivial or risky edits, running state-changing commands, debugging, reviewing, planning, setup, update, or architecture/prompt/workflow decisions."
---

# Using Spec-First

`using-spec-first` is the standalone meta skill and entry governor for `spec-first` in this repository. It decides whether the current request should enter a public `spec-first` workflow before the agent changes state.

It is not a command-backed workflow, slash command, or `$spec-*` workflow. It does **not** exist to force every task through brainstorming.

- Claude Code installs it as `.claude/skills/using-spec-first/SKILL.md` and also reads the managed block in `CLAUDE.md`; its SessionStart hook does not re-inject that block (CLAUDE.md already carries it) and instead emits a short pointer to the active governance plus any startup reminder.
- Codex installs it as `.agents/skills/using-spec-first/SKILL.md` and also reads the managed block in `AGENTS.md`; its SessionStart hook does not re-inject that block (AGENTS.md already carries it) and instead emits a short pointer to the active governance plus any startup reminder.

## Contract Summary

| Field | Contract |
| --- | --- |
| When to use | Before substantial work in a `spec-first` repo, and when the user asks what `spec-first` workflow or command to run next. |
| When not to use | Lightweight factual answers, narrow code-location questions, clearly scoped low-risk small edits, or work already governed by an active public workflow or bounded subagent task. |
| Inputs | Current user intent, host surface, available project instructions, minimal deterministic facts when already available, and this routing policy. |
| Outputs | Either one public workflow entrypoint with a concrete reason, User Next-Step Guide Mode output, or a direct answer/normal execution when no workflow applies. |
| Artifacts | None. `using-spec-first` does not create plans, task packs, review reports, setup reports, runtime assets, or durable knowledge. |
| Failure modes | Ambiguous WHAT/HOW, unclear target repo in a parent workspace, stale or missing runtime guidance, or a request that names an impossible/unsafe route. Ask one narrow question or route to the repair workflow instead of guessing. |
| Workflow | Read only enough facts to classify intent, apply explicit-route normalization and routing priority, announce the chosen route only when useful, then let the selected workflow own execution. |
| Downstream consumers | Public `$spec-*` / `/spec:*` workflows, standalone skills such as `spec-write-tasks`, and human users asking for the next step. |

Core boundary: scripts and CLI commands prepare deterministic facts; the LLM decides the workflow recommendation. This governor must not fabricate command results, infer runtime readiness without evidence, or replace downstream workflow judgment with a local routing checklist.

## Examples As Context

When editing or reviewing this routing prompt, or when running fresh-source eval for routing posture drift, read `skills/using-spec-first/evals/examples.json` as examples-as-context. These examples are not a routing state machine, automatic workflow selector, or semantic readiness gate for ordinary requests.

For lightweight-route regressions, also read `skills/using-spec-first/evals/routing-cases.json`. These cases are machine-judgable guardrails for direct-answer, bounded-read, and explicit-route outcomes; they are not a deterministic router or a replacement for LLM judgment.

For routing-discipline regressions, read `skills/using-spec-first/evals/routing-discipline-cases.json`. These cases target multi-intent conflict, automatic chaining pressure, standalone/internal helper confusion, dispatch authorization, parent-workspace write scope, and setup-hijack boundaries; they are structural output-eval fixtures, not a runtime router.

## Reference Files

Keep this `SKILL.md` focused on trigger, output, and branch-selection posture. Read references only when their boundary is directly relevant:

- `skills/using-spec-first/references/scenario-fingerprint-routing.md`: when `.spec-first/workspace/scenario-fingerprint*.json` already exists or setup/workspace state affects route trust.
- `skills/using-spec-first/references/user-next-step-guide-mode.md`: when the user asks what to run next, which workflow applies, or asks for guide-only output.
- `skills/using-spec-first/references/multi-session-awareness.md`: before substantial file-writing work when opt-in session records may affect coordination disclosure.
- `skills/using-spec-first/references/codex-startup-reminder-boundary.md`: before a top-level Codex orchestrator enters a public `$spec-*` workflow and startup reminder evidence may be relevant.
- `skills/using-spec-first/references/routing-red-flags.md`: when editing or reviewing routing posture and anti-rationalization reminders.
- `skills/using-spec-first/references/output-risk-profile.md`: when editing, reviewing, or evaluating this routing skill; it names likely output failures and matching checks.
- `skills/using-spec-first/references/maintenance-and-fresh-source-eval.md`: when changing this skill, host bootstrap prose, dispatch boundaries, route map entries, or source/runtime guidance.

## Source Of Truth And Runtime Surface

`skills/using-spec-first/SKILL.md` is the source-of-truth routing policy.

The managed bootstrap blocks in `CLAUDE.md` and `AGENTS.md` are the using-spec-first minimal entry anchors, generated by `spec-first init` after choosing the target host and injected at session start. They carry only the load-bearing admission and boundary reminders that must be present before any deeper read: substantial-work workflow check, direct-answer allowance, active-workflow/subagent non-reroute, target repo write boundary, runtime/generated mirror exclusion, source pointer, internal-helper non-exposure, current-host entrypoint spelling, and a small set of common entry anchors. The full Route Map, routing priority, examples, edge cases, and dispatch boundaries live in this SKILL. Tests keep the bootstrap as a faithful core subset and explicitly prevent it from becoming a second complete route table.

Runtime copies under `.claude/`, `.codex/`, and `.agents/skills/` are generated mirrors. Repair stale or missing runtime guidance with `spec-first init` after choosing the target host; do not hand-edit generated mirrors as the source of truth.

Ordinary context routing follows `docs/contracts/context-governance.md`: `.spec-first/audits/**`, `.spec-first/governance/**`, and generated mirrors (`.claude/**`, `.codex/**`, `.agents/skills/**`) are excluded from default workflow context. Route to setup/update/runtime-drift/audit/governance-health workflows, or require a precise user-named path, before treating those directories as evidence.

## Scope Guards

### If You Are Already In A Workflow

If a public `spec-first` workflow is already active, do not restart entry routing on every step. Follow the active workflow's `SKILL.md`.

Re-run entry routing only when the user changes the goal, the active workflow explicitly hands off, or the current request is clearly outside the active workflow's scope.

### If You Are A Subagent

If you were dispatched as a subagent or worker for a specific bounded task, do not restart workflow routing unless the parent explicitly asked you to choose a workflow. Complete the assigned task within its scope and report back.

### What Counts as Substantial Work

Treat these as substantial work:

- non-trivial or risky edits that need an engineering loop: multi-file changes, architecture or contract changes, governance/runtime delivery changes, unclear root cause, sensitive areas, or changes likely to require planning, debugging, review, or migration judgment
- starting implementation, debugging, review, planning, setup, update, bootstrap, optimization, or context-capture workflows
- running commands that change project state or depend on workflow context
- making architectural, prompt, workflow, governance, or contract decisions
- creating, refreshing, or retiring durable project knowledge

These are not substantial work:

- lightweight factual answers
- brief explanations with no workflow leverage
- quick questions where `spec-first` provides no meaningful routing benefit
- showing command output or answering a narrow "where is X used?" question without edits
- clearly scoped, single-point, low-risk code/prose/config edits such as a typo, comment, constant, or local single-function fix, provided the root cause and target file are clear and no architecture, contract, governance, runtime delivery, multi-file, or sensitive-surface judgment is needed

### Lightweight Direct Outcomes

`using-spec-first` has valid non-workflow outcomes. When the current request is lightweight, answer directly or perform a bounded read instead of creating a public workflow artifact.

Direct-answer / bounded-read cases include greetings, current-context or current-instruction explanations, narrow code-location lookups such as "where is X used?", and summarizing or reorganizing the current conversation or a user-provided single document. These requests may still use ordinary source tools such as `rg` or precise file reads when needed, but they do not require brainstorm, plan, work, review, Graphify, or durable artifacts by default.

Clearly scoped small edits may also proceed as normal execution without opening a public workflow. Direct execution still carries the local engineering discipline: update `CHANGELOG.md` when project policy requires it, use the narrowest meaningful verification, respect source/runtime boundaries, and avoid generated mirror patches as source fixes.

If a lightweight request turns into non-trivial or risky editing, planning, review, debugging, setup, source/runtime judgment, multi-file spread, unclear root cause, or another substantial state-changing action, reclassify it at that point and route normally.

### Spec-First Self-Work

Work on `spec-first` itself is substantial when it changes skills, agents, prompt/workflow prose, host instruction blocks, `init`/`doctor`/`clean` behavior, governance contracts, architecture, source/runtime policy, or runtime delivery rules.

Before self-work that changes architecture, prompt, workflow, contract, source/runtime governance, or evolution policy, read `docs/10-prompt/结构化项目角色契约.md` and use it as the judgment baseline.

Clearly scoped, single-point, low-risk ordinary code/prose corrections in `spec-first` itself may proceed directly when they do not touch prompt/workflow/contract/governance/runtime delivery semantics and do not expand beyond the known target. Keep the same local discipline: source-of-truth edits, `CHANGELOG.md` when required, narrow verification, and reclassification if the change becomes substantial.

Route substantial concrete implementation or prose changes to:

- Claude: `/spec:work`
- Codex: `$spec-work`

Route unresolved policy, architecture, or scope questions to `spec-brainstorm` or `spec-plan` based on whether the WHAT or HOW is unclear. Route review-only requests by artifact type: code/diff/PR quality review to `spec-code-review`, requirements/plan/Markdown review to `spec-doc-review`, and skill/agent asset governance audits to `spec-skill-audit`. If the request asks for review plus concrete revisions, route to work and keep a review posture during execution.

For source changes, update source-of-truth files, the narrowest contract tests, and `CHANGELOG.md` when project policy requires it. Keep changelog entries compact and consume changelog history through the latest relevant window / summary-first rules in `docs/contracts/context-governance.md`. Do not modify generated `.claude/`, `.codex/`, or `.agents/skills/` mirrors just to refresh runtime behavior. If runtime drift must be repaired after source validation, use `spec-first init` with the target host selected as a runtime regeneration step, not as the source fix.

## Multi-Session Awareness

Before substantial work that will write files, optionally check whether other agent sessions are currently active in the same worktree. This disclosure is advisory only, never a hard gate, and it uses the opt-in protocol in `docs/contracts/sessions/spec-first-session.md`.

```bash
spec-first session list --json
```

If `active_count >= 2`, emit one short advisory line naming the count and a concrete next-action choice. Do not block, do not lock, do not auto-defer — the LLM decides whether to proceed in parallel with disclosure or to coordinate. For active_count interpretation, missing-command behavior, wording examples, and subagent/headless exclusions, read `skills/using-spec-first/references/multi-session-awareness.md`.

## Decision Output Contract

Do not route by keyword alone. The user's immediate intent beats broad subject area.

When routing is needed, state the chosen entrypoint and one concrete reason, then proceed through that workflow. Do not recite the full decision tree.

When no workflow meaningfully applies, say so briefly only if useful, then answer directly or execute normally.

If the user explicitly invokes a workflow (`/spec:*` or `$spec-*`), honor that route unless it is clearly impossible or unsafe. If the user names a standalone skill, use that skill only when its own scope fits; do not convert it into public workflow admission.

If the user asks only for guidance about the next step, use User Next-Step Guide Mode instead of starting the workflow. If the user directly describes clear work, normal entry routing may announce the chosen workflow and continue under this contract.

## Skill Trigger vs Workflow Admission

A skill trigger is source/methodology loading; it is not automatically public workflow admission. Reading this SKILL, loading an examples file, or matching a skill description can help classify the request while still producing a direct answer, bounded read, or normal execution when no public workflow adds value.

Public workflow admission happens only when the current intent actually matches a public `/spec:*` or `$spec-*` workflow, or the user explicitly invokes one and the route is safe. Admission to a workflow authorizes that workflow to run under its own contract; it does not create a plan/task/review artifact inside this governor and does not grant host-level subagent dispatch beyond the dispatch rules below.

## User Next-Step Guide Mode

Use this mode when the user explicitly asks what to run next, which `spec-first` command to use, which workflow applies, or says they do not know the next step.

This mode is read-only. It may inspect lightweight context that is already available, but it must not create brainstorm, plan, task, review, solution, or runtime artifacts. It recommends the next public workflow entrypoint; the selected workflow performs the actual work.

Output exactly one best next entrypoint, one concrete reason, and one next action. Do not print the full workflow menu.

Use a compact, user-visible shape so the answer is easy to scan:

```text
推荐入口: <current-host entrypoint>
理由: <one concrete reason>
下一步: <one action the user can take now>
```

In English-language repos, use `Recommended entrypoint`, `Reason`, and `Next action`. Do not start the selected workflow from guide mode unless the user explicitly asks to continue with that workflow. For confidence rules, post-workflow "what next?" handling, and after-init setup tie-breaks, read `skills/using-spec-first/references/user-next-step-guide-mode.md`.

## Scenario Fingerprint Routing

When `.spec-first/workspace/scenario-fingerprint.json` or `.spec-first/workspace/scenario-fingerprint-setup.json` is already present, treat it as advisory deterministic context for guide mode and entry routing. Do not run setup, clean, external-tool commands, or runtime regeneration just to create a fingerprint from this entry governor.

Scenario fingerprints are not gates, approvals, or source scope authority. Route output still remains one entrypoint, one reason, and one next action. For layer priority, missing-artifact compatibility, scenario-aware checks, and foreign residual repair wording, read `skills/using-spec-first/references/scenario-fingerprint-routing.md`.

## Routing Rules

Use a decision tree, not a blanket "brainstorm first" rule. Pick the first strongly matching route. If multiple routes apply, choose the workflow that best matches the user's immediate intent.

### Explicit Route Normalization

If the user names a current-host public workflow, honor that explicit route unless it is clearly impossible or unsafe.

If the user names the other host's equivalent public workflow, translate it to the current host entrypoint and state the normalization. For example, Codex should translate `/spec:work` to `$spec-work`; Claude should translate `$spec-work` to `/spec:work`.

If the user names a standalone skill rather than a public workflow, invoke that skill only when its scope fits. Do not invent a `/spec:*` or `$spec-*` command for standalone skills such as `using-spec-first` or `spec-write-tasks`.

### Routing Priority

1. Explicit user route.
2. Safety/repair routes: setup, update, missing runtime assets, broken host readiness.
3. Diagnostic routes: debug before work when the request is about a failure.
4. Evaluation routes: code/doc review before implementation when the user asks for review.
5. Definition routes: ideate/brainstorm before plan/work when the outcome is still unclear; use the PRD workflow for brownfield PRD-grade requirements when existing product/system shape is already anchored.
6. Optimization routes: metric-driven experiments before ordinary work when the user asks to optimize a measurable outcome.
7. Execution routes: plan before work when the desired outcome is clear but the implementation path is not.
8. Knowledge routes: compound/compound-refresh after or around completed work.

Do not chain multiple workflows automatically unless the active workflow or skill explicitly hands off. Route to the next best workflow and let that workflow govern its own handoff. A standalone skill may perform one bounded, documented continuation when its own contract defines that edge (for example `spec-write-tasks` continuing into document review for a high-risk task pack); this is not general multi-workflow chaining.

PRD/readiness tie-break: independent critique of a requirements, plan, task, or Markdown artifact routes to document review. Brownfield PRD authoring/refinement, current-state/code-aware PRD validation, and "can this PRD go to planning without inventing WHAT?" route to the PRD workflow.

### Route Map

| Intent | Claude | Codex |
| --- | --- | --- |
| environment setup, host setup, MCP setup, missing tools, host readiness, project-local setup | `/spec:mcp-setup` | `$spec-mcp-setup` |
| check/update spec-first, refresh generated runtime assets, or repair stale `/spec:*` / `$spec-*` entries | run `spec-first update` in the terminal | run `spec-first update` in the terminal |
| retrieve past coding-agent sessions or ask what happened in prior work | `/spec:sessions` | `$spec-sessions` |
| Slack or organizational discussion context | `/spec:slack-research` | `$spec-slack-research` |
| existing bug, failure, test failure, stack trace, or abnormal behavior to reproduce or diagnose | `/spec:debug` | `$spec-debug` |
| code review, PR review, diff audit, or implementation-quality evaluation | `/spec:code-review` | `$spec-code-review` |
| requirements, plan, spec, or markdown document review | `/spec:doc-review` | `$spec-doc-review` |
| audit spec-first skill/agent assets for engineering quality, boundary, or governance issues | `/spec:skill-audit` | `$spec-skill-audit` |
| audit app/PRD-to-implementation consistency or drift across the project | `/spec:app-consistency-audit` | `$spec-app-consistency-audit` |
| 0-1 product idea, asking what to build, wants ideas, or asks for options/surprising improvements without a concrete feature | `/spec:ideate` | `$spec-ideate` |
| still defining WHAT to build, unclear problem frame, or product decisions before planning | `/spec:brainstorm` or `/spec:ideate` | `$spec-brainstorm` or `$spec-ideate` |
| brownfield PRD authoring, existing PRD refinement, or code-aware PRD validation for an existing system increment | `/spec:prd` | `$spec-prd` |
| optimize a measurable outcome through experiments | `/spec:optimize` | `$spec-optimize` |
| clear desired outcome but needs an execution plan | `/spec:plan` | `$spec-plan` |
| split a settled plan into executable tasks or compile task docs before work | `spec-write-tasks` standalone skill | `spec-write-tasks` standalone skill |
| existing plan, task pack, or implementation task clear enough to execute | `/spec:work` | `$spec-work` |
| polish a browser-visible UI and iterate with a running app | `/spec:polish-beta` | `$spec-polish-beta` |
| capture a recently solved problem or compound knowledge after work | `/spec:compound` | `$spec-compound` |
| refresh, correct, merge, replace, or retire existing durable docs/learnings/pattern docs | `/spec:compound-refresh` | `$spec-compound-refresh` |
| recent spec-first release notes | `/spec:release-notes` | `$spec-release-notes` |

`spec-write-tasks` is not a `/spec:*` or `$spec-*` workflow entrypoint. Ordinary execution-ready work routes to the stable work entrypoint.

If none of the above applies, do not force the request into `spec-first`.

### Parent Workspace Direct Reads

If the user asks a read-only codebase question from a parent workspace containing multiple child Git repos, do not force a workflow only because there are multiple repos. Use bounded direct reads in the likely child repo candidates and state the target-repo assumption. If the request asks for planning, writing, fixing, testing, changelog updates, review autofix, or commits, route normally but require explicit `target_repo` / per-child scope before any repo-local write.

## Dispatch And Host Boundaries

### Workflow Dispatch Admission

Routing into a public workflow authorizes that workflow to run. It does not by itself override host-level subagent tool contracts. In Codex, call `spawn_agent` only when the current request explicitly asks for subagents, delegated work, parallel agents, persona reviewer dispatch, or when an upstream workflow delegates from an already authorized multi-agent context whose visible parent request or handoff evidence includes explicit subagent/delegation/parallel/persona wording.

Some public workflows prefer multi-persona or research phases when host capability and authorization are both present, for example `$spec-doc-review` multi-persona document reviewers, `$spec-code-review` reviewer personas, `$spec-plan` research agents, and `$spec-ideate` grounding or ideation agents. If authorization is absent, use that workflow's documented single-agent/report-only or inline-checklist fallback and record the concrete fallback reason instead of treating the workflow itself as failed.

When Codex fallback is caused by missing dispatch authorization, record `dispatch_authorization_missing` and make the opt-in path user-visible: for multi-persona or subagent review, ask for `subagents`, `personas`, delegated review, or parallel agents in the request.

If the user names `spec-doc-review` in a document-review request without the `$` prefix, normalize it to the current host's public document-review entrypoint when the intent is clearly to run that workflow. Do not invent extra dispatch authorization from normalization; the selected workflow owns reviewer selection, bounded parallelism when authorized, synthesis, artifacts, fallback, and final judgment.

If the user explicitly asks for report-only/no-agents mode, the host lacks a dispatch primitive, the runtime cannot call it, explicit dispatch authorization is absent, or the workflow's own safety boundary is not satisfied, follow that workflow's documented fallback instead of dispatching.

### Host Surface

- Claude workflow entrypoints use `/spec:*`.
- Codex workflow entrypoints use `$spec-*`.
- In Codex, `$spec-doc-review` means the document-review workflow. It uses bounded reviewer dispatch only when the current request also satisfies Codex `spawn_agent` authorization; otherwise it follows the documented fallback.
- `using-spec-first` itself is a standalone meta skill, not a `/spec:*` or `$spec-*` workflow entrypoint.
- `spec-write-tasks` is a standalone skill for optional plan-to-task-pack compilation, not a `/spec:*` or `$spec-*` workflow entrypoint.
- Internal-only skills remain source/runtime support assets, not menu items. Do not recommend them as public workflow paths.

### Codex Startup Reminder Boundary

Codex currently uses managed instruction guidance for startup reminders, not a verified deterministic SessionStart hook.

When a top-level Codex orchestrator is about to route into a public `$spec-*` workflow and the `spec-first` CLI is available, it may run:

```bash
spec-first startup-reminder --codex
```

This is a read-only best-effort check. Missing CLI, command failure, network failure, empty output, or malformed local state must be ignored and must not block workflow routing. Bounded subagents, leaf reviewers, and worker agents must not run the startup reminder. For reminder surfacing, version-update wording, and cooldown-state boundaries, read `skills/using-spec-first/references/codex-startup-reminder-boundary.md`.

### Injection Behavior

If this guidance has already been injected through `CLAUDE.md`, `AGENTS.md`, or Claude SessionStart:

- do not reload or invoke `using-spec-first` just to bootstrap yourself
- use the appropriate public `/spec:*` or `$spec-*` workflow entrypoint when routing is needed
- treat `skills/using-spec-first/SKILL.md` as the source-of-truth text for this routing policy
- if the installed instruction block or standalone meta skill is missing or stale, the repair path is `spec-first init` with the target host selected

## Hard Rules

1. `workflow-first` does not mean `brainstorming-first`.
2. Do **not** make `spec-brainstorm` the universal default front door.
3. Do **not** adopt the `using-superpowers` rule that "if there is a 1% chance a skill applies, you must invoke it."
4. Do **not** turn ordinary lightweight requests into mandatory workflow traffic.
5. Do **not** describe `using-spec-first` itself as a command-backed workflow.
6. Do **not** write Codex entrypoints as `/spec:*`.
7. Do **not** write Claude workflow entrypoints as `$spec-*`.
8. Do **not** expose internal-only skills as user entrypoints. This includes delegated helpers such as `git-worktree`.
9. Do **not** route to hidden helper skills such as git, browser, image, proof, xcode, or bug-report helpers unless a public workflow explicitly delegates to them.
10. Do **not** run `spec-first init`, `clean`, update, or other state-changing commands just because this governor matched; first route to the appropriate workflow or ask a narrow confirmation when required.

## Routing Red Flags

Anti-rationalization reminders are advisory, not a deterministic router. Direct editing is fine for clearly scoped, low-risk small edits; stop and route when scope/risk is unclear, root cause is unresolved, or the change touches architecture, contracts, governance, runtime delivery, multi-file behavior, or sensitive surfaces. For the full red-flag table, read `skills/using-spec-first/references/routing-red-flags.md`.

## Artifact And Evidence Boundaries

`using-spec-first` governs **entry routing only**. It does not create plans, task packs, review reports, setup reports, or durable knowledge. It only decides entry routing or gives a next-step recommendation.

Scripts and CLI commands may prepare deterministic facts for downstream workflows. This skill should not ask the agent to fabricate command results, infer runtime readiness without evidence, or replace downstream workflow judgment with a local routing checklist.

When a workflow is selected, that workflow owns its artifacts, validation evidence, and final judgment. Do not use this governor to create pseudo-plan, pseudo-task, or pseudo-review artifacts.

## Exit Condition

If no `spec-first` workflow meaningfully applies, answer directly or perform the normal task without forcing workflow indirection.