🍞 Loaf

"Why have just a slice when you can get the whole loaf?"

Loaf is an opinionated agentic framework that gives AI coding assistants structured knowledge, enforced tool boundaries, and a coherent workflow from idea to implementation to learning. Write your skills once, deploy to Claude Code, OpenCode, Cursor, Codex, and Amp.

Portable knowledge — Skills cover workflows, engineering standards, and language expertise. Build once, deploy to supported AI coding tools without rewriting anything.

Project journal model — A single SQLite-backed journal captures decisions and progress across every conversation, project-scoped and correlated by an opaque harness id. There is no session entity to open or close, so concurrent conversations across branches and worktrees stay conflict-free. Handoff artifacts live separately in .agents/handoffs/. Work survives context loss, compaction, and /clear.

Issue workflow — The Loaf Flow is pitch → shape → implement → ship → release. /pitch authors a problem-space narrative; /shape bounds an Issue in place (loaf issue new, body + DoD + out-of-scope; decompose with loaf issue promote only when a criterion earns its own DoD). loaf issue check validates readiness; work is built in a started worktree (loaf issue start). /ship is the sole quality gate (PR body is loaf issue render); /release cuts retroactively (loaf release suggest / cut).

Profile-based agents — Functional profiles are defined by tool access, not job titles. A Smith with python-development skills becomes a backend engineer; the same Smith with infrastructure-management becomes a DevOps engineer. Skills determine what an agent knows; the profile determines what it can touch.

Conversation continuity — Pick up exactly where you left off with full traceability. The project journal captures decisions and progress in SQLite; a derived, ephemeral digest (latest wrap + recent branch entries + open issues) is emitted at conversation start. Explicit transfer packets live in .agents/handoffs/ until housekeeping deletes them after deprecation.

Hooks as quality gates — Two hook types: enforcement hooks (pre-commit secrets scanning, pre-push linting) block bad commits automatically; skill instruction hooks inject context at tool invocation time. Language-aware and automatic.

Loaf keeps intent, implementation, and learning connected:

flowchart LR
    idea["/idea · spark<br/><i>capture — offline-safe, no ID</i>"] --> triage["/triage"]
    pitch["/pitch<br/><i>problem discovery</i>"] --> shape
    triage -- promote --> shape["/shape<br/><b>the Issue</b>: body · DoD · out-of-scope"]
    shape -- "criterion earns its own DoD<br/>loaf issue promote" --> shape
    shape -- "sharp question" --> decision["decision issue"]
    decision -- answered --> shape
    shape -- ready --> build["/implement<br/>loaf issue start: worktree · branch · PR"]
    build --> ship["/ship<br/><b>the sole quality gate</b>"]
    ship -- merge --> main[("main")]
    main -. "reads landed since last tag" .-> release["/release<br/>suggest → cut"]
    release -- "tag · notes · members as fact" --> main

Everything left of ship plans forward and can be re-planned freely — issues are recursive (loaf issue tree), questions too foggy to act on stay as prose until they sharpen into decision issues, and Now/Next/Later are advisory buckets. The release track only ever reads backward: a release is cut from what actually landed, so it can never contain unimplemented work. The journal records every step; /reflect and an optional /wrap preserve what the work taught.

Discover the problem, author a brief, then bound an implementable Issue (or bootstrap a project from a pitched BRIEF).

Implement a shaped issue through a started worktree and pull request, review the result, and land it through ship — the sole quality gate.

Integrate outcomes into strategic knowledge.

CLI commands that support the workflow:

Loaf uses functional profiles defined by mechanically enforced tool boundaries — not role titles, not domain labels. What an agent can do is fixed by its profile. What it knows comes from skills loaded at spawn time.

The main conversation is the Warden — it coordinates and delegates but never implements directly. See SOUL.md for the full fellowship identity.

Skills you invoke directly to drive work forward.

Explore and brainstorm are agent techniques (not user slash entry); agents reach for them when direction is undecided — human entry intent routes to /pitch.

Background skills that activate automatically during agent coordination and project management.

Background knowledge that activates automatically to enforce quality.

Domain expertise that loads based on project context.

Build once, deploy everywhere. Skills are the universal layer; profiles and hooks adapt per target.

brew tap levifig/tap
brew install loaf

Homebrew installs the native loaf binary plus Loaf's packaged content under the tap-managed prefix. Use brew upgrade loaf after releases.

/plugin marketplace add levifig/loaf

Updates happen automatically via plugin marketplace. Commands are scoped under loaf: (e.g., /loaf:implement).

npx github:levifig/loaf install

Detects installed tools, lets you select targets, and installs pre-built distributions. To bring an existing installation current afterwards, run loaf upgrade — it syncs every installed harness from anywhere, and refreshes project files only inside a Loaf repo. Codex's optional outside-sandbox policy is explicit: loaf install --to codex --codex-basic-commands installs only centrally classified basic command leaves with absolute executable prefixes; unclassified and operator commands remain gated. Other harness adapters are not implied by this policy.

Projects created with the older TypeScript runtime can keep using their existing .agents/ Markdown files after installing the native Go runtime. If no SQLite database exists yet, Loaf runs supported report, journal, and housekeeping commands in markdown-only compatibility mode.

Use this sequence when you are ready to adopt SQLite-backed state:

loaf state status
loaf migrate markdown --dry-run
loaf migrate markdown --apply
loaf state status

The dry run counts importable artifacts and skipped files without creating a database. The apply step imports .agents/ Markdown into the XDG data-home SQLite database without rewriting the source Markdown files. Loaf uses one global SQLite file and partitions rows by stable project ID, so multiple projects share the same database path while project queries stay isolated. Project IDs are not bound to the checkout path or friendly name; use loaf project rename <name> for display names and loaf project move --from <old-path> after moving a checkout. Newer graph-oriented commands such as loaf issue, loaf idea, loaf spark, loaf tag, loaf bundle, and loaf link require initialized SQLite state; run loaf state init for a fresh project or loaf migrate markdown --apply for an existing Markdown project.

Loaf keeps recovery claims explicit. local_rollback is the default same-data-home snapshot for local corruption rollback; project-scoped replay remains the ordinary migration rollback path; and external_disaster_copy is an operator-selected non-temporary external destination that may help with data-home or device loss but does not prove physical off-device durability. Every backup reports its resolved destination, checksum, SQLite validity, journal retrieval readiness, recovery readiness, and latest canonical journal watermark. device_loss_protected remains false because selecting a path is not evidence that it is remote or durable.

Create and verify backups with loaf state backup, loaf state backup --to /absolute/external/directory, and loaf state backup verify <backup>. Use loaf state backup restore <backup> --to /absolute/empty/rehearsal/loaf.sqlite for an isolated disposable rehearsal; the command proves an exact copy, integrity, foreign-key, schema, project, journal, search-parity, and watermark match without opening or mutating the live database.

Activating a verified copy is a manual, quiesced operator procedure, not an automated restore command:

1. Stop or terminate every Loaf process, harness, background writer, and related service, then verify universal quiescence before any quarantine or activation step. Loaf has no automated live mutation lease and makes no concurrent-restore claim.
2. Verify the durable backup and complete the isolated disposable rehearsal, then create and retain a preserve-current backup before changing the live data home.
3. While all writers remain quiesced, move the old main database and any matching -wal and -shm sidecars together into a durable quarantine. Never mix sidecars from different database files, and never move only the main file when a sidecar belongs to it.
4. Install the verified copy at the resolved live database path with mode 0600, start current Loaf, and run loaf state doctor, loaf state status, and a known journal retrieval check.
5. If validation fails, quiesce again and activate the preserve-current copy using the same procedure; do not continue with concurrent writers.

Install locations:

MCP Servers: Configure Linear directly in each harness and expose one account-specific server per project; the Linear and bootstrap skills record its name in .agents/loaf.json but do not install or authenticate it. Optional: Serena provides semantic editing for large codebases and can be configured through loaf install.

Claude Code LSP Servers: gopls, pyright, typescript-language-server, solargraph

git clone https://github.com/levifig/loaf.git
cd loaf
npm install
npm run build

A successful development build records its source commit (git rev-parse --short=7 HEAD) and updates Loaf's user-local launcher pointer ($XDG_DATA_HOME/loaf/current-dev-launcher). ~/.local/bin/loaf is created only when that name is absent, as a symlink to the pointer, so the last worktree built becomes the active CLI when the PATH name is free. Set LOAF_DEV_LINK=0 to opt out; an existing real file, directory, or any other symlink is never overwritten. Activation is best-effort and never fails a successful native build. A failed multi-target rebuild leaves the previous successful bin/native binaries and provenance file in place.

See AGENTS.md for development guidelines.

npm run typecheck    # Type check
npm run test         # Run tests
loaf build           # Build all targets (after initial npm run build)
loaf install --to all  # Install to detected tools

Testing locally:

• Claude Code: /plugin marketplace add /path/to/loaf
• Others: loaf install --to all (after npm run build)

MIT