Skip to main content
STATE.md is your project’s short-term memory. It tracks current position, performance metrics, and accumulated context across all phases and sessions.

​
Location

.planning/STATE.md
Created after ROADMAP.md during initialization, updated after every significant action.

​
Purpose

Problem it solves: Information is captured in summaries, issues, and decisions but not systematically consumed. Sessions start without context. Solution: A single, small file that’s:
  • Read first in every workflow
  • Updated after every significant action
  • Contains digest of accumulated context
  • Enables instant session restoration

​
Template Structure

# Project State

## Project Reference

See: .planning/PROJECT.md (updated [date])

**Core value:** [One-liner from PROJECT.md Core Value section]
**Current focus:** [Current phase name]

## Current Position

Phase: [X] of [Y] ([Phase name])
Plan: [A] of [B] in current phase
Status: [Ready to plan / Planning / Ready to execute / In progress / Phase complete]
Last activity: [YYYY-MM-DD] — [What happened]

Progress: [░░░░░░░░░░] 0%

## Performance Metrics

**Velocity:**
- Total plans completed: [N]
- Average duration: [X] min
- Total execution time: [X.X] hours

**By Phase:**

| Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|----------|
| - | - | - | - |

**Recent Trend:**
- Last 5 plans: [durations]
- Trend: [Improving / Stable / Degrading]

*Updated after each plan completion*

## Accumulated Context

### Decisions

Decisions are logged in PROJECT.md Key Decisions table.
Recent decisions affecting current work:

- [Phase X]: [Decision summary]
- [Phase Y]: [Decision summary]

### Pending Todos

[From .planning/todos/pending/ — ideas captured during sessions]

None yet.

### Blockers/Concerns

[Issues that affect future work]

None yet.

## Session Continuity

Last session: [YYYY-MM-DD HH:MM]
Stopped at: [Description of last completed action]
Resume file: [Path to .continue-here*.md if exists, otherwise "None"]

​
Section Details

​
Project Reference

Purpose: Points to PROJECT.md for full context. Includes:
  • Core value (the ONE thing that matters)
  • Current focus (which phase)
  • Last update date (triggers re-read if stale)
Note: Claude reads PROJECT.md directly for requirements, constraints, and full decisions.

​
Current Position

Purpose: Where we are right now. Fields:
  • Phase X of Y - Which phase
  • Plan A of B - Which plan within phase
  • Status - Current state (see status values below)
  • Last activity - What happened most recently
  • Progress bar - Visual indicator of overall completion
Progress calculation: 
(completed plans) / (total plans across all phases) × 100%
Example: 
## Current Position

Phase: 2 of 4 (User Features)
Plan: 1 of 3 in current phase
Status: In progress
Last activity: 2025-01-20 — Completed plan 02-01, started 02-02

Progress: [████░░░░░░] 40%

​
Status Values

StatusMeaning
Ready to planPhase ready for /gsd:plan-phase
PlanningPlanning in progress
Ready to executePlans created, ready for /gsd:execute-phase
In progressExecuting plans
Phase completeAll plans done, ready for verification

​
Performance Metrics

Purpose: Track velocity to understand execution patterns. Velocity section:
  • Total plans completed across all phases
  • Average duration per plan
  • Total execution time
By Phase table:
  • Breakdown per phase
  • Helps identify complex vs simple phases
Recent Trend:
  • Last 5 plan durations
  • Trend analysis (improving/stable/degrading)
Updated: After each plan completion. Example: 
## Performance Metrics

**Velocity:**
- Total plans completed: 7
- Average duration: 12 min
- Total execution time: 1.4 hours

**By Phase:**

| Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|---------|
| 1. Foundation | 3 | 45 min | 15 min |
| 2. Features | 4 | 39 min | 9.8 min |

**Recent Trend:**
- Last 5 plans: 15, 12, 10, 8, 9 min
- Trend: Improving

​
Accumulated Context

​
Decisions

Purpose: Quick reference to recent decisions. Guidelines:
  • Full decision log lives in PROJECT.md Key Decisions table
  • STATE.md keeps 3-5 recent decisions affecting current work
  • Format: [Phase X]: [Decision summary]
Example: 
### Decisions

Decisions are logged in PROJECT.md Key Decisions table.
Recent decisions affecting current work:

- Phase 2: Use SWR for data fetching (cleaner than useEffect)
- Phase 1: PostgreSQL for relational data and transactions

​
Pending Todos

Purpose: Track captured ideas. Source: Ideas captured via /gsd:add-todo Format:
  • Count of pending todos
  • Reference to .planning/todos/pending/
  • Brief list if few, count if many
Example: 
### Pending Todos

3 pending todos:
- Add rate limiting to API endpoints
- Investigate pagination performance
- Consider adding caching layer

See `/gsd:check-todos` for details.

​
Blockers/Concerns

Purpose: Issues that affect future work. Source: From “Next Phase Readiness” sections in summaries. Guidelines:
  • Prefix with originating phase
  • Cleared when addressed
  • Focus on actionable concerns
Example: 
### Blockers/Concerns

- Phase 2: Need to set up Stripe account for payment testing
- Phase 3: Email service not configured yet

​
Session Continuity

Purpose: Enable instant resumption. Fields:
  • Last session - When was last work done
  • Stopped at - What was last completed
  • Resume file - Path to .continue-here*.md if exists
Example: 
## Session Continuity

Last session: 2025-01-20 15:30
Stopped at: Completed plan 02-02, ready to execute 02-03
Resume file: .planning/phases/02-features/.continue-here-02-03.md

​
Lifecycle

​
Creation

When: After ROADMAP.md is created during initialization. Initial state:
  • Reference PROJECT.md
  • Initialize empty accumulated context sections
  • Set position to “Phase 1 ready to plan”

​
Reading

First step of every workflow:
  • progress - Present status to user
  • plan - Inform planning decisions
  • execute - Know current position
  • transition - Know what’s complete

​
Writing

After every significant action: execute - After SUMMARY.md created:
  • Update position (phase, plan, status)
  • Note new decisions (detail in PROJECT.md)
  • Add blockers/concerns
  • Update performance metrics
transition - After phase marked complete:
  • Update progress bar
  • Clear resolved blockers
  • Refresh Project Reference date

​
Size Constraint

Keep STATE.md under 100 lines. It’s a DIGEST, not an archive. If accumulated context grows too large:
  • Keep only 3-5 recent decisions in summary (full log in PROJECT.md)
  • Keep only active blockers, remove resolved ones
  • Summarize trends rather than listing all metrics
Goal: “Read once, know where we are” — if it’s too long, that fails.

​
Example: Mid-Project State

# Project State

## Project Reference

See: .planning/PROJECT.md (updated 2025-01-15)

**Core value:** Developers can capture and find tasks instantly without context switching
**Current focus:** Phase 2 - Git Integration

## Current Position

Phase: 2 of 4 (Git Integration)
Plan: 2 of 3 in current phase
Status: In progress
Last activity: 2025-01-20 — Completed plan 02-01, started 02-02

Progress: [████░░░░░░] 42%

## Performance Metrics

**Velocity:**
- Total plans completed: 5
- Average duration: 11 min
- Total execution time: 55 min

**By Phase:**

| Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|---------|
| 1. Foundation | 2 | 28 min | 14 min |
| 2. Git Integration | 3 | 27 min | 9 min |

**Recent Trend:**
- Last 5 plans: 14, 14, 10, 8, 9 min
- Trend: Improving

*Updated after each plan completion*

## Accumulated Context

### Decisions

Decisions are logged in PROJECT.md Key Decisions table.
Recent decisions affecting current work:

- Phase 2: Use simple-git package for git operations
- Phase 1: Store tasks in markdown files, not database

### Pending Todos

2 pending todos:
- Add color coding for task priorities
- Consider adding time tracking

See `/gsd:check-todos` for details.

### Blockers/Concerns

None currently.

## Session Continuity

Last session: 2025-01-20 15:30
Stopped at: Completed plan 02-01, ready to execute 02-02
Resume file: None

​
See Also