skill-intent-contract

宿主：Codex CLI — 此技能为 Claude Code 设计，后适配到 Codex。 交叉引用命令在 Codex 中使用已安装的技能名称，而非 /octo:* 斜杠命令。 使用当前 Codex shell 和子 Agent 工具。在当前会话尚未提供相应能力之前，不要声称某个提供方、模型或宿主子 Agent 可用。 宿主工具的对应关系请参阅 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：先分配工作，再界定范围

在记录意图之前运行此步骤。关键并非如何让多个 Agent 执行任务，而是是否应当委派；如果应当委派，权限应如何分配。框架：Afroogh、Varshney 和 D'Cruz（2025），A Task-Driven Human-AI Collaboration（arXiv:2505.18422）。

评估风险。 复杂度已在其他地方评分——应依据 scripts/lib/routing.sh 中的 estimate_complexity 和 classify_cynefin，而非重新评估。风险是另一个维度，代码库中没有任何机制对其进行衡量，因此应在此通过以下三个问题进行判断：

• 不可逆性——影响能否撤销？撤销需要付出多大代价？
• 后果——是否涉及重大利害关系：安全、金钱、数据或用户？
• 问责——是否有特定人员需要为结果负责？

风险	判断标准
低	可逆、没有重大后果、无需指定人员负责。
中等	只有付出实际代价才能撤销，或后果不明确。
高	不可逆、后果重大，或必须有人负责。

分别分配这三个维度。 它们彼此独立，把它们视为一个维度正是此步骤要避免的错误。面对陌生的工作，人们往往愿意让 AI 主导（主动权），同时保留控制权和决策权——而单一的自主性滑块无法表达这种分配。

• 主动权——由谁发起、提出方案和起草内容。
• 控制权——由谁在执行过程中监督。
• 决策权——由谁对结果拥有最终决定权。

明确记录每项结果：

风险 / 复杂度	主动权	控制权	决策权	AI 角色	执行安排	升级决策	模式
低 / 低	AI	AI	AI	执行者	AI 辅助	无需升级	autonomous
低 / 高	共同	人类	人类	协作者	AI 辅助	无需升级	loop-until-approved
高 / 低	人类	人类	人类	执行者	AI 辅助	无需升级	supervised
高 / 高	人类	人类	人类	挑战者	AI 辅助	无需升级	supervised

高风险 / 高复杂度的分配具有对抗性：由人类主导，同时让 AI 质疑拟议的决策，以有意制衡人类自身的偏见。对于高风险 / 低复杂度的工作，AI 只能执行人类直接批准的、有明确边界的操作。 反转直觉的规则。 对于中等风险的工作，不确定性最高，引用的证据建议完全避免使用 AI——“既不要将其作为把关者，也不要将其作为第二意见”。这与“中等风险意味着中等程度参与”这一顺畅直觉相矛盾，也与同一篇论文更广泛的主张——完全由人自主决策很少有正当理由——存在张力。这种张力确实存在，且尚未解决；应向用户指出这一点，让他们自行决定，而不是悄悄选边站。

确定一种设置。 工作流引擎读取一个变量 AUTONOMY_MODE，它有四个值：

分配方式	AUTONOMY_MODE
人类掌控控制权和决策权，并审批每个阶段	supervised
AI 执行；出现故障或到达质量关卡时再请人类介入	semi-autonomous
AI 执行并反复迭代；人类掌握最终决策权	loop-until-approved
AI 掌握这三项权力	autonomous

记录这三个维度，并且记录最终确定的模式。这种映射会丢失信息：单一轴无法表示三个独立分配，因此契约若只存储模式，就会丢失选择该模式的原因。当分配后来被证明有误时，后续审查者需要查看这份记录。

not-applicable 是仅供契约使用、需要持久化的人类独立处理哨兵值；它不是第五种运行时值，不得传递给工作流引擎。

对于中等风险，记录 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 之一，并根据上表映射

验证所选运行时模式后，才可执行。运行时必须在工作流执行前拒绝 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"}
      ]
    }
  ]
})

如果用户选择“让我描述”，则继续提示用户用文本描述其自定义目标。

步骤 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 → 未满足部分标准，已找出差距

与工作流集成

Embrace 工作流

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

Discover 工作流

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

Plan 工作流（未来）

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

优势

对用户：

• 提前明确预期
• 不会遗漏需求
• 根据原始目标进行验证
• 建立闭环问责机制

对工作流：

• 明确可供优化的成功标准
• 通过边界约束解决方案
• 为更好的决策提供背景信息
• 内置验证框架

可以开始使用了！ 工作流现在可以创建持久化意图契约，并据此进行验证。