How to Use SMALL

SMALL is not a chat pattern, a harness, or a memory trick.

SMALL is explicit execution state: intent, constraints, plans, progress, and handoff as code.

Chat is an input method. The .small/ artifacts are the contract.

Implementation Note: This documentation describes the SMALL Protocol interface. The authoritative CLI implementation is maintained in the small-protocol repository on GitHub.

CLI Contract

The CLI --help output is the source of truth for commands, flags, and exact usage. This documentation explains workflow intent and common use cases, not every flag permutation. For precise command reference, always run small <command> --help.

Execution Model

SMALL v1 is a single-writer profile. Cooperative mutations in one checkout are serialized with a local lock, but v1 has no distributed lock or semantic merge model.

SMALL v2 adds attributed sessions and immutable events. A v2 workspace starts in solo mode and permits one active writer. Collaborative mode is opt-in; when independent histories meet, the reducer preserves compatible events and turns incompatible task, policy, mode, or evidence claims into explicit conflicts. Nothing is resolved by last-write-wins.

Both profiles are deterministic and auditable. Neither profile schedules agents, selects models, executes background jobs, or merges source code.

What SMALL Does Not Do

SMALL does not:

Orchestrate multi-agent coordination
Execute code or run jobs
Make autonomous decisions
Run in the background

SMALL does not allow:

Implicit execution
Hidden state mutation
Agent-to-agent delegation
Silent side effects

If an action cannot be explained, recorded, and replayed, it does not belong in SMALL.

The Core Model

SMALL is used by creating and maintaining a .small/ directory inside a project.

This directory contains the canonical execution state for agent-driven work.

Chat history, editor buffers, and model memory are not canonical.

The canonical state is:

Inspectable
Versioned
Validated
Resumable

Choose a profile

small init creates v1. Migrate only a reviewed workspace, and always preview the exact input digest first:

bash

small migrate --to 2.0.0 --preview --namespace my-project-baseline --json > /tmp/migration.json
small migrate --apply /tmp/migration.json --expect-state <digest>
small session start --label implementation

The migration preserves every original v1 byte under an immutable import ID and starts in solo mode unless collaborative mode was explicitly selected. See Session Profile v2 for the full lifecycle.

Who Writes the v1 `.small/` Artifacts?

There are three valid workflows.

Human-first (Recommended Default)

A human defines intent and constraints.
An agent generates a plan.
The agent appends progress as work is performed.
A handoff is generated at checkpoints.

Humans own intent and constraints. Agents operate within them.

CLI-first (Recommended for Teams)

Developers use explicit CLI commands such as small init, small plan, small status, small check, and small handoff to scaffold and maintain artifacts.
Flag-driven commands keep structure, ownership, and execution state explicit on disk.
Validation and linting are enforced consistently.

This removes "where does this live?" and "what's authoritative?" questions.

Agent-first (Acceptable for Solo Work)

An agent generates .small/ artifacts from a task description.
A human reviews and adjusts intent and constraints.
Validation and linting prevent silent drift.

This is acceptable only because SMALL enforces correctness after generation.

Where Instructions Live

Chat messages are not authoritative.

The authoritative instruction set is:

intent.small.yml
constraints.small.yml

The authoritative execution record is:

progress.small.yml

The authoritative resume point is:

handoff.small.yml

If it is not in these artifacts, it is not part of the execution contract.

Those filenames describe v1. In v2, human policy, session descriptors, immutable events, resolutions, imports, and receipts are separate authoritative records. Inspect them through small status, small policy, small session, small reconstruct, and small reconcile rather than assuming v1 paths.

The CLI Is the Interface

While SMALL is a protocol, the primary user interface is the CLI (or tools that wrap it).

The CLI exists to:

Create correct artifacts
Validate schemas
Enforce invariants
Generate deterministic handoffs

This is the practical entry point for adoption.

Terraform Analogy

A useful mental model for SMALL is Terraform.

Terraform does not execute infrastructure in the abstract. It declares desired state, computes transitions, applies them, and records state durably.

SMALL works the same way, but for AI-assisted work.

SMALL does not decide tasks or orchestrate workflows. small apply invokes one operator-supplied child command and records its outcome; it is not a scheduler or retry loop.

Work selection and workflow execution remain with external tools such as agents, CI systems, or harnesses. SMALL governs the state those systems read and write.

Workspace Metadata and Where SMALL Writes

SMALL writes runtime artifacts to ./.small/ by default (root workspace).
For local development, ./.small/ is expected to be uncommitted and ignored by git.
Use the --workspace flag with any command to scope to a named workspace. This allows isolated .small/ directories within a single project.
To prevent accidental use of the wrong workspace, SMALL uses ./.small/workspace.small.yml to declare the workspace kind.
Valid kinds:
- repo-root - your local repo workspace
- examples - a committed example workspace
If you see: workspace metadata missing, run small init --force --intent "Dev workspace" and then small check --strict.

Workspace Flag Support

The --workspace flag is available on most commands to scope operations to a named workspace:

small plan --workspace <name>
small apply --workspace <name>
small progress add --workspace <name>
small checkpoint --workspace <name>
small check --workspace <name>
small handoff --workspace <name>
small reset --workspace <name>

When not specified, --workspace defaults to the root workspace at ./.small/.

V1 Progress and State Mutation

Progress entries are the canonical record of work performed. The progress.small.yml file is append-only: once written, entries are never modified or deleted.

How Progress Is Recorded

Do not edit progress.small.yml manually. Progress entries should be written exclusively via CLI commands:

small progress add: Record a single progress entry for work that does not have a corresponding task or that requires a manual heartbeat.
small checkpoint: Update task status in plan.small.yml and append a progress entry atomically.

small progress add

Append a single progress entry to progress.small.yml.

Generates RFC3339Nano timestamps automatically
Strictly monotonic (timestamps always increase)
Typical use cases:
- Recording non-shell work (design, writing, refactors)
- Long-running tasks that need periodic heartbeat updates
- Agent runs that require durable audit state without task status changes

Example use cases:

Agent performing research and takes a checkpoint
Human documents manual work performed offline
Background process records periodic progress

small checkpoint

Accept a task as completed or blocked and append the acceptance evidence in one atomic operation. Use small progress add --status in_progress to record task start without accepting an outcome.

Combines plan mutation and progress recording
Essential for deterministic task lifecycle management
Each checkpoint operation is auditable and durable

This is the recommended way to advance task state.

Plan Reconciliation

Plans are forward-looking and may diverge from reality.

If work completed does not match the plan, use the reconciliation pattern:

Update the plan through small plan commands to reflect the actual work that was completed; add replacement tasks and explicitly block superseded tasks rather than rewriting history

Record reconciliation as a progress entry:

bash

small progress add --task meta/reconcile-plan --status completed --evidence "Reconciled plan: [details of changes]"

Key rules:

Never delete or rewrite progress entries. They are append-only.
Never claim that the old plan is still accurate if it isn't.
Document what changed and why in the evidence field.

This ensures:

The audit trail remains complete and honest
Reality and plan stay synchronized
Future agents have accurate context
No hidden state mutations

CLI Command Model

The CLI follows a Terraform-like lifecycle.

Implemented

`small init`

Scaffold .small/ artifacts. When workspace metadata is enabled, also creates workspace.small.yml.

`small check`

Run all enforcement gates: validate, lint, and protocol verification. Recommended as the default enforcement command for both humans and CI. Use small check --strict before handoff or archive when you need full invariant enforcement.

Exits with non-zero status if:

Workspace metadata is missing or invalid
Artifacts fail schema validation
Invariants are violated
replayId is absent from handoff
Completed tasks lack evidence entries

`small validate`

Validate all SMALL artifacts against schemas. Available for advanced usage; small check is recommended for most workflows.

`small lint`

Enforce invariants and protocol rules. Available for advanced usage; small check is recommended for most workflows.

`small plan`

Manage tasks and dependencies inside plan.small.yml.

`small progress add`

Append a single progress entry to progress.small.yml. See "Progress and State Mutation" section above.

`small checkpoint`

Update task status in plan.small.yml and append a progress entry atomically. See "Progress and State Mutation" section above.

`small status`

Summarize current execution state from artifacts.

`small apply`

Execute a single bounded command and record the outcome to progress.

Optional behavior:

Associate execution with a specific task by task_id
Automatically record progress with command output
Explicitly request --auto-checkpoint; successful acceptance also requires reviewed --acceptance-evidence

Emphasis: small apply runs exactly one command. It is not an orchestration tool. By default it records command and persistence outcomes without accepting or rejecting the task.

`small handoff`

Generate handoff.small.yml as a deterministic resume artifact. Includes replayId with value and source.

`small reset`

Reset runtime workspace for a new run (if present in your CLI).

`small selftest`

Run a built-in verification that the CLI binary, runtime layout, and schema access are all functional. Run after install or upgrade to confirm the tool is ready.

`small doctor`

Read-only diagnostic that inspects your .small/ directory and reports on artifact health: missing files, schema violations, ownership inconsistencies, and version mismatches. Run when something feels off or as a pre-flight check before starting a session.

Version Flag

The root command supports small --version and small -v as standard CLI version flags. Output matches small version.

Notes

Root .small/ is runtime state. It should stay local and be gitignored in the spec repo.
examples/**/.small/ is where committed, reviewable example runs live.

Enforcement Rules

The CLI enforces strict rules for workspace integrity, replay identity, and progress tracking. These rules enable small check to act as a CI gate.

Workspace Enforcement

The CLI can require a workspace metadata file: .small/workspace.small.yml

Valid kind values:

repo-root - The primary SMALL workspace at repository root
examples - Committed example runs in examples/**/.small/

small check fails if workspace metadata is missing or invalid, allowing CI to block non-compliant runs.

yaml

# .small/workspace.small.yml
small_version: "1.0.0"
kind: "repo-root"

ReplayId Enforcement

handoff.small.yml must include replayId with two fields:

replayId.value - 64-character lowercase hex string (SHA-256)
replayId.source - Either auto or manual

When source is auto, the value is a deterministic hash of run-defining artifacts (intent + plan + optional constraints). When source is manual, the CLI accepts a hex string and normalizes it to lowercase on write.

yaml

# handoff.small.yml (excerpt)
replayId:
  value: "a1b2c3d4e5f6..."
  source: "auto"

Progress Enforcement

Progress entries must satisfy two rules:

Evidence gate - Completed tasks in plan.small.yml must have matching progress entries in progress.small.yml with evidence populated.
Timestamp gate - Timestamps must be RFC3339Nano format with fractional seconds, and must be strictly increasing.

yaml

# progress.small.yml (excerpt)
entries:
  - timestamp: "2025-01-15T10:00:00.123456789Z"
    task_id: "task-1"
    status: "completed"
    summary: "Created auth middleware"
    evidence:
      - type: "commit"
        ref: "abc123"

Why SMALL Exists

Most agent systems fail because:

Intent is implicit
State is invisible
Execution is ungovernable
Resuming work requires re-explaining everything

SMALL exists to make failure survivable and execution auditable.

Next Steps

Reference Workflow - The default workflow for agent-driven work.
Primitive Specification v1 - Formal definitions of all primitives.
Glossary - Terminology and definitions.

How to Use SMALL

CLI Contract

Execution Model

What SMALL Does Not Do

The Core Model

Choose a profile

Who Writes the v1 .small/ Artifacts?

Human-first (Recommended Default)

CLI-first (Recommended for Teams)

Agent-first (Acceptable for Solo Work)

Where Instructions Live

The CLI Is the Interface

Terraform Analogy

Workspace Metadata and Where SMALL Writes

Workspace Flag Support

V1 Progress and State Mutation

How Progress Is Recorded

small progress add

small checkpoint

Plan Reconciliation

CLI Command Model

Implemented

small init

small check

small validate

small lint

small plan

small progress add

small checkpoint

small status

small apply

small handoff

small reset

small selftest

small doctor

Version Flag

Notes

Enforcement Rules

Workspace Enforcement

ReplayId Enforcement

Progress Enforcement

Why SMALL Exists

Next Steps

Who Writes the v1 `.small/` Artifacts?

`small init`

`small check`

`small validate`

`small lint`

`small plan`

`small progress add`

`small checkpoint`

`small status`

`small apply`

`small handoff`

`small reset`

`small selftest`

`small doctor`