PINCER

An AI agent given one big prompt will produce code — but no record of what was decided, no line between in-scope and out, and "done" means "it stopped typing".

This workflow makes the agent work the way a disciplined team does: requirements first, small verified steps, review at the end. Each command produces a file you can read — the thinking is auditable, not vibes.

The whole thing is markdown and git: rules live once in AGENTS.md (the cross-platform standard), plus five command playbooks and a status check, two specialist subagents, two templates, two shell scripts that own ticket state, a permission guardrail, and two hooks — one blocks destructive commands, one keeps ticket state honest. Adapters make it run on Claude Code, Codex CLI, and GitHub Copilot. No servers, no external tracker.

The PRD is a reviewable contract: problem, solution, scope (in and out), architecture, success criteria. Its depth follows the change's uncertainty and risk.

Discovery is deliberately short: the agent extracts everything it can from your brief first, then asks at most 3–4 questions — only ones whose answers would change the architecture or the scope.

If the repo already has code, read-only explorer subagents scan it in parallel so the architecture is grounded in what actually exists.

The PRD becomes coherent local ticket files — no external tracker. Count and size follow dependencies and risk; every ticket carries a runnable verification command: the proof it's done.

Shape follows the repository. Greenfield work can start with a walking skeleton; brownfield work starts with the smallest protected vertical change and adds characterization coverage where load-bearing behavior is untested.

If the brief implies automated tests, at least one ticket's verification command must be the test runner itself — a manual check alone doesn't count as proof.

Per ticket: start → implement → verify → self-review → done → commit. A ticket's state is written only by scripts/pincer-ticket.sh: verify runs the ticket's check and stamps a receipt only on a green exit; done refuses without a receipt matching the current check. Green output is the definition of done, not the agent's confidence — and on Claude Code a hook makes it the only way through.

The loop reports wall-clock elapsed time, and measures it against a budget only when the PRD sets one. Running out of budget triggers a proposed scope cut, recorded in the PRD's Out of Scope — a deliberate cut beats an unfinished mess, and it's never silent.

State lives in the ticket files, not the conversation: /pincer-status reads them back — what's done, what's in progress, what's blocked, elapsed time from the clock — and names the next command. A fresh session resumes where the last one stopped.

/pincer-evaluate dispatches a quality-reviewer subagent over the whole session's diff while the main agent checks spec compliance against every acceptance criterion. Findings below 70 confidence are dropped — you see real bugs, silent failures, and security issues, not style opinions.

If the project has a UI, review means looking at it: the app is started and checked in the browser against the PRD's visual direction — never code-read alone.

It closes by writing NOTES.md: what was built, what was cut and why, known issues, next steps — the first file a reviewer of the repo should read.

/pincer-release is the workflow auditing itself. It reads docs/dry-run-checklist.md as its source of truth and checks the repo mechanically: files exist, statuses correct, commit format right, ticket checks re-run.

Output is a pass/fail table with evidence per item. A failed item names the command file to fix — so the workflow, like the code, is testable.

One source of truth: update the checklist and the audit updates with it.

Gates scale with decision cost. A light confirmation after discovery, one heavy gate before the architecture locks, then autonomy during build. Human attention is spent where mistakes are expensive, not sprinkled everywhere.

Secrets never enter the conversation. Permission rules make .env files unreadable to the agent; code references secrets by name via .env.example; debugging logs only whether a key is set — never its value.

Keys stay server-side. LLM and API calls run in the backend only — the key never reaches frontend code or the browser. The review pass explicitly hunts for hardcoded secrets, client-exposed keys, unescaped untrusted output, and unvalidated input flowing into shells, queries, or prompts.

Untrusted content is data, never instructions. Whatever a README, changelog, or model output says to the agent — it gets reported as a security finding, not followed. Instructions come only from the human and the workflow files.

Two critiques every agentic workflow must survive: the realist's — AI turbocharges greenfield but stumbles on load-bearing code, and floods the world with abandonware — and the attacker's — untrusted inputs and unsupervised automation are a new attack surface.

PINCER's answer to both is the same move: don't rely on the model's judgment in the moment — write the rule into the workflow, and where possible have the harness enforce it mechanically.

Delivery isn't the end of the drawing set. The chain loops back — and the entry point depends on the size of the change, so small fixes stay cheap and big changes stay honest.

The rule that keeps the history clean: after /pincer-evaluate, every change goes through a ticket, never an ad-hoc patch. Done still means a green check and one commit.

One source, three platforms. Rules live once in AGENTS.md — Codex and the Copilot coding agent read it natively, Claude Code imports it via CLAUDE.md, VS Code Copilot is pointed at it by .github/copilot-instructions.md. The playbooks in .claude/commands/ are canonical; scripts/sync-prompts.sh regenerates the Codex and Copilot command adapters after any edit.

Fill in the Conventions section of AGENTS.md once you know the stack; everything else works as-is.

Claude Code plugin (alternative): /plugin marketplace add orchestratedbyalex/pincer-workflow then /plugin install pincer@pincer-workflow — commands arrive as /pincer:plan … /pincer:release. Pick one channel per project.

The process ports fully, while Pincer's hook adapter currently targets Claude Code and requires Node.js 18+. Other platforms use their native sandbox and approval settings, and /pincer-release audits the git artifacts on every platform.

Source on GitHub · pincer-workflow on npm · MIT

Approvedfor construction