zentao-story

story (v2)

CRITICAL — Before starting, you MUST first use the Read tool to read ../zentao-shared/SKILL.md, which contains authentication, environment variable configuration, error handling, and status value definitions.

Commands

story list — List the stories under a product
story get — Get story details
story create — Create a new story
story update — Update story information
story change — Change a story
story delete — Delete a story
story close — Close a story

Story Lifecycle

Stories have clear lifecycle statuses in ZenTao:

draft → active → changed → closed
         ↑         ↓
         └─────────┘ (可重新激活)

Valid Status Transitions

Current Status	Valid Next Status	Description
draft	active	Submit for review
active	changed, closed	Review passed or closed
changed	active, closed	Re-review or close after change
closed	active	Reactivate

Story Status Values

Status	Chinese	Description
`draft`	Draft	Story draft status
`active`	Active	Submitted for review
`changed`	Changed	Story has changes pending review
`closed`	Closed	Story is closed

Priority Levels

Level	Name	Description
1	Highest	Highest priority
2	High	High priority
3	Medium	Medium priority
4	Low	Low priority

Note: Priority 0 usually means no priority is set.

Story Types

Type	Chinese	Description
`feature`	Feature	New feature story
`enhance`	Enhancement	Feature enhancement
`bugfix`	Bug	Bug fix
`task`	Task	Task-type story
`story`	User story	User story

Story Stage Values

Stage	Description
`wait`	Not started
`plan`	Planned
`developed`	Developed
`testing`	Testing
`released`	Released
`closed`	Closed

Before use, you can first run zentao-cli story --help to view the complete options.

Common Use Cases

1. View all stories under a product

# 列出产品 1 下的所有需求
zentao-cli story list --product 1

# 只看活跃的需求
zentao-cli story list --product 1 --status active

2. View details of a specific story

# 获取需求详情（包含描述、预估工时、阶段等）
zentao-cli story get 123

3. Create a new story

# 基础创建
zentao-cli story create --title "用户登录功能" --product 1 --pri 1

# 完整创建（带类型和预估工时）
zentao-cli story create --title "用户注册功能" --product 1 --pri 1 --type feature --estimate 8

4. Update story status

# 关闭需求
zentao-cli story update 123 --status closed

# 更新优先级
zentao-cli story update 123 --pri 2

# 变更需求状态并指派
zentao-cli story update 123 --status changed --assigned-to developer-name

5. Filter stories by project

# 查看项目 1 下的所有需求
zentao-cli story list --product 1 --project 1

Examples

# 列出产品 1 下的所有需求
zentao-cli story list --product 1

# 只看活跃的需求
zentao-cli story list --product 1 --status active

# 获取需求详情
zentao-cli story get 123

# 创建新需求
zentao-cli story create --title "用户登录功能" --product 1 --pri 1

# 关闭需求
zentao-cli story update 123 --status closed

Output Fields

Field	Type	Description
id	u64	Story ID
title	string	Story title
product	u64	Product ID
status	string	Story status: draft / active / closed / changed
pri	u8	Priority: 0-5
category	string	Story category: feature / requirement / bug / improvement
stage	string	Current stage: wait / plan / developed / testing / released / closed
module	u64	Module ID
assigned_to	string	Assignee
opened_by	string	Creator
estimate	f64	Estimated hours (hours)
version	u64	Version number (used for optimistic locking)

Gotchas

Story ID vs Title: After creating a story, the returned value is the story ID (a number), not the title; subsequent operations need to use the ID.
Status Transition: Only state changes that comply with the state transition rules will be accepted:
- draft → active: Submit for review
- active → changed/closed: Review action
- Invalid transitions will return an error
Version for Updates: When updating a requirement, it is recommended to provide the version field to implement optimistic locking and avoid concurrent update conflicts.
Estimate Unit：--estimate The unit of the parameter ishours（hours）。
Type vs Category: A Story has type(story type) and an implicit category(requirement type); the two may differ, so choose according to the actual business.
Closed Story Reactivation: A closed requirement can be reactivated by setting it to active .
Product Required: When creating a requirement, the --product parameter is required, and the requirement must belong to a product.