Adds basic task management tools.
This commit is contained in:
@@ -1,155 +1,67 @@
|
||||
---
|
||||
name: task-management
|
||||
description: >-
|
||||
Manage, query, create, triage, research, and update project tasks using the
|
||||
repository's task CLI scripts in scripts/ (get-tasks, get-task, add-task,
|
||||
update-task, update-tasks, triage, research) and docs/tasks.md. Activate this
|
||||
skill whenever reading, creating, editing, prioritizing, or updating tasks,
|
||||
checklists, or project progress.
|
||||
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 Skill
|
||||
# Task Management
|
||||
|
||||
This skill provides operational guidelines and procedures for managing project tasks using the automation scripts in `scripts/` and the Single Source of Truth (SSOT) document `docs/tasks.md`.
|
||||
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
|
||||
|
||||
## Quick Reference & Environment Setup
|
||||
|
||||
To make scripts available on your `PATH` and load shell aliases:
|
||||
The optional CLI tools require Python 3.9+ and Bash or Zsh:
|
||||
|
||||
```bash
|
||||
source ./scripts/env.sh
|
||||
```
|
||||
|
||||
> **Note**: For local configurations that should not be committed (such as custom environment variables, agent endpoints, or tokens), create a `scripts/env.local.sh` or `.env.local` file. It will be automatically sourced by `env.sh` and is ignored by Git.
|
||||
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`.
|
||||
|
||||
---
|
||||
|
||||
## Core Procedures
|
||||
|
||||
### 1. Querying and Inspecting Tasks
|
||||
|
||||
- **List active pending tasks**:
|
||||
```bash
|
||||
./scripts/get-tasks
|
||||
```
|
||||
- **List tasks in Planning and Triage**:
|
||||
```bash
|
||||
./scripts/get-tasks --planning
|
||||
# or alias: get-planning-tasks
|
||||
```
|
||||
- **List all tasks**:
|
||||
```bash
|
||||
./scripts/get-tasks --all
|
||||
```
|
||||
- **Filter tasks**:
|
||||
```bash
|
||||
./scripts/get-tasks --accept "Status:In Progress"
|
||||
./scripts/get-tasks --reject "Project:Android"
|
||||
./scripts/get-tasks --sort asc
|
||||
```
|
||||
- **Inspect a specific task**:
|
||||
```bash
|
||||
./scripts/get-task OT-001
|
||||
# Output as JSON:
|
||||
./scripts/get-task OT-001 --json
|
||||
# View description and checklist only:
|
||||
./scripts/get-task OT-001 --description-only
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Creating New Tasks
|
||||
|
||||
Use `add-task` to add a new entry to `docs/tasks.md`. The script automatically assigns the next monotonic ID and re-synchronizes the summary table:
|
||||
## Querying
|
||||
|
||||
```bash
|
||||
./scripts/add-task "Task Title" --project=<project-key> --type=<type> --status=<status> -d "Description text"
|
||||
./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
|
||||
```
|
||||
|
||||
**Common Flags**:
|
||||
- `-p`, `--project`: Project value from frontmatter (e.g., `example-project`, `android`, `ios`, `shared`).
|
||||
- `-t`, `--type`: Task type (`feature`, `bug`, `chore`, `lint`). Default: `feature`.
|
||||
- `-s`, `--status`: Initial status (`planning`, `triage`, `pending`, `in_progress`, `done`, `blocked`, `cancelled`, `research`). Default: `triage`.
|
||||
- `-d`, `--description`: Initial description and markdown checklist items.
|
||||
- `--subproject`: Subproject name if applicable.
|
||||
## Creating and Updating
|
||||
|
||||
---
|
||||
|
||||
### 3. Updating Tasks
|
||||
|
||||
Modify task attributes, title, status, and checklist items using `update-task`:
|
||||
|
||||
- **Change status**:
|
||||
```bash
|
||||
./scripts/update-task OT-001 --status in_progress
|
||||
./scripts/update-task OT-001 --status done
|
||||
```
|
||||
- **Update title or description**:
|
||||
```bash
|
||||
./scripts/update-task OT-001 --title "Updated Descriptive Title"
|
||||
./scripts/update-task OT-001 --description "New full description text"
|
||||
```
|
||||
- **Append checklist items or notes**:
|
||||
```bash
|
||||
./scripts/update-task OT-001 --append-description "- [ ] New requirement step"
|
||||
```
|
||||
- **Check/uncheck checklist items**:
|
||||
```bash
|
||||
# Check all items:
|
||||
./scripts/update-task OT-001 --check-all
|
||||
# Check specific item by keyword:
|
||||
./scripts/update-task OT-001 --check-items "Define initial requirements"
|
||||
# Uncheck all items:
|
||||
./scripts/update-task OT-001 --uncheck-all
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Synchronizing the Document
|
||||
|
||||
If tasks are modified or if table alignment needs re-calculation, run `update-tasks`:
|
||||
Read valid project/type/status values from frontmatter before invoking:
|
||||
|
||||
```bash
|
||||
./scripts/update-tasks
|
||||
./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
|
||||
```
|
||||
|
||||
This script:
|
||||
1. Re-indexes and sorts all detailed task chunks strictly by numeric ID.
|
||||
2. Re-renders the **Overall Progress Table** (`#tasks-list`).
|
||||
3. Re-renders the metadata enum tables (**Projects**, **Task Statuses**, **Task Types**) based on frontmatter.
|
||||
Use `--epic` or `--subproject` only with values defined in frontmatter.
|
||||
Numbers and configured prefixed IDs are accepted.
|
||||
|
||||
---
|
||||
## Synchronization and Review
|
||||
|
||||
### 5. Running Triage & Research Workflows
|
||||
|
||||
- **Triage a task**:
|
||||
```bash
|
||||
./scripts/triage OT-001
|
||||
./scripts/triage OT-001 --agy
|
||||
```
|
||||
- **Research a task**:
|
||||
```bash
|
||||
./scripts/research OT-001
|
||||
./scripts/research OT-001 --agy
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Operational Rules & Best Practices
|
||||
|
||||
1. **Single Source of Truth (SSOT)**:
|
||||
- The `<a id="ot-XXX" class="task" data-project="..." data-status="..." data-task-type="..."></a>` anchor tag in `## Detailed Tasks` is the canonical record.
|
||||
- **Never manually edit the summary table** in `docs/tasks.md`. Always modify task entries using `update-task` or run `update-tasks` after editing details.
|
||||
2. **Lifecycle Discipline**:
|
||||
- `planning`: Scoping and defining requirements.
|
||||
- `triage`: Prioritizing and deciding architecture.
|
||||
- `pending`: Clear scope, ready for execution.
|
||||
- `in_progress`: Work actively being executed.
|
||||
- `done`: All requirements verified and complete.
|
||||
- `blocked`: Waiting on an unresolved external dependency.
|
||||
- `cancelled`: No longer applicable.
|
||||
- `research`: Technical investigation needed before planning.
|
||||
3. **Verification**:
|
||||
- Always run `./scripts/get-tasks` or `./scripts/get-task <ID>` after updating to verify that status transitions and checklist updates have persisted accurately.
|
||||
- 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.
|
||||
|
||||
Reference in New Issue
Block a user