At Zentao

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":"Root cause and result."}
{"resolution":"fixed","resolvedBuild":"trunk","comment":"Root cause: stale session cache; Fix: refresh it during renewal; Commit: 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; its comment is optional.

Usage

Read-only personnel and history queries

Interpret natural language; users do not need CLI flags. "查张三的任务" maps to list tasks "张三"; "查张三解决的 Bug" maps to list bugs "张三" --relation resolvedBy --status all; "查我完成的任务" maps to list tasks --relation finishedBy --status all. Use openedBy for created items and closedBy for items closed by the person. For all historical items still assigned to someone, use assignedTo with --status all. Completion is a relationship: finished/resolved items may have been reassigned or closed, so do not infer the finisher from assignedTo. Use an exact status only when requested (for example --status closed). Account matches take precedence over exact names. If a name is ambiguous, ask for the account. Authentication always uses the existing configuration.

These list queries are read-only. Requests to view, explain, or trace a commit also stop after reading the referenced Bug/Task, comments, and linked Story; do not enter the implementation workflow below. Extract bug/task IDs from the commit when present and use get directly. Do not infer a ZenTao account from a Git author without a matching directory entry or user clarification.

• /at-zentao bug <id> — handle a single bug.
• /at-zentao task <id> — handle a single task.
• /at-zentao story <id> — read requirement scope and acceptance context. This mode is read-only; do not implement a Story status or comment workflow.
• /at-zentao bugs — list bugs assigned to the configured account; let the user select one or more.
• /at-zentao tasks — list assigned tasks and let the user select.
• When the user asks to inspect another person's Bugs or Tasks, treat the named person as the query subject while keeping the configured account for authentication. Use a read-only query and state the accessible scope.
• When the user asks for completed, closed, or historical work, include that status range only for that request. Do not expand the default actionable list.
• /at-zentao export bug <id> or export task <id> — create a read-only, self-contained handoff bundle.

Treat text after an item id as a natural-language request. Recognize task lifecycle requests such as 开始, 暂停, 继续, start, pause, and resume, and time-entry requests such as 填工时, 记录工时, log hours, and worklog. Users do not need to know the internal CLI commands. Reuse any date, hours, or work description already supplied instead of asking twice. Recognize corrections to an existing time entry. Run hours, identify the record from returned ids and values, and ask when more than one record could match; never guess or call log-hours again to compensate for a mistake.

If a list response includes pager data showing more items than returned, tell the user the shown and total counts. Do not silently imply the list is complete. Do not browse through products/projects for the default personal list. For an explicit request about another person or historical work, use the narrowest supported read-only scope and never imply that a partial result is complete.

When a fetched Bug or Task has a positive story id, fetch that Story before planning the implementation. Use its spec and verify fields to identify scope, acceptance criteria, constraints, and non-goals. Keep the Bug or Task as the unit of work: never change, close, activate, or comment on the Story.

For a Task in wait, offer start when the user is about to work on it. For a Task in pause, offer resume; the CLI maps this to ZenTao's restart operation. Invoke pause only when the user explicitly asks or confirms that the work itself is paused; the end of a session or workday is not enough. These are status writes, so show the transition and optional comment and obtain explicit confirmation before invoking the CLI. Starting or resuming preserves the current hours and never implies new consumed time.