# Task Management Integration

## Session-Scoped Reality

Claude Tasks are **ephemeral** — they die when the session ends. `~/.opencode/tasks/` holds lock files only, NOT task data. Plan files (plan.md, phase-XX.md with checkboxes) are the **persistent** layer.

**Tool Availability:** `TaskCreate`/`TaskUpdate`/`TaskGet`/`TaskList` are **CLI-only** — disabled in VSCode extension (`isTTY` check). If these tools error, use `TodoWrite` for progress tracking. Plan files remain the source of truth; hydration is an optimization, not a requirement.

The **hydration pattern** bridges sessions:

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

- **Hydrate:** Read plan files → TaskCreate per unchecked `[ ]` item
- **Work:** TaskUpdate tracks in_progress/completed in real-time
- **Sync-back:** Update `[ ]` → `[x]` in phase files, update plan.md frontmatter status

## When to Create Tasks

**Default:** On — auto-hydrate after plan files are written
**Skip with:** `--no-tasks` flag in planning request
**3-Task Rule:** <3 phases → skip tasks (overhead exceeds benefit)

| Scenario | Tasks? | Why |
|----------|--------|-----|
| Multi-phase feature (3+ phases) | Yes | Track progress, enable parallel |
| Complex dependencies between phases | Yes | Automatic unblocking |
| Plan will be executed by cook | Yes | Seamless handoff |
| Single-phase quick fix | No | Just do it directly |
| Trivial 1-2 step plan | No | Overhead not worth it |

## Task Creation Patterns

### Phase-Level TaskCreate

```
TaskCreate(
  subject: "Setup environment and dependencies",
  activeForm: "Setting up environment",
  description: "Install packages, configure env, setup database. See phase-01-setup.md",
  metadata: { phase: 1, priority: "P1", effort: "2h",
              planDir: "plans/260205-auth/", phaseFile: "phase-01-setup.md" }
)
```

### Critical Step TaskCreate

For high-risk/complex steps within phases:

```
TaskCreate(
  subject: "Implement OAuth2 token refresh",
  activeForm: "Implementing token refresh",
  description: "Handle token expiry, refresh flow, error recovery",
  metadata: { phase: 3, step: "3.4", priority: "P1", effort: "1.5h",
              planDir: "plans/260205-auth/", phaseFile: "phase-03-api.md",
              critical: true, riskLevel: "high" },
  addBlockedBy: ["{phase-2-task-id}"]
)
```

## Metadata & Naming Conventions

**Required metadata:** `phase`, `priority` (P1/P2/P3), `effort`, `planDir`, `phaseFile`
**Optional metadata:** `step`, `critical`, `riskLevel`, `dependencies`

**subject** (imperative): Action verb + deliverable, <60 chars
- "Setup database migrations", "Implement OAuth2 flow", "Create user profile endpoints"

**activeForm** (present continuous): Matches subject in -ing form
- "Setting up database", "Implementing OAuth2", "Creating user profile endpoints"

**description**: 1-2 sentences, concrete deliverables, reference phase file

## Dependency Chains

```
Phase 1 (no blockers)              ← start here
Phase 2 (addBlockedBy: [P1-id])    ← auto-unblocked when P1 completes
Phase 3 (addBlockedBy: [P2-id])
Step 3.4 (addBlockedBy: [P2-id])   ← critical steps share phase dependency
```

Use `addBlockedBy` for forward references ("I need X done first").
Use `addBlocks` when creating parent first ("X blocks these children").

## Cook Handoff Protocol

### Same-Session (planning → cook immediately)

1. Planning hydrates tasks → tasks exist in session
2. Cook Step 3: `TaskList` → finds existing tasks → picks them up
3. Cook skips re-creation, begins implementation directly

### Cross-Session (new session, resume plan)

1. User runs `/ck:cook path/to/plan.md` in new session
2. Cook Step 3: `TaskList` → empty (tasks died with old session)
3. Cook reads plan files → re-hydrates from unchecked `[ ]` items
4. Already-checked `[x]` items = done, skip those

### Sync-Back (cook Step 6)

1. `TaskUpdate` marks all session tasks complete.
2. `project-manager` subagent runs full-plan sync-back:
   - Sweep all `phase-XX-*.md` files.
   - Reconcile completed tasks by metadata (`phase`, `phaseFile`).
   - Backfill stale completed checkboxes `[ ]` → `[x]` across all phases (not only current phase).
   - Update `plan.md` status/progress from actual checkbox state.
3. If any completed task cannot be mapped to a phase file, report unresolved mappings before claiming completion.
4. Git commit captures the state transition for next session.

## Quality Checks

After task hydration, verify:
- Dependency chain has no cycles
- All phases have corresponding tasks
- Required metadata fields present (phase, priority, effort, planDir, phaseFile)
- Task count matches unchecked `[ ]` items in plan files
- Output: `✓ Hydrated [N] phase tasks + [M] critical step tasks with dependency chain`