mcpField
O
openspec-to-beads

openspec-to-beads

github.com/lucastamoiosAgent 工作流565 次安装5 天前更新
代码仓库

关于 openspec-to-beads

将 OpenSpec 规划产物转为 Beads 问题的工作流技能，适用于从规格规划进入实施的团队。它会分析任务范围与依赖、发现潜在缺项，并建立关联的执行跟踪，而非机械地逐项映射。

主要功能

  1. 01分析 OpenSpec 计划与任务
  2. 02创建有优先级的 Beads 问题
  3. 03构建依赖链
  4. 04主动发现遗漏工作
  5. 05将任务关联到 Epic

适用场景

  1. 01将已批准的规格转为可执行问题
  2. 02发现缺失的测试或迁移回滚工作
  3. 03安排设置、实现及其依赖任务
  4. 04为基于 Beads 的执行准备变更

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/lucastamoios/celeiro --skill openspec-to-beads

安装后在 Claude Code 中输入/openspec-to-beads确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

data/
dependency-patterns.md
priority-rules.md
examples/
conversion-workflow.md
templates/
issue-creation.md

详细介绍

OpenSpec 到 Beads 桥接

你是一个工作流编排器，负责将规划产物（OpenSpec）转化为可执行的工作流（Beads），同时保持可追溯性并主动发现实现缺口。

核心理念

OpenSpec 定义要构建什么（不可变契约）。 Beads 跟踪执行状态（可变现实）。

你的工作是智能地弥合差距，而不是机械地转换。

此技能的触发时机

自动触发：

  • 用户运行 openspec apply <change>
  • 用户说“实现此规范”或“开始处理 X”
  • 用户批准提案并提到“准备好了”或“开始吧”

手动触发：

  • 用户明确要求“将规范转换为 beads”
  • 用户说“为此更改创建 issue”

以下情况不要触发：

  • 仅查看规范（openspec show）
  • 创建提案（规划阶段）
  • 审查或迭代规范

智能转换流程

1. 收集上下文（静默侦察）
# Verify prerequisites
openspec show <change-name> 2>&1
bd list --json 2>&1

阅读并理解：

  • openspec/changes/<change>/proposal.md → 我们为什么要做这件事
  • openspec/changes/<change>/tasks.md → 需要完成什么
  • openspec/changes/<change>/specs/*/spec.md → 验收标准
  • openspec/changes/<change>/design.md（如果存在）→ 架构设计方式
2. 关键分析（转换前先思考）

问问自己：

  1. 任务范围是否明确？ 如果范围太大，请指出
  2. 依赖关系是否清晰？ 数据库迁移应先于 API 端点
  3. 缺少了什么？ 测试？文档？部署？
  4. 可能出现什么问题？ 找出会发现更多工作的任务

如果发现问题，请在转换前告知用户

分析示例请参阅 examples/conversion-workflow.md。

3. 智能转换（并非一对一映射）

使用 templates/issue-creation.md 中的模板，智能地创建 issue。

优先级逻辑（来自 data/priority-rules.md）：

  • 基础设施/设置任务：p0（阻塞所有工作）
  • 核心业务逻辑：p1
  • 测试和文档：p1（质量不可妥协）
  • UI 润色：p2

类型检测（来自 data/priority-rules.md）：

  • “setup”“configure” → task
  • “implement”“add” → feature
  • “refactor”“improve” → task
  • “test”“document” → chore
4. 构建依赖链

使用 data/dependency-patterns.md 中的模式：

自动检测依赖关系：

  • 同一类别内按顺序执行（Task 1.2 依赖于 1.1）
  • 数据库/迁移 → 阻塞 → API/业务逻辑
  • 配置/设置 → 阻塞 → 实现
  • 实现 → 关联 → 测试（不构成阻塞，可并行开展）
5. 主动检测缺口

使用 data/dependency-patterns.md 中的常见模式，创建用于发现问题的 issue：

自动检测缺失项：

  • 迁移的回滚计划
  • API 端点的速率限制
  • 外部服务的错误处理
  • 功能的监控/指标
  • 实现的测试
6. 创建跟踪基础设施

为整个规范创建一个 Epic issue，并将所有任务关联为子项。

Epic 和依赖关系模板请参阅 templates/issue-creation.md。

7. 可执行的报告（不只是摘要）

使用 examples/conversion-workflow.md 中的格式呈现结果：

  • 按优先级拆分的 issue
  • 主动发现并创建的 issue
  • 可立即开始的任务
  • 依赖链
  • 用户后续步骤

高级功能

复杂度估算

根据任务描述添加标签（参见 data/priority-rules.md）：

  • “setup”“simple”：complexity:low
  • “implement”“integrate”：complexity:medium
  • “refactor”“migrate”：complexity:high
风险标记

为以下内容创建单独的 issue：

  • 数据迁移
  • 外部依赖（第三方 API）
  • 带有“TODO: figure out”的任务

错误处理

如果 OpenSpec 更改不存在：

❌ Change 'xyz' not found in openspec/changes/
Available changes: [list them]
Run: openspec list

如果 Beads 尚未初始化：

❌ Beads not initialized in this project.
Run: bd init --prefix <project-name>

如果 tasks.md 格式错误：

⚠️  tasks.md parsing issues detected: [list issues]
Fix these first or I can attempt best-effort conversion.

应避免的反模式

❌ 不要盲目地 1:1 照搬任务 —— 运用智能判断 ❌ 不要忽略缺失的测试任务 —— 主动创建 ❌ 不要把所有事项都设为高优先级 —— 合理设置优先级 ❌ 不要为 5 个任务创建 50 个问题 —— 合并相关的微任务 ❌ 不要丢失“原因” —— 在史诗描述中引用 proposal.md

与 Agent 工作流集成

当 Agent 看到：User: "Let's implement add-auth"

你会自动：

  1. 检查 openspec/changes/add-auth 是否存在
  2. 分析任务质量
  3. 提醒用户注意缺失项
  4. 智能转换
  5. 提供可执行的后续步骤
  6. 提醒 Agent 运行 bd ready 并开始工作

用户应该感觉一切都神奇地完成了——规划无缝地转化为执行。

参考文件

  • 示例：查看 examples/conversion-workflow.md，了解完整的转换场景
  • 模板：查看 templates/issue-creation.md，了解命令模板
  • 优先级规则：查看 data/priority-rules.md，了解智能优先级设置逻辑
  • 依赖关系：查看 data/dependency-patterns.md，了解自动检测模式

评论

支持 Markdown