skill-intent-contract

ホスト：Codex CLI — このスキルは Claude Code 向けに設計され、Codex 用に適応されています。 相互参照コマンドでは、/octo:* スラッシュコマンドではなく、Codex にインストールされているスキル名を使用します。 現在の Codex シェルとサブエージェントのツールを使用してください。現在のセッションで利用可能であることが確認できるまでは、プロバイダー、モデル、ホストのサブエージェントが利用可能だと主張しないでください。 ホストツールに相当するものについては、skills/blocks/codex-host-adapter.md を参照してください。

意図契約システム

目的

意図契約は、ユーザーの意図を永続的に記録し、次のことを実現します。

• ユーザーが達成しようとしていることを記録します
• 成功基準を事前に定めます
• 境界と制約を確立します
• ワークフロー全体を通じて引き継がれます
• 最終成果物を元の意図に照らして検証します

これにより、意図と成果の間のループを閉じます。

意図契約の構成

意図契約は、現在解決済みのプラン実行ディレクトリに session-intent.md として保存されます。scripts/plan-storage.sh を使用してそのディレクトリを作成または復元してください。.claude/ に単独の意図ファイルを書き込まないでください。

# Intent Contract

**Created**: [ISO timestamp]
**Workflow**: [discover/embrace/review/etc.]
**Status**: [active/validating/completed]

## Job Statement
What the user is trying to accomplish (JTBD framework).

[User's goal in plain language]

## Success Criteria

### Good Enough
- [Minimum viable success criterion 1]
- [Minimum viable success criterion 2]

### Exceptional
- [Excellence criterion 1]
- [Excellence criterion 2]

## Boundaries
What this should NOT be:
- [Boundary 1: What to avoid]
- [Boundary 2: What's out of scope]

## Context & Constraints

**Stakeholders**: [Who needs this to work for them]
**Existing Assets**: [What to build on]
**Timeline**: [Time constraints if any]
**Technical Constraints**: [Platform, language, dependencies]

## Clarifying Context
[Any answers from the 3-question pattern]

## Task Allocation
**Risk**: [low | intermediate | high]
**Initiative**: [human | AI | shared] — who starts and proposes
**Control**: [human | AI | shared] — who oversees execution as it runs
**Decision rights**: [human | AI] — who has final say on the outcome
**AI role**: [none | executor | collaborator | challenger]
**Execution disposition**: [AI-assisted | human-only | pending-user-decision]
**Escalation decision**: [not-needed | pending | user's recorded resolution]
**Resolved AUTONOMY_MODE**: [supervised | semi-autonomous | loop-until-approved | autonomous | not-applicable (contract-only sentinel)]

## Validation Checklist
- [ ] Meets "good enough" criteria
- [ ] Respects all boundaries
- [ ] Works for all stakeholders
- [ ] Builds on existing assets appropriately
- [ ] Allocation still fits what the task turned out to be

実装手順

意図契約を作成するタイミング

次の場合に意図契約を作成します。

• ユーザーが主要なワークフロー（/octo:embrace、/octo:discover、/octo:plan）を実行する
• ユーザーがタスクの「計画」または「目標設定」を明示的に依頼する
• ワークフローに複数のフェーズと検証が必要である

次の場合は作成しないでください。

• 簡単な単一アクションのコマンド
• 単純なファイルの読み取りや検索
• 会話形式の質問

ステップ 0：スコープを定める前に作業を割り振る

意図を記録する前に、これを実行してください。問うべきなのは、エージェントを使ってタスクをどう進めるかではなく、そもそも委任すべきかどうか、そして委任する場合は権限のどの部分を誰に割り当てるかです。フレームワーク：Afroogh、Varshney、D'Cruz（2025）、A Task-Driven Human-AI Collaboration（arXiv:2505.18422）。

リスクを分類します。 複雑さはすでに別の場所でスコア化されています。再計算するのではなく、scripts/lib/routing.sh の estimate_complexity と classify_cynefin に従ってください。リスクは別の軸であり、コードベースでは測定されないため、ここでは次の3つの質問に基づいて判断します。

• 不可逆性 — 影響を元に戻せますか。そのためのコストはどれくらいですか。
• 結果の重大性 — 安全、金銭、データ、ユーザーなど、重大なものが関わっていますか。
• 説明責任 — 結果について説明を求められる特定の人物がいますか。

リスク	判断基準
低	元に戻すことができ、重大な影響がなく、説明責任を負う特定の人物もいません。
中程度	元に戻すには相応のコストがかかるか、影響が不明確です。
高	元に戻せない、重大な影響がある、または説明責任を負う人物がいます。

3つの次元は個別に割り当てます。 これらは互いに独立しており、1つの軸として扱う誤りを防ぐことが、このステップの目的です。人は慣れない作業ではAIに主導権を容易に任せつつ、管理権と決定権は自分で保持します。単一の自律性スライダーでは、このような割り当てを表現できません。

• 主導権 — 誰が開始し、提案し、草案を作成するか。
• 管理権 — 実行中に誰が監督するか。
• 決定権 — 結果について誰が最終決定を下すか。

すべての結果を明示的に記録します。

リスク／複雑さ	主導権	管理権	決定権	AI の役割	実行の扱い	エスカレーションの判断	モード
低／低	AI	AI	AI	実行者	AI 支援	不要	autonomous
低／高	共同	人間	人間	協力者	AI 支援	不要	loop-until-approved
高／低	人間	人間	人間	実行者	AI 支援	不要	supervised
高／高	人間	人間	人間	批判者	AI 支援	不要	supervised

高／高の割り当てでは、敵対的な視点を取り入れます。人間が主導し、AIは人間自身のバイアスに対する意図的な抑止力として、提案された決定に異議を唱えます。高／低の作業では、AIは人間が直接承認した範囲内のアクションのみを実行できます。 逆転させるルール。 不確実性が最も高い中リスクの作業では、引用された証拠は AI を完全に避けるべきだと述べています —「ゲートキーパーとしても、セカンドオピニオンとしてもならない」。これは、中程度のリスクは中程度の関与を意味するという滑らかな直感と矛盾しており、また、完全な人間の自律が正当化されることはほとんどないという同じ論文のより広範な主張とも緊張関係にあります。その緊張は現実のものであり、未解決です。静かにどちらかの側を選ぶのではなく、それをユーザーに提示して判断を委ねてください。

設定に解決する。 ワークフローエンジンは 1 つの変数 AUTONOMY_MODE を読み取り、4 つの値を持ちます:

配分	AUTONOMY_MODE
人間が制御と決定権を保持し、各フェーズを承認する	supervised
AI が実行し、人間は障害と品質ゲートで呼び出される	semi-autonomous
AI が実行と反復を行い、人間が最終決定権を保持する	loop-until-approved
AI が 3 つすべてを保持する	autonomous

3 つの次元および解決されたモードを記録します。このマッピングは非可逆です。1 つの軸で 3 つの独立した配分を表すことはできないため、モードのみを保存する契約は、それが選ばれた理由を失います。その記録こそ、配分が誤っていたことが判明したときに、後からレビューする担当者が必要とするものです。

not-applicable は、人間のみの作業のための永続化された契約専用のセンチネルです。これは 5 番目のランタイム値ではなく、ワークフローエンジンに渡してはなりません。

中リスクの場合、Execution disposition: pending-user-decision を記録します。Escalation decision: pending を記録し、実行前に停止します。 ユーザーに、人間のみの対応か、特定の文書化された AI 配分かを選択するよう求めます。 その回答を記録し、それに一致するように Task Allocation フィールドを書き換え、続行する前に Escalation decision をユーザーの解決に変更します。人間のみの解決の場合、AI role: none と Resolved AUTONOMY_MODE: not-applicable を記録します。人間のみの not-applicable をワークフローエンジンに渡してはなりません。サポートされている人間のみの動作に解決し、その状態では AI 作業を実行しないでください。

文書化された AI 支援の解決の場合、すべての Task Allocation フィールドを記録します:

• 選択した配分からの Initiative、Control、Decision rights、AI role
• Execution disposition: AI-assisted
• Escalation decision: user's recorded resolution
• Resolved AUTONOMY_MODE: 上記の表を使用してマッピングされた、supervised、semi-autonomous、loop-until-approved、autonomous のいずれか 1 つ

選択したランタイムモードを検証し、その後のみ実行します。ランタイムは、自律的な動作をデフォルトとするのではなく、ワークフロー実行前に not-applicable およびすべての未知またはサポートされていないモードを拒否しなければなりません。

ステップ 1: 意図を捕捉する

ワークフローで 3 つの確認質問を行った後、ユーザーに以下を定義するよう促します:

AskUserQuestion({
  questions: [
    {
      question: "What are you ultimately trying to accomplish?",
      header: "Goal",
      multiSelect: false,
      options: [
        {label: "Let me describe it", description: "I'll write my own goal statement"},
        {label: "Make a decision", description: "Choose between options"},
        {label: "Create deliverable", description: "Build something specific"},
        {label: "Understand a problem", description: "Research and learn"}
      ]
    },
    {
      question: "What defines success for this?",
      header: "Success",
      multiSelect: true,
      options: [
        {label: "Clear recommendation", description: "Know what to do next"},
        {label: "Working implementation", description: "Code that functions"},
        {label: "Team alignment", description: "Everyone understands"},
        {label: "Problem solved", description: "Issue is resolved"}
      ]
    },
    {
      question: "What should this NOT be or do?",
      header: "Boundaries",
      multiSelect: true,
      options: [
        {label: "Over-engineered", description: "Keep it simple"},
        {label: "Incomplete", description: "Must be production-ready"},
        {label: "Disconnected", description: "Must fit our architecture"},
        {label: "Risky", description: "Avoid experimental approaches"}
      ]
    }
  ]
})

ユーザーが「Let me describe it」を選択した場合は、カスタムゴールを入力するためのテキストプロンプトでフォローアップします。

ステップ 2: 意図契約ファイルを作成する

一意の実行ディレクトリを解決し、Write ツールを使用してその session-intent.md を作成します:

PLAN_STORAGE="${CLAUDE_PLUGIN_ROOT:-${HOME}/.claude-octopus/plugin}/scripts/plan-storage.sh"
OCTO_PLAN_DIR="$("$PLAN_STORAGE" current "$PWD" 2>/dev/null || "$PLAN_STORAGE" create "$PWD")"
cat > "${OCTO_PLAN_DIR}/session-intent.md" <<EOF
# Intent Contract

**Created**: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
**Workflow**: ${WORKFLOW_NAME}
**Status**: active

## Job Statement
${USER_GOAL}

## Success Criteria

### Good Enough
${MIN_SUCCESS_CRITERIA}

### Exceptional
${EXCEPTIONAL_CRITERIA}

## Boundaries
What this should NOT be:
${BOUNDARIES}

## Context & Constraints

**Stakeholders**: ${STAKEHOLDERS}
**Timeline**: ${TIMELINE}

## Clarifying Context
${THREE_QUESTION_ANSWERS}

## Validation Checklist
- [ ] Meets "good enough" criteria
- [ ] Respects all boundaries
- [ ] Works for all stakeholders
EOF

ステップ 3: 実行中に参照する

ワークフロー全体を通じて、plan-storage.sh current "$PWD" で現在のプランディレクトリを復元し、その session-intent.md を定期的に読み取って、以下を行います:

• ユーザーのゴールと整合性を保つ
• 境界と一貫した意思決定を行う
• ステークホルダーを念頭に置く

重要な意思決定のポイントでは、明示的に次のように述べます:

Checking against intent contract: [reference specific criterion]

ステップ 4: 最後に検証する

ワークフローが完了したら、解決されたプランディレクトリの session-intent.md を読み取り、検証します:

検証プロセス:

1. 意図契約を読み取る

2. 各成功基準を確認する:

   • ✓ 達成 - どのように達成したかを説明する
   • ✗ 未達成 - その理由と必要なものを説明する
   • ~ 部分的に達成 - ギャップを説明する

3. 境界を確認する:

   • ✓ 遵守 - 確認する
   • ✗ 違反 - 何が起こったかを説明する

4. 検証レポートを生成する:

# Validation Report

## Success Criteria Check

### Good Enough Criteria
- [✓] Criterion 1: [How it was met]
- [✗] Criterion 2: [Why not met, what's needed]

### Exceptional Criteria
- [~] Criterion 1: [Partial progress explanation]

## Boundary Check
All boundaries respected: [Yes/No]
- Boundary 1: [✓/✗] [Explanation]

## Gaps & Next Steps
[If any criteria not met, list concrete next steps]

## Overall Assessment
[Summary: Does this fulfill the original intent?]

5. ユーザーに提示する:
   • 検証レポートを表示する
   • ギャップに対処したいかどうかを尋ねる
   • 意図契約のステータスを「completed」または「validating」に更新する

ステップ 5：インテント契約のステータスを更新する

解決済みの計画ディレクトリにある session-intent.md の Status フィールドを更新します。

• active → ワークフローの進行中
• validating → 基準に照らして確認中
• completed → すべての基準を満たし、境界を遵守
• incomplete → 一部の基準を満たしておらず、不足点を特定済み

ワークフローとの統合

ワークフローの導入

1. Ask 3 clarifying questions (scope, focus, autonomy)
2. Create intent contract
3. DISCOVER phase (reference intent)
4. DEFINE phase (reference intent)
5. DEVELOP phase (reference intent)
6. DELIVER phase (reference intent)
7. Validate against intent contract
8. Present validation report

ワークフローの探索

1. Ask 3 clarifying questions (depth, focus, output)
2. Create intent contract
3. Execute multi-provider research
4. Synthesize findings
5. Validate against intent contract
6. Present validation report

計画ワークフロー（今後）

1. Capture comprehensive intent
2. Create intent contract
3. Route to appropriate workflows
4. Execute custom sequence
5. Validate against intent contract
6. Present validation report

インテント契約の例

# Intent Contract

**Created**: 2026-01-21T15:30:00Z
**Workflow**: embrace
**Status**: active

## Job Statement
Build a user authentication system that our team can implement and maintain.

## Success Criteria

### Good Enough
- Team understands what to build
- Clear technical approach selected
- Security considerations documented
- Implementation plan with steps

### Exceptional
- Multiple authentication methods evaluated
- Security audit performed
- Code examples provided
- Integration tests included

## Boundaries
What this should NOT be:
- Over-engineered with unnecessary features
- Disconnected from our existing Node.js/Express stack
- Experimental or unproven technologies

## Context & Constraints

**Stakeholders**: Development team (5 engineers), Product manager
**Existing Assets**: Express.js API, PostgreSQL database
**Timeline**: Need to start implementation next sprint
**Technical Constraints**: Must work with Express.js, PostgreSQL

## Clarifying Context

**Scope**: Medium feature (multiple components)
**Focus Areas**: Security, Architecture design
**Autonomy**: Supervised (review after each phase)

## Validation Checklist
- [ ] Meets "good enough" criteria
- [ ] Respects all boundaries
- [ ] Works for all stakeholders
- [ ] Builds on existing assets appropriately

メリット

ユーザー向け：

• 事前に明確な期待値を設定
• 要件の見落としを防止
• 当初の目標に照らした検証
• クローズドループの説明責任

ワークフロー向け：

• 最適化の対象となる明確な成功基準
• ソリューションを制約する境界
• より良い判断のためのコンテキスト
• 検証フレームワークを組み込み

すぐに使用できます！ ワークフローで、永続的なインテント契約を作成し、それに照らして検証できるようになりました。