SMALL

Reference workflow

SMALL is designed to make agent work resumable and verifiable. This workflow is the default.

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

Replay IDs identify executions. Progress entries record evidence of work completed. Handoff enables 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

    • Make changes in the repo normally.

  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.
  • Handoff is the only resume entrypoint.
  • If it is not evidenced, it did not happen.
  • Plans may change; reconcile to reality when they do.

Plan Reconciliation

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

When work completed does not match the plan:

  1. Update plan.small.yml to reflect the actual work that was completed
  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.