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)

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

Cross-Session (new session, resume plan)

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

Sync-Back (cook Step 6)

TaskUpdate marks all session tasks complete.
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.
If any completed task cannot be mapped to a phase file, report unresolved mappings before claiming completion.
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

5.8 KiB Raw Permalink Blame History