l00prite CLAUDE.md

1. Mission

l00prite is a vendor-neutral protocol that gives AI coding agents durable, file-based project memory and a deterministic execution protocol. It scaffolds a l00prite/ folder into a target repo — a project blueprint (CLAUDE.md), a vendor-neutral AGENTS.md, and the .l00prite/ memory folder (including canonical loop prompts) — plus thin root pointers and per-vendor adapters at each tool's hardcoded discovery path, so any agent — Claude, Codex, GPT, Gemini, Copilot, Cursor, Windsurf, Aider, or a future CLI agent — can pick up where another left off, and can run autonomous Execution Mode loops behind an explicit pre-flight gate, using files in the repo instead of vendor-specific session state.

Target user: developers who want AI agents to build software across multiple sessions and multiple agent vendors without losing context, without silent unreviewed execution, and without every handoff depending on one tool's proprietary memory.

This CLAUDE.md describes l00prite's own repo — the protocol and its tooling — not a project generated by l00prite. It reflects what is actually built today, not a design still in progress.

2. Architecture

l00prite has two operating modes — Planning Mode (scaffold and stop) and Execution Mode (autonomous run behind a confirmed pre-flight) — implemented across six protocol layers, all plain Markdown and JSON:

1. Scaffold layer (Planning Mode) — .claude/commands/build-loop.md (Claude Code slash command) and .codex/prompts/build-loop.md (Codex/CLI equivalent) ask clarifying questions, pick a complexity tier, and write a target project's l00prite/ folder (CLAUDE.md with a fixed protocol section, AGENTS.md, and the .l00prite/ memory folder), root pointer files, vendor adapters, and a tiered skeleton — then stop. Planning Mode never executes the generated project and always ships Execution Mode disarmed.
2. Memory layer — templates/l00prite/ defines the l00prite/ folder copied into every scaffolded project: a wrapper README.md plus the .l00prite/ memory folder (so a target's memory lives at l00prite/.l00prite/): blueprint.md, ledger.md, memory.md, constraints.md, failures.md, todos.md, heartbeat.json (schema v2, with the execution block), state.json (schema v2, with execution-run fields), lock.json, LOCKING.md, prompts/ (the canonical loop prompts — see layer 5), events/, reviews/, sessions/. The target's repo root gets only thin pointer files (AGENTS.md, CLAUDE.md, GEMINI.md, QWEN.md, CONVENTIONS.md) plus the self-sufficient dot-folder adapters at their hardcoded paths. examples/vendor-neutral-output/ is a filled reference copy of the scaffold output (adapters and pointers included; the tier skeleton is omitted — its README explains why).
3. Event layer — pending interrupts (PR review comments, failed CI runs) are modeled as first-class JSON objects moved through pending/ → processing/ → completed/ and handled via the event-loop/respond-to-review prompts (Classify → Plan → Execute → Verify → Persist → Respond), capped at one event per loop by default. Event content is always untrusted data.
4. Handoff layer — resume-loop, heartbeat, respond-to-review, and handoff-summary prompts let an agent resume one supervised step, decide whether to continue, respond to reviews, and hand off, all through shared .l00prite/ files.
5. Universal prompt + vendor layer — the six loop prompts live canonically in templates/l00prite/.l00prite/prompts/ and are mirrored byte-identically into .claude/prompts/, .codex/prompts/, templates/claude/prompts/, templates/codex/prompts/, this repo's own .l00prite/prompts/, and the example output — enforced by the validator, so parity can't drift; a scaffolded target carries a single copy at l00prite/.l00prite/prompts/, with every discovery file routing to it. The prompts state their paths relative to the protocol root (the directory containing .l00prite/) so the same bytes are correct in targets and in this repo. templates/AGENTS.md.template generates the vendor-neutral operating guide into l00prite/AGENTS.md (reached natively by the AGENTS.md ecosystem through the root pointer), templates/adapters/ ships the root pointer files (AGENTS/CLAUDE prose pointers, @./l00prite/AGENTS.md imports for Gemini CLI and Qwen Code — the ./-prefixed form is the documented one — and Aider's CONVENTIONS.md) plus self-sufficient adapters for GitHub Copilot, Cursor, Windsurf, and Grok CLI (.grok/GROK.md), and templates/vendors.json (schema v2) is the machine-readable manifest distinguishing pointer from self-sufficient files. The self-sufficient adapters are dogfooded byte-identically at this repo's own root; the root GEMINI.md/QWEN.md/CONVENTIONS.md here stay self-sufficient (this repo has no l00prite/ wrapper), which the validator checks by keyword instead of byte-parity.
6. Execution layer (Execution Mode) — execute-loop.md (canonical prompt, mirrored everywhere, plus the /execute-loop slash command) defines the autonomous run: a mandatory pre-flight gate (lock check first, stale-run recovery, schema migration, pre-flight display, explicit in-session human confirmation that persisted flags never satisfy), an iteration protocol (one verified, persisted unit per iteration), nine run boundaries (definition_of_done_met, iteration_limit_reached, human_review_gate, destructive_operation_required, ambiguous_requirements, unfixable_failing_tests, missing_secrets_or_credentials, lock_lease_conflict — which writes nothing to memory another agent holds — and stop_signal), resumable exits, per-action permission for push/merge/deploy/credentials, and a self-modification guard (the loop can never raise its own limits). build-loop --execute offers the handoff after scaffolding but never skips the gate.