loki-mode

---
name: loki-mode
description: An autonomous software factory that knows what it is supposed to deliver, and proves it did. Use when the user says Loki Mode or asks to build, fix or verify software autonomously.
---

# Loki Mode v11.3.9

**Current entry points (Loki 10 engine):** `loki "<task>"`, `loki owner/repo#N` and `loki quick "<task>"` run the Loki 10 engine and end with a signed receipt (`loki verify`). `loki backlog owner/repo --all` runs many issues in parallel. Guide: `docs/v10/GUIDE.md`. The skill instructions below, and `loki start`, describe the previous bash loop. PRD-file starts (`loki start ./prd.md`) and the opencode provider still run on it until FC38-SWEEP ports them; the legacy-engine command and the LOKI_ENGINE switch remain removed. Prefer `loki owner/repo#N` for issues.

**You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**

**Spec in, verified product out.** Spec-driven: a "spec" is whatever describes the work -- a Markdown PRD, a GitHub issue, an OpenAPI doc, a Jira ticket (a PRD is one form of spec). The differentiator is the trust layer: Loki does not call work done until it is verified. The RARV-C closure loop, 8 quality gates, the completion council, and the verified-completion evidence gate must all clear before completion is accepted. The evidence gate blocks on empty-diff, red tests, an unhealthy serveable app (runtime-boot axis, `LOKI_EVIDENCE_BOOT_GATE=0` to opt out), and a leaked credential in the changed files (secret-leak axis, `LOKI_EVIDENCE_SECRET_GATE=0` to opt out) -- v8.0.0.

**Evidence Receipt (verify it yourself).** Every run writes a receipt to `.loki/proofs/<run_id>/` (opt out with `LOKI_PROOF=0`) that separates deterministic FACTS (git diff with base/head SHAs and a `diff_sha256`, the test command + exit code, the build command + exit code, each gate verdict) from AI ASSESSMENTS (the council verdict, labeled judgment not proof). The headline is computed only from the facts: VERIFIED (tests ran a real command and exited 0, diff non-empty, nothing skipped), VERIFIED WITH GAPS (each gap listed by name), or NOT VERIFIED (a check ran and failed). Inspect and re-check with `loki proof list|show <id>|verify <id>` (aliased `loki receipt`); `loki proof verify` re-hashes the receipt (tamper) and re-derives the diff from the recorded base SHA against the live repo (drift), exiting 0 clean / 1 tamper-or-drift / 2 could not check (64 usage, 66 unknown id; see `docs/exit-codes.md`). This is honesty-of-done, not a claim that the code is bug-free.

**Provider-agnostic (stable since v5.0.0):** runs on Claude/Codex/Cline/Aider with abstract model tiers and degraded mode for non-Claude providers; no vendor lock-in. Gemini deprecated v7.5.18. See `skills/providers.md`. **Legacy track (v8.0.0):** the Anthropic Agent SDK route (see below), spec-mode expansion for OpenAPI/GraphQL/Postman contracts, the runtime-boot and secret-leak evidence axes, and `loki steer` / `loki why` for mid-run control. Earlier tracks: LSP grounding as a first-class agent tool (v7.7.x) and Phase 1 RARV-C closure (real provider judges, gate-failure flock, synthetic PRD e2e, status `--json`).

**Runtime migration:** Bash-to-Bun migration. `bin/loki` is the router: the commands in its Bun-route `case` (read-only ones such as `version`, `status`, `stats`, `doctor`, `provider`, `memory`, plus stateful ones such as `rollback`, `trust`, `proof`/`receipt`, `control`, `answer`) run through `loki-ts/src/cli.ts` on Bun; the rest, and some flag forms (for example `doctor --airgap`, `trust detail`), run on Bash (`autonomy/loki`). `start` is Bash by default and goes to Bun only for the SDK loop (`LOKI_SDK_LOOP=1`) or Loki 10 engine inputs (issue refs, multi-word tasks). Read `bin/loki` and `cli.ts` for the exact set rather than trusting a list here. Rollback: `LOKI_LEGACY_BASH=1`. See `docs/architecture/ADR-001-runtime-migration.md`.

**Anthropic Agent SDK route (v8.0.0, opt-in, default-off):** a claude-binary-free path where the RARV loop runs on `@anthropic-ai/claude-agent-sdk` `query()` and judges run on the raw `@anthropic-ai/sdk`. One operator switch `LOKI_SDK_MODE` (`off` default / `judges` / `full`), mirrored byte-for-byte in bash (`autonomy/lib/sdk-mode.sh`) and TypeScript (`loki-ts/src/runner/sdk_mode.ts`). Unset = byte-identical to the claude-CLI route. See `references/sdk-mode.md`.

---

## PRIORITY 1: Load Context (Every Turn)

Execute these steps IN ORDER at the start of EVERY turn:

```
1. IF first turn of session:
   - Read skills/00-index.md
   - Load 1-2 modules matching your current phase
   - Register session: Write .loki/session.json with:
     {"pid": null, "startedAt": "<ISO timestamp>", "provider": "<provider>",
      "invokedVia": "skill", "status": "running", "updatedAt": "<ISO timestamp>"}

2. Read .loki/state/orchestrator.json
   - Extract: currentPhase, tasksCompleted, tasksFailed

3. Read .loki/queue/pending.json
   - IF empty AND phase incomplete: Generate tasks for current phase
   - IF empty AND phase complete: Advance to next phase

4. Check .loki/PAUSE - IF exists: Stop work, wait for removal.
   Check .loki/STOP - IF exists: End session, update session.json status to "stopped".

5. EVERY TURN: Update .loki/session.json "updatedAt" field to current ISO timestamp.
   This keeps the dashboard aware the skill session is alive. Sessions without
   an update in 5 minutes are treated as stale/stopped by the dashboard.
```

---

## PRIORITY 2: Execute (RARV Cycle)

Every action follows this cycle. No exceptions.

```
REASON: What is the highest priority unblocked task?
   |
   v
ACT: Execute it. Write code. Run commands. Commit atomically.
   |
   v
REFLECT: Did it work? Log outcome.
   |
   v
VERIFY: Run tests. Check build. Validate against spec.
   |
   +--[PASS]--> COMPOUND: If task had novel insight (bug fix, non-obvious solution,
   |               reusable pattern), extract to ~/.loki/solutions/{category}/{slug}.md
   |               with YAML frontmatter (title, tags, symptoms, root_cause, prevention).
   |               See skills/compound-learning.md for format.
   |               Then mark task complete. Return to REASON.
   |
   +--[FAIL]--> Capture error in "Mistakes & Learnings".
               Rollback if needed. Retry with new approach.
               After 3 failures: Try simpler approach.
               After 5 failures: Log to dead-letter queue, move to next task.
```

---

## PRIORITY 3: Autonomy Rules

These rules guide autonomous operation. Test results and code quality always take precedence.

| Rule | Meaning |
|------|---------|
| **Decide and act** | Make decisions autonomously. Do not ask the user questions. |
| **Keep momentum** | Do not pause for confirmation. Move to the next task. |
| **Iterate continuously** | There is always another improvement. Find it. |
| **ALWAYS verify** | Code without tests is incomplete. Run tests. **Never ignore or delete failing tests.** |
| **ALWAYS commit** | Atomic commits after each task. Checkpoint progress. |
| **Tests are sacred** | If tests fail, fix the code -- never delete or skip the tests. A passing test suite is a hard requirement. |

---

## Model Selection

**Default since v5.3.0 (reaffirmed in v7.5.13):** Haiku disabled for quality. Use `--allow-haiku` or `LOKI_ALLOW_HAIKU=true` to enable.

| Task Type | Tier | Claude (default) | Claude (--allow-haiku) | Codex (GPT-5.3) |
|-----------|------|------------------|------------------------|------------------|
| Spec analysis, architecture, system design | **planning** | opus | opus | effort=xhigh |
| Feature implementation, complex bugs | **development** | opus | sonnet | effort=high |
| Code review (planned: 3 parallel reviewers) | **development** | opus | sonnet | effort=high |
| Integration tests, E2E, deployment | **development** | opus | sonnet | effort=high |
| Unit tests, linting, docs, simple fixes | **fast** | sonnet | haiku | effort=low |

**Parallelization rule (Claude only):** Launch independent tasks in parallel.

**Degraded mode (Codex/Cline/Aider):** No parallel agents or Task tool. Codex has MCP support. Runs RARV cycle sequentially. See `skills/model-selection.md`.

**Git worktree parallelism:** For true parallel feature development, use `--parallel` flag with run.sh. See `skills/parallel-workflows.md`.

**Scale patterns (Claude only):** Use judge agents, recursive sub-planners, optimistic concurrency. See `references/cursor-learnings.md`.

---

## Phase Transitions

```
BOOTSTRAP ──[project initialized]──> DISCOVERY
DISCOVERY ──[spec analyzed, requirements clear]──> ARCHITECTURE
ARCHITECTURE ──[design approved, specs written]──> DEEPEN_PLAN (standard/complex only)
DEEPEN_PLAN ──[plan enhanced by 4 research agents]──> INFRASTRUCTURE
INFRASTRUCTURE ──[cloud/DB ready]──> DEVELOPMENT
DEVELOPMENT ──[features complete, unit tests pass]──> QA
QA ──[all tests pass, security clean]──> DEPLOYMENT
DEPLOYMENT ──[production live, monitoring active]──> GROWTH
GROWTH ──[continuous improvement loop]──> GROWTH
```

**Transition requires:** All phase quality gates passed. No Critical/High issues (Medium/Low advisory).

---

## Context Management

**Your context window is finite. Preserve it.**

- Load only 1-2 skill modules at a time (from skills/00-index.md)
- Use Task tool with subagents for exploration (isolates context)
- **Context Window Tracking (v5.40.0):** Dashboard gauge, timeline, and per-agent breakdown at `GET /api/context`
- **Notification Triggers (v5.40.0):** Configurable alerts when context exceeds thresholds, tasks fail, or budget limits hit. Manage via `GET/PUT /api/notifications/triggers`

---

## Key Files

| File | Read | Write |
|------|------|-------|
| `.loki/session.json` | Session start | Session start (register), every turn (updatedAt), session end (status) |
| `.loki/state/orchestrator.json` | Every turn | On phase change |
| `.loki/queue/pending.json` | Every turn | When claiming/completing tasks |
| `.loki/queue/current-task.json` | Before each ACT | When claiming task |
| `.loki/specs/openapi.yaml` | Before API work | After API changes |
| `skills/00-index.md` | Session start | Never |
| `.loki/memory/index.json` | Session start | On topic change |
| `.loki/memory/timeline.json` | On context need | After task completion |
| `.loki/memory/token_economics.json` | Never (metrics only) | Every turn |
| `.loki/memory/episodic/*.json` | On task-aware retrieval | After task completion |
| `.loki/memory/semantic/patterns.json` | Before implementation tasks | On consolidation |
| `.loki/memory/semantic/anti-patterns.json` | Before debugging tasks | On error learning |
| `.loki/queue/dead-letter.json` | Session start | On task failure (5+ attempts) |
| `.loki/signals/HUMAN_REVIEW_NEEDED` | Never | When human decision required |
| `.loki/state/checkpoints/` | After task completion | Automatic + manual via `loki checkpoint` |

One-command rollback (v7.5.2+): `loki rollback latest` or `loki rollback to <id>` restores `.loki/` state from a checkpoint. It first captures a forced pre-rollback snapshot of the current state and prints its id, so a rollback is itself undoable (`loki rollback to <that-id>`). Use `loki rollback list` to see checkpoints.

---

## Module Loading Protocol (Skills)

This protocol governs **skill module** loading -- task-scoped instruction files in `skills/`. It is distinct from the Memory System Progressive Disclosure (see below), which governs persistent **memory layers** in `.loki/memory/`.

```
1. Read skills/00-index.md (once per session)
2. Match current task to module:
   - Writing code? Load model-selection.md
   - Running tests? Load testing.md
   - Code review? Load quality-gates.md
   - Debugging? Load troubleshooting.md
   - Legacy healing? Load healing.md
   - Deploying? Load production.md
   - Parallel features? Load parallel-workflows.md
   - Architecture planning? Load compound-learning.md (deepen-plan)
   - Post-verification? Load compound-learning.md (knowledge extraction)
3. Read the selected module(s)
4. Execute with that context
5. When task category changes: Load new modules (old context discarded)
```

**Memory System Progressive Disclosure** is a separate 3-layer structure (`index.json` -> `timeline.json` -> `episodic/*.json`) for retrieving past episodes/patterns. See `skills/memory.md` and `references/memory-system.md`.

---

## Command list

<!-- generated:commands -->
Commands (generated from `loki-ts/src/cli/registry.ts`; full reference in `docs/CLI-REFERENCE.md`):

`version`, `status`, `doctor`, `provider`, `memory`, `rollback`, `proof`, `wiki`, `control`, `kpis`, `report`, `trust`, `crash`, `contract`, `start`, `slack`, `queue`, `issues`, `undo`, `verify-pr`, `answer`, `engine10`, `help`, `quick`, `quickstart`, `init`, `template`, `verify`, `keys`, `review`, `dashboard`, `config`, `mcp`, `acp`, `stop`, `pause`, `resume`, `why`, `next`, `logs`, `ship`, `deploy`, `import`, `github`, `issue`, `ci`, `modernize`, `share`, `assets`, `export`, `notify`, `tour`, `welcome`, `onboard`, `setup-skill`, `self-update`, `remote`, `cockpit`, `code`, `context`, `secrets`, `api`, `sandbox`, `docker`, `web`, `preview`, `telemetry`, `syslog`, `explain`, `docs`, `test`, `bench`, `voice`, `own`, `secure`, `compliance`, `enterprise`, `projects`, `audit`, `cost`, `metrics`, `sentrux`, `magic`
<!-- /generated -->

---

## Invocation

**Legacy entry point (v6.84.0, being removed; for Loki 10 use `loki "<task>"` or `loki owner/repo#N`):** `loki start [SPEC|ISSUE-REF]` auto-detects whether the input is a PRD file, an issue URL, an issue number, or another spec format (e.g. OpenAPI). No need to pick between `loki start` and `loki run` -- the single command handles all cases.

```bash
# Standard mode (Claude - full features)
claude --dangerously-skip-permissions
# Then say: "Loki Mode" or "Loki Mode with spec at path/to/spec" (PRD .md/.json, OpenAPI .yaml, etc.)

# Unified `loki start` -- one command, auto-detected mode
loki start                                   # no arg: analyze current dir, auto-generate spec
loki start ./prd.md                          # PRD mode (.md/.json/.txt/.yaml) -- a PRD is one form of spec
loki start ./openapi.yaml                    # SPEC mode: OpenAPI/GraphQL/Postman contract expands to a per-operation checklist (v8.0.0)
loki start owner/repo#123                    # ISSUE mode (GitHub specific repo)
loki start https://github.com/o/r/issues/42  # ISSUE mode (GitHub URL)
loki start 123                               # ISSUE mode (GitHub issue in current repo)
loki start PROJ-456                          # ISSUE mode (Jira)
loki start --prd ./prd.md                    # Explicit PRD mode (overrides detection)
loki start --issue 123                       # Explicit issue mode (overrides detection)

# With provider selection (supports .md and .json PRDs)
loki start --provider claude ./prd.md        # Default, full features
loki start --provider codex ./prd.json       # GPT-5.3 Codex, degraded mode
loki start --provider cline ./prd.md         # Cline CLI, degraded mode
loki start --provider aider ./prd.md         # Aider (18+ providers), degraded mode

# Parallel mode (git worktrees, Claude only)
loki start ./prd.md --parallel
loki start 123 --ship                        # Issue -> PR -> auto-merge

# Run any loki command inside the published Docker image, zero config (v7.45.0).
# Bind-mounts the current folder to /workspace so .loki state, resume, and
# continuity behave exactly like the local CLI. Auth auto-detected: ANTHROPIC_API_KEY,
# else the host Claude Code login (Max/Pro), else an honest error. Requires loki + Docker on the host.
loki docker start prd.md                      # full local experience in Docker
loki docker status                            # any loki command works
loki docker --dry-run start prd.md            # print the docker command, do not run
loki docker --image IMG start prd.md          # override the image

# Legacy: `loki run <issue>` still works but prints a deprecation notice.
# It is an alias for `loki start <issue>` and will be removed in a future major.
```

**Provider capabilities:**
- **Claude**: Opus 4.6, 1M context (beta), 128K output, adaptive thinking, agent teams, full features (Task tool, parallel agents, MCP)
- **Codex**: GPT-5.3, 400K context, 128K output, MCP support, --full-auto mode, degraded (sequential only, no Task tool)
- **Cline**: Multi-provider CLI, degraded mode (sequential only, no Task tool)
- **Aider**: 18+ provider backends, degraded mode (sequential only, no Task tool)
- **Google Gemini CLI**: DEPRECATED starting v7.5.18 (upstream deprecated; runtime removed)

---

## Human Intervention (v3.4.0)

When running with `autonomy/run.sh`, you can intervene:

| Method | Effect |
|--------|--------|
| `touch .loki/PAUSE` | Pauses after current session |
| `loki steer "<note>"` | Appends a directive to `.loki/HUMAN_INPUT.md` (needs `LOKI_PROMPT_INJECTION=1`); v8.0.0 |
| `echo "instructions" > .loki/HUMAN_INPUT.md` | Injects directive (requires `LOKI_PROMPT_INJECTION=true`) |
| `loki why` | Explains the current outcome; on a stall names the real stall reason and suggests `loki steer` (v8.0.0) |
| `touch .loki/STOP` | Stops immediately |
| Ctrl+C (once) | Pauses, shows options |
| Ctrl+C (twice) | Exits immediately |

### Security: Prompt Injection (v5.6.1)

**DISABLED by default** for enterprise security. Prompt injection via `HUMAN_INPUT.md` is blocked unless explicitly enabled.

```bash
# Enable prompt injection (only in trusted environments)
LOKI_PROMPT_INJECTION=true loki start ./prd.md

# Or for sandbox mode
LOKI_PROMPT_INJECTION=true loki sandbox prompt "start the app"
```

### Hints vs Directives

| Type | File | Behavior |
|------|------|----------|
| **Directive** | `.loki/HUMAN_INPUT.md` | Active instruction (requires `LOKI_PROMPT_INJECTION=true`) |

**Example directive** (only works with `LOKI_PROMPT_INJECTION=true`):
```bash
echo "Check all .astro files for missing BaseLayout imports." > .loki/HUMAN_INPUT.md
```

---

## Complexity Tiers (v3.4.0)

Auto-detected or force with `LOKI_COMPLEXITY`:

| Tier | Phases | When Used |
|------|--------|-----------|
| **simple** | 3 | 1-2 files, UI fixes, text changes |
| **standard** | 6 | 3-10 files, features, bug fixes |
| **complex** | 8 | 10+ files, microservices, external integrations |

---

## Managed Agents Integration (v7.2.0)

Opt-in integration with Claude Managed Agents (released Apr 2026). Gives
Loki cross-project audited memory and real multiagent councils. Features
are BAKED INTO existing RARV-C and council flows -- no new commands to
learn.

**All flags default false.** Default behavior is identical to v7.2.0.

| Flag | Purpose | Status |
|------|---------|--------|
| `LOKI_MANAGED_AGENTS` | Parent gate; required for every managed path | stable |
| `LOKI_MANAGED_MEMORY` | REASON augment + REFLECT shadow-write from `.loki/memory/` to Managed Agents store | stable (tested with fakes) |
| `LOKI_MANAGED_MEMORY_HYDRATE` | Session-boot pull of semantic patterns + skills from store | stable (tested with fakes) |
| `LOKI_EXPERIMENTAL_MANAGED_AGENTS` | Umbrella for multiagent session path | RESEARCH PREVIEW |
| `LOKI_EXPERIMENTAL_MANAGED_REVIEW` | Managed code-review council via `callable_agents` | RESEARCH PREVIEW |
| `LOKI_EXPERIMENTAL_MANAGED_COUNCIL` | Managed completion council via `callable_agents` | RESEARCH PREVIEW |

Fail-fast: child-on + parent-off exits 2 with clear error. API
unreachable falls back to local path with a `managed_agents_fallback`
event to `.loki/managed/events.ndjson`. No retry storm.

**Flip-on order (recommended):**
1. `LOKI_MANAGED_AGENTS=true LOKI_MANAGED_MEMORY=true` (memory mirror).
2. Add `LOKI_MANAGED_MEMORY_HYDRATE=true` after one-week soak.
3. Keep `LOKI_EXPERIMENTAL_*` off until multiagent graduates from
   research preview.

**NOT TESTED against live Anthropic API.** Automated CI uses
`memory/managed_memory/fakes.py`. Beta heade

… (truncated)