Four Commands My AI Agent Can't Skip — From Vague Idea to Merged PR

Ask an AI coding agent to "add CSV export" and it will happily produce an export button, a settings page, three utility modules, and a confident summary of work you never asked for. Speed was never the problem. Aim is.

dev-process-toolkit is my Claude Code plugin that fixes the aim. I've already written about why it exists (deterministic gates, bounded self-review) and what it feels like in a real project. This time: the actual day-to-day workflow. Four commands take you from a fuzzy idea to a merged PR — and at the end, I'll show you the part I'm most proud of: how the plugin tests itself.

/brainstorm — the AI finally asks questions

Most agents treat your first sentence as the full requirements document. /brainstorm treats it as an opening statement.

It runs a Socratic clarification loop: one question at a time. Ask, wait for the answer, then decide if the next question is still needed. Usually 2–4 questions are enough. Then it proposes 2–3 distinct approaches — each with tradeoffs and one main risk — and waits for you to pick. Two hard rules: no code and no specs during brainstorming, and no moving forward without your explicit design approval.

The skill file even ships a "Rationalization Prevention" table — a list of excuses the model might use to cut corners, each with a rebuttal. "These two questions are independent" → "Ask the first, wait, then ask the second." Yes, my plugin argues with my AI so I don't have to.

There's a reason for the paranoia. In an earlier version, Claude ran autonomously, skipped the entire interview, and — like a magpie grabbing shiny things — generated plugin scaffolding, seven skill files, and a README before asking a single question. The docs now call this failure class the magpie bypass.

The fix is structural: the first move must be a question, and a dedicated gate probe fails the check if it isn't. (More on gates in a minute.)

/spec-write — write it down before you build it

/spec-write is where the idea stops being a conversation and becomes a document. It interviews you a bit more, then produces the specs: requirements (what), technical (how), testing (how we'll know it works), and a plan (in what order). Every functional requirement gets its own file with binary pass/fail acceptance criteria. You approve the drafts before anything is committed.

Boring? Extremely. But this is the contract the agent gets audited against later — and the reason a change in week two doesn't quietly undo something from week one.

/implement — TDD with subagents that can't cheat

This is where the robots do robot things. For each requirement, /implement runs a full test-driven cycle — write a failing test (RED), make it pass (GREEN), clean up (REFACTOR), then check the result against the spec (AUDIT) — and hands each stage to a different subagent: a test-writer, an implementer, a refactorer, and a spec-reviewer.

Each one runs in an isolated forked context, so the test-writer literally cannot see the implementation. No writing tests that conveniently pass. The audit stage re-enters RED → GREEN for any missed acceptance criteria — once — and then halts and calls a human.

After the build comes a self-review capped at two rounds. If round two finds the same class of problems as round one, the agent stops burning tokens and escalates. And it never, ever commits without a human saying "go."

Loops everywhere — but every loop has an exit

You may have noticed a pattern: the whole plugin is built from loops (clarify until clear, test until green, review until clean) and deterministic gates that decide when a loop is done. /gate-check alone runs 72 numbered probes — typecheck, lint, tests, plus spec, plan, and branch hygiene checks. Exit codes, not vibes. The core rule from the docs:

"Deterministic checks always override LLM judgment. A failing test means 'fix it,' not 'maybe it's fine.'"

And every loop is bounded: max 2 attempts per role, max 2 review rounds, one audit retry — then a hard stop that surfaces to you. The failure mode is "stopped and asked a human," never "still going, please top up your API credits."

/pr — the boring one, on purpose

/pr does exactly one clever thing: it refuses your title. The PR title is derived from the branch's main Conventional Commit type — the feat: / fix: / refactor: prefix you already write — so it always matches what actually changed. You get a clean summary and a test plan. Naming things is no longer your problem — one down, cache invalidation to go.

The plugin tests itself before every release

Here's my favorite part. The plugin is developed with itself, and before a release it turns its own machinery on itself:

• /smoke-test spins up a brand-new throwaway project and drives the full chain — setup → spec-write → implement → gate-check → spec-review → simplify — through real child Claude sessions, writing every rough edge to a findings file. Its prime directive: "Capture, don't fix." Find the problems, don't paper over them mid-run.
• /conformance-loop runs smoke tests against both supported issue trackers (Linear and Jira) in parallel, dedups the findings, and (with --auto-fix) dispatches /spec-write + /implement for each high-severity finding — then re-runs until one of three exit conditions: green, max-iterations, or no-progress. Even the self-improvement loop has brakes.

From the docs:

"Unit tests test what you remembered to test. Dogfooding tests what the user will actually hit."

At one point every unit test in the repo was green — and the first real dogfooding run still surfaced 14 gaps. Each finding becomes a requirement, requirements become a hardening milestone, and the milestone ships through the same four commands you just read about. The quality is high because the QA department is the plugin.

Found something weird? /report-issue

If the plugin annoys you, tell it: /report-issue asks four short questions (what happened, what you expected, severity, reproducible?), bundles a snapshot of your setup with secrets scrubbed out — seven regex patterns catch API keys, tokens, and JWTs — and shows you a preview before anything leaves your machine. Only then does it publish a secret GitHub gist.

The nice trick: paste that gist URL into /brainstorm in a fresh session, and the plugin starts debugging itself. Your bug report becomes the opening statement of the next Socratic interview. The circle of life.

Try it

/plugin marketplace add nesquikm/dev-process-toolkit
/plugin install dev-process-toolkit@dev-process-toolkit

Then run /dev-process-toolkit:setup in your project — it detects your stack and generates the gate commands. The only prerequisite is bun (the toolkit's helpers run on it, whatever your project's language is). Start small: try /gate-check first, add the full workflow when you're ready.

Every release gets a one-word codename, by the way. The current one is Semaphore. Of course it is.

---

Part of a series on engineering discipline for AI agents. Previously: I Built a Claude Code Plugin That Stops It from Shipping Broken Code (why the toolkit exists) and I Built a macOS App in a Weekend with an AI Agent (the workflow on a real project).