Project Stage Detection

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. Saying "surface gaps per the resolved workflow tier" without resolving it — no bootstrap, no helper call — leaves the tier as whatever the model assumed. 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. A missing bootstrap is invisible to a static read — the config block simply does not render — so verify it by running.

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.)
• Count narrative docs in design/narrative/
• Count level designs in design/levels/

Source Code (the code root — src/ Godot, 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 state, detect stage", and a stage detector that cannot contradict its input is the one thing it must never be — it would report Release for a project whose artifacts match its own Pre-Production row, four stages below, and say nothing.

A disagreement makes Stage Confidence CONCERNS (step 4) — ambiguous signals by definition — however complete the artifacts are. One exception: at workflow: minimal nothing runs /gate-check, so the configured stage stays where /start set it. There, report the observed stage and say the configured one is not advanced at this tier; that lag is expected, not a disagreement.