Skip to content

davila7/claude-code-templates / cli-tool/components/skills/ai-research/loki-mode

loki-mode

Flagged

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.

FileKindSize
.github/workflows/claude-code-review.ymlconfig1.9 KB
.github/workflows/claude.ymlconfig1.8 KB
.github/workflows/release.ymlconfig4.8 KB
.gitignoreother10 B
ACKNOWLEDGEMENTS.mdmarkdown11.8 KB
CHANGELOG.mdmarkdown83.9 KB
CLAUDE.mdmarkdown4.3 KB
CONTEXT-EXPORT.mdmarkdown6.5 KB
INSTALLATION.mdmarkdown9.1 KB
LICENSEother1.1 KB
README.mdmarkdown18.2 KB
SKILL.mdskill md27.9 KB
VERSIONother7 B
autonomy/.loki/dashboard/index.htmlother15.2 KB
autonomy/CONSTITUTION.mdmarkdown10.2 KB
autonomy/README.mdmarkdown7.5 KB
autonomy/run.shexecutablescript74.4 KB
benchmarks/datasets/humaneval.jsonlother209.4 KB
benchmarks/datasets/swebench-lite.jsonconfig321 B
benchmarks/prepare-submission.shexecutablescript6.6 KB
benchmarks/results/2026-01-05-00-23-56/SUMMARY.mdmarkdown1.2 KB
benchmarks/results/2026-01-05-00-23-56/humaneval-results.jsonconfig365 B
benchmarks/results/2026-01-05-00-23-56/swebench-results.jsonconfig383 B
benchmarks/results/2026-01-05-00-49-17/SUMMARY.mdmarkdown1.2 KB
benchmarks/results/2026-01-05-00-49-17/humaneval-results.jsonconfig33.6 KB
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/0.pyscript528 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/1.pyscript936 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/10.pyscript758 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/100.pyscript598 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/101.pyscript537 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/102.pyscript436 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/103.pyscript519 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/104.pyscript602 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/105.pyscript1.1 KB
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/106.pyscript749 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/107.pyscript938 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/108.pyscript720 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/109.pyscript1.6 KB
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/11.pyscript443 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/110.pyscript882 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/111.pyscript859 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/112.pyscript732 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/113.pyscript853 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/114.pyscript447 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/115.pyscript1.2 KB
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/116.pyscript521 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/117.pyscript995 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/118.pyscript835 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/119.pyscript1002 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/12.pyscript564 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/120.pyscript706 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/121.pyscript339 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/122.pyscript494 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/123.pyscript1.1 KB
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/124.pyscript1.6 KB
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/125.pyscript757 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/126.pyscript943 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/127.pyscript1.5 KB
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/128.pyscript653 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/129.pyscript2.2 KB
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/13.pyscript264 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/130.pyscript940 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/131.pyscript417 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/132.pyscript1.0 KB
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/133.pyscript524 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/134.pyscript779 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/135.pyscript481 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/136.pyscript667 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/137.pyscript751 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/138.pyscript295 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/139.pyscript455 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/14.pyscript263 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/140.pyscript989 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/141.pyscript1.4 KB
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/142.pyscript822 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/143.pyscript1.0 KB
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/144.pyscript780 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/145.pyscript702 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/146.pyscript700 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/147.pyscript734 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/148.pyscript1.1 KB
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/149.pyscript880 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/15.pyscript266 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/150.pyscript371 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/151.pyscript647 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/152.pyscript845 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/153.pyscript1.4 KB
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/154.pyscript567 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/155.pyscript427 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/156.pyscript750 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/157.pyscript463 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/158.pyscript524 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/159.pyscript1.1 KB
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/16.pyscript295 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/160.pyscript968 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/161.pyscript637 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/162.pyscript337 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/163.pyscript425 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/17.pyscript736 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/18.pyscript548 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/19.pyscript714 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/2.pyscript360 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/20.pyscript835 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/21.pyscript493 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/22.pyscript349 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/23.pyscript153 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/24.pyscript260 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/25.pyscript689 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/26.pyscript406 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/27.pyscript205 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/28.pyscript240 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/29.pyscript367 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/3.pyscript590 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/30.pyscript262 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/31.pyscript525 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/32.pyscript1.5 KB
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/33.pyscript710 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/34.pyscript172 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/35.pyscript200 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/36.pyscript357 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/37.pyscript481 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/38.pyscript567 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/39.pyscript762 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/4.pyscript530 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/40.pyscript684 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/41.pyscript661 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/42.pyscript239 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/43.pyscript582 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/44.pyscript441 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/45.pyscript158 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/46.pyscript620 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/47.pyscript342 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/48.pyscript271 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/49.pyscript245 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/5.pyscript466 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/50.pyscript412 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/51.pyscript469 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/52.pyscript255 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/53.pyscript129 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/54.pyscript458 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/55.pyscript302 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/56.pyscript559 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/57.pyscript458 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/58.pyscript268 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/59.pyscript477 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/6.pyscript832 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/60.pyscript259 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/61.pyscript559 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/62.pyscript333 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/63.pyscript624 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/64.pyscript560 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/65.pyscript433 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/66.pyscript410 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/67.pyscript876 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/68.pyscript1.5 KB
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/69.pyscript709 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/7.pyscript379 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/70.pyscript693 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/71.pyscript589 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/72.pyscript837 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/73.pyscript612 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/74.pyscript779 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/75.pyscript846 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/76.pyscript571 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/77.pyscript467 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/78.pyscript1.1 KB
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/79.pyscript600 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/8.pyscript527 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/80.pyscript563 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/81.pyscript1.9 KB
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/82.pyscript580 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/83.pyscript855 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/84.pyscript556 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/85.pyscript288 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/86.pyscript660 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/87.pyscript1.1 KB
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/88.pyscript784 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/89.pyscript847 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/9.pyscript506 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/90.pyscript531 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/91.pyscript601 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/92.pyscript586 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/93.pyscript974 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/94.pyscript1.1 KB
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/95.pyscript1003 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/96.pyscript804 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/97.pyscript421 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/98.pyscript396 B
benchmarks/results/2026-01-05-00-49-17/humaneval-solutions/99.pyscript886 B
benchmarks/results/2026-01-05-01-24-17/SUMMARY.mdmarkdown1.3 KB
benchmarks/results/2026-01-05-01-24-17/swebench-patches/astropy__astropy-12907.patchother1.0 KB
benchmarks/results/2026-01-05-01-24-17/swebench-patches/astropy__astropy-14182.patchother2.3 KB
benchmarks/results/2026-01-05-01-24-17/swebench-patches/astropy__astropy-14365.patchother1.3 KB
benchmarks/results/2026-01-05-01-24-17/swebench-patches/astropy__astropy-14995.patchother1.1 KB
benchmarks/results/2026-01-05-01-24-17/swebench-patches/astropy__astropy-6938.patchother997 B
benchmarks/results/2026-01-05-01-24-17/swebench-patches/astropy__astropy-7746.patchother1.6 KB
benchmarks/results/2026-01-05-01-24-17/swebench-patches/django__django-10914.patchother3.3 KB
benchmarks/results/2026-01-05-01-24-17/swebench-patches/django__django-10924.patchother1.9 KB
benchmarks/results/2026-01-05-01-24-17/swebench-patches/django__django-11001.patchother4.3 KB
benchmarks/results/2026-01-05-01-24-17/swebench-patches/django__django-11019.patchother20.2 KB

autonomy/CONSTITUTION.md

View on GitHub
# Loki Mode Agent Constitution

> **Machine-Enforceable Behavioral Contract for All Agents**
> Version 1.0.0 | Immutable Principles | Context-Preserved Lineage

---

## Core Principles (Inviolable)

### 1. Specification-First Development
**RULE:** No code shall be written before the specification exists.

**Enforcement:**
```
IF task.type == "implementation" AND !exists(spec_file):
    BLOCK with error: "SPEC_MISSING"
    REQUIRE: Create OpenAPI spec first
```

**Rationale:** Specs are contracts. Code is implementation. Contract before implementation.

### 2. Git Checkpoint System
**RULE:** Every completed task MUST create a git checkpoint.

**Enforcement:**
```
ON task.status == "completed":
    git add <modified_files>
    git commit -m "[Loki] Task ${task.id}: ${task.title}"
    UPDATE CONTINUITY.md with commit SHA
```

**Rationale:** Git history is proof of progress. Every task is a save point.

### 3. Context Preservation
**RULE:** All agents MUST inherit and preserve context from their spawning agent.

**Enforcement:**
```
ON agent.spawn():
    agent.context.parent_id = spawner.agent_id
    agent.context.lineage = [...spawner.lineage, spawner.agent_id]
    agent.context.inherited_memory = spawner.memory.export()
    WRITE .agent/sub-agents/${agent.agent_id}.json
```

**Rationale:** Context drift kills multi-agent systems. Lineage is truth.

### 4. Iterative Specification Questions
**RULE:** During spec generation, agents MUST ask clarifying questions before assuming.

**Enforcement:**
```
WHILE generating_spec:
    IF ambiguity_detected OR assumption_required:
        questions = generate_clarifying_questions()
        IF orchestrator_mode:
            answers = infer_from_prd()
        ELSE:
            answers = ask_user(questions)
        UPDATE spec WITH answers
```

**Rationale:** Assumptions create bugs. Questions create clarity.

### 5. Machine-Readable Rules
**RULE:** All behavioral rules MUST be represented as structured artifacts, not just prose.

**Enforcement:**
```
rules/
├── pre-commit.schema.json     # Validation rules
├── quality-gates.yaml         # Quality thresholds
├── agent-contracts.json       # Agent responsibilities
└── invariants.ts              # Runtime assertions
```

**Rationale:** Humans read markdown. Machines enforce JSON/YAML.

---

## Agent Behavioral Contracts

### Orchestrator Agent
**Responsibilities:**
- Initialize .loki/ directory structure
- Maintain CONTINUITY.md (working memory)
- Coordinate task queue (pending → in-progress → completed)
- Enforce quality gates
- Manage git checkpoints

**Prohibited Actions:**
- Writing implementation code directly
- Skipping spec generation
- Modifying completed tasks without explicit override

**Context Obligations:**
- MUST read CONTINUITY.md before every action
- MUST update orchestrator.json after phase transitions
- MUST preserve task lineage in completed.json

### Engineering Swarm Agents
**Responsibilities:**
- Implement features per OpenAPI spec
- Write contract tests before implementation
- Create git commits for completed tasks
- Ask clarifying questions when spec is ambiguous

**Prohibited Actions:**
- Implementing without spec
- Skipping tests
- Ignoring linter/type errors

**Context Obligations:**
- MUST inherit parent agent's context
- MUST log all decisions to .agent/sub-agents/${agent_id}.md
- MUST reference spec in all implementation commits

### QA Swarm Agents
**Responsibilities:**
- Generate test cases from OpenAPI spec
- Run contract validation tests
- Report discrepancies between code and spec
- Create bug reports in dead-letter queue

**Prohibited Actions:**
- Modifying implementation code
- Skipping failing tests
- Approving incomplete features

**Context Obligations:**
- MUST validate against spec as source of truth
- MUST log test results to ledgers/
- MUST create git commits for test additions

### DevOps Swarm Agents
**Responsibilities:**
- Automate deployment pipelines
- Monitor service health
- Configure infrastructure as code
- Manage environment secrets

**Prohibited Actions:**
- Storing secrets in plaintext
- Deploying without health checks
- Skipping rollback procedures

**Context Obligations:**
- MUST log all deployments to deployment ledger
- MUST preserve deployment context for rollback
- MUST track infrastructure state in orchestrator.json

---

## Quality Gates (Machine-Enforceable)

### Pre-Commit Hook (BLOCKING)
```yaml
quality_gates:
  linting:
    enabled: true
    auto_fix: true
    block_on_failure: true

  type_checking:
    enabled: true
    strict_mode: true
    block_on_failure: true

  contract_tests:
    enabled: true
    min_coverage: 80%
    block_on_failure: true

  spec_validation:
    enabled: true
    validator: spectral
    block_on_failure: true
```

### Post-Implementation Review (AUTO-FIX)
```yaml
auto_review:
  static_analysis:
    tools: [eslint, prettier, tsc]
    auto_fix: true

  security_scan:
    tools: [semgrep, snyk]
    severity_threshold: medium
    auto_create_issues: true

  performance_check:
    lighthouse_score: 90
    bundle_size_limit: 500kb
    warn_only: true
```

---

## Memory Hierarchy (Priority Order)

### 1. CONTINUITY.md (Volatile - Every Turn)
**Purpose:** What am I doing RIGHT NOW?
**Update Frequency:** Every turn
**Content:** Current task, phase, blockers, next steps

### 2. CONSTITUTION.md (Immutable - This File)
**Purpose:** How MUST I behave?
**Update Frequency:** Version bumps only
**Content:** Behavioral contracts, quality gates, invariants

### 3. CLAUDE.md (Semi-Stable - Significant Changes)
**Purpose:** What is this project?
**Update Frequency:** Architecture changes
**Content:** Tech stack, patterns, project context

### 4. Ledgers (Append-Only - Checkpoint)
**Purpose:** What happened?
**Update Frequency:** After significant events
**Content:** Decisions, deployments, reviews

### 5. .agent/sub-agents/*.json (Lineage Tracking)
**Purpose:** Who did what and why?
**Update Frequency:** Agent lifecycle events
**Content:** Agent context, decisions, inherited memory

---

## Context Lineage Schema

```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"]
  },
  "decisions_made": [
    {
      "timestamp": "2026-01-04T05:31:15Z",
      "question": "Should we use Prisma or raw SQL?",
      "answer": "Raw SQL with better-sqlite3 for simplicity",
      "rationale": "PRD requires minimal dependencies, synchronous ops preferred"
    }
  ],
  "tasks_completed": ["task-005"],
  "commits_created": ["abc123f", "def456a"],
  "status": "completed",
  "completed_at": "2026-01-04T05:45:00Z"
}
```

---

## Git Checkpoint Protocol

### Commit Message Format
```
[Loki] ${agent_type}-${task_id}: ${task_title}

${detailed_description}

Agent: ${agent_id}
Parent: ${parent_agent_id}
Spec: ${spec_reference}
Tests: ${test_files}
```

### 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
```

---

## Invariants (Runtime Assertions)

```typescript
// .loki/rules/invariants.ts

export const INVARIANTS = {
  // Spec must exist before implementation
  SPEC_BEFORE_CODE: (task: Task) => {
    if (task.type === 'implementation') {
      assert(exists(task.spec_reference), 'SPEC_MISSING');
    }
  },

  // All tasks must have git commits
  TASK_HAS_COMMIT: (task: Task) => {
    if (task.status === 'completed') {
      assert(task.git_commit_sha, 'COMMIT_MISSING');
    }
  },

  // Agent lineage must be preserved
  AGENT_HAS_LINEAGE: (agent: Agent) => {
    assert(agent.lineage.length > 0, 'LINEAGE_MISSING');
    assert(agent.spawned_by, 'PARENT_MISSING');
  },

  // CONTINUITY.md must always exist
  CONTINUITY_EXISTS: () => {
    assert(exists('.loki/CONTINUITY.md'), 'CONTINUITY_MISSING');
  },

  // Quality gates must pass before merge
  QUALITY_GATES_PASSED: (task: Task) => {
    if (task.status === 'completed') {
      assert(task.quality_checks.all_passed, 'QUALITY_GATE_FAILED');
    }
  }
};
```

---

## Visual Specification Aids

### Mermaid Diagram Generation (Required for Complex Features)

**RULE:** Architecture decisions and complex workflows MUST include Mermaid diagrams.

**Example - Authentication Flow:**
```mermaid
sequenceDiagram
    participant C as Client
    participant A as API
    participant D as Database

    C->>A: POST /api/auth/login
    A->>A: Validate credentials
    A->>D: Query user
    D-->>A: User record
    A->>A: Generate JWT token
    A-->>C: 200 OK {token}
```

**Storage Location:** `.loki/diagrams/${feature_name}.mmd`

**When Required:**
- Multi-step workflows (3+ steps)
- System architecture changes
- Complex state machines
- Integration points between services

---

## Amendment Process

This constitution can only be amended through:
1. Version bump in header
2. Git commit with `[CONSTITUTION]` prefix
3. Changelog entry documenting what changed and why
4. Re-validation of all existing agents against new rules

**Example Amendment Commit:**
```
[CONSTITUTION] v1.1.0: Add visual specification requirement

Added requirement for Mermaid diagrams on complex features to prevent
ambiguity in multi-step workflows. Based on Addy Osmani's insight that
visual aids significantly improve AI-to-AI communication.

Breaking changes: None
New rules: Section "Visual Specification Aids"
```

---

## Enforcement

All rules in this constitution are **machine-enforceable** and **MUST** be implemented as:
1. Pre-commit hooks (Git)
2. Runtime assertions (TypeScript invariants)
3. Quality gate validators (YAML configs)
4. Agent behavior validators (JSON schemas)

**Human guidance is advisory. Machine enforcement is mandatory.**

---

*"In autonomous systems, trust is built on invariants, not intentions."*
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall