project-initialization-phase

Auto-detect tech stack, architecture patterns, and generate ERD from migrations.

Tech Stack Scanning:

# Frontend detection
if [ -f "package.json" ]; then
  # Detect Next.js
  if grep -q '"next":' package.json; then
    FRONTEND_FRAMEWORK=$(jq -r '.dependencies.next // .devDependencies.next' package.json)
  fi

  # Detect React
  if grep -q '"react":' package.json; then
    REACT_VERSION=$(jq -r '.dependencies.react' package.json)
  fi

  # Detect TypeScript
  if grep -q '"typescript":' package.json; then
    TS_DETECTED=true
  fi
fi

# Backend detection
if [ -f "requirements.txt" ]; then
  # Detect FastAPI
  if grep -q 'fastapi' requirements.txt; then
    BACKEND_FRAMEWORK="FastAPI"
    BACKEND_VERSION=$(grep 'fastapi' requirements.txt | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+')
  fi

  # Detect Django
  if grep -q 'django' requirements.txt; then
    BACKEND_FRAMEWORK="Django"
  fi
fi

# Database detection (from dependencies)
if grep -q '"pg":' package.json || grep -q 'psycopg2' requirements.txt; then
  DATABASE="PostgreSQL"
fi

# Database detection (from migrations)
if [ -d "alembic/versions" ]; then
  DATABASE_MIGRATION_TOOL="Alembic"
  MIGRATION_COUNT=$(ls alembic/versions/*.py 2>/dev/null | wc -l)
fi

Architecture Pattern Detection:

# Detect microservices
if [ -d "services" ] || [ -d "microservices" ]; then
  ARCHITECTURE="microservices"
elif [ -f "docker-compose.yml" ]; then
  # Check for multiple services in docker-compose
  SERVICE_COUNT=$(grep -c 'image:' docker-compose.yml)
  if [ "$SERVICE_COUNT" -gt 2 ]; then
    ARCHITECTURE="microservices"
  fi
else
  ARCHITECTURE="monolith"
fi

Deployment Platform Detection:

if [ -f "vercel.json" ]; then
  DEPLOYMENT_PLATFORM="Vercel"
elif [ -f "railway.json" ] || [ -f "railway.toml" ]; then
  DEPLOYMENT_PLATFORM="Railway"
elif [ -d ".github/workflows" ]; then
  # Inspect deploy workflow for platform
  WORKFLOW_FILE=$(find .github/workflows -name "*deploy*" -type f | head -1)
  if grep -q 'vercel' "$WORKFLOW_FILE"; then
    DEPLOYMENT_PLATFORM="Vercel"
  elif grep -q 'railway' "$WORKFLOW_FILE"; then
    DEPLOYMENT_PLATFORM="Railway"
  fi
fi

ERD Generation from Migrations:

# If Alembic migrations exist, generate ERD
if [ -d "alembic/versions" ]; then
  # Scan migration files for create_table statements
  ENTITIES=()
  for migration in alembic/versions/*.py; do
    # Extract table names
    TABLE_NAME=$(grep -oP "create_table\('\K[^']+" "$migration")
    if [ -n "$TABLE_NAME" ]; then
      ENTITIES+=("$TABLE_NAME")
    fi
  done

  # Result: ENTITIES=("users" "students" "lessons" "progress")
fi

Quality check: Tech stack accurately detected? ERD entities match database schema?

# Pass answers + scan results to project-architect agent
# Agent responsibilities:
# - Read 8 templates from .spec-flow/templates/project/
# - Fill templates with questionnaire answers
# - Inject scan results (if brownfield)
# - Mark unknowns with [NEEDS CLARIFICATION]
# - Generate Mermaid diagrams (C4, ERD)
# - Validate cross-document consistency
# - Write 8 files to docs/project/

echo "🤖 Project-architect agent generating documentation..."
echo "   - Reading 8 templates"
echo "   - Filling with questionnaire answers"
echo "   - Injecting scan results (brownfield)"
echo "   - Generating Mermaid diagrams"
echo "   - Validating cross-document consistency"

DOCS_DIR="docs/project"
REQUIRED_FILES=(
  "overview.md"
  "system-architecture.md"
  "tech-stack.md"
  "data-architecture.md"
  "api-strategy.md"
  "capacity-planning.md"
  "deployment-strategy.md"
  "development-workflow.md"
)

for file in "${REQUIRED_FILES[@]}"; do
  if [ ! -f "$DOCS_DIR/$file" ]; then
    echo "❌ Missing file: $DOCS_DIR/$file"
    exit 1
  fi
done

echo "✅ All 8 documentation files generated"

# Count [NEEDS CLARIFICATION] markers
CLARIFICATION_COUNT=$(grep -r "NEEDS CLARIFICATION" "$DOCS_DIR" | wc -l)
echo "ℹ️  Found $CLARIFICATION_COUNT [NEEDS CLARIFICATION] sections"

# Validate Mermaid diagrams
if grep -q '```mermaid' "$DOCS_DIR/system-architecture.md"; then
  echo "✅ Mermaid diagrams present in system-architecture.md"
else
  echo "⚠️  Warning: No Mermaid diagrams in system-architecture.md"
fi

# Cross-document consistency check
# - Tech stack in tech-stack.md matches system-architecture.md
# - Database in tech-stack.md matches data-architecture.md
# - Deployment model in deployment-strategy.md matches capacity-planning.md

echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "✅ PROJECT DOCUMENTATION GENERATED"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
echo "📊 Coverage:"
if [ "$PROJECT_TYPE" = "greenfield" ]; then
  echo "   - Filled from questionnaire: 70%"
  echo "   - Inferred from defaults: 10%"
  echo "   - Needs clarification: 20%"
else
  echo "   - Filled from questionnaire: 50%"
  echo "   - Inferred from codebase: 30%"
  echo "   - Needs clarification: 20%"
fi
echo ""
echo "📍 [NEEDS CLARIFICATION] Sections: $CLARIFICATION_COUNT"
if [ "$CLARIFICATION_COUNT" -gt 0 ]; then
  echo "   Review and fill these sections:"
  grep -r "NEEDS CLARIFICATION" docs/project/ --with-filename | head -5
  echo "   ..."
fi
echo ""
echo "✅ Generated Files:"
for file in "${REQUIRED_FILES[@]}"; do
  echo "   - docs/project/$file"
done
echo ""
echo "💡 Next Steps:"
echo "   1. Review docs/project/ files"
echo "   2. Fill [NEEDS CLARIFICATION] sections"
echo "   3. Commit: git add docs/project/ && git commit -m 'docs: add project architecture'"
echo "   4. Start building: /roadmap or /feature"
echo ""

## Competitors
- Foreflight (market leader, $250/year)
- CloudAhoy ($99/year)
- ForeFlight Pro ($500/year)

## Competitors
[NEEDS CLARIFICATION: Who are your main competitors? What features do they lack that you'll provide?]

Detected brownfield project
Skipping scan (takes too long)
Result: 35 [NEEDS CLARIFICATION] markers

Detected brownfield project
Scanning package.json... Found Next.js 14, React 18, TypeScript
Scanning alembic/versions... Found User, Student, Lesson entities
Result: 12 [NEEDS CLARIFICATION] markers (67% reduction)

## Performance Targets
- API response time: [TODO]
- Database query time: [FILL THIS]

## Performance Targets
- API response time: [NEEDS CLARIFICATION: p95 < 500ms? 1s? 2s?]
- Database query time: [NEEDS CLARIFICATION: What's acceptable for complex joins? <100ms? <500ms?]

Questionnaire Q7: Database = PostgreSQL
Generated doc: "Database: [NEEDS CLARIFICATION: What database?]"

Questionnaire Q7: Database = PostgreSQL
Generated doc: "Database: PostgreSQL (from questionnaire Q7)"

tech-stack.md: Database = PostgreSQL
data-architecture.md: Database = MongoDB (conflict!)

tech-stack.md: Database = PostgreSQL
data-architecture.md: Database = PostgreSQL (consistent)
capacity-planning.md: Database costs = PostgreSQL pricing (consistent)

## Tech Stack

**Backend**: FastAPI (detected from requirements.txt v0.109.0)
**Frontend**: Next.js 14 (detected from package.json)
**Database**: PostgreSQL (from questionnaire Q7)
**Architecture**: Monolith (inferred from team size: solo developer)
**Deployment**: Vercel (from questionnaire Q8)

## Success Metrics

- Monthly Active Users (MAU): [NEEDS CLARIFICATION: What's your target MAU at 6 months? 12 months?]
- Conversion rate: [NEEDS CLARIFICATION: What % of signups should convert to paid within 30 days?]
- Churn rate: [NEEDS CLARIFICATION: What monthly churn rate is acceptable? <5%? <10%?]

graph TD
    A[User] --> B[FlightPro App]
    B --> C[PostgreSQL]
    B --> D[Clerk Auth]
    B --> E[Vercel Edge Network]

erDiagram
    USER ||--o{ STUDENT : teaches
    STUDENT ||--o{ LESSON : takes
    LESSON ||--o{ PROGRESS : tracks

# Extract database from tech-stack.md
TECH_DB=$(grep "Database:" docs/project/tech-stack.md | awk '{print $2}')

# Extract database from data-architecture.md
DATA_DB=$(grep "Database:" docs/project/data-architecture.md | awk '{print $2}')

# Compare
if [ "$TECH_DB" != "$DATA_DB" ]; then
  echo "❌ Inconsistency: tech-stack says $TECH_DB, data-architecture says $DATA_DB"
  exit 1
fi