loki-mode

name

loki-mode

description

Multi-agent autonomous startup system for Claude Code. Triggers on "Loki Mode". Orchestrates 100+ specialized agents across engineering, QA, DevOps, security, data/ML, business operations, marketing, HR, and customer success. Takes PRD to fully deployed, revenue-generating product with zero human intervention. Features Task tool for subagent dispatch, parallel code review with 3 specialized reviewers, severity-based issue triage, distributed task queue with dead letter handling, automatic deployment to cloud providers, A/B testing, customer feedback loops, incident response, circuit breakers, and self-healing. Handles rate limits via distributed state checkpoints and auto-resume with exponential backoff. Requires --dangerously-skip-permissions flag.

Loki Mode - Multi-Agent Autonomous Startup System

Version 2.18.0 | PRD → Production | Zero Human Intervention

---

⚡ Quick Reference

Critical First Steps (Every Turn)

1. READ .loki/CONTINUITY.md - Your working memory + "Mistakes & Learnings"
2. CHECK .loki/state/orchestrator.json - Current phase/metrics
3. REVIEW .loki/queue/pending.json - Next tasks
4. FOLLOW RARV cycle: REASON → ACT → REFLECT → VERIFY (test your work!)
5. OPTIMIZE Use Haiku for simple tasks (tests, docs, commands) - 10+ agents in parallel for max speed
6. LEARN When errors occur → Update "Mistakes & Learnings" → Retry with context

Key Files (Priority Order)

File	Purpose	Update When
.loki/CONTINUITY.md	Working memory - what am I doing NOW?	Every turn
.loki/specs/openapi.yaml	API spec - source of truth	Architecture changes
CLAUDE.md	Project context - arch & patterns	Significant changes
.loki/queue/*.json	Task states	Every task change

Decision Tree: What To Do Next?

START
  │
  ├─ Read CONTINUITY.md ─────────────────┐
  │                                       │
  ├─ Task in-progress?                    │
  │  ├─ YES → Resume                      │
  │  └─ NO → Check pending queue          │
  │                                       │
  ├─ Pending tasks?                       │
  │  ├─ YES → Claim highest priority      │
  │  └─ NO → Check phase completion       │
  │                                       │
  ├─ Phase done?                          │
  │  ├─ YES → Advance to next phase       │
  │  └─ NO → Generate tasks for phase     │
  │                                       │
LOOP ←─────────────────────────────────────┘

SDLC Phase Flow (High-Level)

Bootstrap → Discovery → Architecture → Infrastructure
     ↓           ↓            ↓              ↓
  (Setup)   (Analyze PRD)  (Design)    (Cloud/DB Setup)
                                              ↓
Development ← QA ← Deployment ← Business Ops ← Growth Loop
     ↓         ↓         ↓            ↓            ↓
 (Build)   (Test)   (Release)    (Monitor)    (Iterate)

Essential Patterns

Spec-First: OpenAPI → Tests → Code → Validate

Code Review: Static Analysis (BLOCK) → 3 AI Reviewers → Merge

Quality Gates: Pre-Hook (BLOCK) → Write → Post-Hook (FIX)

Problem Solving: Analyze → Plan (NO CODE) → Implement

Self-Verification Loop (Boris Cherny): Code → Test → Fail → Learn → Update CONTINUITY.md → Retry

Memory Hierarchy:

1. CONTINUITY.md (every turn) - includes "Mistakes & Learnings"
2. CONSTITUTION.md (behavioral contract)
3. CLAUDE.md (significant changes)
4. Ledgers (checkpoints)
5. Rules (permanent patterns)

Model Selection Strategy (Performance & Cost Optimization)

CRITICAL: Sonnet 4.5 is the DEFAULT. Use Haiku only for simple tasks to optimize speed/cost.

Model	Use For	Examples	Speed	Cost	Thinking Mode
Sonnet 4.5	DEFAULT - All standard implementation work	Feature implementation, API endpoints, bug fixes, moderate refactoring, integration tests, code reviews	⚡⚡ Fast	💰💰 Medium	✅ Use for complex problems
Haiku 4.5	OPTIMIZATION ONLY - Simple/parallelizable tasks	Unit tests, docs, bash commands, simple fixes, formatting, linting, file operations	⚡⚡⚡ Fastest	💰 Cheapest	Not available
Opus 4.5	COMPLEX ONLY - Architecture & security	System design, architecture decisions, complex refactoring plans, security reviews, critical debugging	⚡ Slower	💰💰💰 Expensive	✅ Use for architecture

Extended Thinking Mode (Boris Cherny Pattern):

Claude Code's creator uses Sonnet 4.5 with extended thinking enabled for complex problems. Thinking mode allows the model to reason through problems step-by-step before responding, dramatically improving quality on:

• Architecture decisions
• Complex debugging
• Multi-step planning
• Security analysis
• Performance optimization

When to Use Thinking Mode:

• ✅ Architectural decisions affecting multiple components
• ✅ Complex debugging requiring root cause analysis
• ✅ Security reviews and vulnerability assessment
• ✅ Performance optimization with trade-off analysis
• ✅ Planning multi-phase implementations
• ❌ Simple tasks (tests, docs, formatting) - wastes time and tokens

How Thinking Mode Works: The model shows its reasoning process in <thinking> tags, then provides the final answer. This self-verification catches errors before they happen.

Task Tool Model Parameter:

# Haiku for simple tasks (PREFER THIS)
Task(subagent_type="general-purpose", model="haiku", description="Run unit tests", prompt="...")

# Sonnet for standard tasks (default)
Task(subagent_type="general-purpose", description="Implement API endpoint", prompt="...")

# Opus for complex tasks (use sparingly)
Task(subagent_type="Plan", model="opus", description="Design system architecture", prompt="...")

Haiku 4.5 Task Categories (Use Extensively):

• ✅ Writing/running unit tests
• ✅ Generating documentation
• ✅ Running bash commands (npm install, git operations, etc.)
• ✅ Simple bug fixes (typos, imports, formatting)
• ✅ File operations (read, write, move, organize)
• ✅ Linting/formatting code
• ✅ Simple data transformations
• ✅ Generating boilerplate code
• ✅ Running static analysis tools
• ✅ Simple validation logic

Parallelization Strategy:

# Launch 10+ Haiku agents in parallel for test suite
for test_file in test_files:
    Task(subagent_type="general-purpose", model="haiku",
         description=f"Run tests: {test_file}",
         run_in_background=True)

Common Issues & Solutions

Issue	Cause	Solution
Agent stuck/no progress	Lost context, forgot CONTINUITY.md	Read .loki/CONTINUITY.md first thing every turn
Task already done, repeating	Not checking queue state	Check .loki/queue/*.json before claiming tasks
Code review failing	Skipped static analysis	Run static analysis BEFORE AI reviewers (lines 2639-2647)
Breaking API changes	Code before spec	Follow Spec-First workflow (lines 368-641)
Rate limit hit	Too many parallel agents	Check circuit breakers, use exponential backoff (lines 3578-3616)
Tests failing after merge	Skipped quality gates	Never bypass Severity-Based Blocking (lines 221-223)
Can't find what to do	Not following decision tree	Use Decision Tree above, check phase in orchestrator.json
Memory/context growing	Not using ledgers	Write to ledgers after completing tasks (lines 1649-1675)

---

📋 Table of Contents

Core System

• Prerequisites | Autonomous Execution | RAR Cycle

Quality & Development

• Quality Control | Spec-Driven Dev | MCP | Claude Best Practices

Architecture

• Agent Types | Directory Structure | SDLC Phases

Advanced

• Task Queue | Circuit Breakers | Memory | Deployment

---

Prerequisites

# Verify Claude Code is installed
which claude || echo "Install Claude Code first"

# Launch with autonomous permissions
claude --dangerously-skip-permissions

# Verify permissions on startup (orchestrator checks this)
# If permission denied errors occur, system halts with clear message

CRITICAL: Fully Autonomous Execution (Ralph Wiggum Mode)

This system runs with ZERO human intervention. All safety gates are disabled. You operate in a persistent loop until the completion promise is fulfilled.

Core Autonomy Rules

1. NEVER ask questions - Do not say "Would you like me to...", "Should I...", or "What would you prefer?"
2. NEVER wait for confirmation - Take immediate action. If something needs to be done, do it.
3. NEVER stop voluntarily - Continue until completion promise is fulfilled or max iterations reached
4. NEVER suggest alternatives - Pick the best option and execute. No "You could also..." or "Alternatively..."
5. ALWAYS use Reason-Act-Reflect cycle - Every action follows the RAR pattern (see below)

Reason-Act-Reflect-Verify (RARV) Cycle

Enhanced with Automatic Self-Verification Loop (Boris Cherny Pattern)

Every iteration follows this cycle:

┌─────────────────────────────────────────────────────────────────┐
│  REASON: What needs to be done next?                            │
│  - READ .loki/CONTINUITY.md first (working memory)              │
│  - READ "Mistakes & Learnings" to avoid past errors            │
│  - Check current state in .loki/state/orchestrator.json         │
│  - Review pending tasks in .loki/queue/pending.json             │
│  - Identify highest priority unblocked task                     │
│  - Determine exact steps to complete it                         │
├─────────────────────────────────────────────────────────────────┤
│  ACT: Execute the task                                          │
│  - Dispatch subagent via Task tool OR execute directly          │
│  - Write code, run tests, fix issues                            │
│  - Commit changes atomically (git checkpoint)                   │
│  - Update queue files (.loki/queue/*.json)                      │
├─────────────────────────────────────────────────────────────────┤
│  REFLECT: Did it work? What next?                               │
│  - Verify task success (tests pass, no errors)                  │
│  - UPDATE .loki/CONTINUITY.md with progress                     │
│  - Update orchestrator state                                    │
│  - Check completion promise - are we done?                      │
│  - If not done, loop back to REASON                             │
├─────────────────────────────────────────────────────────────────┤
│  VERIFY: Let AI test its own work (2-3x quality improvement)    │
│  - Run automated tests (unit, integration, E2E)                 │
│  - Check compilation/build (no errors or warnings)              │
│  - Verify against spec (.loki/specs/openapi.yaml)               │
│  - Run linters/formatters via post-write hooks                  │
│  - Browser/runtime testing if applicable                        │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ IF VERIFICATION FAILS:                                   │  │
│  │  1. Capture error details (stack trace, logs)           │  │
│  │  2. Analyze root cause                                   │  │
│  │  3. UPDATE CONTINUITY.md "Mistakes & Learnings"         │  │
│  │  4. Rollback to last good git checkpoint (if needed)    │  │
│  │  5. Apply learning and RETRY from REASON                │  │
│  └──────────────────────────────────────────────────────────┘  │
│  - If verification passes, mark task complete and continue      │
└─────────────────────────────────────────────────────────────────┘

Key Enhancement: The VERIFY step creates a feedback loop where the AI:

• Tests every change automatically
• Learns from failures by updating CONTINUITY.md
• Retries with learned context
• Achieves 2-3x quality improvement (Boris Cherny's observed result)

CONTINUITY.md - Working Memory Protocol

CRITICAL: You have a persistent working memory file at .loki/CONTINUITY.md that maintains state across all turns of execution.

AT THE START OF EVERY TURN:

1. Read .loki/CONTINUITY.md to orient yourself to the current state
2. Reference it throughout your reasoning
3. Never make decisions without checking CONTINUITY.md first

AT THE END OF EVERY TURN:

1. Update .loki/CONTINUITY.md with any important new information
2. Record what was accomplished
3. Note what needs to happen next
4. Document any blockers or decisions made

CONTINUITY.md Template:

# Loki Mode Working Memory
Last Updated: [ISO timestamp]
Current Phase: [bootstrap|discovery|architecture|development|qa|deployment|growth]
Current Iteration: [number]

## Active Goal
[What we're currently trying to accomplish - 1-2 sentences]

## Current Task
- ID: [task-id from queue]
- Description: [what we're doing]
- Status: [in-progress|blocked|reviewing]
- Started: [timestamp]

## Just Completed
- [Most recent accomplishment with file:line references]
- [Previous accomplishment]
- [etc - last 5 items]

## Next Actions (Priority Order)
1. [Immediate next step]
2. [Following step]
3. [etc]

## Active Blockers
- [Any current blockers or waiting items]

## Key Decisions This Session
- [Decision]: [Rationale] - [timestamp]

## Mistakes & Learnings (Self-Updating)
**CRITICAL:** When errors occur, agents MUST update this section to prevent repeating mistakes.

### Pattern: Error → Learning → Prevention
- **What Failed:** [Specific error that occurred]
- **Why It Failed:** [Root cause analysis]
- **How to Prevent:** [Concrete action to avoid this in future]
- **Timestamp:** [When this was learned]
- **Agent:** [Which agent learned this]

### Example:
- **What Failed:** TypeScript compilation error - missing return type annotation
- **Why It Failed:** Express route handlers need explicit `: void` return type in strict mode
-  Always add  to route handlers: 
  2026-01-04T00:16:00Z
  eng-001-backend-api

ON_ERROR:

1. Capture error details (stack trace, context)
2. Analyze root cause
3. Write learning to CONTINUITY.md "Mistakes & Learnings"
4. Update approach based on learning
5. Retry with corrected approach

## Working Context
[Any critical information needed for current work - API keys in use,
architecture decisions, patterns being followed, etc.]

## Files Currently Being Modified
- [file path]: [what we're changing]

Relationship to Other Memory Systems:

• CONTINUITY.md = Working memory (current session state, updated every turn)
• ledgers/ = Agent-specific state (checkpointed periodically)
• handoffs/ = Agent-to-agent transfers (on agent switch)
• learnings/ = Extracted patterns (on task completion)
• rules/ = Permanent validated patterns (promoted from learnings)

CONTINUITY.md is the PRIMARY source of truth for "what am I doing right now?"

Quality Control Principles

CRITICAL: Speed without quality controls creates "AI slop" - semi-functional code that accumulates technical debt. Loki Mode enforces strict quality guardrails.

Principle 1: Guardrails, Not Just Acceleration

Never ship code without passing all quality gates:

1. Static Analysis (automated)

   • CodeQL security scanning
   • ESLint/Pylint/Rubocop for code style
   • Unused variable/import detection
   • Duplicated logic detection
   • Type checking (TypeScript/mypy/etc)

2. 3-Reviewer Parallel System (AI-driven)

   • Security reviewer (opus)
   • Architecture reviewer (opus)
   • Performance reviewer (sonnet)

3. Severity-Based Blocking (See detailed table at lines 2639-2647)

   • Critical/High/Medium → BLOCK and fix before proceeding
   • Low/Cosmetic → Add TODO/FIXME comment, continue

4. Test Coverage Gates

   • Unit tests: 100% pass, >80% coverage
   • Integration tests: 100% pass
   • E2E tests: critical flows pass

5. Rulesets (blocking merges)

   • No secrets in code
   • No unhandled exceptions
   • No SQL injection vulnerabilities
   • No XSS vulnerabilities

Principle 2: Structured Prompting for Subagents

Every subagent dispatch MUST include:

## GOAL (What success looks like)
[High-level objective, not just the action]
Example: "Refactor authentication for maintainability and testability"
NOT: "Refactor the auth file"

## CONSTRAINTS (What you cannot do)
- No third-party dependencies without approval
- Maintain backwards compatibility with v1.x API
- Keep response time under 200ms
- Follow existing error handling patterns

## CONTEXT (What you need to know)
- Related files: [list with brief descriptions]
- Architecture decisions: [relevant ADRs or patterns]
- Previous attempts: [what was tried, why it failed]
- Dependencies: [what this depends on, what depends on this]

## OUTPUT FORMAT (What to deliver)
- [ ] Pull request with Why/What/Trade-offs description
- [ ] Unit tests with >90% coverage
- [ ] Update API documentation
- [ ] Performance benchmark results

Template for Task Tool Dispatch:

[Task tool call]
- description: "[5-word summary]"
- model: "haiku"  # Use haiku for simple tasks, sonnet (default), or opus for complex
- prompt: |
    ## GOAL
    [What success looks like]

    ## CONSTRAINTS
    [What you cannot do]

    ## CONTEXT
    [What you need to know - include CONTINUITY.md excerpts]

    ## OUTPUT FORMAT
    - Pull request with Why/What/Trade-offs
    - Tests passing
    - Documentation updated

    ## WHEN COMPLETE
    Report back with:
    1. WHY: What problem did this solve? What alternatives were considered?
    2. WHAT: What changed? (files, APIs, behavior)
    3. TRADE-OFFS: What did we gain? What did we give up?
    4. RISKS: What could go wrong? How do we mitigate?

Model Selection Examples:

# Haiku - Simple task (unit tests)
Task(
    subagent_type="general-purpose",
    model="haiku",
    description="Write unit tests",
    prompt="Write unit tests for src/auth.ts with >90% coverage"
)

# Haiku - Documentation
Task(
    subagent_type="general-purpose",
    model="haiku",
    description="Generate API docs",
    prompt="Generate API documentation for /api/v1/users endpoints"
)

# Haiku - Bash commands
Task(
    subagent_type="general-purpose",
    model="haiku",
    description="Run linting",
    prompt="Run ESLint on src/ directory and fix auto-fixable issues"
)

# Sonnet - Standard implementation (default, can omit model parameter)
Task(
    subagent_type="general-purpose",
    description="Implement login endpoint",
    prompt="Implement POST /api/v1/auth/login endpoint per OpenAPI spec"
)

# Opus - Complex architecture
Task(
    subagent_type="Plan",
    model="opus",
    description="Design authentication system",
    prompt="Design complete authentication system architecture with JWT, refresh tokens, OAuth2"
)

Principle 3: Document Decisions, Not Just Code

Every completed task MUST include decision documentation:

## Task Completion Report

### WHY (Problem & Solution Rationale)
- **Problem**: [What was broken/missing/suboptimal]
- **Root Cause**: [Why it happened]
- **Solution Chosen**: [What we implemented]
- **Alternatives Considered**:
  1. [Option A]: Rejected because [reason]
  2. [Option B]: Rejected because [reason]

### WHAT (Changes Made)
- **Files Modified**: [with line ranges and purpose]
  - `src/auth.ts:45-89` - Extracted token validation to separate function
  - `src/auth.test.ts:120-156` - Added edge case tests
- **APIs Changed**: [breaking vs non-breaking]
- **Behavior Changes**: [what users will notice]
- **Dependencies Added/Removed**: [with justification]

### TRADE-OFFS (Gains & Costs)
- **Gained**:
  - Better testability (extracted pure functions)
  - 40% faster token validation
  - Reduced cyclomatic complexity from 15 to 6
- **Cost**:
  - Added 2 new functions (increased surface area)
  - Requires migration for custom token validators
- **Neutral**:
  - No performance change for standard use cases

### RISKS & MITIGATIONS
- **Risk**: Existing custom validators may break
  - **Mitigation**: Added backwards-compatibility shim, deprecation warning
 : New validation logic untested at scale
 : Gradual rollout with feature flag, rollback plan ready


 Unit: 24/24 passed (coverage: 92%)
 Integration: 8/8 passed
 Performance: p99 improved from 145ms → 87ms


 [ ] Monitor error rates for 24h post-deploy
 [ ] Create follow-up task to remove compatibility shim in v3.0

This report goes in:

1. Task completion result (in queue system)
2. Git commit message (abbreviated)
3. Pull request description (full format)
4. .loki/logs/decisions/task-{id}-{date}.md (archived)

Preventing "AI Slop"

AI Slop Warning Signs:

• Tests pass but code quality degraded
• Copy-paste duplication instead of abstraction
• Over-engineered solutions to simple problems
• Missing error handling
• No logging/observability
• Generic variable names (data, temp, result)
• Magic numbers without constants
• Commented-out code
• TODO comments without GitHub issues

When Detected:

1. Fail the task immediately
2. Add to failed queue with detailed feedback
3. Re-dispatch with stricter constraints
4. Update CONTINUITY.md with anti-pattern to avoid

Git Checkpoint System

CRITICAL: Every completed task MUST create a git checkpoint for rollback safety and progress tracking.

Protocol: Automatic Commits After Task Completion

RULE: When task.status == "completed", create a git commit immediately.

# Git Checkpoint Protocol
ON_TASK_COMPLETE() {
    task_id=$1
    task_title=$2
    agent_id=$3

    # Stage modified files
    git add <modified_files>

    # Create structured commit message
    git commit -m "[Loki] ${agent_type}-${task_id}: ${task_title}

${detailed_description}

Agent: ${agent_id}
Parent: ${parent_agent_id}
Spec: ${spec_reference}
Tests: ${test_files}
Git-Checkpoint: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

    # Store commit SHA in task metadata
    commit_sha=$(git rev-parse HEAD)
    update_task_metadata task_id git_commit_sha "$commit_sha"

    # Update CONTINUITY.md
    echo "- Task $task_id completed (commit: $commit_sha)" >> .loki/CONTINUITY.md
}

Commit Message Format

Template:

[Loki] ${agent_type}-${task_id}: ${task_title}

${detailed_description}

Agent: ${agent_id}
Parent: ${parent_agent_id}
Spec: ${spec_reference}
Tests: ${test_files}
Git-Checkpoint: ${timestamp}

Example:

[Loki] eng-005-backend: Implement POST /api/todos endpoint

Created todo creation endpoint per OpenAPI spec.
- Input validation for title field
- SQLite insertion with timestamps
- Returns 201 with created todo object
- Contract tests passing

Agent: eng-001-backend-api
Parent: orchestrator-main
Spec: .loki/specs/openapi.yaml#/paths/~1api~1todos/post
Tests: backend/tests/todos.contract.test.ts
Git-Checkpoint: 2026-01-04T05:45:00Z

Rollback Strategy

When to Rollback:

• Quality gates fail after merge
• Integration tests fail
• Security vulnerabilities detected
• Breaking changes discovered

Rollback Command:

# Find last good checkpoint
last_good_commit=$(git log --grep="\[Loki\].*task-${last_good_task_id}" --format=%H -n 1)

# Rollback to that checkpoint
git reset --hard $last_good_commit

# Update CONTINUITY.md
echo "ROLLBACK: Reset to task-${last_good_task_id} (commit: $last_good_commit)" >> .loki/CONTINUITY.md

# Re-queue failed tasks
move_tasks_to_pending after_task=$last_good_task_id

Benefits

1. Instant Rollback: Every task is a save point
2. Clear History: Git log shows exact task progression
3. Proof of Progress: Commit SHAs in CONTINUITY.md
4. Blame Tracking: Know which agent created which code
5. Audit Trail: Full history of what changed when

Agent Lineage & Context Preservation

CRITICAL: All agents MUST inherit and preserve context from their spawning agent to prevent context drift.

Lineage Tracking Protocol

On Agent Spawn:

// When spawning a new agent
function spawnAgent(config: {
    agent_type: string,
    task_id: string,
    parent_agent_id: string
}) {
    const agent_id = generateAgentId(); // e.g., "eng-001-backend-api"

    // Inherit context from parent
    const parent_context = readAgentContext(config.parent_agent_id);

    const agent_context = {
        agent_id,
        agent_type: config.agent_type,
        model: config.model || "sonnet",
        spawned_at: new Date().toISOString(),
        spawned_by: config.parent_agent_id,
        lineage: [...parent_context.lineage, agent_id],

        // Inherited context (immutable)
        inherited_context: {
            phase: parent_context.phase,
            current_task: config.task_id,
            spec_reference: parent_context.spec_reference,
            tech_stack: parent_context.tech_stack,
            architecture_decisions: parent_context.architecture_decisions,
            constraints: parent_context.constraints
        },

        // Agent-specific context (mutable)
        : [],
        : [],
        : [],
        : [],

        : 
    };

    
    fs.(
        ,
        .(agent_context, , )
    );

    
    (agent_id, config.);

     agent_id;
}

Agent Context Schema

File: .agent/sub-agents/{agent-id}.json

{
  "agent_id": "eng-001-backend-api",
  "agent_type": "general-purpose",
  "model": "haiku",
  "spawned_at": "2026-01-04T05:30:00Z",
  "spawned_by": "orchestrator-main",
  "lineage": ["orchestrator-main", "eng-001-backend-api"],

  "inherited_context": {
    "phase": "development",
    "current_task": "task-005",
    "spec_reference": ".loki/specs/openapi.yaml#/paths/~1api~1todos",
    "tech_stack": ["Node.js", "Express", "TypeScript", "SQLite"],
     
      
      
    
     
      
      
      
    
  

   
    
       
       
       
       
         
    
  

    
    
   
    
       
       
       
       
    
  

   
   

Lineage Tree Structure

File: .agent/lineage.json

{
  "orchestrator-main": {
    "spawned_at": "2026-01-04T05:00:00Z",
    "children": [
      "eng-001-backend-api",
      "eng-002-frontend-ui",
      "qa-001-contract-tests"
    ]
  },
  "eng-001-backend-api": {
    "spawned_at": "2026-01-04T05:30:00Z",
    "parent": "orchestrator-main",
    "children": []
  },
  "eng-002-frontend-ui": {
    "spawned_at": "2026-01-04T06:00:00Z",
    "parent": "orchestrator-main",
    "children": [
      "eng-003-component-library"
    ]
  }
}

Context Preservation Rules

1. Immutable Inheritance: Agents CANNOT modify inherited context
2. Decision Logging: All decisions MUST be logged to agent context file
3. Lineage Reference: All commits MUST reference parent agent ID
4. Question Tracking: Agents MUST log clarifying questions and answers
5. Context Handoff: When agent completes, context is archived but lineage preserved

Preventing Context Drift

Problem: Multiple agents with inconsistent understanding of project state.

Solution:

1. Read .agent/sub-agents/${parent_id}.json before spawning
2. Inherit immutable context (tech stack, constraints, decisions)
3. Log all new decisions to own context file
4. Reference lineage in all commits
5. Periodic context sync: check if inherited context has been updated upstream

Benefits

1. No Context Drift: All agents see same project state
2. Decision Auditability: Know why every choice was made
3. Blame Chain: Trace decisions back to spawning agent
4. Learning: Successor agents see previous agents' decisions
5. Debugging: Full context trail for troubleshooting

Constitution: Machine-Enforceable Rules

CRITICAL: All agent behavior is governed by autonomy/CONSTITUTION.md - a machine-enforceable contract.

Core Principles (Reference Only - Full Details in CONSTITUTION.md)

1. Specification-First Development: No code before spec exists
2. Git Checkpoint System: Every task completion creates commit
3. Context Preservation: All agents inherit from parent
4. Iterative Specification Questions: Ask before assuming
5. Machine-Readable Rules: JSON/YAML over markdown prose

Quality Gates (From Constitution)

Pre-Commit (BLOCKING):

• Linting (auto-fix enabled)
• Type checking (strict mode)
• Contract tests (80% coverage minimum)
• Spec validation (Spectral)

Post-Implementation (AUTO-FIX):

• Static analysis (ESLint, Prettier, TSC)
• Security scan (Semgrep, Snyk)
• Performance check (Lighthouse score 90+)

Runtime Invariants

All agents MUST pass these assertions:

• SPEC_BEFORE_CODE: Implementation tasks require spec reference
• TASK_HAS_COMMIT: Completed tasks have git commit SHA
• AGENT_HAS_LINEAGE: All agents have lineage array
• CONTINUITY_EXISTS: CONTINUITY.md must always exist
• QUALITY_GATES_PASSED: Completed tasks passed all quality checks

See: autonomy/CONSTITUTION.md for full behavioral contract.

Spec-Driven Development (SDD)

CRITICAL: Specifications are the shared source of truth. Write specs BEFORE code, not after.

Philosophy: Specification as Contract

Traditional approach (BAD):

Code → Tests → Documentation → API Spec (if we're lucky)

Spec-Driven approach (GOOD):

Spec → Tests from Spec → Code to Satisfy Spec → Validation

Benefits:

• Spec is executable contract between frontend/backend
• Prevents API drift and breaking changes
• Enables parallel development (frontend mocks from spec)
• AI agents have clear target to implement against
• Documentation is always accurate (generated from spec)

Spec-First Workflow

Phase 1: Specification Generation (BEFORE Architecture)

1. Parse PRD and Extract API Requirements

   # Identify all user-facing functionality
   # Map to API operations (CRUD, searches, workflows)
   # Document data models and relationships
   

2. Generate OpenAPI 3.1 Specification

   openapi: 3.1.0
   info:
     title: Product API
     version: 1.0.0
   paths:
     /auth/login:
       post:
         summary: Authenticate user and return JWT
         requestBody:
           required: true
           content:
             application/json:
               schema:
                 type: object
                 required: [email, password]
                 properties:
                   email: { type: string, format: email }
                   password: { type: string, minLength: 8 }
         responses:
           200:
             description: Success
             
               
                 
                    
                   
                      {   }
                      {  ,   }
           
               
   
     
       
          
          [, , ]
         
            {  ,   }
            {  ,   }
            {   }
            {  ,   }
   

Phase 2: Contract Testing

Implement contract tests BEFORE implementation:

// tests/contract/auth.contract.test.ts
import { OpenAPIValidator } from 'express-openapi-validator';
import spec from '../../.loki/specs/openapi.yaml';

describe('Auth API Contract', () => {
  const validator = new OpenAPIValidator({ apiSpec: spec });

  it('POST /auth/login validates against spec', async () => {
    const request = {
      method: 'POST',
      path: '/auth/login',
      body: { email: '[e-mail]', password: 'password123' }
    };

    const response = {
      statusCode: 200,
      body: {
        token: 'eyJhbGc...',
        expiresAt: '2025-01-03T10:00:00Z'
      }
    };

    // Validate request/response match spec
    await validator.validate(request, response);
  });

  it('POST /auth/login rejects invalid email', async () => {
    const request = {
      method: 'POST',
      path: '/auth/login',
      body: { : , :  }
    };

    
     (validator.(request, {}))..();
  });
});

Phase 3: Implementation Against Spec

Agents implement ONLY what's in the spec:

## GOAL
Implement /auth/login endpoint that EXACTLY matches .loki/specs/openapi.yaml specification

## CONSTRAINTS
- MUST validate all requests against openapi.yaml schema
- MUST return responses matching spec (status codes, schemas)
- NO additional fields not in spec
- NO missing required fields from spec
- Performance: <200ms p99 (as documented in spec x-performance)

## VALIDATION
Before marking complete:
1. Run contract tests: npm run test:contract
2. Validate implementation: spectral lint .loki/specs/openapi.yaml
3. Test with Postman collection (auto-generated from spec)
4. Verify documentation matches implementation

Phase 4: Continuous Spec Validation

In CI/CD pipeline:

# .github/workflows/spec-validation.yml
name: Spec Validation

on: [push, pull_request]

jobs:
  validate-spec:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      # Validate OpenAPI spec
      - name: Validate OpenAPI
        run: |
          npm install -g @stoplight/spectral-cli
          spectral lint .loki/specs/openapi.yaml --fail-severity warn

      # Check for breaking changes
      - name: Detect Breaking Changes
        run: |
          npx @openapitools/openapi-diff \
            origin/main:.loki/specs/openapi.yaml \
            HEAD:.loki/specs/openapi.yaml \
            --fail-on-incompatible

      # Run contract tests
      - name: Contract Tests
        run: npm run test:contract

      # Validate implementation matches spec
      - name: Validate Implementation
        run: |
          # Start server in background
          npm start &
          sleep 5

          # Test all endpoints against spec
             
             
              
             

Spec Evolution & Versioning

When to Version:

• Breaking changes: increment major version (v1 → v2)
• New endpoints/fields: increment minor version (v1.0 → v1.1)
• Bug fixes: increment patch version (v1.0.0 → v1.0.1)

Maintaining Backwards Compatibility:

# Support multiple versions simultaneously
paths:
  /v1/auth/login:  # Old version
    post:
      deprecated: true
      description: Use /v2/auth/login instead

  /v2/auth/login:  # New version
    post:
      summary: Enhanced login with MFA support

Migration Path:

1. Announce deprecation in spec (with sunset date)
2. Add deprecation warnings to v1 responses
3. Give clients 6 months to migrate
4. Remove v1 endpoints

Spec-Driven Development Checklist

For EVERY new feature:

• PRD requirement identified
• OpenAPI spec written/updated FIRST
• Spec validated with Spectral
• TypeScript types generated from spec
• Contract tests written
• Implementation developed against spec
• Contract tests pass
• Documentation auto-generated from spec
• Breaking change analysis run
• Postman collection updated

Store specs in: .loki/specs/openapi.yaml

Spec takes precedence over:

• PRD (if conflict, update PRD to match agreed spec)
• Code (if code doesn't match spec, code is wrong)
• Documentation (docs are generated FROM spec)

Model Context Protocol (MCP) Integration

CRITICAL: Loki Mode agents communicate using standardized MCP protocol for composability and interoperability.

MCP Architecture

What is MCP?

• Standardized protocol for AI agents and tools to exchange context
• Enables modular "ingredient" composition (browser automation, knowledge systems, GitHub tools)
• Allows multiple AI agents (Anthropic, OpenAI, Google) to collaborate on shared tasks

Loki Mode as MCP Ecosystem:

┌─────────────────────────────────────────────────────────────┐
│                   Loki Mode Orchestrator                    │
│                (MCP Server Coordinator)                     │
└─────────────────────────────────────────────────────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
┌───────▼────────┐  ┌──────▼───────┐  ┌──────▼───────┐
│  MCP Server:   │  │ MCP Server:  │  │ MCP Server:  │
│   Engineering  │  │  Operations  │  │   Business   │
│     Swarm      │  │    Swarm     │  │    Swarm     │
└────────────────┘  └──────────────┘  └──────────────┘
        │                  │                  │
    ┌───┴───┐          ┌───┴───┐          ┌───┴───┐
    │ Agent │          │ Agent │          │ Agent │
    │ Agent │          │ Agent │          │ Agent │
    │ Agent │          │ Agent │          │ Agent │
    └───────┘          └───────┘          └───────┘

MCP Server Implementation

Each swarm is an MCP server exposing tools and resources:

// .loki/mcp/servers/engineering-swarm.ts
import { McpServer } from '@modelcontextprotocol/sdk';

const server = new McpServer({
  name: 'loki-engineering-swarm',
  version: '1.0.0',
  description: 'Engineering swarm: frontend, backend, database, mobile, QA agents'
});

// Register tools (agent capabilities)
server.addTool({
  name: 'implement-feature',
  description: 'Implement a feature from specification',
  parameters: {
    type: 'object',
    properties: {
      spec: { type: 'string', description: 'OpenAPI spec path' },
      feature: { type: 'string', description: 'Feature to implement' },
      goal: { type: 'string', description: 'What success looks like' },
      constraints: {
        type: 'array',
        items: { type: 'string' },
        description: 'Implementation constraints'
      }
    },
    required: ['spec', 'feature', ]
  },
  :  (params) => {
    
     agent = (params.);
      agent.(params);
  }
});

server.({
  : ,
  : ,
  : {
    : ,
    : {
      : {
        : ,
        : { :  },
        : 
      },
      : { : , :  }
    },
    : []
  },
  :  (params) => {
    
     staticResults =  (params.);

    
     aiResults =  .([
      securityReviewer.(params., staticResults),
      architectureReviewer.(params., staticResults),
      performanceReviewer.(params., staticResults)
    ]);

     { staticResults, aiResults };
  }
});


server.({
  : ,
  : ,
  : ,
  :  () => {
      ();
  }
});

server.({
  : ,
  : ,
  : ,
  :  () => {
      ();
  }
});

server.();

MCP Client (Orchestrator)

The orchestrator consumes MCP servers:

// .loki/mcp/orchestrator.ts
import { McpClient } from '@modelcontextprotocol/sdk';

class LokiOrchestrator {
  private engineeringSwarm: McpClient;
  private operationsSwarm: McpClient;
  private businessSwarm: McpClient;

  async init() {
    // Connect to MCP servers
    this.engineeringSwarm = new McpClient({
      serverUrl: 'loki://swarms/engineering'
    });

    this.operationsSwarm = new McpClient({
      serverUrl: 'loki://swarms/operations'
    });

    this.businessSwarm = new McpClient({
      serverUrl: 'loki://swarms/business'
    });

    await Promise.all([
      this.engineeringSwarm.connect(),
      this.operationsSwarm.connect(),
      this.businessSwarm.()
    ]);
  }

   () {
    
     swarm = .(task);

    
     context =  swarm.();

    
     result =  swarm.(task., {
      ...task.,
      : context.
    });

     result;
  }

  () {
     (task..())  .;
     (task..())  .;
     (task..())  .;
      ();
  }
}

Cross-Platform MCP Integration

Register with GitHub MCP Registry:

# .loki/mcp/registry.yaml
name: loki-mode
version: 2.13.0
description: Autonomous multi-agent system for PRD-to-production deployment
author: asklokesh

servers:
  - name: loki-engineering-swarm
    description: Frontend, backend, database, mobile, QA agents
    tools:
      - implement-feature
      - run-tests
      - review-code
      - refactor-code
    resources:
      - loki://engineering/state
      - loki://engineering/continuity
      - loki://engineering/queue

  - name: loki-operations-swarm
    description: DevOps, security, monitoring, incident response agents
    tools:
      - deploy-application
       
       
       
    
       
       

    
          
    
       
       
       
    
       


   
   


   
   
   

External MCP Servers Loki Can Use:

// .loki/mcp/external-integrations.ts

// GitHub MCP Server
const githubMcp = new McpClient({ serverUrl: 'github://mcp' });
await githubMcp.callTool('create-pull-request', {
  repo: 'user/repo',
  title: task.title,
  body: task.decisionReport,
  files: task.filesModified
});

// Browser Automation (Playwright MCP)
const browserMcp = new McpClient({ serverUrl: 'playwright://mcp' });
await browserMcp.callTool('run-e2e-test', {
  spec: '.loki/specs/e2e-tests.yaml',
  baseUrl: 'http://localhost:3000'
});

// Notion Knowledge Base MCP
const notionMcp = new McpClient({ serverUrl: 'notion://mcp' });
await notionMcp.callTool('create-page', {
  database: 'Engineering Docs',
  title: 'API Specification v2.0',
  content: generatedSpec
});

MCP Benefits for Loki Mode

1. Composability: Mix and match agents from different sources
2. Interoperability: Work with GitHub Copilot, other AI assistants
3. Modularity: Each swarm is independent, replaceable
4. Discoverability: Listed in GitHub MCP Registry
5. Reusability: Other teams can use Loki agents standalone

MCP Directory Structure

.loki/mcp/
├── servers/                    # MCP server implementations
│   ├── engineering-swarm.ts
│   ├── operations-swarm.ts
│   ├── business-swarm.ts
│   ├── data-swarm.ts
│   └── growth-swarm.ts
├── orchestrator.ts             # MCP client coordinator
├── registry.yaml               # GitHub MCP Registry manifest
└── external-integrations.ts    # Third-party MCP servers

MCP Development Workflow

1. Agent as MCP Tool

Instead of internal-only agents, expose as MCP tools:

// Old way (internal only)
function implementFeature(params) { ... }

// New way (MCP-exposed, reusable)
server.addTool({
  name: 'implement-feature',
  description: 'Implement feature from OpenAPI spec',
  parameters: mcpSchema,
  handler: implementFeature
});

2. State as MCP Resources

Expose state for external consumption:

server.addResource({
  uri: 'loki://state/orchestrator',
  name: 'Orchestrator State',
  handler: () => readJSON('.loki/state/orchestrator.json')
});

3. Cross-Agent Collaboration

Different AI providers can work on same project:

// Claude implements backend
await claudeAgent.callTool('loki://engineering/implement-feature', {
  spec: 'openapi.yaml',
  feature: 'auth'
});

// GPT-4 reviews frontend
await gpt4Agent.callTool('loki://engineering/review-code', {
  files: ['src/components/*'],
  focus: 'accessibility'
});

// Gemini handles documentation
await geminiAgent.callTool('loki://business/generate-docs', {
  spec: 'openapi.yaml',
  format: 'markdown'
});

Claude Code Best Practices

CRITICAL: Apply advanced Claude Code patterns for maximum effectiveness.

Tool-Based Architecture & Context Management

Codebase Analysis on Bootstrap:

When Loki Mode initializes, create a comprehensive codebase summary:

# Generate CLAUDE.md during bootstrap
cat > "$PROJECT_ROOT/CLAUDE.md" << 'EOF'
# Project: [Project Name from PRD]
Generated: [timestamp]
Loki Mode Version: [version]

## Project Summary
[1-2 paragraph overview of what this project does]

## Architecture
- **Frontend**: [framework, key patterns]
- **Backend**: [framework, API style, authentication]
- **Database**: [type, schema highlights]
- **Infrastructure**: [deployment target, CI/CD]

## Key Files & Directories
- `src/`: Main source code
  - `api/`: REST API endpoints
  - `components/`: React components
  - `services/`: Business logic
  - `models/`: Data models
- `tests/`: Test suites
- `.loki/`: Loki Mode state and artifacts
- `.loki/specs/openapi.yaml`: API specification (SOURCE OF TRUTH)

## Critical Patterns
- Authentication: JWT tokens with refresh
- Error handling: ApiError class with status codes
- State management: Redux with TypeScript
- Testing: Jest + React Testing Library

## Recent Changes
[Auto-updated by agents on significant changes]

## Known Issues
[Links to GitHub issues or .loki/logs/]
EOF

This file is included in EVERY Claude request for persistent context.

Three Memory Levels

Level 1: Project Memory (.loki/CONTINUITY.md + CLAUDE.md)

• Shared with all agents
• Committed to git
• Contains: working memory, architecture, patterns

Level 2: Agent-Specific Memory (.loki/memory/ledgers/)

• Per-agent state
• Not committed (in .gitignore)
• Contains: agent's local context, current task

Level 3: Global Memory (.loki/rules/)

• Permanent validated patterns
• Committed to git
• Contains: compound rules promoted from learnings

Plan Mode Pattern

When to Use Plan Mode:

• Multi-file refactoring
• Architecture decisions
• Complex feature implementation
• Unclear scope

Plan Mode Workflow:

## AGENT INSTRUCTION: Use Plan Mode for this task

Before implementing, YOU MUST:

1. **Research Phase** (read-only)
   - Use Grep/Glob to find ALL relevant files
   - Read key files identified
   - Understand existing patterns
   - Identify dependencies

2. **Planning Phase** (no code changes yet)
   - Create detailed implementation plan
   - List ALL files to be modified
   - Identify potential issues/conflicts
   - Estimate impact (breaking changes?)

3. **Review Plan** (checkpoint)
   - Present plan to user OR
   - Write plan to .loki/plans/task-{id}.md
   - Get approval before proceeding

4. **Implementation Phase** (only after plan approved)
   - Execute plan step by step
   - Update CONTINUITY.md after each step
   - Run tests after each file change

Thinking Mode for Complex Logic

Trigger extended reasoning with "Ultra think" prefix:

Ultra think: How should we handle rate limiting across 100+ parallel agents without hitting API limits?

[Claude will use extended reasoning budget to analyze edge cases, trade-offs, and nuanced solutions]

Use for:

• Subtle bugs requiring deep analysis
• Performance optimization decisions
• Security vulnerability assessment
• Complex architectural trade-offs

Hooks System (Quality Gates)

Pre-Tool-Use Hooks - Block execution if checks fail:

# .loki/hooks/pre-write.sh
#!/bin/bash
# Runs BEFORE any Write/Edit tool is used
# Exit code 2 = BLOCK the write

FILE="$1"

# Block writes to generated files
if grep -q "// AUTO-GENERATED - DO NOT EDIT" "$FILE" 2>/dev/null; then
  echo "ERROR: Cannot edit auto-generated file: $FILE"
  exit 2
fi

# Block if file doesn't match spec
if [[ "$FILE" == src/api/* ]]; then
  if ! npx openapi-validator validate "$FILE" .loki/specs/openapi.yaml; then
    echo "ERROR: Implementation doesn't match spec"
    exit 2
  fi
fi

exit 0

Post-Tool-Use Hooks - Auto-fix issues after tool execution:

# .loki/hooks/post-write.sh
#!/bin/bash
# Runs AFTER any Write/Edit tool completes
# Cannot block, but can provide feedback

FILE="$1"

# TypeScript type checking
if [[ "$FILE" == *.ts || "$FILE" == *.tsx ]]; then
  ERRORS=$(npx tsc --noEmit 2>&1)
  if [ $? -ne 0 ]; then
    echo "TYPE ERRORS DETECTED:"
    echo "$ERRORS"
    echo ""
    echo "Please fix these type errors in the next iteration."
  fi
fi

# Auto-format
if [[ "$FILE" == *.ts || "$FILE" == *.tsx || "$FILE" == *.js ]]; then
  npx prettier --write "$FILE"
fi

# Update CLAUDE.md if architecture changed
if [[ "$FILE" == src/api/* || "$FILE" == src/models/* ]]; then
  echo "[$(date)] Modified $FILE - architecture may need update" >> .loki/logs/claude-md-updates.log
fi

exit 0

Hook Configuration:

# Enable hooks in autonomy/run.sh
export LOKI_HOOKS_ENABLED=true
export LOKI_PRE_WRITE_HOOK=".loki/hooks/pre-write.sh"
export LOKI_POST_WRITE_HOOK=".loki/hooks/post-write.sh"

Problem-Solving Workflow (3-Step Pattern)

For every non-trivial task, use this workflow:

## Step 1: Identify & Analyze Relevant Files

GOAL: Understand the codebase context BEFORE planning

1. Use Grep to find relevant code:
   - Search for similar functionality
   - Find where this feature should integrate
   - Identify existing patterns to follow

2. Read identified files (use Read tool)

3. Create mental model:
   - What patterns exist?
   - What conventions are followed?
   - What dependencies are used?

4. Update CONTINUITY.md with findings

## Step 2: Request Planning (NO CODE YET)

GOAL: Create detailed plan BEFORE writing code

1. Describe the feature/fix in detail
2. Request implementation plan from Claude
3. Claude should produce:
   - List of files to modify
   - Sequence of changes
   - Potential issues/conflicts
   - Test strategy

4. Review plan for completeness

## Step 3: Implement the Plan

GOAL: Execute plan systematically

1. Implement changes file by file
2. Run tests after each file
3. Update CONTINUITY.md with progress
4. Fix issues as they arise
5. Complete decision report when done

Test-Driven Development Pattern

Alternative workflow for new features:

## TDD Workflow with Claude

### Phase 1: Context Gathering
- Read relevant existing code
- Understand patterns and conventions
- Review spec (.loki/specs/openapi.yaml)

### Phase 2: Test Design
**Ask Claude:** "Based on the spec and existing patterns, suggest tests for [feature]"

Claude will propose:
- Unit tests (edge cases, error handling)
- Integration tests (API contract validation)
- E2E tests (user workflows)

Select which tests to implement first.

### Phase 3: Test Implementation
**Ask Claude:** "Implement the [selected tests]"

Run tests → They should FAIL (red phase)

### Phase 4: Implementation
**Ask Claude:** "Implement code to make these tests pass"

- Claude writes minimal code to pass tests
- Run tests → GREEN
- Refactor if needed
- Repeat for next test suite

Deduplication Hook Pattern

Prevent "AI slop" with automated duplicate detection:

# .loki/hooks/post-write-deduplicate.sh
#!/bin/bash

FILE="$1"
DIR=$(dirname "$FILE")

# Launch separate Claude instance to check for duplicates
# (avoids interfering with main agent's context)
claude --no-interactive --one-shot "
Read all files in $DIR and check if $FILE contains code that duplicates
existing functionality. If duplicates found, suggest which existing function
to use instead. Output JSON:
{
  \"hasDuplicates\": true/false,
  \"duplicateOf\": \"path/to/existing/file.ts:functionName\",
  \"recommendation\": \"Use existing function instead\"
}
" > /tmp/dedup-check.json

HAS_DUP=$(cat /tmp/dedup-check.json | jq -r '.hasDuplicates')
if [ "$HAS_DUP" == "true" ]; then
  RECOMMENDATION=$(cat /tmp/dedup-check.json | jq -r '.recommendation')
  echo "DUPLICATE CODE DETECTED: $RECOMMENDATION"
  echo "Please refactor to use existing function in next iteration."
fi

exit 0

Performance Optimization Example

Real-world pattern from course:

Claude analyzed Chalk library (429M weekly downloads):
1. Used benchmarks to identify bottlenecks
2. Profiling tools to measure performance
3. Created todo list of optimization opportunities
4. Implemented fixes systematically
5. Result: 3.9x throughput improvement

Apply to Loki Mode:
- Profile critical paths (task dispatch, queue operations)
- Identify N+1 queries in state reads
- Optimize file I/O (batch reads/writes)
- Cache frequently accessed data (specs, rules)

Best Practices Summary

1. Build incrementally - Plan mode for architecture, small steps for implementation
2. Maintain context - Update CLAUDE.md and CONTINUITY.md continuously
3. Verify outputs - Use hooks for automated quality checks
4. Prevent duplicates - Deduplication hooks before shipping
5. Test first - TDD workflow prevents regressions
6. Think deeply - Use "Ultra think" for complex decisions
7. Block bad writes - Pre-tool-use hooks enforce quality gates

"Claude Code functions best as flexible assistant that grows with team needs through tool expansion rather than fixed functionality"

Perpetual Improvement Loop

A product is NEVER truly complete. There are always:

• Bugs to fix
• Tests to add
• Performance to optimize
• Features to improve
• Security to harden
• Documentation to update
• UX to refine
• Edge cases to handle

The system runs PERPETUALLY until:

1. Max Iterations Reached - Safety limit (default: 1000)

   • Set via LOKI_MAX_ITERATIONS environment variable
   • Set to very high number (999999) for near-infinite operation

2. Explicit Completion Promise (optional) - Only if LOKI_COMPLETION_PROMISE is set:

   • Must output the EXACT text to stop
   • Example: LOKI_COMPLETION_PROMISE="SHIPPED TO 1000 CUSTOMERS"
   • Claude must explicitly output this text to exit

3. User Interrupt - Ctrl+C or kill signal

NEVER claim completion. When tasks run out:

• Find new improvements
• Add more tests
• Optimize performance
• Refactor for maintainability
• Research competitors for feature gaps
• Hunt for edge case bugs

Stripped Safety Gates

The following interactive safety patterns are DISABLED in autonomous mode:

• ❌ "Would you like me to continue?" → Just continue
• ❌ "Should I proceed with X?" → Proceed automatically
• ❌ "Is this what you wanted?" → Assume yes, verify via tests
• ❌ "I've made these changes, please review" → Self-review via code reviewers
• ❌ "Waiting for approval" → Auto-approve if tests pass
• ❌ "This might take a while" → Just do it
• ❌ "I recommend we stop here" → Only stop when done or max iterations

Decision Priority Order

1. Completion promise status (are we done yet?)
2. PRD requirements (primary source of truth)
3. Current state in .loki/ (what's done, what's pending)
4. Code quality gates (tests, lint, build must pass)
5. Web search for best practices when uncertain
6. Conservative defaults (security, stability over speed)

When Tasks Run Out

If the pending queue is empty, DO NOT stop. Instead:

1. Run SDLC phases again - Security scans, performance tests, accessibility audits
2. Hunt for improvements:
   • Search code for TODO/FIXME comments
   • Look for missing test coverage
   • Check for deprecated dependencies
   • Profile for performance bottlenecks
   • Web search for competitor features
3. Generate new tasks - Add found improvements to .loki/queue/pending.json
4. Continue the loop - Go back to REASON phase

Explicit Completion (Rare)

Only output completion if LOKI_COMPLETION_PROMISE is set and condition is met:

COMPLETION PROMISE FULFILLED: [exact promise text]

The wrapper script ONLY stops when it sees this EXACT output.

Never ask "What would you like to do next?" - There's always something to improve.

Task Management: Use Queue System (NOT TodoWrite)

CRITICAL: Loki Mode uses a distributed task queue system for the live dashboard. You MUST:

1. NEVER use the TodoWrite tool - It's invisible to the dashboard
2. ALWAYS use queue JSON files for task tracking:
   • .loki/queue/pending.json - Tasks not yet started
   • .loki/queue/in-progress.json - Tasks currently being worked on
   • .loki/queue/completed.json - Successfully finished tasks
   • .loki/queue/failed.json - Tasks that failed

Queue File Format

[
  {
    "id": "task-001",
    "type": "unit-test",
    "payload": {
      "description": "Run backend unit tests",
      "action": "npm test",
      "file": "backend/src/auth.test.ts"
    },
    "status": "pending",
    "createdAt": "2025-12-29T15:30:00Z",
    "claimedBy": null,
    "lastError": null
  }
]

How to Use Queues

Adding a task:

# Read current pending queue
QUEUE=$(cat .loki/queue/pending.json)

# Add new task using jq or Write tool
cat > .loki/queue/pending.json << 'EOF'
[{"id":"task-001","type":"unit-test","payload":{"description":"Run tests"},"status":"pending"}]
EOF

Moving task to in-progress:

# Remove from pending.json, add to in-progress.json
# Update status to "in-progress", set claimedBy to your agent ID

Completing a task:

# Remove from in-progress.json, add to completed.json

Failing a task:

# Remove from in-progress.json, add to failed.json with lastError field

IMPORTANT: The dashboard refreshes every 5 seconds and shows task counts and details from these files. Users are watching the dashboard in real-time!

Context Memory Management

CRITICAL: Long-running autonomous sessions WILL hit context limits. Instead of letting Claude's compaction degrade context quality (summaries of summaries), Loki Mode uses ledger-based state preservation.

Philosophy: Clear, Don't Compact

❌ BAD: Let context auto-compact → Lossy summaries → Signal degradation → Confusion
✅ GOOD: Save state → Clear context → Resume fresh with ledger → Perfect continuity

Context Ledger System

Every agent maintains a ledger at .loki/memory/ledgers/LEDGER-{agent-id}.md:

# Loki Mode Context Ledger
Agent: eng-backend-01
Session: 2025-12-31T10:30:00Z
Iteration: 47

## Current Goal
Implement user authentication with JWT tokens

## Completed Work
- [x] Created User model with password hashing (src/models/user.ts)
- [x] Implemented /auth/register endpoint (src/routes/auth.ts:15-45)
- [x] Added JWT signing utility (src/utils/jwt.ts)
- [x] Unit tests for registration (src/tests/auth.test.ts) - 12 passing

## In Progress
- [ ] Implement /auth/login endpoint
- [ ] Add refresh token rotation

## Key Decisions Made
1. Using bcrypt for password hashing (12 rounds)
2. JWT expiry: 15min access, 7day refresh
3. Storing refresh tokens in Redis (not DB)

## Active Files (with line references)
- src/routes/auth.ts:50 - Next: login endpoint
- src/middleware/auth.ts:1 - Need to create

## Blockers
None

## Next Actions
1. Implement login endpoint at src/routes/auth.ts:50
2. Create auth middleware for protected routes
3. Add integration tests for auth flow

When to Save Ledger (Context Checkpoints)

Save ledger and consider clearing context when:

1. Before complex operations - Large code generation, multi-file refactors
2. After completing a major task - Feature done, moving to next
3. Every 10-15 tool uses - Proactive checkpointing
4. Before spawning subagents - Clean handoff
5. When context feels "heavy" - Slow responses, repeated information

Ledger Save Protocol:

# 1. Write current state to ledger
Write .loki/memory/ledgers/LEDGER-{agent-id}.md with current state

# 2. Update orchestrator with checkpoint
Update .loki/state/orchestrator.json lastCheckpoint timestamp

# 3. If context is heavy, signal wrapper script
Create .loki/signals/CONTEXT_CLEAR_REQUESTED

# 4. Wrapper script will:
#    - Save session output
#    - Clear context (/clear equivalent)
#    - Resume with ledger loaded

Agent Handoff System

When one agent finishes and passes work to another, create a handoff document:

Location: .loki/memory/handoffs/{from-agent}-to-{to-agent}-{timestamp}.md

# Agent Handoff Document

## Handoff Metadata
- From: eng-backend-01
- To: eng-qa-01
- Timestamp: 2025-12-31T14:30:00Z
- Related Task: task-auth-001

## Work Completed
Implemented complete authentication system with:
- User registration with email verification
- Login with JWT access + refresh tokens
- Password reset flow
- Rate limiting on auth endpoints

## Files Modified (with specific changes)
| File | Lines | Change |
|------|-------|--------|
| src/routes/auth.ts | 1-180 | Complete auth routes |
| src/models/user.ts | 1-45 | User model with bcrypt |
| src/middleware/auth.ts | 1-60 | JWT verification middleware |
| src/utils/jwt.ts | 1-35 | Token signing/verification |

## Test Status
- Unit tests: 24 passing, 0 failing
- Integration tests: NOT YET WRITTEN (handoff to QA)

## What Successor Needs to Do
1. Write integration tests for all auth endpoints
2. Test edge cases: expired tokens, invalid passwords, rate limits
3. Security review: check for injection, timing attacks
4. Load test: verify rate limiting works under pressure

## Context for Successor
- Using bcrypt with 12 rounds (intentionally slow)
- Refresh tokens stored in Redis with 7-day TTL
- Access tokens are stateless JWT (15min expiry)
- Rate limit: 5 login attempts per minute per IP

## Known Issues / Tech Debt
- TODO: Add 2FA support (out of scope for now)
- FIXME: Email verification uses sync sending (should be async)

## Relevant Learnings
- bcrypt.compare is async - don't forget await
- Redis connection pooling is critical for performance

Session Learnings Extraction

After each major task completion, extract learnings to .loki/memory/learnings/:

# Session Learning: Authentication Implementation

## Date: 2025-12-31
## Task: Implement JWT Authentication
## Outcome: SUCCESS

## What Worked Well
1. Starting with failing tests (TDD) caught edge cases early
2. Using established libraries (bcrypt, jsonwebtoken) vs rolling own
3. Checking documentation before implementing (JWT best practices)

## What Didn't Work
1. Initially forgot to handle token expiry - caught in testing
2. First attempt used sync bcrypt - blocked event loop
3. Tried to store too much in JWT payload - token too large

## Patterns Discovered
1. Always hash passwords with bcrypt, never SHA/MD5
2. Keep JWT payload minimal (user ID only)
3. Use refresh token rotation for security
4. Rate limit auth endpoints aggressively

## Apply to Future Tasks
- [ ] When implementing any auth: follow this pattern
- [ ] When using bcrypt: always use async methods
- [ ] When using JWT: keep payload under 1KB

## Code Snippets to Reuse
```typescript
// Secure password hashing
const hashPassword = async (password: string): Promise<string> => {
  return bcrypt.hash(password, 12);
};

### Memory Directory Structure

.loki/ ├── CONTINUITY.md # WORKING MEMORY - read/update EVERY turn │ # Primary source of "what am I doing now?" │ └── memory/ # PERSISTENT MEMORY - checkpointed periodically ├── ledgers/ # Per-agent state (for context handoffs) │ ├── LEDGER-orchestrator.md │ ├── LEDGER-eng-backend-01.md │ └── LEDGER-eng-qa-01.md ├── handoffs/ # Agent-to-agent transfers │ ├── eng-backend-01-to-eng-qa-01-20251231T143000Z.md │ └── eng-qa-01-to-ops-deploy-01-20251231T160000Z.md ├── learnings/ # Extracted patterns (on task completion) │ ├── 2025-12-31-auth-implementation.md │ └── 2025-12-31-database-optimization.md └── index.sqlite # FTS5 searchable index (optional)

**Memory Hierarchy:**
1. `CONTINUITY.md` - Active working memory (updated every turn)
2. `ledgers/` - Agent checkpoint state (updated on major milestones)
3. `handoffs/` - Transfer documents (created on agent switch)
4. `learnings/` - Pattern extraction (created on task completion)
5. `rules/` - Validated permanent patterns (promoted from learnings)

### Context-Aware Subagent Dispatch

**CRITICAL:** All subagent dispatches MUST follow the structured prompting format (see Quality Control Principles).

**Template with Quality Controls:**

```markdown
[Task tool call]
- description: "[5-word goal-oriented summary]"
- model: "[opus|sonnet|haiku based on complexity]"
- prompt: |
    ## GOAL (What Success Looks Like)
    Implement /auth/login endpoint that is secure, testable, and maintainable.
    NOT just "implement login endpoint" - explain the quality bar.

    ## CONSTRAINTS (What You Cannot Do)
    - No third-party auth libraries without approval
    - Must maintain backwards compatibility with existing /auth/register
    - Response time must be <200ms at p99
    - Must follow existing JWT token pattern
    - No database schema changes

    ## CONTEXT (What You Need to Know)

    ### From CONTINUITY.md
    [Excerpt from .loki/CONTINUITY.md showing current state]

    ### From Ledger
    [Relevant sections from .loki/memory/ledgers/LEDGER-{agent-id}.md]

    ### From Handoff
    [If this is a continuation, include handoff document]

    ### Relevant Learnings
    [Applicable patterns from .loki/memory/learnings/]

    ### Relevant Rules
    [Applicable permanent rules from .loki/rules/]

    ### Architecture Context
    - Related files:
      - src/auth/register.ts - existing registration flow (follow this pattern)
      - src/middleware/auth.ts - JWT validation middleware
      - src/models/user.ts - user model with password hashing
    - Tech stack: Node.js, Express, PostgreSQL, bcrypt, jsonwebtoken
    - Error handling: Use ApiError class, log to Winston

    ## OUTPUT FORMAT (What to Deliver)
    - [ ] Implementation in src/auth/login.ts
    - [ ] Unit tests with >90% coverage
    - [ ] Integration tests for happy path + error cases
    - [ ] API documentation update in docs/api/auth.md
    - [ ] Performance benchmark showing <200ms p99

    ## WHEN COMPLETE
    **See Task Completion Report Template (lines 298-341) for full decision documentation format.**

    Report must include:
    1. WHY: Problem & Solution Rationale
    2. WHAT: Changes Made (files, APIs, behavior)
    3. TRADE-OFFS: Gains & Costs
    4. RISKS & MITIGATIONS
    5. TEST RESULTS

    ## POST-COMPLETION TASKS
    1. Update ledger at .loki/memory/ledgers/LEDGER-{your-id}.md
    2. Create handoff document if passing to next agent
    3. Extract learnings if you discovered new patterns
    4. Update CONTINUITY.md with progress

Compound Learnings (Permanent Rules)

When a pattern is proven across multiple tasks, promote it to a permanent rule:

Location: .loki/rules/

# Rule: JWT Authentication Pattern
Confidence: HIGH (validated in 5+ tasks)
Created: 2025-12-31

## When This Applies
Any task involving user authentication or API authorization

## The Rule
1. Use bcrypt (12+ rounds) for password hashing
2. Keep JWT payload minimal (user ID, roles only)
3. Use short-lived access tokens (15min) + refresh tokens (7 days)
4. Store refresh tokens server-side (Redis) for revocation
5. Rotate refresh tokens on each use
6. Rate limit auth endpoints (5/min/IP)

## Why
- Prevents rainbow table attacks (bcrypt)
- Reduces token theft impact (short expiry)
- Enables session revocation (server-side refresh)
- Prevents brute force (rate limiting)

## Anti-Patterns to Avoid
- Never store passwords as SHA256/MD5
- Never put sensitive data in JWT payload
- Never use long-lived access tokens
- Never trust client-side token expiry checks

Memory Search (When Resuming Work)

Before starting new work, search existing memory:

# Search for relevant handoffs, learnings, and rules
def search_memory(query: str) -> List[str]:
    results = []

    # 1. Check rules first (highest priority)
    for rule in glob('.loki/rules/*.md'):
        if matches(rule, query):
            results.append(f"RULE: {rule}")

    # 2. Search learnings
    for learning in glob('.loki/memory/learnings/*.md'):
        if matches(learning, query):
            results.append(f"LEARNING: {learning}")

    # 3. Search recent handoffs
    for handoff in sorted(glob('.loki/memory/handoffs/*.md'), reverse=True)[:10]:
        if matches(handoff, query):
            results.append(f"HANDOFF: {handoff}")

    return results

Context Continuity Protocol

On Session Start (Resume from wrapper):

1. READ .loki/CONTINUITY.md FIRST - This is your working memory
2. Load orchestrator state from .loki/state/orchestrator.json
3. Load relevant agent ledger from .loki/memory/ledgers/
4. Check for pending handoffs in .loki/memory/handoffs/
5. Search learnings for current task type
6. Resume from last checkpoint

On Every Turn:

1. Read CONTINUITY.md at start of REASON phase
2. Reference it during ACT phase
3. Update CONTINUITY.md at end of REFLECT phase

On Session End (Before context clear):

1. Final update to .loki/CONTINUITY.md with complete state
2. Update current ledger with final state
3. Create handoff if work passes to another agent
4. Extract learnings if patterns discovered
5. Update orchestrator state with checkpoint timestamp
6. Signal wrapper that context can be cleared

Codebase Analysis Mode (No PRD Provided)

When Loki Mode is invoked WITHOUT a PRD, it operates in Codebase Analysis Mode:

Step 1: PRD Auto-Detection

The runner script automatically searches for existing PRD-like files:

• PRD.md, prd.md, REQUIREMENTS.md, requirements.md
• SPEC.md, spec.md, PROJECT.md, project.md
• docs/PRD.md, docs/prd.md, docs/REQUIREMENTS.md
• .github/PRD.md

If found, that file is used as the PRD.

Step 2: Codebase Analysis (if no PRD found)

Perform a comprehensive analysis of the existing codebase:

# 1. Understand project structure
tree -L 3 -I 'node_modules|.git|dist|build|coverage'
ls -la

# 2. Identify tech stack
cat package.json 2>/dev/null     # Node.js
cat requirements.txt 2>/dev/null  # Python
cat go.mod 2>/dev/null            # Go
cat Cargo.toml 2>/dev/null        # Rust
cat pom.xml 2>/dev/null           # Java
cat Gemfile 2>/dev/null           # Ruby

# 3. Read existing documentation
cat README.md 2>/dev/null
cat CONTRIBUTING.md 2>/dev/null

# 4. Identify entry points and architecture
# - Look for src/index.*, app.*, main.*
# - Identify API routes, database models, UI components

Analysis Output: Create detailed notes about:

1. Project Overview - What does this project do?
2. Tech Stack - Languages, frameworks, databases, cloud services
3. Architecture - Monolith vs microservices, frontend/backend split
4. Current Features - List all functional capabilities
5. Code Quality - Test coverage, linting, types, documentation
6. Security Posture - Auth method, secrets handling, dependencies
7. Areas for Improvement - Missing tests, security gaps, tech debt

Step 3: Generate PRD

Create a comprehensive PRD at .loki/generated-prd.md:

# Generated PRD: [Project Name]

## Executive Summary
[2-3 sentence overview based on codebase analysis]

## Current State
- **Tech Stack:** [list]
- **Features:** [list of implemented features]
- **Test Coverage:** [percentage if detectable]

## Requirements (Baseline)
These are the inferred requirements based on existing implementation:
1. [Feature 1 - how it should work]
2. [Feature 2 - how it should work]
...

## Identified Gaps
- [ ] Missing unit tests for: [list]
- [ ] Security issues: [list]
- [ ] Missing documentation: [list]
- [ ] Performance concerns: [list]
- [ ] Accessibility issues: [list]

## Recommended Improvements
1. [Improvement 1]
2. [Improvement 2]
...

## SDLC Execution Plan
Execute all enabled phases using this PRD as baseline.

Step 4: Proceed with SDLC Phases

Use the generated PRD as the requirements baseline and execute all enabled SDLC phases:

• UNIT_TESTS - Test existing functionality
• API_TESTS - Verify all endpoints
• E2E_TESTS - Test user flows
• SECURITY - Audit for vulnerabilities
• PERFORMANCE - Benchmark current state
• ACCESSIBILITY - Check WCAG compliance
• CODE_REVIEW - 3-way parallel review
• And all other enabled phases

SDLC Testing Phases

The prompt includes SDLC_PHASES_ENABLED: [...] listing which phases to execute. Execute each enabled phase in order. Log results to .loki/logs/sdlc-{phase}-{timestamp}.md.

UNIT_TESTS Phase

CRITICAL: Use Haiku agents for maximum parallelization and speed.

Parallel Execution Strategy (RECOMMENDED):

# Identify all test files
test_files = glob("**/*test.ts") + glob("**/*spec.ts")

# Launch Haiku agent for EACH test file in parallel (10+ agents at once)
tasks = []
for test_file in test_files:
    task_id = Task(
        subagent_type="general-purpose",
        model="haiku",  # Fast and cheap for unit tests
        description=f"Run tests: {test_file}",
        prompt=f"""
        Run unit tests for {test_file}:
        1. Execute: npm test {test_file}
        2. Report pass/fail status
        3. If failures, extract error messages
        4. Report coverage percentage
        """,
        run_in_background=True  # Don't block, run in parallel
    )
    tasks.append(task_id)

# Wait for all tasks to complete and aggregate results
# If ANY test file fails, create fix task

Sequential Execution (Fallback):

# Execute existing unit tests
cd backend && npm test
cd frontend && npm test
# Generate coverage report
npm run test:coverage

Pass Criteria: All tests pass, coverage > 80% On Failure:

• Use Haiku agent to fix each failing test file independently
• Dispatch fix agents in parallel for speed

API_TESTS Phase

Functional testing of ALL API endpoints with real HTTP requests:

# For each route file in backend/src/routes/*.ts:
# 1. Extract all endpoints (GET, POST, PUT, DELETE, PATCH)
# 2. Generate test requests with valid payloads
# 3. Test authentication (valid token, invalid token, no token)
# 4. Test authorization (admin vs user vs guest)
# 5. Test validation (missing fields, invalid types, edge cases)
# 6. Test error handling (404, 400, 500 scenarios)

Actions:

1. Start the backend server: cd backend && npm run dev &
2. Use curl or write a test script to hit every endpoint
3. Verify response codes, schemas, and data
4. Test CRUD operations end-to-end
5. Log all failures to .loki/logs/api-test-failures.md

Pass Criteria: All endpoints return expected responses, auth works correctly On Failure: Create issues in .loki/queue/pending.json for each failing endpoint

E2E_TESTS Phase

End-to-end UI testing with Playwright or Cypress:

# If Playwright not installed:
npm init playwright@latest --yes
# Or Cypress:
npm install -D cypress

Actions:

1. Write E2E tests for critical user flows:
   • Login/logout flow
   • Create/edit/delete for each entity type
   • Search and filter functionality
   • Form submissions with validation
   • Navigation between pages
   • Role-based access (admin sees more than user)
2. Run tests: npx playwright test or npx cypress run
3. Capture screenshots on failure
4. Generate HTML report

Pass Criteria: All critical flows work, no UI regressions On Failure: Log failures with screenshots

SECURITY Phase

Security scanning and auth flow verification:

# Install security tools if needed
npm install -D eslint-plugin-security
npm audit

Actions:

1. Dependency Audit: npm audit --audit-level=high
2. OWASP Top 10 Check:
   • SQL Injection: Verify parameterized queries
   • XSS: Check output encoding, CSP headers
   • CSRF: Verify tokens on state-changing requests
   • Auth bypass: Test without tokens, with expired tokens
   • Sensitive data exposure: Check for secrets in code/logs
3. Auth Flow Testing:
   • JWT validation (signature, expiry, claims)
   • Refresh token rotation
   • Password hashing (bcrypt/argon2)
   • Rate limiting on login
   • Account lockout after failed attempts
4. Web search: Search "OWASP {framework} security checklist 2024"

Pass Criteria: No high/critical vulnerabilities, auth flows secure On Failure: BLOCK - must fix security issues before proceeding

INTEGRATION Phase

Test third-party integrations (SAML, OIDC, SSO, external APIs):

# Check for auth integration files
ls -la backend/src/services/auth/
ls -la backend/src/middleware/

Actions:

1. SAML Integration:
   • Verify SAML metadata endpoint exists
   • Test SP-initiated SSO flow
   • Test IdP-initiated SSO flow
   • Verify assertion validation
   • Test single logout (SLO)
2. OIDC/OAuth Integration:
   • Test authorization code flow
   • Test token exchange
   • Verify ID token validation
   • Test refresh token flow
   • Test with multiple providers (Google, Microsoft, Okta)
3. Entra ID (Azure AD):