Stage Detection

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:

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:

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:

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