用途:把设计文档中的用户故事同步到 GitHub,使设计文档定义目标范围,GitHub Issue 跟踪交付进度。
前提:需先阅读仓库说明和完整设计文档,并要求提供精确的设计路径。常规同步要求文档状态为 Status: Revised,即最近一次独立评审无阻塞且机械校验通过;用户可显式覆盖语义评审风险,但交付模式的机械校验仍须通过。使用已认证的 GitHub CLI 和仓库策略。
规范身份:通过仓库相对设计路径加故事 ID 识别受管 Issue,使用标记 <!-- feature-delivery:design=<REPO-RELATIVE-DESIGN-PATH> --> 和 <!-- feature-delivery:story=<STORY-ID> -->。以交付模式运行 scripts/story_contract.py 校验状态、故事结构、稳定 ID 和依赖,其规范化故事源作为受管 Issue 契约。每个故事须包含影响其实现的全部共享架构、数据、安全、迁移、兼容或发布要求;要求变更时更新所有受影响故事,故事正文变化会导致已完成工作重新打开。搜索开启和关闭的 Issue 以匹配精确标记对,仅在设计路径、内容和历史明确无歧义时采用旧候选,遇到重复候选应停止。
同步:运行 python3 /absolute/path/to/scripts/story_contract.py <design-doc> --repo-root <repository-root> --mode delivery --include-source > <temporary-manifest.json>。确定仓库、默认分支、里程碑、标签和稳定设计 URL,先构建完整当前 Issue 映射再改动。创建或复用里程碑,未经授权不重开已关闭里程碑。创建所有缺失的故事 Issue,使用内置渲染器确保正文含精确规范化故事源和规范依赖链接。当受管故事正文、标题、依赖、标签或里程碑不同时原地更新现有 Issue。故事契约变化时重开已完成 Issue,未变化则保持关闭。重新读取每个规范 Issue 并校验标记、受管正文、依赖、标签、里程碑和状态。不要静默关闭从设计中移除的故事,应报告其现有 Issue 并询问删除、推迟或恢复,将决定持久化到 Issue 以免后续重复询问。
受管 Issue 正文包含标记、## Managed Story Contract 下的精确规范化故事源、## Canonical Dependencies 下的规范编号 Issue 引用或 None,以及 ## Design Doc 下的仓库 blob URL 链接。清单哈希可辅助比较内容,但消费者应依赖规范 Issue 正文和当前 GitHub 状态。
结果需报告:设计、里程碑、创建的 Issue、更新的 Issue、重开的已完成 Issue、未变化的已完成 Issue、需决策的已移除故事 Issue、阻塞项。
脚本:scripts/create_issue.sh、scripts/create_milestone.sh、scripts/story_contract.py、scripts/render_issue_body.py。脚本相对本技能解析,多行正文使用临时文件,并保留无关的仓库改动。
限制:依赖 GitHub CLI 认证与仓库策略;常规同步要求 Status: Revised 且机械校验通过;移除故事需人工决策;资料未提供具体收费、平台或效果信息。