task

name	task
description	Creates, coordinates, or implements tasks. Use when the user references a task file (e.g. @docs/tasks/NNN-name/TASK.md), or asks to execute, run, start, implement, plan, create, or work on a task.

Task Workflow

Creating Tasks

Use the task creation script to generate new tasks:

pnpm run task:create -- "Task title here" [options]

Script options:

• --type - Task type: feature, bug, enhancement, chore, or research (optional)
• --status - Initial status: open, in-progress, blocked, completed, or cancelled (default: open)
• --milestone - Milestone directory name (optional)
• --id - Explicit task ID (normally auto-generated, avoid unless needed)

Example:

pnpm run task:create -- "Add user authentication" --type="feature"

Best practices:

• Always prefer using the task scripts over manually editing files
• When creating multiple top-level tasks, run sequentially (not in parallel) — task ID allocation is not concurrency-safe
• Fill out the task template with the information you have at hand — don't do extra research
• Review existing similar tasks to inform your writing
• Keep summaries and requirements clear and actionable
• Ask the user if you're unsure about task scope or details
• After creating the task, commit with: docs: added task NNN: short description

Updating Tasks

• Always run pnpm run task:validate -- <number> after updating a task's frontmatter

"Wrapping up" / Finishing Tasks

When you are asked to wrap up a task:

• Do a final review: summarize changed files, validation results, and any outstanding items. Ask for human approval.
• After receiving approval, mark the status as completed.
• Before filling in a task postmortem, use the /session-info command to get the list of models used during task execution. Record the model information from session info rather than guessing.
• If you are asked to commit the changes, use the conventional commit format appended with the issue number: <type>: description (#NNN)

"Wrap this worktree"

When you are asked to "wrap this worktree", you are expected to be running inside the worktree directory. Do this in order:

1. Run preflight & mergeability checks

pnpm run wt:wrap

The script reads the task number from the worktree's .worktree-info file (no task argument needed). It does not push or merge — it only:

• Confirms the task is marked completed (use pnpm run wt:wrap -- --allow-incomplete to skip)
• Confirms the worktree has no uncommitted changes
• Fetches origin/main and checks the branch is cleanly mergeable into main
• Runs preflight checks: type-check, lint, and test

If mergeability or any check fails, alert the user, investigate the conflicts/failures, and propose a solution — but do not make changes without approval.

2. Ask whether to mark the task complete

Ask the user whether the task should be marked as completed. If they confirm, update the status (pnpm run task:update -- <number> --status=completed), commit the docs change, then re-run pnpm run wt:wrap so the completed-status check passes. If the user declines, only proceed using --allow-incomplete if they explicitly want to open the PR anyway.

3. Write the PR description yourself

Do not auto-generate the description from commit logs. Build it by inspecting the actual work:

• Read the task's TASK.md (and any files in docs/tasks/<NNN-slug>/) for objective and scope.
• Run git diff origin/main...HEAD --stat and review the diff to understand what changed.

Write a concise PR description summarizing what the task accomplished, the key changes, and any reviewer notes or follow-ups.

4. Push the branch and open the PR

# Push the current branch
git push -u origin "$(git branch --show-current)"

# Check whether a PR already exists
gh pr list --head "$(git branch --show-current)" --base main --json number,url

# If none exists, create one targeting main (use --body-file for multi-line descriptions)
gh pr create --base main --head "$(git branch --show-current)" \
  --title "<task title>" \
  --body-file <your-description.md>

Report the PR URL to the user. If a PR already existed, report it and update its description if the scope has changed.

Quick orientation

Tasks live under docs/tasks/NNN-name/ with a TASK.md and an optional subtasks/ directory. The template is at docs/tasks/000-template/.

Status values

open · in-progress · blocked · completed · cancelled

When starting work on a task, mark its status as in-progress.

Milestones

Milestones group related tasks under a shared goal. They live at docs/milestones/NNN-name/MILESTONE.md. To associate a task with a milestone, set the milestone field in the task's frontmatter to the milestone directory name (e.g., 001-v1), or leave it null.

When working on a task whose milestone field is not null, read the corresponding milestone file before starting work:

docs/milestones/<milestone>/MILESTONE.md

Use the milestone's goal, scope, and notes as additional context when interpreting requirements, making design decisions, or scoping work. If the milestone file doesn't exist yet, note this and continue without it.

Completion criteria

A task is complete when all requirements and subtasks are satisfied, code is merged, and the user has given explicit approval. Do not mark a task completed without human sign-off.