Patpat

Engineering skills for code that must survive contact with reality.

Patpat is a portable engineering plugin for AI agents and AI-enabled developer tools that support a compatible plugin or project-scoped Agent Skills directory. Its canonical skills/ tree is host-neutral, though installation and invocation vary by host. Patpat has host adapters for Codex, Claude Code, Grok CLI, Antigravity, and Cursor. Claude Code's marketplace contract is now defined, but its CLI validation and fresh-session invocation have not been run in this environment. Cursor's marketplace listing and fresh-session invocation are not yet verified; use the portable route for that host until they are. For other hosts, use the portable route only after proving the host reads a project-scoped skills directory. There is no universal plugin format: each host must support a compatible plugin contract or skills directory, and invocation must be verified on that host. See the installation guide for host-specific setup.

Guide · Install and update · Capability map · Releases · Security

Agents can produce a heroic amount of plausible code before lunch. The team still has to prove it.

Patpat gives an agent host a disciplined engineering protocol: inspect the real system, name the proof before editing, change the smallest safe surface, and verify the result where the user would see it. These are required agent behaviors. Patpat does not claim that prose alone prevents edit-first mutation; that guarantee requires a host-enforced pre-tool gate plus a receipt proving the gate ran.

If the evidence is "the agent felt confident," the run is still in progress.

The core is Patpat's operating protocol: judgment, safety, git, and honest evidence. Playbooks may specialize the work; none of them can outrank the protocol.

Use /patpat for non-trivial work. It is the same entry as /patpat-loop. Call a focused skill directly when the task is already narrow.

New to the system? Start with The Patpat Guide. It walks from installation proof to the operating loop, verification, delivery, durable runs, earned parallelism, and safe extension.

Install

Codex, from this repository:

codex plugin marketplace add goiltpatpat/patpat
codex plugin add patpat@patpat

Start a new task, then invoke $patpat. Package installation and prompt-time discovery are separate checks.

Other hosts and portable installation

Claude Code, from this repository:

claude plugin marketplace add goiltpatpat/patpat
claude plugin install patpat@patpat

Start a new session, then invoke /patpat:patpat. The marketplace entry follows Patpat's package release version; see the Claude Code install and update steps.

Grok CLI, from this repository:

grok plugin install goiltpatpat/patpat --trust

Start a new session, then invoke /patpat. The trusted hook path is covered by an isolated install-and-execution smoke test.

Antigravity, from a clone that does not contain local development state:

git clone https://github.com/goiltpatpat/patpat.git
agy plugin validate /absolute/path/to/patpat
agy plugin install /absolute/path/to/patpat

For hosts that support the portable Agent Plugins 1.0 format, generate a separate package from the canonical skills tree:

python3 scripts/stage_agent_plugin.py --target /absolute/path/to/patpat-agent-plugin
python3 scripts/validate.py --agent-plugin /absolute/path/to/patpat-agent-plugin

This output uses the standard root plugin.json; it is for compatible Agent Plugins clients, not Antigravity. Git-backed staging excludes Git-ignored local files from skills; without Git metadata, inspect the artifact before installing. Follow each host's documented install path and verify fresh-session discovery there. Hooks and other host-specific behavior still depend on the selected adapter.

Patpat's Cursor marketplace listing and fresh-session invocation have not been proven in a live project. Cursor documents local plugin testing under ~/.cursor/plugins/local/<plugin>; generate the portable package above, copy it into a fresh directory there, reload Cursor, and inspect Customize if local plugin imports are enabled. A same-name marketplace plugin takes precedence over the local copy. Treat Patpat as unverified until its skills are observed in a fresh session. If that host route is unavailable, use a proven project skills directory:

python3 scripts/install_skills.py \
  --target /absolute/path/to/project/.agents/skills \
  --dry-run

A working tree that still contains Memory Bank or other ignored files must be staged first. Agents should follow AGENTS.md. Host commands, updates, and removal live in the installation guide.

Update through the owner of the installed state: Codex marketplace upgrade plus remove/add, Claude marketplace and plugin update after a package version bump, grok plugin update patpat, pull/validate/install on the same Antigravity clone, or the transactional portable updater. Development symlinks follow source content and use the updater when the skill catalog changes. Cursor native update remains unverified. See the update matrix.

Get started

Two steps:

1. Install Patpat on the active host.
2. Invoke /patpat (Cursor), $patpat (Codex), /patpat:patpat (Claude Code), or Use patpat to ... on other hosts.

/patpat reproduce this timeout, fix the root cause, and land the PR

That is enough. Explicit activation authorizes the Patpat loop, proof, and verify. Default commit-and-PR still requires delivery intent; see the operating protocol and default delivery. The router stays on across later turns when a supported trusted host hook supplies a receipt. Say disable /patpat or local only to opt out. Higher-priority repository rules still win. Optional personal engineering instructions can add your preferences; Patpat works without them.

Usage

/patpat is the default entry point. It reads the request, tracks the matched playbook, and routes through inspection, proof, implementation, verification, and review. Codex and Grok hooks persist the mode across resume. The Cursor adapter does not currently persist the mode across resumes because a compatible state-storage path has not been verified; without a hook receipt the mode still applies for the rest of the current session.

FRAME -> INSPECT -> PROOF CONTRACT -> ACT -> VERIFY
VERIFY -> REPORT when local reversible without delivery intent
VERIFY -> REVIEW before delivery / high-risk / durable-run LEARN|REPORT
REVIEW -> LEARN? -> propose and wait for approval -> approved edit -> VERIFY -> REVIEW -> REPORT
LEARN approval pending -> hold; approval declined -> REPORT without editing

A proof contract names the claim, authoritative surface, action, expected observation, and cleanup. A build supports a claim. It does not prove user-visible behavior. Green is a signal, not an alibi.

Cursor uses /patpat or /patpat-loop. Codex uses $patpat or $patpat-loop. Claude Code uses /patpat:patpat. Portable hosts use Use patpat to ....

Playbooks

Browse all playbooks

Playbook	For
Investigation	Read-only explanation: how it works, where it lives, who owns it, and which layer. Rationale questions stay on rationale forensics.
Defect	Reproduce a failure, prove the root cause, and fix it with runtime evidence.
Regression first	A cheap deterministic test exists. Write the failing check, then the fix.
Performance	A measured slowness against a comparable baseline.
Metric hillclimb	Sustained improvement of one metric, one accepted win at a time.
Runtime forensics	A live symptom: leak, idle spin, glitch.
Trace forensics	A captured profile, trace, or heap snapshot.
Rationale forensics	Explain why code reached its current shape: code anchors first, evidence before narrative.
Blast radius	What else this change could break, proven rather than asserted.
Architecture change	Contracts, migrations, or a redesign that must settle before code.
Bounded change	New or changed behavior from a named data shape.
Behavior-preserving refactor	Structure changes without behavior changes.
Prototype	A throwaway sketch that makes a design decision cheap.
Visual equivalence	Pixel-level UI parity between two implementations.
Bespoke workflow	No narrow playbook fits. Design a falsifiable sequence.
Multi-phase run	Work that spans phases, checkpoints, or a durable graph.
Session takeover	Resume or take over in-flight work from live repository state.
Pause safely	Pause in-flight work without opening a PR or merging.
PR drive	PR status only. Land only when named.
PR Readiness Handoff	Move a PR to verified merge-ready status, then return control to the human.
Worktree cleanup	Prune merged or abandoned git worktrees. Simulators stay outside the core.
Arena	Competing isolated attempts at one brief, then a verified synthesis.
Swarm	Parallel slices or races, one aggregated report.
Autopilot	A verified queue or stack. Merge only when named.
Issue loop	Named-provider triage and reproduce. Avoids competing fixes, stays paused until enabled, and defaults provider-triggered issue-loop PRs to draft.
Default delivery	When delivery intent exists, commit and open or update one ready PR after verify and review. Activation alone does not ship.
Authorized delivery	Merge a green verified PR only on explicit land or merge; pause for deploy.
Independent review	Challenge an implementation and its proof without editing.
Skill change	Write or revise a SKILL.md.
Behavioral evaluation	Test whether a skill triggers and behaves correctly.
Project verifier	Build or repair project-local proof against the real system.
Learning	Encode a recurring failure as the smallest durable constraint.
Automation design	Design fail-closed automation for a named integration.
Build a playable slice	Implement the smallest end-to-end game loop for a concrete brief.
Diagnose gameplay	Find the first gameplay state that diverges from the expected result.
Verify a playthrough	Prove rules, player input, visuals, and target-runtime behavior separately.
Visual iteration	Improve requested game presentation against frozen, observable conditions.

Skills

patpat-loop runs most of these when a step needs them. Reach for one directly when the task is already that operation.

Browse all skills

Skill	Use it when
00-workspace-mapper	Explicitly map an unfamiliar workspace; the current catalog has no hard consumer of its map state.
patpat	Slash alias for the loop. /patpat is the default entry.
patpat-loop	The work is non-trivial and needs the full loop.
patpat-inspect	Explain, audit, or diagnose without editing.
patpat-repository-diagram	Turn an idea, plan, or codebase into an interactive diagram; optionally derive a source-evidenced Python import map.
patpat-game-builder	Build a playable game slice or gameplay feature, then verify the real player path.
patpat-plan	Sequence verifiable phases without implementing them.
patpat-impact	Prove blast radius and downstream invariants.
patpat-architect	Settle contracts, migrations, and risk first.
patpat-change	Implement one bounded feature or refactor.
patpat-debug	Reproduce, root-cause, and fix.
patpat-perf	Improve a measured resource regression.
patpat-verify	Test a claim on the real artifact or user surface.
patpat-review	Independently try to falsify the change and its evidence.
patpat-interrogate	Challenge a design or change from adversarial perspectives.
patpat-run	Drive or resume a durable multi-phase graph.
patpat-arena	Compete isolated attempts and synthesize one verified result.
patpat-swarm	Cover slices or races and return one report.
patpat-setup	Install, validate, or remove Patpat on a host.
patpat-ship	Commit-and-PR when delivery intent exists; merge only when explicitly named.
patpat-skill	Author a reusable skill.
patpat-eval	Evaluate skill triggering and behavior against the authorized project with an evidence rubric.
patpat-unslop	Cut superficial patterns and fluff from text or diffs.
patpat-verifier	Create or maintain a project-specific verifier.
patpat-learn	Encode a recurring failure.
patpat-automation	Design fail-closed automation. Do not enable it yet.
patpat-engineer	Execute one isolated slice for a named owner.

Principles live under skills/patpat-loop/principles/. They are references, not discoverable skills. The capability map records what is covered, gated, or left outside the core.

Agent roles

Two roles, one contract each:

• patpat-engineer owns one bounded implementation slice and returns artifacts to the integration owner.
• patpat-reviewer is read-only and tries to break the implementation and its evidence.

Cursor and Antigravity ship a thin native adapter only for the reviewer. The engineer stays a portable skill until a host can enforce file ownership. Codex receives both roles as skills.

Durable runs

patpat-run is a standard-library state machine, not a prose checklist. It refuses ACT without a proof contract, REVIEW without a current content-bound evidence file, and completion without independent review. The third identical blocker stops the run.

Multi-PR plans use a host-neutral checked JSON contract. Validate dependencies, owned files, proof surfaces, exact-head evidence, review gates, and delivery authority before implementation:

python3 skills/patpat-run/scripts/run_state.py --self-test
python3 skills/patpat-run/scripts/validate_plan.py --self-test
python3 skills/patpat-run/scripts/program_state.py --self-test
python3 skills/patpat-run/scripts/team_shape.py --self-test

The program store adds a dependency frontier, inbox, explicit dispatch and delivery gates, and head-bound verification records under Git metadata. It coordinates state without spawning agents or creating delivery authority. Dependency head changes invalidate downstream evidence.

team_shape.py recommends iterative, distributed, or adversarial work from an earned-parallelism gate receipt, explicit evidence, observed capacity, and a caller-owned worker budget. It never grants authority. Coordination uses compact receipts and typed handoff cards rather than replaying full agent transcripts.

Where Patpat stops

Patpat does not turn capability into authority. These boundaries are deliberate:

• Writable arena, swarm, and autopilot require separate worktrees or host-enforced sandboxes and fall back to serial work
• Issue-loop stays paused until a named provider, sandbox, canary, and enable request exist; provider-triggered PRs stay draft without fresh interactive authority
• Merge of a red CI, package publish, and production deploy
• Model-selection presets and persona skills

After verify and review, delivery intent (not activation alone) commits and opens or updates a ready PR. Overnight work stops merge-ready. Only explicit land or merge language can merge when checks are green. Patpat still pauses for production deploy, force-push, secret rotation, and risky auth or billing changes.

Validate

Local validation suite

python3 scripts/validate.py --self-test
python3 scripts/dry_run_loop.py --self-test
python3 scripts/eval_inspect.py --self-test
python3 scripts/eval_representation.py --self-test
python3 scripts/eval_parallel.py --self-test
python3 scripts/eval_why.py --self-test
python3 scripts/install_skills.py --self-test
python3 scripts/update_skills.py --self-test
python3 scripts/stage_plugin.py --self-test
python3 hooks/scripts/patpat_loop_state.py --self-test
python3 skills/patpat-run/scripts/run_state.py --self-test
python3 skills/patpat-run/scripts/validate_plan.py --self-test
python3 skills/patpat-run/scripts/program_state.py --self-test
python3 skills/patpat-run/scripts/team_shape.py --self-test
python3 skills/patpat-ship/scripts/github_observe.py --self-test
python3 skills/patpat-ship/scripts/pr_watch.py --self-test
python3 scripts/smoke_codex_plugin.py
python3 scripts/smoke_antigravity_plugin.py
python3 scripts/smoke_grok_plugin.py

eval_why.py requires a source checkout with Git history; do not use it as an installed-artifact smoke test. Codex and Antigravity smoke commands require their respective CLIs and use isolated homes. The GitHub workflow is the authoritative CI contract; this local list also includes extended checks that CI does not run.

Security and contributions

Report vulnerabilities privately through the security policy. Do not place secrets, private logs, or exploit details in a public issue. Pull requests should keep scope narrow and include observable evidence for the claim being changed; the repository template records that contract without prescribing a development style.

License

MIT