Phase 0 - Foundation Decisions

Done

Overview

• Track: Both (MVP & Showcase)
• Effort: Minimal, foundational setup
• Dependencies: None
• Deliverables: Core architecture decisions, repository setup, development environment

Entry Criteria

• Project requirements defined
• Hosting platform chosen
• Team assembled (if applicable)
• Development machines ready

Implementation Steps

Step	Task	MVP	Showcase	Notes
0.01	Initialize repository	✅	✅	Include .gitignore, README
0.02	Choose package manager	✅	✅	pnpm recommended for speed
0.03	Set up Node.js version	✅	✅	Use .nvmrc with Node 22.x LTS
0.04	Select framework version	✅	✅	Astro 5.11.0 stable
0.05	Configure TypeScript	✅	✅	Strict mode from start
0.05a	Configure Biome (lint/format)	✅	✅	Init @biomejs/biome & VSCode extension
0.06	Initialize Astro project	✅	✅	Use create-astro CLI
0.07	Set up Git hooks	✅	✅	Husky + lint-staged
0.08	Create branch strategy	✅	✅	Document in README
0.09	Configure environment vars	✅	✅	.env.example template
0.10	Create ADR structure	✅	✅	docs/adr/template.md
0.11	Document key decisions	✅	✅	First ADR entry

Code Examples

Initialize Project

# Create project with pnpm
pnpm create astro@latest my-portfolio -- \
  --template minimal \
  --typescript strict \
  --git \
  --no-install

cd my-portfolio
pnpm install

Package Manager Configuration

package.json

{
  "packageManager": "pnpm@9.15.0",
  "engines": {
    "node": ">=22.0.0",
    "pnpm": ">=9.0.0"
  },
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "check": "astro check && tsc --noEmit",
    "format": "biome format --write .",
    "lint": "biome check --write ."
  }
}

Biome Configuration

{% snippet “biome-config” %}

Editor Configuration

root = true

[*]
charset = utf-8
indent_style = space
indent_size = 2
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

Node Version File

.nvmrc

22.16.0

TypeScript Configuration

{% snippet “tsconfig-paths” %}

Git Hooks Setup

{% snippet “git-hooks” %}

{% snippet “lint-staged-config” %}

Environment Variables Template

{% snippet “env-example” %}

First Architecture Decision Record

{% snippet “adr-template” %}

Branch Strategy Documentation

docs/git-workflow.md

## Branch Strategy

### Main Branches
- `main` - Production-ready code
- `develop` - Integration branch (Showcase only)

### Feature Branches
- `feature/*` - New features
- `fix/*` - Bug fixes
- `docs/*` - Documentation updates

### Workflow
1. Create feature branch from main
2. Make changes with conventional commits
3. Open PR with description
4. Merge after review (Showcase) or self-merge (MVP)

### Commit Convention
- `feat:` - New feature
- `fix:` - Bug fix
- `docs:` - Documentation
- `style:` - Formatting
- `refactor:` - Code restructuring
- `perf:` - Performance improvement
- `test:` - Testing
- `chore:` - Maintenance

Common Pitfalls

1. Wrong Package Manager: Mixing npm/yarn/pnpm causes lockfile conflicts

   • Solution: Commit .npmrc with engine-strict=true

2. Loose TypeScript: Starting without strict mode makes it hard to enable later

   • Solution: Always start with strict mode, add // @ts-expect-error sparingly

3. Missing Git Hooks: Code quality degrades without automation

   • Solution: Set up hooks before writing code

4. Environment Variable Confusion: Hardcoded values in code

   • Solution: Use .env.example and validate on startup

Exit Criteria

• Repository initialized with correct .gitignore
• Package manager locked (pnpm-lock.yaml committed)
• Node.js version specified (.nvmrc file)
• TypeScript in strict mode
• Git hooks functioning (test with commit)
• Branch strategy documented
• Environment variables structured
• ADR template and first decision recorded
• README has basic project information

Rollback Strategy

If critical issues found after Phase 0:

1. Package Manager Issues:

   rm -rf node_modules pnpm-lock.yaml
   pnpm install

2. Git Configuration Issues:

   rm -rf .git
   git init
   # Re-apply configuration

3. Framework Version Issues:

   • Update package.json to stable version
   • Clear cache: pnpm store prune
   • Reinstall dependencies

AI Assistant Notes

Key Files to Reference

• package.json - Verify scripts and dependencies
• tsconfig.json - TypeScript configuration
• .husky/pre-commit - Git hooks
• docs/adr/001-foundation.md - Key decisions

Common Prompts for This Phase

• “Set up Astro 5.11.0 project with TypeScript strict mode”
• “Configure Biome for Astro project”
• “Create Git hooks for code quality”
• “Write ADR for foundation decisions”

Context Requirements

• Project type (portfolio, blog, marketing)
• Team size (solo vs team)
• Deployment target (Cloudflare Pages, Vercel, etc.)