Detects the current project stage (concept/mvp/growth/enterprise) from _state.json field presence and completeness
Stage Detection Skill
Detects the current project stage (concept → mvp → growth → enterprise) based on _state.json field presence and completeness. Used by /architect:next-steps, /architect:check-state, and roadmap commands.
When to Use
Invoke this skill when you need to determine what stage a project is at based on its state file. Stage detection drives:
Command recommendations (what to run next)
Required fields validation (what should exist at this stage)
Risk assessment (what gaps are critical for this stage)
Read architecture-output/_state.json from the project. If missing, treat as "concept" stage.
Output
A stage object:
{"stage":"growth","confidence":0.95,"detected_at":"2026-04-24T14:32:10Z","rationale":"Has 12 entities, design tokens, blueprint, but missing tests and monitoring",
"met_criteria"
:
[
"project.name"
,
"tech_stack"
,
"components"
,
"entities"
,
"design"
,
"blueprint"
]
,
"missing_criteria"
:
[
"test_suite"
,
"monitoring"
,
"compliance"
]
,
"next_stage_blockers"
:
[
"80% test coverage (currently 0%)"
,
"observability setup (currently none)"
]
,
"stage_path"
:
"growth → enterprise in ~3 months"
}
Detection Algorithm
if _state.json missing or _state.json.project.name missing:
stage = "concept"
elif missing tech_stack OR missing components:
stage = "mvp-planning"
elif missing entities OR missing blueprint:
stage = "mvp"
elif missing test_suite AND (entities count < 10 OR no_monitoring):
stage = "growth"
elif missing monitoring OR missing compliance:
stage = "growth"
else if has monitoring AND has compliance AND has >= 15 entities AND test_coverage >= 80%:
stage = "enterprise"
else:
stage = "growth" // most projects land here
Confidence Scoring
Confidence (0.0 → 1.0) reflects whether the detected stage matches the project's actual state:
Confidence
Meaning
When it happens
1.0
Certain
Stage fields perfectly match expected set (all met, all missing)
0.9
Very confident
One expected field has inconsistent data (e.g., test_suite.coverage_target exists but no actual tests)
0.8
Confident
Two fields inconsistent or ambiguous (e.g., has monitoring but no compliance)
0.7
Reasonable
Three+ fields are stale or contradictory
< 0.7
Low
State file severely corrupted or contradicts itself (rare)
Example low-confidence scenario:
{"project.stage":"mvp",// manually set to mvp"entities":20,// but has 20 entities (growth indicator)"test_suite":{"coverage":0},// has test struct but 0 coverage"monitoring":null,// monitoring not set up"confidence":0.65,"note":"Mixed signals: test_suite field exists but empty; entities suggest growth; monitoring missing"}
Rationale Generation
Generate a 1-2 sentence summary of why the project is at this stage:
Stage
Example Rationale
concept
No SDL or state file yet. This is the idea stage; ready for market research.
mvp-planning
Defined tech stack but no scaffolded components. Ready to scaffold and start building.
mvp
Scaffolded components exist with basic features. Needs testing and hardening before growth.
growth
10+ entities with complex logic, design tokens, but missing test coverage and observability. Critical to add tests and monitoring before scaling.
enterprise
Full testing, monitoring, compliance setup. Ready for production scale and regulatory scrutiny.
Met Criteria vs. Missing Criteria
For each stage, list fields that ARE present (met_criteria) and NOT present (missing_criteria):
These lists help users understand what they have accomplished and what's needed next.
Next Stage Blockers
For the transition to the next stage, identify 2-3 critical blockers with estimated effort:
Growth → Enterprise blockers example:
"next_stage_blockers":["80% test coverage (currently 0%; est. 2 weeks with 2 engineers)","Monitoring setup (Datadog/Prometheus; est. 1 week)","Security compliance audit (est. 2 weeks)"]
Blockers drive recommendations in /architect:next-steps.
Stage Path Estimate
Project lifecycle estimate based on current staffing implied by scope:
Trajectory
When
Example
Immediate (same week)
If stage is concept or just started mvp
"mvp in 3-5 days with 3-person team"
Short term (1-2 months)
If stage is growth and team is active
"growth → enterprise in 4-6 weeks with current pace"
Long term (3+ months)
If growth with partial coverage
"enterprise in 3+ months at current velocity"
Stale State Detection
If _state.json hasn't been updated in 30+ days:
Confidence drops to 0.7 or lower
Add note: "State file is 35 days old; detected stage may not reflect actual progress"
Recommend running /architect:check-state to validate and refresh
Usage in Commands
From /architect:next-steps:
1. Load _state.json
2. Call stage-detection skill
3. Use returned stage to:
- Filter candidates (only recommend commands for this stage)
- Score by urgency (higher urgency for next-stage blockers)
- Explain why recommendation is timely
From /architect:check-state:
1. Load _state.json
2. Call stage-detection skill
3. Validate that:
- All required fields for this stage exist
- No inconsistencies (test_suite exists but coverage is 0)
- Report missing fields as warnings for stage transition
From /architect:production-readiness:
1. Load _state.json
2. Call stage-detection skill
3. If stage != "enterprise": block and show blockers to reach enterprise
4. If stage == "enterprise": proceed with launch checks
Implementation Notes
No writes: this skill reads only, does not modify state
Deterministic: same input always produces same stage (unless state file has been updated)
Fast: analyze only required fields (no deep traversal of entities array)
Friendly failures: if state file is missing, return stage: "concept" with confidence 1.0 (not an error)
Timestamp all decisions: include detected_at ISO-8601 timestamp for audit trail
Examples
Concept Project
{"stage":"concept","confidence":1.0,"rationale":"No project state yet. Ready for market research and problem validation.","met_criteria":[],"missing_criteria":["project.name","tech_stack","components"],"next_stage_blockers":["Define project name and description","Research market and competitors","Finalize tech stack choice"],"stage_path":"concept → mvp-planning in 1-2 weeks"}
MVP Project
{"stage":"mvp","confidence":0.95,"rationale":"Scaffolded components with basic features. Ready to add tests and observability for stability.","met_criteria":["project.name","tech_stack","components","design"],"missing_criteria":["entities","blueprint","test_suite","monitoring"],"next_stage_blockers":["Entity schema definition (est. 3 days)","Unit & integration tests (est. 5 days; need 60%+ coverage)","Basic monitoring setup (est. 2 days)"],"stage_path":"mvp → growth in 2-3 weeks"}
Growth Project
{"stage":"growth","confidence":0.92,"rationale":"Complex data model (12 entities) with design tokens and blueprint. Missing test coverage and observability for safe scaling.","met_criteria":["project.name","tech_stack","components","entities","design","blueprint","personas"],"missing_criteria":["test_suite","monitoring","compliance"],"next_stage_blockers":["Unit & integration test suite (80% coverage target; est. 3 weeks)","Monitoring setup (metrics, traces, logs; est. 1 week)","Security compliance review (est. 2 weeks)"],"stage_path":"growth → enterprise in 6-8 weeks at current velocity"}
Enterprise Project
{"stage":"enterprise","confidence":0.98,"rationale":"Full production-hardening: tests (87%), monitoring, compliance controls, load testing plan. Ready for scale and regulatory scrutiny.","met_criteria":["project.name","tech_stack","components","entities","design","blueprint","personas","test_suite","monitoring","compliance","load_testing"],"missing_criteria":[],"next_stage_blockers":[],"stage_path":"enterprise: focus on optimization, scalability, and incident response"}
Related Commands
/architect:next-steps — uses stage to recommend high-ROI commands
/architect:check-state — uses stage to validate required fields
/architect:production-readiness — uses stage to gate launch
/architect:roadmap — uses stage to forecast milestones