# AGENTS.md - Your Workspace

This folder is home. Treat it that way.

## Cache Stability ⚡

> **ALL files in this workspace are ABOVE the OpenClaw prompt cache boundary.**
> Every edit invalidates the DeepSeek KV cache prefix → cache MISS → full token cost.
> Prefer writing to `memory/daily/` or `memory/vault.md` (NOT injected into context).
> Only edit above-boundary files for critical corrections.

## Session Startup

Use runtime-provided startup context first. Do not reread startup files unless explicitly asked, context is missing, or you need a deeper follow-up.

---

## Execution Protocol — Planning Layer 🔵

> **完整协议文档（§0-7 + Learning Loop + Context Budget）: `docs/AGENTS-PROTOCOL-FULL.md`**
> 以下为规则摘要。详细规则、表格、代码示例、Checklist → 读完整文档。

### 0. Complexity Classification

**简单任务 → 直接执行**（单文件/单命令/纯查询/对话）
**复杂任务 → 必须用 Task Tree**（3+文件/多步骤/跨项目/新功能/bug分析/预估>45min）
**不确定 → 视为复杂。** if uncertain → treat as Complex

详见 `docs/AGENTS-PROTOCOL-FULL.md` §0。

### 1. Task Tree Construction

复杂任务必须先建 Task Tree（执行树，非功能树）。含 depends_on、并行分组、注入风险。质量门见完整文档 §1f。

详见 `docs/AGENTS-PROTOCOL-FULL.md` §1。

#### 1f. Task Tree Quality Gate
详见 `docs/AGENTS-PROTOCOL-FULL.md` §1f（7 checks: Root/Orphan/Circular/XL/Serial/Risks/Human-dep）。

### 2. Planning Protocol

```
## PLAN
### Goal / Subtasks / Risks / Verification Strategy
```

详见 `docs/AGENTS-PROTOCOL-FULL.md` §2。

### 3. Pre-flight Check

#### 3a. Dependency Scan
FK/imports/types/blast radius → `docs/AGENTS-PROTOCOL-FULL.md` §3a

#### 3b. Learning Context Injector
3 次搜索（反射/最佳实践/Playbook）→ `docs/AGENTS-PROTOCOL-FULL.md` §3b

#### 3c. Domain Checklist Injection
SQL/JS/Next.js/Backend/Generator/Release → `docs/AGENTS-PROTOCOL-FULL.md` §3c

### 4. Failure Replanning Protocol

局部失败→修复继续。结构失败→REPLAN。同错3次→暂停问用户。修复后必查 Auto-Capture（§7）。

详见 `docs/AGENTS-PROTOCOL-FULL.md` §4。

### 5. Verification Protocol

Build/Tests/Lint/Regression/Manual 全检。完成后必须通过 Pre-flight Compliance Gate。

详见 `docs/AGENTS-PROTOCOL-FULL.md` §5。

### 6. Governance Compliance 🔒

- 状态机/心跳/blocker/replan/健康评分/自动停止 → `GOVERNANCE.md`
- 多项目管理 → `PORTFOLIO.md`
- Governance Quality Gate 在输出前必须运行（`GOVERNANCE.md` §9）

### 7. Auto-Capture Trigger

失败后必查 T1-T7 触发条件（build/test/lint 失败、耗时>30min、同类错误再现、路径不匹配、运行时崩溃）。Reflection 必须含 7 字段。详见 `docs/AGENTS-PROTOCOL-FULL.md` §7。

---

## Learning Loop 🔄

**晋升路径：** 反射(1次) → 模式(2次) → 最佳实践(3次) → 清单(4次) → Hard Rule(5次)
**存储：** `reflections/` → `patterns/` → `docs/AGENTS-PROTOCOL-FULL.md` §3c

详见 `docs/AGENTS-PROTOCOL-FULL.md` Learning Loop 章节。

Promotion Rules: 1st → Reflection, 2nd → Pattern, 3rd → Best Practice, 4th → Checklist, 5th → Hard Rule

---

## Agent Package Context Budget ⚠️ HARD RULE

| Size | Token Budget | 读文件 | 改文件 | 新代码 |
|------|-------------|--------|--------|--------|
| Small | ≤30K | ≤3 | ≤2 | ≤300行 |
| Medium | ≤80K | ≤8 | ≤5 | ≤800行 |
| Large | ≤200K | ≤15 | ≤10 | ≤1500行 |
| XL | ❌ 禁止 | — | — | — |

每次分发 Agent Package 前必须声明 Context Budget。Input Size Pre-check 必须执行。
详见 `docs/AGENTS-PROTOCOL-FULL.md`。

### 7. Auto-Capture Trigger

失败后必查 T1-T7 触发条件（build/test/lint 失败、耗时>30min、同类错误再现、路径不匹配、运行时崩溃）。Reflection 必须含 7 字段。
Injected Risks: 每个任务必须注入学习上下文中的风险。详见 `docs/AGENTS-PROTOCOL-FULL.md` §7。