agentleFS
DonchitosDonchitos/Claude-Code-Game-Studios/.claude/skills/next-step/SKILL.md

next-step

Skill39k starsChanged 7 days agoMITView on GitHub

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.

13 other projects use a version of this.

Adopted by

Steady: 0 new projects took it in the last 4 weeks, none the 4 weeks before.thin data

Week of Sep 20: 0 new projectsWeek of Sep 27: 0 new projectsWeek of Oct 4: 0 new projectsWeek of Oct 11: 0 new projectsWeek of Oct 18: 0 new projectsWeek of Oct 25: 0 new projectsWeek of Nov 1: 0 new projectsWeek of Nov 8: 0 new projects
Sep 2026Oct 2026Nov 2026
New projects taking a version of this file each week, over the 8 weeks our latest run read: only 0 in all, so this is a hint, not a trend.

Most recently taken up by

Who's talking about Donchitos/Claude-Code-Game-Studios

The biggest 5 of 35 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 35

Talked about on YouTube and Bluesky (35 times).

On YouTube · 23

18 more on YouTube

On Bluesky · 12

7 more on Bluesky

Used with

Projects with it also use simplify and interview.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • Hugging FaceSkill

    simplify

    Refactor code after tests pass. The "Refactor" phase of Red-Green-Refactor.

    Also in 3 projects that use this

  • dazuckSkill

    interview

    Interview me about a plan to flesh out requirements before implementation. Asks non-obvious questions one at a time until all ambiguities are resolved.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

25 rules. 0 are common, 9 are distinctive, and 16 are very specific to this project.

  • 0

    Common

    Most of the 10 edited versions we read keep these.

  • 9

    Distinctive

    This author's own choices. Worth a look.

  • 16

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If no config block rendered, shell preprocessing is disabled.

    line 31
  2. Very specific:

    Read .claude/docs/workflow-catalog.yaml.

    line 38
  3. Very specific:

    After reading the catalog, list .claude/skills/*/SKILL.md to get the full list of installed skills.

    line 46
  4. Distinctive:

    Only show this block if at least one uncataloged skill exists.

    line 61
  5. Very specific:

    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 …

    line 69
  6. Very specific:

    Read production/session-state/active.md if it exists — but only its STATUS and CHECKPOINT blocks (schema: …

    line 104
  7. Very specific:

    Run it exactly as written, here and below: from the project root, with the relative path — no absolute path, no cd, no 2>&1.

    line 133
  8. Very specific:

    Do not re-derive any of this by searching the files yourself.

    line 148
  9. Very specific:

    When the current stage is production, check for production/sprint-status.yaml before doing any glob-based story checks.

    line 161
  10. Very specific:

    When the person asks for a change to a made game, or says they love or hate it, → Next up is /prototype with their words, whatever else …

    line 204
  11. Very specific:

    no match, and the code root holds fewer than 10 source files → no game yet: → Next up is /prototype (make a game you can play), with …

    line 210
  12. Very specific:

    no match, and 10 or more source files → /setup-engine, as before

    line 216
  13. Distinctive:

    Every one of them still runs if the user asks for it.

    line 301
  14. Distinctive:

    If the user provided an argument (e.g.

    line 324
  15. Very specific:

    A design with nothing to play: When design/gdd/ holds a .md file and Glob finds no prototypes/*/index.html, check engine.name in …

    line 327
  16. Very specific:

    No engine set, or web: → Next up is a playable first, /prototype built from their concept doc (/prototype design/gdd/game-concept.md.

    line 330
  17. Very specific:

    If active.md shows an active task or epic:

    line 344
  18. Distinctive:

    Keep it short and direct. This is a quick orientation, not a report.

    line 352
  19. Very specific:

    At minimal: use this shape instead — no phase label, no gate line.

    line 382
  20. Distinctive:

    If a step has no command (e.g.

    line 415
  21. Distinctive:

    After the current stage's steps, check if the user is likely approaching a gate:

    line 426
  22. Very specific:

    If all required steps in the current stage are complete (or nearly complete), add: "You're close to the [Current] → [Next] gate.

    line 427
  23. Distinctive:

    If multiple required steps remain, skip the gate warning — it's not relevant yet.

    line 429
  24. Distinctive:

    After the recommendations, if the user seems stuck or confused, add:

    line 435
  25. Distinctive:

    Only show this if the user's input suggested confusion (e.g.

    line 451

“Common” is measured: kept by at least 6 in 10 of the 10 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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, min_count and any_of in the catalog against the working tree and reports one line per step. Map its statuses:

statusReport as
PRESENTComplete
ABSENTIncomplete
SHORTIncomplete — say how far short (count=/min= are given)
PATTERN_MISSIncomplete — the file exists but lacks its marker; say so, since "missing" would send the user to recreate a file they already have
NO_CHECKMANUAL if the step carries a note=, else UNKNOWN — completion is not trackable (e.g. repeatable implementation work)

Do not re-derive any of this by searching the files yourself. any_of in particular is a list of alternatives — one match is enough — and hand-evaluating it risks a false "incomplete": engine-setup is satisfied by engine.name in project.yaml or by the legacy Engine: line in .claude/docs/technical-preferences.md, and the script reports which alternative matched (alt=/match=).

NO_CHECK never means done. The script prints a NO_CHECK: total before the rows; if most of a phase is NO_CHECK, say that plainly rather than implying the phase is nearly complete.

Special case: the Production stage — read sprint-status.yaml

When the current stage is production, check for production/sprint-status.yaml before doing any glob-based story checks. If it exists, read it directly:

  • Stories with status: in-progress → surface as "currently active"
  • Stories with status: ready-for-dev → surface as "next up"
  • Stories with status: done → count as complete
  • Stories with status: blocked → surface as blocker with the blocker field

This gives precise per-story status without markdown scanning. Skip the glob artifact check for the implement and story-done steps — the YAML is authoritative.

Special case: repeatable: true (non-production)

For repeatable steps outside production (e.g. "System GDDs"), the artifact check tells you whether any work has been done, not whether it's finished. Label these differently — show what's been detected, then note it may be ongoing.


Step 4m: The Minimal Path (workflow: minimal only)

At minimal the route is the catalog's paths.minimal, not a phase: engine → design/game-brief.md → stories → /dev-story ↔ /story-done. Resolve it in one call:

bash .claude/scripts/artifact-check.sh --path minimal

Map the statuses exactly as in Step 4. implement and story-done are NO_CHECK by design — the story status lines below are their check. The next step is the first of these that applies:

  1. engine-setup not PRESENT → the main path first. Look for prototypes/*/index.html:
    • a match → a game is made. Not played yet → → Next up is to play it and ask for changes in plain words ("make the jump higher"). Once played (its folder has a feel-log.md or a REPORT.md, or its brief an After play: line or a line under ## Keep) → → Next up is to grow it: /prototype and say grow it (its verdict, then one question: keep iterating, or grow it into a real web project), with /setup-engine under "Coming up after that" for an engine instead
    • When the person asks for a change to a made game, or says they love or hate it, → Next up is /prototype with their words, whatever else this list finds: it makes a change with an accept-or-undo question and a checkpoint, takes a love-it as a Keep line, and on hate it it offers fix (recommended), pivot or kill. Never answer it with a change or a drop of your own
    • no match, and the code root holds fewer than 10 source files → no game yet: → Next up is /prototype (make a game you can play), with /setup-engine under "Coming up after that" as the way to start on an engine instead. With design documents in design/gdd/, it is built from their concept doc, as in Step 5's A design with nothing to play (its first case)
    • no match, and 10 or more source files → /setup-engine, as before
  2. game-brief not PRESENT → /reverse-document design [code root] when the code root already holds the game (10 or more source files, the test Step 2 uses for production): at minimal it writes design/game-brief.md from what is built. Otherwise, with nothing under prototypes/ yet, the main path first: → Next up is /prototype (say the game in one line; on Web it is playable, and writes the brief, on an engine it is a quick throwaway build), with /brainstorm under "Coming up after that" for someone with no idea yet. With a prototype made, /brainstorm (at minimal it writes the one-page brief), which on a built game would start a new idea.
  3. create-stories not PRESENT:
    • a grown game (a production/qa/evidence/grow-*/replay.args file) → → Next up is one feature a sitting: say the next feature in your own words to /prototype (the brief's first [ ] Features line is the suggestion, when there is one); it is built, checked and committed in one sitting. /cut goes under "Coming up after that". Stories, epics and gates only when the person asks for them (then /create-stories, as below)
    • otherwise /create-stories with no argument (at minimal it builds the stories straight from the brief's Features list). When the brief has no [ ] Features item and its ## Your systems list has no thin stand-in or later system, → Next up is: every feature in the brief is built, so say what to add next, in your own words, and /create-stories adds it to the brief's Features (with your yes) and makes its stories. /cut goes under "Coming up after that"
  4. Stories exist → the list below was printed by .claude/scripts/story-status.sh before you read this skill: one line per unfinished story, already in the route's order — IN_REVIEW, then IN_PROGRESS, then TODO (a Ready or Not Started story) in build order — then BLOCKED, OTHER, NO_STATUS and the COMPLETE count:

!bash "${CLAUDE_SKILL_DIR}/../../scripts/story-status.sh"

Next up is the story on the first IN_REVIEW, IN_PROGRESS or TODO line. The list is already current; do not run the script again, and do not re-read or re-rank the story files: an In Review story is closed before an In Progress one continues — its work is written, and /story-done is quick.

  • IN_REVIEW → its work is written and waiting to be closed: /story-done [path]
  • IN_PROGRESS → it is not done — whatever the code or commits suggest, only /story-done makes a story Complete. Recommend /story-done [path] only if the user, active.md or the git log says its implementation is written; otherwise /dev-story [path] to carry on
  • TODO → /dev-story [path]
  • a story that deepens a system (a TODO story, or an IN_PROGRESS one with nothing written yet, whose header reads > **Build step**: deepen — <system>): look for that system's design doc, design/gdd/<system>.md (the name lowercased, a leading a, an or the dropped, spaces as hyphens: shop.md for "a shop"). None there → Next up is /design-system <system> first, and say why in one plain line: "Story NNN builds <system> out in full, and there is no design for it yet. /design-system <system> writes one, for this one system, so the story is built from your choices and not the AI's guesses." The story goes first under Coming up after that. The doc is there → /dev-story [path] as for any story, with no design line
  • a BLOCKED story → name it and its blocker; it is never Next up
  • no IN_REVIEW, IN_PROGRESS or TODO line, but BLOCKED, OTHER or NO_STATUS lines remain → nothing can be built next, and the build order is not done. Name each of those stories with its status as written, and a blocked story's blocker (read it from that story's file). Next up is clearing the first of them: resolve its blocker, or give an OTHER or NO_STATUS story a Status: line the route reads (Ready once it can be built)
  • every story Complete (or Done) → the brief's build order is done. Say so, and offer three ways on: play the build; the next feature: on a grown game, /prototype builds it, one feature a sitting; otherwise say what to add next, in your own words, and /create-stories adds it to the brief's Features (with your yes) and makes its stories; or, if the game has outgrown a one-page brief, /project-settings to raise modes.rigor.

A game past the light path's size. With stories, read the brief's Features list (count its [x] and [ ] items, not a cut [-]) and its Skeleton line, if it has one. The game has outgrown the light path when M on the COMPLETE line is 9 or more, the Features list has 9 or more items, or the Skeleton line names four or more systems. Nine is .claude/docs/settings-guidance.md § 4's "about 9 systems"; four systems is the brief's own mark for a systemic game. Then add the Studio mode line to the minimal shape in Step 7, naming the count that passed. It is a suggestion: Next up stays the story, and nothing waits on it. Show it once: only while the COMPLETE line reads 0 of M (no story built yet, when switching costs least), and never twice in one conversation. Once it shows, leave out Step 9's rigor line.

At minimal, never present any of these as required or as a blocker: the game concept doc, art bible, systems map, GDDs, /create-epics, a sprint plan, /gate-check, or sprint close-out (/smoke-check, /team-qa, /retrospective). The brief replaces the design documents and its build order replaces the sprint plan (.claude/docs/workflow-modes.md — minimal floor). Every one of them still runs if the user asks for it; mention one only when the user's argument asks about it. The one exception is a deepen story's design doc above: one system's, named before that story only.

Then skip Steps 5 and 8, and present with the minimal shape in Step 7.


Step 5: Find Position and Identify Next Steps

From the completion data, determine:

  1. Last confirmed complete step — the furthest completed required step
  2. Current blocker — the first incomplete required step (this is what the user must do next)
  3. Optional opportunities — incomplete optional steps that can be done before or alongside the blocker. Surface these per the workflow tier: at full, list all of them; at standard, list an optional doc only if it is required for the current system/phase (do not flag genuinely-optional docs as gaps). At minimal this step does not run — Step 4m replaces it
  4. Upcoming required steps — required steps after the current blocker (show as "coming up" so user can plan ahead)

If the user provided an argument (e.g. "just finished design-review"), use that to advance past the step they named even if the artifact check is ambiguous.

A design with nothing to play. When design/gdd/ holds a .md file and Glob finds no prototypes/*/index.html, check engine.name in project.yaml:

  • No engine set, or web: → Next up is a playable first, /prototype built from their concept doc (/prototype design/gdd/game-concept.md; with no concept doc, the GDD that describes the whole game). Say in one line: "Your design documents stay the source of truth; the brief /prototype writes is only a summary for the build." The blocker found above goes first under "Coming up after that", with /project-stage-detect and /adopt after it.
  • An engine other than web: the blocker stays → Next up. Add under "Also available" that /prototype --path html is the fast option: a browser sketch of the core game, thrown away when the engine build starts.

Step 6: Check for In-Progress Work

If active.md shows an active task or epic:

  • Surface it prominently at the top: "It looks like you were working on [X]"
  • Suggest continuing it or confirm if it's done

Step 7: Present Output

Keep it short and direct. This is a quick orientation, not a report.

## Where You Are: [Phase Label]
Studio mode (`workflow: [value]`): the design documents, agents and `team-*` pipelines. It fits a team, a long project, or someone who wants the paperwork.

**In progress:** [from active.md, if any]

### ✓ Done
- [completed step name]
- [completed step name]

### → Next up (REQUIRED)
**[Step name]** — [description]
Command: `[/command]`

### ~ Also available (OPTIONAL)
- **[Step name]** — [description] → `/command`
- **[Step name]** — [description] → `/command`

### Coming up after that
- [Next required step name] (`/command`)
- [Next required step name] (`/command`)

---
Approaching the **[next stage]** stage gate → run `/gate-check` when ready.

The studio-mode line under the heading labels the path and changes no step.

At minimal use this shape instead — no phase label, no gate line. N counts only stories whose status line says Complete or Done, and only those go under ✓ Done. N and M are the two numbers on the COMPLETE line; it names no finished story, so ✓ Done gives their count, not their titles:

## Where You Are: Minimal path — [N] of [M] stories complete

**In progress:** [from active.md, if any]

### ✓ Done
- Engine: [engine] · Game brief · [N] stories

### → Next up
**[Story NNN: title]** — [what it delivers]
Command: `/story-done [story-path]` for an In Review story, or an In Progress one whose work is written; otherwise `/dev-story [story-path]`, or `/design-system <system>` first for a deepen story whose system has no design doc (Step 4m), with its one line of why

### Coming up after that
- [the next Ready stories in build order, at most 3]

### ~ Studio mode (only when Step 4m's size check passed)
[M stories / N features / N systems]: past the size one brief fits. Studio mode adds a design doc per system and architecture decisions; `/project-settings` switches it on. Optional: the stories build as they are either way.

A grown game with no stories: the heading reads Minimal path — grown game, [N] of [M] Features built (the brief's [x] and [ ] lines), ✓ Done names the grow, and Next up is the next feature, with /prototype as its command.

Formatting rules:

  • ✓ for confirmed complete
  • → for the current required next step (only one — the first blocker)
  • ~ for optional steps available now
  • Show commands inline as backtick code
  • If a step has no command (e.g. "Implement Stories"), explain what to do instead of showing a slash command
  • For MANUAL steps, ask the user: "I can't tell if [step] is done — has it been completed?"

Verdict: COMPLETE — next steps identified.


Step 8: Gate Warning (if close)

Skip this step at minimal — the minimal path has no stage gates.

After the current stage's steps, check if the user is likely approaching a gate:

  • If all required steps in the current stage are complete (or nearly complete), add: "You're close to the [Current] → [Next] gate. Run /gate-check when ready."
  • If multiple required steps remain, skip the gate warning — it's not relevant yet.

Step 9: Escalation Paths

After the recommendations, if the user seems stuck or confused, add:

---
Need more detail?
- `/project-stage-detect` — full gap analysis with all missing artifacts listed
- `/gate-check` — formal readiness check for your next stage
- `/start` — re-orient from scratch
- `/project-settings` — if the process feels mismatched to your project, adjust
  `modes.rigor`. Apply the change-triggers in
  `.claude/docs/settings-guidance.md § 4`: a **lower** tier when the user sounds
  overwhelmed by process (and rigor isn't already `minimal`), or a **higher** tier
  when the project has outgrown it (many systems, or in Production on
  `workflow: minimal`)

Only show this if the user's input suggested confusion (e.g. "I don't know", "stuck", "lost", "not sure"). Don't show it for simple "what's next?" queries. Show the /project-settings rigor line only when a settings-guidance.md § 4 trigger actually fires — the user sounds overwhelmed (and rigor isn't already minimal), or the project has outgrown its tier — not on every confused query. At minimal, leave out the /gate-check line: the minimal path has no stage gates (Step 4m).


Collaborative Protocol

  • Never auto-run the next skill. Recommend it, let the user invoke it.
  • Ask about MANUAL steps rather than assuming complete or incomplete.
  • Match the user's tone — if they sound stressed ("I'm totally lost"), be reassuring and give one action, not a list of six.
  • One primary recommendation — the user should leave knowing exactly one thing to do next. Optional steps and "coming up" are secondary context.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.