base/.agents/skills/task-management/SKILL.md

name, description

name	description
task-management	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.

Task Management Skill

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.

---

Quick Reference & Environment Setup

To make scripts available on your PATH and load shell aliases:

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.

---

Core Procedures

1. Querying and Inspecting Tasks

• List active pending tasks:

  ./scripts/get-tasks
  

• List tasks in Planning and Triage:

  ./scripts/get-tasks --planning
  # or alias: get-planning-tasks
  

• List all tasks:

  ./scripts/get-tasks --all
  

• Filter tasks:

  ./scripts/get-tasks --accept "Status:In Progress"
  ./scripts/get-tasks --reject "Project:Android"
  ./scripts/get-tasks --sort asc
  

• Inspect a specific task:

  ./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:

./scripts/add-task "Task Title" --project=<project-key> --type=<type> --status=<status> -d "Description text"

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.

---

3. Updating Tasks

Modify task attributes, title, status, and checklist items using update-task:

• Change status:

  ./scripts/update-task OT-001 --status in_progress
  ./scripts/update-task OT-001 --status done
  

• Update title or description:

  ./scripts/update-task OT-001 --title "Updated Descriptive Title"
  ./scripts/update-task OT-001 --description "New full description text"
  

• Append checklist items or notes:

  ./scripts/update-task OT-001 --append-description "- [ ] New requirement step"
  

• Check/uncheck checklist items:

  # 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:

./scripts/update-tasks

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.

---

5. Running Triage & Research Workflows

• Triage a task:

  ./scripts/triage OT-001
  ./scripts/triage OT-001 --agy
  

• Research a task:

  ./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.