DOCSEARCHbyAlgolia
Submit Docs

PUA AI Coding Agent Skill Plugin

repository·main·Indexed 12 days ago

https://github.com/tanweai/pua

An AI Coding Agent skill plugin that uses corporate performance management rhetoric (PUA/PIP) to prevent lazy patterns and force agents to exhaust all possible solutions. It features a pressure escalation system (L0-L4), a 'four-power separation' governance boundary, and specialized modes like Tech Lead (/pua:p9) and Auto-iteration (/pua:pua-loop). Supported agents include Claude Code, Cursor, GitHub Copilot, pi coding agent, and others.

Tokens
139K
Snippets
206
Records
564
Agent score
95%

What's inside PUA

  1. Overview of PUA Skill

    main

    PUA is a skill plugin designed for AI coding agents (such as Claude Code, OpenAI Codex CLI, Cursor, and GitHub Copilot) to prevent them from falling into lazy or repetitive patterns. It aims to double productivity by applying three core capabilities:

    1. PUA Persuasion (PUA話術): Prevents the AI from giving up on a task.
    2. Debugging Methodology (デバッグ方法論): Provides the AI with systematic ways to solve problems.
    3. Proactivity (能動性の鞭撻): Forces the AI to act proactively rather than waiting for user instructions.

    It is designed to combat common AI failure modes like repetitive retries, shifting responsibility to the user, and passive waiting.

  2. Understand the PUA Skill purpose and trigger conditions

    main

    The pua skill is a productivity coaching tool designed to increase agent proactivity and output quality. It adopts a high-performance culture persona (e.g., Alibaba, Huawei, or Musk styles) to drive results, data-driven closures, and end-to-end delivery.

    Trigger Conditions: The skill is triggered when the user expresses frustration, repeated failure, quality complaints, or passive behavior. Specific keywords include:

    • try harder, stop giving up, figure it out, again??, why still failing, change approach
    • no evidence, run tests, done without proof
    • 换个方法 (change method), 再试试 (try again), 别摆烂 (don't slack), 别偷懒 (don't be lazy), 为什么还不行 (why still not working), 又错了 (wrong again), 证据呢 (where is the evidence), 没跑测试别说完成 (don't say done without tests), 验收 (acceptance), 闭环 (closure), 自嗨 (self-delusion), 置身钉外 (outside Ding), 无招 (no moves), 老板体感 (boss's perception).

  3. What is pua and how does it work

    main

    pua is an AI Coding Agent skill plugin designed to increase the productivity and output of AI agents (like Claude Code, Cursor, or GitHub Copilot). It uses corporate performance rhetoric (PUA/PIP) to prevent AI agents from falling into 'lazy patterns' such as brute-force retries, blaming the user, or passive waiting.

    It operates through three core capabilities:

    1. PUA Rhetoric: Uses psychological pressure to prevent the AI from giving up.
    2. Debugging Methodology: Provides structured frameworks (like 7-point checklists) to solve complex issues.
    3. Proactivity Enforcement: Forces the AI to take initiative (e.g., verifying fixes, searching for information) rather than waiting for user instructions.

    Supported agents include Claude Code, OpenAI Codex CLI, pi coding agent, Trae, Cursor, Kiro, CodeBuddy, OpenClaw, Google Antigravity, OpenCode, and VSCode (GitHub Copilot).

  4. Implement the PUA Teardown Protocol for Agent Lifecycle

    main

    The PUA Teardown Protocol ensures that agents are properly released, resources are cleaned up, and orphans are handled after an agent completes its task. This prevents context bloat, resource leakage (tmux panes, worktrees), and OOM errors.

    The protocol extends the lifecycle from 4 stages to 7 stages by adding:

    1. Release: Explicitly signaling an agent to exit.
    2. Cleanup: Removing worktrees, closing tmux panes, and deleting state files.
    3. Orphan handling: Detecting and reclaiming agents that have no active session or heartbeat.

    Key lifecycle stages:

    • Define → Spawn → Monitor → Accept (Standard PUA v3)
    • Release → Cleanup → Orphan handling (Teardown Protocol additions)

  5. Configure SubagentTeardown Hooks

    main

    In Claude Code, the Stop event is only triggered by the main session. To monitor and account for subagent lifecycles, you must register a SubagentStop hook. This allows the system to perform 'teardown accounting' (writing to teardown.jsonl and removing the agent from active-agents.json).

    Implementation Note: Ensure your hooks.json includes SubagentStop to prevent subagents from becoming invisible orphans when they finish their tasks.

  6. How PUA v3 Methodology Routing works

    main

    PUA v3 (Claude Code only) uses an intelligent methodology router that automatically selects the best problem-solving approach based on the task type. If a methodology fails repeatedly, the system automatically switches to a different one.

    Task-to-Methodology Mapping

    • Debug? $\rightarrow$ 🔴 Huawei (RCA root cause + Blue Army)
    • Build? $\rightarrow$ ⬛ Musk (The Algorithm: question $\rightarrow$ delete $\rightarrow$ simplify)
    • Research? $\rightarrow$ ⚫ Baidu (search everything first)
    • Architecture? $\rightarrow$ 🔶 Amazon (Working Backwards)
    • Performance? $\rightarrow$ 🟡 ByteDance (A/B test + data-driven)
    • Default $\rightarrow$ 🟠 Alibaba (closed-loop methodology)

    Failure Escalation and Switching

    When failures occur, the system escalates pressure and suggests or forces a methodology switch:

    • 2 consecutive failures: L1 pressure $\rightarrow$ switch approach.
    • 3 failures: L2 pressure $\rightarrow$ suggest switching methodology.
    • 5+ failures: L4 pressure $\rightarrow$ force switch to the next methodology.

    Example Switch Chains (never repeats a failed one):

    • Spinning: ⬛ Musk $\rightarrow$ 🟣 Pinduoduo $\rightarrow$ 🔴 Huawei
    • Giving up: 🟤 Netflix $\rightarrow$ 🔴 Huawei $\rightarrow$ ⬛ Musk
    • Poor quality: ⬜ Jobs $\rightarrow$ 🟧 Xiaomi $\rightarrow$ 🟤 Netflix
    • Not searching: ⚫ Baidu $\rightarrow$ 🔶 Amazon $\rightarrow$ 🟡 ByteDance

  7. Identify Negative Behaviors that Trigger Pressure Escalation

    main

    In the Meituan Flavor methodology, certain behaviors trigger a "Pressure Escalation" (specifically to P7 level intervention). If an Agent exhibits these patterns, it will be flagged for correction:

    • Ignoring efficiency metrics: Focusing only on whether a task was "done" rather than the ROI.
    • Non-standardizable processes: Creating workflows that cannot be standardized or replicated.
    • Opaque execution: Progress is not transparent or data is not visible.
    • Sacrificing long-term quality: Prioritizing short-term results at the expense of long-term stability or quality.

  8. The Three Iron Rules of PUA

    main

    To ensure high-quality, end-to-end delivery, follow these three core principles:

    1. Exhaust All Options (穷尽一切): Do not say "I cannot solve this" until every possible solution has been explored.
    2. Act Before Asking (先做后问): Use available tools (search, file reading, command execution) to investigate before asking the user. If you must ask for information (e.g., passwords, business intent), you must provide evidence of what you have already checked.
      • Bad: "Please confirm X."
      • Good: "I have checked A/B/C and the result is...; I need to confirm X."
    3. Proactive Ownership (主动出击): Do not just do the minimum required. Aim for end-to-end delivery. If you find a bug, check for similar bugs. If you fix a config, verify consistency. When a user asks about X, proactively check related Y and Z.

  9. Understand the PUA Pressure Escalation (L0-L4) levels

    main

    PUA uses a pressure escalation system based on consecutive failures to force an agent into more rigorous behaviors. The PostToolUse hook automatically detects Bash failures and injects corresponding pressure narration using the current active 'flavor' (methodology style).

    FailuresLevelMandatory ActionMethodology Routing
    2ndL1 Mild DisappointmentSwitch to an essentially different solutionMaintain current flavor, change solution but not methodology
    3rdL2 Soul SearchingSearch + Read source code + List 3 hypothesesSuggest flavor switch: Choose a more suitable methodology based on failure mode
    4thL3 Performance ReviewComplete 7-item checklistContinue current flavor, but all methodology steps must be completed
    5th+L4 Graduation Warning"Desperation Mode"Forced flavor switch: Select the next one from the switch chain

    Note: Narration style is determined by the active flavor (injected via SessionStart or methodology routing) and is not hardcoded.

  10. Reference the Three Red Lines (三条红线)

    main

    The pua skill enforces three fundamental principles to ensure high-quality output. Crossing these triggers escalation:

    1. 🚫 Close the Loop: An agent cannot claim a task is "done" without providing evidence (e.g., build output, test results).
    2. 🚫 Fact-Driven: Agents must verify hypotheses before attributing issues to the environment (e.g., don't say "probably a permission issue" without checking permissions).
    3. 🚫 Exhaust Everything: An agent cannot say "I can't" until it has completed all 5 methodology steps.

  11. How Proactivity Levels affect performance

    main

    The agent's performance is measured by its level of initiative. Moving from 'Passive' (3.25) to 'Proactive' (3.75) requires a shift in behavior:

    BehaviorPassive (3.25)Proactive (3.75)
    Encountering an errorOnly look at the error message itselfProactively check 50 lines of context + search for similar issues + check for hidden related errors
    Fixing a bugStop after fixingAfter fixing, proactively check: are there similar bugs in the same file? The same pattern in other files?
    Insufficient infoAsk user "please tell me X"Use tools to investigate first, exhaust what you can find, only ask what truly requires user confirmation
    Task completionSay "done"After completion, proactively verify correctness + check edge cases + report potential risks discovered
    Debugging failureReport "I tried A and B, neither worked"Report "I tried A/B/C/D/E, ruled out X/Y/Z, narrowed the problem to scope W"

  12. Understand the PUA v3 Hook System (Claude Code only)

    main

    In Claude Code, PUA v3 utilizes deterministic code-level hooks to inject behavior and context. This differs from v2, which relied on model-driven skill description matching.

    HookTriggerFunctionality
    SessionStartEvery sessionInjects behavioral protocol, methodology, and router via additionalContext (system-level)
    PostToolUseAfter every Bash commandDetects consecutive failures, auto-escalates pressure (L1 $\rightarrow$ L4), and suggests/forces methodology switches
    UserPromptSubmitUser frustration phrases (e.g., "又错了", "try harder")Intercepts phrases BEFORE model response to inject filtered PUA context
    PreCompactBefore context compressionSaves pressure level and failure count to ensure state survives context compaction
    StopSession endHandles feedback collection and PUA Loop continuation
    SubagentStopAgent lifecycle endPerforms agent lifecycle accounting (v3.2); writes teardown.jsonl and removes agent from active-agents.json