tomevault-io 概要
親エージェントが唯一のユーザ窓口となり、実行はサブエージェント（Executor/Reviewer/Verifier）に委譲する協調開発の設計/運用を定義するスキル。
参照（必読）
references/execution_framework.mdreferences/pipeline_spec_template.jsonreferences/pipeline_spec_guarded_min.jsonreferences/pipeline_json_guardrails.mdreferences/pipeline_prompt_guarded_template.mdreferences/pipeline_dynamic_stage_rules.mdreferences/pipeline_spec_dynamic_safe.jsonreferences/pipeline_prompt_dynamic_template.mdreferences/pipeline_dynamic_test_run_template.mdreferences/subagent_prompt_templates.mdreferences/contract_output.md
入力
- 目的/期待成果
- 対象リポ/対象パス
- 制約（権限、期限、禁止事項）
- 書き込み許可範囲
- レビュー/検証の記録先（review_output_dir）
- 必須ステージ/任意ステージ
- 動的追加/ループ条件（next_stages）と採用理由
- テスト/CI 要件
入力受け渡し例
- 親エージェントは 1 つの PROMPT に統合して
codex_exec.py --promptに渡す。 - 必須要素: OBJECTIVE / SCOPE / CONSTRAINTS / REQUIRED OUTPUTS / CAPSULE PATCH RULES / PIPELINE DESIGN REQUIREMENT / TEST DESIGN REQUIREMENT。
- 例（最小構成）:
ROLE: Parent agent orchestration for <topic> DATE: YYYY-MM-DD OBJECTIVE - <goal> SCOPE - Target repo: <path> - Target paths: <paths> CONSTRAINTS - <constraints> REQUIRED OUTPUTS 1) <artifact list> CAPSULE PATCH RULES - /facts はオブジェクト配列（文字列禁止） - /draft /critique /revise はオブジェクトのまま PIPELINE DESIGN REQUIREMENT - 既定パイプラインの踏襲禁止 - 初期/動的ステージの設計理由 - next_stages 追加条件
役割分担（実行責任）
- 親エージェント: 要件/品質合意、協調ループ起動、ゲート判定、最終報告のみを担当。
- Executor: 実ファイル変更、テスト実行、ログ収集。
- Reviewer: 独立レビュー、根拠付き指摘、未解消事項の提示。
- Verifier: テスト/CI 再実行、失敗時の切り分け・再試行。
- Releaser: commit/PR などの運用作業（任意、必要時のみ）。
手順
- 参照ドキュメントを読み、役割分担と例外条件を確定すること。
- Executor/Reviewer/Verifier の責務と書き込み範囲を明示すること。
- パイプラインを
references/pipeline_spec_template.jsonで組成し、既定パイプラインの踏襲は禁止としてタスクに最適化すること（初期/動的ステージと理由を /draft.proposal に記録）。 - スキーマ逸脱の再発防止として
references/pipeline_json_guardrails.mdを適用し、安定性重視の案件はreferences/pipeline_spec_guarded_min.jsonとreferences/pipeline_prompt_guarded_template.mdを使用すること。 - 動的ステージが必要な案件は
references/pipeline_dynamic_stage_rules.mdとreferences/pipeline_spec_dynamic_safe.jsonとreferences/pipeline_prompt_dynamic_template.mdを使用し、追加条件を /draft.proposal に明記すること。 - 動的設計が必要な場合は
--pipeline-specを使用し、--pipeline-stagesの固定テンプレートに依存しないこと。 allowed_stage_idsは初期/動的追加を含む採用ステージに合わせること（releaseを使う可能性がある場合のみ含め、使わない場合は除外）。stagesは初期実行順のみ列挙すること。- Capsule 構造を
/draft /critique /revise /facts /open_questions /assumptionsに合わせること。 - サブエージェントの依頼文を
references/subagent_prompt_templates.mdから作成すること。 - ループ条件/終了条件、動的追加条件（next_stages）とテスト/CI ゲートを明記すること。
- 成果物契約出力を
references/contract_output.mdに従って固定化すること。 - 事実ベースで記述し、不明は "不明" と明記すること。
実行前提/依存
codex実行バイナリが PATH にあること（例:node_modules/.bin）。jsonschemaがuv run pythonで利用可能であること。- pipeline は 360〜420s/ステージの timeout を推奨（読み取り/整形が多い場合）。
- 確認手順（例）:
command -v codexcommand -v uvuv run python -c "import jsonschema, sys; print('jsonschema_ok')"
検証手順（必須）
- pipeline spec の妥当性検証:
uv run pytest tests/codex_subagent/test_pipeline_spec.py --no-cov - v2 runtime の検証:
uv run pytest tests/codex_subagent/test_v2_runtime.py --no-cov - 動的ステージ運用時の実行テンプレ:
references/pipeline_dynamic_test_run_template.md
Capsule パッチルール（必須）
/factsは「オブジェクト配列」。文字列は不可。/draft/critique/reviseはオブジェクトのまま、キー追加で記録する。/open_questions/assumptionsも許可パス。配列として追記する。- JSON Patch 例:
{ "op": "add", "path": "/facts/-", "value": { "type": "commands", "items": ["cmd1"], "evidence": "shell" } }
最小 pipeline spec 例
※新規 spec は schema_version: "2.0" を前提にする。depends_on で linear / branch / join を表現し、--pipeline-stages は legacy shorthand としてだけ扱う。
{
"schema_version": "2.0",
"allow_dynamic_stages": false,
"allowed_stage_ids": ["draft", "execute", "review", "verify"],
"stages": [
{
"id": "draft",
"role": "planner",
"sandbox": "read-only",
"write_roots": [],
"max_attempts": 1,
"instructions": "パイプライン設計と成功条件を /draft に記録。根拠は /facts。"
},
{
"id": "execute",
"role": "executor",
"sandbox": "workspace-write",
"write_roots": ["src", "tests"],
"max_attempts": 2,
"depends_on": ["draft"],
"instructions": "実行結果/ログを /facts に記録し、必要なコード変更だけ行う。"
},
{
"id": "review",
"role": "reviewer",
"sandbox": "read-only",
"write_roots": [],
"max_attempts": 1,
"depends_on": ["execute"],
"instructions": "独立レビューを /critique に記録。根拠必須。"
},
{
"id": "verify",
"role": "verifier",
"sandbox": "read-only",
"write_roots": [],
"max_attempts": 1,
"depends_on": ["review"],
"instructions": "テスト・検証結果を /facts に追加し、release 可否を判定する。"
}
]
}
起動/成果物保存先
- 起動は
codex-subagentを使用する。 - 例（pipeline spec を使う場合）:
uv run python .agents/skills/codex-subagent/scripts/codex_exec.py \ --mode pipeline --pipeline-spec <spec.json> \ --capsule-store auto --sandbox read-only --json --prompt "$PROMPT" - 再開例:
uv run python .agents/skills/codex-subagent/scripts/codex_exec.py \ --mode pipeline --resume-run <run_id_or_state.json> --json --prompt "$PROMPT" - ログ:
.codex/sessions/codex_exec/{human|auto}/YYYY/MM/DD/run-*.jsonl - capsule（
--capsule-store file|auto）:.codex/sessions/codex_exec/{human|auto}/artifacts/<pipeline_run_id>/capsule.json - checkpoint state:
.codex/sessions/codex_exec/{human|auto}/artifacts/<pipeline_run_id>/state.json - レビュー/検証の成果物:
review_output_dir（既定はoutput/reviews/）
実行ポリシー（品質優先）
- タスク難易度や要求水準を下げての短縮はしない。
- 時間がかかる場合は timeout を延長して対応する。
- timeout が発生したら、同一スコープで再実行する（再実行上限を明示）。
- 再実行しても進められない場合は、タスクを停止しフレームワークのデバッグ/改善に移行する。
例外（親が実行）
- 仕様変更/品質基準変更などユーザ合意が必要な判断。
- サブエージェント権限不足で進行不可となった操作。
- 秘密情報や承認が必要な操作。
オプション
review/verify/releaseステージの有無を選択すること。allow_dynamic_stagesの有効/無効を決めること。- 再実行上限を明示すること。
- 書き込み許可パスとテスト範囲を最小化すること。
既定値（codex_exec）
--mode:single--count:3--sandbox:read-only--timeout:360--profile: 未指定（None）--task-type:code_gen--strategy:best_single--merge:concat--log: 有効--capsule-store:auto--max-stages:10
成果物命名（推奨）
- 基本ディレクトリ:
output/reviews/ - パイプライン spec:
<topic>_pipeline_spec_YYYY-MM-DD.json - サブエージェント依頼文:
<topic>_subagent_prompts_YYYY-MM-DD.md - テスト計画:
<topic>_test_plan_YYYY-MM-DD.md - レビュー記録:
<topic>_review_YYYY-MM-DD_roundN.md - 成果物契約出力:
<topic>_contract_output_YYYY-MM-DD.md
出力
- パイプライン spec（JSON）
- 役割分担と書き込み範囲
- Capsule 構造
- サブエージェント依頼文
- 成果物契約出力
- 未解決事項（ある場合のみ）
Source: tkosht/base — distributed by TomeVault.