jj-todo-workflow

JJ TODO 工作流

核心思路是使用由空修订组成的 DAG 作为 TODO 标记，表示待完成的任务，然后稍后再回来编辑这些修订，实际完成任务。这样可以实现有明确里程碑的结构化开发。 修订说明（即提交消息）充当实现规范。 JJ 可以轻松创建这样的结构，然后逐个填充每个修订。

有关 JJ 基础知识的更多信息，请参阅 working-with-jj 技能。我们在此复用该技能中的脚本。

本技能介绍了两种角色：规划者（负责安排空修订并编写其规范）和工作者（负责实现这些任务）。 根据具体情况，你可能只担任规划者、只担任工作者，或同时担任两者。 最好了解整个流程，但各节标题会明确标出每节主要面向的角色。

快速入门（规划者和工作者）

以下是从规划到完成的完整周期（未写出辅助脚本的完整路径）：

# 1. Plan: Create a simple TODO chain
jj-todo-create @ "Add user validation" "Check email format and password strength"
# Created: abc123 (stays on current @)

jj-todo-create abc123 "Add validation tests" "Test valid/invalid emails and passwords"
# Created: def456 (@ still hasn't moved)

# 2. Start working on first TODO
jj edit abc123
jj-flag-update @ wip   # Now [task:wip]

# ... implement validation ...

# 3. Verify ALL acceptance criteria met
make test  # Or equivalent in your project

# 4. Ask to move to next task
jj-todo-next
### ... review current specs (to ensure compliance) and next possible TODOs ...

# 5. Once we're sure everything is properly done, move to next TODO
jj-todo-next --mark-as done def456   # Marks abc123 as [task:done], starts def456 as [task:wip]

就是这样！ 将空提交作为规范，编辑它们以开展工作，完全完成后运行 jj-todo-next --mark-as done <next-step>。

状态标记（规划者和工作者）

我们使用说明前缀来快速跟踪状态。[task:*] 命名空间便于通过 grep 搜索，也可避免与其他约定冲突。

以下是唯一允许使用的状态标记：

标记	含义
[task:draft]	已创建占位项，需要补充完整规范
[task:todo]	尚未开始，空修订中包含完整规范
[task:wip]	正在进行
[task:blocked]	正在等待外部依赖
[task:standby]	等待某项决定（存在难以修复的问题、对其是否有用提出质疑等）
[task:untested]	已完成实现，但测试不足，尚无法验证
[task:review]	需要审查（代码棘手、设计选择）
[task:done]	已完成，满足所有验收标准

此顺序仅供参考：并非每项任务都必须经历所有步骤，也不一定要按上述顺序进行。

注意：在此技能的早期版本中，standby 称为“broken”。为使此状态适用于更广泛的情况，我们将其更名。

何时使用 draft 而非 todo（规划者）

在以下情况使用 [task:draft]：

• 创建占位任务以建立 DAG 结构
• 任务标题或概念明确，但尚未理清细节
• 希望推迟编写完整验收标准
• 在深入具体细节之前进行高层规划

在以下情况使用 [task:todo]：

• 任务具有完整规范（背景、要求、验收标准）
• 工作人员可以直接接手并实现，无需澄清
• 所有依赖项和实现方法都已清楚记录

更新标记（工作者和规划者）

jj-flag-update @ draft     # Mark as needing specification (Planners)
jj-flag-update @ todo      # Mark as ready to work on (Planners)
jj-flag-update @ wip       # Start work (Workers)
jj-flag-update @ untested  # Implementation done, tests missing (Workers)
jj-flag-update @ done      # Complete (Workers)

查找带标记的修订（规划者和工作者）

jj-find-flagged                     # All tasks
jj-find-flagged draft               # Only [task:draft]
jj-find-flagged todo                # Only [task:todo]
jj-find-flagged wip                 # Only [task:wip]
jj-find-flagged done                # Only [task:done]

# Manual - all tasks
jj log -r 'description(substring:"[task:")'

# Incomplete tasks only (excludes done)
jj log -r 'description(substring:"[task:") & ~description(substring:"[task:done]")'

基本工作流（规划者和工作者）

1. 规划：创建 TODO 链（规划者）

# Create linear chain of tasks
jj-todo-create @ "Task 1: Setup data model" "...details..."
jj-todo-create <T1-id> "Task 2: Implement core logic" "..."
jj-todo-create <T2-id> "Task 3: Add API endpoints" "..."
jj-todo-create <T3-id> "Task 4: Write tests" "..."

2. 工作：编辑每个 TODO（工作者）

# Read the specs
jj-show-desc <task-id>    # BEWARE: Script from the `working-with-jj` skill
 
# Start working on it
jj edit <task-id>
jj-flag-update @ wip

# ... implement ...

# Mark progress
jj-flag-update @ untested

3. 完成并转到下一项（工作者）

jj-todo-next 脚本用于简化“转到下一项任务”的流程。

不带参数

• 打印当前任务的说明，供你检查并确认是否按计划实现了所有内容
• 打印接下来可能处理的任务

# Review current specs and see what's next
jj-todo-next
# Shows:
#   📋 Current task specs for review:
#   ─────────────────────
#   ...
#   ─────────────────────
#
#   Current task status: [task:wip]
#   Mark as [task:done] only if FULLY COMPLIANT with specs above.
#
#   ✅ Available next tasks:
#     abc123  [task:todo] Feature B
#     def456  [task:todo] Feature C
#
#   ⚠️ Child tasks with unmet dependencies:
#     xyz789  [task:todo] Integration
#             Blocked by: abc123

带参数

• 更新当前任务的标记
• 移动到下一个任务（jj edit）
• 将新任务的标记更新为 [task:wip]

# Actually mark current done and start editing next:
jj-todo-next --mark-as done abc123
# Does the `jj edit abc123` and shows its description

规划并行任务（DAG）（规划者）

创建可以独立处理的分支。例如：

# Linear foundation
jj-todo-create @ "Task 1: Core infrastructure"
jj-todo-create <T1-id> "Task 2: Base components"

# Parallel branches from Task 2
jj-parallel-todos <T2-id> "Widget A" "Widget B" "Widget C"

# ... edit their descriptions to add more details ...

# Merge point (all three parents must complete first)
jj new --no-edit <A-id> <B-id> <C-id> -m "[task:todo] Integration of widgets\n\n..."

结果：

          Integration
       /      |        \
   Widget A  Widget B  Widget C
       \      |        /
          Task 2: Base
              |
          Task 1: Core

无需变基——直接指定父修订！

编写优质的 TODO 描述（规划者）

结构

Short title (< 50 chars)

## Context
Why this task exists, what problem it solves.

## Requirements
- Specific requirement 1
- Specific requirement 2

## Implementation notes
Any hints, constraints, or approaches to consider.

## Acceptance criteria
How to know when this is FULLY DONE (not just "good enough"):
- Criterion 1
- Criterion 2

**重要：**验收标准用于定义何时可以将任务标记为 [task:done]。请具体说明，并确保可测试。

整体而言，描述应尽可能自成一体。 它应为上下文有限的 Agent 提供开始工作所需的全部信息，使其无需在最后一刻做出本应提前明确的决定。

尽可能通过链接到以下内容来避免重复：

• 已有的规范文档
• 代码库中的相关示例

添加此类链接时，避免使用行号等不稳定的引用，因为简单的格式调整就可能使其失效。 例如，优先使用章节名称；如果链接到支持标签引用的规范文档，则使用标签引用（如 Markdown 的 #stuff、LaTeX 的 \ref{stuff} 或 Typst 的 @stuff）；引用代码时，则使用函数名或类名。

示例

Implement user authentication

## Context
Users need to log in to access their data. Using JWT tokens
for stateless auth.

## Requirements
- POST /auth/login accepts email + password
- Returns JWT token valid for 24h
- POST /auth/refresh extends token
- Invalid credentials return 401

## Implementation notes
- Use bcrypt for password hashing (see src/auth/admin.py::AdminLogin::hash_passwd which already uses it)
- Store refresh tokens in Redis
- See auth.md (#about-tokens) for token format spec

## Acceptance criteria
- All auth endpoints return correct status codes
- Tokens expire correctly
- Rate limiting prevents brute force

AI 辅助 TODO 工作流

TODO 与 AI 子 Agent 配合使用效果很好：

• 主管 Agent 负责初步规划，并创建 TODO 修订图
• 主管 Agent 确保所有 [task:draft] 任务都已补全并标记为 [task:todo]，之后工作者才能开始
• 子 Agent 只需按照图中的结构和要求，依次“执行”每个修订
• 子 Agent 只能处理 [task:todo] 任务（规范完整），不得处理 [task:draft] 任务
• 主管 Agent 可以审查差异和备注，并在必要时将任务改回例如 [task:wip] 或 [task:draft]

重要：子 Agent 必须依次处理任务，不得并行处理。 在同一仓库中同时运行多个 Agent 会导致冲突，因为它们会争抢工作副本（@）。

如果确实需要并行工作，则必须使用 JJ 工作区（相当于 git worktree）来隔离每个 Agent。 有关如何使用 JJ 工作区并行执行的详细指南，请参阅 references/parallel-agents.md。 但是，除非人类用户明确同意，否则不要创建工作区，因为：

• 这会显著增加复杂性；
• 这部分技能仍处于 beta 阶段。

无论如何，你都必须选择向 Agent 分配一个 TODO，还是一组依次处理的 TODO。只向子 Agent 分配一个 TODO 时，最好将 JJ 的细节抽象起来，不让它们加载此技能。 通过执行 jj edit 切换到正确的修订，为它们做好准备，并由你自行处理常规的 JJ 记录工作。 这样，它们就能真正专注于分配给自己的任务，而不会被 JJ 的细节分散注意力。

何时停止并报告（工作者）

只遵循规定的工作流。 如果遇到任何问题，请停止并向用户报告，尤其是在以下情况下：

• 在错误的修订中进行了更改
• 发现之前的工作需要修复或修改
• 不确定该如何继续
• 依赖项或要求不明确

不要尝试使用此工作流中未明确列出的任何 JJ 操作来修复问题。 由用户处理恢复操作。你的工作是遵循流程，或在无法继续时报告。

记录实现偏差（工作者）

如果实现与规范不符，无论原因如何，都要记录并说明理由：

# After implementing, add notes
jj desc -r @ -m "$(jj-show-desc @)

## Post-Implementation notes
- Used argon2 instead of bcrypt. That's because contrary to admin case, here we also needed to comply with...
- Added /auth/logout endpoint. Not in original spec but necessary because...
- Set Rate limit to 5 attempts per minute. Was unspecified, had to make a choice.
"

提醒：如果 jj-show-desc 来自 working-with-jj 技能。

这会留下决策的审计记录。

提示

保持 TODO 精简（规划者）

每个 TODO 都应能在一次专注的工作时段内完成。如果任务太大，就拆分成多个 TODO。

始终使用 --no-edit（规划者与工作者）

创建 TODO 时，始终使用 jj-todo-create 或 jj new --no-edit。 否则，@ 会移动，你会找不到当前位置。

完成规范：不接受“差不多就行”（工作者）

除非满足所有验收标准，否则不要将任务标记为已完成。

✅ 满足以下条件时标记为已完成：

• 已实现所有要求
• 已通过所有验收标准
• 测试通过（如适用）
• 没有已知问题

❌ 绝不要在以下情况下标记为已完成：

• “差不多就行”或“基本能用”
• 测试失败
• 仅完成部分实现
• 用变通方案代替正确修复
• 打算“以后再回来处理”

如果尚未完成：

• 需要反馈时，使用 --mark-as review
• 等待外部依赖时，使用 --mark-as blocked
• 因某种原因无法测试部分内容时，使用 --mark-as untested
• 其他任何原因，使用 --mark-as standby
• 保持 [task:wip] 状态并继续工作

# FIRST: Verify the work
make check        # or: cargo build, pnpm tsc, uv run pytest

# ONLY if all checks pass:
jj-todo-next --mark-as done <next-id>

开始前检查依赖项（工作者）

如果正在处理并行分支或复杂 DAG，在开始新的 TODO 时：

# Check what a task depends on (its immediate ancestors)
jj log -r 'ancestors(<rev-id>,2)'  # 2 for parents, 3 for parents + grandparents, etc.

# Check what depends on a task (its immediate descendants)
jj log -r 'descendants(<rev-id>,2)'  # 2 for children, 3 for children + grandchildren, etc.

如果任何依赖项（祖先任务）带有仍处于 draft、todo、wip 或 blocked 状态的 [task:*] 标记：立即停止并警告用户。继续之前等待用户批准。

注意： jj-todo-next 会自动检查依赖项，并指出哪些子任务尚未就绪，但它只是为了简化操作，并不能取代 jj。需要时，请自行使用 jj log 检查图。

辅助脚本（规划者和工作者）

辅助脚本位于 scripts/ 中。请使用完整路径调用，以避免设置 PATH。

脚本	用途
jj-todo-create [--draft] <PARENT> <TITLE> [DESC]	创建 TODO（保持在 @）。占位任务使用 --draft
jj-parallel-todos [--draft] <PARENT> <T1> <T2>...	创建并行 TODO。占位任务使用 --draft
jj-todo-next [--mark-as STATUS] [REV]	检查规范、检查依赖项、标记状态并可选择移动
jj-flag-update <REV> <TO_FLAG>	更新状态标记（自动检测当前状态）
jj-find-flagged [FLAG]	查找带标记的修订

working-with-jj 技能中的其他实用脚本：

脚本	用途
jj-show-desc [REV]	打印修订说明

参考资料

高级主题和详细指南：

• references/parallel-agents.md - 使用 JJ 工作区并行执行 Agent（规划者）