sdd-tasks

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

sdd-tasks

Breaks down the design into an atomic, ordered, and verifiable task plan.

Triggers:

/sdd-tasks <change-name>

, task plan, break down implementation, task breakdown, sdd tasks

将设计拆解为原子化、有序且可验证的任务计划。

触发方式：

/sdd-tasks <change-name>

、task plan、break down implementation、task breakdown、sdd tasks

Purpose

用途

The task plan converts the design into an executable work list. Each task is atomic (one single thing), concrete (has a file path), and verifiable (can be marked as done).

It is the input for

sdd-apply

. Without an approved tasks file, nothing gets implemented.

任务计划将设计转换为可执行工作清单。每个任务都是原子化的（单一事项）、具体的（包含文件路径）且可验证的（可明确标记为完成）。

它是

sdd-apply

的输入。未经批准的任务文件无法用于任何实现工作。

Process

流程

Skill Resolution

技能解析

When the orchestrator launches this sub-agent, it resolves the skill path using:

1. .claude/skills/sdd-tasks/SKILL.md     (project-local — highest priority)
2. ~/.claude/skills/sdd-tasks/SKILL.md   (global catalog — fallback)

Project-local skills override the global catalog. See

docs/SKILL-RESOLUTION.md

for the full algorithm.

当编排器启动此子Agent时，它会通过以下路径解析技能路径：

1. .claude/skills/sdd-tasks/SKILL.md     (项目本地 — 优先级最高)
2. ~/.claude/skills/sdd-tasks/SKILL.md   (全局目录 — 备用)

项目本地技能会覆盖全局目录。完整算法请参阅

docs/SKILL-RESOLUTION.md

。

Step 0 — Load project context + Spec context preload

步骤0 — 加载项目上下文 + 规格上下文预加载

skills/_shared/sdd-phase-common.md

Section F (Project Context Load) and Section G (Spec Context Preload). Both are non-blocking.

遵循

skills/_shared/sdd-phase-common.md

中的F部分（项目上下文加载）和G部分（规格上下文预加载）。两者均为非阻塞操作。

Step 1 — Read prior artifacts

步骤1 — 读取先前的工件

I must read:

The design artifact (the file matrix and approach):
- ```
mem_search(query: "sdd/{change-name}/design")
```
  →
```
mem_get_observation(id)
```
  .
- If not found and Engram not reachable: design content passed inline from orchestrator.
The spec artifact (the success criteria):
- ```
mem_search(query: "sdd/{change-name}/spec")
```
  →
```
mem_get_observation(id)
```
  .
- If not found and Engram not reachable: spec content passed inline from orchestrator.
The proposal artifact — specifically the
```
## Supersedes
```
section:
- ```
mem_search(query: "sdd/{change-name}/proposal")
```
  →
```
mem_get_observation(id)
```
  .
- If not found and Engram not reachable: proposal content passed inline from orchestrator.

我必须读取：

设计工件（文件矩阵和实现方案）：
- ```
mem_search(query: "sdd/{change-name}/design")
```
  →
```
mem_get_observation(id)
```
  。
- 如果未找到且Engram不可访问：设计内容由编排器直接传入。
规格工件（成功标准）：
- ```
mem_search(query: "sdd/{change-name}/spec")
```
  →
```
mem_get_observation(id)
```
  。
- 如果未找到且Engram不可访问：规格内容由编排器直接传入。
提案工件 — 特别是
```
## Supersedes
```
部分：
- ```
mem_search(query: "sdd/{change-name}/proposal")
```
  →
```
mem_get_observation(id)
```
  。
- 如果未找到且Engram不可访问：提案内容由编排器直接传入。

Step 2 — Analyze dependencies between tasks

步骤2 — 分析任务间的依赖关系

I identify the natural implementation order:

Types/interfaces before their usage
Providers/services before their consumers
Schema/migration before the code that uses them
Unit tests alongside the code (not at the end)
Removals and replacements BEFORE additions (see Step 3 below)

我会确定自然的实现顺序：

类型/接口先于其使用场景
提供者/服务先于其消费者
架构/迁移先于使用它们的代码
单元测试与代码同步进行（而非放在最后）
移除和替换操作优先于新增操作（见下文步骤3）

Step 3 — Generate removal tasks from Supersedes section

步骤3 — 从Supersedes部分生成移除任务

Step 3a — Check Supersedes

步骤3a — 检查Supersedes部分

Read
```
## Supersedes
```
from proposal.md.
If section is absent (older archived change): log
```
INFO: no Supersedes section in proposal.md — skipping removal task generation
```
and proceed to Step 4 with standard phase organization.
If section states "None — purely additive change": skip removal task generation; proceed to Step 4.
If section has REMOVED or REPLACED items: proceed to Step 3b.

读取proposal.md中的
```
## Supersedes
```
部分。
如果该部分不存在（旧的归档变更）：记录
```
INFO: proposal.md中无Supersedes部分 — 跳过移除任务生成
```
，然后按标准阶段组织进入步骤4。
如果该部分注明“None — purely additive change”：跳过移除任务生成；进入步骤4。
如果该部分包含REMOVED或REPLACED项：进入步骤3b。

Step 3b — Generate removal/replacement tasks

步骤3b — 生成移除/替换任务

For each REMOVED item in Supersedes:

Generate one task titled
```
Remove: [feature name]
```
with:
- File paths to delete or modify
- Acceptance criterion: "File deleted AND no runtime errors in related flows"
- Spec reference: linked spec requirement name (if spec exists for this removal)

For each REPLACED item in Supersedes:

Generate two tasks in dependency order:
1. ```
Remove old: [old feature name]
```
  — delete/unregister the old implementation
2. ```
Implement new: [new feature name]
```
  — add the replacement (link to spec requirement)
Note explicit dependency: task 2 cannot start until task 1 is complete.

对于Supersedes中的每个REMOVED项：

生成一个标题为
```
Remove: [功能名称]
```
的任务，包含：
- 要删除或修改的文件路径
- 验收标准：“文件已删除且相关流程无运行时错误”
- 规格引用：关联的规格需求名称（如果此移除操作有对应的规格）

对于Supersedes中的每个REPLACED项：

按依赖顺序生成两个任务：
1. ```
Remove old: [旧功能名称]
```
  — 删除/注销旧实现
2. ```
Implement new: [新功能名称]
```
  — 添加替代实现（关联规格需求）
明确依赖关系：任务2需在任务1完成后才能开始。

Step 3c — Phase 1 organization

步骤3c — 阶段1组织

All removal and replacement tasks (from Step 3b) MUST be grouped into Phase 1: Removals and Replacements. Standard addition/implementation tasks start from Phase 2 or later. Phase 2 MUST NOT begin until Phase 1 is complete — enforce this with an explicit sequencing note in tasks.md.

Removal task format:

markdown

undefined

所有移除和替换任务（来自步骤3b）必须归入Phase 1: Removals and Replacements。标准的新增/实现任务从Phase 2或更靠后的阶段开始。Phase 2必须在Phase 1完成后才能开始 — 在tasks.md中添加明确的顺序说明来强制执行此规则。

移除任务格式：

markdown

undefined

Phase 1: Removals and Replacements

1.1 Remove: [feature name] from
```
path/to/file
```
Linked spec: [Requirement name from spec, or "N/A — no spec for this removal"] Files:
```
path/to/file
```
(DELETE),
```
path/to/other.ts
```
(remove registration/import) Acceptance: File deleted AND related flows continue without runtime errors
1.2 Remove old: [old feature name] from
```
path/to/old-file
```
Linked spec: [Requirement: Replacement requirement name] Files:
```
path/to/old-file
```
(DELETE or MODIFY) Acceptance: Old implementation fully removed; no lingering imports or references
1.3 Implement new: [new feature name] in
```
path/to/new-file
```
Linked spec: [Requirement: new feature requirement] Depends on: 1.2 Files:
```
path/to/new-file
```
(CREATE or MODIFY) Acceptance: New implementation active; spec scenarios pass

⚠️ Phase 2 MUST NOT begin until all Phase 1 tasks are complete.

undefined

1.1 Remove: [feature name] from
```
path/to/file
```
Linked spec: [Requirement name from spec, or "N/A — no spec for this removal"] Files:
```
path/to/file
```
(DELETE),
```
path/to/other.ts
```
(remove registration/import) Acceptance: File deleted AND related flows continue without runtime errors
1.2 Remove old: [old feature name] from
```
path/to/old-file
```
Linked spec: [Requirement: Replacement requirement name] Files:
```
path/to/old-file
```
(DELETE or MODIFY) Acceptance: Old implementation fully removed; no lingering imports or references
1.3 Implement new: [new feature name] in
```
path/to/new-file
```
Linked spec: [Requirement: new feature requirement] Depends on: 1.2 Files:
```
path/to/new-file
```
(CREATE or MODIFY) Acceptance: New implementation active; spec scenarios pass

⚠️ Phase 2 MUST NOT begin until all Phase 1 tasks are complete.

undefined

Step 4 — Organize addition tasks into phases

步骤4 — 将新增任务组织为多个阶段

I group addition/implementation tasks into logical phases after Phase 1 (or Phase 1 if no removals):

Phase 1 — Removals and Replacements [if Supersedes has items] OR Foundation [if purely additive]
Phase 2 — Foundation: types, interfaces, schemas, configuration [if Phase 1 is Removals]
Phase N — Core: main business logic
Phase N+1 — Integration: connect with the rest of the system
Phase N+2 — Testing: tests for previous phases
Phase N+3 — Cleanup: remove temporary code, update docs

(I adapt phase names to the context of the change)

我会将新增/实现任务分为多个逻辑阶段，位于Phase 1之后（如果没有移除操作，则从Phase 1开始）：

Phase 1 — Removals and Replacements [如果Supersedes包含项] 或 Foundation [如果仅为新增变更]
Phase 2 — Foundation: 类型、接口、架构、配置 [如果Phase 1是Removals]
Phase N — Core: 主要业务逻辑
Phase N+1 — Integration: 与系统其他部分连接
Phase N+2 — Testing: 前序阶段的测试
Phase N+3 — Cleanup: 移除临时代码、更新文档

（我会根据变更的上下文调整阶段名称）

Step 5 — Create tasks.md

步骤5 — 创建tasks.md

Step 4a — Warning Classification Rules

步骤4a — 警告分类规则

While analyzing each task, I MUST identify ambiguities, risks, or open decisions that could affect implementation. For each one found, I classify it as one of:

MUST_RESOLVE
— A warning that blocks implementation until the user provides an explicit answer. Use this when:
- The task involves a business rule decision that has multiple valid interpretations
- The task depends on an external system behavior that is ambiguous (e.g., which field to use in an API response)
- The task cannot be implemented correctly without knowing the user's intent
- Example reason:
```
"business rule decision — external system behavior is ambiguous"
```
ADVISORY
— A warning that is logged for awareness but does not block implementation. Use this when:
- The concern is a performance consideration that does not affect functional correctness
- The concern is a style or naming preference with no impact on task completion
- The concern is informational and the implementer can safely proceed without further input
- Example reason:
```
"performance consideration — does not affect correctness"
```
- Example reason:
```
"style or naming preference — no impact on current task"
```

Each warning classification MUST include a reason statement explaining why it belongs in its category.

在分析每个任务时，我必须识别可能影响实现的歧义、风险或未决决策。对于每个发现的问题，将其分类为以下类型之一：

MUST_RESOLVE
— 此类警告会阻塞实现，直到用户提供明确答复。适用于以下场景：
- 任务涉及存在多种合理解释的业务规则决策
- 任务依赖于模糊的外部系统行为（例如，API响应中应使用哪个字段）
- 不了解用户意图就无法正确实现任务
- 示例原因：
```
"business rule decision — external system behavior is ambiguous"
```
ADVISORY
— 此类警告仅用于告知，不会阻塞实现。适用于以下场景：
- 问题是不影响功能正确性的性能考虑因素
- 问题是对任务完成无影响的风格或命名偏好
- 问题仅为信息性内容，实现者无需进一步输入即可安全继续
- 示例原因：
```
"performance consideration — does not affect correctness"
```
- 示例原因：
```
"style or naming preference — no impact on current task"
```

每个警告分类必须包含原因说明，解释其所属类别的理由。

Step 4b — Record warnings in tasks.md

步骤4b — 在tasks.md中记录警告

Every warning identified in Step 4a MUST be recorded inline with the affected task in

tasks.md

, using the following formats:

MUST_RESOLVE format:

markdown

- [ ] X.Y Task description [WARNING: MUST_RESOLVE]
  Warning: [human-readable warning text]
  Reason: [classification reason, e.g., "business rule decision — external system field ambiguous"]
  Question: [clarifying question derived from the warning]

ADVISORY format:

markdown

- [ ] X.Y Task description [WARNING: ADVISORY]
  Warning: [human-readable warning text]
  Reason: [classification reason, e.g., "performance consideration — does not affect correctness"]

Placement rules:

Warnings appear immediately below their task entry, indented with two spaces
A task may have at most one warning entry (combine multiple concerns into one if needed)
Tasks without warnings have no indented block below them

Example task with MUST_RESOLVE warning:

markdown

- [ ] 2.1 Create `src/services/payment.service.ts` with method `processPayment(dto: PaymentDto): Promise<PaymentResult>` [WARNING: MUST_RESOLVE]
  Warning: Stripe invoice field for failure date is ambiguous — `status_transitions.marked_uncollectible_at` vs `status_transitions.voided_at` may both apply depending on invoice state.
  Reason: business rule decision — external system behavior is ambiguous
  Question: Which Stripe invoice field should be used to record the payment failure date?

I persist the task plan to engram:

Call

mem_save

with

topic_key: sdd/{change-name}/tasks

type: architecture

project: {project}

, content = full tasks markdown. Do NOT write any file.

If Engram MCP is not reachable: skip persistence. Return task plan content inline only.

Content format:

markdown

undefined

步骤4a中识别的每个警告必须与受影响的任务一起内联记录在

tasks.md

中，使用以下格式：

MUST_RESOLVE格式：

markdown

- [ ] X.Y Task description [WARNING: MUST_RESOLVE]
  Warning: [human-readable warning text]
  Reason: [classification reason, e.g., "business rule decision — external system field ambiguous"]
  Question: [clarifying question derived from the warning]

ADVISORY格式：

markdown

- [ ] X.Y Task description [WARNING: ADVISORY]
  Warning: [human-readable warning text]
  Reason: [classification reason, e.g., "performance consideration — does not affect correctness"]

放置规则：

警告紧跟在其任务条目下方，缩进两个空格
一个任务最多只能有一个警告条目（如有多个问题，需合并为一个）
无警告的任务下方无需添加缩进块

带有MUST_RESOLVE警告的任务示例：

markdown

- [ ] 2.1 Create `src/services/payment.service.ts` with method `processPayment(dto: PaymentDto): Promise<PaymentResult>` [WARNING: MUST_RESOLVE]
  Warning: Stripe invoice field for failure date is ambiguous — `status_transitions.marked_uncollectible_at` vs `status_transitions.voided_at` may both apply depending on invoice state.
  Reason: business rule decision — external system behavior is ambiguous
  Question: Which Stripe invoice field should be used to record the payment failure date?

我会将任务计划保存到Engram：

调用

mem_save

，参数为

topic_key: sdd/{change-name}/tasks

、

type: architecture

、

project: {project}

，content为完整的任务markdown内容。请勿写入任何文件。

如果Engram MCP不可访问：跳过持久化操作。仅直接返回任务计划内容。

内容格式：

markdown

undefined

Task Plan: [change-name]

Date: [YYYY-MM-DD] Design: engram:sdd/[name]/design

Progress: 0/[total] tasks

Phase 1: [Phase Name]

1.1 Create

src/types/auth.types.ts

with interfaces

LoginRequest

LoginResponse

JwtPayload

1.2 Create
```
src/schemas/auth.schema.ts
```
with Zod schemas for login validation

1.3 Modify

src/config/jwt.config.ts

— add

refreshSecret

and

refreshExpiresIn

1.1 Create

src/types/auth.types.ts

with interfaces

LoginRequest

LoginResponse

JwtPayload

1.2 Create
```
src/schemas/auth.schema.ts
```
with Zod schemas for login validation

1.3 Modify

src/config/jwt.config.ts

— add

refreshSecret

and

refreshExpiresIn

Phase 2: [Phase Name]

2.1 Create

src/services/auth.service.ts

with methods

login()

logout()

refreshToken()

2.2 Modify

src/repositories/user.repository.ts

— add

findByEmail()

method

2.3 Create
```
src/middleware/auth.middleware.ts
```
for JWT validation on protected routes

2.1 Create

src/services/auth.service.ts

with methods

login()

logout()

refreshToken()

2.2 Modify

src/repositories/user.repository.ts

— add

findByEmail()

method

2.3 Create
```
src/middleware/auth.middleware.ts
```
for JWT validation on protected routes

Phase 3: [Phase Name]

3.1 Create
```
src/controllers/auth.controller.ts
```
with endpoints POST /login, POST /logout, POST /refresh
3.2 Modify
```
src/routes/index.ts
```
— register auth routes
3.3 Modify
```
src/app.ts
```
— integrate auth middleware on protected routes

3.1 Create
```
src/controllers/auth.controller.ts
```
with endpoints POST /login, POST /logout, POST /refresh
3.2 Modify
```
src/routes/index.ts
```
— register auth routes
3.3 Modify
```
src/app.ts
```
— integrate auth middleware on protected routes

Phase 4: Testing

4.1 Create
```
tests/unit/auth.service.spec.ts
```
— unit tests for AuthService

4.2 Create

tests/integration/auth.controller.spec.ts

— endpoint tests

4.3 Verify scenario coverage from spec (review engram:sdd/[name]/spec)

4.1 Create
```
tests/unit/auth.service.spec.ts
```
— unit tests for AuthService

4.2 Create

tests/integration/auth.controller.spec.ts

— endpoint tests

4.3 Verify scenario coverage from spec (review engram:sdd/[name]/spec)

Phase 5: Cleanup

5.1 Update
```
README.md
```
— document new endpoints
5.2 Update
```
ai-context/architecture.md
```
if there were structural changes

5.1 Update
```
README.md
```
— document new endpoints
5.2 Update
```
ai-context/architecture.md
```
if there were structural changes

Implementation Notes

[Design decisions the implementer must keep in mind:]

[important note 1]
[important note 2]

[Design decisions the implementer must keep in mind:]

[important note 1]
[important note 2]

Blockers

[Tasks that cannot start until something external is ready:]

[blocker]: [what resolves it]

[If none: "None."]

---

[Tasks that cannot start until something external is ready:]

[blocker]: [what resolves it]

[If none: "None."]

---

Format of a well-written task

优质任务的格式

Well written

优质示例

- [ ] 2.1 Create `src/services/payment.service.ts` with method `processPayment(dto: PaymentDto): Promise<PaymentResult>`

- [ ] 2.1 Create `src/services/payment.service.ts` with method `processPayment(dto: PaymentDto): Promise<PaymentResult>`

Poorly written

不良示例

- [ ] Add payment logic

Rule: Each task must answer "which file and what specific change?"

- [ ] Add payment logic

规则：每个任务必须回答“哪个文件？具体变更是什么？”

Output to Orchestrator

向编排器输出

Return ONLY this JSON block. Do NOT add free-form text, command suggestions, or implementation steps after it.

json

{
  "status": "ok|warning|blocked",
  "summary": "Plan for [change-name]: [N] phases, [M] total tasks. Estimate: [Low/Medium/High].",
  "artifacts": ["engram:sdd/{change-name}/tasks"],
  "next_recommended": ["sdd-apply"],
  "risks": ["[blocker if any]"]
}

The orchestrator will present

next_recommended

to the user as

/sdd-apply

(hyphen-separated, with slash prefix). Do not format it yourself.

仅返回以下JSON块。请勿添加自由格式文本、命令建议或实现步骤。

json

{
  "status": "ok|warning|blocked",
  "summary": "Plan for [change-name]: [N] phases, [M] total tasks. Estimate: [Low/Medium/High].",
  "artifacts": ["engram:sdd/{change-name}/tasks"],
  "next_recommended": ["sdd-apply"],
  "risks": ["[blocker if any]"]
}

编排器会将

next_recommended

以

/sdd-apply

的形式呈现给用户（连字符分隔，带斜杠前缀）。请勿自行格式化。

Rules

规则

HARD STOP: My only output is
```
tasks.md
```
+ the JSON block. I NEVER implement any task, write code, or modify project files beyond creating tasks.md
Each task MUST have a concrete file path
Each task MUST be atomic (single responsibility)
Each task MUST be verifiable (can be marked done with certainty)
Tests go with their code, not all at the end
Phase order respects technical dependencies
Documentation and memory tasks (ai-context) go in the last phase
I do NOT include tasks that go beyond the proposal's scope
If I detect that the design is incomplete to generate tasks, I report it as a blocker

硬性要求：我的输出只能是
```
tasks.md
```
+ JSON块。我绝不会实现任何任务、编写代码或修改项目文件（除了创建tasks.md）
每个任务必须包含具体的文件路径
每个任务必须是原子化的（单一职责）
每个任务必须是可验证的（可明确标记为完成）
测试与代码同步进行，而非全部放在最后
阶段顺序需遵循技术依赖关系
文档和内存任务（ai-context）放在最后一个阶段
我不会包含超出提案范围的任务
如果我发现设计不足以生成任务，会将其报告为阻塞项