# declarative-openspec-loop

你提供「怎样算符合预期」的校验方式，Agent 按 OpenSpec 走 propose → apply → 校验，不通过就分析原因再迭代，直到通过。

## 什么时候使用

- 已经能说清目标，也有办法判断结果对不对，希望 Agent 自动做到通过为止。
- 会说「声明式编程」「按预期循环」「做到校验通过」。
- 不适合：还在选型、还没有校验手段、只想改一小处且自己盯着看。

## 安装

```bash
pouch add declarative-openspec-loop          # 当前项目
pouch add declarative-openspec-loop -g       # 全局
```

## 使用前准备

- 本机已安装 [openspec](https://openspec.dev/) CLI。
- 当前 Agent 已安装 OpenSpec 的三个子 skill：`openspec-explore`、`openspec-propose`、`openspec-apply-change`。
- 你必须给出校验方式，缺了 Agent 会先问，不会空跑。可用下面任意组合：
  - 校验命令，退出码 0 即通过，比如 `make test-one2`
  - 预期文档，里面有校验项表
  - 清单：日志关键字、输出文件、数值容差
  - 自由描述：Agent 会先归纳成可执行检查，向你确认后再跑

## 使用示例

```text
按声明式循环做：让登录失败时返回统一错误码。
校验：跑 pytest tests/test_login.py，全部 green 即通过。最多 3 轮。
```

```text
目标：拟合轮廓与 docs/tmp/expect_desc.md 一致。
校验：make test-one2，且日志覆盖文档「校验项」表全部 8 项。
```

## Agent 会做什么

1. 记下 change 名称和校验方式，写到 `docs/tmp/<change>/expectation.md`。
2. 必要时先探索；然后 propose 出 proposal / design / tasks，每个任务尽量带验收。
3. apply 实现，再跑你给的校验。
4. 失败按原因分级：小 bug 直接修；任务遗漏就补 tasks；方向错了才改设计。默认最多 5 轮（你可改上限）。同一错误连续 2 轮会停下来问你。
5. 通过后给出变更摘要和思路，过程记录留在 `docs/tmp/<change>/`。

不会在没校验方式时开跑，也不会到上限后自己放弃或无限重试。

## 如何判断完成

- 你指定的校验命令退出码 0，或校验项全部满足。
- Agent 给出变更文件列表和思路。
- `docs/tmp/<change>/` 里有 `expectation.md`、每轮 `iteration_*.md` 和校验原始输出。
- 到上限或反复失败时停下，并说明当前进度和未通过项，而不是假装完成。