implement-task-linear

根据 Linear 任务实现

在同一个分支和同一个 PR 中实现所有提供的 Linear 任务。提供的任务是必需输入，也是合并后的范围边界；每个任务的来源链和代码仓库上下文会进一步明确实现方式，但不得擅自增加工作。发布 PR 前，必须完成所有提供的任务；任何目标上的阻碍都会阻止合并变更的发布。

将此技能用作 $complete-work 的 Linear 专用封装。在规划交付前，先阅读该技能；它负责分支设置、增量提交、验证、推送、通过 create-pr 创建 PR，以及通过 finish-pr 推进评审和 CI 收敛。如果该技能或所需依赖不可用，请报告缺失的前置条件，并在开始实现前解决，而不是改用不完整的工作流。调用此技能即表示授权执行完整工作流；合并、部署和发布留待用户另行请求。

在起草或修改任何任务前，先阅读并遵循 $linear-ticket。向其提供每个目标经过核实的团队／项目边界，以及本工作流授予的范围授权；它负责任务内容、编号、元数据、估算、原生写入和回读验证。

采取行动前，先用几条简短、明确的要点说明计划如何发现和交付。步骤 1–3 仅用于只读发现和澄清：利用这些步骤制定充分知情的计划，然后再创建分支、修改代码仓库或修改 Linear。

1. 确定目标和 Linear 边界

接受一个或多个明确无误的 Linear 任务标识符或 URL。若用户未提供，请向其索取；解析所有提供的引用，并对指向同一任务的引用去重。为每个任务维护目标清单，记录其标识符、URL、验收标准、团队／项目 ID、工作流状态 ID、估算、实现和验证覆盖情况，以及保存状态。在以下步骤中，对清单内的每个任务执行针对该目标的发现和协调。

获取每个目标的完整描述、状态、标签、团队、项目、关联标识符、评论以及包含需求的附件。记录确切的团队 ID 和项目 ID。若目标没有项目，请要求用户为其指定项目，或授权将其分配到一个具名项目，然后再检查周边的 Linear 工作。

明确提供的目标可能属于不同团队或项目；请分别保留各自的边界。对于每个目标，在读取或修改任何相关 Linear 任务时应用该目标自身的边界：

• 使用记录的两个 ID 进行查询，然后核实每条结果都包含这两个 ID；
• 通过限定范围的查询发现父任务、子任务、阻塞项、重复项和相关任务，不要直接获取未经核实的标识符；
• 将跨范围关联视为不可用上下文，只报告其存在；
• 对 linear-ticket 传入记录的两个 ID，以授权写入。

按 ID 确定每个目标团队的相关工作流状态，尤其是 In Progress、In Review、Backlog 以及任何阻塞状态。遇到歧义时应报告，不要猜测。

在此只读阶段，使用 linear-ticket 发现估算。每次获准更新目标任务或相关任务（包括状态更改）时，都要附上评估后的估算及其理由。

完成此步骤后，每个提供的目标都应已记录其验收标准、团队／项目 ID，以及可用的工作流状态。

2. 沿溯源链追踪

确定仓库根目录，并在开展其他仓库工作前阅读所有适用的 AGENTS.md。

然后按以下顺序解析上下文。除非目标明确依赖某项来源，否则每项来源均为可选：

1. 源头规格 — 跟进目标中的每个明确 Source 路径或 URL、规格链接、设计链接或承载需求的附件。当 to-linear 将规格表示为原生父级时，通过限定团队和项目范围的查询找到该父级，验证两个 ID，然后阅读其完整描述和评论。如果未记录溯源信息，请在 docs/、specs/ 和 .scratch/ 中搜索与目标标题、来源名称或功能标识明确匹配的单一结果；如果存在多个可能的匹配项，请先询问。检查相关范围内的父级、阻塞项、里程碑或周期中的关联项，以及重叠的问题（若它们有助于明确意图、依赖关系或偏差）。
2. 计划 — 如果根目录下存在 PLAN.md，请完整阅读。根据它了解更大的目标、排序、依赖关系以及目标在计划中的位置。
3. 领域上下文 — 如果根目录下存在 CONTEXT.md，请完整阅读。如果根目录下存在 CONTEXT-MAP.md，也请完整阅读，并遵循其中所有适用于目标的上下文条目。上下文文件定义项目用语和领域边界，而非实现范围。
4. 决策 — 阅读根目录 docs/adr/ 下适用的 ADR，以及任何特定上下文目录中的 docs/adr/。遵循所选规格、计划、上下文文件、ADR 和当前对话中的相关产物指针。
5. 仓库实际情况 — 检查涉及的代码、测试、文档、架构、迁移、生成的产物、配置和 git 状态。保留无关的用户更改。

前置技能可能已完成溯源链中的不同部分：

• grill-with-docs 可能会生成 CONTEXT.md、CONTEXT-MAP.md 和 ADR；
• to-spec 会在源头跟踪器问题中发布实现决策、商定的测试切入点和范围外边界；
• to-linear 会通过原生父级或 Source 引用将该来源关联到目标，并可能将持久约束复制到 Context 中。

缺少可选产物不会阻止实现。明确的指针必须得到处理：阅读它们，或说明无法获取的原因。

采用以下证据优先级：

• 提供的目标问题共同定义交付内容和验收标准；
• 源头规格和 PLAN.md 说明意图、排序和排除项，但不得扩大目标范围；
• 上下文文件和 ADR 限定用语、边界和持久决策；
• 仓库定义当前实现的实际情况。

指出重大冲突或过时证据。仅当冲突会改变预期行为、公共接口、兼容性或范围时才提出询问。

当每个目标的所有明确溯源指针都已解决或说明无法获取、所有适用的上下文产物都已阅读，并且每项目标要求都已归类为已实现、部分实现、缺失、相矛盾或受阻时，此步骤即告完成。

3. 明确并规划交付

开始实现前，用简短易懂的要点向用户概述：

• 具体交付成果及将发生变更的界面；
• 小步交付计划，以及每一步的验证方式，包括约定的公开测试切入点或最适用的现有测试切入点；
• 发现过程中确认的重要假设、权衡、上下文缺口或偏差；
• 需要用户提供的任何信息，随后说明计划的提交、PR，以及通过 complete-work 完成 CI/审查的计划。

让概述便于快速浏览；简要列出参考过的资料，仅在需要解释决策时展开说明。创建分支或开始实现前，与用户解决有关需求、行为、范围、兼容性或公开接口的重要不确定事项。此类决策需要进一步询问时，使用 complete-work 的条件式 $grilling 访谈，并纳入用户已给出的答复。任务明确且可执行时，只需提供概述，无需重复暂停以征求批准。

将每个目标的每项验收标准和长期约束，都对应到实现变更或具体验证方式。将所提供目标之间的依赖关系和重叠要求作为一个整体交付来规划。确认所有工作可以在一个仓库和一个 PR 中交付；如果不行，须在实现前与用户解决冲突。只有经过验证，现有行为才能视为满足要求。如果选择测试切入点会创建或实质性更改公开接口，而上游资料尚未对此作出明确规定，则须与用户确认。

为这一整体交付准备简洁的审查上下文。将每个目标的验收标准覆盖情况、已确定的权衡和排除项纳入 complete-work 和 PR，并附上简短的来源链接和足够的说明，让 PR Agent 无需访问 Linear 也能判断意图。单独保留完整的目标台账；PR 简述应说明重要约束，但不要照搬所有发现记录。

当用户已收到概述、每项验收标准都有交付和验证路径，且所有重要问题均已得到答复时，本步骤即告完成。

4. 通过 complete-work 交付

针对整体范围调用一次 $complete-work，并纳入每个目标的完整需求、可用时的原始用户故事、验收标准、来源信息、长期约束、商定的计划、测试切入点及用户决策。遵循其完整工作流，包括 create-pr 的用户故事规则：要求提供简短、日常易懂的用户故事，确保没有技术背景的读者也能理解，并可根据需要调整原文措辞。Git 和 PR 流程应由 complete-work 处理。其分支设置应在上述只读发现与澄清之后进行；编辑前，须根据最新获取的基线重新核对计划，并与用户解决任何新出现的重要不确定事项。

整体工作的实现开始时，将每个目标都移至其团队的已解决 In Progress 状态，除非该目标已处于更后续状态，或用户要求保留原状态。开始时就处理所有目标，包括计划在后续切片中完成的目标。此操作及之后所有工单写入都须通过 linear-ticket 完成，然后在台账中记录经验证的结果或失败。

在 complete-work 中，按已验证的垂直切片实现，在约定的公开切入点针对可测试行为先写失败测试，再实现通过。纳入所需文档、架构、迁移、生成的制品和配置。在 PR 发布关卡之前，根据仓库规范、适用的 ADR、所提供每个目标的每项验收标准及来源规范约束，审查完整差异；修复发现的问题并重新运行受影响的检查。所需目标工作须包含在这一次变更中。

在创建 PR 时关联所有目标并更新审查状态

将所有目标标识符，以及为该任务提供依据且已由此 PR 全部完成的相关工单，一并传给 create-pr，以应用其标题前缀规则。还要要求 PR 描述以一行结尾，提及每个提供的目标，例如：

Fixes ENG-123, ENG-124, ENG-125, ENG-126, and ENG-127

使用台账中的实际标识符；如果只有一个目标，就使用单个标识符。现有的 GitHub–Linear 集成会使用这些结尾引用来关联 PR，并在 PR 合并时自动关闭工单；请勿更改该集成配置，并让工单保持开启状态，直到合并为止。

完整创建或复用 PR 后，立即读回已保存的标题和描述。验证标题符合 create-pr 的工单前缀规则，且结尾引用包含所有提供的目标。修正任何遗漏，然后为每个目标执行第 5 步中的 PR 评论和 In Review 状态转换，再继续执行 finish-pr。此时审查或 CI 可能仍在进行中；无需等待它们完成即可执行这些状态转换。

需要用户输入时进行协作

只要现有工具、访问权限和已确定的需求允许，就继续自主推进。当进度需要用户作出决定、提供凭据或权限、设置账户或满足其他前置条件时，请及时询问并说明：

• 目前已实现并验证的内容，并在有帮助时提供可检查的产物、截图或预览；
• 缺少的具体内容，以及它会阻碍哪些剩余行为或检查；
• 如何提供或获取该内容；如涉及设置或访问权限，请提供服务或账户的直接链接、相关设置位置和最低限度的操作步骤；
• 应在哪里配置，包括适用时的确切环境变量或密钥名称及目标环境；
• 用户完成后需要确认什么，以及之后将恢复哪些工作。

要求用户手动设置前，先检查可用的已认证工具和现有配置。请对照相关服务的文档核实当前设置说明，不要臆造账户操作路径。应通过适当的密钥存储或本地环境配置凭据，而不是在聊天中索要密钥值或将其提交到代码库。

例如，界面可能已可供检查，但实时数据仍因缺少 API 密钥而无法使用。请展示界面，指出尚未验证的集成，并提供服务链接和配置步骤。等待用户回复期间，继续开展不依赖该输入的工作；暂停依赖该输入的工作。收到输入后，验证前置条件并恢复工作。仅仅等待一段时间并不算作答。complete-work 的完整性门槛仍然适用：目标尚未完成时，不得以部分实现或模拟数据为由发布 PR。

5. 对账 Linear 并移交

按上述指示，在创建 PR 时运行此对账；complete-work 到达最终审计或停止条件后，再运行一次。重新获取每个目标和每个已变更的相关议题，然后再次确认每个议题的团队／项目边界。复用现有移交评论；如果证据有变化，就更新评论，而不要在最后一轮重复添加。

当所有提供目标的必需结果均已实现并验证，且共享 PR 已创建后，对每个目标：

1. 添加或更新简洁的目标评论，链接共享 PR，并将该目标的验收标准对应到实现和验证证据，其中包括当前 CI／评审状态，以及 finish-pr 报告的任何阻碍。
2. 通过 linear-ticket，仅当目标当前状态早于所属团队的已解析 In Review 状态时，才将目标移至该状态，然后在台账中记录已验证结果。

保留已完成、已取消、已归档、In Review 以及其他终态或进展更靠后的状态。如果任何目标的实现或必需验证受阻，则不要发布合并 PR；将已开始的目标保留为 In Progress，或在适用时使用已解析的受阻状态，并记录未满足的标准、证据和依赖项。区分实现就绪与 PR 评审或 CI 尚未完成的情况；只有满足 finish-pr 的完成定义时，才报告整个工作流已完成。合并后的完成状态转换交由已配置的 GitHub–Linear 自动化处理。

相关 Linear 工作

用户授权在相关目标记录的团队／项目边界内，进行有充分理由的最少相关议题变更，只要实现证据支持这些变更。

使用 linear-ticket 创建有充分理由的后续议题，并更新有证据支持的相关议题；传入来源目标及其边界。其重叠、标准覆盖、来源追溯、里程碑／编号、估算和验证规则均适用。此工作流授权对所有提供目标之外的议题进行最少的相关编辑和后续跟进；创建里程碑以及更改现有名称／标题仍需明确批准。必需的目标工作仍须纳入合并实现，未满足的前置条件仍是阻碍。已验证为完全覆盖的相关议题，可通过相同的工单流程从较早状态移至 In Review。

移交

报告：

• 每个提供目标的标识符、URL 和已验证的最终状态；
• 共享 PR URL、所有提供目标已验证的关闭引用，以及 finish-pr 的最终审计；或者说明阻碍 PR 创建或工作流完成的具体前置条件；
• 已实现的结果和变更涉及的部分；
• 验证命令及其结果；
• 验收标准覆盖情况；
• 使用的上下文来源及不可用的明确指针；
• 发现的重大偏差或冲突；
• 所有曾影响实现决策的已读取相关议题；
• 每个已创建或修改的议题及其原因、状态和 URL；
• 每个已创建或修改议题的已保存估算及简要依据、任何临时规模假设，或具体的禁用／错误结果；
• 阻碍、限制和后续工作。

明确说明是否没有变更任何相关 Linear 议题。