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 is a single-agent state protocol by design.

Every SMALL execution assumes:

One active decision-making agent
One explicit execution context
One linear, auditable chain of actions

This constraint is intentional. By enforcing a single-agent model, SMALL guarantees:

Deterministic execution
Complete auditability
Explicit intent and scope
No hidden or emergent behavior

Multi-agent coordination, delegation, or negotiation is explicitly out of scope for SMALL v0.x.

If multiple agents are required, they must operate in separate SMALL projects, with coordination handled externally.

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

Who Writes the `.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 the SMALL CLI to scaffold and manage artifacts.
Interactive prompts remove ambiguity about structure and placement.
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.

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 execute tasks or orchestrate workflows. It defines intent, constraints, and lifecycle state, and records immutable state transitions as work progresses.

Execution is performed by external tools such as agents, CI systems, or harnesses. SMALL governs the state those systems read from and write to.

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"
- then small handoff
- then small check

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/.

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

Move a task from one status to another (pending -> in_progress, in_progress -> completed, in_progress -> blocked) and append a progress entry in a single atomic operation.

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 to reflect the actual work that was completed

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.

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`

Create or update plan.small.yml from intent and constraints.

`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
Optionally checkpoint the task on success or mark blocked on failure

Emphasis: small apply runs exactly one command. It is not an orchestration tool. It records intent, command, and outcome for auditability.

`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 doctor`

Diagnose common workspace issues (if present in your CLI).

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

Who Writes the .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

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 doctor

Notes

Enforcement Rules

Workspace Enforcement

ReplayId Enforcement

Progress Enforcement

Why SMALL Exists

Next Steps

Who Writes the `.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 doctor`