task-manager

When to Use

Use this skill immediately after the user approves a plan for code changes. It creates the task folder, scaffolds files, records the plan and context, and updates the backlog.

Do not use for brainstorming or unapproved ideas.

Task Structure (authoritative)

Each task lives at:
.meridian/tasks/TASK-###/

Files inside (exact names):

• TASK-###.yaml — Task brief (objective, scope, constraints, acceptance criteria, deliverables, risks, out of scope, links)
• TASK-###-plan.md — Exact plan approved by the user (freeze this; changes require re‑approval)
• TASK-###-context.md — Relevant context (Why decisions were made), key files, timestamped progress notes (log decisions, blockers, links, PRs)

IDs: 3‑digit, zero‑padded, uppercase folder prefix: TASK-001, TASK-002, …

Preconditions

1. The user has explicitly approved the plan (or you have an approved summary of the plan).
2. You know the short, action‑oriented title (≤80 chars).
3. No secrets or PII are copied into task files.

Creating a Task

Step 1 — Create the folder and files

Run the helper script:

• python3 $CLAUDE_PROJECT_DIR/.claude/skills/task-manager/scripts/create-task.py
  • It will automatically create a new folder for a task with 3 files:
    • $CLAUDE_PROJECT_DIR/.meridian/tasks/TASK-###/TASK-###.yaml
    • $CLAUDE_PROJECT_DIR/.meridian/tasks/TASK-###/TASK-###-plan.md
    • $CLAUDE_PROJECT_DIR/.meridian/tasks/TASK-###/TASK-###-context.md

Step 2 — Populate files

• Read each file before writing (System limitation)
• Fill TASK-###.yaml using the Task Brief YAML Template.
• Paste the approved plan into TASK-###-plan.md
• Add an initial entry to TASK-###-context.md

Step 3 — Update the backlog

Append/update an entry in .meridian/task-backlog.yaml with:

• id, title, status: todo, priority, and the relative path to the task folder.

task-backlog.yaml — quick guide

• Purpose: Single source of truth for all tasks (status, priority, location).

• Structure: Top‑level key tasks:, each item is one task entry.

• When to add: Immediately after creating TASK-###; set status: todo.

• When to update: On start (in_progress), when blocked (blocked + reason in the task’s context file), and on completion (done).

• What to edit: status, priority

• Never: Rename id, delete finished tasks (mark done instead).

• Allowed values:

  • status: todo | in_progress | blocked | done
  • priority: P0 | P1 | P2 | P3 (P0 = highest)

• Consistency: id must match the folder name and the files inside it.

Example entry (recommended)

tasks:
  - id: TASK-037
    title: "Add cursor-based pagination to /api/orders"
    priority: P1
    status: in_progress
    path: ".meridian/tasks/TASK-037/"

During Execution

Status transitions

• todo → in_progress when you start coding.
• Optional: blocked when waiting on dependency/decision; record reason in context.
• in_progress → done when the Definition of Done is met.

What to update

1. TASK-###-context.md: Add timestamped notes for:
   • Decisions, tradeoffs, key files, and blocked reasons.
   • Links to PR(s), commit SHAs, builds, or dashboards.
   • “Memory candidates” (facts worth persisting) — flag with MEMORY:; then use memory-curator (never write memory.jsonl manually).
2. $CLAUDE_PROJECT_DIR/.meridian/task-backlog.yaml:
   • Update status.
3. TASK-###.yaml:

Finishing a Task (Definition of Done)

Mark done only when all are true:

• Code compiles; typecheck/lint/test/build pass.
• Tests added/updated for new behavior; critical flows covered.
• Docs updated where relevant (README/snippets/endpoint contracts).
• No secrets/PII in code, commits, or logs. UI/API changes meet accessibility/security checks.
• If schema/data changed: migration applied and rollback plan documented in the plan or context.
• TASK-###-context.md has a final note with the merged PR link(s).
• Run memory-curator to add any durable architectural decisions (don’t edit memory manually).
• Update .meridian/task-backlog.yaml to done.

Editing Scope or Plan

• Any material change to goals, acceptance criteria, or approach requires re‑approval.
• Update TASK-###-plan.md with a short “Amendment ” section describing the change.
• Log the reason and reference in TASK-###-context.md.

Splitting / Merging / Cancelling Tasks

• Split: Create new tasks, move relevant sections, and update backlog. In originals, add: “Superseded by: …”.
• Merge: Keep one task as primary; close the others as done with “Merged into: …” notes.
• Cancel: Set status to done with resolution: canceled; explain in context; keep history.