step-running

ステップ実行

DAG プランの単一ステップを、アトミックなバックグラウンドサブエージェントとして実行します。自律的に作業を完了し、結果を報告します。ユーザーとのやり取りは行いません。

これは phase-running の DAG における兄弟スキルです。実行モデルとアトミック性の契約は同一ですが、次の点が異なります。

• プランのパスとフェーズ番号ではなく、ステップファイルのパス（step-<n>.md）を受け取ります。
• 作業を始める前に、ステップのフロントマターにある status フィールドを使ってステップをアトミックに確保し、完了時または失敗時に解放します。これにより、同じプランディレクトリを複数のオーケストレーターインスタンスから安全に操作できます。

実行モデル

このスキルはバックグラウンドの Agent（サブエージェント）内で実行されます。v-implementing（または /run-step を呼び出したユーザー）が、run_in_background: true を指定して Agent ツールから起動します。

ステップエージェントが受け取る情報：

• ステップのパス：step-<n>.md のフルパス
• プランディレクトリ：親プランディレクトリのフルパス（プラン全体のコンテキストを得るため、ここから root.md を読み込みます）
• Agent ID：このサブエージェントの一意の識別子（例：オーケストレーターのセッション ID + ステップ ID + タイムスタンプ）。アトミックな確保と古い確保の検出に使用します。
• 関連コンテキスト：呼び出し元から渡される追加のコンテキスト

並行処理：アトミックな確保

作業を始める前に、ステップを確保します。

1. ステップファイルのフロントマターを読み込みます。
2. status: done の場合 — Status: skipped と報告して終了します。ステップはすでに完了しています。
3. status: claimed で、assignee が自身の Agent ID と異なる場合：
   • 有効な確保（claimed_at が直近 1 時間以内）の場合：Status: blocked（理由：claimed by <other-id>）と報告して終了します。
   • 古い確保（1 時間超）の場合：前のワーカーが停止した可能性が高いため、処理を続けて上書きします。
4. それ以外の場合（status: ready または古い claimed）：単一の Edit でフロントマターのブロックを書き換え、ファイルシステム上で十分にアトミックな書き込みを行います。次の値を設定します。
   • status: claimed
   • assignee: <your-agent-id>
   • claimed_at: <ISO timestamp UTC>
5. ファイルを再読み込みします。assignee が自身の ID と異なる場合は、別のワーカーとの競合に負けています。Status: blocked（理由：lost claim race）と報告して終了します。

最終状態に移行する際は、フロントマターを次のように設定します。

• 完了：status: done とし、assignee と claimed_at を消去します。
• ブロックまたは失敗（再試行可能）：status: ready とし、assignee と claimed_at を消去します。オーケストレーター（または別のワーカー）が再試行できます。
• 失敗（再試行不可）：status: claimed のままにして、オーケストレーターが調査できるよう、レポートに理由を記載します。

真のマシン間アトミック性（NFS など）が必要な場合は、呼び出し元が（共有ロックサービスなどを使って）同期を担います。単一の Edit を使う方法は、ローカルファイルシステムや適切に動作するネットワークファイルシステムでは十分です。

自律性

ステップエージェントは、サブエージェント内では常に Autopilot として実行されます。外側の自律性と人間によるチェックポイントは、呼び出し元のコンテキストが制御します。

重要：ステップエージェントは AskUserQuestion を使用しません。不明点がある場合は、詳細を添えて Status: blocked と報告します。ユーザーとのやり取りは呼び出し元が行います。

手順

ステップ 1：コンテキストの読み込み

1. ステップを確保します（「並行処理：アトミックな確保」を参照）。確保できなかった場合は、ここで停止します。
2. ステップファイル全体を読み込みます。
3. プラン全体のコンテキスト（概要、現在の状態、目指す最終状態、実装方針、全体の検証）を得るため、プランディレクトリから root.md を読み込みます。
4. ステップの「必要な変更」セクションで言及されているファイルをすべて読み込みます。

ステップ 2：事前チェック

チェック	失敗時の対応
すべての depends_on ステップの status が done	スケジューラーの不具合です。確保を解放し、blocked と報告します
対象ファイルにマージコンフリクトがない	確保を解放し、blocked と報告します
依存するステップで指定されたファイル／ディレクトリが存在する	確保を解放し、blocked と報告します

ステップ 3：ステップの実行

ステップの「必要な変更」セクションに記載された変更を実装します。軽微な不一致には対応し、重大な不一致がある場合は blocked と報告します。

ステップ 4：検証を実行する

phase-running と同じ 3 つの分類パターンです。

1. 自動検証（実行可能なコマンド）：各コマンドを実行し、合格／不合格を記録します。不合格の場合は、修正して 1 回再試行します。
2. 自動 QA（エージェント主導のシナリオ — ブラウザー操作、スクリーンショットの差分、CLI の手順確認）：実行し、項目ごとに合格／不合格を記録します。
3. 手動検証：未チェックのままにします。ユーザーと一緒に対応するのは呼び出し元です。
4. QA 仕様書（リンク先のドキュメント）：存在する場合は、QA Doc: <path> と報告します。シナリオをインラインで実行しないでください。

ステップ 5：ステップファイルを更新する

• 合格した自動検証と自動 QA の項目にチェックを入れます（- [x]）。
• 手動検証の項目にはチェックを入れないでください。
• 「Concurrency: Atomic Claim」の終端遷移ルールに従って、フロントマターの status を更新します。
• last_updated／last_updated_by のフロントマターフィールドがある場合は更新します。

ステップ 6：結果を報告する

完了：

Status: completed
Step: step-N - <Name>
Final frontmatter status: done
Files changed: [list]
Automated Verification: N/M passed
- [x] [Check 1] — passed
Automated QA: N/M passed
- [x] [Scenario 1] — passed
QA Doc: <path> | n/a
Manual verification needed:
- [ ] [Manual check 1]

ブロック／失敗： phase-running と同じ形式に加えて、オーケストレーターがステップを再試行可能な状態（ready）に戻すか、調査のために保留するか（claimed）を判断できるよう、Final frontmatter status: の行を含めます。

アトミック性の契約

• 対話形式の質問はしません。
• 説明のない中途半端な状態を残しません。
• 終了時のフロントマターの status は、常に最終状態を反映します。
• 呼び出し元が次の手順を判断できるだけの詳細を報告に含めます。

コンテキスト引き継ぎパターン

方向	データ
呼び出し元 → ステップエージェント	ステップのパス + プランディレクトリ + エージェント ID + 自律性モード
ステップエージェントが読み取るもの	ステップファイル + root.md + Changes Required 内のファイル
ステップエージェントが書き込むもの	フロントマターのステータス遷移 + チェックボックス + コード変更
ステップエージェント → 呼び出し元	ステータス + 変更ファイル + 検証結果 + 最終的なフロントマターのステータス
呼び出し元が対応するもの	手動検証、ステップ間の調整、QA ドキュメントの実行、人によるチェックポイント