SMALL

How to Use SMALL

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

SMALL is Execution as Code: explicit intent, declared constraints, validated plans, append-only progress, deterministic handoff.

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

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

SMALL is analogous to Terraform in one specific way:

Terraform makes infrastructure explicit and reviewable. SMALL makes execution explicit and reviewable.

Terraform manages desired infrastructure state. SMALL manages desired execution state and continuity.

This is not "AI magic." This is execution governance.

CLI Command Model

The CLI follows a Terraform-like lifecycle.

Implemented

small init

Create a .small/ directory with scaffolded artifacts.

small validate

Validate all SMALL artifacts against schemas.

small lint

Enforce invariants and protocol rules.

small handoff

Generate a deterministic resume artifact from current state.

small verify

Run validate + lint + project checks (often via Make).

Planned

These commands are on the roadmap but not yet implemented.

small plan

Generate or update a task plan from intent and constraints.

small status

Summarize current execution state from artifacts.

small apply

Run an agent bounded by intent and constraints.

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