speckit-tasks

用户输入

$ARGUMENTS

如果用户输入不为空，在继续之前必须先考虑用户输入。

执行前检查

检查扩展钩子（生成任务之前）：

• 检查项目根目录中是否存在 .specify/extensions.yml。
• 如果存在，请读取文件并查找 hooks.before_tasks 键下的条目。
• 如果 YAML 无法解析或无效，不要默默跳过：告知用户无法读取 .specify/extensions.yml（包括解析器错误），并说明未检查任何钩子，包括在那里注册的任何强制钩子（optional: false），然后正常继续。
• 过滤掉 enabled 明确为 false 的钩子。未设置 enabled 字段的钩子默认视为已启用。
• 对于其余钩子，不要尝试解释或计算钩子的 condition 表达式：
  • 如果钩子没有 condition 字段，或者该字段为 null／空，则将钩子视为可执行。
  • 如果钩子定义了非空的 condition，则跳过该钩子，并将条件计算留给 HookExecutor 实现。
• 根据钩子命令名称构造命令调用时，将句点（.）替换为连字符（-）。例如，speckit.git.commit → /speckit-git-commit。
• 对于每个可执行钩子，根据其 optional 标记输出以下内容：

  • 可选钩子（optional: true）：

    ## 扩展钩子
    
    **可选前置钩子**：{extension}
    命令：`/{command}`
    描述：{description}
    
    提示词：{prompt}
    执行方式：`/{command}`
    

  • 强制钩子（optional: false）：

    ## 扩展钩子
    
    **自动前置钩子**：{extension}
    正在执行：`/{command}`
    EXECUTE_COMMAND: {command}
    
    等待钩子命令的执行结果后，再继续生成大纲。
    

    输出以上内容后，你必须实际调用钩子，并等待其执行完成后才能继续。以你在此 Agent／会话中亲自运行命令的方式调用它（实际调用方式可能与显示的 {command} ID 不同，例如，技能模式的 Agent 运行 /skill:speckit-... 或 $speckit-...）。仅输出该内容并不等于运行钩子。

• 如果没有注册任何钩子，或者 .specify/extensions.yml 不存在，则静默跳过。

大纲

1. 设置：在仓库根目录运行 .specify/scripts/bash/setup-tasks.sh --json，并解析 FEATURE_DIR、TASKS_TEMPLATE_CONTENT、TASKS_TEMPLATE 和 AVAILABLE_DOCS 列表。提供时，FEATURE_DIR 和 TASKS_TEMPLATE 必须是绝对路径。AVAILABLE_DOCS 是 FEATURE_DIR 下可用文档名称／相对路径的列表（例如 research.md 或 contracts/）。对于 "I'm Groot" 这类参数中的单引号，请使用转义语法：例如 'I'''m Groot'（或尽可能使用双引号："I'm Groot"）。

2. 加载设计文档：从 FEATURE_DIR 读取：

   • 必需：plan.md（技术栈、库、结构）、spec.md（带优先级的用户故事）
   • 可选：data-model.md（实体）、contracts/（接口契约）、research.md（决策）、quickstart.md（测试场景）
   • 如果存在：加载 .specify/memory/constitution.md，以了解项目原则和治理约束
   • 注意：并非所有项目都包含所有文档。根据现有文档生成任务。

3. 执行任务生成工作流：

   • 加载 plan.md，提取技术栈、库和项目结构
   • 加载 spec.md，提取带优先级的用户故事（P1、P2、P3 等）
   • 如果 data-model.md 存在：提取实体并映射到用户故事
   • 如果 contracts/ 存在：将接口契约映射到用户故事
   • 如果 research.md 存在：提取用于设置任务的决策
   • 按用户故事组织生成任务（见下方任务生成规则）
   • 生成依赖关系图，展示用户故事的完成顺序
   • 为每个用户故事创建并行执行示例
   • 验证任务完整性（每个用户故事都包含所有必要任务，且可独立测试）

4. 生成 tasks.md：使用 TASKS_TEMPLATE_CONTENT（来自上述 JSON 输出）作为结构。为兼容省略 TASKS_TEMPLATE_CONTENT 的旧版设置脚本，请改为读取 TASKS_TEMPLATE。填写以下内容：

   • 来自 plan.md 的正确功能名称
   • 阶段 1：设置任务（项目初始化）
   • 阶段 2：基础任务（所有用户故事的阻塞性前置条件）
   • 阶段 3+：每个用户故事各一个阶段（按 spec.md 中的优先级排序）
   • 每个阶段包含：故事目标、独立测试标准、测试（如有要求）、实现任务
   • 最终阶段：润色与横切关注点
   • 所有任务必须遵循严格的清单格式（见下方任务生成规则）
   • 为每项任务提供清晰的文件路径
   • 依赖关系部分展示故事完成顺序
   • 为每个故事提供并行执行示例
   • 实施策略部分（先实现 MVP，再逐步交付）

必需的执行后钩子

在向用户报告完成之前，你必须完成本节。

检查项目根目录中是否存在 .specify/extensions.yml。

• 如果该文件不存在，或者 hooks.after_tasks 下没有注册钩子，则跳转到完成报告。
• 如果该文件存在，则读取文件并查找 hooks.after_tasks 键下的条目。
• 如果无法解析 YAML 或 YAML 无效，不要悄悄跳过：告知用户无法读取 .specify/extensions.yml（包括解析器错误），并说明未检查任何钩子，包括在那里注册的任何必需钩子（optional: false），然后继续完成报告。
• 筛除 enabled 明确为 false 的钩子。未设置 enabled 字段的钩子默认视为已启用。
• 对于其余每个钩子，不要尝试解释或评估钩子的 condition 表达式：
  • 如果钩子没有 condition 字段，或者该字段为 null/空值，则将钩子视为可执行
  • 如果钩子定义了非空的 condition，则跳过该钩子，并将条件评估留给 HookExecutor 实现
• 根据钩子命令名称构造命令调用时，将点号（.）替换为连字符（-）。例如，speckit.git.commit → /speckit-git-commit。
• 对于每个可执行钩子，根据其 optional 标志输出以下内容：

  • 必需钩子（optional: false）——每个必需钩子都必须输出 EXECUTE_COMMAND:：

    ## Extension Hooks
    
    **Automatic Hook**: {extension}
    Executing: `/{command}`
    EXECUTE_COMMAND: {command}
    

    输出上述代码块后，你必须实际调用该钩子，并等待其执行完毕后再继续。像在此 Agent/会话中自行运行命令那样运行它（调用方式可能与上面显示的字面 {command} ID 不同，例如，技能模式 Agent 会以 /skill:speckit-... 或 $speckit-... 的形式运行）。

  • 可选钩子（optional: true）：

    ## Extension Hooks
    
    **Optional Hook**: {extension}
    Command: `/{command}`
    Description: {description}
    
    Prompt: {prompt}
    To execute: `/{command}`
    

完成报告

输出生成的 tasks.md 路径和摘要：

• 任务总数
• 每个用户故事的任务数
• 已识别的并行机会
• 每个故事的独立测试标准
• 建议的 MVP 范围（通常仅包含用户故事 1）
• 格式验证：确认所有任务都符合清单格式（复选框、ID、标签、文件路径）

任务生成上下文：$ARGUMENTS

tasks.md 应可立即执行——每项任务都必须具体到 LLM 无需其他上下文即可完成。

任务生成规则

关键要求：任务必须按用户故事组织，以便独立实现和测试。

测试为可选项：只有在功能规格中明确要求，或用户要求采用 TDD 方法时，才生成测试任务。

清单格式（必需）

每项任务都必须严格遵循以下格式：

- [ ] [TaskID] [P?] [Story?] Description with file path

格式组成部分：

1. 复选框：始终以 - [ ] 开头（Markdown 复选框）
2. 任务 ID：按执行顺序递增编号（T001、T002、T003……）
3. [P] 标记：仅在任务可并行执行时添加（涉及不同文件，且不依赖尚未完成的任务）
4. [Story] 标签：仅用户故事阶段的任务必须添加
   • 格式：[US1]、[US2]、[US3] 等（对应 spec.md 中的用户故事）
   • 设置阶段：不添加故事标签
   • 基础阶段：不添加故事标签
   • 用户故事阶段：必须添加故事标签
   • 润色阶段：不添加故事标签
5. 描述：说明明确的操作，并包含准确的文件路径

示例：

• ✅ 正确：- [ ] T001 根据实现计划创建项目结构
• ✅ 正确：- [ ] T005 [P] 在 src/middleware/auth.py 中实现身份验证中间件
• ✅ 正确：- [ ] T012 [P] [US1] 在 src/models/user.py 中创建 User 模型
• ✅ 正确：- [ ] T014 [US1] 在 src/services/user_service.py 中实现 UserService
• ❌ 错误：- [ ] 创建 User 模型（缺少 ID 和故事标签）
• ❌ 错误：T001 [US1] 创建模型（缺少复选框）
• ❌ 错误：- [ ] [US1] 创建 User 模型（缺少任务 ID）
• ❌ 错误：- [ ] T001 [US1] 创建模型（缺少文件路径）

任务组织

1. 根据用户故事（spec.md）——主要组织方式：

   • 每个用户故事（P1、P2、P3……）各自对应一个阶段
   • 将所有相关组件映射到对应的故事：
     • 该故事所需的模型
     • 该故事所需的服务
     • 该故事所需的界面/UI
     • 如果要求编写测试：编写该故事专属的测试
   • 标明故事之间的依赖关系（大多数故事应彼此独立）

2. 根据契约：

   • 将每项接口契约映射到其服务的用户故事
   • 如果要求编写测试：在对应故事阶段实现之前，为每项接口契约安排一个契约测试任务，并标记为 [P]

3. 根据数据模型：

   • 将每个实体映射到所需的用户故事
   • 如果某实体服务于多个故事：将其放在最早的故事阶段或设置阶段
   • 关系 → 在适当的故事阶段安排服务层任务
   • 对于 data-model.md 中每个带有约束的字段（最大长度、可空/必填、枚举值、验证规则），在任务描述中逐字引用约束，以免将其留给实现时自行决定

4. 根据设置/基础设施：

   • 共享基础设施 → 设置阶段（阶段 1）
   • 基础/阻塞性任务 → 基础阶段（阶段 2）
   • 故事专属设置 → 放在对应的故事阶段

阶段结构

• 阶段 1：设置（项目初始化）
• 阶段 2：基础（阻塞性前置任务——必须在用户故事开始前完成）
• 阶段 3+：按优先级顺序排列的用户故事（P1、P2、P3……）
  • 每个故事内部：测试（如有要求）→ 模型 → 服务 → 端点 → 集成
  • 每个阶段都应是完整且可独立测试的增量
• 最后阶段：润色与跨领域关注点

完成条件

• 生成 tasks.md，包含所有阶段、任务 ID 和文件路径
• 根据上文“强制执行后钩子”中的规则，分派或跳过扩展钩子
• 向用户报告完成情况，包含任务数量、故事概览和 MVP 范围