← All features

Define the workAvailable in v0.3.0

Intent, scope and packets

A packet holds everything about one task: intent, scope, plan, acceptance gates and return format. The intent states the problem, desired outcome and checkable success conditions, must be accepted before it binds to a lease, and travels byte for byte to every stage, worker and reviewer. Every return ends with one AC line per success condition.

When you need it

When the goal lives only in a chat, each stage and reviewer works from a slightly different version of it, and “done” drifts away from what you actually asked for.

How it works

  1. oah packet new <task> writes .oah/tasks/<task>/PACKET.md from a template and scores the stage routes into its ## Plan; oah packet check <task> says what is still missing.
  2. The intent holds Problem, Desired outcome and Success conditions (AC1, AC2, …). Success conditions are outcomes you can check, not process steps.
  3. Status: draft cannot be bound to a lease (OAH_INTENT_NOT_ACCEPTED). Intent-ID never changes; a changed goal raises Revision, which you accept and rebind.
  4. oah intent show <task> prints the binding state: current, stale, missing or unbound.
  5. Every return ends with INTENT <id>@r<n> <digest> and one AC<n>: met|unmet|deferred — <evidence> line per success condition, checked by oah finish --return and each review round.
  6. oah preflight --task T aborts when your branch is behind or another lease holds your paths, warns about a dirty tree or new commits touching your scope, and lists what it did not prove.

Example

The intent filled in for the worked example's task.

Status: accepted
### Problem
`python hello.py` always prints `Hello, world!`; it cannot greet a person by name.
### Desired outcome
`python hello.py Ada` prints `Hello, Ada!`, and without a name it still prints `Hello, world!`.
### Success conditions
- AC1: `python hello.py Ada` prints `Hello, Ada!`.
- AC2: the unit tests pass, including a test for a name.

Requirements

  • A Scope with at least one path, or - repo for the whole repository; oah packet new <task> --scope <path> fills it for you.

Limits and recovery

  • An empty ## Scope warns OAH_SCOPE_EMPTY, and oah start --packet refuses it.
  • Template placeholders left in the intent refuse with OAH_PACKET_PLACEHOLDER.
  • Editing the packet after binding makes the binding stale (OAH_INTENT_NOT_CURRENT): restore it, or raise Revision, accept and rebind.
  • A return that does not match the bound intent refuses with OAH_INTENT_RETURN_INVALID.
  • Preflight warnings do not stop you; an ABORT verdict (exit code 2) must be fixed first.

Original documents

Related