SMALL

Reference workflow

SMALL is designed to make agent work resumable and verifiable. This workflow is the default. It describes v1; v2 keeps the same governance boundary but records lifecycle through attributed sessions and immutable events.

This workflow is defined in detail in How to Use SMALL.

In v1, replay IDs identify the run-defining state. In v2, project, session, event, and frontier identities preserve causality. Evidence-backed lifecycle records enable deterministic resumption.

Workflow

  1. Initialize SMALL artifacts

    • Create .small/ and commit it.

  2. Define intent and constraints

    • Intent is the why.
    • Constraints are the hard rules.

  3. Generate a plan

    • Plans are disposable and allowed to change.

  4. Execute work

    • Let the external agent, CI system, or harness perform the work. Use small apply when one bounded child command and its outcome should be captured.

  5. Append progress with evidence

    • Commit hashes, commands run, screenshots, links, test output.

  6. Generate a handoff

    • Run small handoff at checkpoints to generate a deterministic summary for another agent to resume.

  7. Verify

    • Run small check as the default enforcement gate. If check fails, the run is not compliant.
    • This command runs validate + lint + verify (workspace, replayId, progress evidence).
    • small verify is also valid for CI-specific enforcement.

Rules of the road

  • Progress is append-only.
  • V1 resumes from its explicit handoff; v2 reconstructs bounded session resume views from immutable records.
  • If it is not evidenced, it did not happen.
  • Plans may change; reconcile to reality when they do.
  • small apply records command outcome; only small checkpoint accepts a task.
  • A v2 workspace is solo unless collaborative mode was explicitly selected.
  • V2 conflicts require explicit reconciliation before strict handoff or snapshot.

For the v2 start/mode/close/resume flow, see Session Profile v2.

Plan Reconciliation

Plans are forward-looking proposals and may be wrong or need adjustment.

When work completed does not match the plan:

  1. Use small plan commands to add the actual work and explicitly block any superseded task; do not rewrite progress history
  2. Record the reconciliation as progress:
    bash 
    small progress add --task meta/reconcile-plan --status completed --evidence "Reconciled plan to match completed work: [description of changes]"

This keeps the audit trail accurate and prevents confusion between planned vs. actual work.

Replay ID vs Progress

Understanding the relationship between Replay IDs and Progress is essential:

  • replayId represents execution identity - a deterministic fingerprint of declared intent
  • Progress entries record evidence of completed work and reference tasks
  • Handoff captures the current state and includes the replayId for resumption

Deterministic Replay Guarantee

  • Reordering keys -> same replayId
  • Changing intent, plan, or constraints content -> different replayId

This is intentional. Identical intent produces identical execution fingerprints.

For more details on how Replay IDs work, see How SMALL Works.