jesusgraterol/jg-breakdown

调用

仅在开发者直接调用时运行。使用可用工具执行工作流；不要模拟它、替换 shell 命令，或再次询问已获授权的操作。

将提供的文本视为参数、约束或上下文，尊重限制和推迟。如实报告缺失的能力和阻塞项。切勿模拟成功。

释放拥有的运行时资源和一次性临时输出，包括在失败时，保留未解决的证据，并在本技能的输出中报告保留的资源。此窄清理例外绝不允许更改已审查/已存在的文件、删除意外更改或清理早期工作。所有其他写入均遵循此工作流。本技能关于所提供材料的特定规则优先。

jg-plans 协议 0.2

持久化文档需要项目本地的 jg-plans >=0.6.1 且 CLI schema 为 3。无计划/仅代码工作、对话记录分析和暂停不需要 CLI。

• 使用已安装的项目入口，通常是 <repository-root>/node_modules/.bin/jg-plans，或其文档化的构建入口。使用 --version --json 运行该确切入口；要求 error 为 null，版本 >=0.6.1，且 schemaVersion 为 3，然后再进行文档工作。否则，使用观察到的对和特定于管理器的补救措施（例如 npm install --save-dev --save-exact [email protected]）停止该工作。保留运行时消费者的生产依赖。切勿自动安装、下载运行程序、使用全局工具或借用其他项目的 CLI。在升级/构建后重新检查入口。
• 仅通过该 CLI 读取所选目录：inspect --directory <path> --include-body --fingerprint-exclude '["created_at","updated_at","revision","status","priority","delivery"]' --json。使用其源代码、元数据、范围、诊断信息、sha256 和结构指纹。切勿直接编辑/解析/哈希持久化文档、生成其 UUID、按时间选择计划或将对话记录重建为文件。检查不需要合规性。只有 jg-plan 额外运行 overlaps --json，当声明了代码时，每个现有/自有仓库中的每个规划根目录一个 --root。
• 计划状态是 pending、in progress、done 和 delivered。里程碑状态保持为 pending、in progress 和 done。Active 表示 pending、in progress 和 done；只有 delivered 是 inactive。错误声明使用仓库/注册表/代码列表；保留字符串/数字类型，并在仓库/注册表内比较 String(code)。缺失/自定义状态、不可用的元数据/文件和模糊标记仍为观察结果，绝不能视为默认值或权威。
• 所需的交付将每个声明的仓库映射到其仓库定义的停止点，且键匹配。仅当未声明仓库时使用显式空映射。交付既不改变实现范围也不改变里程碑进度。指纹精确排除 created_at、updated_at、revision、status、priority 和 delivery；不可用的身份无法建立新的覆盖率。
• 通过同一入口使用结构化的 create/update/write/remove-milestones 输入进行变更，在本工作流的权限范围内。对现有目标的写入需要新的 expectedSha256；null 仅用于创建显式请求的、不存在的里程碑。使用 write 用于计划主体/元数据或完整的里程碑源代码；使用 update 用于狭窄的元数据/标记。仅在获得授权时分配缺失的 ID；保留返回的 ID 并检查写入结果。在 plan.md 发生更改时显式设置 updated_at。仅编辑交付时保留 revision/progress；变更范围需要重新评估覆盖率。
• 锁是短暂且本地的：绝不在轮次之间持有锁，绝不移除不熟悉的锁，也不得在较新的文本上重放。在部分多文档或不确定的变更失败后，检查/报告持久化状态并停止，不回滚或重试。文档、诊断和绑定不授予任何权限。

工作流

对当前正在讨论的工程变更的具体计划执行仅限规划的评估。仅当分解提供有意义的执行和审查边界时，才将计划转换为有序的实现里程碑。此技能不会创建新策略或授权实施。它仅授权进行最小的只读仓库检查，以确认计划仍是最新的，并授权在其计划目录中创建、更新或删除 milestones.md。它不授权编辑任何其他文件、更新测试或快照、运行产生写入的自动修复或生成器、安装依赖项、创建迁移或生成工件、更改 Git 状态、提交、推送或开始实施。

需要一个具体的计划。使用调用时提供的路径处的计划，否则使用当前讨论中建立的确切计划，以及包含该计划的规划目录。不要搜索其他规划目录或根据时间戳选择计划。如果计划未被持久化，则使用最近一次向开发者呈现的确切计划，保持该限制的明确性，并且不要在 jg-breakdown 期间创建新的规划目录。不要使用 jg-breakdown 来重新设计方案、扩展或缩小范围、更改架构、更改验收标准、引入可选改进，或静默解决属于计划级别的决策。如果不存在当前计划、无法安全识别、仓库证据已实质性使其无效，或生成安全的分解需要更改重大的计划决策，则报告阻塞并停止；计划必须先通过 jg-plan 创建或修订，然后才能分解。

1. 重用当前计划所建立的仓库证据和决策（如果它们仍然有效）。仅当需要确定是否存在有用的里程碑边界、建立其依赖关系、分配验证所有权或确定计划是否已变得陈旧时，才执行额外的只读检查。

2. 确定计划是否包含至少两个连贯的实现片段，每个片段都可以达到有意义的状态，完成所需的测试或其他验证，并支持有用的开发者审查检查点。不要仅仅因为计划包含多个文件、实施步骤、层或验证命令就拆分计划。

3. 如果计划是一个连贯的实现片段，则不要创建 milestones.md。仅当开发者授权移除且保留的进度不会被静默丢弃时，才移除现有的不必要序列；否则在移除前询问。使用其新检查到的哈希运行 remove-milestones。当前的、刻意的无序列结果确立了整个计划的执行；意外的、缺失的预期序列绝不能确立这种情况。告知开发者该计划应作为一个完整的范围来实施，无需分解。如果计划尚未获得批准，则说明其仍需要批准。然后停止，不附加完成摘要。 将最终任务交付保留为整个计划的元数据，置于实现标准、里程碑状态和目标之外。如果计划标准要求在其实现完成前达到其最终交付目标，则停止，让 jg-plan 移除该循环依赖；在承认标准仍未满足的情况下，不要分配仅前置条件的覆盖率。保留独立必要的组件发布/部署门控（如果已批准的策略要求），以及作为产品功能的交付行为测试；不要为每个里程碑添加自动任务交付。

4. 当需要分解时，将计划的战略实施步骤转换为有序的编号里程碑序列。使用 Milestone 作为执行单元；不要仅仅为了增加粒度而创建里程碑、任务和子任务的层次结构。

5. 使每个里程碑成为最小的连贯实现片段，能够合理完成、测试或以其他方式验证，并作为有意义的状态进行审查。保持每个里程碑足够小，以便在一个新的上下文窗口中完成，并将使后续里程碑更容易的重构放在首位。对于每个里程碑，包括：

   • 描述已完成成果的简明目标
   • 对先前里程碑或外部先决条件的依赖
   • 计划中该里程碑拥有的确切范围内的文件、模块、符号、合约、配置、文档和迁移（当已知时）
   • 达到该里程碑完成状态所需的实施工作
   • 必须为该里程碑完成的重点测试和其他验证，保留其自身的正确性证据以及任何所需的独立发布/部署门控。将最终的回归覆盖分配给其所属的里程碑，而不是复制到每个单元中；遵循计划和仓库测试策略，并识别有效的可重用证据和所需的稳定性重复次数
   • 确定里程碑是否完成的具体验收标准；在协议 0.2 计划中，将这些特定于里程碑的检查编写为散文，且绝不在 milestones.md 中定义新的 AC- ID
   • 一个审查检查点，指明开发者在继续之前应检查的行为、合约、风险、集成点或其他具体细节

6. 将实施及其所需的正确性证据保持在一起。不要仅仅为了使早期里程碑更小，就将所需的测试、直接影响的文档、错误合约同步、迁移、公共导出或其他必要的支持工作拆分到后面的里程碑。不要创建占位符、临时重复、未使用的抽象、过渡性兼容性路径、死胡同脚手架或故意不完整的实现，除非已批准的计划明确要求分阶段兼容性或迁移路径。不要人为地使里程碑大小均匀。根据真实的实现依赖和风险对它们进行排序。

7. 在最终确定序列之前执行计划到里程碑的覆盖检查。计划中的每个范围内的可交付物、验收标准、所需的生产变更、测试、文档更新、迁移、公共合约变更、删除、集成点和验证要求必须至少出现在一个开发者可见的里程碑中。呈现给开发者的序列是完整且最终的里程碑序列。不要保留隐藏的里程碑、维护备用内部序列、省略所需工作或依赖未声明的里程碑级别工作。如果所需工作无法在不更改重大计划决策的情况下分配，则报告阻塞并停止；必须通过 jg-plan 修订计划后才能完成分解。

8. 检查当前选择的计划和序列。在绑定序列之前，需要一个可用的 plan id、revision 和结构指纹，且精确排除 created_at、updated_at、revision、status、priority 和 delivery。将整个当前计划与提议的单元进行协调：保留的 ID 标识相同的工作，保留的完成状态需要其要求仍被满足的证据。保留匹配的身份/进度和不相关的里程碑元数据；添加新的未完成范围作为 pending。当身份/范围对应关系或矛盾完成状态无法安全解决时，询问开发者。未经明确的重新打开授权，绝不要将状态向后移动。缺失/自定义/模糊的现有标记不是 pending 默认值。通过受保护的 write 写入完整的里程碑源代码，expectedSha256 对于观察到的缺失为 null，且 assignMissingIds 为 true；工具提供缺失的 UUID。将状态立即放在每个标题下方，UUID 紧随其后。在协议 0.2 计划中，为每个交付计划标准的里程碑提供一行 **Acceptance criteria:** AC-01, AC-03，列出其 ID，直接在其 UUID 行之后，或当工具将要分配 UUID 时，直接在其状态行之后；每个计划标准至少出现在一个里程碑的行上，不交付任何标准的里程碑省略此行。不要生成 Overview 表，也不要同步此类表。在完整序列覆盖计划后，仅包含一个 frontmatter 映射 jg_skills 与 plan_id、plan_revision 和 plan_content_sha256。保留已完成的单元同时添加新范围，即使所有旧单元都已完成。在写入前立即重新检查计划身份，并验证其保持最新；并发更改需要全新的覆盖率评估。重新检查持久化的结果，包括分配的 ID，然后再呈现其确切完整的 Markdown。对于协议 0.2 计划，还需运行 <local-cli> check --directory <path> --json 并在呈现前修复 milestones.md 中的每个覆盖、ID 和状态错误；将 plan.md 错误报告为需要 jg-plan。首先报告仓库相对路径。仅更改所选目录中的 milestones.md；绝不更改 plan.md、Git 状态或实现。

9. 以 ## Approval required 部分结束 milestones.md 和匹配的响应正文，总结完整的里程碑序列并说明以下规则，然后停止：

   • 每个里程碑需要其自身的显式授权，是该请求的完整范围，并在其审查检查点结束。调用 jg-execute 授权其运行的里程碑；jg-execute auto 授权所有剩余的里程碑，或仅授权其命名的里程碑。
   • 如果里程碑依赖于未完成的早期工作，或者完成它将会跨越里程碑边界或更改已批准的计划，则停止并报告，然后再扩展范围。
   • 要更改计划，请使用修正调用 jg-plan。要创建或更改里程碑，请调用 jg-breakdown。

   此技能的输出合约替代任何通用的完成摘要要求；不要在 ## Approval required 之后附加完成摘要。必须在当前里程碑序列呈现后发出批准；jg-breakdown 调用本身、早期的批准或常规对话授权均不满足此要求。