SKILL: ZenTao

Enable AI Agents to operate the ZenTao system via natural language. Based on

scripts/*.js

(Node.js scripts) to call ZenTao RESTful API v2.

Quick Start

bash

# Configure environment variables
export CHANDAO_URL="https://your-zentao.com"
export CHANDAO_ACCOUNT="your_account"
export CHANDAO_PASSWORD="your_password"

# Verify configuration
node scripts/auth.js --action list-products

# Basic usage
node scripts/<module>.js --action <action> [--args]

Security Guidelines

Never expose
```
CHANDAO_ACCOUNT
```
or
```
CHANDAO_PASSWORD
```
in chat, files, code, or logs.
All API calls must go through scripts — never call the ZenTao API directly.
Never read
```
.env
```
files or environment variables containing credentials in conversation output.
Authentication is automatically managed by
```
auth.js
```
(auto-login on first request, local Token file caching, auto-refresh on 401).

How to Execute

First-time use — Confirm environment variables
```
CHANDAO_URL
```
/
```
CHANDAO_ACCOUNT
```
/
```
CHANDAO_PASSWORD
```
are configured

Verify —

node scripts/auth.js --action list-products

Intent matching — Match user natural language with the "Intent Recognition Rules" below.

Execute — Call the corresponding

scripts/<module>.js --action <action> [--args]

Script List

Script	Module	Operations
`auth.js`	Authentication	`login` / `get-token` / `list-products`
`product.js`	Product	`list` / `get` / `create` / `update` / `delete` / `list-by-program`
`project.js`	Project	`list` / `get` / `create` / `update` / `delete` / `list-by-program`
`story.js`	Story	`list` / `get` / `create` / `update` / `close` / `activate` / `change` / `delete`
`task.js`	Task	`list` / `get` / `create` / `update` / `start` / `finish` / `close` / `activate` / `delete`
`execution.js`	Execution	`list` / `get` / `create` / `update` / `start` / `suspend` / `close` / `link-products` / `delete`
`bug.js`	Bug	`list` / `get` / `create` / `update` / `resolve` / `close` / `activate` / `delete`
`testcase.js`	Test Case	`list` / `get` / `create` / `update` / `delete`

Common Options

```
--dry-run
```
— Preview operation results without actual execution (all write operations)
```
--limit <N>
```
— Number of items per page, default 20, max 1000 (all list operations)
```
--page <N>
```
— Page number, starts from 1 (all list operations)
```
--yes
```
— Confirm deletion, without this flag it only prompts but doesn't execute (all delete operations)

Intent Recognition Rules

Environment Configuration

"Configure ZenTao" / "Set up ZenTao" / "Cannot find ZenTao" → Guide user to configure
```
CHANDAO_URL
```
/
```
CHANDAO_ACCOUNT
```
/
```
CHANDAO_PASSWORD
```
"Login failed" / "Authentication failed" / "401" → Prompt user to check account and password in environment variables
"Query products" / "Product list" / "What products are there" →
```
node scripts/product.js --action list
```

"Product details" / "Check product X" →

node scripts/product.js --action get --id <id>

"Create product" / "New product" →

node scripts/product.js --action create --name <name>

"Update product" / "Modify product" / "Edit product" →
```
node scripts/product.js --action update --id <id>
```

"Delete product" →

node scripts/product.js --action delete --id <id>

"Products in program" / "Products in program N" →

node scripts/product.js --action list-by-program --program N

Product Pass-through Parameters

User Keyword	Extracted Field	Value
Normal	`--type`	`normal`
Multi-branch	`--type`	`branch`
Multi-platform	`--type`	`platform`
Public	`--acl`	`open`
Private	`--acl`	`private`

Project Management

"Query projects" / "Project list" / "What projects are there" →
```
node scripts/project.js --action list
```

"Project details" / "Check project X" →

node scripts/project.js --action get --id <id>

"Create project" / "New project" →

node scripts/project.js --action create --name <name> --model <model> --begin <date> --end <date>

"Update project" / "Modify project" / "Edit project" →
```
node scripts/project.js --action update --id <id>
```

"Delete project" →

node scripts/project.js --action delete --id <id>

"Projects in program" / "Projects in program N" →

node scripts/project.js --action list-by-program --program N

Project Pass-through Parameters

User Keyword	Extracted Field	Value
Agile / Scrum	`--model`	`scrum`
Waterfall	`--model`	`waterfall`
Kanban	`--model`	`kanban`
Agile Plus	`--model`	`agileplus`
Waterfall Plus	`--model`	`waterfallplus`

Common Update Rules

⚠️ Must get current values before all update operations ZenTao API's PUT request will reset fields not included to default values (e.g., priority will change from 2 to 3).

Correct Flow (automatically implemented in scripts):

First
```
GET /<module>/<id>
```
to get current values
Keep values of fields that need to remain unchanged
Only modify fields that need to be updated
Send all fields together in the update request

Affected Scope:

story update

task update

execution update

bug update

product update

project update

testcase update

and all other update operations.

See Details: Item 23 in

references/pitfalls.md

⭐ Important: One-time Creation Principle

🎯 Core Principle: Pass all context parameters at once, avoid create-then-update

When user's natural language contains multiple parameters, must pass all known parameters during creation, instead of creating first then updating.

❌ Wrong Approach (two API calls):

bash

# 1st call: Create with only required parameters
node scripts/execution.js --action create --project 11 --name "Sprint 39" --begin 2026-06-01 --end 2026-06-15

# 2nd call: Update to add other parameters
node scripts/execution.js --action update --id 39 --products 21 --lifetime short

✅ Correct Approach (one API call):

bash

# Pass all parameters at once
node scripts/execution.js --action create \
  --project 11 \
  --name "Sprint 39" \
  --begin 2026-06-01 \
  --end 2026-06-15 \
  --products 21 \
  --lifetime short

Applicable Scenarios:

✅ When creating a sprint, product, owner, type, etc. are known → Pass all during creation
✅ When creating a story, module, priority, source, etc. are known → Pass all during creation
✅ When creating a task, assignee, estimated time, linked story, etc. are known → Pass all during creation
✅ When creating a bug, severity, affected version, linked execution, etc. are known → Pass all during creation

Reasons:

🚀 Reduce API Calls: 1 vs 2, improve efficiency
📊 Data Consistency: Avoid intermediate states
⚡ User Experience: Complete in one go, no need to wait for secondary update
🔒 Avoid Errors: Reduce field reset issues that may occur during update operations

Agent Execution Rules:

📌 After extracting all available parameters from user's instruction, immediately assemble the complete command and execute creation, do not operate step by step.

Fuzzy Instruction Handling

"Check project" / "View project" / "Project details" without providing ID → Ask user: "Please provide the project ID"
"Update project" / "Modify project" without providing ID → Ask user: "Please provide the project ID"
"Delete project" without providing ID → Ask user: "Please provide the project ID"

Story Management

"List stories" / "Story list" →
```
node scripts/story.js --action list
```

"Stories in project N" →

node scripts/story.js --action list --project N

"Stories in execution N" →

node scripts/story.js --action list --execution N

"Story details" / "View story" →

node scripts/story.js --action get --id <id>

"Create story" / "New story" →

node scripts/story.js --action create --product <id> --title <title>

"Update story" / "Modify story" →

node scripts/story.js --action update --id <id>

"Activate story" / "Reopen story" →

node scripts/story.js --action activate --id <id>

"Close story" →

node scripts/story.js --action close --id <id> --reason done

"Change story" →

node scripts/story.js --action change --id <id> --reviewer <account>

⚠️ Important: Format Requirements for spec/verify Fields

Story description (
```
--spec
```
) and acceptance criteria (
```
--verify
```
) fields must use HTML format
Markdown format is not allowed (e.g.,
```
# Title
```
,
```
**Bold**
```
,
```
- List
```
)

Use HTML tags instead (e.g.,

<h2>Title</h2>

<strong>Bold</strong>

<ul><li>List</li></ul>

)

Story Pass-through Parameters

User Keyword	Extracted Field	Value
Feature	`--category`	`feature`
Interface	`--category`	`interface`
Performance	`--category`	`performance`
Security	`--category`	`safe`
Experience	`--category`	`experience`
Improvement	`--category`	`improve`
Customer	`--source`	`customer`
User	`--source`	`user`

Task Management

"List tasks" / "Task list" →

node scripts/task.js --action list --execution <id>

"Task details" / "View task" →

node scripts/task.js --action get --id <id>

"Create task" / "New task" →

node scripts/task.js --action create --execution <id> --name <name>

"Start task" / "Claim task" →

node scripts/task.js --action start --id <id>

"Finish task" →

node scripts/task.js --action finish --id <id> --consumed <hours>

"Close task" →

node scripts/task.js --action close --id <id>

"Activate task" →

node scripts/task.js --action activate --id <id>

"Delete task" →

node scripts/task.js --action delete --id <id>

Task Pass-through Parameters

User Keyword	Extracted Field	Value
Development	`--type`	`devel`
Testing	`--type`	`test`
Design	`--type`	`design`
Discussion	`--type`	`discuss`
UI/Interface	`--type`	`ui`

Execution/Sprint Management

"List executions" / "Sprint list" →

node scripts/execution.js --action list [--project N] [--status all|undone|wait|doing]

"Execution details" / "View sprint" →

node scripts/execution.js --action get --id <id>

"Create execution" / "New sprint" →

node scripts/execution.js --action create --project <id> --name <name> --begin <date> --end <date> [--products <ids>]

"Update execution" / "Modify execution" / "Edit execution" →

node scripts/execution.js --action update --id <id> [--products <ids>]

"Start execution" / "Start sprint" →

node scripts/execution.js --action start --id <id>

"Suspend execution" / "Suspend sprint" →

node scripts/execution.js --action suspend --id <id>

"Close execution" / "Close sprint" →

node scripts/execution.js --action close --id <id>

"Delete execution" / "Delete sprint" →

node scripts/execution.js --action delete --id <id>

⚠️ Product Association Notes:
✅ Recommended Method: Use
--products
parameter to associate products during
create
or
update
❌ Not Supported:
link-products
action (ZenTao API returns 403 permission error)
📝 Association Rules: Sprint must first be associated with a project, and can only associate products that the project has already associated
Example:
node scripts/execution.js --action create --project 11 --name "Sprint" --begin 2026-06-01 --end 2026-06-15 --products 21

Execution Pass-through Parameters

User Keyword	Extracted Field	Value
Agile / Scrum	`--type`	`sprint`
Kanban	`--type`	`kanban`
Short-term	`--lifetime`	`short`
Long-term	`--lifetime`	`long`
Ops	`--lifetime`	`ops`
Public	`--acl`	`open`
Private	`--acl`	`private`

Bug Management

"Bug list" / "List bugs" →
```
node scripts/bug.js --action list
```

"Bugs in product N" →

node scripts/bug.js --action list --product N

"Bugs in project N" →

node scripts/bug.js --action list --project N

"Bugs in execution" / "Sprint bugs" / "Bugs in execution N" →
```
node scripts/bug.js --action list --execution <id>
```

"Bug details" / "View bug N" →

node scripts/bug.js --action get --id <id>

"Create bug" / "Report bug" →

node scripts/bug.js --action create --product <id> --title <title>

"Modify bug" / "Edit bug" / "Update bug" →

node scripts/bug.js --action update --id <id>

"Resolve bug N" →

node scripts/bug.js --action resolve --id <id> --resolution <resolution>

"Close bug N" →

node scripts/bug.js --action close --id <id>

"Reopen bug N" / "Activate bug N" →

node scripts/bug.js --action activate --id <id> --openedBuild <version|trunk>

"Delete bug N" →
```
node scripts/bug.js --action delete --id <id>
```
(requires user confirmation)

Bug Pass-through Parameters

User Keyword	Extracted Field	Value
Code error	`--type`	`codeerror`
Configuration	`--type`	`config`
Installation	`--type`	`install`
Security	`--type`	`security`
Performance	`--type`	`performance`
Fixed	`--resolution`	`fixed`
By design	`--resolution`	`bydesign`
Cannot reproduce	`--resolution`	`notrepro`
Critical/Emergency	`--severity`	`1`
High	`--severity`	`2`
Medium	`--severity`	`3`
Low	`--severity`	`4`

Epic Management

Epic module is not implemented yet, can be added later as needed.

Test Management

"Test case list" →
```
node scripts/testcase.js --action list
```

"Test cases in product N" →

node scripts/testcase.js --action list --product N

"Test cases in project N" →

node scripts/testcase.js --action list --project N

"Test cases in execution N" →

node scripts/testcase.js --action list --execution N

"Test case details" / "View test case N" →

node scripts/testcase.js --action get --id <id>

"Create test case" →

node scripts/testcase.js --action create --product <id> --title <title> --steps '...'

"Modify test case" / "Edit test case" →

node scripts/testcase.js --action update --id <id>

"Delete test case" / "Delete test case N" →
```
node scripts/testcase.js --action delete --id <id>
```
(requires user confirmation)

⚠️ Important: Format Requirements for Test Case Steps and Expectations

Test cases must include steps (
--steps
), with expectations specified via the
```
expect
```
field in steps
Both steps and expectations use plain text, HTML and Markdown are prohibited

--steps

format:

[{"step": "Step 1", "expect": "Expectation 1", "type": "step"}, ...]

```
type
```
only supports
```
step
```

Program Management

Program module is not implemented yet, can be added later as needed.

Release/Version

Release/version module is not implemented yet, can be added later as needed.

System Management

System management module is not implemented yet, can be added later as needed.

Bug Fix Workflow (Important! Corrected by User)

Must update ZenTao status immediately after fixing a bug, do not wait until all bugs are fixed to process in batches.

bash

# After fixing a bug, execute immediately:
node scripts/bug.js --action resolve --id <id> --resolution fixed

Correct Flow:

Read bug list, fix one by one
After fixing each one → Compile and test → Immediately execute
```
bug resolve
```
After all are fixed, submit code and tag version

Error Handling

Scenario	Handling
Environment variables not configured	Prompt user to configure `CHANDAO_URL` / `CHANDAO_ACCOUNT` / `CHANDAO_PASSWORD`
Login failure	Prompt user to check if account and password in environment variables are correct
No data	"No data available"
Network error	Friendly prompt, do not expose internal details
`--dry-run` output	Show the operation to be executed, ask user for confirmation
HTTP 403	Check user role and module permissions, see Pitfalls

Key Warning Summary

See details in references/pitfalls.md

⚠️ API v2 creation interface parameter names must have
```
ID
```
suffix (e.g.,
```
executionID
```
), otherwise returns 403
⚠️ Bug status transitions must use dedicated endpoints (
```
bug resolve/close/activate
```
),
```
bug update --status
```
is invalid
⚠️ It is recommended to pass
```
--assigned-to
```
when resolving bugs (otherwise assignee will be cleared) and
```
--resolved-build
```
⚠️
```
story close
```
must pass
```
--reason
```
(enum: done/subdivided/duplicate/postponed/willnotdo/cancel/bydesign)
⚠️
```
story change
```
must pass
```
--reviewer
```
⚠️
```
task finish
```
must pass
```
--consumed
```
⚠️
```
execution create
```
uses
```
--project
```
(not
```
--product
```
)
⚠️
```
bug list
```
does not have
```
--pri
```
parameter

⚠️

project create

requires

name

model

begin

end

model

values are

scrum

waterfall

kanban

agileplus

waterfallplus

⚠️
```
model
```
field in
```
project create/update
```
is a different concept from
```
type
```
in
```
execution
```
, do not confuse them

⚠️

execution create

requires

project

name

begin

end

, supports extended fields like

lifetime

days

products

plans

PO

QD

PM

RD

acl

⚠️
```
execution update
```
requires
```
name
```
+
```
begin
```
+
```
end
```
,
```
--project
```
is used to modify the associated project
⚠️ All
```
delete
```
commands require
```
--yes
```
confirmation
⚠️ 403 errors may be caused by incorrect parameter names, user has no role, or role lacks module permissions
⚠️ spec/verify fields must use HTML format: Story description (
```
--spec
```
) and acceptance criteria (
```
--verify
```
) fields must use HTML format, Markdown is not allowed
⚠️ PUT requests reset unincluded fields to default values: ZenTao API's PUT request will reset fields not included in the request body to default values. Must get current values before update operations, then merge user-specified fields. See Item 23 in
```
references/pitfalls.md
```

Core References

Topic	Description	Reference
Setup & Config	Installation and environment configuration	setup.md
API Pitfalls	ZenTao API pitfalls (23 items)	pitfalls.md
Help & FAQ	Frequently asked questions	help.md
API Fields	v2 API required parameters quick reference	zentao-v2-api-fields.md
API Quirks	Common pitfalls of API v2	zentao-api-v2-quirks.md
Permissions	Permissions and role issues	zentao-api-permissions.md
Product API	Product management commands	commands-product.md
Project API	Project management commands	commands-project.md
Story API	Story management commands	commands-story.md
Task API	Task management commands	commands-task.md
Execution API	Execution/sprint management commands	commands-execution.md
Bug API	Bug management commands	commands-bug.md
Test API	Test case management commands	commands-test.md

Script Architecture

scripts/
├── auth.js         # Shared HTTP + Token authentication + utility functions (all scripts depend on this)
├── product.js      # Product CRUD
├── project.js      # Project CRUD
├── story.js        # Story CRUD + lifecycle
├── task.js         # Task CRUD + lifecycle
├── execution.js    # Execution CRUD + lifecycle
├── bug.js          # Bug CRUD + lifecycle
└── testcase.js     # Test Case CRUD

chandao

NPX Install

Tags

SKILL.md Content (Chinese)

SKILL: ZenTao

Quick Start

Security Guidelines

How to Execute

Script List

Common Options

Intent Recognition Rules

Environment Configuration

Product Pass-through Parameters

Project Management

Project Pass-through Parameters

Common Update Rules

⭐ Important: One-time Creation Principle

Fuzzy Instruction Handling

Story Management

Story Pass-through Parameters

Task Management

Task Pass-through Parameters

Execution/Sprint Management

Execution Pass-through Parameters

Bug Management

Bug Pass-through Parameters

Epic Management

Test Management

Program Management

Release/Version

System Management

Bug Fix Workflow (Important! Corrected by User)

Error Handling

Key Warning Summary

Core References

Script Architecture