Adds basic task management tools.

scripts/README.md

@@ -1,67 +1,77 @@
 # Project Scripts
 
-This directory contains repository maintenance, task management, and release automation scripts for **Old Bear Battles**.
+Optional task-management tools for any kind of project. They require
+Python 3.9+ and Bash or Zsh, but no third-party Python packages. They do not
+prescribe the project's language, platform, or subject.
 
----
+Tasks live in [docs/tasks.md](../docs/tasks.md). Project identity and optional
+commands live in [project-config.json](../project-config.json).
 
-## Active Task Management Tooling
+## Environment
 
-All work items and backlog features are tracked directly in repository Markdown at [docs/tasks.md](file:///Users/tom/Projects/OldBearBattles/docs/tasks.md). The Python CLI scripts below provide fast query, insertion, update, and normalization capabilities:
-
-### `get-tasks`
-Lists tasks from `docs/tasks.md` with sorting, column selection, and flexible predicate filtering:
 ```bash
-./scripts/get-tasks                              # List all tasks sorted by ID (desc)
-./scripts/get-tasks --accept 'Status:Testing'    # List tasks currently awaiting verification
-./scripts/get-tasks -p                           # List tasks in Triage and Planning status
-./scripts/get-tasks --all                        # Show all tasks including Done and Cancelled
-./scripts/get-tasks --sort asc                   # Sort in ascending order
+source ./scripts/env.sh
 ```
 
-### `get-task <ID>`
-Displays detailed information, metadata fields, and full description for a specific task ID:
-```bash
-./scripts/get-task OB-206
-```
+This adds scripts to `PATH` and defines task aliases. It sources trusted local
+shell settings from `scripts/env.sh.local`, or `.env` if the first file is
+absent. Both are ignored by Git. An existing `TASKS_FILE` is preserved.
+`TASK_ID_PREFIX` overrides task frontmatter; the default prefix is `EX`.
+All task commands accept `-f /path/to/tasks.md`.
 
-### `add-task <title>`
-Appends a new task entry to `docs/tasks.md` with frontmatter and structured markdown anchor tags:
-```bash
-./scripts/add-task "Descriptive Title" -p cmn -t feature -s ready -d "Task description and criteria"
-```
-**Options**:
-- `-p, --project`: Project code (`vtt`, `cmn`, `platform`, `shared`, `brawl`)
-- `-t, --type`: Task type (`feature`, `bug`, `chore`)
-- `-s, --status`: Initial status (`triage`, `planning`, `ready`, `in_progress`, `testing`, `done`, `blocked`, `cancelled`)
-- `-d, --description`: Markdown description text
+## Query and Edit Tasks
 
-### `update-task <ID>`
-Updates status, checks off checklist items, or appends notes to a task:
-```bash
-./scripts/update-task OB-206 --status testing
-./scripts/update-task OB-206 --check-all
-./scripts/update-task OB-206 --append-description "### Implementation Notes:\n- Added test coverage."
-```
-
-### `update-tasks`
-Validates and normalizes `docs/tasks.md` tables, frontmatter, and anchor IDs:
 ```bash
+./scripts/get-tasks --all
+./scripts/get-tasks --accept 'Status:Testing'
+./scripts/get-tasks --planning
+./scripts/get-tasks --sort asc
+./scripts/get-task EX-001
+./scripts/get-task 1 --json
+./scripts/add-task "Describe the first deliverable" -p example-project -t task -s triage
+./scripts/update-task 1 --status ready
+./scripts/work-on-task 1 --start
+./scripts/update-task 1 --status testing --check-all
+./scripts/update-task 1 --append-description "- [ ] Additional review criterion"
 ./scripts/update-tasks
 ```
 
-### `triage` / `research`
-Interactive helpers for rapidly reviewing tasks in triage or conducting architectural research on backlog items.
+- `get-tasks`: triage tasks by default; `--all` includes completed work.
+  Supports column selection and filters; `--help` lists the options.
+- `get-task`: metadata and full description for a prefixed ID or task number.
+- `add-task`: assigns the next numeric ID. Supply a project key and type from
+  frontmatter; the legacy defaults are `shared` and `feature`.
+- `update-task`: edits metadata, descriptions, and checklist items.
+- `work-on-task`: validates readiness and optionally starts work.
+- `update-tasks`: regenerates summary/enum tables and normalizes IDs and links.
 
----
+`testing` means awaiting human verification, whether that is editorial review,
+a planning checklist, or software tests. Agents do not mark their own work
+`done`.
 
-## Release Tooling
+## Optional Agent Helpers
 
-- **`build-release`**: Automated release build pipeline (runs test suites, packages production build).
-- **`package-release`**: Distribution packaging script for reproducible standalone releases.
+```bash
+./scripts/triage 1 --hermes
+./scripts/research 1 --agy
+```
 
----
+These launch an installed Hermes or Antigravity CLI. Core task commands and
+tests do not need either. Select an agent with `--agent`, a shortcut above,
+or `TASK_AGENT`. Missing agents are reported as errors.
 
-## Note on `ot` (Open Tasks)
+`triage` accepts `planning` / `triage`; `research` accepts `research`.
+Their prompts read the shared JSON configuration and refer to
+[AGENTS.md](../AGENTS.md), rather than assuming a particular project or stack.
+An empty `commands` object means no project commands are configured. Configured
+commands are included as guidance, not executed by these helpers.
 
-> [!NOTE]
-> Any references to `ot` (Open Tasks) refer to an upcoming standalone task management tool that is currently under development and not yet released. In the meantime, all tasks in this repository are managed directly in [docs/tasks.md](file:///Users/tom/Projects/OldBearBattles/docs/tasks.md) using the scripts documented above.
+## Tooling Tests
+
+```bash
+python3 -m unittest discover -s scripts/tests -v
+```
+
+This validates the bundled tools, not your project's deliverables.
+No release scripts are provided: publishing or deployment should be added only
+when the project's needs are known.