linear-implement

Linear 实现

将仓库根目录用作工作流来源。阅读并遵循：

• agents/implementer.md
• docs/implementer.md
• docs/agent-required-passes.md
• docs/superpowers-linear-persistence.md
• templates/linear-status-comment.md
• templates/linear-dashboard-comment.md
• schemas/linear-ai.status.v1.schema.yaml
• schemas/linear-ai.dashboard.v1.schema.yaml

从最新的有效标记计划评论开始。不要臆造缺失的产品行为。如果遇到阻塞，请在带标记的状态评论中汇总问题，并应用或发出正确的 Linear 修改。

认领锁

遵循 docs/workflow.md 中的认领锁规则。开始时重新读取议题；如果议题已带有 in-use，且本次运行并非在恢复自身认领，则停止并报告该议题已被认领，不做任何更改。否则，在认领议题时添加 in-use 标签（同时应用 llm-active）。本次运行停止处理该议题时，应移除 in-use：交接为待审核、受阻、放弃或失败时均须移除。in-use 不属于 llm-* 命名空间，因此批量移除 llm-* 标签时不会将其移除；请明确释放它。

认领时，还需将 linear-ai:claim 区块写入议题描述（templates/linear-claim-block.md），其中 claimed_by: linear-implement，并填写 ISO 8601 格式的 claimed_at。释放认领时，移除该认领区块，使描述与标签保持一致。

实现前检查关卡

更改任何代码之前，在认领议题后运行一次此检查关卡：

1. 再次确认没有未解决的问题。重新阅读最新的就绪计划、其中的 open_questions、accepted_unknowns 和 do_not_assume，以及相关代码。如果任何重要问题尚未得到答复且未被明确接受，或者你在阅读代码时发现新的歧义，请停止并使用 llm-blocked 状态进行阻塞，同时汇总问题，不要猜测或开始实现。存在重要未解决问题时，不得开始实现。
2. 如果没有未解决的问题，将就绪计划拆分为彼此独立的并行工作流——按仓库、模块、检查清单项、测试范围或验证工作流拆分，使处理互不重叠文件的工作流可以同时进行。根据并行执行规则，在隔离的工作树中将每个工作流交给各自的子 Agent；仅对必须共享可变文件的工作流保留顺序执行。

自动模式

存在有效的就绪计划后，以自动模式运行实现。在不再次征求许可的情况下，继续执行安全且可逆的本地检查、编辑、测试和验证步骤。这包括读取仓库上下文、创建仓库本地 TDD 计划、编辑就绪计划中指定或暗示的文件、更新测试、运行有针对性的验证、更新 Linear 面板／状态证据，以及针对失败的检查反复迭代。

仅当下一步具有破坏性、不可逆、需要凭据、会影响外部生产环境、会实质性改变范围、缺少必要授权，或确实存在可能导致大量返工的歧义时，才提问或阻塞。请在带标记的状态评论中汇总阻塞问题，不要因常规实现选择而中断。

必需的权限上下文

开始直接实施前，请确认所需的实施者权限上下文已启用。会话必须具备目标仓库的工作区写入权限、运行仓库包管理器和验证命令的权限、用于修改仪表板/状态的 Linear MCP 读写工具、在涉及分支或 PR 工作时使用的 Git/GitHub 工具，以及就绪计划要求的任何项目 MCP 工具。

不要在逐条提示授权模式下开始常规实施。应先建立或继承所需的实施者权限上下文，以便无需反复确认即可开展已批准的安全、可逆工作。如果无法建立该上下文，则将工作范围缩小到安全的只读检查，或发布/输出包含缺失权限的受阻状态，而不是在常规步骤中反复询问。

在 Superpowers 任务列表同步到 Linear issue 描述仪表板，或输出 REQUIRED_LINEAR_MUTATIONS 之前，不得进行任何实施或代码更改。

在 issue 描述中维护一个符合 linear-ai.dashboard.v1 架构的仪表板区块。将 Superpowers 任务列表同步到该仪表板，使用 CLI 风格的状态符号、稳定的就绪计划任务 ID，并在每项顶层任务状态变更后更新 last_checked 修复证据。将任务标记为已完成前，检查实际代码/工作树状态。仅在无法写入描述时，才将仪表板评论作为备用方案。

并行执行

针对互相独立的实施工作，充分使用子 Agent。如果各工作通道不需要修改相同的文件，则按仓库、模块、检查清单项、测试范围、审查通道或验证通道拆分就绪计划。

实施必须始终在隔离的 issue 工作树 <repo>/.worktrees/<issue-id>-<optional suffix> 中进行，除非能确认当前已处于正确的 issue 工作树中。绝不直接在分支工作树中实施，也绝不直接在 main 或 master 上实施。将就绪计划或 Linear issue 中的分支名称或 Git 引用视为关联到 issue 工作树的 Git 底层引用，而非主要工作区。

并行执行会修改代码的子 Agent 时，优先使用 Git worktree 隔离。每个会修改代码的通道都应使用自己的临时通道工作树或 Git 引用，运行自己的针对性验证，并报告变更文件、运行的测试、剩余风险和仪表板任务 ID。不得让多个会修改代码的子 Agent 共用同一工作树。

派遣子 Agent 前，请确认它们具备相应通道所需的工具和权限：仓库读写权限、包管理器、测试命令；如有需要，还包括 Linear MCP 读写工具、涉及 PR 工作时使用的 Git/GitHub 工具，以及必需的项目 MCP 工具。如果不具备这些工具和权限，则将通道范围缩小为只读工作，或在主会话中执行。

只有在审查差异、解决冲突、更新仪表板任务列表，并在 issue 工作树中重新运行相关验证之后，才能合并子 Agent 的工作。合并并验证后，清理临时通道工作树。临时通道工作树应与持久的 issue 工作树分开。如果有意保留任何临时通道工作树，请在状态评论中说明其路径、分支、负责人和原因。

实现审查循环

当实现看起来已完成且本地验证通过后，在提出目标问题和应用 llm-review 之前，运行 docs/agent-required-passes.md 中的强制实现审查循环。并行派发独立的审查子 Agent——始终包括通用审查、重构／代码异味、Bug 排查、安全性和规范／范围核验；此外，还应包括运行环境提供的任何专用语言／领域审查者。然后修复或说明每项发现的理由，在标记的状态评论中记录每项说明，并重复审查轮次，直到收敛。除非问题明确规定了不同的上限，否则最多进行五轮审查。每轮审查后，发布或输出一份轮次摘要，包含轮次编号、执行的审查者／审查视角、按严重程度分类的发现、已修复的发现、已说明理由的发现、已延期或受阻的发现、重新运行的验证，以及循环是继续、已收敛，还是因达到上限而受阻。如果达到上限时仍未收敛，则发布受阻状态。然后通过信心和测试缺口自检关卡。只有循环收敛且两个自检关卡均通过，实现才算完成。

提交与目标策略

实现和验证完成后，除非问题本身明确要求或规定了不同的交接方式，否则使用默认集成路径：将问题工作树变基到本地 main 分支，压缩为尽可能少且能保留可审查行为和回滚边界的提交，然后集成到本地 main 分支。

只有代码进入 main 分支，工单才算完成。打开的 PR 不足以视为工单已完成。除非问题明确要求将其作为最终路径，否则功能分支和 PR 都只是审查交接状态。

在推送、合并、创建 PR、将 PR 标记为可审查、应用 llm-review 或发布可供审查的交接之前，确认目标：

• 完成工作时，集成到默认分支（main 或 master）
• 仅当问题明确要求此交接方式时，才创建或更新不含 PR 的功能分支
• 仅当问题明确要求此交接方式或要求在集成到 main 之前进行人工审查时，才创建或更新包含 PR 的功能分支

在 final_destination 中将答案记录为 main、master、feature_branch 或 feature_branch_pr。如果答案缺失、含糊不清或仍为 undecided，则停止并标记为 llm-blocked 或输出 REQUIRED_LINEAR_MUTATIONS；不要根据计划、分支名称、现有问题工作树或现有草稿 PR 推断答案。

保留尽可能少的压缩提交：仅按可审查的行为或风险边界拆分，不要为每个微小编辑单独提交，也不要把不相关的内容合并成一个批量提交。

使用 Conventional Commit 风格的 semver 语法，并在每个提交主题中包含 Linear 问题 ID，例如：

feat(HCL-123): add dashboard persistence
fix(HCL-123): repair status extraction
test(HCL-123): cover dashboard validation

Linear 魔法词关联

在结尾处使用魔法词并附上问题 ID，将工作关联到 Linear 问题，以便 Linear 自动关联并推进状态（推送/打开时设为 In Progress；更改进入默认分支时设为 Done）：

• 目标为带 PR 的功能分支：在 PR 描述中写入结尾魔法词和问题 ID，例如 Fixes HCL-123（多个问题：Fixes HCL-123, HCL-124）。魔法词仅在 PR 标题或描述中生效，在 PR 评论中无效。
• 目标为直接合并到 main（main/master）：除上述 Conventional Commit 主题行外，还要在提交消息正文中添加一行 Fixes HCL-123。没有 PR 的功能分支仅在问题明确要求时作为交接例外。
• 结尾魔法词：close/closes/closed/closing、fix/fixes/fixed/fixing、resolve/resolves/resolved/resolving、complete/completes/completed/completing、implements/implemented/implementing。优先使用 Fixes。为便于阅读和基于提交证据完成收尾，Conventional Commit 主题行保留 (HCL-123) 范围标记；魔法词则负责触发 Linear 自动化。
• 由于结尾魔法词会在合并时将问题移至 Done，linear-close 会执行验证并完成收尾：即使问题已处于 Done，也会继续验证证据、更新仪表板、发布收尾评论，并移除 llm-* 和 in-use。

在状态评论中报告最终提交列表和所选目标。

在交接至可供审查状态之前，确认已明确选择最终目标、临时通道工作树已清理，并明确列出问题工作树是已清理还是有意保留。

Linear MCP 契约

在可用时使用以下 Linear MCP 工具：

• get_issue - 读取当前问题、标签、状态和分支元数据。
• list_comments - 操作前查找最新的已标记计划评论和状态评论。
• save_comment - 发布带标记的实现状态、问题、阻塞项和可供审查的证据。
• save_issue - 应用 llm-active、llm-blocked 或 llm-review，移除其他 llm-* 标签，开始时添加 in-use 声明、停止时移除该声明，更新问题描述仪表板，并在可写时更新状态。

如果问题是子问题，请在同一最终处理流程中应用 docs/workflow.md 中的父问题和子问题规则：处于 llm-active 时，将父问题移至 llm-active 和 In Progress；处于 llm-blocked 时，按该规则汇总父问题状态。绝不要对父问题声明 in-use。

使用以下方式验证状态评论和问题描述仪表板：

scripts/validate_marked_comments.ts --description <issue-description-file> <status-comment-file>

应用 llm-review 或声明已准备好供审查之前，运行严格交接检查：

scripts/verify_handoff.ts --issue-id <ISSUE-ID> --status <status-comment-file> --description <issue-description-file>

如果有 Linear 元数据快照可用，使用以下方式验证标签：

scripts/validate_marked_comments.ts --metadata <metadata.json> <status-comment-file>

使用 Agent 可用的本地 JavaScript 包管理器或运行时：Bun 可直接运行 .ts 脚本；Node/npm/pnpm/yarn 环境应通过 tsx 等 TypeScript 运行器运行这些脚本。

如果 Linear MCP 写入工具不可用，不要声称已更新标签、状态或评论。输出 REQUIRED_LINEAR_MUTATIONS，其中包含准确的带标记状态评论以及标签/状态变更。

阶段完成交接

当实现完成一项任务、更新阻塞事项、完成验证或达到可供审核的状态时，请报告变更内容、验证证据、当前 Linear 标签/状态、PR 或补丁链接（如有），以及建议的下一步。对于阻塞、已放弃或可供审核的交接，或者没有安全且明确的任务剩余时，请询问是否还有其他内容需要补充。对于常规已完成任务，不要询问是否继续；只要还有工作，且下一步安全明确，就继续处理下一个未勾选任务、验证或审核交接。

在阻塞、已放弃或可供审核的交接中，用户回答“没有”后，询问用户是否要继续执行建议的下一项技能。明确说出建议的下一项技能，并等待用户确认；不要自动运行。

使用以下回复格式：

• 当前阶段
• 变更内容
• 证据
• 缺少的证据
• 尚未解决的阻塞事项
• 建议的下一步
• 建议的下一项技能
• 问题：继续之前还有其他内容需要补充吗？
• 问题：要继续执行建议的下一项技能吗？

当实现已通过验证、适用时已提供 PR 链接，且问题已有状态评论（其中 implementation_status 设置为 review_ready、blocked、active 或 abandoned）时，停止。