| name | stage-detection |
| description | 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)
- Success criteria (MVP = basic components; Growth = 10+ entities; Enterprise = monitoring + compliance)
Input
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",
"entities": 20,
"test_suite": { "coverage": 0 },
"monitoring": null,
"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):
Growth stage example:
"met_criteria": [
"project.name",
"project.description",
"tech_stack",
"components",
"entities",
"design",
"blueprint",
"personas"
],
"missing_criteria": [
"test_suite",
"monitoring",
"compliance",
"load_testing"
]
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":
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
