START HERE
What you will learn
- Turn a vague request into testable acceptance criteria.
- Distinguish descriptive permission fields from enforced controls.
- Define lifecycle states and durable identifiers for trustworthy status updates.
Before you start: Bring a small development ticket, the repository owner and an example of how its expected behaviour can be tested.
Reference edition: Provider-neutral reference design; named tools are implementation examples. Sources checked 2026-11-12.
A good ticket still needs execution details
“Fix property search” leaves important questions unanswered. Which repository and base revision? What does a valid postcode look like? Should the change affect pagination? May the worker alter a schema, install a new dependency or change an API? A contract resolves these questions before execution.
Capture the objective, permitted areas, explicit exclusions, acceptance criteria, validation commands, time and cost budgets, owner and completion action. Repository-specific instructions explain how the project works; the task contract explains what this run is authorised to do. Neither should contain secrets.
Separate identity, intent and authority
Give a logical task one task ID and each execution attempt its own execution ID. Persist the external source reference, repository identifier, base commit, branch, change request, resulting commit, test evidence and final state. A retry is another attempt at the same task, not an unrelated work item.
Resolve repository and workspace paths from trusted configuration. Do not let ticket text choose an arbitrary checkout URL, local directory, executable or shell command. An approved engine profile selects the runner and model settings. The contract can request a profile, but the orchestrator must authorise it.
Permission fields describe policy; they do not enforce it
A JSON value saying deploy_production is false cannot prevent a process from using a production credential that was accidentally mounted. Pair each field with a control: scoped tokens, no production network route, restricted mounts, protected branches and a separate publisher or deployment identity.
For a task that prohibits schema changes, inspect the diff for migrations and other schema-related files and require a separately authorised review if any appear. Path checks alone do not establish semantic safety: application code or dependencies can also execute database operations. Use disposable databases, restricted credentials and independent validation as well.
A lifecycle should explain what happened
Queued means accepted work is waiting for capacity. Preparing covers checkout and dependency setup. Executing covers implementation. Validating evaluates the proposed revision. Remediating is a bounded attempt to address a specific failure. Review means a change request is ready for review, not that it has been accepted.
Completed requires the acceptance event defined by your process, such as an approved merge. Blocked means a person or external decision is required; Failed means the run ended unsuccessfully. Add Cancelled and Timed out where these outcomes matter. An engine exit code must not silently move a task from Executing to Completed.
Keep status synchronisation reliable
Persist each state transition before publishing an update to the source task. Store pending outbound updates with the transition, using a transactional outbox or an equivalent durable mechanism. A synchronisation job can then retry safely if the project tool is unavailable.
Every event needs an ID, execution ID and sequence or revision. Consumers should ignore duplicate updates and refuse stale transitions. Verify the current repository state when reconciling acceptance: a delayed “checks passed” message for an earlier commit must not overwrite a later failed result. Redact secrets and customer information before storing events or sending them to a project tool.
Technical examples
Illustrative task contract
This example is tool-neutral. Repository IDs, validation profiles and permission profiles resolve through trusted server configuration. These fields are a design example, not a complete executable schema.
{
"schema_version": "1",
"task_id": "DEV-1042",
"execution_id": "run-001",
"source": {
"system": "project-tool",
"record_id": "1042"
},
"repository_id": "reports-app",
"base_commit": "<approved-commit-sha>",
"branch": "agent/DEV-1042",
"objective": "Filter property search by postcode without changing pagination",
"scope": {
"allowed_areas": [
"search application code",
"search tests"
],
"excluded": [
"database schema",
"public API contract",
"release configuration"
]
},
"acceptance_criteria": [
"Approved postcode examples return only matching records",
"Pagination preserves the selected filter",
"Existing API response shape is unchanged"
],
"validation_profile": "search-regression-v1",
"permission_profile": "development-no-production",
"limits": {
"timeout_minutes": 20,
"max_remediation_attempts": 2,
"max_cost_units": 5
},
"completion": {
"publish_change_request": true,
"source_status": "review",
"requires_acceptance_event": true
}
}States with explicit exit evidence
| State | Meaning | Exit evidence |
|---|---|---|
| Queued / Preparing | Waiting, then setting up an isolated workspace | Authorisation and prepared revision recorded |
| Executing | Engine is proposing changes | Run event and candidate revision recorded |
| Validating / Remediating | Checks run; bounded fixes may follow | Trusted check results for the exact revision |
| Review | A checked change request is available | Required acceptance or rejection event |
| Completed | The agreed acceptance condition occurred | Accepted revision and approving event |
| Blocked / Failed | A decision is needed or execution ended unsuccessfully | Reason, evidence and next owner |
| Cancelled / Timed out | Execution was stopped or exceeded its limit | Termination confirmation and cleaned-up resources |
Step-by-step process
Agree one behavioural example
Write a failing input and its expected output. Include one regression you must preserve and one thing the task must not change.
Resolve the execution boundary
Pin the repository and revision, select approved validation and permission profiles, and set cost, runtime and remediation limits.
Validate the contract before dispatch
Reject missing acceptance criteria, unknown profiles, unauthorised repositories and impossible combinations of scope and permissions.
Map every transition to evidence
Define which service may write each state and how it verifies the event. Keep source-task updates separate from execution success.
FOLLOW ONE EXAMPLE
Worked scenario
A postcode ticket becomes an executable boundary
A ticket says “Search is broken for one postcode.” The developer has access to a Laravel-style backend and a TypeScript frontend, but the task must not alter the database schema.
- The owner supplies synthetic records, a postcode query and the expected filtered page. They confirm the existing API response must remain compatible.
- The orchestrator resolves the approved checkout and creates a development-only worker with a disposable test database.
- The validator detects a migration in the proposed diff. It blocks publication and records the scope violation rather than treating passing tests as permission.
- The owner either narrows the implementation to the authorised scope or approves a separately assessed task. The original contract is not silently expanded.
What this shows: The worker can act without repeated prompts because its boundaries are defined in advance. Work outside them becomes a visible decision.
The process at a glance
Read Mermaid diagram source
flowchart TD
T[Vague ticket] --> N[Normalise objective and examples]
N --> A{Authority and scope valid}
A -->|No| B[Blocked with named owner]
A -->|Yes| Q[Queued]
Q --> P[Preparing]
P --> E[Executing]
E --> V[Validating]
V -->|Allowed repair| M[Remediating]
M --> E
V -->|Checks pass| R[Review]
R --> H[Acceptance event]
H --> C[Completed]
V -->|Limit or policy failure| F[Failed or blocked]What you should have at the end
- A versioned, validated task contract with explicit exclusions and limits.
- A lifecycle and identifier mapping that supports retries without confusing acceptance with execution.
Common mistakes and how to avoid them
Treating prose as access control
Instructions help the engine reason. Platform permissions, credentials and review gates enforce authority.
Marking the source ticket done when a PR opens
A proposed change can still fail CI or review. Use Review until the agreed acceptance event is verified.
Letting an old callback win
Bind checks to the commit and execution attempt. Reconcile stale events rather than overwriting newer truth.
APPLY THE IDEA
Try it yourself
Your task: Rewrite one ambiguous bug report as a versioned task contract with three acceptance criteria and three exclusions.
What to produce: A redacted contract plus a table mapping each permission to an external enforcement control.
Check your understanding: Can a reviewer explain why the task would block, fail or complete without reading the agent transcript?
Key terms in plain English
- Acceptance criterion
- An observable behaviour that must hold for the requested change.
- Execution attempt
- One bounded run against a specified starting revision.
- Transactional outbox
- A durable record of an outbound update stored with the state change that requires it.
- Idempotent update
- An update that can be repeated without creating another logical effect.