Skip to content

Task Authoring Standard

1. Purpose

Define a mandatory task-writing format so agent execution is deterministic, reviewable, and contract-safe.

This standard applies to every task in doc/governance/Agent_Work_Queue.yaml.

2. Required Fields Per Task

Each task must include the following fields:

  • id
  • title
  • role
  • priority
  • status
  • owner
  • branch
  • depends_on
  • acceptance_checks
  • notes

Queue validation should fail if any required field is missing.

3. Notes Block: Mandatory Sections

notes must be a YAML block scalar and include all sections below in order.

3.1 Context

  • One short paragraph explaining the business/runtime problem.
  • Must name the user-facing effect (for example: wrong field returned, auth scope leak, terminal silently disconnected).

3.2 Pre-Read (Required)

  • Explicit doc/file list that the implementer must read before coding.
  • Use concrete paths only (no “read docs” phrasing).

3.3 Invariants (Must Not Break)

  • 3 to 8 bullets of non-negotiable constraints.
  • Examples: canonical field names, state machine ordering, required error envelope shape, mandatory project scoping.

3.4 Scope

  • What is in this task.
  • What is explicitly out of scope (to prevent hidden expansion).

3.5 Deliverables

  • Concrete file-level outputs expected from this task.
  • Include contract/doc updates if behavior or payload shape changes.

3.6 Evidence Required in Handoff

  • Exact proof expected from implementer handoff:
  • files changed,
  • commit SHA,
  • exact acceptance commands run,
  • result summary.

4. Acceptance Checks Rules

  • Must be executable shell commands only.
  • Must include at least:
  • one targeted test command for changed behavior,
  • one broader suite command for regression safety.
  • For contract-impacting tasks, include a contract check command (for example make codegen, contract grep, or invariant gate).
  • “All tests pass” prose is not valid.

5. Contract and Error Discipline

If task changes API/event behavior:

  • Update spec first (doc/api/openapi.draft.yaml and/or doc/api/asyncapi.draft.yaml).
  • Keep canonical response/error shape:
  • {"code","message","correlation_id","details?"}
  • Do not rename fields ad-hoc; use contract names exactly.

Task notes must include the exact fields/codes affected.

6. Root-Cause Rule

Tasks must target root cause, not only symptom suppression.

If true root cause is out of scope:

  • mark task blocked,
  • create upstream follow-up task ID in queue,
  • reference it in handoff.

Do not mark done with temporary fallback only.

7. Review Checklist (Per Task)

Reviewer must confirm:

  1. Pre-read files were listed and relevant.
  2. Invariants are specific and testable.
  3. Acceptance checks are runnable and sufficient.
  4. Contract fields/error codes match spec exactly.
  5. Handoff evidence includes command outputs and commit SHA.

If any item fails, task returns to in_progress with explicit gaps.

8. Task Template

Use this template for new queue entries:

- id: A-EXAMPLE-001
  title: Short action-focused title
  role: A-backend
  priority: 10
  status: todo
  owner: agent-a
  branch: agent/A-backend
  depends_on: []
  acceptance_checks:
  - go test ./cmd/api ./packages/services/example
  - make test-integration-selected
  notes: |
    Context:
    <problem + user/runtime impact>

    Pre-read (required):
    - doc/path/one.md
    - doc/path/two.yaml
    - packages/path/file.go

    Invariants (must not break):
    - <invariant 1>
    - <invariant 2>
    - <invariant 3>

    Scope:
    - In: <what to implement>
    - Out: <what not to change>

    Deliverables:
    - <file/path + expected change>

    Evidence required in handoff:
    - files changed
    - commit SHA
    - exact acceptance commands run
    - pass/fail status by command