maintain-tasks

# Task Management for Session Continuity Tasks are your **working memory that survives compaction**. Use them to maintain intent, sequence, and coordination across the natural lifecycle of a session. ## Tasks vs Issue Trackers | Tool | Purpose | Scope | |------|---------|-------| | **Tasks** | Session/project working memory | Current effort, active coordination | | **Linear/GitHub** | Team-visible project management | Cross-session, multi-person tracking | Tasks are NOT a replacement for filing issues. They are your **local execution state** — what you're doing now, what comes next, who (which agent) is responsible. **Sync pattern:** 1. Pull work from Linear/GitHub into Tasks for execution 2. Work through Tasks within the session 3. Update Linear/GitHub at completion boundaries ## Why Tasks Survive Compaction When context compacts, conversation history gets summarized. But Tasks persist in full: - Task subjects and descriptions remain intact - Dependencies (`blockedBy`, `blocks`) preserved - Status (`pending`, `in_progress`, `completed`) preserved - **Subagent assignments preserved** (critical — see below) This means after compaction, you can read TaskList and know exactly where you were, what's next, and who's responsible. ## Subagent Assignment (Critical) **Always assign subagents explicitly in task subjects.** After compaction, nuanced instructions like "have the reviewer check this" can lose fidelity. Explicit assignment survives: ``` [engineer] Implement auth refresh endpoint [reviewer] Review auth implementation for security [tester] Validate auth flow end-to-end ``` The `[agent-name]` prefix is not decoration — it's **recoverable intent**. After compaction, you can scan TaskList and immediately know which agent handles each task. ### Assignment Patterns ``` # Explicit agent assignment [engineer] Build the feature [analyst] Research the approach [reviewer] Check for issues [tester] Validate behavior # Background agents (include task ID for retrieval) [reviewer:background] Security audit (task-id: abc123) # Resumable agents (include agent ID) [analyst] Continue research (resume: a7227ac) ``` ## Task Dependencies Use `blockedBy` and `blocks` to encode sequence: ``` Task 1: [analyst] Research auth patterns Task 2: [engineer] Implement auth flow (blockedBy: 1) Task 3: [reviewer] Review implementation (blockedBy: 2) Task 4: [tester] Validate auth (blockedBy: 3) ``` After compaction, dependencies tell you what's actionable (no blockers) vs what's waiting. ## Required Discipline ### When Starting Work 1. **Check TaskList first** — understand current state 2. **Create tasks for non-trivial work** — 3+ steps means use Tasks 3. **Set status to `in_progress`** before beginning 4. **Assign subagent explicitly** in the subject ### When Completing Work 1. **Mark completed immediately** — don't batch 2. **Add discovered follow-ups** as new tasks 3. **Check for unblocked tasks** — completing one may unblock others ### Before Compaction As context fills, ensure Tasks reflect: - What's done (completed tasks) - What's active (single `in_progress` task) - What's discovered (new tasks from implementation) - What's blocked and why ## Task Structure ``` Subject: [agent] Imperative action description Description: - Context needed to execute - Acceptance criteria - Any constraints or considerations ActiveForm: Present continuous for spinner ("Implementing auth flow") ``` **Subject format:** `[agent-name] Verb the thing` - `[engineer] Implement JWT refresh logic` - `[reviewer] Audit auth module for vulnerabilities` - `[analyst] Research rate limiting approaches` **Description includes:** - Enough context for the assigned agent to proceed independently - Clear done criteria - Dependencies or blockers if not captured in `blockedBy` ## Coordination Patterns ### Sequential Handoff ``` 1. [analyst] Research → creates findings 2. [engineer] Implement → uses findings (blockedBy: 1) 3. [reviewer] Review → checks implementation (blockedBy: 2) 4. [tester] Validate → confirms behavior (blockedBy: 3) ``` ### Parallel Execution ``` 1. [engineer] Implement feature A 2. [engineer] Implement feature B 3. [tester] Integration tests (blockedBy: 1, 2) ``` Tasks 1 and 2 can run in parallel; Task 3 waits for both. ### Iterative Refinement ``` 1. [engineer] Initial implementation 2. [reviewer] Review round 1 (blockedBy: 1) 3. [engineer] Address feedback (blockedBy: 2) 4. [reviewer] Review round 2 (blockedBy: 3) ``` ## Anti-Patterns | Anti-Pattern | Why It Fails | Better Approach | |--------------|--------------|-----------------| | No agent assignment | Lost after compaction | Always prefix with `[agent]` | | Vague subjects | Can't recover intent | Specific, actionable subjects | | Batching completions | State becomes stale | Mark done immediately | | Skipping for "quick" tasks | Consistency matters | If 3+ steps, use Tasks | | No dependencies | Unclear sequence | Encode with `blockedBy` | ## Rules ALWAYS: - Assign subagent explicitly in task subject: `[agent] Task description` - Use dependencies to encode sequence - Mark `in_progress` before starting, `completed` when done - Check TaskList after compaction to recover state NEVER: - Use Tasks as a replacement for Linear/GitHub issues - Leave multiple tasks `in_progress` simultaneously - Skip agent assignment ("the main agent will figure it out") - Batch task completions at end of work