Review 281125

# Kotef Architecture Review — 28.11.2025

## Deep Context Reference

For detailed architecture diagrams, complete agent flow (Mermaid), state structure, edge cases, and known issues, see:

**`/Users/sasha/IdeaProjects/personal_projects/kotef/.sdd/prompts/06_research_281125.md`**

This document contains:
- Full Mermaid flowcharts for main graph, each node, and SDD orchestrator
- Complete `AgentState` TypeScript interface
- Edge case handling tables
- Prompt roles and responsibilities
- Known architectural problems

---

## Context

**Kotef** is an autonomous AI coding agent built on Node.js/TypeScript/LangGraph.js. It uses SDD (Spec-Driven Development) as its "brain" for planning and executing tasks. Integrates with external LLMs (OpenRouter) for planning/research and Kiro CLI for coding.

**Current state**: MVP works, but the implementation feels over-engineered in some places while missing important aspects in others. Project is maintained by a single developer.

---

## Architectural Questions for Analysis

### 1. Repo Discovery — Is it deep enough?

**What exists:**
- `project_summary.ts` — basic analysis: languages by extensions, frameworks from package.json
- `code_index.ts` — ts-morph index for TS/JS (symbols, functions)
- `code_index_treesitter.ts` — tree-sitter for Python/Go/Rust/Java
- `contextScan` — cwd, files, gitStatus, readmeSummary

**What's missing (compared to modern agents):**
- Semantic code search (embeddings)
- Import graph / dependency tree analysis
- Understanding of architectural patterns (MVC, Clean Architecture)
- LSP integration for type information
- "Hot paths" in code

**Question:** Should we add semantic search or is improving tree-sitter + import graph sufficient?

---

### 2. Context Loss at OpenRouter → Kiro Handoff

**Flow:**