@hiroleague/taskmanager 0.0.1 → 0.0.2

package/skills/hiro-task-manager-cli/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: hiro-task-manager-cli
+description: Use this skill when working with Hiro Task Manager through the `hirotm` CLI to manage tasks, task lists and task boards.
+---
+
+# Hiro Task Manager CLI
+
+Use this skill when the user wants to work with Hiro Task Manager through the `hirotm` CLI to manage tasks, task lists and task boards.
+
+## Use this skill for
+- Creating, updating and deleting tasks.
+- Creating, updating and deleting task lists.
+- Managing boards.
+- listing, searching and filtering tasks, lists and boards.
+- Managing Hiro Task Manager server, to be able to operate on tasks, lists and boards.
+- Delete, purge or restore tasks, lists and boards.
+
+## Default operating workflow
+1. Navigate to intended workspace root.
+2. Initially make sure Hiro Task Manager server is running.
+3. Discover the boards, lists or tasks you need to work with.
+4. Narrow down to the entity you need to work with, using search or list/filter.
+5. Use (Identification) to identify yourself in all commands.
+6. Perform the smallest safe mutation using all the available data, 
+7. Show the resulting state after the change.
+
+## Core rules
+- Use `hirotm` cli command for all operations.
+- use `--help` to get help on any command or sub command `boards --help`, `boards describe --help`.
+- Run commands from the intended workspace root.
+- Inspect current state before making mutations.
+- Use `--client-name` on mutating commands so changes are attributable.
+- Treat delete, purge, and structural changes as sensitive.
+
+# Identification
+
+Identify yourself in all commands with `--client-name <your-name>`. Your name should reflect the Agent Name, ex: Cursor Agent, Github Copilot Agent, Claude Code Agent, Open Code Agent.
+If you are not sure, use a generic name "AI Agent"
+
+## Installation
+
+If command is not found, ask the user to [install](https://docs.hiroleague.com/task-manager/get-started/quick-start) it and configure it.
+
+# Discovery
+
+- use `boards list` to list all boards.
+- use `boards describe <id-or-slug>` to describe all or some board details.
+- use `tasks list --board <board-id-or-slug>` to list and filter tasks in a board.
+
+# Finding/Adding/Updating Tasks
+
+- When a user refers to an existing task, use `tasks list` with filers, or `search query` to find it.
+- If convenient, use limit, offset, fields, or quiet options to manage and the output shape.
+- When adding a task
+  - use any available information such as priority, task group, release, etc...
+  - Add proper title (80 characters max) and Emoji if relevant only.
+  - use Organized Markdown description if the task body is detailed.
+  - use mermaid diagrams if the task includes design diagrams or if the user requests it.
+  - If linking to a larger documents in the workspace, make sure to use a proper link from the workspace root.
+
+# Access
+
+If you are not allowed to access an entity or perform an operation due to CLI Access Control, explain the situation and suggest the user to give you the necessary permissions. Never attempt to bypass the CLI Access Control.
+
+# Server Operations
+
+- Check Server Status with `server status`
+- Start Server with `server start --background`
+- Stop Server with `server stop`
+
+## References
+
+- [Installation Guide](https://docs.hiroleague.com/task-manager/get-started/quick-start)
+- Server Commands - Start, stop, and check the server status.
+- [Boards Commands](reference/boards.md) - Create, update, delete, list, describe, and configure boards.
+- [Lists Commands](reference/lists.md) - List, add, update, move, delete, restore, and purge board lists.
+- [Tasks Commands](reference/tasks.md) - List, add, update, move, delete, restore, and purge tasks.
+- [Releases Commands](reference/releases.md) - List, show, add, update, and delete releases.
+- [Trash Commands](reference/trash.md) - Inspect trashed boards, lists, and tasks.
+- [Status Commands](reference/statuses.md) - List workflow statuses and their meanings.
+- [Search Commands](reference/search.md) - Full-text task search with `query search`.
+- [CLI Access Policy](reference/cli-access-policy.md) - Map commands to `cliPolicy` requirements and read/write permissions.
+- [Errors and Exit Codes](reference/errors.md) - Exit codes, stderr fields, and common machine-readable codes.
+
+
+
+**Safety notes**
+
+- Prefer inspect-first workflows.
+- Search before create when overlap is likely.
+- Do not purge unless intent is clearly explicit.
+- Do not bypass the CLI by any other means than the `hirotm` CLI.
+- Respect permission and policy failures instead of working around them unsafely.
+
+**References**
+
+- [Online Documentation](https://docs.hiroleague.com/task-manager/get-started/quick-start)

package/skills/hiro-task-manager-cli/reference/boards.md

@@ -0,0 +1,143 @@
+# Boards Commands
+
+Use `hirotm boards` to discover boards, inspect board structure, and manage board-level settings. Use `hirotm tasks list --board <id-or-slug>` for task rows; `boards describe` does not return tasks.
+
+
+## Shared arguments
+
+- `<id-or-slug>`: board numeric id or board slug.
+- `--yes`: use for non-interactive destructive or structural commands.
+
+### Text input variants
+
+Used by board create or update when setting descriptions.
+
+- `--description <text>`: inline text.
+- `--description-file <path>`: read text from file.
+- `--description-stdin`: read text from stdin.
+
+### JSON input variants
+
+Used by `boards configure groups` and `boards configure priorities`. Pass exactly one.
+
+- `--json <text>`: inline JSON.
+- `--file <path>`: read JSON from file.
+- `--stdin`: read JSON from stdin.
+
+## Commands
+
+### `boards list`
+
+Format:
+
+```bash
+hirotm boards list [--limit <n>] [--offset <n>] [--page-all] [--fields <keys>]
+```
+
+Use this to discover accessible boards before mutation.
+
+- `--limit <n>`: page size.
+- `--offset <n>`: skip rows.
+- `--page-all`: merge all pages.
+- `--fields <keys>`: project only selected fields.
+- Supports global `--quiet` with `--format ndjson`.
+
+### `boards describe <id-or-slug>`
+
+Format:
+
+```bash
+hirotm boards describe <id-or-slug> [--entities <csv>]
+```
+
+Use this to inspect one board without loading tasks.
+
+- Best source for `listId`, `groupId`, `priority`, `releaseId`, and status ids.
+- `--entities <csv>` accepts `list`, `group`, `priority`, `release`, `status`, `meta`.
+- Omitting `--entities` returns the standard entity sections without `meta`.
+- There is no `boards show`; pair `boards describe` with `tasks list --board` when task rows are needed.
+
+### `boards add [name]`
+
+Format:
+
+```bash
+hirotm boards add [name] [--emoji <text>] [description flags]
+```
+
+Create a new board.
+
+- `[name]`: board name. Optional.
+- `--emoji <text>`: emoji prefix for the board.
+- Description flags are listed once in `Text input variants`.
+
+### `boards update <id-or-slug>`
+
+Format:
+
+```bash
+hirotm boards update <id-or-slug> [--name <text>] [--emoji <text> | --clear-emoji] [description flags | --clear-description] [--board-color <preset> | --clear-board-color]
+```
+
+Update board identity or appearance. Pass at least one change.
+
+- `--name <text>`: rename the board.
+- `--emoji <text>` or `--clear-emoji`: set or clear emoji.
+- Description flags are listed once in `Text input variants`.
+- `--clear-description`: remove the description.
+- `--board-color <preset>`: one of `stone`, `cyan`, `azure`, `indigo`, `violet`, `rose`, `amber`, `emerald`, `coral`, `sage`.
+- `--clear-board-color`: remove the color preset.
+
+### `boards delete <id-or-slug>`
+
+Format:
+
+```bash
+hirotm boards delete <id-or-slug> --yes
+```
+
+Move a board to Trash.
+
+### `boards restore <id-or-slug>`
+
+Format:
+
+```bash
+hirotm boards restore <id-or-slug> --yes
+```
+
+Restore a trashed board.
+
+### `boards purge <id-or-slug>`
+
+Format:
+
+```bash
+hirotm boards purge <id-or-slug> --yes
+```
+
+Permanently delete a trashed board. This is irreversible.
+
+### `boards configure groups <id-or-slug>`
+
+Format:
+
+```bash
+hirotm boards configure groups <id-or-slug> [--json <text> | --file <path> | --stdin] --yes
+```
+
+Replace board task groups from JSON input.
+
+- JSON input variants are listed once in `JSON input variants`.
+
+### `boards configure priorities <id-or-slug>`
+
+Format:
+
+```bash
+hirotm boards configure priorities <id-or-slug> [--json <text> | --file <path> | --stdin] --yes
+```
+
+Replace board priorities from JSON input.
+
+- JSON input variants are listed once in `JSON input variants`.

package/skills/hiro-task-manager-cli/reference/cli-access-policy.md

@@ -0,0 +1,72 @@
+# CLI Access Policy
+
+Use this page to map `hirotm` commands to the board CLI policy checks enforced by Task Manager.
+
+## Core rule
+
+- `readBoard` is the baseline requirement for board-scoped commands.
+- Trash listings only return rows for boards the CLI can read.
+- If `readBoard` is off, board-scoped reads and writes fail for that board.
+
+## Policy flags
+
+- `readBoard`: read board-scoped data.
+- `createLists`: create new lists on a board.
+- `createTasks`: create new tasks on a board.
+- `manageCliCreatedLists`: manage lists created by the CLI.
+- `manageAnyLists`: manage lists regardless of creator.
+- `manageCliCreatedTasks`: manage tasks created by the CLI.
+- `manageAnyTasks`: manage tasks regardless of creator.
+- `manageStructure`: manage releases and board structure.
+- `deleteBoard`: delete, restore, and purge boards.
+
+## Command mapping
+
+### Board reads
+
+- `boards list`: `readBoard`
+- `boards describe`: `readBoard`
+
+### Board lifecycle
+
+- `boards delete`: `readBoard` + `deleteBoard`
+- `boards restore`: `readBoard` + `deleteBoard`
+- `boards purge`: `readBoard` + `deleteBoard`
+
+### List commands
+
+- `lists add`: `readBoard` + `createLists`
+- `lists delete`: `readBoard` + either `manageCliCreatedLists` for CLI-created lists or `manageAnyLists` for other lists
+- `lists restore`: `readBoard` + either `manageCliCreatedLists` for CLI-created lists or `manageAnyLists` for other lists
+- `lists purge`: `readBoard` + either `manageCliCreatedLists` for CLI-created lists or `manageAnyLists` for other lists
+
+### Task commands
+
+- `tasks add`: `readBoard` + `createTasks`
+- `tasks delete`: `readBoard` + either `manageCliCreatedTasks` for CLI-created tasks or `manageAnyTasks` for other tasks
+- `tasks restore`: `readBoard` + either `manageCliCreatedTasks` for CLI-created tasks or `manageAnyTasks` for other tasks
+- `tasks purge`: `readBoard` + either `manageCliCreatedTasks` for CLI-created tasks or `manageAnyTasks` for other tasks
+
+### Release commands
+
+- `releases list`: `readBoard`
+- `releases show`: `readBoard`
+- `releases add`: `readBoard` + `manageStructure`
+- `releases update`: `readBoard` + `manageStructure`
+- `releases delete`: `readBoard` + `manageStructure`
+
+### Search and trash
+
+- `query search` without `--board`: returns hits only from boards the CLI can read
+- `query search --board <id-or-slug>`: `readBoard` for that board
+- `trash list boards`: `readBoard` for each returned board
+- `trash list lists`: `readBoard` for each row's board
+- `trash list tasks`: `readBoard` for each row's board
+
+### Global commands
+
+- `statuses list`: not board-scoped
+
+## Practical note
+
+Use `hirotm boards describe <id-or-slug>` to inspect the current `cliPolicy` values before attempting a write.

package/skills/hiro-task-manager-cli/reference/errors.md

@@ -0,0 +1,85 @@
+# Errors and Exit Codes
+
+Use this page for how `hirotm` reports failures through exit codes and stderr payloads.
+
+## Failure output
+
+- With `--format ndjson`, failures are JSON on stderr.
+- With `--format human`, failures are plain text on stderr.
+- Prefer the machine-readable `code` field over parsing `error` text.
+
+## Common stderr fields
+
+- `error`: human-readable summary.
+- `code`: stable machine-readable identifier.
+- `retryable`: whether retry may succeed later.
+- `hint`: recovery hint, such as how to start the server.
+- `status`: HTTP status when the error came from the API.
+- `url`: request URL when relevant.
+- `serverCode`: original API code when the CLI normalized `code`.
+
+## Exit codes
+
+| Exit | Meaning | Typical action |
+| --- | --- | --- |
+| `0` | Success | Parse stdout and continue. |
+| `1` | Generic failure or unmapped server/API error | Read `error` and `code`; retry only if appropriate. |
+| `2` | Invalid CLI arguments | Fix flags or values; do not retry unchanged. |
+| `3` | Not found | Refresh ids, slugs, or file paths. |
+| `4` | Forbidden | Respect CLI policy; do not retry unchanged. |
+| `5` | Conflict | Skip create, rename differently, or resolve state conflict. |
+| `6` | Server unreachable | Start the server using the provided `hint`, then retry. |
+| `7` | Timeout | Retry after a delay. |
+| `8` | Version mismatch | Update the CLI or app. |
+| `9` | Bad request or validation failure | Fix the request shape or values. |
+| `10` | Unauthenticated | Configure auth when that flow exists. |
+
+## Common `code` values
+
+### API and permission codes
+
+- `bad_request`
+- `unauthenticated`
+- `forbidden`
+- `not_found`
+- `conflict`
+- `request_timeout`
+- `version_mismatch`
+- `rate_limited`
+- `internal_error`
+- `http_error`
+
+### Local validation codes
+
+- `missing_required`
+- `invalid_value`
+- `mutually_exclusive_options`
+- `conflicting_input_sources`
+- `conflicting_clear_with_input`
+- `invalid_json`
+- `invalid_input_shape`
+- `no_update_fields`
+- `release_not_found_by_name`
+- `emoji_validation_failed`
+
+### Connection and process codes
+
+- `server_unreachable`
+- `request_timeout`
+- `server_start_timeout`
+- `server_exited`
+- `no_managed_server`
+- `stale_pid`
+- `signal_failed`
+
+### Other useful codes
+
+- `file_not_found`
+- `response_inconsistent`
+- `internal_error`
+- `confirmation_required`
+- `confirmation_declined`
+
+## Recovery rule
+
+If the CLI exits with `6`, run the exact `hint` command from stderr, then retry.

package/skills/hiro-task-manager-cli/reference/lists.md

@@ -0,0 +1,106 @@
+# Lists Commands
+
+Use `hirotm lists` to inspect and manage board columns. Lists belong to a board, so most commands require `--board <id-or-slug>`.
+
+## Shared arguments
+
+- `--board <id-or-slug>`: target board id or slug.
+- `<list-id>`: numeric list id.
+- `--yes`: use for non-interactive delete, restore, and purge commands.
+
+### Position flags
+
+Used by `lists move`. Pass exactly one.
+
+- `--before <list-id>`: place before another list.
+- `--after <list-id>`: place after another list.
+- `--first`: move to the first position.
+- `--last`: move to the last position.
+
+## Commands
+
+### `lists list`
+
+Format:
+
+```bash
+hirotm lists list --board <id-or-slug> [--limit <n>] [--offset <n>] [--page-all] [--fields <keys>]
+```
+
+Use this to discover lists on a board before mutation.
+
+- `--limit <n>`: page size.
+- `--offset <n>`: skip rows.
+- `--page-all`: merge all pages.
+- `--fields <keys>`: project only selected fields.
+- Supports global `--quiet` with `--format ndjson`.
+
+### `lists add`
+
+Format:
+
+```bash
+hirotm lists add --board <id-or-slug> [name] [--emoji <text>]
+```
+
+Create a new list on a board.
+
+- `[name]`: list name. Optional.
+- `--emoji <text>`: emoji prefix for the list.
+
+### `lists update`
+
+Format:
+
+```bash
+hirotm lists update --board <id-or-slug> <list-id> [--name <text>] [--color <css> | --clear-color] [--emoji <text> | --clear-emoji]
+```
+
+Update list fields. Pass at least one change.
+
+- `--name <text>`: rename the list.
+- `--color <css>`: set a CSS color value.
+- `--clear-color`: remove the list color.
+- `--emoji <text>` or `--clear-emoji`: set or clear emoji.
+
+### `lists move`
+
+Format:
+
+```bash
+hirotm lists move --board <id-or-slug> <list-id> [--before <list-id> | --after <list-id> | --first | --last]
+```
+
+Reorder a list within a board.
+
+- Position flags are listed once in `Position flags`.
+
+### `lists delete`
+
+Format:
+
+```bash
+hirotm lists delete --board <id-or-slug> <list-id> --yes
+```
+
+Move a list to Trash.
+
+### `lists restore`
+
+Format:
+
+```bash
+hirotm lists restore <list-id> --yes
+```
+
+Restore a trashed list.
+
+### `lists purge`
+
+Format:
+
+```bash
+hirotm lists purge <list-id> --yes
+```
+
+Permanently delete a trashed list. This is irreversible.

package/skills/hiro-task-manager-cli/reference/releases.md

@@ -0,0 +1,87 @@
+# Releases Commands
+
+Use `hirotm releases` to inspect and manage board releases. Releases are board-level labels used to group tasks.
+
+## Shared arguments
+
+- `--board <id-or-slug>`: target board id or slug.
+- `<release-id>`: numeric release id.
+- `--yes`: use for non-interactive delete commands.
+
+### Shared list/read flags
+
+Used by `releases list` and partially by `releases show`.
+
+- `--limit <n>`: page size.
+- `--offset <n>`: skip rows.
+- `--page-all`: merge all pages.
+- `--fields <keys>`: project only selected fields.
+- `releases list` supports global `--quiet` with `--format ndjson`.
+
+### Shared update fields
+
+Used by `releases add` and `releases update`.
+
+- `--name <text>`: release name.
+- `--color <css>` or `--clear-color`: set or clear release color.
+- `--release-date <text>` or `--clear-release-date`: set or clear the release date.
+
+## Commands
+
+### `releases list`
+
+Format:
+
+```bash
+hirotm releases list --board <id-or-slug> [--limit <n>] [--offset <n>] [--page-all] [--fields <keys>]
+```
+
+Use this to discover releases on a board before setting `--release` or `--release-id` on tasks.
+
+### `releases show`
+
+Format:
+
+```bash
+hirotm releases show --board <id-or-slug> <release-id> [--fields <keys>]
+```
+
+Inspect one release by id.
+
+### `releases add`
+
+Format:
+
+```bash
+hirotm releases add --board <id-or-slug> --name <text> [--color <css> | --clear-color] [--release-date <text> | --clear-release-date]
+```
+
+Create a release on a board.
+
+- Shared update fields are listed once in `Shared update fields`.
+- Release names must be unique per board.
+
+### `releases update`
+
+Format:
+
+```bash
+hirotm releases update --board <id-or-slug> <release-id> [--name <text>] [--color <css> | --clear-color] [--release-date <text> | --clear-release-date]
+```
+
+Update release fields. Pass at least one change.
+
+- Shared update fields are listed once in `Shared update fields`.
+
+### `releases delete`
+
+Format:
+
+```bash
+hirotm releases delete --board <id-or-slug> <release-id> [--move-tasks-to <id>] --yes
+```
+
+Delete a release from a board.
+
+- `--move-tasks-to <id>`: move tagged tasks to another release before deletion.
+- If omitted, tasks on that release become untagged.

package/skills/hiro-task-manager-cli/reference/search.md

@@ -0,0 +1,38 @@
+# Search Commands
+
+Use `hirotm query search` for full-text task search across indexed task fields such as title, body, list name, group label, and status label.
+
+## Command
+
+### `query search <query...>`
+
+Format:
+
+```bash
+hirotm query search <query...> [--board <id-or-slug>] [--limit <n>] [--offset <n>] [--page-all] [--no-prefix] [--fields <keys>]
+```
+
+Search tasks by text.
+
+- `<query...>`: search text. Quote phrases when needed.
+- `--board <id-or-slug>`: limit hits to one board.
+- `--limit <n>`: page size. Defaults to `20` when omitted.
+- `--offset <n>`: skip rows.
+- `--page-all`: merge all pages.
+- `--no-prefix`: disable automatic prefix matching on the last token.
+- `--fields <keys>`: project only selected fields.
+- Supports global `--quiet` with `--format ndjson`.
+
+## Search behavior
+
+- By default, the last token is prefix-matched unless `--no-prefix` is used.
+- Results are ordered by relevance score, best matches first.
+- Invalid search syntax returns an error.
+
+## Result fields
+
+- `taskId`: global task id.
+- `boardSlug` / `boardName`: where the task lives.
+- `listName`: list name for the hit.
+- `snippet`: short excerpt with match context.
+- `score`: relevance score; lower is better.

package/skills/hiro-task-manager-cli/reference/statuses.md

@@ -0,0 +1,25 @@
+# Statuses Commands
+
+Use `hirotm statuses` to inspect the global workflow status table. These status ids are the values used by task commands for `--status`.
+
+## Commands
+
+### `statuses list`
+
+Format:
+
+```bash
+hirotm statuses list [--fields <keys>]
+```
+
+List all workflow statuses in display order.
+
+- `--fields <keys>`: project only selected fields.
+- Supports global `--quiet` with `--format ndjson`.
+
+## Field meaning
+
+- `statusId`: value accepted by task commands for `--status`.
+- `label`: human-readable status name.
+- `sortOrder`: workflow display order.
+- `isClosed`: whether the status counts as closed.