Loa

"The Loa are pragmatic entities... They're not worshipped for salvation—they're worked with for practical results."

What's new in v2.0.0-rc.9 (release candidate)

The 2.0 line ships as a pre-release: it soaks with real users, fixes land as -rc.N, and 2.0.0 is promoted once the exit criteria in the rc.1 release notes are met. Stable users can stay on v1.202.1 until then.

rc.9 — performance follow-ups (cycle-137, notes): the framework's own overhead drops on every session start, edit and /loa without a single behaviour change — the repo-map generator runs once (4.66 → 1.22 s), the grimoire index sanitises in one awk per family (1.82 → 0.83 s), the known-failures SessionStart hook is one process (488 → 15 ms), the Write/Edit PreToolUse hooks parse their payload once (≈ 78 → 62 ms), the Stop guard reads its config once (24 → 14 ms), compat-lib.sh probes the platform lazily, and cheval imports one provider adapter instead of ten; a deterministic spawn-budget test guards the hot paths. The loop's six follow-ups ship with it: the known-failures parsers read one more field shape and never attach a field to the wrong entry, the grimoire index caches its 1,100 decision rows behind a uid-owned trust boundary (826 → 196 ms warm), /loa reads its catalog fields with one yq and the agy opt-in node once, the karpathy hook needs no yq on the warm path, audit-envelope.sh verify-chains verifies every chain file in one process and fails closed on any malformed record, and two slow test files got faster or honestly measured. Also in this candidate: the cycle-134 post-ship fixes, the cycle-135 review-coverage follow-ups (Bridgebuilder exclusion grammar, protected paths, base .reviewignore, housekeeping merges) and the cycle-136 Bridgebuilder and scaffold follow-ups that shipped to main after rc.8.

rc.8 — the follow-through (cycle-133, notes): the Bridgebuilder reads every pull request pinned to one head and its enriched consensus is the consensus; release publication tags the merge commit and proves it reachable before it announces; the public record branch is a framework script with a credential scan; the eval harness gained one fail-closed session library, a per-sandbox egress guard (the host is unreachable even from a --internal network), a restartable batch supervisor, grader 1.5 with judge verdicts, one finding contract run by four agreeing validators (every review and audit bullet carries a Failure: scenario), external corpus seeding and registration v2; the beads sweep closed 174 beads with evidence and kept 147 under backlog-2026-10. The home-scope mount (Loa reviewing Loa from the sandbox HOME) landed but is not claimed — see the notes.

rc.5 — earned guards and open voices (cycle-129, CHANGELOG):

• Every guard carries its origin and its yield: grimoires/loa/guards.md lists every hook, fence pattern, validator rule and gate with where it came from and whether it is active, dormant or telemetry; .run/guard-yield.json counts its real blocks and likely false positives over 30 days; /loa prints a Guards line. guard-yield.sh --check fails CI when a guard has no origin.
• Control arms: the recall evals can run with a kernel block, the companion voice or the rule files switched off (run-arms.sh), against a record corpus of eight real sprints, so a rule's claim on review recall is measured before its text is cut. The kernel kept every pinned rationale this cycle (the arm run was still running at the gate) and shrank by the Agent Teams table; its byte cap fell to 9,445 B.
• Controls that run or go: implement_gate.mode (ask, the default, logs a row; telemetry; deny refuses an unsanctioned App-Zone write while the run position is known), run position derived from files (run-checkpoint.sh derive), the circuit breaker as a script (record-round), per-task surgical-diff state; the input guardrails and danger-level enforcement default off in the example (82 events, zero catches), the Agent Teams rules live in their reference, and the pure-review skills carry disallowed-tools.
• The fence stops blocking prose: a heredoc whose consumer only writes a file (cat, tee, gh pr comment -F -, git commit -F -, …) is scanned per segment, not as a command; interpreters, wrappers, substitutions, executable targets and anything unlisted still scan in full (destructive_command_guard.heredoc_classifier, corpus 99 benign / 184 dangerous rows). Two pre-existing holes closed on the way: a backtick substitution was inert to every rule, and gh api with a destructive method on refs, branch protection, tags, releases or the repository had no rule (FR-GH-1).
• One profile knob: loa.profile: lean | standard | full sets the nine optional surfaces; no floor key is reachable through it; the example ships those keys as commented, profile-governed lines so a copied example follows the profile you choose, and /loa says when a guardrail control is off.
• Task kinds: every sprint task says whether it is mechanical, judgment or operator work, and tools/cycle-ratio.sh prints the cycle's script / prose / model-call ratio.
• Open voices: a local OpenAI-compatible server is a declared provider (keyless: true, allow_insecure_endpoint: "127.0.0.1"; one endpoint rule in cheval, the bash validator and model-health-probe.sh --provider <name>), the chat path sends response_format json_schema and strips thinking traces honestly, advisory_voices run beside the dissent's counted voices and can never change a verdict, and hounfour.locality: local_voices refuses every hosted hop by name across the dissent, Flatline, Bridgebuilder and the probe. Bridgebuilder reads providers only from trusted configuration, prints completed/planned voices and exits 3 on a degraded consensus.

Upgrading: see the CHANGELOG Migration notes — implement_gate.mode: ask and destructive_command_guard.heredoc_classifier: false are the rollback keys; set guardrails.input.enabled: true and guardrails.danger_level.enforce: true (or loa.profile: full) to restore the old guardrail defaults.

Unreleased — decision surfaces (cycle-128, CHANGELOG):

• Decision maps: /chart <slug> maps an effort that spans more than one cycle as question tickets and a map doc in grimoires/loa/maps/. It plans and never builds, and /plan reports the charting phase.
• Decision ledger: every planning decision becomes a DEC row in grimoires/loa/decisions.yaml with who decided it. Agent decisions stay proposed until you confirm them with /decisions.
• Rounds and attribution: the interview asks every question whose prerequisites are settled in one round, each with a recommended answer. Facts are looked up, never asked; decisions are yours, and PR bodies list the ones taken on your behalf.
• Spike tickets: a question talk cannot settle becomes a prototype ticket on a spike/<slug> branch that is pushed, never merged and never opened as a PR.
• Glossaries: .claude/loa/GLOSSARY.md and a project GLOSSARY.md; tools/check-glossary-terms.sh fails CI when a kernel term has no entry.
• Test discipline: sprint plans name their Seams Under Test, and red-test-check.sh proves a bug fix's test failed before the fix and passes after it.
• Operator-only commands: /decisions, /contribute, /run-halt, /loa-eject and three others carry disable-model-invocation, so only you can run them.

Upgrading: interview.pacing unset now means rounds in thorough mode, and plans dated from 2026-10-13 need the Seams block (see the CHANGELOG Migration notes).

rc.2 — friction floor (cycle-125, notes): the destructive-command fence stops blocking cache/scratch cleanups it cannot lose data on (corpus-gated, 49 benign / 60 dangerous rows), the big planning artefacts read by section (notes-guard.sh read --file F --section 'Sprint N'), /run refuses to start a run it cannot finish (run-preflight.sh, eight predicates, the fix named) and the next session is told how to resume, /loa shows provider health (breakers, credential presence, CLI hops) and artefact sizes, and the ids the fleet actually calls are priced (dated releases, aliases, CLI hops) with the unpriced share always visible. No new configuration key.

Unreleased — full size (cycle-126, migration addendum): size limits come from the catalog entry actually resolved (the probed input bound until you calibrate it), every dissent gets a second voice from the other model family, context-clearing thresholds follow the session model's window, opus → claude-opus-5-5 and cheap → claude-sonnet-5, and /loa shows what the implement gate can and cannot see.

rc.1 — model-generation floor (cycle-124):

• Model-generation floor — the framework's own use of Claude moves to Opus 5 / Sonnet 5 / Fable 5.1: opus → claude-opus-5, fable → claude-fable-5-1, per-hop max_tokens defaults sized to the model (16K/64K on Anthropic, clamped to the catalog), adaptive thinking on the 4.6+ family, prompt caching with a single persona breakpoint, structured outputs (--json-schema) for dissent and Flatline. LOA_CHEVAL_LEGACY_WIRE=1 restores the pre-2.0 request body.
• Mechanical gates, continued — coverage-first review/audit (every finding with file:line), verdict trailers enforced by the golden path, prompt byte budgets on every PR, bounded NOTES.md (200 KiB block line with notes-guard.sh rotate), ledger isolation for every test harness.
• Aleph is opt-in — aleph.enabled (default false); Aleph users set it to true before upgrading.
• Release engineering — the post-merge pipeline prepares an inspectable candidate and publishes only an approved digest; pre-releases enter and promote through the CHANGELOG heading (2.0.0-rc.1 → -rc.2 → 2.0.0).

Read the migration guide (five recipes, every kill switch) and ADR-004 (why the floor, why Aleph is opt-in, why an rc first). The line-by-line rc.1 audit is in grimoires/loa/reports/breaking-surface-audit-2.0.0-rc.1.md; rc.2 adds no configuration key and no removal. Feedback on the candidate: open an issue labelled 2.0.0-rc.

What Is This?

Loa is an agent-driven development framework for Claude Code (Anthropic's official CLI). It adds 40 specialized skills, quality gates, persistent memory, and structured workflows on top of Claude Code — including a self-improving spiral orchestrator that can autonomously plan, build, review, and learn across multiple development cycles. Works on macOS and Linux. Created by @deep-name at The Honey Jar.

Why "Loa"?

In William Gibson's Sprawl trilogy (Neuromancer, Count Zero), Loa are AI entities that "ride" humans through neural interfaces — a metaphor Gibson adapted from Haitian Vodou via the anthropological work of Robert Tallant and (likely) Maya Deren. These agents don't replace you — they ride with you, channeling expertise through the interface. See docs/ecosystem-architecture.md for the full naming lineage.

Quick Start (~2 minutes)

Prerequisites: Claude Code (Anthropic's CLI for Claude), Git, jq, yq v4+. See INSTALLATION.md for full details.

# Install (one command, any existing repo — adds Loa as git submodule)
curl -fsSL https://raw.githubusercontent.com/0xHoneyJar/loa/main/.claude/scripts/mount-loa.sh | bash

# Or pin to a specific version (the release candidate; v1.202.1 is the latest stable tag)
curl -fsSL https://raw.githubusercontent.com/0xHoneyJar/loa/main/.claude/scripts/mount-loa.sh | bash -s -- --tag v2.0.0-rc.9

# Start Claude Code
claude

# These are slash commands typed inside Claude Code, not your terminal.
# 5 commands. Full development cycle.
/loa       # Where am I? Status, health, next step
/plan      # Requirements -> Architecture -> Sprints
/build     # Implement the current sprint
/review    # Code review + security audit
/ship      # Deploy and archive

After install, you should see .loa/ (submodule), .claude/ (symlinks), grimoires/loa/, and .loa.config.yaml in your repo. Run /loa doctor inside Claude Code to verify everything is healthy.

Three ways to install: Submodule mode (default, recommended for existing projects), clone template (new projects), or vendored mode (legacy — no symlink support). See INSTALLATION.md for the full comparison.

Not sure where you are? /loa shows your current state, health, and next step.

New project? See INSTALLATION.md to clone the template. For detailed setup, optional tools (beads, ck), and configuration, start there too.

Why Loa?

The problem: AI coding assistants are powerful but unstructured. Without guardrails, you get ad-hoc code with no traceability, no security review, and no memory across sessions.

The solution: Loa adds structure without ceremony. Each phase produces a traceable artifact (PRD, SDD, Sprint Plan, Code, Review, Audit) using specialized AI agents. Your code gets reviewed by a Tech Lead agent and a Security Auditor agent before it ships.

Key differentiators:

• Multi-agent orchestration: 40 specialized skills, not one general-purpose prompt
• Quality gates: Two-phase review (code + security) prevents unreviewed code from shipping
• Session persistence: Beads task graph + persistent memory survive context clears
• Adversarial review: Flatline Protocol uses cross-model dissent (Opus + GPT) for planning QA
• Self-improving spiral: /spiral dispatches autonomous development cycles with evidence-gated quality gates that the LLM cannot skip — benchmarked and validated
• Zero-config start: Mount onto any repo, type /plan, start building

The Workflow

Golden Path (5 commands, zero arguments)

Command	What It Does
/loa	Where am I? What's next?
/plan	Plan your project (requirements -> architecture -> sprints)
/build	Build the current sprint
/review	Review and audit your work
/ship	Deploy and archive

Each Golden Path command auto-detects context and does the right thing. No arguments needed. First run of /plan takes 2-5 minutes and creates grimoires/loa/prd.md.

Diagnostics

If something isn't working, start here:

/loa doctor          # Full system health check with structured error codes
/loa doctor --json   # CI-friendly output

Power User Commands (Truenames)

For fine-grained control, use the underlying commands directly:

Phase	Command	Output
1	/plan-and-analyze	Product Requirements (PRD)
2	/architect	Software Design (SDD)
3	/sprint-plan	Sprint Plan
4	/implement sprint-N	Code + Tests
5	/review-sprint sprint-N	Approval or Feedback
5.5	/audit-sprint sprint-N	Security Approval
6	/deploy-production	Infrastructure

51 total commands. Type /loa for the Golden Path or see PROCESS.md for all commands.

The Agents

A selection of the specialized skills that ride alongside you:

Skill	Role
discovering-requirements	Senior Product Manager
designing-architecture	Software Architect
planning-sprints	Technical PM
implementing-tasks	Senior Engineer
reviewing-code	Tech Lead
auditing-security	Security Auditor
deploying-infrastructure	DevOps Architect
translating-for-executives	Developer Relations
enhancing-prompts	Prompt Engineer
run-mode	Autonomous Executor
run-bridge	Excellence Loop Operator
simstim-workflow	HITL Orchestrator
spiraling	Autopoietic Meta-Orchestrator
riding-codebase	Codebase Analyst
continuous-learning	Learning Extractor
flatline-knowledge	Knowledge Retriever
browsing-constructs	Construct Browser
mounting-framework	Framework Installer
autonomous-agent	Autonomous Agent

Spiral Autopoietic Orchestrator

The spiral (/spiral) is a self-improving meta-loop that dispatches autonomous development cycles. Each cycle runs the full Loa workflow (plan, build, review, audit), then harvests lessons to seed the next cycle. The system learns from its own output.

/spiral --start "Build feature X"
│
├── SEED    — query Vision Registry for relevant prior insights
├── SIMSTIM — dispatch full cycle (PRD → SDD → Sprint → Implement → Review → Audit → PR)
├── HARVEST — extract learnings, promote patterns, capture visions
└── EVALUATE — check stopping conditions, decide whether to continue

Quality gates are evidence-gated: a bash orchestrator sequences phases as separate claude -p subprocesses, with Flatline multi-model review, independent code review, and independent security audit running in bash between phases. The LLM cannot skip gates because it is not the LLM's decision.

Cost optimization: Sonnet handles planning and implementation (~5x cheaper tokens), Opus handles review and audit (judgment quality). Benchmarked at equivalent output quality across both models. Default budget: $15/cycle.

Kaironic termination: unlike most agentic pipelines that only stop when wall-clock caps fire (budget / max iterations / timeout), the spiral observes its own findings-rate and halts on flatline_convergence — 2 consecutive cycles producing < 3 new findings each. The loop decides "we've reached a plateau" and terminates before exhausting budget. Second-order cybernetic convergence; see .claude/skills/spiraling/SKILL.md for the distinction between chronos (wall-clock) and kairos (signal-exhaustion) stopping conditions.

# .loa.config.yaml — enable the spiral
spiral:
  enabled: true
  harness:
    executor_model: sonnet    # planning + implementation
    advisor_model: opus       # review + audit

See RFC-060 for the design, harness architecture for the engineering pattern, and benchmark report for the data.

Architecture

Loa uses a three-zone model inspired by AWS Projen and Google's ADK:

Zone	Path	Description
System	.claude/	Framework-managed (never edit directly)
State	grimoires/, .beads/	Project memory
App	src/, lib/	Your code

Key principle: Customize via .claude/overrides/ and .loa.config.yaml, not by editing .claude/ directly.

Key Features

Feature	Description	Documentation
Golden Path	5 zero-arg commands for 90% of users	CLAUDE.md
Error Codes & /loa doctor	Structured LOA-E001+ codes with fix suggestions	Data
Flatline Protocol	Multi-model adversarial review (Opus + GPT-5.2)	Protocol
Adversarial Dissent	Cross-model challenge during review and audit	CHANGELOG.md
Cross-Repo Patterns	25 reusable patterns in 5 library modules	Lib
DRY Constraint Registry	Single-source constraint generation from JSON	Data
Beads-First Architecture	Persistent task tracking (recommended; required for /run mode, works without for interactive use)	CLAUDE.md
Known-Failures Ledger	Compounding failure memory with recurrence-driven escalation	Grimoire
Input Guardrails	PII filtering, injection detection, danger levels	Protocol
Portable Persistence	WAL-based persistence with circuit breakers	Lib
Cross-Platform Compat	Shell scripting protocol for macOS + Linux	Scripts
Prompt Enhancement	PTCF-based prompt analysis and improvement	CHANGELOG.md
Run Mode	Autonomous sprint execution with draft PRs	CLAUDE.md
Run Bridge	Iterative excellence loop with Bridgebuilder review and flatline detection	CLAUDE.md
Lore Knowledge Base	Cultural/philosophical context for agent skills (Mibera + Neuromancer)	Data
Spiral Orchestrator	Self-improving meta-loop: plan → build → review → harvest → repeat	RFC-060
Evidence-Gated Harness	Bash-enforced quality gates that LLMs cannot skip — flight recorder audit trail	Architecture
Advisor Strategy	Sonnet executes (~5x cheaper), Opus judges (review/audit quality)	Benchmark
Vision Registry	Speculative insight capture from bridge iterations, graduated to active mode	Per-project under grimoires/loa/visions/ (project-zone; created on first vision)
Grounded Truth	Checksum-verified codebase summaries extending /ride	Script
Simstim	HITL accelerated development (PRD -> SDD -> Sprint -> Run)	Command
Compound Learning	Cross-session pattern detection + feedback loop	CHANGELOG.md
Construct Manifest Standard	Event-driven contracts with schema validation	CHANGELOG.md
Quality Gates	Two-phase review: Tech Lead + Security Auditor	PROCESS.md
Loa Constructs	Commercial skill packs from registry	INSTALLATION.md
Sprint Ledger	Global sprint numbering across cycles	CLAUDE.md
beads_rust	Persistent task graph across sessions	INSTALLATION.md
ck Search	Semantic code search	INSTALLATION.md

Documentation

Document	Purpose
INSTALLATION.md	Setup, prerequisites, configuration, updates
PROCESS.md	Complete workflow, agents, commands, protocols
CLAUDE.md	Technical reference for Claude Code
CHANGELOG.md	Version history

Maintainer

@deep-name

License

AGPL-3.0 — Use, modify, distribute freely. Network service deployments must release source code.

Commercial licenses are available for organizations that wish to use Loa without AGPL obligations.

Links

• Repository
• Issues
• Changelog
• Claude Code
• beads_rust

Ridden with Loa