---
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 editing files, 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, 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.

## 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:

- modifying code, docs, config, or generated runtime assets
- 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

### 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.

If a lightweight request turns into editing, planning, review, debugging, setup, source/runtime judgment, or another 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, 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.

Route 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. The check is read-only and uses the opt-in advisory protocol defined in `docs/contracts/sessions/spec-first-session.md`:

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

If `active_count` is 0 or the command returns "0 active", proceed normally — single-actor mode is the default and this disclosure is not needed.

If `active_count >= 2`, emit one short advisory line in the user-facing response before continuing, naming the count and one 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. Examples of valid advisory phrasing:

- "另一个 session 正在 work；继续即可，写入冲突会被 `concurrent-write-detected` 兜住，或者用 `git-worktree` 隔离开。"
- "Detected 2 active sessions in this worktree. Proceeding; consider `spec-first session register` for visibility, or use a separate `git-worktree` to isolate."

`spec-first session list` returning a non-zero exit, missing binary, missing `.spec-first/sessions/` directory, or an empty list are all equivalent to single-actor mode. Do not derive judgment from the absence of session records — register is opt-in. Do not invent fallback heuristics from `git status --porcelain` external-mtime patterns; that belongs to the writer-side fingerprint detection, not to guide-mode disclosure.

This disclosure is **never** a hard gate. It does not run as part of headless / autofix / programmatic flows where the response shape is fixed. It is also unnecessary when this skill is being invoked from inside a bounded subagent that has already accepted the parent's scope.

## 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 repositories whose active `CLAUDE.md` / `AGENTS.md` `spec-first:lang` block sets English, use the same three fields as `Recommended entrypoint`, `Reason`, and `Next action`. The next action should be a copy-ready workflow invocation or a short continuation phrase such as "reply `continue` to run it now". Do not start the selected workflow from guide mode unless the user explicitly asks to continue with that workflow.

Use the Routing Priority and Routing Rules below as the source of truth. Use the exact current-host public entrypoint those rules select.

High-confidence guide cases may recommend without confirmation after naming the chosen route:

- clear failures, stack traces, or test failures -> debug
- clear code, PR, diff, requirements, plan, or markdown review requests -> code review or doc review based on the artifact
- clear setup, host readiness, MCP, update, or runtime repair requests -> setup or update based on the repair target
- existing plan, task pack, or implementation-ready task -> work

Low-confidence cases need one narrow confirmation before routing:

- idea generation vs requirement shaping vs execution planning is unclear
- a change could be either a bug fix or a product behavior change
- the user may need a durable artifact, but it is not clear whether that artifact should be requirements, a plan, tasks, or review notes
- a workflow just finished, but its handoff context is unavailable or conflicts with the new request

When the user asks "what next?" after a workflow:

- If an active workflow has an explicit handoff, follow that workflow's handoff.
- If a brainstorm requirements document exists and implementation direction is not yet planned, recommend plan.
- If a plan or validated task pack exists and the work is implementation-ready, recommend work.
- If there is an existing diff and the user asks whether it is ready, recommend code review or doc review based on the artifact.
- After init, prefer setup/readiness guidance only when the user asks about setup/readiness, missing runtime assets, MCP setup, or a workflow is blocked by unavailable tools.
- After init, when runtime or MCP readiness is unresolved but the user has a clear lightweight docs, small-code, plan, work, or review goal, route by that goal and require the selected workflow to disclose degraded setup/MCP evidence when relevant.

## 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. Prefer the bootstrap layer (`developer-scenario-fingerprint.v1`) over the setup layer (`developer-scenario-fingerprint-setup.v1`). If only the setup layer exists, use it with the limitation that bootstrap-only fields are unavailable. 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. Read their independent dimensions and scenario class as routing evidence for the current user intent; do not collapse them into a single risk score. The route output still remains one entrypoint, one reason, and one next action.

Use this compatibility rule before the priority checks:

- If the fingerprint is missing and setup artifacts exist, add one advisory line that rerunning `$spec-mcp-setup` / `/spec:mcp-setup` will refresh the workspace scenario fingerprint, then continue normal routing by user intent.
- If the fingerprint is missing and no setup artifacts exist, recommend `$spec-mcp-setup` / `/spec:mcp-setup` for setup/readiness or "what next?" requests. For clearly lightweight work, route by intent and mention missing scenario evidence only when it affects trust in setup/MCP facts.

Apply these scenario-aware checks in priority order, then fall back to the ordinary Routing Rules:

1. `state_class=foreign-residual-workspace` or non-empty `foreign_residual_indicators[]`: route to the current repair owner before downstream work. Recommend `spec-first clean --workspace-orphans` as the preview-first inspection step, then `spec-first clean --workspace-orphans --confirm` only when the user explicitly wants to delete the quarantined parent artifacts; pair cleanup with `spec-first init` or `$spec-mcp-setup` / `/spec:mcp-setup` when setup facts or generated runtime guidance must be refreshed.
2. `state_class=first-time-git-repo`: recommend `$spec-mcp-setup` / `/spec:mcp-setup` when the user is asking for setup/readiness or wants durable setup facts before downstream work.
3. `complexity_dimensions.git_alignment_broken=true` and the user is asking for impact analysis, review, refactor, or cross-module reasoning: disclose the coverage blind spot and prefer bounded direct reads; do not claim full workspace coverage.
4. `complexity_dimensions.worktree_dirty_source_affecting=true` and the user is asking for commit, PR, review, or impact: mention the bounded dirty path sample when present and ask the selected downstream workflow to disclose dirty evidence.
5. None of the above: route normally by the user's immediate intent.

If `freshness.stale_setup_layer=true`, add one advisory line recommending rerunning `$spec-mcp-setup` / `/spec:mcp-setup`; do not block ordinary routing solely for stale setup-layer evidence.

## 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. Legacy/internal `lfg` must not be recommended as a public workflow path.

### 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.

If the command prints a reminder, surface that reminder and continue routing. Version reminders point to running `spec-first update` in the terminal, where the user decides whether to upgrade; they must not install packages, refresh runtime assets, or restart Codex.

Bounded subagents, leaf reviewers, and worker agents must not run the startup reminder or write reminder cooldown state. They inherit the parent task scope.

### 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 legacy/internal `lfg` and 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

| Thought | Better move |
| --- | --- |
| "I'll just edit the file first." | Check whether this is `work`, `debug`, `update`, or `compound-refresh`. |
| "This is just a quick architecture/prompt change." | Treat architecture, prompt, workflow, and contract changes as substantial work. |
| "I need to inspect a bunch of files before deciding." | Do a minimal fact check only; route if the request is already clearly review/debug/plan/work. |
| "The user asked for a review, but I can answer informally." | Use `code-review` or `doc-review` when the review target is concrete. |
| "The task is vague, but I can probably implement something." | Use `brainstorm` or `plan` before work. |
| "A helper skill exists, so I should expose it." | Only public workflows are user entrypoints; internal helpers stay hidden. |
| "I should run init/update now." | Route to `update` or `setup` first unless the user explicitly requested the command. |

## 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.
