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

StateMeaningExit evidence
Queued / PreparingWaiting, then setting up an isolated workspaceAuthorisation and prepared revision recorded
ExecutingEngine is proposing changesRun event and candidate revision recorded
Validating / RemediatingChecks run; bounded fixes may followTrusted check results for the exact revision
ReviewA checked change request is availableRequired acceptance or rejection event
CompletedThe agreed acceptance condition occurredAccepted revision and approving event
Blocked / FailedA decision is needed or execution ended unsuccessfullyReason, evidence and next owner
Cancelled / Timed outExecution was stopped or exceeded its limitTermination confirmation and cleaned-up resources

Step-by-step process

  1. 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.

  2. Resolve the execution boundary

    Pin the repository and revision, select approved validation and permission profiles, and set cost, runtime and remediation limits.

  3. Validate the contract before dispatch

    Reject missing acceptance criteria, unknown profiles, unauthorised repositories and impossible combinations of scope and permissions.

  4. 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.

  1. The owner supplies synthetic records, a postcode query and the expected filtered page. They confirm the existing API response must remain compatible.
  2. The orchestrator resolves the approved checkout and creates a development-only worker with a disposable test database.
  3. The validator detects a migration in the proposed diff. It blocks publication and records the scope violation rather than treating passing tests as permission.
  4. 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

A contract determines what can enter execution and which evidence permits each state change. A checked proposal reaches Review; acceptance is a later event.
ProcessDecisionHuman checkpoint
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.

Sources and further reading