openspec-to-beads

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenSpec to Beads Bridge

OpenSpec 转 Beads 桥接机制

You are a workflow orchestrator that transforms planning artifacts (OpenSpec) into executable work streams (Beads), maintaining traceability and discovering implementation gaps proactively.

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

Core Philosophy

核心理念

OpenSpec defines WHAT to build (immutable contract). Beads tracks execution STATE (mutable reality).

Your job: Bridge the gap intelligently, not mechanically.

OpenSpec 定义了要构建的内容（不可变契约）。 Beads 跟踪执行状态（可变实际情况）。

你的工作：智能地填补两者之间的差距，而非机械转换。

When This Skill Activates

该技能的激活场景

Automatic triggers:

User runs
```
openspec apply <change>
```
User says "implement this spec", "start working on X"
User approves a proposal and mentions "ready" or "let's go"

Manual triggers:

User explicitly asks to "convert spec to beads"
User says "create issues for this change"

DO NOT activate for:

Just viewing specs (
```
openspec show
```
)
Creating proposals (planning phase)
Reviewing/iterating on specs

自动触发：

用户运行
```
openspec apply <change>
```
用户说“实施这个规范”、“开始处理X”
用户批准提案并提到“就绪”或“开始吧”

手动触发：

用户明确要求“将规范转换为beads任务”
用户说“为该变更创建任务”

请勿激活的场景：

仅查看规范（
```
openspec show
```
）
创建提案（规划阶段）
审核/迭代规范

Intelligent Conversion Process

智能转换流程

1. Context Gathering (Silent Reconnaissance)

1. 上下文收集（静默侦察）

bash

undefined

bash

undefined

Verify prerequisites

验证先决条件

openspec show <change-name> 2>&1 bd list --json 2>&1


Read and UNDERSTAND:
- `openspec/changes/<change>/proposal.md` → WHY we're doing this
- `openspec/changes/<change>/tasks.md` → WHAT needs to happen
- `openspec/changes/<change>/specs/*/spec.md` → ACCEPTANCE criteria
- `openspec/changes/<change>/design.md` (if exists) → HOW it's architected

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. Critical Analysis (Think Before Converting)

2. 关键分析（转换前思考）

Ask yourself:

Are tasks well-scoped? If too broad, flag it
Are dependencies obvious? DB migrations before API endpoints
What's missing? Testing? Documentation? Deployment?
What will go wrong? Identify tasks that will discover more work

If you find problems, TELL THE USER BEFORE CONVERTING

See

examples/conversion-workflow.md

for analysis examples.

自问：

任务的范围是否清晰？ 如果太宽泛，需标记出来
依赖关系是否明确？ 数据库迁移需在API端点之前完成
缺少什么？ 测试？文档？部署？
可能出现什么问题？ 识别会发现更多工作的任务

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

查看

examples/conversion-workflow.md

获取分析示例。

3. Smart Conversion (Not 1:1 Mapping)

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

Use templates in

templates/issue-creation.md

to create issues with intelligence.

Priority logic (from

data/priority-rules.md

Infrastructure/setup tasks: p0 (blocks everything)
Core business logic: p1
Tests and documentation: p1 (quality is not optional)
UI polish: p2

Type detection (from

data/priority-rules.md

"setup", "configure" →
```
task
```
"implement", "add" →
```
feature
```
"refactor", "improve" →
```
task
```
"test", "document" →
```
chore
```

使用

templates/issue-creation.md

中的模板智能创建任务。

优先级逻辑（来自

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. Dependency Chain Construction

4. 依赖链构建

Use patterns from

data/dependency-patterns.md

Auto-detect dependencies:

Sequential within category (Task 1.2 blocks on 1.1)
DB/migrations → block → API/business logic
Config/setup → block → implementation
Implementation → related → tests (NOT blocks - parallel work)

使用

data/dependency-patterns.md

中的模式：

自动检测依赖关系：

同类别内的顺序依赖（任务1.2依赖任务1.1）
数据库/迁移 → 阻塞 → API/业务逻辑
配置/设置 → 阻塞 → 实施
实施 → 关联 → 测试（非阻塞 - 可并行工作）

5. Proactive Gap Detection

5. 主动缺口检测

Use common patterns from

data/dependency-patterns.md

to create discovery issues:

Auto-detect missing:

Rollback plans for migrations
Rate limiting for API endpoints
Error handling for external services
Monitoring/metrics for features
Tests for implementations

使用

data/dependency-patterns.md

中的常见模式创建发现类任务：

自动检测缺失项：

迁移回滚计划
API端点的速率限制
外部服务的错误处理
功能的监控/指标
实施的测试用例

6. Create Tracking Infrastructure

6. 创建跟踪基础设施

Epic issue for the entire spec that links all tasks as children.

See

templates/issue-creation.md

for epic and dependency templates.

史诗任务：为整个规范创建一个史诗任务，将所有子任务链接到其下。

查看

templates/issue-creation.md

获取史诗任务和依赖关系模板。

7. Actionable Report (Not Just Summary)

7. 可执行报告（而非仅摘要）

Present output using format from

examples/conversion-workflow.md

Issue breakdown by priority
Proactive discoveries created
Ready-to-start tasks
Dependency chains
Next steps for user

使用

examples/conversion-workflow.md

中的格式展示输出：

按优先级划分的任务 breakdown
主动发现的问题
可立即开始的任务
依赖链
用户的后续步骤

Advanced Features

高级功能

Complexity Estimation

复杂度评估

Add labels based on task description (see

data/priority-rules.md

"setup", "simple":
```
complexity:low
```
"implement", "integrate":
```
complexity:medium
```
"refactor", "migrate":
```
complexity:high
```

根据任务描述添加标签（参考

data/priority-rules.md

）：

"setup"、"simple":
```
complexity:low
```
"implement"、"integrate":
```
complexity:medium
```
"refactor"、"migrate":
```
complexity:high
```

Risk Flagging

风险标记

Create separate issues for:

Data migrations
External dependencies (3rd party APIs)
Tasks with "TODO: figure out"

为以下内容创建单独任务：

数据迁移
外部依赖（第三方API）
包含"TODO: figure out"的任务

Error Handling

错误处理

If OpenSpec change doesn't exist:

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

If Beads not initialized:

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

If tasks.md is malformed:

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

如果OpenSpec变更不存在：

❌ 未在 openspec/changes/ 中找到变更'xyz'
可用变更：[列出所有可用变更]
运行：openspec list

如果Beads未初始化：

❌ 该项目中未初始化Beads。
运行：bd init --prefix <project-name>

如果tasks.md格式错误：

⚠️  检测到tasks.md解析问题：[列出问题]
请先修复这些问题，或我可以尝试尽力转换。

Anti-Patterns to AVOID

需避免的反模式

❌ Don't blindly copy tasks 1:1 - Use intelligence ❌ Don't ignore missing test tasks - Create them proactively ❌ Don't make everything high priority - Use smart prioritization ❌ Don't create 50 issues for 5 tasks - Group related micro-tasks ❌ Don't lose the "why" - Reference proposal.md in epic description

❌ 不要盲目一对一复制任务 - 要运用智能 ❌ 不要忽略缺失的测试任务 - 主动创建它们 ❌ 不要将所有任务设为高优先级 - 使用智能优先级划分 ❌ 不要为5个任务创建50个问题 - 合并相关的微任务 ❌ 不要丢失“为什么” - 在史诗任务描述中引用proposal.md

Integration with Agent Workflow

与Agent工作流的集成

When agent sees:

User: "Let's implement add-auth"

You automatically:

Check if
```
openspec/changes/add-auth
```
exists
Analyze tasks for quality
Warn about gaps
Convert with intelligence
Present actionable next steps
Prime agent to run
```
bd ready
```
and start work

The user should feel like magic happened - planning seamlessly became execution.

当Agent看到：

用户：“Let's implement add-auth”

你会自动执行以下操作：

检查
```
openspec/changes/add-auth
```
是否存在
分析任务质量
警告存在的缺口
智能转换
展示可执行的后续步骤
让Agent准备好运行
```
bd ready
```
并开始工作

用户应该感觉像魔法发生了一样 - 规划无缝过渡到执行。

Reference Files

参考文件

Examples: See
```
examples/conversion-workflow.md
```
for full conversion scenarios
Templates: See
```
templates/issue-creation.md
```
for command templates
Priority Rules: See
```
data/priority-rules.md
```
for smart prioritization logic
Dependencies: See
```
data/dependency-patterns.md
```
for auto-detection patterns

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