temp

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

@@ -0,0 +1,155 @@
+---
+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.
+---
+
+# 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:
+
+```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.
+
+---
+
+## 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:
+
+```bash
+./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**:
+  ```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`:
+
+```bash
+./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**:
+  ```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.