Thunk Planning Workflow

Setup (if thunk command not found)

If the thunk command is not available, install it first:

cd /path/to/thunk/repo  # where pyproject.toml lives
uv venv && source .venv/bin/activate
uv pip install -e .

Or in an existing venv: source .venv/bin/activate && uv pip install -e .

Thunk orchestrates multiple AI agents (Claude Code + OpenAI Codex) to create implementation plans through iterative refinement.

Quick Reference

Command	Purpose
thunk init "task"	Start new planning session
thunk wait --session <id>	Block until turn complete
thunk status --session <id>	Check progress
thunk continue --session <id>	Start next turn after edits
thunk approve --session <id>	Lock plan as final
thunk list	List all sessions
thunk clean --session <id>	Remove session
thunk diff --session <id>	Show changes between turns

Workflow

init → wait → [user edits] → continue → wait → ... → approve

1. init: Creates session, agents start exploring codebase
2. wait: Blocks until agents complete draft → peer review → synthesis
3. User edits: Human reviews .thunk/sessions/<id>/turns/NNN.md
4. continue: Starts next turn, agents refine based on edits
5. approve: Locks plan, creates PLAN.md symlink

Session Phases

• initializing - Session just created
• drafting - Agents creating initial drafts
• peer_review - Agents reviewing each other's work
• synthesizing - Combining into unified plan
• user_review - Waiting for human feedback
• approved - Plan locked and final

Plan File Format

## Questions
### Q1: [Question needing user input]
**Context:** Why this matters
**Answer:** [User fills this in]

## Summary
[2-3 sentence overview]

## Tasks
- [ ] **Task 1**: Description
  - **Files:** `path/file.py` (create|modify)
  - **Rationale:** Why needed
  - **Dependencies:** none | Task N

## Risks
- **Risk name** (severity: high|medium|low)
  - **Mitigation:** How to address

## Alternatives Considered
- **Alternative**: Rejected because [reason]

Session File Structure

.thunk/sessions/swift-river/       # Human-friendly session ID
├── meta.yaml           # Task, created_at
├── state.yaml          # turn, phase, agent_plan_ids
├── bold-peak.md        # Agent's working plan (opaque name)
├── calm-forest.md      # Another agent's plan
├── turns/
│   ├── 001.md          # Turn 1 synthesis (user edits this)
│   └── 002.md          # Turn 2
├── agents/
│   ├── opus/cli_session_id.txt
│   ├── codex/cli_session_id.txt
│   └── turn-001/
│       ├── opus-draft.md
│       └── opus-final.md
└── PLAN.md             # Symlink to approved turn

Session Continuation

Agents preserve context across turns:

• Claude Code: --resume <session_id>
• Codex: codex resume <thread_id>

First turn exploration (reading files, understanding patterns) is remembered in subsequent turns.