openspec-to-beads

OpenSpec から Beads へのブリッジ

計画成果物（OpenSpec）を実行可能な作業ストリーム（Beads）に変換し、追跡可能性を維持しながら、実装上の不足を積極的に発見するワークフローオーケストレーターです。

中核となる理念

OpenSpec は構築するもの（不変の契約）を定義します。 Beads は実行状態（変化する現実）を追跡します。

あなたの役割は、機械的に変換するのではなく、両者の隔たりを知的に埋めることです。

このスキルが有効になるタイミング

自動トリガー：

• ユーザーが openspec apply <change> を実行したとき
• ユーザーが「この仕様を実装して」「X の作業を始めて」と言ったとき
• ユーザーが提案を承認し、「準備完了」や「始めましょう」と言ったとき

手動トリガー：

• ユーザーが明示的に「仕様を Beads に変換して」と依頼したとき
• ユーザーが「この変更の課題を作成して」と言ったとき

次の場合は有効にしないでください：

• 仕様を表示するだけの場合（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 エンドポイントより先に DB マイグレーションを行う必要があります
3. 不足しているものはありますか？ テスト？ ドキュメント？ デプロイ？
4. 何がうまくいかない可能性がありますか？ さらなる作業が必要になると判明しそうなタスクを特定してください

問題を見つけた場合は、変換する前にユーザーに伝えてください

分析例については、examples/conversion-workflow.md を参照してください。

3. スマートな変換（1 対 1 のマッピングではありません）

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. 依存関係チェーンの構築

data/dependency-patterns.md のパターンを使ってください：

依存関係を自動検出：

• 同じカテゴリ内の順次処理（Task 1.2 は 1.1 にブロックされます）
• DB／マイグレーション → ブロック → API／ビジネスロジック
• 設定／セットアップ → ブロック → 実装
• 実装 → 関連 → テスト（ブロックではありません。並行して作業します）

5. 不足の積極的な検出

data/dependency-patterns.md の一般的なパターンを使って、発見した事項の課題を作成してください：

不足を自動検出：

• マイグレーションのロールバック計画
• API エンドポイントのレート制限
• 外部サービスのエラーハンドリング
• 機能のモニタリング／メトリクス
• 実装のテスト

6. 追跡インフラストラクチャの作成

仕様全体を対象とし、すべてのタスクを子としてリンクするエピック課題を作成します。

エピックと依存関係のテンプレートについては、templates/issue-creation.md を参照してください。

7. 実行可能なレポート（単なる要約ではありません）

examples/conversion-workflow.md の形式を使って、結果を提示してください：

• 優先度別の課題の内訳
• 積極的に発見して作成した課題
• すぐに着手できるタスク
• 依存関係チェーン
• ユーザー向けの次のステップ

高度な機能

複雑さの見積もり

タスクの説明に基づいてラベルを追加してください（data/priority-rules.md を参照）：

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

リスクのフラグ付け

次の項目には個別の課題を作成してください：

• データマイグレーション
• 外部依存関係（サードパーティ 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を参照しましょう

エージェントのワークフローとの連携

エージェントが次の内容を受け取ったとき：User: "Let's implement add-auth"

自動的に次の処理を行います。

1. openspec/changes/add-authが存在するか確認します
2. タスクの品質を分析します
3. 不足があれば警告します
4. 適切に判断しながら変換します
5. 実行可能な次のステップを提示します
6. bd readyを実行して作業を開始するようエージェントに促します

ユーザーは、計画がシームレスに実行へと移り、まるで魔法が起きたように感じるはずです。

参考ファイル

• 例：完全な変換シナリオについては、examples/conversion-workflow.mdを参照してください
• テンプレート：コマンドテンプレートについては、templates/issue-creation.mdを参照してください
• 優先順位のルール：優先順位を賢く付けるロジックについては、data/priority-rules.mdを参照してください
• 依存関係：自動検出のパターンについては、data/dependency-patterns.mdを参照してください