Agent Work Protocol

An always-on operating protocol for coding agents. Build only what was asked, surface ambiguity instead of guessing, scale process to the size of the task, and verify before claiming.

---

The problem

Coding agents fail in predictable ways:

• they over-build — inventing abstractions and features nobody asked for;
• they guess through ambiguity instead of asking, and the wrong guess surfaces at review;
• they hallucinate file paths, function names, and command behavior;
• they silently revert or rewrite work when they hit friction;
• they never push back on a bad instruction;
• they apply the same heavyweight process to a one-line fix as to a subsystem change — or no process at all.

These aren't model-capability problems. They're operating-discipline problems. A capable agent with no protocol still does all of the above.

What this is

A single, self-contained protocol (PROTOCOL.md, ~240 lines) that defines how an agent works — not what it knows. It is loaded into every session, so it governs trivial fixes and multi-day features alike. Its spine is a communication taxonomy the agent uses at the top of every response:

Mark	Meaning	Effect
Q#	A value or preference you haven't supplied	Halts dependent work
A#	An assumption about an ambiguous instruction	Proceeds if intent is obvious; halts if not
P#	Pushback on a decision likely to end badly	Halts the contested change only
E#	Expansion beyond the ask	Surfaced, never built without a yes
X#	A risk call already made, for you to sanity-check	Blocks the next merge that includes it

Around that taxonomy it adds: trivial-vs-non-trivial process scaling, a planning interview, a quality gate with an analyzer pass, git-worktree discipline, a session-file format, a degraded mode for when there's no git or filesystem, anti-hallucination and output-verification rules, a loop guard, and an explicit precedence ladder (in-conversation resolutions > your instructions > CLAUDE.md > this protocol).

See examples/session-top.md for what a response header looks like in practice.

Install

Option A — Claude Code plugin (always-on)

Adds a SessionStart hook that injects the protocol into every session automatically.

# add this repo as a plugin marketplace, then install
claude plugin marketplace add Ryuketsukami/agent-work-protocol
claude plugin install agent-work-protocol@agent-work-protocol

Option B — paste into CLAUDE.md (zero-setup)

Copy the contents of PROTOCOL.md into your project's .claude/CLAUDE.md (or ~/.claude/CLAUDE.md for all projects). No tooling required — works anywhere CLAUDE.md is read.

Option C — your own SessionStart hook

If you already manage hooks, point a SessionStart hook at the file:

{
  "hooks": {
    "SessionStart": [
      { "hooks": [ { "type": "command", "command": "cat /path/to/PROTOCOL.md" } ] }
    ]
  }
}

SessionStart stdout is injected into the session context, so the protocol survives compaction and applies from the first message.

What's in the protocol

§	Section	What it governs
1	Build only what was asked	Smallest viable change; no invented scope; self-review
2	On task start	Workspace check, classification, setup
3	Tasks and process scaling	Trivial vs non-trivial; precise definitions
4	Communication — Q/A/P/E/X	The raise taxonomy and halting rules
5	Quality gate	Test scope and the analyzer pass
6	Planning	The design interview for non-trivial work
7	Git	Worktree-per-task, micro-task commits, rollback
8	Session file	Boundary-logged task state
9	Degraded mode	No git / no persistent FS fallback
10	Project docs	GLOSSARY, ADRs, config-vs-constants
11	Delegation	When to fan out to sub-agents, and how to brief/verify
12	Verification and guards	Untrusted input, anti-hallucination, output verification, loop guard
—	Precedence and budget	Conflict resolution order; budget signalling

Philosophy

The protocol is opinionated on purpose. Two principles it will not soften:

• Surface, don't guess. Ambiguity is a first-class input. The agent's job when blocked is to raise, not to pick the likeliest reading and hope.
• Process matches stakes. A one-line fix shouldn't drag a worktree and a planning interview behind it; a subsystem change shouldn't skip them. The protocol defines the boundary precisely so the agent can't hand-wave it.

License

MIT — see LICENSE. Use it, fork it, adapt it to your own agents.