Concepts
The vocabulary the rest of the documentation uses: what Luna is, the rules its extensions follow, and how capability tiers, layers and profiles relate. Nothing here is a promise of future work; see Roadmap for that.
What Luna is
Luna is an opinionated distribution of the pi coding agent: extensions, skills, prompt templates, themes, profiles and an installer. It adds what pi deliberately leaves out of its core (a permission gate, delegation, durable memory, verification, recovery, observability) and packages it so one command installs a coherent set.
Two properties shape everything else:
- The harness matters as much as the model. Reliability comes from decomposition, durable state, verification, bounded recovery and observability around the model, not from prompting alone. Luna is that surrounding harness.
- Local first, portable. Luna installs onto any pi installation with
pi install. It does not depend on a particular model, provider, container or host, and it never sends anything anywhere on its own.
Design rules
Every extension and profile follows these. npm run verify enforces the mechanical ones.
- Stable instruction is separate from learned recall. Policy and skills are versioned files; memory is a cheaper, selectively retained layer.
- Progressive disclosure. Skill names load at start, bodies on demand; memory indexes first, details on trigger.
- The trace is not the context. An append-only trace records what happened; only selected summaries reach the model.
- A long task has an explicit objective with a verifiable definition of done, restartable from the working tree and the goal file alone.
- The model does not certify "done". Verification decides, cheapest checks first.
- Recovery is evidence-driven and bounded, chosen by the kind of failure, never retry-until-broke.
- Isolated workers, not one giant context. Delegated work runs in its own process under the same governance as its parent.
- Scale the machinery to the task. A quick fix must not pay long-horizon overhead; that is what profiles and effort are for.
- General capability lives in Luna; domain rules compose on top. A domain extension (for example engagement scope and rules of engagement) composes a general one and never reimplements it. Per-engagement values live in the engagement configuration, not in the capability layer.
- Extensions are self-contained. No extension imports another; cross-extension contracts go
through small registries on
globalThis(Symbol.for("pi-kit.*")), so any one extension can be removed without breaking the rest.
Tiers
A tier is a level of capability. Each is useful alone; higher tiers are only worth trusting once the lower ones are solid.
| Tier | Name | The agent can | Provided by |
|---|---|---|---|
| T0 | Safe substrate | Not damage the repository or leak secrets; every action is recoverable; progress survives a crash. | guards, checkpoints |
| T1 | Durable quick-task agent | Make fast, correct edits; remember project facts; keep context lean. | memory, handoff, context hygiene |
| T2 | Verified agent | Refuse to declare victory on broken code; self-correct from verifier feedback. | verify-gate, verifier-board |
| T3 | Long-horizon agent | Hold a goal and plan, persist state across context resets, isolate risky work, recover by evidence. | goal-core, task-graph, branch-lab, autonomous-loop |
| T4 | Self-improving specialist | Record and score runs, mine failures, curate skills, route hard jobs to a stronger reviewer. | trace-ledger, skill-forge, self-improvement |
Each extension manifest declares a tier; the capability matrix shows the
tiers each profile reaches.
Layers
Extensions belong to one of six layers, which is what a manifest's layer field records.
- Execution substrate: isolation, checkpoints, rollback, worktrees.
- Tool surface: few, typed, observable tools; interception and re-validation of tool calls (the tool firewall).
- Context and memory: identity, policy (
AGENTS.md), procedural memory (skills), project memory, task summaries, the trace, retrieval, and the context sieve that decides what the model sees. - Orchestration: goals, task graphs, delegation, the autonomous loop, model routing.
- Verification: cheap static gates, executable tests, process critics, independent reviewers.
- Observability and self-improvement: structured traces, the status bar, cost accounting, skill mining.
Profiles
A profile is a named set of extensions, skills and prompts, plus a firewall mode and policy. It exists so the machinery scales to the task. The profiles guide lists what each one loads and how to switch; effort is a separate, per-task dial that changes how much the agent delegates without changing what is installed.
Where things run
flowchart LR
operator([Operator]) --> pi[pi runtime]
pi --> kit[Luna extensions]
kit -->|governed child processes| child[Delegated workers]
kit -->|read-only accounting| trace[(Trace and cost ledgers)]
pi --> provider[Model provider]
kit -. optional .-> container[Hardened autonomy container]
Luna runs inside pi's process. Delegated workers are separate pi processes that Luna launches under the same governance as their parent. The autonomy runner is a separate, optional component that runs a whole session inside a hardened container.