Agent skill

PUA Loop

by tanweai in tanweai/pua

Runs an unattended iterate-until-verified loop in which a user-set verify command, not the agent's own claim, decides when the task is finished.

MITAuto-check passedAgent Workflows

SKILL.md written in Chinese; this summary is our English description.

Install PUA Loop

skills CLI
$ npx skills add tanweai/pua --skill pua-loop -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install tanweai/pua pua-loop --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/tanweai/pua.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/pua-loop .claude/skills/pua-loop && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
pua-loop
GitHub stars
20k
Used in
1 other repo
Token cost
~1.1k tokens
SKILL.md length
323 words
Files
1
Skills in repo
28
Repo updated
First seen
Licence
MIT

At a glance

Runs an unattended iterate-until-verified loop in which a user-set verify command, not the agent's own claim, decides when the task is finished.

  • Works in 3 steps: 启动 PUA Loop → 告知用户 → 开始执行任务
  • Running a long autonomous fix-until-tests-pass loop when you ask for it explicitly
  • SKILL.md covers 门控协议(Gate Protocol), 核心规则, 启动方式 and 迭代压力升级, plus 3 more sections
  • Calls claude, bash and npm

What it does

The loop borrows a gating design from autoresearch: the agent outputs a completion promise, but a verify command set by you at start-up and stored in the state file's frontmatter is run independently by a hook, and only its result counts. The agent cannot edit that command. When the task implies a check (npm test, a build, a health-check curl), the skill adds the verify option itself; if unsure, it falls back to trusting the agent.

Each iteration is appended to a history file under .claude, so a git revert does not erase the record of failed attempts, and the agent reads it before each round. Repeated rejections trigger escalating prompts: a reminder at first, a reassessment with several fresh hypotheses after more failures, and a forced change of direction after many. There is no iteration cap by default; the loop ends on a verified promise, a manual abort marker, a configured maximum or Ctrl+C. Inside it the agent may not ask you questions or give up, and it follows the core pua skill's behavior rules.

When your agent uses it

  • Running a long autonomous fix-until-tests-pass loop when you ask for it explicitly
  • Making task completion depend on an independent verify command
  • Keeping a record of failed attempts that survives git reverts

Example prompts

  • “Start a PUA loop to fix all failing tests, verified by npm test.”
  • “Run an autonomous loop to build the REST API and check it against the health endpoint with curl.”
  • “Cancel the current PUA loop.”

Requirements

  • Claude Code with the pua plugin and its setup script
  • A shell command that can verify completion, such as npm test

Workflow steps

3 steps, taken from the step headings in SKILL.md.

  1. 启动 PUA Loop
  2. 告知用户
  3. 开始执行任务

What it can do on your machine

Read from SKILL.md and the folder at commit e6e6cd2. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • claude
    • bash
    • npm
    • cargo

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use npm, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

PUA Loop loads about 1.1k tokens when it runs. Until then it costs about 44 tokens; SKILL.md has 323 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~44
When it runs · the whole SKILL.md, loaded when a task matches
~1.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from tanweai/pua at commit e6e6cd2, republished under its MIT licence (© tanweai). 323 words, ~1,146 tokens.

Download SKILL.mdSave it as .claude/skills/pua-loop/SKILL.md (or your agent's skills folder).
name
pua-loop
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.
license
MIT

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_rejectionsHook 行为
1-2提醒:"上次 promise 被 Oracle 拒绝"
3-4REASSESS:"重读验证输出,列 3 个不同假设"
5+强制转向:"你在解决错误的问题。退回需求本身"
模式 5: 无限迭代

默认 max_iterations: 0(无限)。没有人为上限。循环永远不会因为"跑了太多轮"而停止——只有以下条件能终止:

  1. <promise> 被 Oracle 验证通过
  2. <loop-abort> 人工终止信号
  3. max_iterations 达到(如果用户设定了)
  4. 用户 Ctrl+C

核心规则

  1. 加载 pua:pua 核心 skill 的全部行为协议 — 三条红线、方法论、压力升级照常执行
  2. 禁止调用 AskUserQuestion — loop 模式下不打断用户,所有决策自主完成
  3. 禁止说"我无法解决" — 在 loop 里没有退出权,穷尽一切才能输出完成信号
  4. 每次迭代:读 history.jsonl → git log → 检查上次改动 → 执行 → 验证 → repeat

启动方式

用户输入 /pua:pua-loop "任务描述" 时,执行以下流程:

Step 1: 启动 PUA Loop

运行 setup 脚本:

bash
bash "${CLAUDE_PLUGIN_ROOT}/scripts/setup-pua-loop.sh" "$ARGUMENTS" --completion-promise "LOOP_DONE"

重要:如果用户提供了可验证的命令(如 npm test、cargo build、curl),自动追加 --verify '命令'。例如:

  • 用户说 "Fix all tests" → --verify 'npm test'
  • 用户说 "Build a REST API" → --verify 'curl -sf http://localhost:3000/health'
  • 用户说 "Optimize bundle size" → 无明确 verify,不追加

如果任务描述中能推断出验证命令,主动追加 --verify。如果不确定,不追加(退回 honor system)。

Step 2: 告知用户

输出:

▎ [PUA Loop] 自动迭代模式启动。无上限,跑到 Oracle 验证通过为止。
▎ 完成条件:<promise>LOOP_DONE</promise>(Oracle 独立验证)
▎ 取消方式:Ctrl+C / /cancel-pua-loop
▎ 因为信任所以简单——但 Oracle 不信任你。
Step 3: 开始执行任务

按 PUA 核心 skill 的行为协议执行。

迭代压力升级

迭代轮次行为要求
1-3稳步推进,建立 baseline
4-7换方案,别原地打转
8-15git log + history.jsonl 回顾,分析根因
16-30穷尽了吗?git diff 确认没在重复
31-50停下来重新审视根因,用完全不同的思路
51-100退回去从需求本身重新质疑
100+诚实评估:如果真的不可能,<loop-abort>

完成条件

输出 <promise>LOOP_DONE</promise> 前,必须满足:

  1. 任务的核心功能已实现
  2. 自己先运行验证命令确认通过(Phase 1)
  3. 知道 Oracle 会独立再跑一遍验证(Phase 2)
  4. 同类问题已扫描

如果 Oracle 拒绝了你的 promise:

  1. 读取 hook 返回的验证输出
  2. 修复验证失败的原因
  3. 再次自己运行验证确认通过
  4. 再输出 <promise>

人工介入信号

<loop-abort> — 终止

不可能完成时使用(需外部权限、根本性需求变更)。删除状态文件,loop 终止。

<loop-pause> — 暂停

需要用户补全配置时使用。状态保留,新会话自动恢复。 输出前先写进度到 .claude/pua-loop-context.md。

禁止
  • 不要用 <loop-abort> 逃避困难——只有真正无法自动化才用
  • 不要因为 Oracle 拒绝了就 abort——修复验证问题

与 autoresearch 的关系

维度karpathy/autoresearchPUA Loop
Oracleevaluate_bpb() 物理隔离verify_command 在 frontmatter,Claude 不可修改
Gate 层数1层(metric only)2层(Claude 自验 + hook Oracle)
失败记忆results.tsvpua-loop-history.jsonl(ASI 模式)
Stall 检测无promise_rejections 计数 + 强制 REASSESS
回滚git reset --hardPUA 方法论切换(不回滚,换方向)
终止NEVER STOPNEVER STOP(Oracle 验证通过除外)
质量引擎无PUA 三条红线 + 压力升级

© tanweai, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/pua-loop of tanweai/pua.

Open the folder on GitHubat commit e6e6cd2

Used in 1 other repository

We found 1 copy of this SKILL.md (exact, near-identical or edited) in other folders, from 1 other GitHub owner. This page covers the copy in tanweai/pua, which our catalogue first saw on October 7, 2026.

Compare with similar skills

PUA Loop next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

PUA Loop compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
PUA Loop this skilltanweai/pua20k1 repos~1.1kAutomated safety check: PassMIT
Flowguard Task Guardmajiayu000/spellbook286—~2.1kAutomated safety check: PassMIT
Show Me Your Work Decision Logcursor/plugins10k9 repos~1.6kAutomated safety check: PassNone
Loop Until Verifiedjtaroreh/agystack108—~607Automated safety check: PassMIT
ULW Loopcode-yeongyu/oh-my-openagent70k—~3.2kAutomated safety check: PassCustom licence
Superloopy Evidence Loopbeefiker/superloopy1111 repos~5.9kAutomated safety check: PassMIT

Similar skills

  • Flowguard Task Guard

    majiayu000/spellbook

    Single entry point that routes long or ambiguous agent tasks, checks live state, bounds autonomous loops and leaves a resumable handoff.

    286 GitHub stars~2.1k tokensUpdated today
    Agent WorkflowsAuto-check passed
  • Official

    Keeps a TSV decision log for long or unattended agent runs, one row per decision with what, why, evidence and result, so a reviewer can check the work later.

    10k GitHub starsUsed in 9 repos~1.6k tokens
    Agent WorkflowsAuto-check passed
  • Loop Until Verified

    jtaroreh/agystack

    Runs an iterative verification loop on Google Antigravity: make one edit, run a test command, and reschedule until the command passes or the iteration budget runs out.

    108 GitHub stars~607 tokensUpdated 6 days ago
    Agent WorkflowsAuto-check passed
  • ULW Loop

    code-yeongyu/oh-my-openagent

    Runs a long task as a checkpointed goal loop: it creates goals, mirrors each step into a todo list, gathers evidence per criterion and lands every goal before the next.

    70k GitHub stars~3.2k tokensUpdated today
    Agent WorkflowsAuto-check passed
  • Superloopy Evidence Loop

    beefiker/superloopy

    Runs a light task loop where each goal criterion passes only when a real evidence artifact exists, with progress stored in a `.superloopy` folder.

    111 GitHub starsUsed in 1 repo~5.9k tokens
    Agent WorkflowsAuto-check passed
  • Goal Objective Drafter

    QwenLM/qwen-code

    Turns a vague intention into a /goal objective with one outcome, numbered yes-or-no checks, guardrails, a budget and a block protocol, without starting the work.

    28k GitHub stars~3.5k tokensUpdated today
    Agent WorkflowsAuto-check passed

More from tanweai/pua

All 28 skills in this repo
  • Adds short, pointed workplace reminders drawn from two Chinese essays on corporate culture, nudging the agent to prove results with evidence instead of polished reports.

    20k GitHub stars~556 tokensUpdated 29 days ago
    Auto-check passed
  • Pushes an agent to exhaust every option, investigate before asking and take initiative beyond the literal request, instead of giving up or waiting passively.

    20k GitHub starsUsed in 2 repos~6.9k tokens
    Auto-check passed
  • Pushes an agent to keep verifying and changing approach after repeated failures, using a diagnosis line, evidence-based completion and confirmation before risky edits.

    20k GitHub stars~502 tokensUpdated 29 days ago
    Auto-check passed
  • Pushes an agent that keeps failing or gives up to exhaust every option, using harsh corporate-pressure wording, a diagnosis line and a proactivity checklist.

    20k GitHub stars~3.3k tokensUpdated 29 days ago
    Auto-check passed
  • Pushes an agent that keeps failing, gives up or claims unverified success into a diagnosis, evidence and verification loop, with a Pi extension for persistent mode.

    20k GitHub stars~569 tokensUpdated 29 days ago
    Auto-check passed
  • An instruction-only discipline for Trae that forces evidence-based work when an agent keeps failing, gives up or declares a task finished without proof.

    20k GitHub stars~878 tokensUpdated 29 days ago
    Auto-check passed

Questions about PUA Loop

What does PUA Loop do?

Runs an unattended iterate-until-verified loop in which a user-set verify command, not the agent's own claim, decides when the task is finished. The loop borrows a gating design from autoresearch: the agent outputs a completion promise, but a verify command set by you at start-up and stored in the state file's frontmatter is run independently by a hook, and only its result counts. The agent cannot edit that command.

When should I use PUA Loop?

PUA Loop fits situations like: running a long autonomous fix-until-tests-pass loop when you ask for it explicitly; making task completion depend on an independent verify command; keeping a record of failed attempts that survives git reverts.

How do I install PUA Loop in Claude Code?

Run `npx skills add tanweai/pua --skill pua-loop -a claude-code`. Or copy the skill folder (skills/pua-loop in tanweai/pua) into .claude/skills/pua-loop in your project. Claude Code loads it when a task matches its description.

How do I install PUA Loop in Codex?

Run `npx skills add tanweai/pua --skill pua-loop -a codex`. Or copy the skill folder (skills/pua-loop in tanweai/pua) into .agents/skills/pua-loop in your project. Codex loads it when a task matches its description.

Can I use PUA Loop in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add tanweai/pua --skill pua-loop -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/pua-loop, .gemini/skills/pua-loop, .github/skills/pua-loop and .opencode/skills/pua-loop in your project.

What does PUA Loop need to run?

Going by SKILL.md and its folder, PUA Loop needs the command-line tools its instructions call (claude, bash, npm and cargo). Our summary lists: Claude Code with the pua plugin and its setup script; A shell command that can verify completion, such as npm test.

Does PUA Loop access the network?

SKILL.md contains no URLs. Its commands use npm, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is PUA Loop safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does PUA Loop use?

PUA Loop is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does PUA Loop use?

About 1.1k tokens (SKILL.md is roughly 4.6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to PUA Loop?

Skills that share tags, products or a category with PUA Loop: Flowguard Task Guard (majiayu000/spellbook, 286 stars), Show Me Your Work Decision Log (cursor/plugins, 10k stars), Loop Until Verified (jtaroreh/agystack, 108 stars) and ULW Loop (code-yeongyu/oh-my-openagent, 70k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains PUA Loop?

tanweai (a GitHub user) maintains it in tanweai/pua, which has 19,708 GitHub stars. The repository holds 28 skills in this directory. The repository was last updated on September 9, 2026.

Source: tanweai/pua on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.