project-stage-detect
Automatically analyze project state, detect stage, identify gaps, and recommend next steps based on existing artifacts.
- License 许可
- MIT
- 最近更新
- 2026-11-12
- Stars
- ★ 3
- Forks
- 1
01 前言 Front Matter
- name
- project-stage-detect
- description
- Automatically analyze project state, detect stage, identify gaps, and recommend next steps based on existing artifacts.
- allowed-tools
- Read, Glob, Grep, Bash
- argument-hint
- [optional: role filter like 'programmer' or 'designer']
- user-invocable
- true
03 SKILL.md 正文
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
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
Based on scanned artifacts, determine stage. 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):
| Stage | Indicators |
|---|---|
| Concept | No game concept doc, brainstorming phase |
| Systems Design | Game concept exists, systems index missing or incomplete |
| Technical Setup | Systems index exists, engine not configured |
| Pre-Production | Engine configured, src/ has <10 source files |
| Production | src/ has 10+ source files, active development |
| Polish | Explicit only (set by /gate-check Production → Polish gate) |
| Release | Explicit only (set by /gate-check Polish → Release gate) |
3. Collaborative Gap Identification
DO NOT just list missing files. Instead, ask clarifying questions:
- "I see combat code (
src/gameplay/combat/) but nodesign/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]
## 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-systemsto decompose into systems - Missing design docs? →
/reverse-document design src/[system] - Missing architecture docs? →
/architecture-decisionor/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:
- Question First: Ask about gaps, don't assume
- Present Options: "Should I create X, or is it tracked elsewhere?"
- User Decides: Wait for direction
- Show Draft: Display report summary
- Get Approval: "May I write to production/project-stage-report.md?"
Never silently write files. Always show findings and ask before creating artifacts.
04 同仓库更多 Skills
webapp-testing
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
internal-comms
A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.).
web-artifacts-builder
Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.
frontend-design
Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
algorithmic-art
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
theme-factory
Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly.