convez.ai
Agente
levifig

loaf

levifig/loaf

Ver no GitHub
InicialPluginScore Β· de 0 a 100

🍞 Loaf – An opinionated agent harness/framework – Built primarily for Claude Code, with support for Codex, OpenCode, and Cursor.

InstalaΓ§Γ£o

$npx convez-ai levifig/loaf

1 comando no terminal: detecta o formato do repositΓ³rio (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

MΓ©tricas

Estrelas
4
Forks
0
Acompanhando
1
SaΓΊde
42%
Último commit
hΓ‘ 3 dias
VersΓ£o
v0.5.0
Issues abertas
96
Contribuidores
1

README

A traduΓ§Γ£o para o portuguΓͺs deste README ainda estΓ‘ na fila.

🍞 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 β€” 33 skills (31 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 and decisions with frontmatter tracking. Handoff artifacts live separately in .agents/handoffs/. 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 and decisions in .agents/sessions/; 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.

The Pipeline

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

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                       PHASE 1: SHAPE                        β”‚
β”‚                                                             β”‚
β”‚         /idea  β†’  /brainstorm  β†’  /shape  β†’  SPEC          β”‚
β”‚                                                             β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                              ↓
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                       PHASE 2: BUILD                        β”‚
β”‚                                                             β”‚
β”‚           /breakdown  β†’  /implement  β†’  /release            β”‚
β”‚                                                             β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                              ↓
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                       PHASE 3: LEARN                        β”‚
β”‚                                                             β”‚
β”‚           /housekeeping  β†’  /reflect  β†’  /wrap              β”‚
β”‚                                                             β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Phase 1: Shape

Transform raw ideas into implementable specs with clear boundaries.

CommandWhat It Does
/ideaQuick capture of rough ideas into .agents/ideas/
/brainstormDeep exploration of a problem space
/shapeRigorous shaping into bounded spec (what's IN and OUT)
/strategyDiscover and document strategic direction

Phase 2: Build

Decompose specs into atomic tasks and execute with specialized agents.

CommandWhat It Does
/breakdownSplit spec into agent-sized atomic tasks
/implementExecute 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.

CommandWhat It Does
/housekeepingReview completed sessions, archive or delete lifecycle-complete artifacts
/reflectIntegrate learnings into strategic documents
/handoffPackage context for another agent, branch, task, or future session
/wrapSession summary: what shipped, what's pending, what's next

Pipeline Commands

CLI commands that support the workflow pipeline:

CommandWhat It Does
loaf buildBuild all targets after modifying skills/agents
loaf installInstall to detected AI tools
loaf checkRun enforcement hooks manually
loaf projectManage durable project identity (show, rename, move)
loaf taskManage project tasks (list, show, update, archive)
loaf specManage spec lifecycle
loaf kbKnowledge base management
loaf sessionSession journal management (list, start, end, log)
loaf session enrichEnrich session journal from JSONL conversation logs
loaf session housekeepingReview and archive agent artifacts
loaf release / loaf shipOrchestrate release ritual

Profiles

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

ProfileRoleTool AccessWhat It Does
SmithImplementerFull writeForges code, tests, config, and docs. Speciality determined by skills.
SentinelReviewerRead-onlyWatches, guards, and verifies. Cannot modify what it reviews β€” by design.
RangerResearcherRead + webScouts far, gathers intelligence, reports structured findings.
LibrarianLibrarianRead + Edit (.agents/)Tends session lifecycle, state, and wrap summaries. Does not forge code or scout.

The main session is the Warden β€” it coordinates and delegates but never implements directly. See SOUL.md for the full fellowship identity.

Skills

Workflow

Skills you invoke directly to drive work forward.

SkillActivates When
shapeShaping ideas into bounded specs
breakdownDecomposing specs into atomic tasks
implementStarting task or spec implementation
releaseOrchestrating the release ritual (version bump, squash merge)
brainstormDeep exploration of a problem space
researchInvestigating questions, comparing options
strategyDiscovering or updating strategic direction
architectureCreating Architecture Decision Records
ideaQuick capture of ideas for later evaluation
triageReview and process intake queue (sparks + raw ideas)
reflectIntegrating learnings into strategic docs
housekeepingReviewing and archiving agent artifacts
handoffCreating disposable transfer packets in .agents/handoffs/
bootstrapBootstrapping new or existing projects
wrapEnd-of-session summary: shipped, pending, next

Orchestration & Knowledge

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

SkillActivates When
orchestrationManaging sessions, delegating agents, Linear integration
councilMulti-perspective deliberation during complex decisions
knowledge-baseManaging project knowledge files
cli-referenceLooking up which CLI command to use

Engineering Standards

Background knowledge that activates automatically to enforce quality.

SkillActivates When
foundationsWriting code β€” style, naming, TDD, verification, code review
git-workflowBranching, commits, PRs, squash merges
debuggingDiagnosing failures, tracking hypotheses, flaky tests
security-complianceThreat modeling, secrets management, compliance checks
documentation-standardsADRs, API docs, changelogs, Mermaid diagrams

Language & Domain

Domain expertise that loads based on project context.

SkillActivates When
typescript-developmentTypeScript, React, Next.js, Tailwind, Vitest
python-developmentFastAPI, Pydantic, pytest, async patterns
ruby-developmentRails 8, Hotwire, Minitest
go-developmentGo services, concurrency, testing
interface-designUI/UX, accessibility (WCAG 2.1), design systems
database-designSchema design, migrations, query optimization
infrastructure-managementDocker, Kubernetes, CI/CD, Terraform
power-systems-modelingThermal rating models, conductor physics

Multi-Target Support

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

TargetProfilesSkillsHooksStatus
Claude Codeβœ“βœ“βœ“Primary
OpenCodeβœ“βœ“βœ“Full support
Cursorβœ“βœ“βœ“Full support
Codexβ€”βœ“βœ“Skills + hooks
Geminiβ€”βœ“β€”Skills only

Note: council-session skill renamed to council for consistency. Removed skills: resume-session, reference-session.

Getting Started

Homebrew

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.

Claude Code

/plugin marketplace add levifig/loaf

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

OpenCode, Cursor, Codex, Gemini

npx github:levifig/loaf install

Detects installed tools, lets you select targets, and installs pre-built distributions. Re-run with --upgrade to update.

Upgrading Existing Projects

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 task, spec, report, session, 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 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.

Recovering SQLite State From A Backup

Loaf backups are full SQLite database copies stored outside the repository. There is not yet a loaf state restore command, so restore is an explicit manual procedure:

loaf state backup verify /path/to/backup.sqlite
DB="$(loaf state path)"
cp "$DB" "$DB.before-restore"
cp /path/to/backup.sqlite "$DB"
loaf state doctor
loaf state status

Only copy a backup after loaf state backup verify reports verified: true, integrity: ok, foreign keys: ok, and the expected project identities. Preserve the current global database first so a bad restore can be reversed. For agentic restore flows, loaf state backup verify --json includes restore_database_path, restore_preserve_path, and restore_validation_commands for the current checkout. After copying the backup into $XDG_DATA_HOME/loaf/loaf.sqlite, run loaf state doctor and loaf state status from the affected checkout before continuing work.

Install locations:

TargetLocation
OpenCode~/.config/opencode/ or ~/.opencode/
Cursor~/.cursor/
Codex$CODEX_HOME/skills/ or ~/.codex/skills/
Gemini~/.gemini/skills/

Integrations

Claude Code only.

Recommended MCP Servers: Linear (issue tracking). Optional: Serena (semantic editing for large codebases β€” most code intelligence is now built into Claude Code's native LSP). Not bundled β€” loaf install will detect and recommend missing MCPs.

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

Development

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

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 link)

License

MIT

Ver o original no GitHub

Bom para

Relacionados