task

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Task Management with Fine

使用Fine进行任务管理

Fine is an agent-first project management CLI. Tasks are markdown files in a

tasks/

directory, managed via CLI commands and direct file editing.

Fine是一款以Agent为核心的项目管理CLI工具。任务以Markdown文件形式存储在

tasks/

目录中，可通过CLI命令或直接编辑文件进行管理。

Key principle: tasks are self-contained

核心原则：任务独立自洽

Each task must have a well-defined deliverable — something concrete that can be verified when the task is done. Executors can read other tasks, but they have no context from previous task executions (no memory of decisions made, approaches taken, or intermediate findings from other sessions). This means:

Every step must be achievable from the repository and the task description alone. Don't write steps that depend on runtime state, environment-specific setup, or decisions made during a previous task's execution.
Tasks need well-defined deliverables, not open-ended research. "Identify all broken links" is not a good task — it produces no deliverable. "Fix all broken links in the docs" is good — the deliverable is updated files. If research is needed, fold it into a task that acts on the findings.
Verification steps are fine if they have clear pass/fail criteria. For example, "Verify all links return 200" is a good step. If you can't define concrete verification criteria for a step, leave it out — but note the omission in your summary so the user can adjust.
Include context the executor will need. The executor can see other task files, but doesn't know what happened during their execution. If a task depends on choices made in another task, reference the expected output (e.g., "the auth module added in task 003") rather than assuming the executor knows the approach that was taken.

每个任务必须具备明确可交付成果——即任务完成后可验证的具体内容。执行者可以查看其他任务，但不具备之前任务执行的上下文信息（不记得之前做出的决策、采用的方法或其他会话中的中间发现）。这意味着：

每一步都必须仅通过代码库和任务描述即可完成。不要编写依赖运行时状态、特定环境配置或之前任务执行过程中决策的步骤。
任务需要明确的可交付成果，而非开放式研究。“找出所有失效链接”不是一个好任务——它没有产出可交付成果。“修复文档中的所有失效链接”才是合适的——可交付成果是更新后的文件。如果需要进行研究，应将其融入到一个基于研究结果采取行动的任务中。
如果有明确的通过/失败标准，验证步骤是可行的。例如，“验证所有链接返回200状态码”是一个合适的步骤。如果某一步骤无法定义具体的验证标准，请将其省略——但要在总结中说明省略情况，以便用户调整。
包含执行者所需的上下文信息。执行者可以查看其他任务文件，但不知道这些任务的执行过程。如果某个任务依赖于另一任务中做出的选择，请引用预期输出（例如，“任务003中添加的auth模块”），而非假设执行者知晓采用的方法。

Task file format

任务文件格式

Each task is a markdown file named

NNN-slug.md

(e.g.,

001-user-authentication.md

). The ID and slug come from the filename, not the content.

markdown

undefined

每个任务都是一个命名为

NNN-slug.md

的Markdown文件（例如

001-user-authentication.md

）。ID和slug来自文件名，而非文件内容。

markdown

undefined

Title

标题

Description paragraph(s).

描述段落。

Steps

步骤

Incomplete step
Completed step


- **Title**: The first H1. Required.
- **Description**: Everything between the title and `## Steps`. Can be multiple
  paragraphs.
- **Steps**: Checklist items under `## Steps`. Omit the section entirely if
  there are no steps.

未完成步骤
已完成步骤


- **标题**：第一个一级标题，必填项。
- **描述**：标题与`## 步骤`之间的所有内容，可以是多个段落。
- **步骤**：`## 步骤`下的复选列表项。如果没有步骤，可完全省略该部分。

CLI commands

CLI命令

Run commands with

npx @jagersoftware/fine <command>

使用

npx @jagersoftware/fine <command>

运行命令。

Create a task

创建任务

npx @jagersoftware/fine create --title "Feature Name" --description "What this feature does and why"

This auto-assigns the next available ID and generates the slug from the title. Use descriptive titles that read well as filenames — "User Authentication" becomes

001-user-authentication.md

npx @jagersoftware/fine create --title "Feature Name" --description "What this feature does and why"

该命令会自动分配下一个可用的ID，并根据标题生成slug。请使用能清晰反映文件名的描述性标题——例如“用户认证”会生成

001-user-authentication.md

。

List all tasks

列出所有任务

npx @jagersoftware/fine list

Shows each task with its ID, title, and step progress (completed/total). This is the default command — running

fine

with no arguments does the same thing.

npx @jagersoftware/fine list

显示每个任务的ID、标题和步骤进度（已完成/总数）。这是默认命令——直接运行

fine

不带参数也会执行相同操作。

Show a task

查看任务详情

npx @jagersoftware/fine show <id>

Accepts padded or unpadded IDs — both

and

work. Displays the full task content including description and all steps with their completion status.

npx @jagersoftware/fine show <id>

接受带前导零或不带前导零的ID——

和

都有效。显示任务的完整内容，包括描述和所有步骤的完成状态。

Add a step

添加步骤

npx @jagersoftware/fine add-step <id> --step "Step description"

Appends a new incomplete step to the task. Steps are always added as unchecked (

- [ ]

npx @jagersoftware/fine add-step <id> --step "Step description"

向任务末尾添加一个未完成的步骤。新步骤始终为未勾选状态(

- [ ]

)。

Direct markdown editing

直接编辑Markdown文件

Some operations don't have CLI commands yet. Handle these by editing the task file directly.

有些操作目前没有对应的CLI命令，可通过直接编辑任务文件来处理。

Complete a step

标记步骤为完成

Open the file in

tasks/

and change

[ ]

[x]

Before: - [ ] Implement login endpoint
After:  - [x] Implement login endpoint

打开

tasks/

目录下的文件，将

[ ]

改为

[x]

：

修改前: - [ ] 实现登录端点
修改后:  - [x] 实现登录端点

Remove a step

删除步骤

Delete the entire line (

- [ ]

- [x]

) from the Steps section. If no steps remain, remove the

## Steps

heading and the blank line above it too, so the file stays clean.

删除该步骤的整行内容（

- [ ]

或

- [x]

）。如果所有步骤都被删除，请同时删除

## 步骤

标题及其上方的空行，保持文件整洁。

Edit the description

编辑描述

Modify the text between the

# Title

line and

## Steps

. Keep at least one blank line after the title and before the steps heading.

修改

# 标题

行与

## 步骤

之间的文本内容。标题与步骤标题之间至少保留一个空行。

Reorder steps

调整步骤顺序

Move the

- [ ]

- [x]

lines into the desired order. Each step is one line, so reordering is straightforward.

移动

- [ ]

- [x]

行至所需顺序。每个步骤单独占一行，因此调整顺序非常简单。

Workflow

工作流程

When asked to work with tasks, follow this approach:

Check what exists first. Run
```
list
```
to see current tasks before creating new ones — avoid duplicates.
Create tasks for distinct features, not for individual steps. A task represents a self-contained body of work with a well-defined deliverable; steps go inside it. The executor can read other tasks but has no context from their execution.
Break work into concrete steps using TDD. Each step should be a single action with a clear deliverable, not a vague goal. "Add login endpoint with JWT validation" is better than "Handle authentication." Follow a test-driven approach: for each piece of functionality, add a step to write a failing test before the step that implements the feature. The test step should produce a test that runs and fails (red), and the implementation step should make it pass (green). For example, instead of just "Add login endpoint," use two steps: "Write failing test for login endpoint" followed by "Implement login endpoint to pass test." Not every step needs a test (e.g., config changes, refactors with existing coverage), but any step that adds or changes behavior should be preceded by a test step.
Ask when unclear. Use AskUserQuestion to clarify ambiguities before creating or modifying tasks — e.g., unclear scope, missing acceptance criteria, or uncertain deliverables. It's better to ask than to guess wrong.
Do NOT perform the work. This skill is for task management only — creating, viewing, updating, and organizing tasks. After creating or updating a task, summarize what was created/changed and stop. Do not start implementing the steps.
Summarize when done. After creating a task or making changes, give a brief summary of the task (title, description, steps) so the user can confirm it looks right.

当需要处理任务时，请遵循以下流程：

先检查现有任务。在创建新任务前，先运行
```
list
```
查看当前任务——避免重复创建。
为不同功能创建独立任务，而非为单个步骤创建任务。一个任务代表一个独立自洽的工作单元，具备明确的可交付成果；步骤则包含在任务内部。执行者可以查看其他任务，但不具备这些任务的执行上下文。
使用TDD将工作拆分为具体步骤。每个步骤应是一个具有明确可交付成果的单一操作，而非模糊的目标。“添加带JWT验证的登录端点”比“处理认证”更合适。遵循测试驱动开发方法：对于每个功能，先添加一个编写失败测试的步骤，再添加实现该功能的步骤。测试步骤应产出一个运行后失败的测试（红），实现步骤则要让测试通过（绿）。例如，不要只写“添加登录端点”，而是拆分为两个步骤：“编写登录端点的失败测试”和“实现登录端点以通过测试”。并非所有步骤都需要测试（例如配置更改、已有测试覆盖的重构），但任何添加或修改功能的步骤都应在前面加上测试步骤。
有疑问时询问用户。在创建或修改任务前，使用AskUserQuestion澄清模糊点——例如不明确的范围、缺失的验收标准或不确定的可交付成果。与其猜测错误，不如主动询问。
不要执行具体工作。此技能仅用于任务管理——创建、查看、更新和整理任务。创建或更新任务后，总结所做的创建/修改操作即可停止，不要开始执行步骤中的工作。
完成后进行总结。创建任务或做出修改后，简要总结任务的内容（标题、描述、步骤），以便用户确认是否符合预期。

Typical agent session

典型Agent会话示例

Here's the natural flow for using fine as an agent. Note: always stop after the task management action and summarize — never start implementing the work.

User: "Create a task for adding dark mode support"

1. npx @jagersoftware/fine create --title "Dark Mode Support" --description "Add a dark/light theme toggle..."
2. npx @jagersoftware/fine add-step 1 --step "Define color tokens for both themes"
3. npx @jagersoftware/fine add-step 1 --step "Write failing test for ThemeProvider context"
4. npx @jagersoftware/fine add-step 1 --step "Implement ThemeProvider context to pass test"
5. npx @jagersoftware/fine add-step 1 --step "Write failing test for toggle component"
6. npx @jagersoftware/fine add-step 1 --step "Add toggle component to header to pass test"
7. npx @jagersoftware/fine add-step 1 --step "Write failing test for persisting theme preference"
8. npx @jagersoftware/fine add-step 1 --step "Persist preference to localStorage to pass test"
9. Summarize: "Created task 001 — Dark Mode Support with 7 steps (TDD: red/green pairs for each behavior): ..."
   STOP here. Do not begin implementing the steps.

User: "What's the status of our tasks?"

1. npx @jagersoftware/fine list
   → Shows all tasks with progress
2. npx @jagersoftware/fine show 1
   → Shows detail for any task that needs attention
3. Summarize the current status for the user. Do not start working on incomplete steps.

User: "Mark the color tokens step as done"

1. Edit tasks/001-dark-mode-support.md
   Change: - [ ] Define color tokens for both themes
   To:     - [x] Define color tokens for both themes
2. Summarize: "Marked 'Define color tokens for both themes' as complete."
   STOP here.

以下是Agent使用Fine的自然流程。注意：完成任务管理操作后务必停止并总结——绝不要开始执行具体工作。

用户：“创建一个添加暗色模式支持的任务”

1. npx @jagersoftware/fine create --title "Dark Mode Support" --description "Add a dark/light theme toggle..."
2. npx @jagersoftware/fine add-step 1 --step "Define color tokens for both themes"
3. npx @jagersoftware/fine add-step 1 --step "Write failing test for ThemeProvider context"
4. npx @jagersoftware/fine add-step 1 --step "Implement ThemeProvider context to pass test"
5. npx @jagersoftware/fine add-step 1 --step "Write failing test for toggle component"
6. npx @jagersoftware/fine add-step 1 --step "Add toggle component to header to pass test"
7. npx @jagersoftware/fine add-step 1 --step "Write failing test for persisting theme preference"
8. npx @jagersoftware/fine add-step 1 --step "Persist preference to localStorage to pass test"
9. 总结：“已创建任务001——暗色模式支持，包含7个步骤（采用TDD：每个功能对应红/绿测试对）：...”
   在此处停止，不要开始执行步骤中的工作。

用户：“我们的任务状态如何？”

1. npx @jagersoftware/fine list
   → 显示所有任务的进度
2. npx @jagersoftware/fine show 1
   → 显示需要关注的任务详情
3. 向用户总结当前任务状态。不要开始处理未完成的步骤。

用户：“标记颜色令牌步骤为已完成”

1. 编辑tasks/001-dark-mode-support.md
   修改：- [ ] Define color tokens for both themes
   为：     - [x] Define color tokens for both themes
2. 总结：“已将‘定义双主题颜色令牌’步骤标记为完成。”
   在此处停止。