project-initialization-phase

<objective>
Guide execution of the /init-project command to generate 8 comprehensive project-level design documents through interactive questionnaire, brownfield codebase scanning, and cross-document consistency validation. Embodies "Planning is 80% of the project, 20% code" philosophy.

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)
</objective>

<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>

<prerequisites>
**Environment checks**:
- Templates exist in `.spec-flow/templates/project/` (8 files: overview-template, system-architecture-template, etc.)
- `docs/` directory exists or can be created
- Project-architect agent available at `.claude/agents/phase/project-architect.md`

**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)
</prerequisites>

<workflow>
<step number="1">
**Detect Project Type (Greenfield vs Brownfield)**

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

**Detection Logic**:

```bash
# 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
```

**Inform user**:

```bash
if [ "$PROJECT_TYPE" = "brownfield" ]; then
  echo "✅ Detected existing codebase ($TECH_DETECTED)"
  echo "   Will scan codebase to auto-fill project docs"
else
  echo "ℹ️  No existing codebase detected (greenfield project)"
  echo "   Will generate templates with [NEEDS CLARIFICATION] markers"
fi
```

**Quality check**: Correct project type detected? If unclear (e.g., multiple languages), ask user which is primary.
</step>

<step number="2">
**Interactive Questionnaire (15 Questions)**

Gather essential project context to fill documentation templates.

**Question Flow** (full list in reference.md):

```bash
# Q1: Project name
read -p "Q1. Project name (e.g., FlightPro): " PROJECT_NAME

# Q2: Vision (1 sentence)
read -p "Q2. Vision - What problem does this solve? (1 sentence): " VISION

# Q3: Primary users
read -p "Q3. Primary users (e.g., CFIs, students): " PRIMARY_USERS

# Q4: Scale tier
echo "Q4. Scale tier:"
echo "   1) Micro (100 users, $40/mo)"
echo "   2) Small (1K users, $95/mo)"
echo "   3) Medium (10K users, $415/mo)"
echo "   4) Large (100K+ users, $2K+/mo)"
read -p "   Choice (1-4): " SCALE_CHOICE
case $SCALE_CHOICE in
  1) SCALE="micro" ;;
  2) SCALE="small" ;;
  3) SCALE="medium" ;;
  4) SCALE="large" ;;
esac

# Q5-Q15: Team size, architecture style, database, deployment platform,
#         API style, auth provider, budget, privacy, git workflow,
#         deployment model, frontend framework
```

**Validation**:
- Required: PROJECT_NAME, VISION, PRIMARY_USERS
- Optional (can be "unknown" or "TBD"): Budget, specific versions

**Store answers**:

```bash
# Save to temporary file for project-architect agent
cat > /tm