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.