openspec-task-loop

OpenSpec タスクループ

サブエージェントのアーキテクチャ

このスキルでは、各イテレーションでコンテキストを蓄積し、前のステップに依存する、厳密に逐次実行されるサブエージェントのパイプラインを使用します。パターン：E（段階的パイプライン）＋C（レビューループ）。

エージェント

エージェント	役割	実行タイミング
spec-scaffolder	OpenSpec のすべての成果物（proposal.md、design.md、tasks.md、specs/）を作成します	タスク選択後
implementer	対象範囲内のタスクを実装し、チェックボックスを更新して、検証を実行します	仕様の準備後
verifier	品質ゲートを独立して確認します：スコープの原子性、受け入れ基準、仕様とテストの整合性	実装完了後
archiver	仕様の差分をマージしてアーカイブに移動し、親の tasks.md を更新します	検証合格後

逐次的な依存関係

• 並列処理なし：ステップ N+1 はステップ N の完了に依存します
• コンテキストの蓄積：各エージェントは前の成果物を読み、理解を深めます
• 品質ゲート：次のステップに進む前に、各段階が確実であることを検証エージェントが確認します

逐次実行の理由：この段階的なアプローチがないと、複数回のタスクイテレーション（5～10回）によって推論の品質が大幅に低下します。各ステップで信頼性を高め、問題を早期に発見できます。

環境の確認

実行前に、次の項目を確認してください。

1. リポジトリへの git アクセスを確認します
2. openspec/ ディレクトリへの書き込み権限を確認します
3. プロジェクトルートに既存のタスクリスト（tasks.md）があるか確認します
4. references/openspec-task-templates.md が利用可能であることを確認します

編集前のリポジトリ同期（必須）

既存のリポジトリでファイルを作成・更新・削除する前に、現在のブランチをリモートと同期します。

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

作業ツリーがクリーンでない場合は、まずスタッシュし、同期してから復元します。

git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

origin がない、pull を利用できない、または rebase／スタッシュで競合が発生した場合は、停止して続行する前にユーザーに確認してください。

概要

OpenSpec はタスク1つにつき変更1つとして実行します。スコープを絞り、成果物を生成し、実装、検証、アーカイブを済ませてから次のタスクに進みます。

ワークフローの選択

1. 現在のコーディングツールで /opsx:* コマンドがサポートされている場合：ネイティブの OPSX フローを使用します。
2. サポートされていない場合：openspec/changes/<change-id>/ の下にファイルを作成する手動の代替手順を使用します。

コアループ（単一タスク）

tasks.md から選択したタスクごとに、次の手順を実行します。

1. タスクを1つだけ選択します

   • 価値のある原子的な単位を1つに絞ります（通常は開発に1～3日）。
   • 大きすぎる場合は、先に分割します。

2. タスク専用の変更を作成します

   • 変更 ID は task-<task-id>-<short-slug> の形式にします（例：task-2-3-pin-crud）。

3. OpenSpec の成果物を使って計画します

   • proposal.md：意図、スコープ、受け入れ基準、対象外の事項。
   • specs/.../spec.md：要件と GIVEN／WHEN／THEN シナリオ。
   • design.md：実装方針とトレードオフ。
   • tasks.md：この単一タスクの実装チェックリスト。

4. このタスクのスコープのみを実装します

   • 無関係なリファクタリングを含めないでください。
   • 作業が完了したらチェックボックスを更新します。

5. アーカイブ前に検証します

   • 完全性、正確性、一貫性を検証します。
   • アーカイブ前に重大な不一致を修正します。

6. アーカイブして同期します

   • 必要に応じて仕様の差分をマージします。
   • 変更フォルダーをアーカイブします。
   • 親プロジェクトのタスクを完了済みにします。

ネイティブ OPSX コマンドの手順

タスクごとに、次の手順を使用します。

/opsx:new task-<task-id>-<slug>
/opsx:ff <change-id>          # or /opsx:continue for stepwise control
/opsx:apply <change-id>
/opsx:verify <change-id>
/opsx:archive <change-id>

ルール：

• 要件がまだ不明確な場合は、/opsx:continue を優先します。
• スコープが明確で小さい場合は、/opsx:ff を優先します。
• 実装によって計画とのずれが判明した場合は、続行する前に成果物を更新します。

手動の代替手順（/opsx 非対応の場合）

スラッシュコマンドを利用できない場合：

1. OpenSpec ツリー（openspec/changes、openspec/specs）があることを確認します。
2. 変更フォルダーを1つ作成し、次のファイルを用意します。
   • proposal.md
   • design.md
   • tasks.md
   • specs/<capability>/spec.md
3. タスクの成果物を準備する前に、references/openspec-task-templates.md を読みます。
4. タスクを実装し、チェックボックスを更新します。
5. ローカルで検証／テストを実行します。
6. 仕様の差分を openspec/specs/ にマージし、変更を openspec/changes/archive/<date>-<change-id>/ に移動します。

品質ゲート（アーカイブ前に必ず合格すること）

• スコープが単一タスクのままで、アトミックである
• 受け入れ基準を満たしている
• 仕様のシナリオがテストまたは実行可能なチェックに反映されている
• 無関係なファイルが変更されていない
• 親の tasks.md が完了状態に更新されている
• アーカイブの注記に変更内容とその理由が記載されている

更新の出力形式

進捗を報告する際は、次の形式を使用します。

Task: <id + title>
Change: <openspec change id>
Status: planning | implementing | verifying | archived
Done:
- ...
Next:
- ...
Risks/Notes:
- ...

期待される出力

完了したタスクのイテレーションごとに、次の内容が確認できる必要があります。

• proposal.md、design.md、tasks.md、および specs/<capability>/spec.md を含む OpenSpec の変更フォルダー（openspec/changes/<change-id>/）
• すべてのタスクのチェックボックスがオンになった実装済みコード
• スコープのアトミック性、受け入れ基準の達成、仕様とテストの整合性を確認した検証レポート
• openspec/changes/archive/<date>-<change-id>/ に移動された変更フォルダー
• 完了したタスクが完了済みとしてマークされた、更新済みの親 tasks.md
• Status: archived を示す、出力形式ブロックに沿った進捗レポート

エッジケース

• タスクが大きすぎる場合: 作業を開始する前に、より小さなアトミックなサブタスク（1〜3日分の開発作業）に分割します。大きすぎるタスクの実装は開始しないでください。
• /opsx コマンドがサポートされていない場合: openspec/changes/ の下に手動でファイルを作成し、手動フォールバックの手順に従います。
• references/openspec-task-templates.md がない場合: ユーザーに警告し、最小限の成果物で進めます。足場の品質を高めるため、テンプレートファイルの提供を依頼します。
• 検証で重大な不整合が見つかった場合: アーカイブを中止し、具体的な不足点を提示して、再検証の前に修正します。品質ゲートに不合格のままアーカイブしてはいけません。
• リベース中にマージコンフリクトが発生した場合: 作業を停止してユーザーにコンフリクトを提示し、仕様ファイルや実装ファイルの変更を自動で解決しないでください。
• Tasks.md が存在しない場合: ループに入る前に、タスクリストの提供または作成をユーザーに依頼します。

ステップ完了レポート

各主要ステップの完了後、次の形式でステータスレポートを出力します。

◆ [Step Name] ([step N of M] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          √ pass (note if relevant)
  [Check 3]:          × fail — [reason]
  [Check 4]:          √ pass
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

チェック項目の名前は、そのステップで実際に検証する内容に合わせてください。合格には √、不合格には ×、簡単な補足には — を使用します。「Criteria」行には、達成した受け入れ基準の数をまとめます。「Result」行には、全体の判定を記載します。

選択（ステップ1/4）

◆ Selection (step 1 of 4 — task scoping)
··································································
  Task identified:        √ pass — task-2-3-pin-crud selected
  Scope bounded:          √ pass — 1-3 dev days, atomic unit
  Dependencies clear:     √ pass — no blockers in tasks.md
  [Criteria]:             √ 3/3 met
  ____________________________
  Result:                 PASS

計画（ステップ2/4）

◆ Planning (step 2 of 4 — spec scaffolding)
··································································
  Spec artifacts created: √ pass — proposal.md, design.md, tasks.md, spec.md
  Implementation planned: √ pass — approach and tradeoffs documented
  [Criteria]:             √ 2/2 met
  ____________________________
  Result:                 PASS

実装（ステップ3/4）

◆ Implementation (step 3 of 4 — code delivery)
··································································
  Code written:           √ pass — all checkboxes updated
  Tests pass:             × fail — 1 unit test failing
  Scope respected:        √ pass — no unrelated files changed
  [Criteria]:             √ 2/3 met
  ____________________________
  Result:                 PARTIAL

アーカイブ（ステップ4/4）

◆ Archive (step 4 of 4 — completion and sync)
··································································
  Artifacts synced:       √ pass — specs merged into openspec/specs/
  Quality gate passed:    √ pass — all 6 criteria met
  [Criteria]:             √ 2/2 met
  ____________________________
  Result:                 PASS

リソース

• references/openspec-task-templates.md — 手動モード用の proposal/spec/design/tasks テンプレート。
• scripts/new_task_change.sh — 手動モードで使用できる任意の足場作成スクリプト。