Unfolder

A program that writes programs: deterministic harness (tree, scheduler, verification) with a tiny LLM as one computing layer for semantic fills.

See docs/PARADIGM.md and docs/VERIFICATION.md.

Setup (uv)

Requires uv.

uv sync --all-extras
cp ../research-watch/.env .env   # or copy OPENAI_API_KEY only

Quick start

uv run unfolder init
uv run unfolder plan "A CLI that prints hello" --heuristic
uv run unfolder status

V2: multi-agent swarm pipeline

Layer-bound swarm architecture (docs/V2_ARCHITECTURE.md, docs/V2_IMPLEMENTATION.md): spec swarm → blueprint swarm (tree.yaml) → deterministic materialization → implementation swarms (upward invalidation, sibling locking) → acceptance swarm.

uv run unfolder v2 build "A tiny expense tracker library" --project /tmp/app   # full pipeline
uv run unfolder v2 spec "..."        # phase 1 only (interactive elicitation)
uv run unfolder v2 status --project /tmp/app

Add --headless to let the spec swarm decide instead of asking questions.

From-scratch build (complex app proof)

The harness receives only a spec and acceptance tests — no src/. It must generate the full application.

uv run unfolder build run --target-id ledger-cli --heuristic --dest /tmp/ledger --keep

With OpenAI (harness + LLM only, no reference finalize):

uv run unfolder build run --target-id ledger-cli --dest /tmp/ledger-llm

Target layout: examples/verify-target/ contains SPEC.md, tests/, pyproject.toml — no src/.

Development

./scripts/e2e.sh              # full quality gate (recommended before handoff)
uv run pytest tests/ -q
uv run ruff check src tests
uv run unfolder viz --open    # requires viz extra

See HANDOFF.md for the complete checklist.