# Project Scripts

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

## Environment

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

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

## Query and Edit Tasks

```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
```

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

## Optional Agent Helpers

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

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

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