/at-zentao

name: at-zentao
description: "Handle ZenTao (禅道) Bugs and Tasks end to end, including updating or writing back an item after code changes, managing Task status and hours, and reading linked Stories. Use for referenced ZenTao items, requirements, status changes, time entries, or post-implementation synchronization."
argument-hint: "bug <id> [request] | task <id> [request] | story <id> | bugs | tasks | export bug|task <id>"

ZenTao Bug/Task Workflow

Secure CLI boundary

This Skill bundles `scripts/zentao-cli.mjs`. Resolve the Skill root as the directory containing this `SKILL.md`, then run the script with Node using its resolved path from any working directory:

node <skill-root>/scripts/zentao-cli.mjs <command>

The script is the only component allowed to read ZenTao configuration, exchange credentials for a token, send authenticated requests, or inspect raw error responses. Run it directly without reading or copying its source into the conversation. Never read `~/.agent-tools/config.jsonc`, print ZenTao env vars, call the token endpoint, or construct a ZenTao `Token` header yourself.

The CLI emits only sanitized JSON. Treat a nonzero exit as a stopped ZenTao operation and report its safe `error`, `message`, and optional HTTP `status`. Do not work around the CLI with `curl` when authentication or an endpoint fails.

Configuration

The CLI reads the global `~/.agent-tools/config.jsonc`, or `$AGENT_TOOLS_HOME/config.jsonc` when `AGENT_TOOLS_HOME` is set. It never reads repository-level configuration. Basic configuration:

{
  "zentao": {
    "url": "https://zentao.example.com",
    "account": "user",
    "password": "your-password"
  }
}

To avoid storing the password in the file, use `"password": { "env": "ZENTAO_PASSWORD" }` and set that environment variable. Direct env overrides are `ZENTAO_URL`, `ZENTAO_ACCOUNT`, and `ZENTAO_PASSWORD`. `ZENTAO_TOKEN` may be used instead of password exchange; it is accepted only from the environment.

When configuration is missing, tell the user which file to edit and show the template above. Never ask them to paste a password or token into chat, and do not edit or inspect the file after they add credentials. Ask them to say "done", then validate with:

node <skill-root>/scripts/zentao-cli.mjs doctor

Report only whether the connection succeeded and whether authentication used `token` or `account-password`.

CLI commands

Read-only commands:

node <skill-root>/scripts/zentao-cli.mjs list bugs
node <skill-root>/scripts/zentao-cli.mjs list tasks
node <skill-root>/scripts/zentao-cli.mjs list stories
node <skill-root>/scripts/zentao-cli.mjs list tasks "person account or exact name"
node <skill-root>/scripts/zentao-cli.mjs list tasks "person" --relation finishedBy --status all
node <skill-root>/scripts/zentao-cli.mjs list bugs "person" --relation resolvedBy --status all
node <skill-root>/scripts/zentao-cli.mjs list stories "person account or exact name"
node <skill-root>/scripts/zentao-cli.mjs get bug <id>
node <skill-root>/scripts/zentao-cli.mjs get task <id>
node <skill-root>/scripts/zentao-cli.mjs get story <id>
node <skill-root>/scripts/zentao-cli.mjs get bug <id> --download-dir <path>
node <skill-root>/scripts/zentao-cli.mjs hours task <id>

`get` downloads token-gated inline images and attachments into a temporary directory by default and returns only local paths. Inspect those local files; never pass the original ZenTao URL to an image tool. For Bugs and Tasks, a configured `zentao.commentPrompt` is returned as `writeback.commentPrompt`. Use it only when drafting a write-back comment; it is not item data or an existing comment. `get` also returns safe `comments` from action history, keeping only id, actor, action, date, and non-empty comment. An omitted `comments` means actions were unavailable; an empty array means actions were available but contained no comments.

Write commands require JSON on stdin and are allowed only after the explicit confirmation steps below:

node <skill-root>/scripts/zentao-cli.mjs comment bug <id>
node <skill-root>/scripts/zentao-cli.mjs comment task <id>
node <skill-root>/scripts/zentao-cli.mjs resolve bug <id>
node <skill-root>/scripts/zentao-cli.mjs start task <id>
node <skill-root>/scripts/zentao-cli.mjs pause task <id>
node <skill-root>/scripts/zentao-cli.mjs resume task <id>
node <skill-root>/scripts/zentao-cli.mjs log-hours task <id>
node <skill-root>/scripts/zentao-cli.mjs edit-hours task <id> <effort-id>
node <skill-root>/scripts/zentao-cli.mjs finish task <id>

Input shapes:

{"comment":"Cause and result."}
{"resolution":"fixed","resolvedBuild":"trunk","comment":"Cause: stale session cache\nFix: refresh it during renewal\nScope: requests after session renewal\nTest suggestions: renew a session, then confirm the next request succeeds\nCommit: abc1234"}
{"realStarted":"2026-08-11 09:00:00","comment":"Started implementation."}
{"date":"2026-08-11","consumed":2,"left":14,"work":"Implemented the first part of the task."}
{"work":"Corrected work description, commit abc1234."}
{"currentConsumed":1.5,"realStarted":"2026-08-11 09:00:00","finishedDate":"2026-08-11 10:30:00","comment":"Completed: implemented session renewal; Commit: abc1234."}

For `duplicate`, also pass `"duplicateBug": <id>`. Send JSON through stdin, not as a command-line argument. The CLI handles UTF-8 form encoding and computes a task's total consumed hours from its current ZenTao value. `start`, `pause`, and `resume` accept an optional `comment`; `start` also accepts `realStarted` and otherwise uses the current time. The CLI preserves the task's current hours when starting or resuming it. `log-hours` defaults `date` to today, requires positive remaining hours, and keeps the task open. `hours` is read-only. `edit-hours` preserves omitted fields from the existing record and updates it through ZenTao's native effort workflow. Use `finish` when the task is complete;