Project Files

Project Communication Files

Standard files for coordinating work across agents and sessions. These files serve as the single source of truth for project state.

Quick-Start

The 3 core files for agent coordination:

PLAN.md — Strategy

# Plan: <Project>
## Goal
One-line objective.
## Strategy
High-level approach.
## Phases
### Phase 1: <Name> [IN_PROGRESS]
- Objective: What this achieves
- Success criteria: How we know it's done

TODO.md — Tasks

# TODO
## Current Sprint
### In Progress
- [ ] agent: Task description
### Ready
- [ ] agent: Task description
### Blocked
- [ ] agent: Task (blocked by: X)

SESSION.md — Handoff

# Session: YYYY-MM-DD HH:MM
## Context
What we were working on.
## Current State
- PLAN phase: X, TODO items: Y, Blockers: None
## Next Actions
1. Complete X (assigned to: agent)
2. Start Y

File Overview

File Formats

PLAN.md

Strategic direction. Updated when approach changes.

# Plan: <Feature/Project Name>

## Goal
One-line objective.

## Strategy
High-level approach (2-3 paragraphs).

## Phases

### Phase 1: <Name> [IN_PROGRESS]
- Objective: What this phase achieves
- Success criteria: How we know it's done

### Phase 2: <Name> [PENDING]
- Objective: ...

## Constraints
- Must use X technology
- Must maintain Y compatibility

## Risks
- Risk: Mitigation strategy

State markers: [PENDING], [IN_PROGRESS], [COMPLETED], [BLOCKED]

TODO.md

Active work queue. Updated continuously.

# TODO

## Current Sprint

### In Progress
- [ ] <agent-name>: Task description (blocked by: X, ETA: Y)

### Ready
- [ ] <agent-name>: Task description (depends on: X)
- [ ] <agent-name>: Task description

### Blocked
- [ ] <agent-name>: Task description (blocked by: X, reason: Y)

## Backlog
- [ ] Future task

## Completed (Last 5)
- [x] <agent-name>: Task description (completed: DATE)

Assignment format: <agent-name>: <task> (e.g., architect: Design auth API)

SPEC.md

Technical specification. Updated during planning.

# SPEC: <Component/Feature>

## Overview
What this component does.

## Interface

### API/Exports
```typescript
function doThing(input: Input): Output

Types

interface Input { ... }
interface Output { ... }

Behavior

• Given X, should Y
• Error cases: Z

Dependencies

• Requires: module-a
• Used by: module-b

Open Questions

• Question to resolve

### DECISIONS.md

Architecture Decision Records. Append-only.

```markdown
# Decisions

## ADR-001: <Title>

**Date:** YYYY-MM-DD  
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXX

### Context
What problem were we solving?

### Decision
What did we decide?

### Consequences
Positive:
- Benefit 1

Negative:
- Trade-off 1

ADR numbering: Sequential (ADR-001, ADR-002...)

SESSION.md

Session handoff. Updated at end of session.

# Session: YYYY-MM-DD HH:MM

## Context
What we were working on and why.

## Current State
- PLAN phase: X
- TODO items in progress: Y, Z
- Blockers: None | X

## Files Modified
- `src/auth/login.ts` - Added validation
- `tests/auth.test.ts` - Added tests

## Next Actions
1. Complete X (assigned to: agent-name)
2. Start Y (ready to go)

## Notes for Next Session
- Watch out for: potential issue
- Remember to: check Z

STATUS.md

Quick status dashboard. Updated as needed.

# Status

**Last Updated:** YYYY-MM-DD HH:MM  
**Current Phase:** Implementation  
**Overall Health:** 🟢 On Track | 🟡 At Risk | 🔴 Blocked

## Progress
- [x] Planning complete
- [x] Design approved
- [ ] Implementation (60%)
- [ ] Testing
- [ ] Deployment

## Blockers
None.

## Recent Changes
- Change 1
- Change 2

CHANGELOG.md

Completed work history. Append-only.

# Changelog

## [Unreleased]

### Added
- Feature X implemented by @agent-name
- API endpoint Y added

### Fixed
- Bug Z resolved

## [DATE] - Release Name

### Added
- Initial implementation

Follows Keep a Changelog format.

Workflow Integration

Starting a Complex Task

# 1. Create PLAN.md with high-level strategy
cat > PLAN.md << 'EOF'
# Plan: User Authentication

## Goal
Implement secure JWT-based authentication.

## Strategy
...
EOF

# 2. Create TODO.md with initial tasks
cat > TODO.md << 'EOF'
# TODO

## Current Sprint

### Ready
- [ ] architect: Design auth API (SPEC.md)
- [ ] security: Review threat model
EOF

# 3. Create initial SPEC.md template
cat > SPEC.md << 'EOF'
# SPEC: Authentication API

## Overview
...
EOF

Delegating to Subagents

When using spawn-subagents or mixture-of-experts:

# Read context files before spawning
PLAN=$(cat PLAN.md)
TODO=$(cat TODO.md)
SPEC=$(cat SPEC.md)

# Spawn expert with full context
tmux send-keys -t subagent-architect \
  "pi -p 'Review PLAN.md, TODO.md, and SPEC.md. Then: $TASK' ..." C-m

Session Handoff

At end of session:

# 1. Update TODO.md - mark completed, move in-progress to ready
# 2. Update SESSION.md with current state
# 3. Update CHANGELOG.md with completed work
cat >> CHANGELOG.md << 'EOF'

### Added
- Implemented user login flow (SESSION.md for details)
EOF

Mixture of Experts Coordination

Use files to share context between experts:

# Pre-populate files for experts to read
for expert in architect security performance; do
  # Each expert reads PLAN/TODO/SPEC, writes to DECISIONS
  tmux send-keys -t "moe-$expert" \
    "cat PLAN.md SPEC.md | pi -p 'Review and add decisions to DECISIONS.md' ..." C-m
done

Best Practices

DOs

• Update TODO.md in real-time — Mark tasks done as you complete them
• Write SESSION.md before quitting — Future you will thank you
• Keep SPEC.md precise — Ambiguity causes rework
• Date all entries — Context decays over time
• Use status markers — [IN_PROGRESS], [BLOCKED], [DONE]

DON'Ts

• Don't duplicate information — Link to files instead of copying
• Don't leave TODO.md stale — If it's wrong, it's harmful
• Don't delete from CHANGELOG — Append-only history
• Don't skip DECISIONS.md — You'll forget why you chose X

File Lifecycle

PLAN.md      → Created at project start, updated when strategy shifts
TODO.md      → Created with first tasks, updated continuously
SPEC.md      → Created during design phase, refined during implementation
DECISIONS.md → Created on first ADR, appended forever
SESSION.md   → Created at session end, archived after next session starts
STATUS.md    → Created when needed, kept current
CHANGELOG.md → Created at project start, appended forever

Quick Commands

# Check current status
cat STATUS.md

# See what's in progress
grep -A 5 "In Progress" TODO.md

# View recent decisions
tail -50 DECISIONS.md

# Find previous session context
cat SESSION.md

# See what changed recently
tail -30 CHANGELOG.md