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     │
└──────────────────┘            └───────────────────┘

Tool Availability

Task tools (TaskCreate/TaskUpdate/TaskGet/TaskList) are CLI-only — disabled in VSCode extension. If unavailable, use TodoWrite for progress tracking. The hydration pattern still works: plan files remain source of truth, sync-back updates checkboxes regardless of Task tool availability.

Session Start: Hydration

Read plan files: plan.md + phase-XX-*.md
Identify unchecked [ ] items = remaining work
TaskCreate per unchecked item with metadata (phase, priority, effort, planDir, phaseFile) — or TodoWrite if Task tools unavailable
Set up addBlockedBy dependency chains between phases (skip if using TodoWrite fallback)
Already-checked [x] items = done, skip

Check first: TaskList() — if tasks already exist (same session), skip re-creation. If TaskList errors, proceed with TodoWrite.

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

Collect completed tasks (TaskUpdate(status: "completed")) with metadata (phase, phaseFile, planDir).
Sweep all phase-XX-*.md files in the target plan directory.
Reconcile and backfill: update [ ] → [x] for all completed items across every phase file (including earlier phases).
Update plan.md frontmatter: status field (pending → in-progress → completed).
Update progress percentages in plan.md overview from real checkbox counts.
Report unresolved mappings when completed tasks cannot be matched to a phase file.
Git commit captures state transition for next session.

Cross-Session Resume

When user runs /ck:cook path/to/plan.md in a new session:

TaskList() → empty (tasks died with old session)
Read plan files → re-hydrate from unchecked [ ] items
Already-checked [x] = done, creates tasks only for remaining work
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:

---
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.

4.1 KiB Raw Blame History