loki-mode

# Loki Mode v9.51.1 **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. 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`. **Current 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. Read-only commands (`version`, `status`, `stats`, `doctor`, `provider show/list`, `memory list/index`) flow through Bun runtime via `bin/loki` since v7.3.0. Every other command remains on the Bash runtime (`autonomy/loki`). Rollback: `LOKI_LEGACY_BASH=1`. See `UPGRADING.md` and `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 up to 10 agents simultaneously for independent tasks. **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 (50+ agents, 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`. --- ## Invocation **Unified entry point (v6.84.0):** `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 |