project-initialization-phase

This skill orchestrates one-time project setup, producing foundation documentation that all features must align with.

Core responsibilities:

• Detect project type (greenfield vs brownfield)
• Run interactive questionnaire (15 questions covering vision, scale, tech stack, constraints)
• Scan existing codebase (if brownfield) to auto-fill docs
• Launch project-architect agent to generate 8 documentation files
• Validate cross-document consistency
• Present summary with [NEEDS CLARIFICATION] count

Inputs: User answers (15 questions), existing codebase (if brownfield), templates from .spec-flow/templates/project/ Outputs: 8 markdown files in docs/project/ (overview, architecture, tech-stack, data, API, capacity, deployment, workflow) Expected duration: 15-20 minutes (10 min questions + 5-10 min generation/review)

<quick_start> Execute /init-project workflow in 6 steps:

1. Detect project type - Check for package.json, requirements.txt, etc. (greenfield vs brownfield)
2. Interactive questionnaire - Ask 15 questions (project name, vision, scale, tech stack, constraints)
3. Brownfield scanning (if applicable) - Auto-detect tech stack, ERD from migrations, architecture pattern
4. Launch project-architect agent - Generate 8 docs from templates + answers + scan results
5. Validate documentation - Verify all 8 files exist, [NEEDS CLARIFICATION] count < 20, Mermaid diagrams present
6. Summary report - Show coverage (greenfield: 70% filled, brownfield: 80% filled), next steps

Key principle: Mark unknowns with [NEEDS CLARIFICATION] instead of hallucinating. </quick_start>

<success_criteria> Project initialization phase complete when:

• All 8 files generated in docs/project/ (overview, system-architecture, tech-stack, data-architecture, api-strategy, capacity-planning, deployment-strategy, development-workflow)
• [NEEDS CLARIFICATION] count < 20 (indicates good coverage from questionnaire/scan)
• Mermaid diagrams present and valid (C4 in system-architecture, ERD in data-architecture)
• Cross-document consistency validated (tech stack, database, deployment model aligned)
• Tech stack accurately detected (brownfield only)
• User informed of next steps (review docs, fill clarifications, commit)

If [NEEDS CLARIFICATION] count > 30, re-run questionnaire with more detailed answers or manually fill post-generation. </success_criteria>

Knowledge requirements:

• Understanding of greenfield vs brownfield projects
• Familiarity with tech stack detection strategies (package.json, requirements.txt parsing)
• ERD generation from database migrations (Alembic, Prisma)
• Cross-document consistency validation patterns

Before running: ⚠️ WARNING: /init-project generates 8 files in docs/project/. If directory already exists, offer user to:

• A) Backup existing docs to docs/project-backup-{timestamp}/
• B) Append to existing docs (merge new sections)
• C) Abort (user will manually update)

Determine if starting from scratch (greenfield) or with existing codebase (brownfield).

Detection Logic:

# Check for existing codebase indicators
if [ -f "package.json" ]; then
  PROJECT_TYPE="brownfield"
  TECH_DETECTED="Node.js"
elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
  PROJECT_TYPE="brownfield"
  TECH_DETECTED="Python"
elif [ -f "Cargo.toml" ]; then
  PROJECT_TYPE="brownfield"
  TECH_DETECTED="Rust"
elif [ -f "go.mod" ]; then
  PROJECT_TYPE="brownfield"
  TECH_DETECTED="Go"
elif [ -f "Gemfile" ]; then
  PROJECT_TYPE="brownfield"
  TECH_DETECTED="Ruby"
else
  PROJECT_TYPE="greenfield"
fi