---
name: task-management
description: "Manage, query, create, triage, research, and update project tasks using scripts/ and docs/tasks.md. Use when reading, creating, editing, prioritizing, or updating tasks, checklists, or project progress for any kind of project."
---

# Task Management

Read [the script guide](../../../scripts/README.md) and
[the tracker](../../../docs/tasks.md). Use its configured prefix, project keys,
statuses, and types, not an assumed project or software stack.
Examples below use task numbers so they work with any prefix.

## Environment

The optional CLI tools require Python 3.9+ and Bash or Zsh:

```bash
source ./scripts/env.sh
```

Keep local overrides in ignored `scripts/env.sh.local` or `.env`. These are
trusted shell scripts. `TASKS_FILE` chooses the tracker; `TASK_ID_PREFIX`
overrides its prefix. All task commands accept `-f /path/to/tasks.md`.

## Querying

```bash
./scripts/get-tasks
./scripts/get-tasks --all
./scripts/get-tasks --planning
./scripts/get-tasks --accept "Status:Ready"
./scripts/get-task 1
./scripts/get-task 1 --json
./scripts/get-task 1 --description-only
```

## Creating and Updating

Read valid project/type/status values from frontmatter before invoking:

```bash
./scripts/add-task "Task Title" --project example-project --type task --status triage -d "Description and review criteria"
./scripts/update-task 1 --status in_progress
./scripts/update-task 1 --title "Updated Title"
./scripts/update-task 1 --append-description "- [ ] Additional criterion"
./scripts/update-task 1 --check-all
./scripts/update-task 1 --status testing
```

Use `--epic` or `--subproject` only with values defined in frontmatter.
Numbers and configured prefixed IDs are accepted.

## Synchronization and Review

- Anchor attributes in Detailed Tasks are the canonical task metadata.
- Do not manually edit generated summary/enum tables. Run
  `./scripts/update-tasks` to regenerate them.
- Run `./scripts/get-task <number>` after edits to verify persisted values.
- `planning` / `triage` / `research` scope work; `ready` permits execution;
  `in_progress` tracks active work; `testing` awaits human verification.
- `testing` applies to any project, including writing and research. It need
  not involve automated tests. Humans confirm `done`.
- Optional `triage` / `research` helpers require a supported external agent CLI;
  normal task management does not.
- If the CLI runtime is unavailable, explain that limitation. With user
  agreement, maintain canonical task details in Markdown and ensure tables
  remain consistent; do not silently claim script verification succeeded.