/project-stage-detect

name: project-stage-detect
description: "Analyze project state, detect stage, identify gaps, recommend next steps. 'Where are we in development?'"
argument-hint: "[optional: role filter like 'programmer' or 'designer']"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Bash(bash "*/.claude/skills/project-stage-detect/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/artifact-check.sh), Bash(bash ".claude/scripts/artifact-check.sh"), Bash(bash ./.claude/scripts/artifact-check.sh), Bash(bash .claude/scripts/artifact-check.sh *), Bash(bash ".claude/scripts/artifact-check.sh" *), Bash(bash ./.claude/scripts/artifact-check.sh *)
model: haiku
# Read-only diagnostic skill — no specialist agent delegation needed

Project Stage Detection

This skill scans your project to determine its current development stage, completeness of artifacts, and gaps that need attention. It's especially useful when:

• Starting with an existing project
• Onboarding to a codebase
• Checking what's missing before a milestone
• Understanding "where are we?"

---

Workflow

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

**Automation mode**: Resolve `modes.automation` (`project.local.yaml` → `project.yaml` → default `collaborative`). Every `AskUserQuestion` call and every file write follows `.claude/docs/automation-modes.md` (collaborative asks always · guided major-only · autonomous logs and proceeds; `automation_always_ask` categories always prompt).

Resolved above — use as-is. No block → defaults in `.claude/docs/config-resolution.md`.

> **Resolve the tier — do not assume it.** The tier decides what counts as a gap > at all: at `full` every missing doc is one; at `minimal` none of them are, > because a brief plus an engine is the normal state and code is the expected > next step. Guessing high tells a jam project it is missing GDDs, an art bible > and ADRs — the exact "process feels mismatched to my project" experience > `modes.rigor` exists to prevent.

**`workflow`** (per `.claude/docs/workflow-modes.md`). The tier governs which absent documents count as gaps (step 3) — below `full`, optional docs are not flagged.

1. Scan Key Directories

**Start with the deterministic pass — it answers "what exists" for every catalogued artifact in one call:**

Bash: bash .claude/scripts/artifact-check.sh

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

With no `--phase` it reports every phase, so a single call covers the whole project: per step, `PRESENT` / `ABSENT` / `SHORT` (with `count=` and `min=`) / `PATTERN_MISS` / `NO_CHECK`. Use it instead of hand-globbing each artifact below, and treat its `NO_CHECK` total as the honest bound on what existence checks can tell you.

It reports observations only — this skill still decides what stage those observations imply, and the tier still governs which absences are gaps at all (see the workflow-tier note below).

Then analyze what the script cannot: content quality, counts it does not track, and the judgement calls.

**Design Documentation** (`design/`):

• Count GDD files in `design/gdd/*.md`
• Check for game-concept.md (or `design/game-brief.md` at `minimal`), game-pillars.md, systems-index.md
• If systems-index.md exists, count total systems vs. designed systems
• Analyze completeness (Overview, Detailed Design, Edge Cases, etc.). Read GDDs

by section: find the headings you need with the Grep tool (pattern `^#`, content mode) and Read those ranges with offset and limit.

• Count narrative docs in `design/narrative/`
• Count level designs in `design/levels/`

**Source Code** (the code root — `src/` Godot and Web, `Assets/` Unity, `Source/` Unreal; resolve per `.claude/docs/code-root-resolution.md`):

• Count source files (language-agnostic)
• Identify major systems (directories with 5+ files)
• Check for core/, gameplay/, ai/, networking/, ui/ directories
• Estimate lines of code (rough scale)
• An unresolved root means none of these ran: report

`NOT ASSESSED — code root unresolved`, never zero source files — zero files reads as a greenfield project, and the source-file rows of the stage table cannot be decided without the count

**Production Artifacts** (`production/`):

• Check for active sprint plans. At `workflow: minimal` there are no sprints:

read the story files' progress through the brief's build order instead, and never report a missing sprint plan, milestone or roadmap as a gap

• Look for milestone definitions
• Find roadmap documents

**Prototypes** (`prototypes/`):

• Count prototype directories
• Check for READMEs (documented vs undocumented)
• Assess if prototypes are archived or active

**Architecture Docs** (`docs/architecture/`):

• Count ADRs (Architecture Decision Records)
• Check for overview/index documents

**Tests** (`tests/`):

• Count test files
• Estimate test coverage (rough heuristic)

2. Classify Project Stage

Based on scanned artifacts, determine stage. Check `project.stage` in `project.yaml` first (if present); else `production/stage.txt` (legacy fallback) — either is an explicit override from `/gate-check`. Otherwise, auto-detect using these heuristics (check from most-advanced backward):

> **Always run the heuristics, even when a stage is configured — then COMPARE.** > The configured value is authoritative for what the stage *is*; it is not > evidence that the artifacts support it. Report both, and when they disagree say > so explicitly: > > > "Configured stage: **Release**. Observed artifacts indicate > > **Pre-Production** (2 source files, 0 ADRs, no architecture doc, no epics). > > These disagree — the configured stage may be stale, or work exists outside > > this repo." > > Reading config and reporting it back is not detection. This skill's own > description promises "analyze project s