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

0. Run the Deterministic Phase Gate

Before any model-side scanning, run (Bash):

python3 "${CLAUDE_PLUGIN_ROOT:-.claude}/scripts/check_phase.py" \
  --catalog "${CLAUDE_PLUGIN_ROOT:-.claude}/docs/workflow-catalog.yaml" --json

This returns the track (game/product), current phase, per-step completion verdicts, the current blocker, and any dependency violations (a completed step whose required dependency was skipped). These verdicts are deterministic — carry them into the report unchanged; do not re-derive completion by globbing (docs/deterministic-gates.md). Name the gate in the report: check_phase.py → exit N.

• EXIT: 2 — surface each violation as a top-priority gap.
• EXIT: 3 — the gate produced no verdict (say so explicitly); fall back to model-side classification below and mark Stage Confidence as CONCERNS at best.

The scans below add what the gate cannot see: content quality, code volume, and gaps that need human judgment.

1. Scan Key Directories

Analyze project structure and content:

Design Documentation (design/):

• Count GDD files in design/gdd/*.md
• Check for game-concept.md, 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 (src/):

• 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)

Production Artifacts (production/):

• Check for active sprint plans
• 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

Normal path: the stage is the phase field from check_phase.py (Step 0) — it already applied stage.txt-first, artifact-inference-second, for the right track. Report it with Stage Confidence: PASS and name the gate.

Fallback (gate exit 3 only): check production/stage.txt first — if it exists, use its value (explicit override from /gate-check). Otherwise, auto-detect using these heuristics (check from most-advanced backward):

3. Collaborative Gap Identification

DO NOT just list missing files. Instead, ask clarifying questions:

• "I see combat code (src/gameplay/combat/) but no design/gdd/combat-system.md. Was this prototyped first, or should we reverse-document?"
• "You have 15 ADRs but no architecture overview. Should I create one to help new contributors?"
• "No sprint plans in production/. Are you tracking work elsewhere (Jira, Trello, etc.)?"
• "I found a game concept but no systems index. Have you decomposed the concept into individual systems yet, or should we run /map-systems?"
• "Prototypes directory has 3 projects with no READMEs. Were these experiments, or do they need documentation?"

4. Generate Stage Report

Use template: .claude/docs/templates/project-stage-report.md

Report structure:

# Project Stage Analysis

**Date**: [date]
**Stage**: [Concept/Systems Design/Technical Setup/Pre-Production/Production/Polish/Release]
**Stage Confidence**: [PASS — clearly detected / CONCERNS — ambiguous signals / FAIL — critical gaps block progress]

## Completeness Overview
- Design: [X%] ([N] docs, [gaps])
- Code: [X%] ([N] files, [systems])
- Architecture: [X%] ([N] ADRs, [gaps])
- Production: [X%] ([status])
- Tests: [X%] ([coverage estimate])

## Gaps Identified
1. [Gap description + clarifying question]
2. [Gap description + clarifying question]

## Recommended Next Steps
[Priority-ordered list based on stage and role]

5. Role-Filtered Recommendations (Optional)

If user provided a role argument (e.g., /project-stage-detect programmer):

Programmer:

• Focus on architecture docs, test coverage, missing ADRs
• Code-to-docs gaps

Designer:

• Focus on GDD completeness, missing design sections
• Prototype documentation

Producer:

• Focus on sprint plans, milestone tracking, roadmap
• Cross-team coordination docs

General (no role):

• Holistic view of all gaps
• Highest-priority items across domains

6. Request Approval Before Writing

Collaborative protocol:

I've analyzed your project. Here's what I found:

[Show summary]

Gaps identified:
1. [Gap 1 + question]
2. [Gap 2 + question]

Recommended next steps:
- [Priority 1]
- [Priority 2]
- [Priority 3]

May I write the full stage analysis to production/project-stage-report.md?

Wait for user approval before creating the file.

Example Usage

# General project analysis
/project-stage-detect

# Programmer-focused analysis
/project-stage-detect programmer

# Designer-focused analysis
/project-stage-detect designer

Follow-Up Actions

After generating the report, suggest relevant next steps:

• Concept exists but no systems index? → /map-systems to decompose into systems
• Missing design docs? → /reverse-document design src/[system]
• Missing architecture docs? → /architecture-decision or /reverse-document architecture
• Prototypes need documentation? → /reverse-document concept prototypes/[name]
• No sprint plan? → /sprint-plan
• Approaching milestone? → /milestone-review

Collaborative Protocol

This skill follows the collaborative design principle:

1. Question First: Ask about gaps, don't assume
2. Present Options: "Should I create X, or is it tracked elsewhere?"
3. User Decides: Wait for direction
4. Show Draft: Display report summary
5. Get Approval: "May I write to production/project-stage-report.md?"

Never silently write files. Always show findings and ask before creating artifacts.