Scriptonia/blog
DocsGet Scriptonia
← All posts
WORKFLOW2026-07-02 · 6 min read

Issue → PR: making coding agents build what customers actually asked for

The reliable way to go from a customer issue to a merged PR with a coding agent is a grounded plan file: retrieve the real customer signal behind the issue, check it against prior decisions, write PLAN.md with cited evidence and explicit non-goals, then have the agent execute that file verbatim.

Every team running coding agents hits the same wall: the agent is fast, but deciding what to tell it to build is now the bottleneck — and getting it wrong is expensive in review cycles, not compute.

The failure loop most teams are stuck in

Issue arrives → someone half-writes a spec from memory → agent builds → reviewer notices it's not what the customer meant → repeat. The agent was never the problem. The spec was folklore.

The grounded loop

1 SIGNAL scriptonia add <files> # tickets, calls, threads — once
2 PLAN scriptonia plan "<the issue>" # retrieve → check decisions → PLAN.md
3 BUILD claude "execute PLAN.md" # or codex · opencode · hermes
4 REFINE scriptonia comment plan/<slug> "…" # note in → plan v2 out

Step 2 is where the leverage is. A generated plan contains, in order:

  • Goal — one sentence describing what exists when it's done.
  • Evidence — why now, with each claim citing signal ids you can resolve to the raw quote.
  • Constraints — prior decisions this touches; conflicts are ⚠ UNRESOLVED until a human approves.
  • Non-goals — the fence. What the agent must NOT build, however tempting.
  • Acceptance criteria + real file paths + test plan — enough that the agent never asks “should the default be X or Y?”

Where the human stays in the loop

Exactly one place: between plan and build. You read one page. If scope is wrong, you don't edit the file — you leave a comment (scriptonia comment plan/<slug> "…") and the plan regenerates with your note folded in and versioned. Handing the plan to the agent is the approval.

What changes in the PR

The PR description cites the same signal ids as the plan. Your reviewer isn't evaluating “does this look reasonable” — they're checking “does this match the plan we already approved,” which is a five-minute review instead of a debate.

Frequently asked questions

Why not just paste the ticket into the agent's prompt?

One ticket is one voice. The signal that should shape scope is spread across Slack, five tickets, and two sales calls — and some of it contradicts your roadmap. Retrieval plus a contradiction check catches what a pasted ticket can't.

What stops the agent from ignoring the plan?

The plan is injected into AGENTS.md — the instruction file agents read before acting — with an explicit rule: execute PLAN.md exactly, respect Non-goals, stop on any UNRESOLVED constraint.

How long does the loop take?

Generating a plan takes about 15 seconds. The human review of a one-page plan takes a minute or two. The agent's build time is whatever it always was — but with far fewer clarifying questions and re-dos.

Try the loop on your own repo

One command, free tier, sample data included. Issue in, PLAN.md out.

npx scriptonia login