ptask

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Task

项目任务

Maintain a compact task system in

docs/task/

with deterministic status updates.

在

docs/task/

目录下维护一套轻量任务系统，支持可确定性的状态更新。

Hard Rules

硬性规则

Use English filenames only, even for Chinese content.
Keep one language per project/task file (follow user preference, otherwise follow existing project language).
Task index uses one-line entries only; all details go to detail files.
Claim before work; do not implement code before claim is complete.
Write status changes immediately; never defer.

仅使用英文文件名，即便内容为中文也不例外。
每个项目/任务文件仅保留一种语言（遵循用户偏好，无偏好时遵循项目已有语言）。
任务索引仅使用单行条目，所有详情都存入详情文件中。
工作前先认领，认领完成前不要编写实现代码。
状态变更要立即同步，绝不延迟。

Language Mode

语言模式

Content can be English or Chinese.
Filenames stay English in all cases (
```
index.md
```
,
```
PREFIX-NNN.md
```
).
Keep one language per project unless the user explicitly asks to switch.

内容可使用英文或中文。
所有场景下文件名都保持英文（
```
index.md
```
、
```
PREFIX-NNN.md
```
）。
每个项目仅保留一种语言，除非用户明确要求切换。

Canonical Structure

规范结构

docs/task/
├── index.md
└── PREFIX-NNN.md

```
index.md
```
: one-line status entries
```
PREFIX-NNN.md
```
: detail files (description, owner, dependencies, notes)

docs/task/
├── index.md
└── PREFIX-NNN.md

```
index.md
```
：单行状态条目
```
PREFIX-NNN.md
```
：详情文件（包含描述、负责人、依赖、备注）

Task Formats

任务格式

Index Entry

索引条目

markdown

- [ ] [**PREFIX-001 Short imperative title**](PREFIX-001.md) `P1`

markdown

- [ ] [**PREFIX-001 Short imperative title**](PREFIX-001.md) `P1`

Index Entry (Chinese Content)

索引条目（中文内容）

markdown

- [ ] [**PREFIX-001 简短祈使句标题**](PREFIX-001.md) `P1`

markdown

- [ ] [**PREFIX-001 简短祈使句标题**](PREFIX-001.md) `P1`

Detail File Template

详情文件模板

markdown

undefined

markdown

undefined

PREFIX-001 Short imperative title

status: pending
priority: P1
owner: (unassigned)
createdAt: YYYY-MM-DD HH:mm

status: pending
priority: P1
owner: (unassigned)
createdAt: YYYY-MM-DD HH:mm

Description

What needs to be done, with context and acceptance criteria.

ActiveForm

Present-continuous description for spinner display.

Dependencies

blocked by: (none)
blocks: (none)

blocked by: (none)
blocks: (none)

Notes

(Implementation notes, progress logs, or related links.)

undefined

(Implementation notes, progress logs, or related links.)

undefined

Detail File Template (Chinese Content)

详情文件模板（中文内容）

markdown

undefined

markdown

undefined

PREFIX-001 简短祈使句标题

status: pending
priority: P1
owner: (未分配)
createdAt: YYYY-MM-DD HH:mm

status: pending
priority: P1
owner: (未分配)
createdAt: YYYY-MM-DD HH:mm

描述

需要做什么，包含上下文和验收标准。

进行时描述

进行中的现在进行时描述（用于 spinner 显示）。

依赖

blocked by: (无)
blocks: (无)

blocked by: (无)
blocks: (无)

笔记

（实现笔记、进度日志或相关链接。）

undefined

（实现笔记、进度日志或相关链接。）

undefined

ID, Marker, and Status Rules

ID、标记与状态规则

Task ID

任务ID

Format:
```
PREFIX-NNN
```
(uppercase prefix + zero-padded 3 digits)
Sequence per prefix starts from
```
001
```
Never reuse or renumber IDs

格式：
```
PREFIX-NNN
```
（大写前缀 + 补零的3位数字）
每个前缀下的序列从
```
001
```
开始
绝不复用或重编ID

Status Markers

状态标记

Marker	Meaning	TaskUpdate status
`[ ]`	Pending	`pending`
`[-]`	In progress	`in_progress`
`[x]`	Completed	`completed`
`[~]`	Closed / Won't do	`deleted`

标记	含义	TaskUpdate 状态
`[ ]`	待处理	`pending`
`[-]`	进行中	`in_progress`
`[x]`	已完成	`completed`
`[~]`	已关闭/不做	`deleted`

Allowed detail

status

values

允许的详情页

status

取值

```
pending
```
```
in_progress
```
```
completed
```
```
closed
```

```
pending
```
```
in_progress
```
```
completed
```
```
closed
```

Priority

优先级

```
P0
```
: blocking
```
P1
```
: high
```
P2
```
: medium
```
P3
```
: low

```
P0
```
：阻塞级
```
P1
```
：高
```
P2
```
：中
```
P3
```
：低

Claim-Before-Work (Multi-Agent Safety)

工作前认领（多Agent安全机制）

Before writing any implementation code:

Read
```
docs/task/index.md
```
.
If marker is
```
[-]
```
, open detail file and check
```
owner
```
.
If owned by another agent, skip and pick another task.

Claim atomically:

Update index marker
```
[ ] -> [-]
```
Update detail
```
status -> in_progress
```
and set
```
owner
```

Call

TaskUpdate(status: "in_progress", owner: "<agent>")

if task tools are available

Start implementation only after all claim writes succeed.

On completion:

Update index
```
[-] -> [x]
```
Update detail
```
status -> completed
```
Call
```
TaskUpdate(status: "completed")
```
if task tools are available

On close/won't do:

Update index to
```
[~]
```
Update detail
```
status -> closed
```
and add reason in notes
Call
```
TaskUpdate(status: "deleted")
```
if task tools are available

在编写任何实现代码前：

读取
```
docs/task/index.md
```
。
如果标记为
```
[-]
```
，打开详情文件检查
```
owner
```
字段。
如果归属其他Agent，跳过该任务选择其他任务。
原子性认领：
- 将索引标记从
```
[ ]
```
  更新为
```
[-]
```
- 将详情页
```
status
```
  更新为
```
in_progress
```
  并设置
```
owner
```
- 如果有可用的任务工具，调用
```
TaskUpdate(status: "in_progress", owner: "<agent>")
```
所有认领写入操作成功后再开始实现。

任务完成时：

将索引标记从
```
[-]
```
更新为
```
[x]
```
将详情页
```
status
```
更新为
```
completed
```
如果有可用的任务工具，调用
```
TaskUpdate(status: "completed")
```

任务关闭/无需实现时：

将索引标记更新为
```
[~]
```
将详情页
```
status
```
更新为
```
closed
```
并在备注中添加原因
如果有可用的任务工具，调用
```
TaskUpdate(status: "deleted")
```

Sync Rules

同步规则

Primary source is

docs/task/

files.

If
```
TaskCreate
```
/
```
TaskUpdate
```
tools are available, keep tool state synced with file state.
If tools are unavailable, continue with file-only sync and mention that in updates.

Session checklist:

Session start: read
```
docs/task/index.md
```
and active detail files.
New task: create detail file first, then append index line.
Before work: complete Claim-Before-Work.
Session end: verify all statuses are persisted and update index header date.

主数据源为

docs/task/

下的文件。

如果有可用的
```
TaskCreate
```
/
```
TaskUpdate
```
工具，保持工具状态与文件状态同步。
如果工具不可用，继续仅通过文件同步，并在更新中说明该情况。

会话检查清单：

会话开始：读取
```
docs/task/index.md
```
和活跃的详情文件。
新建任务：先创建详情文件，再追加索引行。
工作前：完成工作前认领流程。
会话结束：验证所有状态已持久化，并更新索引头部日期。

Project Initialization

项目初始化

On first use in a repository:

Ensure
```
CLAUDE.md
```
has a
```
## Project Task
```
section that references
```
/ptask
```
and claim-before-work.
Ensure
```
AGENTS.md
```
has the same section.
Ensure
```
docs/task/index.md
```
exists; initialize it if missing.

Recommended

CLAUDE.md

AGENTS.md

block:

markdown

undefined

在仓库中首次使用时：

确保
```
CLAUDE.md
```
中有
```
## Project Task
```
章节，引用
```
/ptask
```
和工作前认领规则。
确保
```
AGENTS.md
```
中有相同章节。
确保
```
docs/task/index.md
```
存在，缺失则初始化。

推荐的

CLAUDE.md

AGENTS.md

配置块：

markdown

undefined

Project Task

Use the /ptask skill to manage all tasks.

Read
```
docs/task/index.md
```
before starting work.
Every feature/fix has a task entry.
Use
```
PREFIX-NNN
```
IDs; never reuse IDs.
Claim task before implementation: index + detail + task tool sync.
Update status markers in place after progress/completion.


Chinese content version (filenames still English):

```markdown

Use the /ptask skill to manage all tasks.

Read
```
docs/task/index.md
```
before starting work.
Every feature/fix has a task entry.
Use
```
PREFIX-NNN
```
IDs; never reuse IDs.
Claim task before implementation: index + detail + task tool sync.
Update status markers in place after progress/completion.


中文内容版本（文件名仍保持英文）：

```markdown

Project Task

使用 /ptask 管理所有任务。

开始工作前先读
```
docs/task/index.md
```
。
每个功能或修复都要有对应任务条目。
任务编号使用
```
PREFIX-NNN
```
，禁止复用。
实现前必须先认领：索引 + 详情 + 任务工具状态同步。
进度和完成后原地更新状态标记。

undefined

使用 /ptask 管理所有任务。

开始工作前先读
```
docs/task/index.md
```
。
每个功能或修复都要有对应任务条目。
任务编号使用
```
PREFIX-NNN
```
，禁止复用。
实现前必须先认领：索引 + 详情 + 任务工具状态同步。
进度和完成后原地更新状态标记。

undefined

Update Rules

更新规则

In
```
index.md
```
, only update checkbox markers; never delete historical lines.
In detail files, update fields in place; do not delete existing sections.
Append new tasks at the end of
```
index.md
```
.

在
```
index.md
```
中仅更新复选框标记，绝不删除历史行。
在详情文件中原地更新字段，不要删除已有章节。
新任务追加到
```
index.md
```
末尾。

Output Behavior

输出行为

When reporting progress:

Summarize index changes.
List
```
[-]
```
and
```
[ ]
```
tasks.
List newly completed
```
[x]
```
tasks.

Keep updates concise and aligned with actual repository changes.

汇报进度时：

汇总索引变更内容。
列出
```
[-]
```
和
```
[ ]
```
状态的任务。
列出新完成的
```
[x]
```
状态的任务。

保持更新简洁，与仓库实际变更一致。