Quick Start

Run all small commands from your repository root. If executed inside .small/, SMALL will still resolve the workspace automatically.

Initialize a SMALL Workspace

small init creates the stable v1 profile. V2 is an explicit migration from a reviewed v1 workspace; it is never selected implicitly.

bash

small init --intent "My project description"

This creates a v1 .small/ directory with the five canonical artifacts:

text

.small/
|-- intent.small.yml
|-- constraints.small.yml
|-- plan.small.yml
|-- progress.small.yml
`-- handoff.small.yml

Verify the Environment

bash

small selftest       # Confirm CLI binary and runtime are functional
small doctor         # Diagnose workspace health (read-only)

Run these before starting work. If either fails, fix the issue before proceeding.

Validate Artifacts

bash

small validate

Check Project Status

bash

small status

What a SMALL Project Looks Like

A v1 SMALL project consists of five canonical artifacts plus workspace metadata. The v1 set is fixed; growth happens inside the artifacts. V2 uses the separate session/event layout described below.

text

.small/
|-- intent.small.yml        # Stable: what the work is
|-- constraints.small.yml   # Stable: what must not change
|-- plan.small.yml          # Grows: tasks added and updated
|-- progress.small.yml      # Append-only execution log
|-- handoff.small.yml       # Regenerated resume checkpoint
`-- workspace.small.yml     # Workspace metadata (kind, version)

Artifact Evolution

Artifact	Behavior
intent	Set once, rarely edited
constraints	Set once, rarely edited
plan	Grows over time
progress	Append-only
handoff	Regenerated on handoff
workspace	Generated by init

Opting into the v2 session profile

small init continues to create the stable v1 profile. Convert only a reviewed workspace and only through preview/apply:

bash

small migrate --to 2.0.0 --preview --namespace my-project-baseline --json > /tmp/migration.json
# Copy expected_input_digest from the preview:
small migrate --apply /tmp/migration.json --expect-state <digest>
small session start --label first-v2-session

The migrated workspace starts in solo mode unless --mode collaborative was explicitly selected during preview. See the Session Profile v2.