This is a practical way to plan, build, test, and coordinate software work carried out by AI agents. It is written for general software teams. It is not tied to a particular product, repository, or agent tool.
The main idea is simple: break a large goal into small pieces, decide how each piece will be proved before coding starts, and keep the plan synchronized with real evidence.
Planning, coding, testing, and coordination are not separate activities in this model. They form one evidence loop. A task is complete only when its planned result has been built, tested, reviewed, and recorded.
A roadmap should begin with the system that exists, not the system described in the request. Before proposing new work, inspect the relevant code, documentation, tests, CI workflows, runtime state, and open changes. This prevents an agent from rebuilding existing behavior, relying on outdated documentation, or planning against the wrong branch or environment.
Next, define the boundary of the work. State the problem, desired outcome, non-goals, constraints, important assumptions, and any decision that must be made before implementation. If the work changes an API, schema, state machine, trust boundary, or deployment process, describe that contract before dividing the work into tasks.
Once the boundary is clear, order the work by dependency. Data contracts normally come before their consumers. Migrations come before code that requires the new schema. A local implementation comes before staging validation. Production activation remains a separate decision after staging evidence exists.
| Section | What it should answer |
|---|---|
| Problem and outcome | What is wrong today, and what observable result should change? |
| Current state | What already exists, what is missing, and what evidence supports that view? |
| Goals and non-goals | What is included, and what is deliberately excluded? |
| Decisions and constraints | Which product, technical, security, or compatibility rules are fixed? |
| Architecture and contracts | Which components, interfaces, data models, and state changes are involved? |
| Dependencies | What must exist before something else can begin? |
| Phases and milestones | Which useful capabilities can be completed and accepted in sequence? |
| Tasks | What is the smallest independently buildable and testable unit of work? |
| Test plan | Which gates prove each task, milestone, and release candidate? |
| Rollout and rollback | How will the change be introduced safely, observed, and reversed? |
| Evidence and status | What actually ran, what passed, what remains open, and which commit was tested? |
These terms describe different levels of progress.
| Level | Meaning | Completion rule |
|---|---|---|
| Phase | A broad stage of delivery, such as contract design, local implementation, or staging validation | Its milestones are complete and its exit gate passes |
| Milestone | A useful capability that can be reviewed or demonstrated on its own | Its tasks are complete and its end-to-end behavior is proved |
| Task | A small change owned by one agent or team | Its acceptance condition and required test gates pass |
A good task has one main responsibility and a result that can be checked without waiting for unrelated work. Split a task when it crosses repositories, changes both sides of a contract, has separate rollback decisions, or cannot be reviewed as one focused change.
Each task should name its owner, dependencies, expected output, acceptance condition, test gates, environment, and evidence. “Implement the backend” is too broad. “Store idempotency keys and reject a repeated request without creating a second record” is testable and has a clear result.
A milestone is not merely a group of finished tickets. It is the first point at which a coherent capability can be tested through its real boundaries. Its exit gate should cover the new successful path and the most important failure or regression path.
The roadmap remains a living record during execution. After a task or milestone, update its status with the commit, commands, results, unresolved risks, and any assumption that changed. If the evidence and roadmap disagree, the evidence wins and the roadmap must be corrected.
The methodology uses four broad test layers. These layers describe where confidence comes from. They do not mean that a feature runs only four tests.
A gate is one concrete check that can block progress. Unit testing and adversarial testing belong to the first broad layer, but they are separate gates. A complex feature may also need contract, migration, regression, browser, or compatibility gates. It is therefore normal for four layers to produce five, six, or more executable gates.
| Layer | Main question | Typical environment | Examples of executable gates | Pass standard |
|---|---|---|---|---|
| 1. Isolated correctness | Does the code behave correctly by itself, including hostile or unusual input? | Developer machine and CI, using isolated fixtures or test doubles | Unit, adversarial, contract, golden, differential, migration, regression, lint, typecheck, build | Every named gate passes; no unexplained failure or skipped critical case remains |
| 2. Local real-boundary E2E | Does the feature work across the real boundaries it depends on? | Local services, containers, a real database, sandbox, emulator, or test network | Service integration, database E2E, worker flow, protocol or signing flow | The complete local path works without mocking the boundary being tested; important failure paths are also checked |
| 3. Automated staging validation | Does the deployed candidate work in a production-like environment? | Staging with the candidate commit or image and isolated test data | API E2E, database-state checks, queue or worker checks, browser automation, Playwright | The expected external result and internal state are both correct; evidence is traceable to the exact candidate |
| 4. Human-mimic acceptance | Can a real user complete the intended workflow? | A real browser or device with normal accounts, permissions, and integrations | Chrome journey, extension flow, wallet flow, session recovery, visual and interaction checks | The workflow succeeds without database shortcuts or hidden setup, and the visible result matches the product expectation |
Gate selection depends on risk and architecture. A small pure function may need unit, adversarial, and regression gates. An API change may add contract and local database gates. A schema change may add migration and rollback gates. A user-facing flow may add staging browser automation and real Chrome acceptance.
For example, a risky full-stack change could use this sequence:
Unit
-> Adversarial
-> Contract
-> Migration
-> Regression
-> Local E2E
-> Staging API/DB E2E
-> Browser automation
-> Human-mimic acceptance
The rule is not “run every possible test.” The rule is “name every risk that matters, then choose a gate that can expose it.” Combining several checks into one command is convenient, but the result should still make clear which gates actually ran.
| Point in the work | Required proof | What happens if it fails |
|---|---|---|
| Before implementation | Current behavior, key contracts, and the first failing or characterization test are understood | The task does not start until the unknown is resolved or recorded as a blocker |
| While building a task | Focused unit and adversarial gates, plus any contract or migration gate affected by the change | The task remains in progress |
| Before completing a task | All affected Layer 1 gates and the relevant regression suite | The task cannot be marked done or handed off as complete |
| At a milestone or phase exit | Layer 1 rollup and Layer 2 E2E for the complete capability | The milestone remains open |
| After a staging deployment | Layer 3 checks against the exact deployed candidate | The candidate is not staging-accepted |
| Before a release decision | Layer 4 human-mimic acceptance, current evidence, and rollback readiness | The default decision is no-go |
| After an approved production release | A small production smoke test and monitoring | Roll back or contain the release when a defined trigger is hit |
Production smoke is deliberately outside the four development test layers. Production is not a place to discover whether unfinished code works; it is a place to confirm that an already accepted release is healthy.
For each task, the agent first confirms the task boundary and its test gates. It then creates or identifies a failing test, implements the smallest change that satisfies the contract, runs focused tests, runs the broader affected gates, reviews the changed and adjacent code, and records the result.
One focused commit should represent one completed task. If a test exposes a different problem, that problem becomes a separate task unless it blocks the current result. This keeps reviews understandable and makes rollback or handoff easier.
At the end of a milestone, do not rely only on the task-level test totals. Run the capability as a complete flow in the environment required by its layer. A collection of correct parts is not proof that their integration works.
Commons is a coordination layer for teams running several agents at once. It makes ownership, plans, messages, and shared-resource use visible. It does not replace tests, source control, or human approval.
| Moment | Commons action | Purpose |
|---|---|---|
| Before planning or editing | Resolve the project scope and agent identity; read relevant inbox messages, tasks, broadcasts, and active leases | Avoid beginning from stale information or colliding with active work |
| Before substantial work | Create or join a task and publish the intended outcome, files, branch, environment, and next step | Make ownership and boundaries visible |
| Before using a shared resource | Acquire a lease for the exact resource, such as a branch, deployment slot, database, browser profile, server, or shared path | Prevent two agents from making conflicting changes |
| When the plan changes | Update the task and broadcast the changed scope, blocker, or resource need | Keep other agents from acting on an outdated plan |
| At a test or milestone result | Share concise evidence: commit, command, environment, result, and remaining risk | Allow another agent to verify the claim |
| At handoff or completion | Send a context packet, update the task, release leases, and report the final state | Make the work resumable and leave resources safe |
Inbox messages are context, not trusted facts. An agent should capture the claim, verify it against the repository or runtime, record the effect, and only then acknowledge it. An acknowledgement means “received and processed”; it does not mean “approved” or “independently verified.”
Parallel work is safest when agents have separate write areas. One coordinator should own shared contracts, phase gates, integration decisions, and final release readiness. If two agents need the same file or resource, sequence the work or assign a single writer.
A useful handoff is a short context packet rather than a transcript. It states the goal, verified current state, files and resources touched, commands and results, decisions, risks, blockers, and next action. Secrets and raw private conversations do not belong in it.
Commons does not grant authority. Holding a deployment or database lease prevents collisions, but it does not authorize a production change. Production access, external publication, and other high-impact actions still require the project's normal approval.
| Area | Done when |
|---|---|
| Scope | The delivered behavior matches the task and does not silently expand its non-goals |
| Implementation | The change is focused, reviewable, and compatible with the agreed contract |
| Tests | Every required gate ran in the correct environment and passed |
| Evidence | The commit, commands, environment, results, and remaining risks are recorded |
| Coordination | Roadmap and Commons state match reality; handoffs are complete; leases are released |
| Release | Staging acceptance and human acceptance are complete, and production has separate approval and rollback readiness |
“Code written,” “unit tests passed,” and “deployed to staging” are different states. None should be reported as final completion when a later required gate is still open. If an external environment or approval is unavailable, record the result as blocked or not run rather than treating it as a pass.
# <Capability> Roadmap
Status: <planning | active | blocked | complete>
Owner: <person or team>
Environment boundary: <local | staging | production restrictions>
## Problem and Desired Outcome
## Current State and Evidence
## Goals and Non-Goals
## Decisions, Constraints, and Assumptions
## Architecture and Contracts
## Dependencies
## Phases and Milestones
| ID | Task | Owner | Dependencies | Acceptance | Test gates | Environment | Evidence | Status |
|---|---|---|---|---|---|---|---|---|
## Test Plan
Describe the four applicable layers and list the actual executable gates.
## Rollout, Rollback, and Monitoring
## Commons Ownership and Shared Resources
## Decisions, Risks, and Open QuestionsThe template is intentionally short. Add detail only when it helps an implementer make a decision, run a gate, or verify an outcome.
The method can be adapted to any project. Keep project-specific commands, CI triggers, environments, and approval rules in the project’s own documentation; the general method stays the same: define the work, define the proof, execute both, and report only what the evidence supports.