/next-step

name: next-step
description: "Names the one next step: make a game, change it after play, grow it, or the next studio-mode step. Use when asked what to do next, or stuck."
argument-hint: "[optional: what you just finished, e.g. 'finished design-review' or 'stuck on ADRs']"
user-invocable: true
allowed-tools: Read, Glob, Grep, Bash(bash "*/.claude/skills/next-step/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash "*/.claude/skills/next-step/../../scripts/story-status.sh"), Bash(bash .claude/scripts/story-status.sh*), Bash(bash .claude/scripts/artifact-check.sh *), Bash(bash ".claude/scripts/artifact-check.sh" *), Bash(bash ./.claude/scripts/artifact-check.sh *), Bash(git log *)
model: haiku

Next Step — What Do I Do Next?

This skill is read-only — it reports findings but writes no files.

This skill figures out where the project is and tells you the one thing to do next. The main path comes first: make a game (`/prototype`), change it after you play it, then grow it into a project you keep building. The stages below, with their design documents, agents, `team-*` pipelines and stage gates, are **studio mode**, the path at `workflow` `standard` or `full`. It is **lightweight** — not a full audit. For a full gap analysis, use `/project-stage-detect`.

Live Project State

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys project.stage,workflow`

These are resolved before this skill runs. Use them as-is:

• **`project.stage`** from the config block is the authoritative phase for Step 2

— it already applies the `project.yaml` → `production/stage.txt` fallback, and preserves values containing spaces (`Systems Design`).

• **`workflow`** from the config block is the tier for Steps 2 and 5 — do not re-read it.
• If no config block rendered, shell preprocessing is disabled; fall back to the

defaults in `.claude/docs/config-resolution.md`.

---

Step 1: Read the Catalog

Read `.claude/docs/workflow-catalog.yaml`. This is the authoritative list of all phases, their steps (in order), whether each step is required or optional, and the artifact globs that indicate completion.

---

Step 1b: Find Skills Not in the Catalog

After reading the catalog, list `.claude/skills/*/SKILL.md` to get the full list of installed skills. For each file, extract the `name:` field from its frontmatter.

Compare against the `command:` values in the catalog. Any skill whose name does not appear as a catalog command is an **uncataloged skill** — still usable but not part of the phase-gated workflow.

Collect these for the output in Step 7 — show them as a footer block:

### Also installed (not in workflow)
- `/skill-name` — [description from SKILL.md frontmatter]
- `/skill-name` — [description]

Only show this block if at least one uncataloged skill exists. Limit to the 10 most relevant based on the project's stage (QA skills in production, team skills in production/polish, etc.).

---

Step 2: Determine the Current Stage

**First, take `workflow` from the config block above.** If it is `minimal`, the project is on the minimal path, not the phase ladder: skip the rest of this step, read the session context (**Step 3**), then go to **Step 4m**. At that tier, do not map `project.stage` — nothing on the minimal path runs `/gate-check`, so the stage reads Concept however far the project has got, and walking the Concept stage would send a project that already has stories back to the concept doc, art bible and systems map.

Otherwise, check in this order:

1. **Take `project.stage` from the config block above** — it is already resolved. Map its value to a catalog phase key:

• "Concept" → `concept`
• "Systems Design" → `systems-design`
• "Technical Setup" → `technical-setup`
• "Pre-Production" → `pre-production`
• "Production" → `production`
• "Polish" → `polish`
• "Release" → `release`

2. **If neither is set**, infer phase from artifacts (most-advanced match wins):

• code root has 10+ source files → `production`
• `production/epics/**/story-*.md` exists → `pre-production`
• `docs/architecture/adr-*.md` exists → `technical-setup`
• `design/gdd/systems-index.md` exists → `systems-design`
• `design/gdd/game-concept.md` (or `design/game-brief.md`) exists → `concept`
• Nothing → `concept` (fresh project)

3. **`workflow`** was taken at the top of this step (per `.claude/docs/workflow-modes.md`). It controls whether optional docs are surfaced as next steps (Step 5).

---

Step 3: Read Session Context

Read `production/session-state/active.md` if it exists — but only its STATUS and CHECKPOINT blocks (schema: `.claude/docs/templates/session-state.md`); the narrative below them can be long. Find the markers (search `production/session-state/active.md` for `<!-- /?(STATUS|CHECKPOINT) -->`, with line numbers) and read from the first to the last. A file with no markers predates the schema: read its last `## Session Extract` block instead. Extract:

• What was most recently worked on
• Any in-progress tasks or open questions
• Current epic/feature/task from STATUS block (if present)

This tells you what the user just finished or is stuck on — use it to personalize the output. It runs at every tier: at `minimal` it is the only read of the checkpoint Step 4m relies on (a checkpoint saying "Next step: /story-done" means the work is written). From here, `minimal` goes to **Step 4m**, not Step 4.

---

Step 4: Check Step Completion for the Current Stage

For each step in the current stage (from the catalog):

Artifact-based checks

**Resolve these deterministically — one call, not a glob per step:**

bash .claude/scripts/artifact-check.sh --phase [current-phase]

Run it exactly as written, here and below: from the project root, with the relative path — no absolute path, no `cd`, no `2>&1`. This skill's permission grant matches that form; any other asks the user to approve it.

It evaluates every `glob`, `pattern`, `m