Plan First Development

Planning

Overview

Plan-first development methodology where 80%+ of time goes to planning before implementation begins. Planning tokens are cheaper than implementation tokens, and models reason better about a detailed plan that fits their context window than about a sprawling codebase.

When to use: Starting new projects, adding major features, breaking complex work into phases, resuming work after context clears, managing multi-session implementations, coordinating multiple agents on the same codebase.

When NOT to use: Quick bug fixes, one-file changes, exploratory prototyping where requirements are unknown, trivial refactors where the change is obvious.

Quick Reference

Common Mistakes

Delegation

• Explore existing codebase for architecture decisions: Use Explore agent to survey file structure, patterns, and dependencies before planning
• Execute phase implementation with verification: Use Task agent to implement individual phases, run verification criteria, and create checkpoint commits
• Design architecture and decompose into phases: Use Plan agent to create implementation phases with dependency ordering and gate criteria

References

• Planning process and iterative refinement
• Session management and context tracking
• Phase-based implementation planning
• Review workflows and multi-model blending
• Decision tracking and conditional documents
• Planning document templates

Decision Tracking and Conditional Documents

Always Generate

• IMPLEMENTATION_PHASES.md
• SESSION.md

Generate Conditionally

Best Practices Guides

Keep best practices guides in your project folder and reference them in AGENTS.md. Have Claude Code search the web and update them to latest versions.

Real-World Example Plan Documents

FAQ

Q: Should I code a skeleton first?

You get a better result faster by creating one big detailed, granular plan. That is the only way to get models to understand the entire system at once. Once you start turning it into code, it gets too big to understand.

Q: What about problems I did not anticipate?

Finding the flaws and fixing them is the whole point of all the iterations and blending in feedback from all the frontier models. After implementing v1, create another plan for v2.

Q: How do I divide tasks for agents?

Each agent uses the task board to find the next optimal task and marks it in-progress. Distributed, fungible agents.

Q: Do agents need specialization?

No. Every agent is fungible and a generalist. They all use the same base model and read the same AGENTS.md.

Q: Should design decisions be in markdown or beads?

The beads themselves can and should contain this markdown. You can have long descriptions and comments inside the beads -- they do not need to be short bullet point entries.

Planning Document Templates

IMPLEMENTATION_PHASES.md

The core planning document for every project. Each phase is context-safe (5-8 files, 2-4 hours).

# Implementation Phases: [Project Name]

**Project Type**: [Web App / Dashboard / API / Tool]
**Stack**: [Primary technologies]
**Estimated Total**: [X hours]

---

## Phase 1: [Name]

**Type**: [Infrastructure/Database/API/UI/Integration/Testing]
**Estimated**: [X hours]
**Files**: [file1.ts, file2.tsx, ...]

### File Map

- `src/[file].ts` (~XXX lines)
  - **Purpose**: [What this file does]
  - **Key exports**: [Main functions/components/types]
  - **Dependencies**: [What it imports]
  - **Used by**: [What uses it]

### Data Flow

[Mermaid diagram for complex interactions]

### Critical Dependencies

**Internal**: [Codebase files this phase depends on]
**External**: [npm packages needed]
**Configuration**: [Environment variables, config files]

### Gotchas and Known Issues

- **[Issue]**: [Description and solution]

### Tasks

- [ ] Task 1
- [ ] Task 2
- [ ] Test basic functionality

### Verification Criteria

- [ ] Specific test 1
- [ ] Specific test 2

### Exit Criteria

[Clear definition of when this phase is complete]

---

## Notes

### Testing Strategy

[Inline per-phase / Separate testing phase / Hybrid]

### Deployment Strategy

[Deploy per phase / Deploy at milestones / Final deploy]

### Context Management

Phases sized to fit within a single session including implementation,
verification, debugging, and documentation updates.

### Dependencies

1. Infrastructure (no dependencies)
2. Database (depends on Infrastructure)
3. API (depends on Infrastructure + Database)
4. UI (depends on API)
5. Integration (depends on relevant phases)
6. Testing (depends on all implementation phases)

ARCHITECTURE.md

Generate when the project has multiple services, complex system boundaries, or non-trivial data flows.

# Architecture: [Project Name]

**Deployment**: [Platform]
**Frontend**: [Framework + libraries]
**Backend**: [Framework + runtime]

---

## System Overview

[ASCII diagram showing major components and their connections]

---

## Components Breakdown

### Frontend

**Responsibilities**: User interaction, client validation, optimistic updates, state management
**Key Libraries**: [List with purpose of each]

### Backend

**Responsibilities**: Routing, auth, validation, business logic, database ops
**Route Structure**: [Overview of route organization]
**Middleware Pipeline**: [Request flow through middleware]

### Database

**Access Pattern**: [How the backend queries the database]
**Migrations**: [Where migrations live and how to run them]

### External Services

[List each service with purpose and integration method]

---

## Data Flow Patterns

### [Flow Name]

[Step-by-step flow description showing how data moves through the system]

---

## Security

**Authentication**: [Method and provider]
**Authorization**: [How ownership/permissions are checked]
**Input Validation**: [Client and server validation strategy]
**Secrets**: [How secrets are managed across environments]

---

## Scaling Considerations

[Current limits and what to change if you need to scale beyond them]

DATABASE_SCHEMA.md

Generate when the project has 3+ tables.

# Database Schema: [Project Name]

**Database**: [Engine]
**Migrations**: [Location]
**ORM**: [ORM or raw SQL]

---

## Tables

### `[table_name]`

**Purpose**: [What this table stores]

| Column       | Type    | Constraints           | Notes                  |
| ------------ | ------- | --------------------- | ---------------------- |
| `id`         | INTEGER | PRIMARY KEY           | Auto-increment         |
| `user_id`    | INTEGER | FOREIGN KEY, NOT NULL | References `users(id)` |
| `[field]`    | [TYPE]  | [CONSTRAINTS]         | [Notes]                |
| `created_at` | INTEGER | NOT NULL              | Unix timestamp         |

**Indexes**: [List indexes with purpose]
**Relationships**: [Foreign key relationships]

---

## Relationships Diagram

[ASCII diagram showing table relationships]

---

## Migrations

### Migration 0001: [Description]

**File**: `migrations/0001_[name].sql`
**Creates**: [Tables created]
**Run**: `[command to execute migration]`

---

## Seed Data

[Sample data for development and testing]

---

## Query Patterns

[Common queries used by the application]

---

## Constraints

**Database level**: Primary keys, foreign keys, unique constraints, not null
**Application level**: Format validation, length limits, enum values, business rules

API_ENDPOINTS.md

Generate when the project has 5+ endpoints.

# API Endpoints: [Project Name]

**Base URL**: `/api`
**Auth**: [Authentication method]
**Validation**: [Validation library]

---

## Response Format

### Success

[Standard success response structure]

### Error

[Standard error response structure with error codes]

---

## [Resource] Endpoints

### GET `/api/[resource]`

**Purpose**: [What this endpoint does]
**Auth**: [Required/None]
**Query Parameters**: [List with defaults]
**Response 200**: [Response body example]

### POST `/api/[resource]`

**Purpose**: [What this endpoint does]
**Auth**: [Required/None]
**Request Body**: [Request body with validation schema]
**Response 201**: [Response body example]
**Response 400**: [Validation error example]

### PATCH `/api/[resource]/:id`

**Purpose**: [What this endpoint does]
**Auth**: [Required/None]
**Request Body**: [Partial update fields]
**Response 200**: [Response body example]

### DELETE `/api/[resource]/:id`

**Purpose**: [What this endpoint does]
**Auth**: [Required/None]
**Response 204**: No content

---

## Middleware

**CORS**: [Origins, methods, headers]
**Auth**: [JWT verification, context injection]
**Validation**: [Request body validation against schemas]
**Error Handler**: [Catch unhandled errors, sanitize responses]

When to Generate Each Document

Template Usage Guidelines

• Replace all [placeholders] with project-specific values
• Remove optional sections that do not apply
• Add project-specific sections as needed
• Keep templates in a docs/ directory in the project root
• Reference templates from SESSION.md for easy navigation

Phase-Based Implementation Planning

Phase Structure

Generate structured docs starting with IMPLEMENTATION_PHASES.md. Every phase MUST have:

1. Type -- Infrastructure / Database / API / UI / Integration / Testing 2. Estimated duration -- in hours 3. Files -- specific files created or modified 4. Task list -- ordered checklist with clear actions 5. Verification criteria -- checkbox list of tests to confirm phase works 6. Exit criteria -- clear definition of "done"

Context-Safe Sizing Rules

• Max 5-8 files touched per phase
• Max 2 cross-phase dependencies
• Implementation + verification + fixes should fit in one 2-4 hour session

Auto-Split When Violated

Phase 4 "Complete User Management" is too large (12 files, 8-10 hours).

Suggested split:
- Phase 4a: User CRUD API (5 files, 4 hours)
- Phase 4b: User Profile UI (6 files, 5 hours)

Verification Requirements by Type

• API: Test all HTTP status codes (200, 400, 401, 404, 500)
• UI: Test user flows, form validation, error states
• Database: Test CRUD, constraints, relationships
• Integration: Test service connectivity, webhooks, error handling

Logical Phase Order

Infrastructure -> Database -> API -> UI -> Integration -> Testing

File-Level Detail in Phases

Include for API, UI, and Integration phases:

File map:

- `src/routes/tasks.ts` (~150 lines) - CRUD endpoints
  - Purpose, key exports, dependencies, used by
- `src/lib/schemas.ts` (~80 lines) - Validation schemas

Data flow (Mermaid):

sequenceDiagram
Client->>Worker: POST /api/tasks
Worker->>Auth: authenticateUser()
Worker->>D1: INSERT INTO tasks
D1->>Worker: task record
Worker->>Client: 201 + JSON

Dependencies and gotchas:

**Internal**: auth.ts, schemas.ts, D1 binding
**External**: zod, hono, @clerk/backend
**Gotchas**: Ownership checks on PATCH/DELETE, pagination (50 max), soft delete

Approach Comparison

When multiple implementation paths exist, use a decision matrix to choose systematically.

Decision Matrix

Score each approach (1-5) against weighted criteria:

Criteria (weight)        | Approach A: New Service | Approach B: Extend Existing | Approach C: Third-Party
-------------------------|------------------------|-----------------------------|------------------------
Complexity (3)           | 2                      | 4                           | 5
Maintainability (3)      | 5                      | 3                           | 2
Performance (2)          | 4                      | 3                           | 4
Team familiarity (2)     | 2                      | 5                           | 3
Time to ship (2)         | 2                      | 4                           | 5
Operational cost (1)     | 2                      | 5                           | 3
-------------------------|------------------------|-----------------------------|------------------------
Weighted total           | 40                     | 48                          | 46

Higher complexity scores mean lower complexity (scoring reflects desirability, not raw magnitude).

Record the decision so future developers understand the trade-offs:

Decision: Extend the existing notification service (Approach B)
Rationale: Team familiarity is high, shipping timeline is tight,
           and the existing service handles 80% of the requirements.
Trade-offs accepted: Maintainability score is lower; plan a refactor
                     if notification types exceed 5.
Revisit trigger: If latency exceeds 200ms p99 or notification types > 5.

Spike / Prototype Pattern

A spike is a timeboxed experiment to answer a specific technical question before committing to an approach.

Spike Structure

Question:    Can we render 10,000 rows with virtual scrolling under 16ms per frame?
Timebox:     4 hours
Approach:    Build minimal prototype with react-window, measure with React Profiler
Success:     < 16ms render, < 50MB memory at 10k rows
Failure:     Exceeds thresholds -> evaluate canvas-based rendering
Deliverable: Written summary with measurements, not production code

Spike Rules

1. Timebox strictly -- if the timebox expires without an answer, that itself is a finding 2. Answer one question -- resist scope creep during the spike 3. Throw away the code -- spike code is for learning, not shipping 4. Document the result -- measurements, findings, and recommendation 5. Decide immediately -- the spike should unblock a decision, not create more questions

Scope Negotiation

MoSCoW Prioritization

Must have (MVP):
  - Core functionality required for launch
  - Without these, the feature has no value

Should have (v1.1):
  - Important but not blocking launch
  - First enhancements after MVP ships

Could have (future):
  - Nice-to-have improvements
  - Build only after must/should are stable

Won't have (out of scope):
  - Explicitly excluded from this effort
  - Prevents scope creep by naming what is deferred

Each phase should be independently shippable and deliver user value.

Dependency Mapping

Understanding what blocks what prevents wasted effort and enables parallel work.

Building a Dependency Graph

List all tasks, then for each ask: "What must be true before I can start this?"

Task                          | Depends on           | Blocks
------------------------------|----------------------|------------------
A. Database migration         | Nothing              | B, C
B. Notification API           | A                    | D, E
C. Event hook integration     | A                    | E
D. Frontend component         | B                    | F
E. End-to-end test            | B, C                 | Nothing
F. UI integration test        | D                    | Nothing

Critical Path

The critical path is the longest chain of dependent tasks -- it determines the minimum project duration.

Critical path: A -> B -> D -> F  (4 sequential steps)
Parallel path:  A -> C -> E      (3 steps, runs alongside)

Focus effort on critical path tasks. Delays on the parallel path have slack before they impact the timeline.

Risk Assessment

Probability x Impact Matrix

Rate each risk on two axes (1-5 scale), then multiply for a risk score:

Risk                              | Probability | Impact | Score | Priority
----------------------------------|-------------|--------|-------|----------
API response too slow for UI      | 3           | 4      | 12    | High
Migration corrupts existing data  | 2           | 5      | 10    | High
Third-party SDK breaks on update  | 3           | 3      | 9     | Medium
New component causes layout shift | 4           | 2      | 8     | Medium
Feature flag system has edge case | 2           | 2      | 4     | Low

Focus mitigation effort on high-score risks first.

Mitigation Strategies

Time Estimation

Three-point estimation: For each task, estimate optimistic, likely, and pessimistic durations:

Task: Build notification API

Optimistic:   2 days (everything works first try)
Likely:       4 days (normal iteration and testing)
Pessimistic:  8 days (unexpected integration issues)

Expected:     (2 + 4*4 + 8) / 6 = 4.3 days

Reference class forecasting: Look at similar past work. If "add a new API endpoint" has historically taken 3-5 days, use that range regardless of how simple the new endpoint seems.

Status Icons

Planning Process and Iterative Refinement

Why Planning Matters

• Measure twice, cut once -- becomes "Check your plan N times, implement once"
• A very big, complex markdown plan is still shorter than a few substantive code files
• Front-loading human input in planning enables removing yourself from implementation
• The code will be written ridiculously quickly when you start enough agents with a solid plan

Creating the Initial Plan

Write the plan in a frontier model (GPT Pro Extended Reasoning, Opus 4.5). Include:

1. Goals and intent -- what you are really trying to accomplish 2. Workflows -- how the software works from the user's perspective 3. Tech stack -- be specific (e.g., "TypeScript, TanStack Start, Tailwind v4") 4. Architecture decisions -- high-level structure and patterns 5. The "why" -- the more the model understands your end goal, the better it performs

You do not even need to write the initial markdown plan yourself. You can write it with a frontier model, just explaining what you want to make.

Iterative Refinement

Paste the entire plan into GPT Pro with Extended Reasoning and use this prompt:

Carefully review this entire plan for me and come up with your best revisions
in terms of better architecture, new features, changed features, etc. to make
it better, more robust/reliable, more performant, more compelling/useful, etc.
For each proposed change, give me your detailed analysis and
rationale/justification for why it would make the project better along with the
git-diff style change versus the original plan shown below:

<PASTE YOUR EXISTING COMPLETE PLAN HERE>

Then integrate revisions via Claude Code:

````text OK, now integrate these revisions to the markdown plan in-place; use ultrathink and be meticulous. At the end, you can tell me which changes you wholeheartedly agree with, which you somewhat agree with, and which you disagree with:

``[Pasted text from GPT Pro]` ```

Repeat Until Steady-State

• Start fresh conversations for each round
• After 4-5 rounds, suggestions become very incremental
• You will see massive improvements from v2 to v3, continuing to the end
• This phase can take 2-3 hours for complex features -- this is normal

Planning Workflow for New Projects

1. Ask 3-5 clarifying questions (auth, data, features, scope, timeline) 2. Wait for user answers 3. Create planning docs immediately 4. Output all docs for review 5. Confirm user is satisfied 6. Suggest creating SESSION.md and starting Phase 1

Good Plan vs Great Plan

When to Plan vs Just Build

Planning depth by complexity:

Goal Decomposition

Breaking "build feature X" into concrete, ordered steps. Start from the desired outcome and work backward.

The Decomposition Process

1. Define the outcome -- what does "done" look like from the user's perspective? 2. Identify the layers -- which systems, modules, or files are involved? 3. Extract prerequisites -- what must exist before each piece can be built? 4. Order by dependency -- what blocks what? 5. Size the steps -- each step should be completable and testable independently

Decomposition Patterns

Essential Plan Elements

1. Self-contained -- never need external docs to understand 2. Granular -- complex features broken into specific subtasks 3. Dependency-aware -- what blocks what 4. Justified -- includes reasoning, not just instructions 5. User-focused -- each piece serves the end user

Review Workflows and Multi-Model Blending

Multi-Model Blending

Get competing plans from multiple frontier models, then use a final arbiter to blend:

I asked 3 competing LLMs to do the exact same thing and they came up with
pretty different plans which you can read below. I want you to REALLY carefully
analyze their plans with an open mind and be intellectually honest about what
they did that's better than your plan. Then I want you to come up with the best
possible revisions to your plan that artfully and skillfully blends the "best
of all worlds" to create a true, ultimate, superior hybrid version of the plan
that best achieves our stated goals and will work the best in real-world
practice; you should provide me with a complete series of git-diff style changes
to your original plan to turn it into the new, enhanced plan that integrates the
best of all the plans with every good idea included:

[Paste competing plans here]

When to Blend

• After initial plan is refined (4-5 rounds)
• When different models suggest fundamentally different architectures
• For critical technical decisions where multiple perspectives add value

Anti-Patterns

Troubleshooting

Context Cleared Mid-Phase

1. Read SESSION.md -- find "Next Action" 2. Read referenced planning docs for phase spec 3. Check git log for recent checkpoint commits 4. Continue from the documented next action

Phase Verification Failing

1. Update SESSION.md stage to "Debugging" 2. Document the specific failure in "Current Issue" 3. Fix the issue 4. Return to Verification stage and continue checking criteria

Plan Feels Incomplete After Refinement

• Run additional review rounds (improvements continue past round 5)
• Try multi-model blending for fresh perspectives
• Check: Does the plan explain WHY, not just WHAT?
• Check: Are user workflows documented end-to-end?

Phase Too Large to Complete in One Session

• Split using auto-split logic (max 5-8 files, 2-4 hours)
• Create sub-phases (4a, 4b) with their own verification criteria
• Each sub-phase must be independently verifiable

Session Management and Context Tracking

SESSION.md Purpose

SESSION.md is a navigation hub in the project root (<200 lines). It references planning docs and tracks current progress. Planning docs are the reference material (rarely change); SESSION.md is the living document (updates constantly).

Phases vs Sessions

• Phases (IMPLEMENTATION_PHASES.md): Units of WORK. Have verification/exit criteria. May span multiple sessions.
• Sessions (SESSION.md): Units of CONTEXT. Complete before clearing context. Can cover part of a phase or multiple small phases.

Example: Phase 3 (Tasks API) -> Session 1 (GET/POST) -> Session 2 (PATCH/DELETE) -> Session 3 (verify complete)

SESSION.md Template

# Session State

**Current Phase**: Phase 3
**Current Stage**: Implementation
**Last Checkpoint**: abc1234 (2025-10-23)
**Planning Docs**: `docs/IMPLEMENTATION_PHASES.md`, `docs/ARCHITECTURE.md`

---

## Phase 1: Setup [Complete]

**Completed**: 2025-10-15 | **Checkpoint**: abc1234
**Summary**: Vite + React + Tailwind v4 + D1 binding

## Phase 2: Database [Complete]

**Completed**: 2025-10-18 | **Checkpoint**: def5678
**Summary**: D1 schema + migrations + seed data

## Phase 3: Tasks API [In Progress]

**Type**: API | **Started**: 2025-10-23
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-3`

**Progress**:

- [x] GET /api/tasks endpoint (commit: ghi9012)
- [x] POST /api/tasks endpoint (commit: jkl3456)
- [ ] PATCH /api/tasks/:id <-- CURRENT
- [ ] DELETE /api/tasks/:id
- [ ] Verify all endpoints

**Next Action**: Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47

**Key Files**: `src/routes/tasks.ts`, `src/lib/schemas.ts`

**Known Issues**: None

## Phase 4: Task UI [Pending]

**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-4`

Status Icons

Stages Within a Phase

Each phase progresses through three stages:

1. Implementation -- writing code for tasks 2. Verification -- testing against verification criteria from IMPLEMENTATION_PHASES.md 3. Debugging -- fixing issues found during verification

Update SESSION.md with the current stage. Example during verification:

**Current Stage**: Verification

**Verification Progress**:

- [x] GET /api/tasks returns 200
- [x] POST /api/tasks creates task
- [ ] POST with invalid data returns 400 (currently returns 500)

**Current Issue**: Invalid data returning 500. Check src/middleware/validate.ts

Session Handoff Protocol

Ending a Session

1. Update SESSION.md with current progress and stage 2. Create a git checkpoint commit (see format below) 3. Set a concrete "Next Action" with file path, line number, and task 4. Push to remote if desired

Resuming a Session

1. Read SESSION.md -- find "Current Phase", "Current Stage", and "Next Action" 2. Read referenced planning docs for phase spec and verification criteria 3. Check git log for recent checkpoint commits 4. Continue from the documented next action

Context Full Mid-Phase

When context is filling up before a phase is complete:

1. Update SESSION.md with current progress 2. Create git checkpoint commit (status: In Progress) 3. Clear context 4. Read SESSION.md + planning docs 5. Continue from "Next Action"

Phase Complete

1. Run all verification criteria from IMPLEMENTATION_PHASES.md 2. Mark phase Complete in SESSION.md 3. Create git checkpoint commit (status: Complete) 4. Move next phase from Pending to In Progress 5. Set "Next Action" for first task of next phase

Git Checkpoint Format

checkpoint: Phase [N] [Status] - [Brief Description]

Phase: [N] - [Name]
Status: [Complete/In Progress/Paused/Blocked]
Session: [What was accomplished this session]

Files Changed:
- path/to/file.ts (what changed)

Next: [Concrete next action with file path + line number]

Checkpoint Examples

Phase complete:

checkpoint: Phase 3 Complete - Tasks API

Phase: 3 - Tasks API
Status: Complete
Session: Completed all CRUD endpoints and verified functionality

Files Changed:
- src/routes/tasks.ts (all CRUD operations)
- src/lib/schemas.ts (task validation)

Next: Phase 4 - Start building Task List UI component

Context full mid-phase:

checkpoint: Phase 3 In Progress - Endpoints implemented

Phase: 3 - Tasks API
Status: In Progress
Session: Implemented GET and POST endpoints, need PATCH/DELETE

Files Changed:
- src/routes/tasks.ts (GET, POST endpoints)
- src/lib/schemas.ts (task schema)

Next: Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47

Paused for decision:

checkpoint: Phase 3 Paused - Need design decision

Phase: 3 - Tasks API
Status: Paused
Session: Built endpoints but need to decide on tag filtering approach

Files Changed:
- src/routes/tasks.ts (basic endpoints)

Next: Decide: client-side tag filtering or SQL query parameter? Resume at src/routes/tasks.ts:89

When to Checkpoint

• End of phase (status: Complete)
• Context getting full mid-phase (status: In Progress)
• Pausing for user decision (status: Paused)
• Hitting a blocker (status: Blocked)

Creating a Checkpoint

git add path/to/changed/files
git commit -m "$(cat <<'EOF'
checkpoint: Phase 3 In Progress - Endpoints implemented

Phase: 3 - Tasks API
Status: In Progress
Session: Implemented GET and POST endpoints

Files Changed:
- src/routes/tasks.ts (GET, POST endpoints)

Next: Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47
EOF
)"

After committing, update SESSION.md with the checkpoint commit hash. This means SESSION.md is always uncommitted when resuming -- this is by design.

Expected Uncommitted Files

Normal (no warning needed):

• SESSION.md -- checkpoint hash updated post-commit, always uncommitted between sessions
• CLAUDE.md -- often updated during dev

Warning triggers (unexpected uncommitted):

• Source files (.ts, .tsx, .js)
• Config files (vite.config.ts, wrangler.jsonc)
• Planning docs (IMPLEMENTATION_PHASES.md, ARCHITECTURE.md)
• New untracked files

SESSION.md Guidelines

Do:

• Collapse completed phases to 2-3 lines (date, checkpoint, summary)
• Use concrete "Next Action" with file path + line number + task
• Reference planning docs instead of duplicating content
• Checkpoint at phase end or when context is full

Do not:

• Copy code into SESSION.md (reference file paths instead)
• Duplicate IMPLEMENTATION_PHASES.md content (link with anchors)
• Use vague actions like "continue API work"
• Let SESSION.md exceed 200 lines

Creating SESSION.md for a New Project

After generating IMPLEMENTATION_PHASES.md:

1. Read IMPLEMENTATION_PHASES.md to extract phase names and types 2. Create SESSION.md in project root 3. Set Phase 1 as In Progress, all others as Pending 4. Expand Phase 1 with task checklist from IMPLEMENTATION_PHASES.md 5. Set concrete "Next Action" for the first task 6. Commit SESSION.md as part of initial project setup