Building an AI Coding Workflow: The Right Agent at the Right Stage

A development-workflow analysis argues that teams misuse AI coding assistants by treating adoption as a single dial — either rewriting every generated line by hand and killing speed, or letting the assistant drive without any written intent to review against, which collapses around the third feature. The proposed fix separates three distinct sources of truth: Shape Up-style pitches that capture why a change is worth doing, OpenSpec-style specs that define what a change must do, and Architectural Decision Records that document how the team has agreed to build things.

The framework treats the development lifecycle as a state machine with mixed ownership. Some stages — setting appetite, placing a bet, accepting an ADR — remain strictly human judgement. Others, like expanding a pitch into a spec or drafting a pull request description, are agent-drafted and human-corrected. A few, like folding a merged change back into the source of truth, are fully automatic. Crucially, an agent may apply an already-accepted architectural decision but can never invent or ratify a new one; new standards flow back into ADRs only under human control.

Underpinning all of this is a thin workflow runtime enforcing four non-negotiable rules: never skip a stage that requires a human, never run an agent where none belongs, never let a change exceed its fixed appetite, and never advance work on an unaccepted architectural decision. For teams adopting AI-assisted coding, the piece offers a concrete structure for gaining speed without losing architectural coherence or review discipline.