loaf

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 complete pipeline from idea to implementation to learning. Write your skills once, deploy to Claude Code, OpenCode, Cursor, Codex, and Gemini.

Why Loaf?

Portable knowledge — 31 skills (29 active, 2 deprecated) covering workflows, engineering standards, and language expertise. Build once, deploy to five AI coding tools without rewriting anything.

Session journal model — Session files in .agents/sessions/ capture state, decisions, and handoff context with frontmatter tracking. Work survives context loss, compaction, and /clear.

Spec-first pipeline — Ideas are shaped into bounded specs before any code is written. Every change flows: Idea → Spec → Tasks → Code → Learnings. Nothing gets lost.

Profile-based agents — Three functional profiles 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.

Session continuity — Pick up exactly where you left off with full traceability. Session journals capture state, decisions, and handoff context in .agents/sessions/.

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.

The Pipeline

Loaf's commands form a three-phase workflow that mirrors how good software gets built:

┌─────────────────────────────────────────────────────────────┐
│                      PHASE 1: SHAPE                         │
│                                                             │
│   /idea  →  /brainstorm  →  /shape  →  Bounded Spec      │
│                                                             │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                      PHASE 2: BUILD                         │
│                                                             │
│   /breakdown  →  /implement                                │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                      PHASE 3: LEARN                         │
│                                                             │
│   /housekeeping  →  /reflect  →  Updated Strategy         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Phase 1: Shape

Transform raw ideas into implementable specs with clear boundaries.

Command	What It Does
/idea	Quick capture of rough ideas into .agents/ideas/
/brainstorm	Deep exploration of a problem space
/shape	Rigorous shaping into bounded spec (what's IN and OUT)
/strategy	Discover and document strategic direction

Phase 2: Build

Decompose specs into atomic tasks and execute with specialized agents.

Command	What It Does
/breakdown	Split spec into agent-sized atomic tasks
/implement	Execute tasks with orchestrated agent delegation
/release (/ship)	Orchestrate the merge ritual: pre-flight, docs check, version bump, squash merge, cleanup

Phase 3: Learn

Integrate outcomes into strategic knowledge.

Command	What It Does
/housekeeping	Review completed sessions, archive artifacts
/reflect	Integrate learnings into strategic documents

Pipeline Commands

CLI commands that support the workflow pipeline:

Command	What It Does
loaf build	Build all targets after modifying skills/agents
loaf install	Install to detected AI tools
loaf check	Run enforcement hooks manually
loaf task	Manage project tasks (list, show, update, archive)
loaf spec	Manage spec lifecycle
loaf kb	Knowledge base management
loaf session	Session journal management (list, start, end, log)
loaf housekeeping	Review and archive agent artifacts
loaf release / loaf ship	Orchestrate release ritual

Profiles

Loaf uses three 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.