# Hydration Workflow

Tasks are **session-scoped** — they disappear when the session ends. Plan files are the **persistent** layer. The hydration pattern bridges sessions.

## Flow Diagram

```
┌──────────────────┐  Hydrate   ┌───────────────────┐
│ Plan Files       │ ─────────► │ Claude Tasks      │
│ (persistent)     │            │ (session-scoped)  │
│ [ ] Phase 1      │            │ ◼ pending         │
│ [ ] Phase 2      │            │ ◼ pending         │
└──────────────────┘            └───────────────────┘
                                        │ Work
                                        ▼
┌──────────────────┐  Sync-back ┌───────────────────┐
│ Plan Files       │ ◄───────── │ Task Updates      │
│ (updated)        │            │ (completed)       │
│ [x] Phase 1      │            │ ✓ completed       │
│ [ ] Phase 2      │            │ ◼ in_progress     │
└──────────────────┘            └───────────────────┘
```

## Session Start: Hydration

1. Read plan files: `plan.md` + `phase-XX-*.md`
2. Identify unchecked `[ ]` items = remaining work
3. `TaskCreate` per unchecked item with metadata (phase, priority, effort, planDir, phaseFile)
4. Set up `addBlockedBy` dependency chains between phases
5. Already-checked `[x]` items = done, skip

**Check first:** `TaskList()` — if tasks already exist (same session), skip re-creation.

## During Work

- `TaskUpdate(status: "in_progress")` when picking up a task
- `TaskUpdate(status: "completed")` immediately after finishing
- Parallel agents coordinate through shared task list
- Blocked tasks auto-unblock when dependencies complete

## Session End: Sync-Back

1. `TaskUpdate` marks all session tasks as complete
2. Update phase files: `[ ]` → `[x]` for completed items
3. Update `plan.md` frontmatter: status field (pending → in-progress → completed)
4. Update progress percentages in plan overview
5. Git commit captures state transition for next session

## Cross-Session Resume

When user runs `/cook path/to/plan.md` in a new session:
1. `TaskList()` → empty (tasks died with old session)
2. Read plan files → re-hydrate from unchecked `[ ]` items
3. Already-checked `[x]` = done, creates tasks only for remaining work
4. Dependency chain reconstructed automatically

## Compound Interest Effect

Each hydration cycle makes specs smarter:
- **Session 1:** Execute first tasks, establish patterns
- **Session 2:** See completed work, build on established patterns
- **Session 3:** Full context of prior sessions, fewer clarifications needed

Git history shows progression. Completed checkboxes show the path that worked. Specs gain **institutional memory** across sessions.

## YAML Frontmatter Sync

Plan files MUST have frontmatter with these fields:

```yaml
---
title: Feature name
description: Brief description
status: in-progress  # pending | in-progress | completed
priority: P1
effort: medium
branch: feature-branch
tags: [auth, api]
created: 2026-02-05
---
```

Update `status` field during sync-back when plan state changes.