90 lines
4.1 KiB
Markdown
90 lines
4.1 KiB
Markdown
# 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
|
|
|
|
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) — or `TodoWrite` if Task tools unavailable
|
|
4. Set up `addBlockedBy` dependency chains between phases (skip if using TodoWrite fallback)
|
|
5. 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
|
|
|
|
1. Collect completed tasks (`TaskUpdate(status: "completed")`) with metadata (`phase`, `phaseFile`, `planDir`).
|
|
2. Sweep all `phase-XX-*.md` files in the target plan directory.
|
|
3. Reconcile and backfill: update `[ ]` → `[x]` for all completed items across every phase file (including earlier phases).
|
|
4. Update `plan.md` frontmatter: status field (pending → in-progress → completed).
|
|
5. Update progress percentages in `plan.md` overview from real checkbox counts.
|
|
6. Report unresolved mappings when completed tasks cannot be matched to a phase file.
|
|
7. Git commit captures state transition for next session.
|
|
|
|
## Cross-Session Resume
|
|
|
|
When user runs `/ck: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.
|