Develop

Why this workflow exists

Most bad agent output is not bad coding — it is coding before understanding. Develop splits one implementation into two halves. First it states the goal, acceptance behavior, out of scope, assumptions, and solution boundary, then stops. Only action language you send after that checkpoint allows production code to change. Everything after that — corrections, omissions, follow-up questions — stays inside the same task without another invocation.

How it runs, stage by stage

Every rule below is taken from the workflow definition in the source repository — this is what the agent is actually told to do.

1. 01

   Discover once

   Read everything worth reading — and read it only once.

   • Read applicable project instructions and authoritative requirement or design documents.
   • Inspect version-control state and preserve unrelated uncommitted work.
   • Read the relevant implementation, tests, callers, and nearby existing patterns.
   • If the existing behavior is itself broken, switch to the Diagnose lifecycle.
   • Evidence is gathered once and reused; unchanged discovery is never repeated for narration.
2. 02

   Clarify to a safe threshold

   Ask only what changes the result, and ask it all at once.

   • A question is allowed only when all three hold: the answer changes accepted behavior, the request leaves it unresolved or authoritative evidence contradicts it, and no contract or precedent already resolves it.
   • Implementation facts discoverable in the repository — field names, associations, helper choice, storage shape — are investigation work, not user choices.
   • Inventory every behavior marked undefined, unknown, intentional, or not established before asking. Undefined never means out of scope on its own.
   • For delete and write operations, an undefined unknown or missing-resource result is a hard-stop question. It cannot be inferred from a success return value, absent precedent, or a neighboring read API.
   • All independent qualifying questions go into one compact batch; only genuinely dependent questions follow the answers.
   • A complete contract closes its named input domain. Inputs outside it stay out of scope instead of extending the interview.
3. 03

   Present the checkpoint

   Put the final understanding on the table, then stop.

   • Present the goal, acceptance behavior, out of scope, assumptions, and material solution boundary.
   • A short checkpoint stays in the conversation. A substantial one uses the project’s authoritative document, or docs/requirements/<feature-slug>.md with status Draft when no convention exists.
   • When the first request already supplies a complete contract, create and verify that Draft in the same turn — hypothetical optional inputs cannot delay it.
   • Do not change production code, tests, or configuration before approval. Writing the requirement record is allowed.
   • End the turn after the checkpoint. The Develop invocation itself is not approval to code.
4. 04

   ApprovalHuman gate

   One explicit sentence from you opens this gate — nothing else does.

   • Only action language sent after the checkpoint approves implementation, such as “implement this”, “start implementation”, or “proceed with the plan above”.
   • The initial request, answers to clarification questions, and reading acknowledgements never count as approval.
   • On approval, a durable requirement record is marked Accepted and work continues directly — you are never asked to invoke Develop again.
5. 05

   Choose boundary and feedback

   Decide where the change belongs and what evidence will prove it.

   • Reuse existing behavior only when it has the same domain responsibility and should evolve together.
   • Place rules with the module that owns the relevant data and invariant; inspect sibling callers before changing shared behavior.
   • Choose the highest stable public seam that can prove each behavior slice.
   • Use red-green-refactor for regressions and valuable business behavior; use compile, lint, or integration checks for mechanical, presentation, configuration, and framework-wiring work.
   • When new stable behavior closes a coverage gap, leave focused automated coverage — unless it would be ceremonial or could not detect the behavior.
6. 06

   Implement and harden

   Smallest clear change at the owning boundary, then targeted hardening only.

   • Make the smallest clear change at the owning boundary and keep control flow, effects, failures, and state transitions explicit.
   • Avoid speculative abstractions, dependencies, configuration, and unrelated cleanup.
   • Preserve validation, permissions, security, data integrity, compatibility, accessibility, and unrelated work.
   • Run focused feedback after a behavior-changing slice only when its result could have changed — never rerun the same command against the same state.
   • Add targeted coverage only for real risk: input, numeric/time, collection, state/lifecycle, duplicate/concurrent, permission/trust, resource/external-failure, migration, or compatibility.
   • If implementation reveals a material requirement change, align only that increment, update the checkpoint, and pause for approval again.
7. 07

   Complete and reconcile

   Prove every accepted behavior, and make the documents true again.

   • Re-read the accepted behavior and inspect the diff for correctness, safety, ownership, readability, test sensitivity, scope, and temporary artifacts.
   • Reconcile every accepted behavior as verified, partially verified, incomplete, or deviated.
   • Before marking a record Implemented, replace stale future-tense language — “will be added”, “to be created”, “pending” — with the actual files and fresh evidence. A status-only edit is not sufficient.
   • Update authoritative documentation only for changed facts; update project instructions only for durable cross-task rules.
   • Remove temporary diagnostics and report remaining gaps.
   • Do not commit, push, publish, create external issues, install dependencies, or change global configuration unless authorized.

Rules that cannot be bypassed

A real invocation

What the conversation actually looks like, from the token you send to the evidence you get back.

1. Agent

   Reads project rules, Git state, the existing export and permission code, then asks the single question that changes the result: what should happen for an order ID that does not exist?

2. You

   Fail with a 404.

3. Agent

   Returns the checkpoint — goal, acceptance behavior, out of scope, assumptions, solution boundary — creates docs/requirements/order-batch-export.md as Draft, and stops.

4. You

   Proceed with the plan above.

5. Agent

   Marks the record Accepted, implements inside the order module boundary, adds a focused test for the 404 branch, runs verification, then marks the record Implemented with the real files and fresh results.

When to use it

• A feature, refactor, test-only change, or maintainability improvement.
• The change affects product behavior and needs alignment before implementation.
• The task spans several turns and corrections must keep their context.
• You want one explicit approval point before any code is written.

When to reach for something else

Questions