AI coding agent workflow at a glance
Treat the workflow as six states with explicit outputs and return paths, not as a checklist that always moves forward.
The agent advances only when the current stage has produced enough evidence for the next decision. A failed check returns to the earliest stage that can correct it; a missing decision or permission stops the run.
Brief adapts the amount of structure. A low-risk, scoped task may use one compact context packet and focused validation. Larger or riskier work adds a mission contract and durable proof.
| Stage | Output | Return when |
|---|---|---|
| 1 · Outcome | Observable behavior, non-goals, and authority boundary | Ask for a decision when the outcome, owner, or permitted action is unclear. |
| 2 · Context | Source-backed working set and pre-edit receipt | Return to Outcome if evidence changes the request; stay here while the repository, scope, or rule is uncertain. |
| 3 · Plan | Files, reuse decisions, risks, checks, and stop conditions | Return to Context when the plan depends on an unverified pattern, file, owner, or test. |
| 4 · Change | Smallest coherent diff and recorded scope changes | Return to Plan when the diff expands, or to Context when a hidden dependency or rule appears. |
| 5 · Verify | Behavior proof, exact results, review verdict, and skips | Return to Change for a narrow defect, or to Context or Plan when a failure exposes a wrong assumption. |
| 6 · Handoff | Changed behavior, proof, remaining risk, and open decisions | Return to Verify when proof is missing; stop for judgment or approval the run cannot supply. |
Define the observable outcome
The request should describe what must become true, while leaving implementation choices open until the agent inspects the code.
“Improve authentication” is too broad to verify. “Keep a signed-in user on the requested page after their session refreshes” gives the agent a behavior, a boundary, and a place to look. A good mission can still begin in plain English; it simply makes the end state legible.
Brief uses the request as a routing signal. Exact files and symbols raise scope confidence, but they are not mandatory. If the task touches security, data, deployment, migrations, billing, or several surfaces, Brief expands the run contract and makes stop conditions explicit.
Gather context that can change the plan
Before choosing an implementation, collect the local rules, nearby examples, tests, owners, and earlier decisions that govern this part of the repository.
Suppose the request is to keep a signed-in user on the requested page after a session refresh. The useful context is not every authentication file. It is the refresh path, the redirect helper, the tests that describe return URLs, and any rule that limits where session state may be read.
Brief records that small set as a context packet with source paths. If the packet reveals a shared helper or a security boundary, the plan changes before code does. If it finds no reliable example, that absence is visible too; the agent should investigate rather than invent a house style.
Build the plan from repository evidence
A useful plan names real files, reuse decisions, risks, and checks discovered in the repository.
Plans written from the request alone often restate the request. The agent should first locate the runtime path, open the relevant rules, identify the closest implementation, and find the test grammar. Only then can it choose a small sequence of edits that fits the codebase.
Not every small task needs a mission. A compact, low-risk change may need one context packet and one focused check. For larger or riskier work, a Brief mission records the objective, likely files, validation, review bar, autonomy ceiling, and stop conditions. When new evidence changes the scope, the mission changes with it.
- What the user will be able to observe
- Which files and systems are probably involved
- Which existing pattern will be reused or ruled out
- Which checks can prove the change
- What requires a human decision or new permission
Let the agent own the bounded inner loop
Within the agreed boundary, the agent should inspect, edit, run checks, diagnose failures, and iterate without waiting after every reversible step.
Delegation loses its value when a person must approve every search and test. It also becomes unsafe when “finish the task” is interpreted as permission to publish, delete data, change production settings, or expand into adjacent systems. The autonomy ceiling separates normal implementation work from actions that need new authority.
A focused task may need only one context packet and one test. A larger mission may include a visual proof loop, database verification, or an independent review. Brief scales the loop from task evidence rather than from job title or a fixed process template.
- Continue through reversible searches, edits, and focused checks inside the agreed repository scope.
- Refresh context when the diff reaches a new file, rule, owner, or risk boundary.
- Stop for new authority, external writes, destructive actions, production changes, or unresolved product judgment.
Verify behavior, not activity
A changed file proves that work happened. Verification shows whether the requested behavior now holds at the right boundary.
For the session-refresh example, a type check is useful but incomplete. The stronger proof exercises an expired session, confirms the refresh succeeds, and checks that the original return URL survives. A browser check may also be needed if navigation or loading state changed.
When a check fails, return to the smallest stage that can explain it. A wrong assumption belongs back in context or planning; a narrow bug belongs in execution. Local diff review can check deterministic evidence and applicable rules, but product or architecture tradeoffs remain human judgment. Record skipped checks plainly so the handoff never makes the evidence sound stronger than it is.
Worked example: preserve a return URL after session refresh
The same request can move through all six states without turning a bounded engineering task into ceremony.
Suppose the request is: “When a signed-in user's session refreshes, keep them on the page they originally requested.” The outcome is observable, but the safe implementation still depends on the repository's refresh path, redirect rules, and return-URL tests.
Brief can route those sources before the first edit and bound the change to the existing session flow. If a test exposes a wrong redirect assumption, the run returns to Context or Plan. If the work needs a new security decision, production access, or unavailable credentials, it stops for a person rather than stretching the original request.
| Stage | Example evidence | Decision |
|---|---|---|
| Outcome | A signed-in user remains on the originally requested page after the session refreshes. | Keep auth-provider changes and unrelated navigation work out of scope. |
| Context | Refresh path, redirect helper, return-URL tests, applicable session rules, and their source paths. | Reuse the repository's existing redirect and session boundaries. |
| Plan | Likely files, the closest passing test, security risk, focused checks, and stop conditions. | Change the refresh path and its boundary test; stop if the redirect policy is unresolved. |
| Change | A small local diff in the refresh flow and the test that defines return-URL behavior. | Do not refactor adjacent authentication code without new evidence and scope. |
| Verify | An expired-session check refreshes successfully, preserves a safe local URL, and rejects an external return URL. | Return to Change for a narrow defect; return to Context or Plan for a wrong assumption. |
| Handoff | Changed behavior, exact commands and results, local review verdict, explicit skips, and remaining auth risk. | Report the evidence without claiming more coverage than the checks provide. |
Hand off proof, skips, and remaining risk
The handoff should say what changed, what passed, what was not run, and what remains uncertain.
A long activity log is not proof. Reviewers need the changed behavior, the meaningful files, the exact validation commands, the diff-review result, and any remaining risk. Screenshots are useful for visual claims; they cannot prove a keyboard interaction or a data boundary on their own.
Brief links mission, context, review, and handoff receipts so the evidence can be checked without replaying the whole conversation. Humans still decide product direction, accept tradeoffs, and approve consequential actions. The loop makes those decisions easier to locate.
Common questions
Questions worth asking next
Does every task need a mission plan?
No. A low-risk, tightly scoped change can use a compact context packet and focused validation. Brief expands the loop when scope, risk, or failed evidence warrants it.
When should a coding agent stop?
It should stop when the task needs new authority, a product decision, unavailable credentials, destructive production action, or scope beyond the agreed mission.
How is the production workflow different from the agent's inner loop?
The inner loop is the agent inspecting, editing, testing, and diagnosing. The production workflow surrounds that work with an observable outcome, source-backed repository context, an authority boundary, proportionate verification, and a reviewer-readable handoff.