intent-engineering

向 OpenClaw 代理添加机器可读的意图层。创建 INTENT.md（优化优先级、权衡、委托规则），通过 agent-context-loader 将其连接到子代理生成中，并确保每个子代理知道您正在优化什么 - 而不仅仅是要做什么。解决“Klarna 故障模式”：人工智能优化可衡量的指标而不是实际目标。当设置新的 OpenClaw 工作区、子代理不断做出错误的权衡时，或者当您想要明确控制成本/质量/速度优先级时，请使用。

# Intent Engineering

## The Problem

Without an intent layer, agents optimize for what's measurable (fast response, no errors) rather than what matters (your actual priorities). The Klarna failure: AI saved $60M and destroyed customer loyalty because it optimized resolution time, not relationships.

## What This Skill Installs

1. **`INTENT.md`** — YAML priority manifest at workspace root
2. **`lib/agent-context-loader.js`** — prepends intent summary to every subagent spawn
3. **Routing integration** — intent propagation flag in all routing decisions

## Installation

### Step 1 — Create INTENT.md

Copy `references/intent-template.md` to your workspace root as `INTENT.md` and edit:

```bash
cp $(dirname $0)/references/intent-template.md $OPENCLAW_WORKSPACE/INTENT.md
```

Or create it manually — see `references/intent-template.md` for the annotated schema.

### Step 2 — Install agent-context-loader

Copy the reference implementation to `lib/`:

```bash
cp $(dirname $0)/references/agent-context-loader-template.js $OPENCLAW_WORKSPACE/lib/agent-context-loader.js
```

Verify it runs:

```bash
node $OPENCLAW_WORKSPACE/lib/agent-context-loader.js $OPENCLAW_WORKSPACE
```

### Step 3 — Wire into spawn calls

In any subagent spawn, prepend the intent context to the task description:

```javascript
const { prepareAgentContext } = require('./lib/agent-context-loader');

const { context } = prepareAgentContext(taskType, workspaceRoot);
const fullTask = context ? context + '\n\n---\n\n' + originalTask : originalTask;

// Use fullTask as your subagent task description
```

`taskType` is a string describing the work (e.g. `"code_review"`, `"research"`, `"writing"`). The loader extracts relevant context from INTENT.md and recent memory automatically.

### Step 4 — Verify

Spawn a test subagent with a task that would normally trigger a tradeoff (cost vs quality, speed vs depth). Confirm the subagent's output reflects your priorities from INTENT.md.

## INTENT.md Structure

| Field | Purpose |
|---|---|
| `optimization_priority` | Ordered priorities: primary → never_sacrifice |
| `tradeoffs` | Explicit rules when objectives conflict |
| `model_tier_intent` | Which task types get which model tier |
| `delegation_intent` | When to delegate vs handle inline |
| `quality_intent` | Per-domain quality standards |

See `references/intent-template.md` for the full annotated template.

## How It Works

`prepareAgentContext()` reads INTENT.md fresh on every call, extracts a compact summary (≤200 chars), and prepends it to the spawn task. Subagents receive:

```
## Intent
Optimize for: user_value > honesty > cost. Never sacrifice: honesty, safety.
Delegate when blocking chat. Prefer depth for architecture/writing.
```

If INTENT.md is missing, a safe default is injected. The loader never throws — it degrades silently.

## References

- `references/intent-template.md` — Full annotated INTENT.md template with all fields
- `references/agent-context-loader-template.js` — Complete agent-context-loader.js implementation

---

## 中文说明

# 意图工程（Intent Engineering）

## 问题所在

如果没有意图层，代理会优化那些可衡量的指标（快速响应、无错误），而不是真正重要的东西（你的实际优先级）。Klarna 的失败案例：人工智能节省了 6000 万美元却摧毁了客户忠诚度，因为它优化的是问题解决时间，而非客户关系。

## 此技能安装的内容

1. **`INTENT.md`** — 位于工作区根目录的 YAML 优先级清单
2. **`lib/agent-context-loader.js`** — 在每次生成子代理时预先附加意图摘要
3. **路由集成** — 在所有路由决策中加入意图传播标志

## 安装

### 第 1 步 — 创建 INTENT.md

将 `references/intent-template.md` 复制到工作区根目录，命名为 `INTENT.md` 并进行编辑：

```bash
cp $(dirname $0)/references/intent-template.md $OPENCLAW_WORKSPACE/INTENT.md
```

或者手动创建它——参见 `references/intent-template.md` 中带注释的结构说明。

### 第 2 步 — 安装 agent-context-loader

将参考实现复制到 `lib/`：

```bash
cp $(dirname $0)/references/agent-context-loader-template.js $OPENCLAW_WORKSPACE/lib/agent-context-loader.js
```

验证它能运行：

```bash
node $OPENCLAW_WORKSPACE/lib/agent-context-loader.js $OPENCLAW_WORKSPACE
```

### 第 3 步 — 接入生成调用

在任何子代理生成中，将意图上下文预先附加到任务描述前：

```javascript
const { prepareAgentContext } = require('./lib/agent-context-loader');

const { context } = prepareAgentContext(taskType, workspaceRoot);
const fullTask = context ? context + '\n\n---\n\n' + originalTask : originalTask;

// Use fullTask as your subagent task description
```

`taskType` 是一个描述工作内容的字符串（例如 `"code_review"`、`"research"`、`"writing"`）。加载器会自动从 INTENT.md 和近期记忆中提取相关上下文。

### 第 4 步 — 验证

生成一个测试子代理，给它一个通常会触发权衡的任务（成本 vs 质量、速度 vs 深度）。确认子代理的输出反映了你在 INTENT.md 中设定的优先级。

## INTENT.md 结构

| 字段 | 用途 |
|---|---|
| `optimization_priority` | 有序优先级：primary → never_sacrifice |
| `tradeoffs` | 目标冲突时的明确规则 |
| `model_tier_intent` | 哪类任务使用哪个模型层级 |
| `delegation_intent` | 何时委托 vs 内联处理 |
| `quality_intent` | 各领域的质量标准 |

完整带注释的模板参见 `references/intent-template.md`。

## 工作原理

`prepareAgentContext()` 在每次调用时都重新读取 INTENT.md，提取一段紧凑摘要（≤200 字符），并将其预先附加到生成任务前。子代理收到的内容如下：

```
## Intent
Optimize for: user_value > honesty > cost. Never sacrifice: honesty, safety.
Delegate when blocking chat. Prefer depth for architecture/writing.
```

如果 INTENT.md 缺失，则注入一个安全的默认值。加载器从不抛出异常——它会静默降级。

## 参考资料

- `references/intent-template.md` — 包含所有字段、带注释的完整 INTENT.md 模板
- `references/agent-context-loader-template.js` — 完整的 agent-context-loader.js 实现