task-spec-execution

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Task Spec Execution

任务规格执行

Use this skill after roadmap structure exists and one concrete task is selected or ready to be selected.

当路线图结构已存在且已选定或准备选定一个具体任务时，使用此技能。

Composition

职责范围

Entry: reached from
```
doc-driven-spec-workflow
```
or
```
milestone-planning
```
after a concrete task exists or is selected.
Owns: task-local
```
spec.md
```
, optional task-local
```
plan.md
```
, readiness checks, implementation governance, verification, docs/status updates, and branch closing.
Does not own: minimum docs scaffold bootstrap, milestone boundary decisions, module grouping, roadmap-layer task creation, or planning-stage templates.
Handoff: return to
```
doc-driven-spec-workflow
```
after one concrete task checkpoint and branch closing are resolved.

入口：当存在或选定具体任务后，从
```
doc-driven-spec-workflow
```
或
```
milestone-planning
```
进入此流程。
负责内容：任务级的
```
spec.md
```
、可选的任务级
```
plan.md
```
、就绪检查、实现管控、验证、文档/状态更新以及分支关闭。
不负责内容：基础文档脚手架初始化、里程碑边界决策、模块分组、路线图层级的任务创建或规划阶段模板。
交接：完成一个具体任务的检查点和分支关闭后，返回
```
doc-driven-spec-workflow
```
。

Core Rules

核心规则

Spec and Plan

规格说明与计划

Spec: defines behavior, scope, exclusions, and tradeoffs.
Plan: defines implementation slices, file map, and verification (only when complexity justifies it).
Do not collapse into one document.
Default to task-local
```
spec.md
```
and optional
```
plan.md
```
; use global
```
docs/specs/
```
or
```
docs/plans/
```
only for standalone or cross-task docs.
Do not create a new spec for pure docs governance work such as architecture edits, task/module reshaping, milestone changes, or index maintenance.
Default to
```
1 task -> 1 spec
```
. Revise the existing spec for corrections or clarifications instead of creating another one.
If multiple specs seem necessary, stop and use
```
milestone-planning
```
to split the task first.

规格说明（Spec）：定义行为、范围、排除项和权衡方案。
计划（Plan）：定义实现拆分、文件映射和验证方式（仅当复杂度较高时需要）。
请勿将两者合并为单个文档。
默认使用任务级的
```
spec.md
```
和可选的
```
plan.md
```
；仅当文档为独立或跨任务内容时，才使用全局的
```
docs/specs/
```
或
```
docs/plans/
```
目录。
对于纯文档管控工作（如架构编辑、任务/模块重构、里程碑变更或索引维护），无需创建新的规格说明。
默认遵循「1个任务对应1份规格说明」的原则。如需修正或澄清，应修改现有规格说明，而非创建新的。
若认为需要多份规格说明，请先停止当前操作，使用
```
milestone-planning
```
拆分任务。

Governance Mode

管控模式

Mode	Work Type	Requires Spec
Docs governance	Architecture edits, task/module reshaping, milestone updates, index maintenance	No
Implementation governance	Code edits for concrete `docs/tasks/*` task	Yes

Keep pure docs governance in docs mode. It does not create implementation permission.
Defer minimum docs scaffold initialization to
```
docs-workflow-bootstrap
```
.
This skill may read or maintain bootstrap-created docs after they exist, but it is not the primary owner of repository scaffold initialization.
Defer roadmap decomposition, milestone boundaries, module grouping, and task reshaping to
```
milestone-planning
```
.

模式	工作类型	是否需要规格说明
文档管控	架构编辑、任务/模块重构、里程碑更新、索引维护	否
实现管控	针对具体 `docs/tasks/*` 任务的代码编辑	是

纯文档管控工作需保持在文档模式下，不产生实现权限。
基础文档脚手架初始化请交由
```
docs-workflow-bootstrap
```
处理。
此技能可读取或维护已初始化的脚手架文档，但并非仓库脚手架初始化的主要负责方。
路线图分解、里程碑边界、模块分组和任务重构请交由
```
milestone-planning
```
处理。

Implementation Requirements

实现要求

Before code edits:

Spec approval
Plan approval (when required)
Branch/worktree isolation
Readiness checkpoint

Do not edit implementation code for a concrete
```
docs/tasks/*
```
task until all four conditions are satisfied.
Resolve a docs checkpoint for approved task-local docs before implementation isolation.

代码编辑前需满足以下条件：

规格说明已获批
计划已获批（如有需要）
分支/工作区已隔离
就绪检查已完成

在四个条件全部满足前，不得编辑具体
```
docs/tasks/*
```
任务的实现代码。
在实现隔离前，需完成已获批任务级文档的检查点确认。

Branch Isolation Rules

分支隔离规则

Situation	Action
Workspace dirty, shared, risky, or likely to conflict	Use `superpowers:using-git-worktrees` or equivalent safe worktree workflow
Workspace clean and isolation risk is low	Create dedicated task branch in place
User explicitly asks to stay on current branch	Only with explicit user choice

Default: never start implementation on current branch. Do not carry approved-but-uncommitted task-local docs into implementation worktree by default.

场景	操作
工作区脏污、共享、存在风险或可能冲突	使用 `superpowers:using-git-worktrees` 或等效的安全工作区流程
工作区干净且隔离风险低	在当前位置创建专用任务分支
用户明确要求留在当前分支	仅在用户明确选择时执行

默认规则：绝不在当前分支启动实现工作。默认情况下，请勿将已获批但未提交的任务级文档带入实现工作区。

Checkpoint Flow

检查点流程

Complexity	Flow
Default	`spec -> user confirms -> docs checkpoint -> code`
Complex	`spec -> user confirms -> plan -> user confirms -> docs checkpoint -> code`

Hard pause at concrete task: report verification/docs updates, resolve commit or approved uncommitted checkpoint, resolve branch closing, then stop.
Milestone completion is hard boundary: frozen after move to
```
Completed Milestones
```
.
Crossing milestones: resolve previous milestone closure and new milestone confirmation first.
For docs-only or governance work, stop after reporting changed files and key diffs. Do not commit unless the user asked for it up front or confirms after review.

复杂度	流程
默认	`规格说明 -> 用户确认 -> 文档检查点 -> 代码实现`
复杂	`规格说明 -> 用户确认 -> 计划 -> 用户确认 -> 文档检查点 -> 代码实现`

在具体任务处强制暂停：报告验证/文档更新情况，完成提交或已获批未提交内容的检查点确认，完成分支关闭，然后停止操作。
里程碑完成是强制边界：移入「已完成里程碑」后即冻结。
跨里程碑操作：需先完成前一个里程碑的关闭和新里程碑的确认。
对于纯文档或管控工作，报告变更文件和关键差异后即可停止。除非用户事先要求或审阅后确认，否则请勿提交。

Branch Closing

分支关闭

After completing concrete
```
docs/tasks/*
```
task, do not start another task until branch closing is resolved.

Use

superpowers:finishing-a-development-branch

for merge/PR/keep/discard options.

Use
```
superpowers:using-git-worktrees
```
cleanup rules for worktree cleanup.
Removing a worktree does not remove its task branch.
If the user chooses merge and cleanup, confirm whether cleanup includes deleting the fully merged task branch before deleting it.
Never delete branch or worktree without confirming closing decision.
If user asks to "continue", treat as prompt to resolve branch closing first.

完成具体
```
docs/tasks/*
```
任务后，在分支关闭前不得启动新任务。
使用
```
superpowers:finishing-a-development-branch
```
处理合并/PR/保留/废弃选项。
使用
```
superpowers:using-git-worktrees
```
的清理规则处理工作区清理。
删除工作区不会删除其对应的任务分支。
若用户选择合并并清理，需确认清理是否包含删除已完全合并的任务分支，再执行删除操作。
未经确认关闭决策，不得删除分支或工作区。
若用户要求「继续」，需先完成分支关闭操作。

Task And Status Rules

任务与状态规则

Use
```
docs/tasks/
```
to decide next task, not
```
docs/context/
```
.
Do not infer new concrete task from
```
docs/architecture/
```
alone.
If architecture implies follow-up work but
```
docs/tasks/
```
has no open task, use
```
milestone-planning
```
first.
Tasks inside unconfirmed milestone (
```
Roadmap confirmed: no
```
) are not suitable open work.
Respect task sizing. If too small, too broad, or only sub-step, stop and use
```
milestone-planning
```
.
Completed milestones are frozen. Never reopen or add modules/tasks.
Tasks fit one focused branch including implementation, tests, docs/status updates, code review, verification.
Keep implementation steps inside
```
spec.md
```
, optional
```
plan.md
```
, or checklist items; do not promote into tasks.
Task-level
```
Depends on
```
stays within same milestone normally. Put cross-milestone sequencing in milestone-level notes.
Respect task dependencies exactly as written.
Keep task status mutually exclusive:
```
planned
```
,
```
in_progress
```
,
```
blocked
```
,
```
completed
```
.

docs/tasks/index.md

lists

Open Milestones

and

Completed Milestones

, no modules or task counts.

Move milestones from open to completed only when whole milestone done; no
```
[completed/total]
```
.
Do not begin task from later milestone until previous milestone intentionally active by explicit user choice or reviewed for closure and target milestone explicitly confirmed.
Keep milestone/module indexes accurate, do not redesign structure here.
Each concrete task: directory with
```
task.md
```
, task-local
```
spec.md
```
, optional
```
plan.md
```
.
```
task.md
```
tracks status, dependencies, acceptance points; not detailed step-by-step plan.
When all open tasks complete, report if milestone appears complete. Use
```
milestone-planning
```
before moving milestone state or adding missing work.
Pure cleanup, concept clarification, docs governance belongs in current work round by default. Create task directory only for complex/cross-cutting governance with independent acceptance or project-level execution state; even then, do not create spec unless it drives concrete implementation.
Use
```
docs/tasks/
```
as the only source of truth for concrete next work.
Tasks in a milestone still marked
```
Roadmap confirmed: no
```
remain candidate tasks only until milestone entry is explicitly confirmed.
Resolve the previous task checkpoint before starting another concrete task.
Report milestone-entry governance changes before drafting the first task spec in that milestone.

使用
```
docs/tasks/
```
目录确定下一个任务，而非
```
docs/context/
```
。
不得仅从
```
docs/architecture/
```
推断新的具体任务。
若架构隐含后续工作但
```
docs/tasks/
```
中无开放任务，请先使用
```
milestone-planning
```
。
未确认里程碑（标记为「Roadmap confirmed: no」）内的任务不适宜作为开放工作。
需遵循任务规模要求。若任务过小、过宽泛或仅为子步骤，请停止操作并使用
```
milestone-planning
```
。
已完成的里程碑处于冻结状态，不得重新打开或添加模块/任务。
每个任务应对应一个聚焦分支，包含实现、测试、文档/状态更新、代码评审和验证。
实现步骤需保留在
```
spec.md
```
、可选的
```
plan.md
```
或检查项中，不得提升为独立任务。
任务级的「依赖」通常应属于同一里程碑。跨里程碑的顺序安排需放在里程碑级备注中。
需严格遵循任务依赖的书面定义。
任务状态需保持互斥：
```
planned
```
（计划中）、
```
in_progress
```
（进行中）、
```
blocked
```
（阻塞）、
```
completed
```
（已完成）。
```
docs/tasks/index.md
```
需列出「开放里程碑」和「已完成里程碑」，无需包含模块或任务数量。
仅当整个里程碑完成时，才可将其从开放状态移入已完成状态；不得使用「[已完成/总数]」的标记方式。
在前一个里程碑未被用户明确选择激活或未完成关闭审核、目标里程碑未被明确确认前，不得启动后续里程碑的任务。
需保持里程碑/模块索引准确，不得在此流程中重新设计结构。
每个具体任务需对应一个目录，包含
```
task.md
```
、任务级
```
spec.md
```
和可选的
```
plan.md
```
。
```
task.md
```
用于跟踪状态、依赖和验收要点；不得包含详细的分步计划。
当所有开放任务完成时，需报告里程碑是否已完成。在变更里程碑状态或添加遗漏工作前，请先使用
```
milestone-planning
```
。
纯清理工作、概念澄清、文档管控默认属于当前工作周期。仅当管控工作复杂/跨领域且有独立验收标准或项目级执行状态时，才需创建任务目录；即便如此，除非该管控工作驱动具体实现，否则无需创建规格说明。
需将
```
docs/tasks/
```
作为确定下一项具体工作的唯一可信来源。
标记为「Roadmap confirmed: no」的里程碑内的任务仅为候选任务，需待里程碑条目被明确确认后才可执行。
启动新的具体任务前，需完成前一个任务的检查点确认。
在起草某里程碑的首个任务规格说明前，需报告里程碑条目管控的变更情况。

Docs Boundaries

文档边界

```
docs/architecture/
```
holds stable behavior and long-lived constraints.
```
docs/tasks/
```
holds roadmap state, milestone or module indexes, and concrete task directories.
```
docs/context/
```
holds supporting research and unstable reference material.
Treat code as the source of truth when code and docs diverge.
If implementation changes behavior, API shape, task status, architecture assumptions, or other documented constraints, update the relevant docs in the same round.
If a conclusion in
```
docs/context/
```
becomes a stable system rule, move or restate it in
```
docs/architecture/
```
.

```
docs/architecture/
```
目录存放稳定的行为定义和长期约束。
```
docs/tasks/
```
目录存放路线图状态、里程碑或模块索引以及具体任务目录。
```
docs/context/
```
目录存放辅助研究和不稳定的参考资料。
当代码与文档出现分歧时，以代码为可信来源。
若实现变更了行为、API形态、任务状态、架构假设或其他已记录的约束，需在同一工作周期内更新相关文档。
若
```
docs/context/
```
中的结论成为稳定的系统规则，需将其迁移或重述至
```
docs/architecture/
```
目录。

Detailed Rules and Violations

详细规则与违规处理

For stop conditions, low-frequency execution details, and template-loading guidance, see references/task-execution-detailed-rules.md.

关于停止条件、低频率执行细节和模板加载指南，请参阅references/task-execution-detailed-rules.md。

Workflow

工作流程

Follow this order unless the user explicitly asks for something different:

If the user's feature, behavior, or task intent is ambiguous, use
```
superpowers:brainstorming
```
when available, or an equivalent clarification workflow, before selecting or creating a concrete task.
If the main uncertainty is roadmap shape rather than current-task design, use
```
milestone-planning
```
before continuing here.
Read
```
docs/index.md
```
and the relevant docs index files.
Read the relevant
```
docs/architecture/
```
documents for behavior boundaries.
Read the relevant
```
docs/tasks/
```
milestone/module index plus task directory or
```
task.md
```
for order, status, and dependencies.
Use
```
docs/context/
```
only for supporting research or unstable reference material.
If there is no suitable open task because the roadmap shape itself is missing or unclear, stop and use
```
milestone-planning
```
.
If the next candidate task is in a new milestone, first verify that the previous milestone checkpoint is closed and the target milestone is explicitly confirmed for entry. If not, stop and resolve milestone governance first.
If implementing one concrete task, create or update its task directory and write one focused
```
spec.md
```
inside it.
Stop after writing the spec; do not code until the user explicitly confirms it in the current thread.
Create
```
plan.md
```
inside the task directory only for genuinely complex or multi-step work; if created, stop again for user confirmation before coding.
After spec approval, and after plan approval when a plan exists, resolve a docs checkpoint for the approved task-local docs before implementation isolation.
Before implementation edits, announce and run the readiness checkpoint.
Implement from the approved spec or plan, then verify, update docs/status, and resolve branch closing.
Stop after one concrete task. Continue only when the user explicitly asks in the current thread.
Add an
```
index.md
```
for every new major documentation section.

除非用户明确要求，否则请遵循以下顺序：

若用户提出的功能、行为或任务意图不明确，在选定或创建具体任务前，若可用请使用
```
superpowers:brainstorming
```
，或采用等效的澄清流程。
若主要不确定性在于路线图形态而非当前任务设计，请先使用
```
milestone-planning
```
。
阅读
```
docs/index.md
```
和相关文档索引文件。
阅读相关
```
docs/architecture/
```
文档，了解行为边界。
阅读相关
```
docs/tasks/
```
的里程碑/模块索引以及任务目录或
```
task.md
```
，了解顺序、状态和依赖关系。
仅将
```
docs/context/
```
用于辅助研究或不稳定参考资料。
若因路线图形态缺失或不清晰而没有合适的开放任务，请停止操作并使用
```
milestone-planning
```
。
若下一个候选任务属于新里程碑，需先验证前一个里程碑的检查点已关闭且目标里程碑已被明确确认可进入。若未满足，请停止操作并先完成里程碑管控。
若实现一个具体任务，需创建或更新其任务目录，并在其中编写一份聚焦的
```
spec.md
```
。
完成规格说明编写后停止操作；在用户当前线程中明确确认前，不得进行代码实现。
仅当工作确实复杂或多步骤时，才在任务目录中创建
```
plan.md
```
；若创建了计划，需再次等待用户确认后才可进行代码实现。
规格说明获批后（如有计划则需计划也获批），在实现隔离前需完成已获批任务级文档的检查点确认。
在实现编辑前，需告知用户并执行就绪检查。
根据获批的规格说明或计划进行实现，然后验证、更新文档/状态并完成分支关闭。
完成一个具体任务后停止操作。仅当用户在当前线程中明确要求时，才可继续。
每个新的主要文档章节需添加
```
index.md
```
。

When To Use

使用场景

Use this skill when:

The repository uses
```
docs/architecture
```
,
```
docs/tasks
```
,
```
docs/context
```
, and task-local or standalone specs/plans
The current concrete task has been chosen or is ready to be chosen from the existing roadmap

Use

milestone-planning

first when the user is still deciding milestone/module/task structure.

Do not use for repositories without this layout.

在以下场景中使用此技能：

仓库使用
```
docs/architecture
```
、
```
docs/tasks
```
、
```
docs/context
```
目录，以及任务级或独立的规格说明/计划
当前具体任务已从现有路线图中选定或准备选定

当用户仍在确定里程碑/模块/任务结构时，请先使用

milestone-planning

。

请勿在未采用此布局的仓库中使用此技能。