# Pua Loop

PUA Loop, guided iterative development with recurring checks, completion evidence, and...

- Repository: https://github.com/tanweai/pua (19789 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-09-09
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add tanweai/pua --skill pua-loop -g -a claude-code -y`
Codex: `npx skills add tanweai/pua --skill pua-loop -g -a codex -y`
Cursor: `npx skills add tanweai/pua --skill pua-loop -g -a cursor -y`
Gemini CLI: `npx skills add tanweai/pua --skill pua-loop -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add tanweai/pua`

## Description

PUA Loop, guided iterative development with recurring checks, completion evidence, and pause/abort markers. Use only when the user explicitly asks for loop/自动迭代 mode.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# PUA Loop, 自动迭代 + 门控协议 + PUA 质量引擎

> autoresearch 证明了：630 行 Python + Oracle 验证，一夜跑 100 个实验，每个实验的结果不可伪造。
> PUA Loop 借鉴同样的门控设计：**Claude 说"完成了"不算数，verify_command 说了才算。**

## 门控协议（Gate Protocol）

借鉴 autoresearch 的 5 个设计模式：

### 模式 1: Oracle Isolation（评估者隔离）

```
                    Claude 输出 <promise>LOOP_DONE</promise>
                                 │
                                 ▼
                    ┌─── Stop Hook (Oracle) ───┐
                    │                          │
                    │  运行 verify_command      │
                    │  （Claude 无法修改此命令）  │
                    │                          │
                    │  exit 0 ──→ ✅ 接受       │
                    │  exit ≠0 ──→ 🚫 拒绝      │
                    │    → 将验证输出喂回 Claude  │
                    │    → loop 继续             │
                    └──────────────────────────┘
```

**verify_command 由用户在启动时设定，嵌入在状态文件 frontmatter 中，Claude 无法修改。** 这是 autoresearch 中 "agent 不能修改评估函数" 原则的实现。

### 模式 2: 二阶 Gate

- **Phase 1 (in-prompt)**: Claude 自己跑 build/test，判断是否完成
- **Phase 2 (in-hook)**: Hook 独立运行 verify_command，确认或拒绝

两阶段分离。即使 Claude 在 Phase 1 自欺欺人，Phase 2 的 Oracle 会拦住。

### 模式 3: ASI（失败记忆）

每次迭代的结果追加到 `.claude/pua-loop-history.jsonl`：

```json
{"iteration":0,"status":"init","verify_command":"npm test","timestamp":"..."}
{"iteration":1,"status":"continue","timestamp":"..."}
{"iteration":2,"status":"promise_rejected","verify_exit":1,"rejections":1,"verify_tail":"3 tests failed","timestamp":"..."}
{"iteration":3,"status":"promise_rejected","verify_exit":1,"rejections":2,"verify_tail":"2 tests failed","timestamp":"..."}
{"iteration":4,"status":"complete","promise_rejections":2,"timestamp":"..."}
```

Git revert 会撤代码，但 history.jsonl 不受影响。Claude 每轮读取此文件，避免重复失败方案。

### 模式 4: Stall Detection（连败强制反思）

| promise_rejections | Hook 行为 |
|-------------------|-----------|
| 1-2 | 提醒："上次 promise 被 Oracle 拒绝" |
| 3-4 | REASSESS："重读验证输出，列 3 个不同假设" |
| 5+ | 强制转向："你在解决错误的问题。退回需求本身" |

### 模式 5: 无限迭代

The rest: https://github.com/tanweai/pua/blob/HEAD/skills/pua-loop/SKILL.md