loki-mode 6.0.0 → 6.2.0

package/docs/architecture/bmad-integration-review.md

@@ -0,0 +1,86 @@
+# BMAD Integration Adversarial Review
+
+**Date:** 2026-02-25
+**Methodology:** BMAD-style adversarial review (zero findings = failure, re-analyze)
+**Reviewers:** 3 blind Opus agents + Devil's Advocate pass
+
+## Review Process
+
+Three independent reviewers analyzed the full BMAD integration diff across 5 files.
+Combined: 48 unique findings (2 CRITICAL, 12 HIGH, 21 MEDIUM, 13 LOW).
+
+After triage: 1 CRITICAL and 5 HIGH findings were fixed before this report.
+
+## Findings Fixed (Pre-Merge)
+
+| # | Severity | File | Issue | Fix Applied |
+|---|----------|------|-------|-------------|
+| 1 | CRITICAL | bmad-adapter.py:136-140 | Path traversal via config.json outputDir | Added resolve() + project root boundary check |
+| 2 | HIGH | bmad-adapter.py:266,294,419 | Missing errors="replace" on read_text | Replaced all read_text with _safe_read() helper (size limit + encoding safety) |
+| 3 | HIGH | bmad-adapter.py:576-607 | Non-atomic file writes | Added _write_atomic() using tempfile + os.replace pattern |
+| 4 | HIGH | run.sh:7042-7050 | Unbounded BMAD content in prompt | Added head -c size limits (16K arch, 32K tasks, 8K validation) |
+| 5 | HIGH | run.sh:7066-7074 | BMAD context before human_directive in prompt | Moved bmad_context after human_directive and queue_tasks |
+| 6 | HIGH | test-bmad-integration.sh:37,126,163,248 | Trap quoting + inline Python injection | Fixed trap quoting, replaced open('$var') with sys.argv[1] |
+
+## Findings Accepted (Known Limitations)
+
+| # | Severity | Issue | Rationale for Accepting |
+|---|----------|-------|------------------------|
+| 1 | MEDIUM | Regex YAML parser does not handle block-style lists | BMAD fixtures use flow-style. Block-style support is a future enhancement. Documented in code. |
+| 2 | MEDIUM | populate_bmad_queue() has no standalone test | Function tested indirectly through full integration. Standalone test is a future improvement. |
+| 3 | MEDIUM | prd-analyzer scope estimation includes architecture lines | Conservative choice -- slightly inflated feature count is better than missing features. |
+| 4 | MEDIUM | BMAD_PROJECT_PATH exported but unused by run.sh | Intentionally kept for future provider scripts. Added comment. |
+| 5 | LOW | Error messages show full filesystem paths | Acceptable for CLI tool aimed at developers. Not a production web service. |
+| 6 | LOW | mkdir uses default umask | Standard Python behavior, consistent with rest of codebase. |
+
+## Adversarial Scenarios Tested
+
+### What happens when BMAD output format changes in V7?
+
+The adapter uses loose pattern matching (regex on headings, not exact schema validation).
+Section headings like "## Functional Requirements" and "FR1:" patterns are generic enough
+to survive minor format changes. The frontmatter parser handles unknown keys gracefully.
+**Risk: LOW.** The adapter degrades gracefully -- fewer dimensions matched means lower
+score, not a crash.
+
+### What happens with malformed BMAD artifacts?
+
+Tested with incomplete fixture (partial workflow state). Adapter:
+- Reports workflow completion percentage
+- Warns about missing artifacts
+- Processes what exists without crashing
+- Uses errors="replace" for encoding safety
+- Has 10MB file size limit
+
+**Risk: LOW.** Graceful degradation verified.
+
+### What happens when _bmad-output/ contains partial workflow state?
+
+Tested with `stepsCompleted: [init, discovery, vision]` (30% complete).
+Adapter reports completion percentage and warns. Does not block processing.
+**Risk: LOW.** User gets informed about incomplete state.
+
+### What happens if someone passes --bmad-project to a non-BMAD project?
+
+Clear error message and non-zero exit code:
+```
+ERROR: BMAD output directory not found: _bmad-output/planning-artifacts
+This does not appear to be a BMAD project.
+```
+**Risk: NONE.** Clean failure.
+
+### What about backward compatibility for non-BMAD projects?
+
+All BMAD code paths are guarded:
+- CLI: only activated by explicit --bmad-project flag
+- run.sh: checks for .loki/bmad-metadata.json existence
+- prd-analyzer.py: new patterns only ADD to existing ones, never replace
+
+Freeform PRD test confirms identical scoring (5.0/10) before and after changes.
+**Risk: NONE.** Verified by test.
+
+## Recommendation
+
+**PASS.** All CRITICAL and HIGH findings fixed. Remaining MEDIUM/LOW findings are
+acceptable known limitations with documented rationale. Backward compatibility verified.
+Integration is clean, additive, and well-guarded.

package/docs/architecture/bmad-integration-validation.md

@@ -0,0 +1,249 @@
+# BMAD Integration Validation Report
+
+**Date:** 2026-02-25
+**Validator:** Automated analysis against Loki Mode v6.0.0 codebase
+**BMAD Version:** Latest main (cloned 2026-02-25)
+
+## Decision: GO (Phase 0 / Epic 1 only)
+
+Phase 0 (BMAD Artifact Pipeline) is low-risk, additive, and achievable with the current
+codebase. Phases 1-2 are deferred pending P0 value validation.
+
+---
+
+## 1. Compatibility Matrix
+
+| Integration Point | Status | Notes |
+|---|---|---|
+| PRD format parsing | Compatible (minor gaps) | 7/9 analyzer dimensions match BMAD headings directly |
+| Artifact chain discovery | New capability needed | Adapter must find `_bmad-output/planning-artifacts/` |
+| Agent personas | Complementary | BMAD pre-dev agents + Loki execution agents = full coverage |
+| Voice capabilities | Insufficient for P2 | voice.sh only does 4-section dictation, not structured dialogue |
+| Context budget | Safe | ~8-15K tokens per iteration (step files load one-at-a-time) |
+| License | MIT -- fully compatible | No restrictions on integration or redistribution |
+| Event bus integration | Ready | `.loki/events/pending/` accepts BMAD artifact events |
+| Memory system | Ready | BMAD artifacts can be stored as episodic memory |
+| CLI integration | Straightforward | `--bmad-project` flag pattern matches existing CLI architecture |
+| Dashboard | Deferred (P1) | Would need new "Elicitation" panel |
+
+## 2. PRD Format Gap Analysis
+
+### BMAD PRD Section Headings vs Loki Analyzer Dimensions
+
+| BMAD PRD Section | Loki Dimension | Match Type |
+|---|---|---|
+| `## Executive Summary` | -- | NO MATCH (no heading pattern covers "executive summary") |
+| `## Project Classification` | -- | NO MATCH |
+| `## Success Criteria` | `acceptance_criteria` | PARTIAL (heading pattern matches "criteria" keyword) |
+| `## Product Scope` | `feature_list` | MATCH (heading pattern matches "scope") |
+| `## User Journeys` | `user_stories` | MATCH (heading pattern matches "user.*journey") |
+| `## Domain-Specific Requirements` | -- | NO MATCH |
+| `## Innovation & Novel Patterns` | -- | NO MATCH |
+| `## [ProjectType] Specific Requirements` | `feature_list` | PARTIAL (matches "requirement") |
+| `## Project Scoping & Phased Development` | `feature_list` | PARTIAL (matches "scope") |
+| `## Functional Requirements` | `feature_list` | MATCH (matches "functional" and "requirement") |
+| `## Non-Functional Requirements` | Multiple | MATCH (content patterns for security, deployment, error handling) |
+
+### Content Pattern Matches
+
+| BMAD Content Pattern | Loki Content Pattern | Match? |
+|---|---|---|
+| `FR{N}: [Actor] can [capability]` | `user can/should/will` in `user_stories` | YES |
+| `Given/When/Then` (in epics) | `given.*when.*then` in `acceptance_criteria` | YES |
+| `As a {role}, I want {action}` (stories) | `as a \w+` in `user_stories` | YES |
+| Tech stack mentions in architecture.md | Tech keyword patterns in `tech_stack` | YES |
+| `### Performance`, `### Security` (NFRs) | Security/deployment heading patterns | YES |
+
+### Gaps Requiring Adapter Work
+
+1. **Executive Summary** -- BMAD's most prominent section has no matching Loki dimension.
+   Adapter should map this to a "project_overview" meta-dimension.
+
+2. **Project Classification** -- BMAD includes project type, domain, complexity.
+   No Loki equivalent. Adapter should extract and pass as metadata.
+
+3. **Domain-Specific Requirements** -- Healthcare, fintech, govtech compliance sections.
+   No Loki dimension covers domain compliance. Consider adding as optional dimension.
+
+4. **Innovation & Novel Patterns** -- BMAD-specific section.
+   Not needed for scoring; pass through as supplementary context.
+
+5. **Frontmatter parsing** -- BMAD documents have YAML frontmatter with `stepsCompleted`,
+   `inputDocuments`, `workflowType`. Loki's prd-analyzer.py ignores frontmatter entirely.
+   Adapter must strip frontmatter before passing to analyzer OR extend analyzer.
+
+### Scoring Impact
+
+A well-formed BMAD PRD would score approximately **7.5-8.5/10** on the current analyzer
+without any changes:
+- `feature_list`: HIGH (## Functional Requirements + bullet lists)
+- `user_stories`: HIGH (## User Journeys + "As a..." stories in epics)
+- `acceptance_criteria`: HIGH (Given/When/Then in epics)
+- `tech_stack`: PARTIAL-HIGH (architecture.md has tech details, PRD may not)
+- `security`: PARTIAL (## Non-Functional Requirements > ### Security)
+- `deployment`: PARTIAL (may be in architecture.md, not PRD)
+- `data_model`: NONE-PARTIAL (usually in architecture.md, not PRD)
+- `api_spec`: NONE-PARTIAL (usually in architecture.md, not PRD)
+- `error_handling`: PARTIAL (## Non-Functional Requirements may cover this)
+
+With an adapter that also feeds architecture.md into the analyzer, score would be **9-10/10**.
+
+## 3. Agent Overlap Analysis
+
+### BMAD Agents (8) vs Loki Agent Types (41)
+
+| BMAD Agent | Role | Loki Equivalent(s) | Relationship |
+|---|---|---|---|
+| Mary (Analyst) | Business analysis, research | `prod-pm` (partial) | Complementary -- BMAD analyst is pre-development |
+| John (PM) | PRD creation, validation | `prod-pm`, `orch-planner` | Overlapping -- Loki PM focuses on execution planning |
+| Winston (Architect) | Architecture design | `eng-infra`, `orch-planner` | Complementary -- BMAD architect is pre-code |
+| Sally (UX Designer) | UX specification | `prod-design` | Complementary -- BMAD UX is spec, Loki is implementation |
+| Amelia (Developer) | Code implementation | `eng-*` (8 agents) | Superseded -- Loki has specialized dev agents |
+| Bob (Scrum Master) | Sprint planning | `orch-coordinator` | Overlapping -- different abstraction level |
+| Quinn (QA) | E2E test generation | `eng-qa` | Overlapping -- both generate tests |
+| Barry (Quick Flow) | Solo rapid dev | No equivalent | Unique to BMAD |
+
+### Assessment
+
+- **Zero conflict.** BMAD agents operate in the pre-development space (requirements, planning,
+  architecture). Loki agents operate in the execution space (coding, testing, deploying).
+- **Clear handoff point:** BMAD produces artifacts (PRD, architecture, epics). Loki consumes
+  them. The adapter bridges the format gap.
+- **Party Mode** (multi-agent collaboration) is a BMAD concept that could enrich Loki's
+  council-based review in future phases.
+
+## 4. Voice Compatibility Assessment
+
+### Current Capabilities (voice.sh)
+
+| Capability | Status |
+|---|---|
+| STT (Speech-to-Text) | Whisper API, local Whisper, macOS dictation |
+| TTS (Text-to-Speech) | macOS `say`, Linux espeak/festival |
+| Audio recording | sox, ffmpeg, arecord |
+| Guided dictation | 4-section template only (name, overview, requirements, tech stack) |
+| Structured dialogue | NOT SUPPORTED |
+| Agent handoff | NOT SUPPORTED |
+| Session persistence | NOT SUPPORTED |
+| Technical term correction | NOT SUPPORTED |
+
+### What BMAD Voice Integration (P2) Would Require
+
+| Requirement | Effort | Description |
+|---|---|---|
+| Step-file-to-question mapper | Large | Convert BMAD step instructions to conversational prompts |
+| Multi-turn dialogue manager | Large | Track conversation state, handle clarifications, backtracking |
+| Agent persona injection | Medium | Voice TTS uses agent voice characteristics |
+| Technical term correction loop | Medium | Confirm jargon transcription ("Did you say React or Preact?") |
+| Session persistence | Medium | Resume BMAD workflows across voice sessions |
+| Dual-mode interface | Large | Voice for elicitation, visual for review |
+
+### Assessment
+
+Voice integration (P2) is the highest-risk phase. The current voice.sh is a thin wrapper
+around STT/TTS tools. Transforming it into a structured dialogue system requires:
+- New conversation state machine (not just record-transcribe-write)
+- BMAD step-file interpreter (convert markdown instructions to conversational flow)
+- Feedback loop for transcription accuracy (critical for technical terms)
+
+**Recommendation:** Defer P2 entirely. P0 (artifact pipeline) delivers value without voice.
+Voice integration can be revisited after P0 proves the BMAD artifact format is stable and useful.
+
+## 5. Context Budget Analysis
+
+### Per-Iteration Context Cost (P0 Only)
+
+| Component | Tokens | Source |
+|---|---|---|
+| Loki SKILL.md | ~2,750 | Always loaded |
+| RARV instructions | ~1,500 | build_prompt() |
+| SDLC phases + rules | ~1,000 | build_prompt() |
+| Memory context | ~2,000-5,000 | Memory retrieval |
+| PRD content | ~5,000-12,000 | BMAD PRD document |
+| PRD observations | ~500-1,000 | prd-analyzer output |
+| **BMAD adapter metadata** | **~500-1,000** | **Project classification, artifact chain info** |
+| **BMAD architecture summary** | **~2,000-4,000** | **Condensed architecture decisions** |
+| **BMAD epic summary** | **~1,000-3,000** | **Active epic/story context** |
+| Checklist status | ~500-1,000 | verification-results.json |
+| Queue tasks | ~500-2,000 | .loki/queue/ |
+| **TOTAL** | **~17,250-32,250** | **Well under 150K ceiling** |
+
+### Verdict
+
+At worst case (~32K tokens), BMAD integration uses ~21% of a 150K context window.
+This leaves ample room for code context, tool outputs, and conversation history.
+No context pressure risk.
+
+## 6. Risk Register
+
+| Risk | Severity | Likelihood | Mitigation |
+|---|---|---|---|
+| BMAD output format changes in future versions | Medium | Medium | Adapter uses loose pattern matching, not exact schema; version-pin BMAD reference |
+| Malformed BMAD artifacts (partial workflow state) | Low | Medium | Adapter validates artifact completeness; falls back to freeform PRD path |
+| BMAD `_bmad-output/` not found | Low | Low | Clear error message; `--bmad-project` flag is explicit, not auto-detected |
+| prd-analyzer regression on freeform PRDs | High | Low | Test suite includes both BMAD and freeform PRD fixtures; backward compatibility gate |
+| Context budget exceeded with very large BMAD PRDs | Low | Low | PRD content is truncated at 12K tokens; architecture summary is condensed |
+| BMAD trademark concerns | Low | Low | MIT license permits code use; trademark applies to branding, not API integration |
+| Scope creep into P1/P2 during P0 implementation | Medium | Medium | Strict phase gates; P1/P2 deferred until P0 ships and proves value |
+
+## 7. Integration Architecture (P0)
+
+```
+User's BMAD project
+  _bmad-output/
+    planning-artifacts/
+      product-brief-*.md
+      prd-*.md              <-- Primary input
+      architecture.md       <-- Secondary input
+      epics.md              <-- Story/task source
+    implementation-artifacts/
+      sprint-status.yaml
+      *.story.md
+
+                    |
+                    v
+
+  autonomy/bmad-adapter.py
+    - Discover _bmad-output/ structure
+    - Parse BMAD frontmatter (stepsCompleted, workflowType)
+    - Strip frontmatter, normalize headings
+    - Extract project classification metadata
+    - Feed normalized PRD to prd-analyzer.py
+    - Map epics to .loki/queue/ task format
+
+                    |
+                    v
+
+  autonomy/prd-analyzer.py (enhanced)
+    - New heading patterns for BMAD sections
+    - Architecture.md scoring support
+    - BMAD quality bonus (structured methodology)
+    - Backward-compatible with freeform PRDs
+
+                    |
+                    v
+
+  autonomy/loki --bmad-project <path>
+    - Discovery: find _bmad-output/ in project
+    - Load: run bmad-adapter.py, then prd-analyzer.py
+    - Inject: BMAD metadata into build_prompt()
+    - Queue: BMAD epics/stories into .loki/queue/
+
+                    |
+                    v
+
+  autonomy/run.sh (build_prompt)
+    - BMAD context block injected alongside PRD
+    - Architecture decisions as supplementary context
+    - Epic/story tracking in checklist system
+```
+
+## 8. Recommendations
+
+1. **Proceed with P0 (Epic 1) only.** BMAD Artifact Pipeline.
+2. **Do not embed BMAD engine.** Read BMAD outputs, do not execute BMAD workflows.
+3. **Do not implement voice integration.** Defer to separate initiative.
+4. **Create adapter as standalone Python module.** `autonomy/bmad-adapter.py` -- stdlib only.
+5. **Enhance prd-analyzer.py conservatively.** Add patterns, do not restructure.
+6. **Test with real BMAD output fixtures.** Create test fixtures from BMAD's own templates.
+7. **Gate P1 on P0 success metrics:** At least 5 real projects use `--bmad-project` flag.

package/docs/architecture/bmad-loki-voice-agent-council-analysis.md

@@ -0,0 +1,61 @@
+# BMAD Method x Loki Mode Voice Agent -- Council Analysis
+
+**Date:** 2026-02-25
+**Council:** 3 Opus reviewers (blind review)
+**Verdict:** Unanimous YES with phased approach
+
+## Proposal Summary
+
+Integrate the BMAD Method (https://github.com/bmad-code-org/BMAD-METHOD) with Loki Mode
+to create a structured requirements elicitation pipeline. BMAD provides a 4-phase
+workflow (Analysis, Planning, Solutioning, Implementation) with agent personas, step-file
+architecture, and adversarial review -- complementing Loki Mode's autonomous execution engine.
+
+## Council Findings
+
+### Reviewer 1: Architecture Focus
+
+**Vote:** YES (phased)
+
+- BMAD's step-file architecture aligns with Loki's progressive disclosure model
+- BMAD artifacts (product-brief, PRD, architecture, epics) map cleanly to Loki's SDLC phases
+- Context budget is manageable: BMAD step files load one-at-a-time (~3K tokens each)
+- Integration surface is well-defined: `.loki/queue/`, `build_prompt()`, event bus
+- Risk: BMAD is an external dependency that may change format without notice
+
+### Reviewer 2: Integration Feasibility
+
+**Vote:** YES (phased)
+
+- BMAD PRD output sections (Functional Requirements, Success Criteria, User Journeys)
+  match most of prd-analyzer.py's existing dimension patterns
+- Agent overlap is complementary, not conflicting: BMAD covers pre-development, Loki covers execution
+- Voice.sh needs significant extension for structured dialogue (currently only 4-section dictation)
+- MIT license is fully compatible with Loki Mode's distribution
+- Risk: Voice agent layer (Phase 3) has highest uncertainty; STT reliability for technical terms
+
+### Reviewer 3: Risk and Quality
+
+**Vote:** YES (phased, with gates)
+
+- Backward compatibility is achievable: BMAD integration is additive (new flag, new adapter)
+- Existing non-BMAD projects are untouched unless `--bmad-project` is explicitly used
+- Quality gates apply to all new code: 3-reviewer blind review, anti-sycophancy, test coverage
+- BMAD's adversarial review methodology strengthens Loki's existing quality gate system
+- Risk: Scope creep from Epic 2 (engine embedding) and Epic 3 (voice agent) -- phase gates essential
+
+## Recommended Phased Approach
+
+| Phase | Epic | Priority | Risk |
+|-------|-------|----------|------|
+| P0 | BMAD Artifact Pipeline (parse, score, load) | Must-have | Low |
+| P1 | BMAD Engine Embedding (agent YAML parser, step processor) | Should-have | Medium |
+| P2 | Voice Agent Layer (structured dialogue, BMAD-to-voice) | Nice-to-have | High |
+
+## Key Constraints
+
+1. P0 must ship independently and prove value before P1/P2 begin
+2. No runtime dependency on BMAD repo -- adapter reads BMAD output artifacts only
+3. Zero regression on existing non-BMAD workflows
+4. All code must pass existing 9-gate quality system
+5. Context budget: BMAD additions must stay under 15K tokens per iteration

package/mcp/__init__.py

@@ -57,4 +57,4 @@ try:
 except ImportError:
     __all__ = ['mcp']
 
-__version__ = '6.0.0'
+__version__ = '6.2.0'

package/mcp/requirements.txt

@@ -1 +1,2 @@
 mcp>=1.0.0
+chromadb>=1.0.0

package/mcp/server.py

@@ -1214,6 +1214,158 @@ async def loki_quality_report() -> str:
         return json.dumps({"error": str(e)})
 
 
+# ============================================================
+# CODE SEARCH - ChromaDB-backed semantic code search
+# ============================================================
+
+# ChromaDB connection (lazy-initialized)
+_chroma_client = None
+_chroma_collection = None
+
+CHROMA_HOST = os.environ.get("LOKI_CHROMA_HOST", "localhost")
+CHROMA_PORT = int(os.environ.get("LOKI_CHROMA_PORT", "8100"))
+CHROMA_COLLECTION = os.environ.get("LOKI_CHROMA_COLLECTION", "loki-codebase")
+
+
+def _get_chroma_collection():
+    """Get or create ChromaDB collection (lazy connection)."""
+    global _chroma_client, _chroma_collection
+    if _chroma_collection is not None:
+        return _chroma_collection
+    try:
+        import chromadb
+        _chroma_client = chromadb.HttpClient(host=CHROMA_HOST, port=int(CHROMA_PORT))
+        _chroma_collection = _chroma_client.get_collection(name=CHROMA_COLLECTION)
+        return _chroma_collection
+    except Exception as e:
+        logger.warning(f"ChromaDB not available: {e}")
+        return None
+
+
+@mcp.tool()
+async def loki_code_search(
+    query: str,
+    n_results: int = 10,
+    language: Optional[str] = None,
+    file_filter: Optional[str] = None,
+    type_filter: Optional[str] = None,
+) -> str:
+    """Search the loki-mode codebase semantically.
+
+    Finds functions, classes, and code sections by meaning, not just keywords.
+    Returns file paths, line numbers, and code snippets ranked by relevance.
+
+    Args:
+        query: Natural language search query (e.g., "rate limit detection",
+               "model selection for RARV tier", "how does the council vote")
+        n_results: Number of results to return (default 10, max 30)
+        language: Filter by language: "shell", "python", "markdown" (optional)
+        file_filter: Filter by file path substring (e.g., "autonomy/", "dashboard/") (optional)
+        type_filter: Filter by chunk type: "function", "class", "header", "section", "file" (optional)
+    """
+    _emit_tool_event_async('loki_code_search', 'start', query=query)
+
+    collection = _get_chroma_collection()
+    if collection is None:
+        return json.dumps({
+            "error": "ChromaDB not available. Start it with: docker start loki-chroma",
+            "hint": "Re-index with: python3.12 tools/index-codebase.py --reset"
+        })
+
+    n_results = min(max(1, n_results), 30)
+
+    # Build where filter
+    where_clauses = []
+    if language:
+        where_clauses.append({"language": language})
+    if type_filter:
+        where_clauses.append({"type": type_filter})
+
+    where = None
+    if len(where_clauses) == 1:
+        where = where_clauses[0]
+    elif len(where_clauses) > 1:
+        where = {"$and": where_clauses}
+
+    try:
+        results = collection.query(
+            query_texts=[query],
+            n_results=n_results,
+            where=where,
+            include=["documents", "metadatas", "distances"],
+        )
+
+        # Format results
+        output = []
+        for i in range(len(results["ids"][0])):
+            meta = results["metadatas"][0][i]
+            doc = results["documents"][0][i]
+            dist = results["distances"][0][i]
+
+            # Apply file_filter post-query (ChromaDB where doesn't support substring match)
+            if file_filter and file_filter not in meta.get("file", ""):
+                continue
+
+            # Truncate document for response
+            preview = doc[:500] + "..." if len(doc) > 500 else doc
+
+            output.append({
+                "file": meta.get("file", ""),
+                "line": meta.get("line", 0),
+                "name": meta.get("name", ""),
+                "type": meta.get("type", ""),
+                "language": meta.get("language", ""),
+                "relevance": round(1 - dist, 4),  # Convert distance to similarity
+                "preview": preview,
+            })
+
+        _emit_tool_event_async('loki_code_search', 'complete',
+                               result_status='success', result_count=len(output))
+        return json.dumps({"query": query, "results": output, "total": len(output)})
+
+    except Exception as e:
+        logger.error(f"Code search failed: {e}")
+        _emit_tool_event_async('loki_code_search', 'complete',
+                               result_status='error', error=str(e))
+        return json.dumps({"error": str(e)})
+
+
+@mcp.tool()
+async def loki_code_search_stats() -> str:
+    """Get statistics about the code search index.
+
+    Shows total chunks, files indexed, breakdown by language and type.
+    Useful for verifying the index is up to date.
+    """
+    collection = _get_chroma_collection()
+    if collection is None:
+        return json.dumps({"error": "ChromaDB not available"})
+
+    try:
+        count = collection.count()
+        results = collection.get(limit=count, include=["metadatas"])
+
+        langs = {}
+        types = {}
+        files = set()
+        for meta in results["metadatas"]:
+            lang = meta.get("language", "unknown")
+            typ = meta.get("type", "unknown")
+            langs[lang] = langs.get(lang, 0) + 1
+            types[typ] = types.get(typ, 0) + 1
+            files.add(meta.get("file", ""))
+
+        return json.dumps({
+            "total_chunks": count,
+            "unique_files": len(files),
+            "by_language": langs,
+            "by_type": types,
+            "reindex_command": "python3.12 tools/index-codebase.py --reset",
+        })
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
 # ============================================================
 # PROMPTS - Pre-built prompt templates
 # ============================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loki-mode",
-  "version": "6.0.0",
+  "version": "6.2.0",
   "description": "Loki Mode by Autonomi - Multi-agent autonomous startup system for Claude Code, Codex CLI, and Gemini CLI",
   "keywords": [
     "agent",

package/templates/clusters/README.md

@@ -0,0 +1,21 @@
+# Cluster Templates
+
+Pre-built workflow topologies for common development patterns.
+
+## Usage
+
+    loki cluster list                    # List available templates
+    loki cluster validate <template>     # Validate topology
+    loki cluster run <template> [args]   # Execute workflow
+
+## Template Format
+
+Each template is a JSON file defining agents, their pub/sub topics,
+and the workflow topology.
+
+## Available Templates
+
+- security-review: Multi-agent security audit pipeline
+- performance-audit: Performance analysis with profiling
+- refactoring: Structured refactoring with test preservation
+- code-review: Multi-reviewer code review process

package/templates/clusters/code-review.json

@@ -0,0 +1,36 @@
+{
+    "name": "Code Review",
+    "description": "Multi-reviewer code review with conflict resolution",
+    "version": "1.0.0",
+    "topology": "fan-out-fan-in",
+    "agents": [
+        {
+            "id": "reviewer-arch",
+            "type": "review-code",
+            "role": "Review architecture and design patterns",
+            "subscribes": ["task.start"],
+            "publishes": ["review.architecture"]
+        },
+        {
+            "id": "reviewer-security",
+            "type": "review-security",
+            "role": "Review security implications",
+            "subscribes": ["task.start"],
+            "publishes": ["review.security"]
+        },
+        {
+            "id": "reviewer-tests",
+            "type": "eng-qa",
+            "role": "Review test coverage and quality",
+            "subscribes": ["task.start"],
+            "publishes": ["review.tests"]
+        },
+        {
+            "id": "resolver",
+            "type": "review-code",
+            "role": "Synthesize all review findings and resolve conflicts",
+            "subscribes": ["review.architecture", "review.security", "review.tests"],
+            "publishes": ["task.complete"]
+        }
+    ]
+}

package/templates/clusters/performance-audit.json

@@ -0,0 +1,29 @@
+{
+    "name": "Performance Audit",
+    "description": "Performance analysis with profiling and optimization recommendations",
+    "version": "1.0.0",
+    "topology": "fan-out-fan-in",
+    "agents": [
+        {
+            "id": "profiler",
+            "type": "eng-perf",
+            "role": "Profile application and identify bottlenecks",
+            "subscribes": ["task.start"],
+            "publishes": ["profile.results"]
+        },
+        {
+            "id": "db-analyzer",
+            "type": "eng-database",
+            "role": "Analyze database queries and index usage",
+            "subscribes": ["task.start"],
+            "publishes": ["db.analysis"]
+        },
+        {
+            "id": "optimizer",
+            "type": "eng-perf",
+            "role": "Generate optimization recommendations from all analyses",
+            "subscribes": ["profile.results", "db.analysis"],
+            "publishes": ["task.complete"]
+        }
+    ]
+}