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.
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.
SKILL.md written in Chinese; this summary is our English description.
$ npx skills add tanweai/pua --skill pua-loop -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install tanweai/pua pua-loop --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ 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-srcUse ~/.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/
Install the "pua-loop" agent skill from https://github.com/tanweai/pua/tree/main/skills/pua-loop into .claude/skills/pua-loop/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "pua-loop", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/tanweai/pua/tree/main/skills/pua-loopType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add tanweai/pua --skill pua-loop -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install tanweai/pua pua-loop --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/tanweai/pua.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/pua-loop .agents/skills/pua-loop && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "pua-loop" agent skill from https://github.com/tanweai/pua/tree/main/skills/pua-loop into .agents/skills/pua-loop/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "pua-loop", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add tanweai/pua --skill pua-loop -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install tanweai/pua pua-loop --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/tanweai/pua.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/pua-loop .cursor/skills/pua-loop && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "pua-loop" agent skill from https://github.com/tanweai/pua/tree/main/skills/pua-loop into .cursor/skills/pua-loop/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "pua-loop", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/tanweai/pua.git --path skills/pua-loop--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add tanweai/pua --skill pua-loop -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install tanweai/pua pua-loop --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/tanweai/pua.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/pua-loop .gemini/skills/pua-loop && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "pua-loop" agent skill from https://github.com/tanweai/pua/tree/main/skills/pua-loop into .gemini/skills/pua-loop/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "pua-loop", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install tanweai/pua pua-loopInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add tanweai/pua --skill pua-loop -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/tanweai/pua.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/pua-loop .github/skills/pua-loop && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "pua-loop" agent skill from https://github.com/tanweai/pua/tree/main/skills/pua-loop into .github/skills/pua-loop/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "pua-loop", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add tanweai/pua --skill pua-loop -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install tanweai/pua pua-loop --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/tanweai/pua.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/pua-loop .opencode/skills/pua-loop && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "pua-loop" agent skill from https://github.com/tanweai/pua/tree/main/skills/pua-loop into .opencode/skills/pua-loop/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "pua-loop", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
pua-loopRuns 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 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.
3 steps, taken from the step headings in SKILL.md.
Read from SKILL.md and the folder at commit e6e6cd2. It shows what the files ask for, not the result of running them.
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.
Shell commands in SKILL.md call:
claudebashnpmcargoFrom the folder's file list and the shell code blocks in SKILL.md.
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.
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
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.
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.
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.
The full file from tanweai/pua at commit e6e6cd2, republished under its MIT licence (© tanweai). 323 words, ~1,146 tokens.
.claude/skills/pua-loop/SKILL.md (or your agent's skills folder).autoresearch 证明了:630 行 Python + Oracle 验证,一夜跑 100 个实验,每个实验的结果不可伪造。 PUA Loop 借鉴同样的门控设计:Claude 说"完成了"不算数,verify_command 说了才算。
借鉴 autoresearch 的 5 个设计模式:
Claude 输出 <promise>LOOP_DONE</promise>
│
▼
┌─── Stop Hook (Oracle) ───┐
│ │
│ 运行 verify_command │
│ (Claude 无法修改此命令) │
│ │
│ exit 0 ──→ ✅ 接受 │
│ exit ≠0 ──→ 🚫 拒绝 │
│ → 将验证输出喂回 Claude │
│ → loop 继续 │
└──────────────────────────┘verify_command 由用户在启动时设定,嵌入在状态文件 frontmatter 中,Claude 无法修改。 这是 autoresearch 中 "agent 不能修改评估函数" 原则的实现。
两阶段分离。即使 Claude 在 Phase 1 自欺欺人,Phase 2 的 Oracle 会拦住。
每次迭代的结果追加到 .claude/pua-loop-history.jsonl:
{"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 每轮读取此文件,避免重复失败方案。
| promise_rejections | Hook 行为 |
|---|---|
| 1-2 | 提醒:"上次 promise 被 Oracle 拒绝" |
| 3-4 | REASSESS:"重读验证输出,列 3 个不同假设" |
| 5+ | 强制转向:"你在解决错误的问题。退回需求本身" |
默认 max_iterations: 0(无限)。没有人为上限。循环永远不会因为"跑了太多轮"而停止——只有以下条件能终止:
<promise> 被 Oracle 验证通过<loop-abort> 人工终止信号max_iterations 达到(如果用户设定了)pua:pua 核心 skill 的全部行为协议 — 三条红线、方法论、压力升级照常执行用户输入 /pua:pua-loop "任务描述" 时,执行以下流程:
运行 setup 脚本:
bash "${CLAUDE_PLUGIN_ROOT}/scripts/setup-pua-loop.sh" "$ARGUMENTS" --completion-promise "LOOP_DONE"重要:如果用户提供了可验证的命令(如 npm test、cargo build、curl),自动追加 --verify '命令'。例如:
--verify 'npm test'--verify 'curl -sf http://localhost:3000/health'如果任务描述中能推断出验证命令,主动追加 --verify。如果不确定,不追加(退回 honor system)。
输出:
▎ [PUA Loop] 自动迭代模式启动。无上限,跑到 Oracle 验证通过为止。
▎ 完成条件:<promise>LOOP_DONE</promise>(Oracle 独立验证)
▎ 取消方式:Ctrl+C / /cancel-pua-loop
▎ 因为信任所以简单——但 Oracle 不信任你。按 PUA 核心 skill 的行为协议执行。
| 迭代轮次 | 行为要求 |
|---|---|
| 1-3 | 稳步推进,建立 baseline |
| 4-7 | 换方案,别原地打转 |
| 8-15 | git log + history.jsonl 回顾,分析根因 |
| 16-30 | 穷尽了吗?git diff 确认没在重复 |
| 31-50 | 停下来重新审视根因,用完全不同的思路 |
| 51-100 | 退回去从需求本身重新质疑 |
| 100+ | 诚实评估:如果真的不可能,<loop-abort> |
输出 <promise>LOOP_DONE</promise> 前,必须满足:
如果 Oracle 拒绝了你的 promise:
<promise><loop-abort> — 终止不可能完成时使用(需外部权限、根本性需求变更)。删除状态文件,loop 终止。
<loop-pause> — 暂停需要用户补全配置时使用。状态保留,新会话自动恢复。
输出前先写进度到 .claude/pua-loop-context.md。
<loop-abort> 逃避困难——只有真正无法自动化才用| 维度 | karpathy/autoresearch | PUA Loop |
|---|---|---|
| Oracle | evaluate_bpb() 物理隔离 | verify_command 在 frontmatter,Claude 不可修改 |
| Gate 层数 | 1层(metric only) | 2层(Claude 自验 + hook Oracle) |
| 失败记忆 | results.tsv | pua-loop-history.jsonl(ASI 模式) |
| Stall 检测 | 无 | promise_rejections 计数 + 强制 REASSESS |
| 回滚 | git reset --hard | PUA 方法论切换(不回滚,换方向) |
| 终止 | NEVER STOP | NEVER 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
Just SKILL.md in skills/pua-loop of tanweai/pua.
Open the folder on GitHubat commit e6e6cd2
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.
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.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| PUA Loop this skilltanweai/pua | 20k | 1 repos | ~1.1k | Automated safety check: Pass | MIT | |
| Flowguard Task Guardmajiayu000/spellbook | 286 | — | ~2.1k | Automated safety check: Pass | MIT | |
| Show Me Your Work Decision Logcursor/plugins | 10k | 9 repos | ~1.6k | Automated safety check: Pass | None | |
| Loop Until Verifiedjtaroreh/agystack | 108 | — | ~607 | Automated safety check: Pass | MIT | |
| ULW Loopcode-yeongyu/oh-my-openagent | 70k | — | ~3.2k | Automated safety check: Pass | Custom licence | |
| Superloopy Evidence Loopbeefiker/superloopy | 111 | 1 repos | ~5.9k | Automated safety check: Pass | MIT |
majiayu000/spellbook
Single entry point that routes long or ambiguous agent tasks, checks live state, bounds autonomous loops and leaves a resumable handoff.
cursor/plugins
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.
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.
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.
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.
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.
tanweai/pua
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.
tanweai/pua
Pushes an agent to exhaust every option, investigate before asking and take initiative beyond the literal request, instead of giving up or waiting passively.
tanweai/pua
Pushes an agent to keep verifying and changing approach after repeated failures, using a diagnosis line, evidence-based completion and confirmation before risky edits.
tanweai/pua
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.
tanweai/pua
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.
tanweai/pua
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.
Categories
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.