hiro-task-manager-cli

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 (see Destructive operations).

Destructive operations

The following commands are destructive and must NEVER be invoked without an explicit, unambiguous user request in the current turn:

• tasks purge, lists purge, boards purge — permanent deletion, not recoverable.

Soft-deletes (tasks delete, lists delete, boards delete) are allowed only after:

1. The agent has shown the target entity to the user (via show, describe, or list) and confirmed it is the right one.
2. The user's intent to delete that specific entity is unambiguous.

Always prefer trash inspection and restore over re-creating an entity that was deleted by mistake.

For any destructive command that supports it, run with --dry-run first, then rerun with --yes only after the user confirms.

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.
• prefer hirotm --help and subcommand help when you need examples or docs links.
• Run commands from the intended workspace root.
• Inspect current state before making mutations.
• For paginated reads or search, prefer --count-only when you only need cardinality first.
• Use --client-name on mutating commands so changes are attributable.
• Treat delete, purge, and structural changes as sensitive.
• Prefer --dry-run first for delete, purge, and board structure changes, then rerun with --yes only when ready.
• Use --no-color when plain output is easier to inspect for one run.

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"

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.
• use tasks show <task-id> or lists show <list-id> to print one row by global id when you already know the id.

Finding/Adding/Updating Tasks

• When a user refers to an existing task, use tasks list with filters, tasks show, or query search 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.

Errors

• Prefer the machine-readable stderr code over parsing the error text.
• If stderr includes a hint, use it as the next recovery step.
• HTTP/API failures usually include better hint guidance than local argument-validation failures.

Server Operations

• Check Server Status with server status
• Start Server with server start --background
• Stop Server with server stop

References

• Server Commands - Start, stop, and check the server status.
• Boards Commands - Create, update, delete, list, describe, and configure boards.
• Lists Commands - List, show, add, update, move, delete, restore, and purge board lists.
• Tasks Commands - List, show, add, update, move, delete, restore, and purge tasks.
• Releases Commands - List, show, add, update, delete, and set-default releases.
• Trash Commands - Inspect trashed boards, lists, and tasks.
• Status Commands - List workflow statuses and their meanings.
• Search Commands - Full-text task search with query search.
• CLI Access Policy - Map commands to cliPolicy requirements and read/write permissions.
• Errors and Exit Codes - Exit codes, stderr fields, and common machine-readable codes.

Safety notes

• Prefer inspect-first workflows.
• Search before create when overlap is likely.
• Do not bypass the CLI by any other means than the hirotm CLI.
• Respect permission and policy failures instead of working around them unsafely.
• For destructive commands, see Destructive operations.

References

• Online Documentation