Project Stage Detection

Purpose

Detect the maturity stage of a software project by analyzing its file structure, configuration files, documentation, and test coverage. Route to the appropriate onboarding or initialization workflow based on the detected stage.

When to Invoke

Skill({ skill: 'project-stage-detection' });

Invoke when:

• Starting work on an unfamiliar repository
• Onboarding a new project into agent-studio
• Determining which workflow to apply (bootstrap vs. enhance vs. optimize)
• Assessing project health at session start
• The planner needs context about project maturity before decomposing tasks

Stage Definitions

Stage	Description	Indicators
new	Freshly initialized, no meaningful content	Only boilerplate files, no src/
early	Has core structure but missing key components	src/ exists, no tests or CI
mid	Functional codebase, gaps in quality infrastructure	Tests exist, no CI/CD or sparse docs
mature	Full-featured with CI/CD, tests, docs, linting	All quality gates present

Workflow

Step 1: Collect File Structure Evidence

Command:

node .claude/skills/project-stage-detection/scripts/main.cjs --dir <project_root>

Expected output: JSON with stage, confidence, indicators, and recommendations.

Verify: Exit code 0 and valid JSON with a stage field.

Step 2: Evaluate Stage Indicators

The script checks for these indicators, scoring each:

Indicator	Weight	Checked Path(s)
Source directory exists	HIGH	src/, lib/, app/
Tests exist	HIGH	tests/, test/, spec/, __tests__/
CI/CD pipeline configured	HIGH	.github/workflows/, .gitlab-ci.yml
Package.json / pyproject.toml	MED	package.json, pyproject.toml
README exists and non-trivial	MED	README.md (>500 bytes)
Linting configured	MED	.eslintrc*, .ruff.toml, pylintrc
Documentation directory	LOW	docs/, .claude/docs/
Changelog present	LOW	CHANGELOG.md, CHANGELOG.rst
Dependencies locked	LOW	package-lock.json, pnpm-lock.yaml

Step 3: Compute Stage Score

Score Range	Stage
0–2	new
3–5	early
6–7	mid
8–9	mature

Command to verify score:

node .claude/skills/project-stage-detection/scripts/main.cjs --dir . --json | node -e "const d=require('fs').readFileSync('/dev/stdin','utf8');const r=JSON.parse(d);console.log('Stage:',r.stage,'Score:',r.score,'Confidence:',r.confidence)"

Step 4: Route to Appropriate Workflow

Based on the detected stage:

Stage	Recommended Action
new	Invoke project-onboarding skill to bootstrap
early	Invoke gap-detection to find missing infrastructure
mid	Invoke gap-detection then proactive-audit
mature	Invoke gap-detection as health check only

Routing command:

// After detection
if (result.stage === 'new') {
  Skill({ skill: 'project-onboarding' });
} else {
  Skill({ skill: 'gap-detection' });
}

Step 5: Write Detection Report

Output location: .claude/context/reports/backend/project-stage-report-YYYY-MM-DD.md

Report format:

# Project Stage Detection Report

**Date:** {{date}}
**Project:** {{project_root}}
**Detected Stage:** {{stage}}
**Confidence:** {{confidence}}%

## Evidence

{{indicators_table}}

## Recommendations

{{recommendations_list}}

Output Schema

See schemas/output.schema.json for the full structured output contract.

Enforcement Hooks

Input validated against schemas/input.schema.json before execution. Output contract defined in schemas/output.schema.json.

Assigned Agents

• planner — uses on task start to calibrate workflow complexity
• architect — uses for brownfield assessment before redesign
• developer — uses to determine onboarding steps for new repos
• master-orchestrator — uses to route to correct initialization workflow

Memory Protocol

Before starting:

Read .claude/context/memory/learnings.md for any previously detected stage for this project. If the stage was recently detected (within 7 days), skip re-detection and use cached result.

After completing:

Append to .claude/context/memory/learnings.md:

## Project Stage Detection — {{date}}

- Project: {{project_root}}
- Stage: {{stage}} (confidence: {{confidence}}%)
- Key gaps: {{gap_summary}}
- Recommended next action: {{next_action}}

Anti-Patterns

• Never hard-code stage thresholds — always compute from indicators.
• Never report mature for a project with no tests — tests are a required mature indicator.
• Never run detection on .claude/ subdirectories — scan the project root only.
• Never block on missing files — handle gracefully with existsSync checks.