From f5c9d6d876899da52d2b1907c9f38ca597e0b127 Mon Sep 17 00:00:00 2001 From: demonshinobi Date: Thu, 5 Feb 2026 02:36:56 -0500 Subject: [PATCH] docs: update component counts to match codebase Updated verified counts: - Skills: 114 (was 108-109) - Agents: 48 (was 32) - Hooks: 34 TypeScript source files - MCP Servers: 9 (was 10) - Added Lean proofs count: 108 Co-Authored-By: Claude Opus 4.5 --- .../20260204-025956/ARCHITECTURE.md | 795 ++++++++++ .auto-doc-history/20260204-025956/README.md | 1257 ++++++++++++++++ .../20260205-023154/ARCHITECTURE.md | 812 +++++++++++ .auto-doc-history/20260205-023154/README.md | 1277 +++++++++++++++++ .auto-doc-timestamp | 22 + README.md | 57 +- docs/ARCHITECTURE.md | 26 +- 7 files changed, 4224 insertions(+), 22 deletions(-) create mode 100644 .auto-doc-history/20260204-025956/ARCHITECTURE.md create mode 100644 .auto-doc-history/20260204-025956/README.md create mode 100644 .auto-doc-history/20260205-023154/ARCHITECTURE.md create mode 100644 .auto-doc-history/20260205-023154/README.md create mode 100644 .auto-doc-timestamp diff --git a/.auto-doc-history/20260204-025956/ARCHITECTURE.md b/.auto-doc-history/20260204-025956/ARCHITECTURE.md new file mode 100644 index 00000000..5a74264d --- /dev/null +++ b/.auto-doc-history/20260204-025956/ARCHITECTURE.md @@ -0,0 +1,795 @@ +# Continuous Claude v3 - Architecture Guide + +## Executive Summary + +Continuous Claude v3 is an **agentic AI development environment** built on top of Claude Code. It transforms a single AI assistant into a coordinated system of specialized agents, with automatic context management, semantic memory, and token-efficient code analysis. Think of it as "VS Code + GitHub Copilot, but the AI can delegate to specialist AIs, remember past sessions, and understand code at the AST level." + +The system has four main layers: **Skills** (what users can trigger), **Hooks** (automatic behaviors), **Agents** (specialized sub-assistants), and **Infrastructure** (persistence and analysis tools). + +--- + +## Architecture Diagram + +``` ++-----------------------------------------------------------------------------------+ +| USER INTERACTION | +| "help me understand authentication" | "implement feature X" | "debug this bug" | ++-----------------------------------------------------------------------------------+ + | + v ++-----------------------------------------------------------------------------------+ +| SKILL ACTIVATION LAYER | +| skill-rules.json -> keyword/intent matching -> skill suggestion/injection | ++-----------------------------------------------------------------------------------+ + | + v ++-----------------------------------------------------------------------------------+ +| HOOK LAYER | +| | +| +-------------+ +---------------+ +--------------+ +----------------+ | +| | SessionStart| | UserPrompt | | PreToolUse | | PostToolUse | | +| | - Continuity| | - Skill inject| | - Search rtr | | - Compiler | | +| | - Indexing | | - Braintrust | | - TLDR inject| | - Handoff idx | | +| +-------------+ +---------------+ +--------------+ +----------------+ | +| | +| +-------------+ +---------------+ +--------------+ +----------------+ | +| | SubagentSt | | SubagentStop | | Stop | | SessionEnd | | +| | - Register | | - Continuity | | - Coordinator| | - Cleanup | | +| +-------------+ +---------------+ +--------------+ +----------------+ | ++-----------------------------------------------------------------------------------+ + | + v ++-----------------------------------------------------------------------------------+ +| AGENT LAYER (41 agents) | +| | +| ORCHESTRATORS IMPLEMENTERS EXPLORERS REVIEWERS | +| +----------+ +----------+ +----------+ +----------+ | +| | maestro | | kraken | | scout | | critic | | +| | (opus) | | (opus) | | (sonnet) | | (sonnet) | | +| | multi-ag | | TDD impl | | codebase | | code | | +| +----------+ +----------+ +----------+ +----------+ | +| | +| PLANNERS DEBUGGERS VALIDATORS SPECIALIZED | +| +----------+ +----------+ +----------+ +----------+ | +| | architect| | sleuth | | arbiter | | aegis | | +| | (opus) | | (opus) | | (opus) | | security | | +| | design | | debug | | testing | +----------+ | +| +----------+ +----------+ +----------+ | phoenix | | +| | refactor | | +| +----------+ | ++-----------------------------------------------------------------------------------+ + | + v ++-----------------------------------------------------------------------------------+ +| INFRASTRUCTURE LAYER | +| | +| +-------------------+ +-------------------+ +-------------------+ | +| | TLDR-Code 5-Layer | | PostgreSQL+pgvec | | File Persistence | | +| | - AST (structure) | | - sessions | | - thoughts/shared | | +| | - Call Graph | | - file_claims | | - handoffs/ | | +| | - CFG (control) | | - archival_memory | | - plans/ | | +| | - DFG (data flow) | | - handoffs | | - ledgers/ | | +| | - PDG (deps) | | | | - .claude/cache/ | | +| +-------------------+ +-------------------+ +-------------------+ | +| | +| +-------------------+ +-------------------+ +-------------------+ | +| | Symbol Index | | Artifact Index | | MCP Servers | | +| | /tmp/claude- | | (SQLite FTS5) | | - Firecrawl | | +| | symbol-index/ | | - handoffs | | - Perplexity | | +| | symbols.json | | - plans | | - GitHub | | +| | callers.json | | - continuity | | - AST-grep | | +| +-------------------+ +-------------------+ +-------------------+ | ++-----------------------------------------------------------------------------------+ +``` + +--- + +## 1. Capability Catalog (What Users Can Do) + +Users activate capabilities through **natural language keywords**. No slash commands needed - the system detects intent. + +### Planning & Workflow + +| Capability | Trigger Keywords | What It Does | +|------------|-----------------|--------------| +| **Create Plan** | "create plan", "plan feature", "design" | Architect agent creates phased implementation plan | +| **Implement Plan** | "implement plan", "execute plan", "follow plan" | Kraken agent executes plan with TDD | +| **Create Handoff** | "create handoff", "done for today", "wrap up" | Saves session state for future pickup | +| **Resume Handoff** | "resume handoff", "continue work", "pick up where" | Restores context from previous session | +| **Continuity Ledger** | "save state", "before compact", "low on context" | Creates checkpoint within session | + +### Code Understanding (TLDR-Code) + +| Capability | Trigger Keywords | What It Does | +|------------|-----------------|--------------| +| **Call Graph** | "what calls", "who calls", "calls what" | Shows function call relationships | +| **Complexity Analysis** | "how complex", "cyclomatic" | CFG-based complexity metrics | +| **Data Flow** | "where does variable", "what sets" | Tracks variable origins and uses | +| **Program Slicing** | "what affects line", "dependencies" | PDG-based impact analysis | + +### Search & Research + +| Capability | Trigger Keywords | What It Does | +|------------|-----------------|--------------| +| **Semantic Search** | "recall", "what worked", "past decisions" | Searches archival memory with embeddings | +| **Structural Search** | "ast", "find all calls", "refactor" | AST-grep for code patterns | +| **Text Search** | "grep", "find in code", "search for" | Fast text search via Morph/Grep | +| **Web Research** | "search the web", "look up", "perplexity" | AI-powered web search | +| **Documentation** | "docs", "how to use", "API reference" | Library docs via Nia | + +### Code Quality + +| Capability | Trigger Keywords | What It Does | +|------------|-----------------|--------------| +| **Quality Check** | "lint", "code quality", "auto-fix" | Qlty CLI with 70+ linters | +| **TDD Workflow** | "implement", "add feature", "fix bug" | Forces test-first development | +| **Debug** | "debug", "investigate", "why is it" | Spawns debug-agent for investigation | + +### Git & GitHub + +| Capability | Trigger Keywords | What It Does | +|------------|-----------------|--------------| +| **Commit** | "commit", "save changes", "push" | Git commit with user approval | +| **PR Description** | "describe pr", "create pr" | Generates PR description from changes | +| **GitHub Search** | "github", "search repo", "PR" | Searches GitHub via MCP | + +### Math & Computation + +| Capability | Trigger Keywords | What It Does | +|------------|-----------------|--------------| +| **Math Computation** | "calculate", "solve", "integrate" | SymPy, Z3, Pint computation | +| **Formal Proofs** | "prove", "theorem", "verify" | Lean 4 + Godel-Prover | + +--- + +## 2. Hook Layer (Automatic Behaviors) + +Hooks fire automatically at specific lifecycle points. Users don't invoke them directly - they just work. + +### PreToolUse Hooks + +| Hook | Triggers On | What It Does | +|------|-------------|--------------| +| `path-rules` | Read, Edit, Write | Enforces file access patterns | +| `tldr-read-enforcer` | Read | Intercepts file reads, offers TLDR context instead | +| `smart-search-router` | Grep | Routes to AST-grep/LEANN/Grep based on query type | +| `tldr-context-inject` | Task | Adds code context to subagent prompts | +| `file-claims` | Edit | Tracks which session owns which files | +| `pre-edit-context` | Edit | Injects context before edits | + +### PostToolUse Hooks + +| Hook | Triggers On | What It Does | +|------|-------------|--------------| +| `pattern-orchestrator` | Task | Manages multi-agent patterns (pipeline, jury, debate) | +| `typescript-preflight` | Edit, Write | Runs TypeScript compiler check | +| `handoff-index` | Write | Indexes handoff documents for search | +| `compiler-in-the-loop` | Write | Validates code changes compile | +| `import-validator` | Edit, Write | Checks import statements are valid | + +### Session Lifecycle Hooks + +| Hook | Fires When | What It Does | +|------|------------|--------------| +| `session-register` | SessionStart | Registers session in coordination layer | +| `session-start-continuity` | Resume/Compact | Restores continuity ledger | +| `skill-activation-prompt` | UserPromptSubmit | Suggests relevant skills | +| `subagent-start` | SubagentStart | Registers subagent spawn | +| `subagent-stop-continuity` | SubagentStop | Saves subagent state | +| `stop-coordinator` | Stop | Handles graceful shutdown | +| `session-end-cleanup` | SessionEnd | Cleanup and final state save | + +--- + +## 3. Agent Layer + +41 specialized agents, each with a defined role, model preference, and tool access. + +### Orchestration Agents + +| Agent | Model | Purpose | +|-------|-------|---------| +| **maestro** | opus | Multi-agent coordination, pattern selection | +| **kraken** | opus | TDD implementation, checkpointing, resumable work | + +### Planning Agents + +| Agent | Model | Purpose | +|-------|-------|---------| +| **architect** | opus | Feature design, interface planning, integration design | +| **phoenix** | opus | Refactoring plans, tech debt analysis | +| **pioneer** | opus | Migration planning, framework upgrades | + +### Exploration Agents + +| Agent | Model | Purpose | +|-------|-------|---------| +| **scout** | sonnet | Codebase exploration, pattern finding | +| **oracle** | opus | External research (web, docs) | +| **pathfinder** | sonnet | Navigation, file location | + +### Implementation Agents + +| Agent | Model | Purpose | +|-------|-------|---------| +| **spark** | sonnet | Quick fixes, small changes | +| **kraken** | opus | Full TDD implementation | + +### Debugging Agents + +| Agent | Model | Purpose | +|-------|-------|---------| +| **sleuth** | opus | Debug investigation, root cause analysis | +| **profiler** | opus | Performance analysis | + +### Validation Agents + +| Agent | Model | Purpose | +|-------|-------|---------| +| **arbiter** | opus | Unit/integration testing | +| **atlas** | opus | E2E testing | +| **validator** | sonnet | Plan validation against precedent | + +### Review Agents + +| Agent | Model | Purpose | +|-------|-------|---------| +| **critic** | sonnet | Code review | +| **judge** | sonnet | Refactor review | +| **warden** | sonnet | Security review | +| **surveyor** | sonnet | Migration completeness | + +### Specialized Agents + +| Agent | Model | Purpose | +|-------|-------|---------| +| **aegis** | opus | Security analysis, vulnerability scanning | +| **herald** | sonnet | Release preparation, changelog | +| **scribe** | sonnet | Documentation generation | +| **liaison** | sonnet | Integration/API quality review | + +### Agent Output Location + +All agents write their output to: +``` +.claude/cache/agents//latest-output.md +``` + +--- + +## 4. Infrastructure Layer + +### TLDR-Code (5-Layer Code Analysis) + +**Install:** `uv tool install llm-tldr` | **Source:** [github.com/parcadei/tldr-code](https://github.com/parcadei/tldr-code) + +A token-efficient code understanding system that provides 85% token savings compared to raw file reads. + +| Layer | Extractor | What It Provides | +|-------|-----------|------------------| +| **L1: AST** | `ast_extractor.py` | Functions, classes, imports, structure | +| **L2: Call Graph** | `hybrid_extractor.py`, `cross_file_calls.py` | What calls what, cross-file dependencies | +| **L3: CFG** | `cfg_extractor.py` | Control flow, cyclomatic complexity | +| **L4: DFG** | `dfg_extractor.py` | Variable definitions and uses, data flow | +| **L5: PDG** | `pdg_extractor.py` | Program dependencies, backward/forward slicing | + +**Supported Languages:** Python, TypeScript, Go, Rust + +**API Entry Point:** `tldr/api.py` +```python +from tldr.api import get_relevant_context, query, get_slice +``` + +### PostgreSQL + pgvector + +Schema in `docker/init-schema.sql` + +| Table | Purpose | +|-------|---------| +| `sessions` | Cross-terminal awareness and coordination | +| `file_claims` | Cross-terminal file locking | +| `archival_memory` | Long-term learnings with vector embeddings | +| `handoffs` | Session handoffs with embeddings | + +**Features:** +- Semantic search via pgvector embeddings (1024-dim BGE) +- Hybrid RRF search (text + vector combined) +- Cross-session coordination + +### Artifact Index (SQLite FTS5) + +Schema: `opc/scripts/artifact_schema.sql` +Location: `.claude/cache/context-graph/context.db` + +| Table | Indexed Content | +|-------|-----------------| +| `handoffs` | Task summary, what worked/failed, key decisions | +| `plans` | Title, overview, approach, phases | +| `continuity` | Goal, state, learnings | +| `queries` | Q&A pairs for compound learning | + +**Features:** +- Full-text search with porter stemming +- BM25 ranking with column weights +- Automatic FTS sync via triggers + +### File-Based Persistence + +``` +thoughts/ + shared/ + handoffs/ # Session handoff documents (YAML) + / + current.md # Active handoff + *.yaml # Historical handoffs + plans/ # Implementation plans + ledgers/ # Continuity snapshots + experiments/ # A/B tests, comparisons + skill-builds/ # Skill development iterations + +.claude/ + cache/ + agents/ # Agent outputs + /latest-output.md + patterns/ # Multi-agent pattern state + pipeline-*.json + jury-*.json + context-graph/ # SQLite artifact index + hooks/src/ # Hook implementations + skills/ # Skill definitions + agents/ # Agent definitions +``` + +### Symbol Index + +Location: `/tmp/claude-symbol-index/` + +| File | Content | +|------|---------| +| `symbols.json` | Function/class definitions with location | +| `callers.json` | Who calls each function | + +Built by `build_symbol_index.py` on SessionStart. + +--- + +## 5. Key Python Scripts + +### Entry Points (User-Callable) + +| Script | Purpose | +|--------|---------| +| `recall_learnings.py` | Semantic search of archival memory | +| `store_learning.py` | Store a new learning | +| `observe_agents.py` | Query running agent state | +| `braintrust_analyze.py` | Analyze session logs | +| `artifact_query.py` | Search artifact index | + +### Background Services + +| Script | Purpose | +|--------|---------| +| `build_symbol_index.py` | Builds symbol index on session start | +| `index_incremental.py` | Incremental artifact indexing | + +### Computation Backends + +| Script | Purpose | +|--------|---------| +| `sympy_compute.py` | Symbolic math | +| `z3_solve.py` | Constraint solving | +| `pint_compute.py` | Unit conversions | +| `math_router.py` | Routes math queries to backends | + +### Hook Launcher + +`hook_launcher.py` - Central dispatcher that compiles and runs TypeScript hooks via the `tsc-cache/` directory. + +--- + +## 6. Data Flow Diagrams + +### User Request Flow + +``` +User: "debug the authentication bug" + | + v ++-------------------+ +| UserPromptSubmit | skill-activation-prompt hook fires ++-------------------+ + | + v (skill suggested: debug-agent) ++-------------------+ +| Task Tool | spawns debug-agent ++-------------------+ + | + v ++-------------------+ +| PreToolUse:Task | tldr-context-inject adds code context ++-------------------+ + | + v ++-------------------+ +| debug-agent runs | uses TLDR-code, searches codebase ++-------------------+ + | + v ++-------------------+ +| PostToolUse:Task | pattern-orchestrator checks completion ++-------------------+ + | + v ++-------------------+ +| Agent Output | .claude/cache/agents/debug-agent/latest-output.md ++-------------------+ +``` + +### Code Context Injection Flow + +``` +Claude wants to Read file.py + | + v ++-------------------+ +| PreToolUse:Read | tldr-read-enforcer fires ++-------------------+ + | + v (blocks read, suggests TLDR) ++-------------------+ +| TLDR Analysis | +| L1: AST extract | +| L2: Call graph | +| L3: CFG (if func) | ++-------------------+ + | + v ++-------------------+ +| Context Returned | 95% fewer tokens than raw file ++-------------------+ +``` + +### Search Routing Flow + +``` +Claude calls Grep("validateToken") + | + v ++-------------------+ +| PreToolUse:Grep | smart-search-router fires ++-------------------+ + | + v (detects: structural query about function) ++-------------------+ +| Route Decision | +| - Structural? -> AST-grep +| - Semantic? -> LEANN/Embeddings +| - Literal? -> Grep (pass through) ++-------------------+ + | + v (this is structural) ++-------------------+ +| Redirect to | uses AST-grep for function references +| AST-grep | ++-------------------+ +``` + +--- + +## 7. Key Files Reference + +### Configuration + +| File | Purpose | +|------|---------| +| `.claude/settings.json` | Hook registration, tool configuration | +| `.claude/skills/skill-rules.json` | Skill triggers and keywords | +| `opc/pyproject.toml` | Python dependencies | + +### Hook Implementations + +| File | Purpose | +|------|---------| +| `.claude/hooks/src/smart-search-router.ts` | Routes searches to best tool | +| `.claude/hooks/src/tldr-context-inject.ts` | Adds TLDR context to agents | +| `.claude/hooks/src/pattern-orchestrator.ts` | Multi-agent pattern management | +| `.claude/hooks/src/session-start-continuity.ts` | Restores session state | +| `.claude/hooks/src/handoff-index.ts` | Indexes handoff documents | + +### Agent Definitions + +| File | Purpose | +|------|---------| +| `.claude/agents/kraken.md` | TDD implementation agent | +| `.claude/agents/maestro.md` | Multi-agent orchestrator | +| `.claude/agents/architect.md` | Feature planning agent | +| `.claude/agents/scout.md` | Codebase exploration | + +### Core Libraries + +| File | Purpose | +|------|---------| +| `tldr/api.py` (llm-tldr package) | TLDR-Code public API | +| `opc/scripts/temporal_memory/store_pg.py` | Temporal memory PostgreSQL store | +| `opc/scripts/artifact_index.py` | Artifact index management | + +--- + +## 8. Getting Started + +### For Users + +1. **Ask naturally** - "help me understand the auth system" triggers appropriate skills/agents +2. **Create plans first** - "create a plan for feature X" before implementing +3. **Use handoffs** - "create handoff" when stopping, "resume handoff" when returning +4. **Trust the routing** - the system picks the right tool (TLDR vs Grep vs AST-grep) + +### For Developers + +1. **Add skills** in `.claude/skills//SKILL.md` +2. **Register triggers** in `.claude/skills/skill-rules.json` +3. **Add hooks** in `.claude/hooks/src/*.ts`, register in `.claude/settings.json` +4. **Add agents** in `.claude/agents/.md` + +### Key Invariants + +- **Agents write to files, not stdout** - all agent output goes to `.claude/cache/agents/` +- **Hooks are fast** - timeouts are 5-60 seconds +- **Memory is semantic** - use embeddings for recall, not exact match +- **TDD is enforced** - implementation agents write tests first +- **Context is precious** - TLDR saves 85% tokens + +--- + +## 9. Glossary + +| Term | Meaning | +|------|---------| +| **Skill** | A capability triggered by keywords in user input | +| **Hook** | Automatic behavior at lifecycle points (PreToolUse, etc.) | +| **Agent** | Specialized sub-assistant spawned via Task tool | +| **TLDR-Code** | Token-efficient code analysis (5 layers) | +| **Handoff** | Document transferring state between sessions | +| **Continuity Ledger** | Checkpoint within a session | +| **Artifact Index** | Full-text searchable index of past work | +| **Temporal Fact** | Fact that evolves over turns (e.g., "current goal") | +| **Pattern** | Multi-agent coordination (pipeline, jury, debate, gencritic) | + +--- + +## 10. TLDR 5-Layer Analysis Results + +> Generated via `tldr arch`, `tldr calls`, `tldr dead`, `tldr cfg`, `tldr dfg` + +### 10.1 Architectural Layer Detection (L2: Call Graph) + +TLDR detected 3 architectural layers based on call patterns: + +#### Entry Layer (Controllers/Handlers) +Files that are called from outside but rarely call other internal code. + +| Directory | Calls Out | Calls In | Functions | Inferred Layer | +|-----------|-----------|----------|-----------|----------------| +| `scripts/` (root) | 21 | 3 | 1,232 | HIGH (entry) | +| `archive/` | 66 | 6 | 590+ | HIGH (entry, dead code) | +| `temporal_memory/` | 13 | 1 | 55 | HIGH (entry) | + +#### Service Layer (Business Logic) +Files that mediate between entry and data layers. + +| Directory | Calls Out | Calls In | Functions | Inferred Layer | +|-----------|-----------|----------|-----------|----------------| +| `monitors/` | 1 | 0 | 25 | MIDDLE (service) | + +#### Data Layer (Utilities) +Files that provide primitive operations, rarely call other code. + +| Directory | Calls Out | Calls In | Functions | Inferred Layer | +|-----------|-----------|----------|-----------|----------------| +| `agentica_patterns/` | 4 | 116 | 251 | LOW (utility) | +| `setup/` | 0 | 4 | 67 | LOW (utility) | +| `sacred_tui/` | 0 | 2 | 11 | LOW (utility) | +| `security/` | 0 | 0 | 4 | LOW (utility) | + +### 10.2 Cross-File Call Graph (Key Edges) + +Selected high-impact call relationships: + +``` +math_router.py + → sympy_compute.py:safe_parse + → numpy_compute.py:cmd_* + → scipy_compute.py:cmd_* + → mpmath_compute.py:cmd_* + +temporal_memory/store_pg.py + → postgres_pool.py:get_connection + → postgres_pool.py:init_pgvector + +memory_service_pg.py + → postgres_pool.py:get_connection (38 callers total) + → embedding_service.py:embed + +braintrust_hooks.py + → session_start → get_project_id + → session_start → get_session_value + → log → ensure_dirs +``` + +#### Most Called Functions (Impact Analysis) + +| Function | File | Caller Count | Description | +|----------|------|--------------|-------------| +| `get_connection` | `postgres_pool.py` | 38 | Central DB connection pool | +| `math_command` | `math_base.py` | 50+ | Math computation wrapper | +| `parse_array` | `math_base.py` | 30+ | Array parsing for numpy | +| `parse_matrix` | `math_base.py` | 20+ | Matrix parsing for scipy | + +### 10.3 Complexity Hot Spots (L3: CFG) + +Functions with elevated cyclomatic complexity: + +| Function | File | Complexity | Blocks | Reason | +|----------|------|------------|--------|--------| +| `session_start` | `braintrust_hooks.py` | 5 | 13 | Multiple early returns | +| `search_hybrid` | `memory_service_pg.py` | 3 | 6 | Date filter branches | +| `infer_pattern` | `pattern_inference.py` | 12+ | - | Pattern matching logic | +| `main` | `compiler-in-the-loop.ts` | 8+ | - | Lean4 + Loogle integration | +| `main` | `skill-activation-prompt.ts` | 10+ | - | Large skill matching switch | + +#### Refactoring Candidates + +1. **`skill-activation-prompt.ts:main`** - Extract skill matchers to separate functions +2. **`pattern_inference.py:infer_pattern`** - Use strategy pattern +3. **`braintrust_hooks.py`** - Split session vs span logic + +### 10.4 Data Flow Analysis (L4: DFG) + +#### Key Data Paths + +**PostgreSQL Connection Flow (38 callers):** +``` +postgres_pool.py:get_connection() + ├── memory_service_pg.py (all methods) + ├── temporal_memory/store_pg.py + ├── coordination_pg.py + ├── message_memory.py + └── populate_temporal_sessions.py +``` + +**Embedding Pipeline:** +``` +Input text + → embedding_service.py:embed() + → OpenAI/Local API + → memory_service_pg.py:store() + → PostgreSQL (pgvector column) +``` + +**search_hybrid Data Flow:** +``` +Parameters: + text_query: str + query_embedding: list[float] (1536 dims) + limit: int = 10 + text_weight: float = 0.5 + vector_weight: float = 0.5 + start_date, end_date: Optional[datetime] + │ + ▼ + _pad_embedding() → padded_query + │ + ▼ + Build SQL conditions (date filters) + │ + ▼ + Execute hybrid query: + SELECT ... + ts_rank(...) * text_weight + + (1 - embedding <=> query) * vector_weight + │ + ▼ +Output: list[MemoryRecord] +``` + +### 10.5 Dead Code Analysis + +#### Cleanup Completed (2026-01-07) + +**Files archived:** +| File | Reason | +|------|--------| +| `offline_search.py` → `archive/` | Duplicate of wizard functionality, only test imports | +| `service_checks.py` → `archive/` | Duplicate of wizard functionality, only test imports | +| `test_mcp_offline.py` → `tests/archive/` | Tests for archived files | + +**Functions removed:** +| File | Function | Reason | +|------|----------|--------| +| `braintrust_analyze.py` | `format_duration` | Never called, no tests | +| `secrets_filter.py` | `mask_secret` | Never called, not exported | + +**Functions kept (have tests, cross-platform support):** +| File | Function | Reason | +|------|----------|--------| +| `hook_launcher.py` | `expand_path` | Cross-platform path handling, tested | + +#### Archive Directory (490+ functions) + +The `archive/` directory contains deprecated subsystems: + +| File | Status | Note | +|------|--------|------| +| `offline_search.py` | Archived | Duplicate of wizard SQLite fallback | +| `service_checks.py` | Archived | Duplicate of wizard service checks | +| `user_preferences.py` | Dead | Old preference system | +| `websocket_multiplex.py` | Dead | Replaced by coordination_pg | +| `skill_validation.py` | Dead | Moved to hooks | +| `ledger_workflow.py` | Dead | Superseded by continuity hooks | +| `post_tool_use_flywheel.py` | Dead | Never integrated | +| `db_connection.py` | Dead | Replaced by postgres_pool | + +### 10.6 Circular Dependencies + +**Resolved:** The `claude_scope ↔ unified_scope` circular dependency was eliminated by archiving both modules (2026-01-07). These were Agentica infrastructure modules that were never integrated into production hooks or skills. + +No circular dependencies remain in active code. + +### 10.7 TLDR-Code Package Structure + +**PyPI:** `llm-tldr` | **Source:** [github.com/parcadei/tldr-code](https://github.com/parcadei/tldr-code) + +| Module | Layer | Functions | Classes | Purpose | +|--------|-------|-----------|---------|---------| +| `api.py` | API | 20 | 3 | Unified interface | +| `ast_extractor.py` | L1 | 2 | 6 | Python AST extraction | +| `hybrid_extractor.py` | L1 | 1 | 1 | Multi-language AST | +| `cross_file_calls.py` | L2 | 53 | 2 | Call graph building | +| `cfg_extractor.py` | L3 | 7 | 5 | Control flow graphs | +| `dfg_extractor.py` | L4 | 7 | 7 | Data flow analysis | +| `pdg_extractor.py` | L5 | 6 | 4 | Program dependencies | +| `analysis.py` | Util | 9 | 1 | Impact/dead code | +| `cli.py` | CLI | 1 | 0 | Command-line entry | + +### 10.8 Hook System Structure + +Location: `.claude/hooks/src/` + +| Category | Hooks | Purpose | +|----------|-------|---------| +| Session | 4 | Start/end lifecycle | +| Tool Interception | 8 | Enhance tool behavior | +| Subagent | 4 | Agent coordination | +| Patterns | 2 | Multi-agent orchestration | +| Validation | 3 | Code quality gates | + +**Key Hook Functions:** + +| Hook | Key Functions | +|------|---------------| +| `skill-activation-prompt.ts` | `runPatternInference`, `generateAgenticaOutput` | +| `tldr-context-inject.ts` | `detectIntent`, `getTldrContext`, `extractEntryPoints` | +| `subagent-stop-continuity.ts` | `parseStructuredHandoff`, `createYamlHandoff` | +| `compiler-in-the-loop.ts` | `runLeanCompiler`, `getGoedelSuggestions`, `queryLoogle` | +| `pattern-orchestrator.ts` | `handlePipeline`, `handleJury`, `handleDebate`, `handleGenCritic` | + +--- + +## 11. Summary Statistics + +| Metric | Count | Notes | +|--------|-------|-------| +| Python functions | 2,328 | Across all `opc/scripts/` | +| TypeScript hooks | 34 | Active in `.claude/hooks/src/` | +| Skills | 123 | In `.claude/skills/` | +| Agents | 41 | Defined in system prompt | +| Tests | 265+ | TLDR-code alone | +| Entry layer functions | 1,057 | Called from outside | +| Leaf functions | 729 | Utility/helper code | +| Dead functions | 4 active, 43 archived | Most dead code now in archive/ | +| Circular dependencies | 0 | Resolved by archiving scope modules | +| get_connection callers | 38 | Most called internal function | + +--- + +*This architecture document is generated by TLDR 5-layer analysis. Token cost: ~5,000 (vs ~50,000 raw files = 90% savings).* diff --git a/.auto-doc-history/20260204-025956/README.md b/.auto-doc-history/20260204-025956/README.md new file mode 100644 index 00000000..7d5d90ea --- /dev/null +++ b/.auto-doc-history/20260204-025956/README.md @@ -0,0 +1,1257 @@ +# Continuous Claude + +> A persistent, learning, multi-agent development environment built on Claude Code + +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) +[![Claude Code](https://img.shields.io/badge/Claude-Code-orange.svg)](https://claude.ai/code) +[![Skills](https://img.shields.io/badge/Skills-109-green.svg)](#skills-system) +[![Agents](https://img.shields.io/badge/Agents-32-purple.svg)](#agents-system) +[![Hooks](https://img.shields.io/badge/Hooks-30-blue.svg)](#hooks-system) + +**Continuous Claude** transforms Claude Code into a continuously learning system that maintains context across sessions, orchestrates specialized agents, and eliminates wasting tokens through intelligent code analysis. + +## Table of Contents + +- [Why Continuous Claude?](#why-continuous-claude) +- [Design Principles](#design-principles) +- [How to Talk to Claude](#how-to-talk-to-claude) +- [Quick Start](#quick-start) +- [Architecture](#architecture) +- [Core Systems](#core-systems) + - [Skills (109)](#skills-system) + - [Agents (32)](#agents-system) + - [Hooks (30)](#hooks-system) + - [TLDR Code Analysis](#tldr-code-analysis) + - [Memory System](#memory-system) + - [Continuity System](#continuity-system) + - [Math System](#math-system) +- [Workflows](#workflows) +- [Installation](#installation) +- [Updating](#updating) +- [Configuration](#configuration) +- [Contributing](#contributing) +- [License](#license) + +--- + +## Why Continuous Claude? + +Claude Code has a **compaction problem**: when context fills up, the system compacts your conversation, losing nuanced understanding and decisions made during the session. + +**Continuous Claude solves this with:** + +| Problem | Solution | +|---------|----------| +| Context loss on compaction | YAML handoffs - more token-efficient transfer | +| Starting fresh each session | Memory system recalls + daemon auto-extracts learnings | +| Reading entire files burns tokens | 5-layer code analysis + semantic index | +| Complex tasks need coordination | Meta-skills orchestrate agent workflows | +| Repeating workflows manually | 109 skills with natural language triggers | + +**The mantra: Compound, don't compact.** Extract learnings automatically, then start fresh with full context. + +### Why "Continuous"? Why "Compounding"? + +The name is a pun. **Continuous** because Claude maintains state across sessions. **Compounding** because each session makes the system smarter—learnings accumulate like compound interest. + +--- + +## Design Principles + +An agent is five things: **Prompt + Tools + Context + Memory + Model**. + +| Component | What We Optimize | +|-----------|------------------| +| **Prompt** | Skills inject relevant context; hooks add system reminders | +| **Tools** | TLDR reduces tokens; agents parallelize work | +| **Context** | Not just *what* Claude knows, but *how* it's provided | +| **Memory** | Daemon extracts learnings; recall surfaces them | +| **Model** | Becomes swappable when the other four are solid | + +### Anti-Complexity + +We resist plugin sprawl. Every MCP, subscription, and tool you add promises improvement but risks breaking context, tools, or prompts through clashes. + +**Our approach:** +- **Time, not money** — No required paid services. Perplexity and NIA are optional, high-value-per-token. +- **Learn, don't accumulate** — A system that learns handles edge cases better than one that collects plugins. +- **Shift-left validation** — Hooks run pyright/ruff after edits, catching errors before tests. + +The failure modes of complex systems are structurally invisible until they happen. A learning, context-efficient system doesn't prevent all failures—but it recovers and improves. + +--- + +## How to Talk to Claude + +**You don't need to memorize slash commands.** Just describe what you want naturally. + +### The Skill Activation System + +When you send a message, a hook injects context that tells **Claude** which skills and agents are relevant. Claude infers from a rule-based system and decides which tools to use. + +``` +> "Fix the login bug in auth.py" + +🎯 SKILL ACTIVATION CHECK +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +⚠️ CRITICAL SKILLS (REQUIRED): + → create_handoff + +📚 RECOMMENDED SKILLS: + → fix + → debug + +🤖 RECOMMENDED AGENTS (token-efficient): + → debug-agent + → scout + +ACTION: Use Skill tool BEFORE responding +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +### Priority Levels + +| Level | Meaning | +|-------|---------| +| ⚠️ **CRITICAL** | Must use (e.g., handoffs before ending session) | +| 📚 **RECOMMENDED** | Should use (e.g., workflow skills) | +| 💡 **SUGGESTED** | Consider using (e.g., optimization tools) | +| 📌 **OPTIONAL** | Nice to have (e.g., documentation helpers) | + +### Natural Language Examples + +| What You Say | What Activates | +|--------------|----------------| +| "Fix the broken login" | `/fix` workflow → debug-agent, scout | +| "Build a user dashboard" | `/build` workflow → plan-agent, kraken | +| "I want to understand this codebase" | `/explore` + scout agent | +| "What could go wrong with this plan?" | `/premortem` | +| "Help me figure out what I need" | `/discovery-interview` | +| "Done for today" | `create_handoff` (critical) | +| "Resume where we left off" | `resume_handoff` | +| "Research auth patterns" | oracle agent + perplexity | +| "Find all usages of this API" | scout agent + ast-grep | + +### Why This Approach? + +| Benefit | How | +|---------|-----| +| **More Discoverable** | Don't need to know commands exist | +| **Context-Aware** | System knows when you're 90% through context | +| **Reduces Cognitive Load** | Describe intent naturally, get curated suggestions | +| **Power User Friendly** | Still supports /fix, /build, etc. directly | + +### Skill vs Workflow vs Agent + +| Type | Purpose | Example | +|------|---------|---------| +| **Skill** | Single-purpose tool | `commit`, `tldr-code`, `qlty-check` | +| **Workflow** | Multi-step process | `/fix` (sleuth → premortem → kraken → commit) | +| **Agent** | Specialized sub-session | scout (exploration), oracle (research) | + +[See detailed skill activation docs →](docs/skill-activation.md) + +--- + +## Quick Start + +### Prerequisites + +- Python 3.11+ +- [uv](https://github.com/astral-sh/uv) package manager +- Docker (for PostgreSQL) +- Claude Code CLI + +### Installation + +```bash +# Clone +git clone https://github.com/parcadei/Continuous-Claude-v3.git +cd Continuous-Claude-v3/opc + +# Run setup wizard (12 steps) +uv run python -m scripts.setup.wizard +``` + +> **Note:** The `pyproject.toml` is in `opc/`. Always run `uv` commands from the `opc/` directory. + +### What the Wizard Does + +| Step | What It Does | +|------|--------------| +| 1 | Backup existing .claude/ config (if present) | +| 2 | Check prerequisites (Docker, Python, uv) | +| 3-5 | Database + API key configuration | +| 6-7 | Start Docker stack, run migrations | +| 8 | Install Claude Code integration (32 agents, 109 skills, 30 hooks) | +| 9 | Math features (SymPy, Z3, Pint - optional) | +| 10 | TLDR code analysis tool | +| 11-12 | Diagnostics tools + Loogle (optional) | + +### Remote Database Setup + +By default, CC-v3 runs PostgreSQL locally via Docker. For remote database setups: + +#### 1. Database Preparation + +```bash +# Connect to your remote PostgreSQL instance +psql -h hostname -U user -d continuous_claude + +# Enable pgvector extension (requires superuser or rds_superuser) +CREATE EXTENSION IF NOT EXISTS vector; + +# Apply the schema (from your local clone) +psql -h hostname -U user -d continuous_claude -f docker/init-schema.sql +``` + +> **Managed PostgreSQL tips:** +> - **AWS RDS**: Add `vector` to `shared_preload_libraries` in DB Parameter Group +> - **Supabase**: Enable via Database Extensions page +> - **Azure Database**: Use Extensions pane to enable pgvector + +#### 2. Connection Configuration + +Set `CONTINUOUS_CLAUDE_DB_URL` in `~/.claude/settings.json`: + +```json +{ + "env": { + "CONTINUOUS_CLAUDE_DB_URL": "postgresql://user:password@hostname:5432/continuous_claude" + } +} +``` + +Or export before running Claude: + +```bash +export CONTINUOUS_CLAUDE_DB_URL="postgresql://user:password@hostname:5432/continuous_claude" +claude +``` + +See `.env.example` for all available environment variables. + +### First Session + +```bash +# Start Claude Code +claude + +# Try a workflow +> /workflow +``` + +### First Session Commands + +| Command | What it does | +|---------|--------------| +| `/workflow` | Goal-based routing (Research/Plan/Build/Fix) | +| `/fix bug ` | Investigate and fix a bug | +| `/build greenfield ` | Build a new feature from scratch | +| `/explore` | Understand the codebase | +| `/premortem` | Risk analysis before implementation | + +--- + +## Architecture + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ CONTINUOUS CLAUDE │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ Skills │ │ Agents │ │ Hooks │ │ +│ │ (109) │───▶│ (32) │◀───│ (30) │ │ +│ └─────────────┘ └─────────────┘ └─────────────┘ │ +│ │ │ │ │ +│ ▼ ▼ ▼ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ TLDR Code Analysis │ │ +│ │ L1:AST → L2:CallGraph → L3:CFG → L4:DFG → L5:Slicing │ │ +│ │ (95% token savings) │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ │ │ │ +│ ▼ ▼ ▼ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ Memory │ │ Continuity │ │ Coordination│ │ +│ │ System │ │ Ledgers │ │ Layer │ │ +│ └─────────────┘ └─────────────┘ └─────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +### Data Flow: Session Lifecycle + +``` +SessionStart Working SessionEnd + │ │ │ + ▼ ▼ ▼ +┌─────────┐ ┌─────────┐ ┌─────────┐ +│ Load │ │ Track │ │ Save │ +│ context │─────────────────▶│ changes │──────────────────▶│ state │ +└─────────┘ └─────────┘ └─────────┘ + │ │ │ + ├── Continuity ledger ├── File claims ├── Handoff + ├── Memory recall ├── TLDR indexing ├── Learnings + └── Symbol index └── Blackboard └── Outcome + │ + ▼ + ┌─────────┐ + │ /clear │ + │ Fresh │ + │ context │ + └─────────┘ +``` + +### The Continuity Loop (Detailed) + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ THE CONTINUITY LOOP │ +└─────────────────────────────────────────────────────────────────────────────┘ + + 1. SESSION START 2. WORKING + ┌────────────────────┐ ┌────────────────────┐ + │ │ │ │ + │ Ledger loaded ────┼──▶ Context │ PostToolUse ──────┼──▶ Index handoffs + │ Handoff loaded │ │ UserPrompt ───────┼──▶ Skill hints + │ Memory recalled │ │ Edit tracking ────┼──▶ Dirty flag++ + │ TLDR cache warmed │ │ SubagentStop ─────┼──▶ Agent reports + │ │ │ │ + └────────────────────┘ └────────────────────┘ + │ │ + │ ▼ + │ ┌────────────────────┐ + │ │ 3. PRE-COMPACT │ + │ │ │ + │ │ Auto-handoff ─────┼──▶ thoughts/shared/ + │ │ (YAML format) │ handoffs/*.yaml + │ │ Dirty > 20? ──────┼──▶ TLDR re-index + │ │ │ + │ └────────────────────┘ + │ │ + │ ▼ + │ ┌────────────────────┐ + │ │ 4. SESSION END │ + │ │ │ + │ │ Stale heartbeat ──┼──▶ Daemon wakes + │ │ Daemon spawns ────┼──▶ Headless Claude + │ │ Thinking blocks ──┼──▶ archival_memory + │ │ │ + │ └────────────────────┘ + │ │ + │ │ + └──────────────◀────── /clear ◀──────┘ + Fresh context + state preserved +``` + +### Workflow Chains + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ META-SKILL WORKFLOWS │ +└─────────────────────────────────────────────────────────────────────────────┘ + + /fix bug /build greenfield + ───────── ───────────────── + ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ + │ sleuth │─▶│ premortem│ │discovery │─▶│plan-agent│ + │(diagnose)│ │ (risk) │ │(clarify) │ │ (design) │ + └──────────┘ └────┬─────┘ └──────────┘ └────┬─────┘ + │ │ + ▼ ▼ + ┌──────────┐ ┌──────────┐ + │ kraken │ │ validate │ + │ (fix) │ │ (check) │ + └────┬─────┘ └────┬─────┘ + │ │ + ▼ ▼ + ┌──────────┐ ┌──────────┐ + │ arbiter │ │ kraken │ + │ (test) │ │(implement│ + └────┬─────┘ └────┬─────┘ + │ │ + ▼ ▼ + ┌──────────┐ ┌──────────┐ + │ commit │ │ commit │ + └──────────┘ └──────────┘ + + + /tdd /refactor + ──── ───────── + ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ + │plan-agent│─▶│ arbiter │ │ phoenix │─▶│ warden │ + │ (design) │ │(tests 🔴)│ │(analyze) │ │ (review) │ + └──────────┘ └────┬─────┘ └──────────┘ └────┬─────┘ + │ │ + ▼ ▼ + ┌──────────┐ ┌──────────┐ + │ kraken │ │ kraken │ + │(code 🟢) │ │(transform│ + └────┬─────┘ └────┬─────┘ + │ │ + ▼ ▼ + ┌──────────┐ ┌──────────┐ + │ arbiter │ │ judge │ + │(verify ✓)│ │ (review) │ + └──────────┘ └──────────┘ +``` + +### Data Layer Architecture + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ DATA LAYER ARCHITECTURE │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ TLDR 5-LAYER CODE ANALYSIS SEMANTIC INDEX │ +│ ┌────────────────────────┐ ┌────────────────────────┐ │ +│ │ L1: AST (~500 tok) │ │ BGE-large-en-v1.5 │ │ +│ │ └── Functions, │ │ ├── All 5 layers │ │ +│ │ classes, sigs │ │ ├── 10 lines context │ │ +│ │ │ │ └── FAISS index │ │ +│ │ L2: Call Graph (+440) │ │ │ │ +│ │ └── Cross-file │──────────────│ Query: "auth logic" │ │ +│ │ dependencies │ │ Returns: ranked funcs │ │ +│ │ │ └────────────────────────┘ │ +│ │ L3: CFG (+110 tok) │ │ +│ │ └── Control flow │ │ +│ │ │ MEMORY (PostgreSQL+pgvector) │ +│ │ L4: DFG (+130 tok) │ ┌────────────────────────┐ │ +│ │ └── Data flow │ │ sessions (heartbeat) │ │ +│ │ │ │ file_claims (locks) │ │ +│ │ L5: PDG (+150 tok) │ │ archival_memory (BGE) │ │ +│ │ └── Slicing │ │ handoffs (embeddings) │ │ +│ └────────────────────────┘ └────────────────────────┘ │ +│ ~1,200 tokens │ +│ vs 23,000 raw │ +│ = 95% savings FILE SYSTEM │ +│ ┌────────────────────────┐ │ +│ │ thoughts/ │ │ +│ │ ├── ledgers/ │ │ +│ │ │ └── CONTINUITY_*.md│ │ +│ │ └── shared/ │ │ +│ │ ├── handoffs/*.yaml│ │ +│ │ └── plans/*.md │ │ +│ │ │ │ +│ │ .tldr/ │ │ +│ │ └── (daemon cache) │ │ +│ └────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Core Systems + +### Skills System + +Skills are modular capabilities triggered by natural language. Located in `.claude/skills/`. + +#### Meta-Skills (Workflow Orchestrators) + +| Meta-Skill | Chain | Use When | +|------------|-------|----------| +| `/workflow` | Router → appropriate workflow | Don't know where to start | +| `/build` | discovery → plan → validate → implement → commit | Building features | +| `/fix` | sleuth → premortem → kraken → test → commit | Fixing bugs | +| `/tdd` | plan → arbiter (tests) → kraken (implement) → arbiter | Test-first development | +| `/refactor` | phoenix → plan → kraken → reviewer → arbiter | Safe code transformation | +| `/review` | parallel specialized reviews → synthesis | Code review | +| `/explore` | scout (quick/deep/architecture) | Understand codebase | +| `/security` | vulnerability scan → verification | Security audits | +| `/release` | audit → E2E → review → changelog | Ship releases | + +#### Meta-Skill Reference + +Each meta-skill supports modes, scopes, and flags. Type the skill alone (e.g., `/build`) to get an interactive question flow. + +**`/build [options] [description]`** + +| Mode | Chain | Use For | +|------|-------|---------| +| `greenfield` | discovery → plan → validate → implement → commit → PR | New feature from scratch | +| `brownfield` | onboard → research → plan → validate → implement | Feature in existing codebase | +| `tdd` | plan → test-first → implement | Test-driven development | +| `refactor` | impact analysis → plan → TDD → implement | Safe refactoring | + +| Option | Effect | +|--------|--------| +| `--skip-discovery` | Skip interview phase (have clear spec) | +| `--skip-validate` | Skip plan validation | +| `--skip-commit` | Don't auto-commit | +| `--skip-pr` | Don't create PR description | +| `--parallel` | Run research agents in parallel | + +**`/fix [options] [description]`** + +| Scope | Chain | Use For | +|-------|-------|---------| +| `bug` | debug → implement → test → commit | General bug fix | +| `hook` | debug-hooks → hook-developer → implement → test | Hook issues | +| `deps` | preflight → oracle → plan → implement → qlty | Dependency errors | +| `pr-comments` | github-search → research → plan → implement → commit | PR feedback | + +| Option | Effect | +|--------|--------| +| `--no-test` | Skip regression test | +| `--dry-run` | Diagnose only, don't fix | +| `--no-commit` | Don't auto-commit | + +**`/explore [options]`** + +| Depth | Time | What It Does | +|-------|------|--------------| +| `quick` | ~1 min | tldr tree + structure overview | +| `deep` | ~5 min | onboard + tldr + research + documentation | +| `architecture` | ~3 min | tldr arch + call graph + layers | + +| Option | Effect | +|--------|--------| +| `--focus "area"` | Focus on specific area (e.g., `--focus "auth"`) | +| `--output handoff` | Create handoff for implementation | +| `--output doc` | Create documentation file | +| `--entry "func"` | Start from specific entry point | + +**`/tdd`, `/refactor`, `/review`, `/security`, `/release`** + +These follow their defined chains without mode flags. Just run: +``` +/tdd "implement retry logic" +/refactor "extract auth module" +/review # reviews current changes +/security "authentication code" +/release v1.2.0 +``` + +#### Key Skills (High-Value Tools) + +**Planning & Risk** +- **premortem**: TIGERS & ELEPHANTS risk analysis - use before any significant implementation +- **discovery-interview**: Transform vague ideas into detailed specs + +**Context Management** +- **create_handoff**: Capture session state for transfer +- **resume_handoff**: Resume from handoff with context +- **continuity_ledger**: Track state within session + +**Code Analysis (95% Token Savings)** +- **tldr-code**: Call graph, CFG, DFG, slicing +- **ast-grep-find**: Structural code search +- **morph-search**: Fast text search (20x faster than grep) + +**Research** +- **perplexity-search**: AI-powered web search +- **nia-docs**: Library documentation search +- **github-search**: Search GitHub code/issues/PRs + +**Quality** +- **qlty-check**: 70+ linters, auto-fix +- **braintrust-analyze**: Session analysis, replay, and debugging failed sessions + +**Math & Formal Proofs** +- **math**: Unified computation (SymPy, Z3, Pint) — one entry point for all math +- **prove**: Lean4 theorem proving with 5-phase workflow (Research → Design → Test → Implement → Verify) +- **pint-compute**: Unit-aware arithmetic and conversions +- **shapely-compute**: Computational geometry + +The `/prove` skill enables machine-verified proofs without learning Lean syntax. Used to create the first Lean formalization of Sylvester-Gallai theorem. + +#### The Thought Process + +``` +What do I want to do? +├── Don't know → /workflow (guided router) +├── Building → /build greenfield or brownfield +├── Fixing → /fix bug +├── Understanding → /explore +├── Planning → premortem first, then plan-agent +├── Researching → oracle or perplexity-search +├── Reviewing → /review +├── Proving → /prove (Lean4 formal verification) +├── Computing → /math (SymPy, Z3, Pint) +└── Shipping → /release +``` + +[See detailed skills breakdown →](docs/skills/) + +--- + +### Agents System + +Agents are specialized AI workers spawned via the Task tool. Located in `.claude/agents/`. + +#### Agent Categories (32 active) + +> **Note:** There are likely too many agents—consolidation is a v4 goal. Use what fits your workflow. + +**Orchestrators (2)** +- **maestro**: Multi-agent coordination with patterns (Pipeline, Swarm, Jury) +- **kraken**: TDD implementation agent with checkpoint/resume support + +**Planners (4)** +- **architect**: Feature planning + API integration +- **phoenix**: Refactoring + framework migration planning +- **plan-agent**: Lightweight planning with research/MCP tools +- **validate-agent**: Validate plans against best practices + +**Explorers (4)** +- **scout**: Codebase exploration (use instead of Explore) +- **oracle**: External research (web, docs, APIs) +- **pathfinder**: External repository analysis +- **research-codebase**: Document codebase as-is + +**Implementers (3)** +- **kraken**: TDD implementation with strict test-first workflow +- **spark**: Lightweight fixes and quick tweaks +- **agentica-agent**: Build Python agents using Agentica SDK + +**Debuggers (3)** +- **sleuth**: General bug investigation and root cause +- **debug-agent**: Issue investigation via logs/code search +- **profiler**: Performance profiling and race conditions + +**Validators (2)** - arbiter, atlas + +**Reviewers (6)** - critic, judge, surveyor, liaison, plan-reviewer, review-agent + +**Specialized (8)** - aegis, herald, scribe, chronicler, session-analyst, braintrust-analyst, memory-extractor, onboard + +#### Common Workflows + +| Workflow | Agent Chain | +|----------|-------------| +| Feature | architect → plan-reviewer → kraken → review-agent → arbiter | +| Refactoring | phoenix → plan-reviewer → kraken → judge → arbiter | +| Bug Fix | sleuth → spark/kraken → arbiter → scribe | + +[See detailed agent guide →](docs/agents/) + +--- + +### Hooks System + +Hooks intercept Claude Code at lifecycle points. Located in `.claude/hooks/`. + +#### Hook Events (30 hooks total) + +| Event | Key Hooks | Purpose | +|-------|-----------|---------| +| **SessionStart** | session-start-continuity, session-register, braintrust-tracing | Load context, register session | +| **PreToolUse** | tldr-read-enforcer, smart-search-router, tldr-context-inject, file-claims | Token savings, search routing | +| **PostToolUse** | post-edit-diagnostics, handoff-index, post-edit-notify | Validation, indexing | +| **PreCompact** | pre-compact-continuity | Auto-save before compaction | +| **UserPromptSubmit** | skill-activation-prompt, memory-awareness | Skill hints, memory recall | +| **SubagentStop** | subagent-stop-continuity | Save agent state | +| **SessionEnd** | session-end-cleanup, session-outcome | Cleanup, extract learnings | + +#### Key Hooks + +| Hook | Purpose | +|------|---------| +| **tldr-context-inject** | Adds code analysis to agent prompts | +| **smart-search-router** | Routes grep to AST-grep when appropriate | +| **post-edit-diagnostics** | Runs pyright/ruff after edits | +| **memory-awareness** | Surfaces relevant learnings | + +[See all 30 hooks →](docs/hooks/) + +--- + +### TLDR Code Analysis + +TLDR provides token-efficient code summaries through 5 analysis layers. + +#### The 5-Layer Stack + +| Layer | Name | What it provides | Tokens | +|-------|------|------------------|--------| +| **L1** | AST | Functions, classes, signatures | ~500 tokens | +| **L2** | Call Graph | Who calls what (cross-file) | +440 tokens | +| **L3** | CFG | Control flow, complexity | +110 tokens | +| **L4** | DFG | Data flow, variable tracking | +130 tokens | +| **L5** | PDG | Program slicing, impact analysis | +150 tokens | + +**Total: ~1,200 tokens vs 23,000 raw = 95% savings** + +#### CLI Commands + +```bash +# Structure analysis +tldr tree src/ # File tree +tldr structure src/ --lang python # Code structure (codemaps) + +# Search and extraction +tldr search "process_data" src/ # Find code +tldr context process_data --project src/ --depth 2 # LLM-ready context + +# Flow analysis +tldr cfg src/main.py main # Control flow graph +tldr dfg src/main.py main # Data flow graph +tldr slice src/main.py main 42 # What affects line 42? + +# Codebase analysis +tldr impact process_data src/ # Who calls this function? +tldr dead src/ # Find unreachable code +tldr arch src/ # Detect architectural layers + +# Semantic search (natural language) +tldr daemon semantic "find authentication logic" +``` + +#### Semantic Index + +Beyond structural analysis, TLDR builds a **semantic index** of your codebase: + +- **Natural language queries** — Ask "where is error handling?" instead of grepping +- **Auto-rebuild** — Dirty flag hook tracks file changes; index rebuilds after N edits +- **Selective indexing** — Use `.tldrignore` to control what gets indexed + +```bash +# .tldrignore example +__pycache__/ +*.test.py +node_modules/ +.venv/ +``` + +The semantic index uses all 5 layers plus 10 lines of surrounding code context—not just docstrings. + +#### Hook Integration + +TLDR is automatically integrated via hooks: + +- **tldr-read-enforcer**: Returns L1+L2+L3 instead of full file reads +- **smart-search-router**: Routes Grep to `tldr search` +- **post-tool-use-tracker**: Updates indexes when files change + +[See TLDR documentation →](opc/packages/tldr-code/) + +--- + +### Memory System + +Cross-session learning powered by PostgreSQL + pgvector. + +#### How It Works + +``` +Session ends → Database detects stale heartbeat (>5 min) + → Daemon spawns headless Claude (Sonnet) + → Analyzes thinking blocks from session + → Extracts learnings to archival_memory + → Next session recalls relevant learnings +``` + +The key insight: **thinking blocks contain the real reasoning**—not just what Claude did, but why. The daemon extracts this automatically. + +#### Conversational Interface + +| What You Say | What Happens | +|--------------|--------------| +| "Remember that auth uses JWT" | Stores learning with context | +| "Recall authentication patterns" | Searches memory, surfaces matches | +| "What did we decide about X?" | Implicit recall via memory-awareness hook | + +#### Database Schema (4 tables) + +| Table | Purpose | +|-------|---------| +| **sessions** | Cross-terminal awareness | +| **file_claims** | Cross-terminal file locking | +| **archival_memory** | Long-term learnings with BGE embeddings | +| **handoffs** | Session handoffs with embeddings | + +#### Recall Commands + +```bash +# Recall learnings (hybrid text + vector search) +cd opc && uv run python scripts/core/recall_learnings.py \ + --query "authentication patterns" + +# Store a learning explicitly +cd opc && uv run python scripts/core/store_learning.py \ + --session-id "my-session" \ + --type WORKING_SOLUTION \ + --content "What I learned" \ + --confidence high +``` + +#### Automatic Memory + +The **memory-awareness** hook surfaces relevant learnings when you send a message. You'll see `MEMORY MATCH` indicators—Claude can use these without you asking. + +--- + +### Continuity System + +Preserve state across context clears and sessions. + +#### Continuity Ledger + +Within-session state tracking. Location: `thoughts/ledgers/CONTINUITY_.md` + +```markdown +# Session: feature-x +Updated: 2026-01-08 + +## Goal +Implement feature X with proper error handling + +## Completed +- [x] Designed API schema +- [x] Implemented core logic + +## In Progress +- [ ] Add error handling + +## Blockers +- Need clarification on retry policy +``` + +#### Handoffs + +Between-session knowledge transfer. Location: `thoughts/shared/handoffs//` + +```yaml +--- +date: 2026-01-08T15:26:01+0000 +session_name: feature-x +status: complete +--- + +# Handoff: Feature X Implementation + +## Task(s) +| Task | Status | +|------|--------| +| Design API | Completed | +| Implement core | Completed | +| Error handling | Pending | + +## Next Steps +1. Add retry logic to API calls +2. Write integration tests +``` + +#### Commands + +| Command | Effect | +|---------|--------| +| "save state" | Updates continuity ledger | +| "done for today" / `/handoff` | Creates handoff document | +| "resume work" | Loads latest handoff | + +--- + +### Math System + +Two capabilities: **computation** (SymPy, Z3, Pint) and **formal verification** (Lean4 + Mathlib). + +#### The Stack + +| Tool | Purpose | Example | +|------|---------|---------| +| **SymPy** | Symbolic math | Solve equations, integrals, matrix operations | +| **Z3** | Constraint solving | Prove inequalities, SAT problems | +| **Pint** | Unit conversion | Convert miles to km, dimensional analysis | +| **Lean4** | Formal proofs | Machine-verified theorems | +| **Mathlib** | 100K+ theorems | Pre-formalized lemmas to build on | +| **Loogle** | Type-aware search | Find Mathlib lemmas by signature | + +#### Two Entry Points + +| Skill | Use When | +|-------|----------| +| `/math` | Computing, solving, calculating | +| `/prove` | Formal verification, machine-checked proofs | + +#### /math Examples + +```bash +# Solve equation +"Solve x² - 4 = 0" → x = ±2 + +# Compute eigenvalues +"Eigenvalues of [[2,1],[1,2]]" → {1: 1, 3: 1} + +# Prove inequality +"Is x² + y² ≥ 2xy always true?" → PROVED (equals (x-y)²) + +# Convert units +"26.2 miles to km" → 42.16 km +``` + +#### /prove - Formal Verification + +5-phase workflow for machine-verified proofs: + +``` +📚 RESEARCH → 🏗️ DESIGN → 🧪 TEST → ⚙️ IMPLEMENT → ✅ VERIFY +``` + +1. **Research**: Search Mathlib with Loogle, find proof strategy +2. **Design**: Create skeleton with `sorry` placeholders +3. **Test**: Search for counterexamples before proving +4. **Implement**: Fill sorries with compiler-in-the-loop feedback +5. **Verify**: Audit axioms, confirm zero sorries + +``` +/prove every group homomorphism preserves identity +/prove continuous functions on compact sets are uniformly continuous +``` + +**Achievement**: Used to create the first Lean formalization of the Sylvester-Gallai theorem. + +#### Prerequisites (Optional) + +Math features require installation via wizard step 9: + +```bash +# Installed automatically by wizard +uv pip install sympy z3-solver pint shapely + +# Lean4 (for /prove) +curl https://raw.githubusercontent.com/leanprover/elan/master/elan-init.sh -sSf | sh +``` + +--- + +## Workflows + +### /workflow - Goal-Based Router + +``` +> /workflow + +? What's your goal? + ○ Research - Understand codebase/docs + ○ Plan - Design implementation approach + ○ Build - Implement features + ○ Fix - Investigate and resolve issues +``` + +### /fix - Bug Resolution + +```bash +/fix bug "login fails silently" +``` + +**Chain:** sleuth → [checkpoint] → [premortem] → kraken → test → commit + +| Scope | What it does | +|-------|--------------| +| `bug` | General bug investigation | +| `hook` | Hook-specific debugging | +| `deps` | Dependency issues | +| `pr-comments` | Address PR feedback | + +### /build - Feature Development + +```bash +/build greenfield "user dashboard" +``` + +**Chain:** discovery → plan → validate → implement → commit → PR + +| Mode | What it does | +|------|--------------| +| `greenfield` | New feature from scratch | +| `brownfield` | Modify existing codebase | +| `tdd` | Test-first development | +| `refactor` | Safe code transformation | + +### /premortem - Risk Analysis + +```bash +/premortem deep thoughts/shared/plans/feature-x.md +``` + +**Output:** +- **TIGERS**: Clear threats (HIGH/MEDIUM/LOW severity) +- **ELEPHANTS**: Unspoken concerns + +Blocks on HIGH severity until user accepts/mitigates risks. + +--- + +## Installation + +### Full Installation (Recommended) + +```bash +# Clone +git clone https://github.com/parcadei/continuous-claude.git +cd continuous-claude/opc + +# Run the setup wizard +uv run python -m scripts.setup.wizard +``` + +The wizard walks you through all configuration options interactively. + +## Updating + +Pull latest changes and sync your installation: + +```bash +cd continuous-claude/opc +uv run python -m scripts.setup.update +``` + +This will: +- Pull latest from GitHub +- Update hooks, skills, rules, agents +- Upgrade TLDR if installed +- Rebuild TypeScript hooks if changed + +### What Gets Installed + +| Component | Location | +|-----------|----------| +| Agents (32) | ~/.claude/agents/ | +| Skills (109) | ~/.claude/skills/ | +| Hooks (30) | ~/.claude/hooks/ | +| Rules | ~/.claude/rules/ | +| Scripts | ~/.claude/scripts/ | +| PostgreSQL | Docker container | + +### Installation Mode: Copy vs Symlink + +The wizard offers two installation modes: + +| Mode | How It Works | Best For | +|------|--------------|----------| +| **Copy** (default) | Copies files from repo to `~/.claude/` | End users, stable setup | +| **Symlink** | Creates symlinks to repo files | Contributors, development | + +#### Copy Mode (Default) + +Files are copied from `continuous-claude/.claude/` to `~/.claude/`. Changes you make in `~/.claude/` are **local only** and will be overwritten on next update. + +```text +continuous-claude/.claude/ ──COPY──> ~/.claude/ + (source) (user config) +``` + +**Pros:** Stable, isolated from repo changes +**Cons:** Local changes lost on update, manual sync needed + +#### Symlink Mode (Recommended for Contributors) + +Creates symlinks so `~/.claude/` points directly to repo files. Changes in either location affect the same files. + +```text +~/.claude/rules ──SYMLINK──> continuous-claude/.claude/rules +~/.claude/skills ──SYMLINK──> continuous-claude/.claude/skills +~/.claude/hooks ──SYMLINK──> continuous-claude/.claude/hooks +~/.claude/agents ──SYMLINK──> continuous-claude/.claude/agents +``` + +**Pros:** +- Changes auto-sync to repo (can `git commit` improvements) +- No re-installation needed after `git pull` +- Contribute back easily + +**Cons:** +- Breaking changes in repo affect your setup immediately +- Need to manage git workflow + +#### Switching to Symlink Mode + +If you installed with copy mode and want to switch: + +```bash +# Backup current config +mkdir -p ~/.claude/backups/$(date +%Y%m%d) +cp -r ~/.claude/{rules,skills,hooks,agents} ~/.claude/backups/$(date +%Y%m%d)/ + +# Verify backup succeeded before proceeding +ls -la ~/.claude/backups/$(date +%Y%m%d)/ + +# Remove copies (only after verifying backup above) +rm -rf ~/.claude/{rules,skills,hooks,agents} + +# Create symlinks (adjust path to your repo location) +REPO="$HOME/continuous-claude" # or wherever you cloned +ln -s "$REPO/.claude/rules" ~/.claude/rules +ln -s "$REPO/.claude/skills" ~/.claude/skills +ln -s "$REPO/.claude/hooks" ~/.claude/hooks +ln -s "$REPO/.claude/agents" ~/.claude/agents + +# Verify +ls -la ~/.claude | grep -E "rules|skills|hooks|agents" +``` + +**Windows users:** Use PowerShell (as Administrator or with Developer Mode enabled): + +```powershell +# Enable Developer Mode first (Settings → Privacy & security → For developers) +# Or run PowerShell as Administrator + +# Backup current config +$BackupDir = "$HOME\.claude\backups\$(Get-Date -Format 'yyyyMMdd')" +New-Item -ItemType Directory -Path $BackupDir -Force +Copy-Item -Recurse "$HOME\.claude\rules","$HOME\.claude\skills","$HOME\.claude\hooks","$HOME\.claude\agents" $BackupDir + +# Verify backup succeeded before proceeding +Get-ChildItem $BackupDir + +# Remove copies (only after verifying backup above) +Remove-Item -Recurse "$HOME\.claude\rules","$HOME\.claude\skills","$HOME\.claude\hooks","$HOME\.claude\agents" + +# Create symlinks (adjust path to your repo location) +$REPO = "$HOME\continuous-claude" # or wherever you cloned +New-Item -ItemType SymbolicLink -Path "$HOME\.claude\rules" -Target "$REPO\.claude\rules" +New-Item -ItemType SymbolicLink -Path "$HOME\.claude\skills" -Target "$REPO\.claude\skills" +New-Item -ItemType SymbolicLink -Path "$HOME\.claude\hooks" -Target "$REPO\.claude\hooks" +New-Item -ItemType SymbolicLink -Path "$HOME\.claude\agents" -Target "$REPO\.claude\agents" + +# Verify +Get-ChildItem "$HOME\.claude" | Where-Object { $_.LinkType -eq "SymbolicLink" } +``` + +### For Brownfield Projects + +After installation, start Claude and run: +``` +> /onboard +``` + +This analyzes the codebase and creates an initial continuity ledger. + +--- + +## Configuration + +### .claude/settings.json + +Central configuration for hooks, tools, and workflows. + +```json +{ + "hooks": { + "SessionStart": [...], + "PreToolUse": [...], + "PostToolUse": [...], + "UserPromptSubmit": [...] + } +} +``` + +### .claude/skills/skill-rules.json + +Skill activation triggers. + +```json +{ + "rules": [ + { + "skill": "fix", + "keywords": ["fix this", "broken", "not working"], + "intentPatterns": ["fix.*(bug|issue|error)"] + } + ] +} +``` + +### Environment Variables + +| Variable | Purpose | Required | +|----------|---------|----------| +| `DATABASE_URL` | PostgreSQL connection string | Yes | +| `BRAINTRUST_API_KEY` | Session tracing | No | +| `PERPLEXITY_API_KEY` | Web search | No | +| `NIA_API_KEY` | Documentation search | No | +| `CLAUDE_OPC_DIR` | Path to CC's opc/ directory (set by wizard) | Auto | +| `CLAUDE_PROJECT_DIR` | Current project directory (set by SessionStart hook) | Auto | + +Services without API keys still work: +- Continuity system (ledgers, handoffs) +- TLDR code analysis +- Local git operations +- TDD workflow + +--- + +## Directory Structure + +``` +continuous-claude/ +├── .claude/ +│ ├── agents/ # 32 specialized AI agents +│ ├── hooks/ # 30 lifecycle hooks +│ │ ├── src/ # TypeScript source +│ │ └── dist/ # Compiled JavaScript +│ ├── skills/ # 109 modular capabilities +│ ├── rules/ # System policies +│ ├── scripts/ # Python utilities +│ └── settings.json # Hook configuration +├── opc/ +│ ├── packages/ +│ │ └── tldr-code/ # 5-layer code analysis +│ ├── scripts/ +│ │ ├── setup/ # Wizard, Docker, integration +│ │ └── core/ # recall_learnings, store_learning +│ └── docker/ +│ └── init-schema.sql # 4-table PostgreSQL schema +├── thoughts/ +│ ├── ledgers/ # Continuity ledgers (CONTINUITY_*.md) +│ └── shared/ +│ ├── handoffs/ # Session handoffs (*.yaml) +│ └── plans/ # Implementation plans +└── docs/ # Documentation +``` + +--- + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on: + +- Adding new skills +- Creating agents +- Developing hooks +- Extending TLDR + +--- + +## Acknowledgments + +### Patterns & Architecture +- **[@numman-ali](https://github.com/numman-ali)** - Continuity ledger pattern +- **[Anthropic](https://anthropic.com)** - Claude Code and "Code Execution with MCP" +- **[obra/superpowers](https://github.com/obra/superpowers)** - Agent orchestration patterns +- **[EveryInc/compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin)** - Compound engineering workflow +- **[yoloshii/mcp-code-execution-enhanced](https://github.com/yoloshii/mcp-code-execution-enhanced)** - Enhanced MCP execution +- **[HumanLayer](https://github.com/humanlayer/humanlayer)** - Agent patterns + +### Tools & Services +- **[uv](https://github.com/astral-sh/uv)** - Python packaging +- **[tree-sitter](https://tree-sitter.github.io/)** - Code parsing +- **[Braintrust](https://braintrust.dev)** - LLM evaluation, logging, and session tracing +- **[qlty](https://github.com/qltysh/qlty)** - Universal code quality CLI (70+ linters) +- **[ast-grep](https://github.com/ast-grep/ast-grep)** - AST-based code search and refactoring +- **[Nia](https://trynia.ai)** - Library documentation search +- **[Morph](https://www.morphllm.com)** - WarpGrep fast code search +- **[Firecrawl](https://www.firecrawl.dev)** - Web scraping API +- **[RepoPrompt](https://repoprompt.com)** - Token-efficient codebase maps + +--- + +## Star History + +[![Star History Chart](https://api.star-history.com/svg?repos=parcadei/Continuous-Claude-v2&type=timeline)](https://star-history.com/#parcadei/Continuous-Claude-v2&Date) + +--- + +## License + +[MIT](LICENSE) - Use freely, contribute back. + +--- + +**Continuous Claude**: Not just a coding assistant—a persistent, learning, multi-agent development environment that gets smarter with every session. diff --git a/.auto-doc-history/20260205-023154/ARCHITECTURE.md b/.auto-doc-history/20260205-023154/ARCHITECTURE.md new file mode 100644 index 00000000..ae9c2c10 --- /dev/null +++ b/.auto-doc-history/20260205-023154/ARCHITECTURE.md @@ -0,0 +1,812 @@ +# Continuous Claude v3 - Architecture Guide + +## Executive Summary + +Continuous Claude v3 is an **agentic AI development environment** built on top of Claude Code. It transforms a single AI assistant into a coordinated system of specialized agents, with automatic context management, semantic memory, and token-efficient code analysis. Think of it as "VS Code + GitHub Copilot, but the AI can delegate to specialist AIs, remember past sessions, and understand code at the AST level." + +The system has four main layers: **Skills** (what users can trigger), **Hooks** (automatic behaviors), **Agents** (specialized sub-assistants), and **Infrastructure** (persistence and analysis tools). + +--- + +## Architecture Diagram + +``` ++-----------------------------------------------------------------------------------+ +| USER INTERACTION | +| "help me understand authentication" | "implement feature X" | "debug this bug" | ++-----------------------------------------------------------------------------------+ + | + v ++-----------------------------------------------------------------------------------+ +| SKILL ACTIVATION LAYER | +| skill-rules.json -> keyword/intent matching -> skill suggestion/injection | ++-----------------------------------------------------------------------------------+ + | + v ++-----------------------------------------------------------------------------------+ +| HOOK LAYER | +| | +| +-------------+ +---------------+ +--------------+ +----------------+ | +| | SessionStart| | UserPrompt | | PreToolUse | | PostToolUse | | +| | - Continuity| | - Skill inject| | - Search rtr | | - Compiler | | +| | - Indexing | | - Braintrust | | - TLDR inject| | - Handoff idx | | +| +-------------+ +---------------+ +--------------+ +----------------+ | +| | +| +-------------+ +---------------+ +--------------+ +----------------+ | +| | SubagentSt | | SubagentStop | | Stop | | SessionEnd | | +| | - Register | | - Continuity | | - Coordinator| | - Cleanup | | +| +-------------+ +---------------+ +--------------+ +----------------+ | ++-----------------------------------------------------------------------------------+ + | + v ++-----------------------------------------------------------------------------------+ +| AGENT LAYER (32 agents) | +| | +| ORCHESTRATORS IMPLEMENTERS EXPLORERS REVIEWERS | +| +----------+ +----------+ +----------+ +----------+ | +| | maestro | | kraken | | scout | | critic | | +| | (opus) | | (opus) | | (sonnet) | | (sonnet) | | +| | multi-ag | | TDD impl | | codebase | | code | | +| +----------+ +----------+ +----------+ +----------+ | +| | +| PLANNERS DEBUGGERS VALIDATORS SPECIALIZED | +| +----------+ +----------+ +----------+ +----------+ | +| | architect| | sleuth | | arbiter | | aegis | | +| | (opus) | | (opus) | | (opus) | | security | | +| | design | | debug | | testing | +----------+ | +| +----------+ +----------+ +----------+ | phoenix | | +| | refactor | | +| +----------+ | ++-----------------------------------------------------------------------------------+ + | + v ++-----------------------------------------------------------------------------------+ +| INFRASTRUCTURE LAYER | +| | +| +-------------------+ +-------------------+ +-------------------+ | +| | TLDR-Code 5-Layer | | PostgreSQL+pgvec | | File Persistence | | +| | - AST (structure) | | - sessions | | - thoughts/shared | | +| | - Call Graph | | - file_claims | | - handoffs/ | | +| | - CFG (control) | | - archival_memory | | - plans/ | | +| | - DFG (data flow) | | - handoffs | | - ledgers/ | | +| | - PDG (deps) | | | | - .claude/cache/ | | +| +-------------------+ +-------------------+ +-------------------+ | +| | +| +-------------------+ +-------------------+ +-------------------+ | +| | Symbol Index | | Artifact Index | | MCP Servers | | +| | /tmp/claude- | | (SQLite FTS5) | | - Firecrawl | | +| | symbol-index/ | | - handoffs | | - Perplexity | | +| | symbols.json | | - plans | | - GitHub | | +| | callers.json | | - continuity | | - AST-grep | | +| +-------------------+ +-------------------+ +-------------------+ | ++-----------------------------------------------------------------------------------+ +``` + +--- + +## 1. Capability Catalog (What Users Can Do) + +Users activate capabilities through **natural language keywords**. No slash commands needed - the system detects intent. + +### Planning & Workflow + +| Capability | Trigger Keywords | What It Does | +|------------|-----------------|--------------| +| **Create Plan** | "create plan", "plan feature", "design" | Architect agent creates phased implementation plan | +| **Implement Plan** | "implement plan", "execute plan", "follow plan" | Kraken agent executes plan with TDD | +| **Create Handoff** | "create handoff", "done for today", "wrap up" | Saves session state for future pickup | +| **Resume Handoff** | "resume handoff", "continue work", "pick up where" | Restores context from previous session | +| **Continuity Ledger** | "save state", "before compact", "low on context" | Creates checkpoint within session | + +### Code Understanding (TLDR-Code) + +| Capability | Trigger Keywords | What It Does | +|------------|-----------------|--------------| +| **Call Graph** | "what calls", "who calls", "calls what" | Shows function call relationships | +| **Complexity Analysis** | "how complex", "cyclomatic" | CFG-based complexity metrics | +| **Data Flow** | "where does variable", "what sets" | Tracks variable origins and uses | +| **Program Slicing** | "what affects line", "dependencies" | PDG-based impact analysis | + +### Search & Research + +| Capability | Trigger Keywords | What It Does | +|------------|-----------------|--------------| +| **Semantic Search** | "recall", "what worked", "past decisions" | Searches archival memory with embeddings | +| **Structural Search** | "ast", "find all calls", "refactor" | AST-grep for code patterns | +| **Text Search** | "grep", "find in code", "search for" | Fast text search via Morph/Grep | +| **Web Research** | "search the web", "look up", "perplexity" | AI-powered web search | +| **Documentation** | "docs", "how to use", "API reference" | Library docs via Nia | + +### Code Quality + +| Capability | Trigger Keywords | What It Does | +|------------|-----------------|--------------| +| **Quality Check** | "lint", "code quality", "auto-fix" | Qlty CLI with 70+ linters | +| **TDD Workflow** | "implement", "add feature", "fix bug" | Forces test-first development | +| **Debug** | "debug", "investigate", "why is it" | Spawns debug-agent for investigation | + +### Git & GitHub + +| Capability | Trigger Keywords | What It Does | +|------------|-----------------|--------------| +| **Commit** | "commit", "save changes", "push" | Git commit with user approval | +| **PR Description** | "describe pr", "create pr" | Generates PR description from changes | +| **GitHub Search** | "github", "search repo", "PR" | Searches GitHub via MCP | + +### Math & Computation + +| Capability | Trigger Keywords | What It Does | +|------------|-----------------|--------------| +| **Math Computation** | "calculate", "solve", "integrate" | SymPy, Z3, Pint computation | +| **Formal Proofs** | "prove", "theorem", "verify" | Lean 4 + Godel-Prover | + +--- + +## 2. Hook Layer (Automatic Behaviors) + +Hooks fire automatically at specific lifecycle points. Users don't invoke them directly - they just work. + +### PreToolUse Hooks + +| Hook | Triggers On | What It Does | +|------|-------------|--------------| +| `path-rules` | Read, Edit, Write | Enforces file access patterns | +| `tldr-read-enforcer` | Read | Intercepts file reads, offers TLDR context instead | +| `smart-search-router` | Grep | Routes to AST-grep/LEANN/Grep based on query type | +| `tldr-context-inject` | Task | Adds code context to subagent prompts | +| `file-claims` | Edit | Tracks which session owns which files | +| `pre-edit-context` | Edit | Injects context before edits | + +### PostToolUse Hooks + +| Hook | Triggers On | What It Does | +|------|-------------|--------------| +| `pattern-orchestrator` | Task | Manages multi-agent patterns (pipeline, jury, debate) | +| `typescript-preflight` | Edit, Write | Runs TypeScript compiler check | +| `handoff-index` | Write | Indexes handoff documents for search | +| `compiler-in-the-loop` | Write | Validates code changes compile | +| `import-validator` | Edit, Write | Checks import statements are valid | + +### Session Lifecycle Hooks + +| Hook | Fires When | What It Does | +|------|------------|--------------| +| `session-register` | SessionStart | Registers session in coordination layer | +| `session-start-continuity` | Resume/Compact | Restores continuity ledger | +| `skill-activation-prompt` | UserPromptSubmit | Suggests relevant skills | +| `subagent-start` | SubagentStart | Registers subagent spawn | +| `subagent-stop-continuity` | SubagentStop | Saves subagent state | +| `stop-coordinator` | Stop | Handles graceful shutdown | +| `session-end-cleanup` | SessionEnd | Cleanup and final state save | + +--- + +## 3. Agent Layer + +32 specialized agents, each with a defined role, model preference, and tool access. + +### Orchestration Agents + +| Agent | Model | Purpose | +|-------|-------|---------| +| **maestro** | opus | Multi-agent coordination, pattern selection | +| **kraken** | opus | TDD implementation, checkpointing, resumable work | + +### Planning Agents + +| Agent | Model | Purpose | +|-------|-------|---------| +| **architect** | opus | Feature design, interface planning, integration design | +| **phoenix** | opus | Refactoring plans, tech debt analysis | +| **pioneer** | opus | Migration planning, framework upgrades | + +### Exploration Agents + +| Agent | Model | Purpose | +|-------|-------|---------| +| **scout** | sonnet | Codebase exploration, pattern finding | +| **oracle** | opus | External research (web, docs) | +| **pathfinder** | sonnet | Navigation, file location | + +### Implementation Agents + +| Agent | Model | Purpose | +|-------|-------|---------| +| **spark** | sonnet | Quick fixes, small changes | +| **kraken** | opus | Full TDD implementation | + +### Debugging Agents + +| Agent | Model | Purpose | +|-------|-------|---------| +| **sleuth** | opus | Debug investigation, root cause analysis | +| **profiler** | opus | Performance analysis | + +### Validation Agents + +| Agent | Model | Purpose | +|-------|-------|---------| +| **arbiter** | opus | Unit/integration testing | +| **atlas** | opus | E2E testing | +| **validator** | sonnet | Plan validation against precedent | + +### Review Agents + +| Agent | Model | Purpose | +|-------|-------|---------| +| **critic** | sonnet | Code review | +| **judge** | sonnet | Refactor review | +| **warden** | sonnet | Security review | +| **surveyor** | sonnet | Migration completeness | + +### Specialized Agents + +| Agent | Model | Purpose | +|-------|-------|---------| +| **aegis** | opus | Security analysis, vulnerability scanning | +| **herald** | sonnet | Release preparation, changelog | +| **scribe** | sonnet | Documentation generation | +| **liaison** | sonnet | Integration/API quality review | + +### Agent Output Location + +All agents write their output to: +``` +.claude/cache/agents//latest-output.md +``` + +--- + +## 4. Infrastructure Layer + +### TLDR-Code (5-Layer Code Analysis) + +**Install:** `uv tool install llm-tldr` | **Source:** [github.com/parcadei/tldr-code](https://github.com/parcadei/tldr-code) + +A token-efficient code understanding system that provides 85% token savings compared to raw file reads. + +| Layer | Extractor | What It Provides | +|-------|-----------|------------------| +| **L1: AST** | `ast_extractor.py` | Functions, classes, imports, structure | +| **L2: Call Graph** | `hybrid_extractor.py`, `cross_file_calls.py` | What calls what, cross-file dependencies | +| **L3: CFG** | `cfg_extractor.py` | Control flow, cyclomatic complexity | +| **L4: DFG** | `dfg_extractor.py` | Variable definitions and uses, data flow | +| **L5: PDG** | `pdg_extractor.py` | Program dependencies, backward/forward slicing | + +**Supported Languages:** Python, TypeScript, Go, Rust + +**API Entry Point:** `tldr/api.py` +```python +from tldr.api import get_relevant_context, query, get_slice +``` + +### PostgreSQL + pgvector + +Schema in `docker/init-schema.sql` + +| Table | Purpose | +|-------|---------| +| `sessions` | Cross-terminal awareness and coordination | +| `file_claims` | Cross-terminal file locking | +| `archival_memory` | Long-term learnings with vector embeddings | +| `handoffs` | Session handoffs with embeddings | + +**Features:** +- Semantic search via pgvector embeddings (1024-dim BGE) +- Hybrid RRF search (text + vector combined) +- Cross-session coordination + +### Artifact Index (SQLite FTS5) + +Schema: `opc/scripts/artifact_schema.sql` +Location: `.claude/cache/context-graph/context.db` + +| Table | Indexed Content | +|-------|-----------------| +| `handoffs` | Task summary, what worked/failed, key decisions | +| `plans` | Title, overview, approach, phases | +| `continuity` | Goal, state, learnings | +| `queries` | Q&A pairs for compound learning | + +**Features:** +- Full-text search with porter stemming +- BM25 ranking with column weights +- Automatic FTS sync via triggers + +### File-Based Persistence + +``` +thoughts/ + shared/ + handoffs/ # Session handoff documents (YAML) + / + current.md # Active handoff + *.yaml # Historical handoffs + plans/ # Implementation plans + ledgers/ # Continuity snapshots + experiments/ # A/B tests, comparisons + skill-builds/ # Skill development iterations + +.claude/ + cache/ + agents/ # Agent outputs + /latest-output.md + patterns/ # Multi-agent pattern state + pipeline-*.json + jury-*.json + context-graph/ # SQLite artifact index + hooks/src/ # Hook implementations + skills/ # Skill definitions + agents/ # Agent definitions +``` + +### Symbol Index + +Location: `/tmp/claude-symbol-index/` + +| File | Content | +|------|---------| +| `symbols.json` | Function/class definitions with location | +| `callers.json` | Who calls each function | + +Built by `build_symbol_index.py` on SessionStart. + +--- + +## 5. Key Python Scripts + +### Entry Points (User-Callable) + +| Script | Purpose | +|--------|---------| +| `recall_learnings.py` | Semantic search of archival memory | +| `store_learning.py` | Store a new learning | +| `observe_agents.py` | Query running agent state | +| `braintrust_analyze.py` | Analyze session logs | +| `artifact_query.py` | Search artifact index | + +### Background Services + +| Script | Purpose | +|--------|---------| +| `build_symbol_index.py` | Builds symbol index on session start | +| `index_incremental.py` | Incremental artifact indexing | + +### Computation Backends + +| Script | Purpose | +|--------|---------| +| `sympy_compute.py` | Symbolic math | +| `z3_solve.py` | Constraint solving | +| `pint_compute.py` | Unit conversions | +| `math_router.py` | Routes math queries to backends | + +### Hook Launcher + +`hook_launcher.py` - Central dispatcher that compiles and runs TypeScript hooks via the `tsc-cache/` directory. + +--- + +## 6. Data Flow Diagrams + +### User Request Flow + +``` +User: "debug the authentication bug" + | + v ++-------------------+ +| UserPromptSubmit | skill-activation-prompt hook fires ++-------------------+ + | + v (skill suggested: debug-agent) ++-------------------+ +| Task Tool | spawns debug-agent ++-------------------+ + | + v ++-------------------+ +| PreToolUse:Task | tldr-context-inject adds code context ++-------------------+ + | + v ++-------------------+ +| debug-agent runs | uses TLDR-code, searches codebase ++-------------------+ + | + v ++-------------------+ +| PostToolUse:Task | pattern-orchestrator checks completion ++-------------------+ + | + v ++-------------------+ +| Agent Output | .claude/cache/agents/debug-agent/latest-output.md ++-------------------+ +``` + +### Code Context Injection Flow + +``` +Claude wants to Read file.py + | + v ++-------------------+ +| PreToolUse:Read | tldr-read-enforcer fires ++-------------------+ + | + v (blocks read, suggests TLDR) ++-------------------+ +| TLDR Analysis | +| L1: AST extract | +| L2: Call graph | +| L3: CFG (if func) | ++-------------------+ + | + v ++-------------------+ +| Context Returned | 95% fewer tokens than raw file ++-------------------+ +``` + +### Search Routing Flow + +``` +Claude calls Grep("validateToken") + | + v ++-------------------+ +| PreToolUse:Grep | smart-search-router fires ++-------------------+ + | + v (detects: structural query about function) ++-------------------+ +| Route Decision | +| - Structural? -> AST-grep +| - Semantic? -> LEANN/Embeddings +| - Literal? -> Grep (pass through) ++-------------------+ + | + v (this is structural) ++-------------------+ +| Redirect to | uses AST-grep for function references +| AST-grep | ++-------------------+ +``` + +--- + +## 7. Key Files Reference + +### Configuration + +| File | Purpose | +|------|---------| +| `.claude/settings.json` | Hook registration, tool configuration | +| `.claude/skills/skill-rules.json` | Skill triggers and keywords | +| `opc/pyproject.toml` | Python dependencies | + +### Hook Implementations + +| File | Purpose | +|------|---------| +| `.claude/hooks/src/smart-search-router.ts` | Routes searches to best tool | +| `.claude/hooks/src/tldr-context-inject.ts` | Adds TLDR context to agents | +| `.claude/hooks/src/pattern-orchestrator.ts` | Multi-agent pattern management | +| `.claude/hooks/src/session-start-continuity.ts` | Restores session state | +| `.claude/hooks/src/handoff-index.ts` | Indexes handoff documents | + +### Agent Definitions + +| File | Purpose | +|------|---------| +| `.claude/agents/kraken.md` | TDD implementation agent | +| `.claude/agents/maestro.md` | Multi-agent orchestrator | +| `.claude/agents/architect.md` | Feature planning agent | +| `.claude/agents/scout.md` | Codebase exploration | + +### Core Libraries + +| File | Purpose | +|------|---------| +| `tldr/api.py` (llm-tldr package) | TLDR-Code public API | +| `opc/scripts/temporal_memory/store_pg.py` | Temporal memory PostgreSQL store | +| `opc/scripts/artifact_index.py` | Artifact index management | + +--- + +## 8. Getting Started + +### For Users + +1. **Ask naturally** - "help me understand the auth system" triggers appropriate skills/agents +2. **Create plans first** - "create a plan for feature X" before implementing +3. **Use handoffs** - "create handoff" when stopping, "resume handoff" when returning +4. **Trust the routing** - the system picks the right tool (TLDR vs Grep vs AST-grep) + +### For Developers + +1. **Add skills** in `.claude/skills//SKILL.md` +2. **Register triggers** in `.claude/skills/skill-rules.json` +3. **Add hooks** in `.claude/hooks/src/*.ts`, register in `.claude/settings.json` +4. **Add agents** in `.claude/agents/.md` + +### Key Invariants + +- **Agents write to files, not stdout** - all agent output goes to `.claude/cache/agents/` +- **Hooks are fast** - timeouts are 5-60 seconds +- **Memory is semantic** - use embeddings for recall, not exact match +- **TDD is enforced** - implementation agents write tests first +- **Context is precious** - TLDR saves 85% tokens + +--- + +## 9. Glossary + +| Term | Meaning | +|------|---------| +| **Skill** | A capability triggered by keywords in user input | +| **Hook** | Automatic behavior at lifecycle points (PreToolUse, etc.) | +| **Agent** | Specialized sub-assistant spawned via Task tool | +| **TLDR-Code** | Token-efficient code analysis (5 layers) | +| **Handoff** | Document transferring state between sessions | +| **Continuity Ledger** | Checkpoint within a session | +| **Artifact Index** | Full-text searchable index of past work | +| **Temporal Fact** | Fact that evolves over turns (e.g., "current goal") | +| **Pattern** | Multi-agent coordination (pipeline, jury, debate, gencritic) | + +--- + +## 10. TLDR 5-Layer Analysis Results + +> Generated via `tldr arch`, `tldr calls`, `tldr dead`, `tldr cfg`, `tldr dfg` + +### 10.1 Architectural Layer Detection (L2: Call Graph) + +TLDR detected 3 architectural layers based on call patterns: + +#### Entry Layer (Controllers/Handlers) +Files that are called from outside but rarely call other internal code. + +| Directory | Calls Out | Calls In | Functions | Inferred Layer | +|-----------|-----------|----------|-----------|----------------| +| `scripts/` (root) | 21 | 3 | 1,232 | HIGH (entry) | +| `archive/` | 66 | 6 | 590+ | HIGH (entry, dead code) | +| `temporal_memory/` | 13 | 1 | 55 | HIGH (entry) | + +#### Service Layer (Business Logic) +Files that mediate between entry and data layers. + +| Directory | Calls Out | Calls In | Functions | Inferred Layer | +|-----------|-----------|----------|-----------|----------------| +| `monitors/` | 1 | 0 | 25 | MIDDLE (service) | + +#### Data Layer (Utilities) +Files that provide primitive operations, rarely call other code. + +| Directory | Calls Out | Calls In | Functions | Inferred Layer | +|-----------|-----------|----------|-----------|----------------| +| `agentica_patterns/` | 4 | 116 | 251 | LOW (utility) | +| `setup/` | 0 | 4 | 67 | LOW (utility) | +| `sacred_tui/` | 0 | 2 | 11 | LOW (utility) | +| `security/` | 0 | 0 | 4 | LOW (utility) | + +### 10.2 Cross-File Call Graph (Key Edges) + +Selected high-impact call relationships: + +``` +math_router.py + → sympy_compute.py:safe_parse + → numpy_compute.py:cmd_* + → scipy_compute.py:cmd_* + → mpmath_compute.py:cmd_* + +temporal_memory/store_pg.py + → postgres_pool.py:get_connection + → postgres_pool.py:init_pgvector + +memory_service_pg.py + → postgres_pool.py:get_connection (38 callers total) + → embedding_service.py:embed + +braintrust_hooks.py + → session_start → get_project_id + → session_start → get_session_value + → log → ensure_dirs +``` + +#### Most Called Functions (Impact Analysis) + +| Function | File | Caller Count | Description | +|----------|------|--------------|-------------| +| `get_connection` | `postgres_pool.py` | 38 | Central DB connection pool | +| `math_command` | `math_base.py` | 50+ | Math computation wrapper | +| `parse_array` | `math_base.py` | 30+ | Array parsing for numpy | +| `parse_matrix` | `math_base.py` | 20+ | Matrix parsing for scipy | + +### 10.3 Complexity Hot Spots (L3: CFG) + +Functions with elevated cyclomatic complexity: + +| Function | File | Complexity | Blocks | Reason | +|----------|------|------------|--------|--------| +| `session_start` | `braintrust_hooks.py` | 5 | 13 | Multiple early returns | +| `search_hybrid` | `memory_service_pg.py` | 3 | 6 | Date filter branches | +| `infer_pattern` | `pattern_inference.py` | 12+ | - | Pattern matching logic | +| `main` | `compiler-in-the-loop.ts` | 8+ | - | Lean4 + Loogle integration | +| `main` | `skill-activation-prompt.ts` | 10+ | - | Large skill matching switch | + +#### Refactoring Candidates + +1. **`skill-activation-prompt.ts:main`** - Extract skill matchers to separate functions +2. **`pattern_inference.py:infer_pattern`** - Use strategy pattern +3. **`braintrust_hooks.py`** - Split session vs span logic + +### 10.4 Data Flow Analysis (L4: DFG) + +#### Key Data Paths + +**PostgreSQL Connection Flow (38 callers):** +``` +postgres_pool.py:get_connection() + ├── memory_service_pg.py (all methods) + ├── temporal_memory/store_pg.py + ├── coordination_pg.py + ├── message_memory.py + └── populate_temporal_sessions.py +``` + +**Embedding Pipeline:** +``` +Input text + → embedding_service.py:embed() + → OpenAI/Local API + → memory_service_pg.py:store() + → PostgreSQL (pgvector column) +``` + +**search_hybrid Data Flow:** +``` +Parameters: + text_query: str + query_embedding: list[float] (1536 dims) + limit: int = 10 + text_weight: float = 0.5 + vector_weight: float = 0.5 + start_date, end_date: Optional[datetime] + │ + ▼ + _pad_embedding() → padded_query + │ + ▼ + Build SQL conditions (date filters) + │ + ▼ + Execute hybrid query: + SELECT ... + ts_rank(...) * text_weight + + (1 - embedding <=> query) * vector_weight + │ + ▼ +Output: list[MemoryRecord] +``` + +### 10.5 Dead Code Analysis + +#### Cleanup Completed (2026-01-07) + +**Files archived:** +| File | Reason | +|------|--------| +| `offline_search.py` → `archive/` | Duplicate of wizard functionality, only test imports | +| `service_checks.py` → `archive/` | Duplicate of wizard functionality, only test imports | +| `test_mcp_offline.py` → `tests/archive/` | Tests for archived files | + +**Functions removed:** +| File | Function | Reason | +|------|----------|--------| +| `braintrust_analyze.py` | `format_duration` | Never called, no tests | +| `secrets_filter.py` | `mask_secret` | Never called, not exported | + +**Functions kept (have tests, cross-platform support):** +| File | Function | Reason | +|------|----------|--------| +| `hook_launcher.py` | `expand_path` | Cross-platform path handling, tested | + +#### Archive Directory (490+ functions) + +The `archive/` directory contains deprecated subsystems: + +| File | Status | Note | +|------|--------|------| +| `offline_search.py` | Archived | Duplicate of wizard SQLite fallback | +| `service_checks.py` | Archived | Duplicate of wizard service checks | +| `user_preferences.py` | Dead | Old preference system | +| `websocket_multiplex.py` | Dead | Replaced by coordination_pg | +| `skill_validation.py` | Dead | Moved to hooks | +| `ledger_workflow.py` | Dead | Superseded by continuity hooks | +| `post_tool_use_flywheel.py` | Dead | Never integrated | +| `db_connection.py` | Dead | Replaced by postgres_pool | + +### 10.6 Circular Dependencies + +**Resolved:** The `claude_scope ↔ unified_scope` circular dependency was eliminated by archiving both modules (2026-01-07). These were Agentica infrastructure modules that were never integrated into production hooks or skills. + +No circular dependencies remain in active code. + +### 10.7 TLDR-Code Package Structure + +**PyPI:** `llm-tldr` | **Source:** [github.com/parcadei/tldr-code](https://github.com/parcadei/tldr-code) + +| Module | Layer | Functions | Classes | Purpose | +|--------|-------|-----------|---------|---------| +| `api.py` | API | 20 | 3 | Unified interface | +| `ast_extractor.py` | L1 | 2 | 6 | Python AST extraction | +| `hybrid_extractor.py` | L1 | 1 | 1 | Multi-language AST | +| `cross_file_calls.py` | L2 | 53 | 2 | Call graph building | +| `cfg_extractor.py` | L3 | 7 | 5 | Control flow graphs | +| `dfg_extractor.py` | L4 | 7 | 7 | Data flow analysis | +| `pdg_extractor.py` | L5 | 6 | 4 | Program dependencies | +| `analysis.py` | Util | 9 | 1 | Impact/dead code | +| `cli.py` | CLI | 1 | 0 | Command-line entry | + +### 10.8 Hook System Structure + +Location: `.claude/hooks/src/` + +| Category | Hooks | Purpose | +|----------|-------|---------| +| Session | 4 | Start/end lifecycle | +| Tool Interception | 8 | Enhance tool behavior | +| Subagent | 4 | Agent coordination | +| Patterns | 2 | Multi-agent orchestration | +| Validation | 3 | Code quality gates | + +**Key Hook Functions:** + +| Hook | Key Functions | +|------|---------------| +| `skill-activation-prompt.ts` | `runPatternInference`, `generateAgenticaOutput` | +| `tldr-context-inject.ts` | `detectIntent`, `getTldrContext`, `extractEntryPoints` | +| `subagent-stop-continuity.ts` | `parseStructuredHandoff`, `createYamlHandoff` | +| `compiler-in-the-loop.ts` | `runLeanCompiler`, `getGoedelSuggestions`, `queryLoogle` | +| `pattern-orchestrator.ts` | `handlePipeline`, `handleJury`, `handleDebate`, `handleGenCritic` | + +--- + +## 11. Summary Statistics + +| Metric | Count | Notes | +|--------|-------|-------| +| Python functions | 2,328 | Across all `opc/scripts/` | +| TypeScript hooks | 34 | Active in `.claude/hooks/src/` | +| Skills | 108 | Active SKILL.md files in `.claude/skills/` | +| Agents | 32 | Agent definitions in `.claude/agents/` | +| MCP Servers | 10 | Server integrations in `.claude/servers/` | +| Tests | 265+ | TLDR-code alone | +| Entry layer functions | 1,057 | Called from outside | +| Leaf functions | 729 | Utility/helper code | +| Dead functions | 4 active, 43 archived | Most dead code now in archive/ | +| Circular dependencies | 0 | Resolved by archiving scope modules | +| get_connection callers | 38 | Most called internal function | + +--- + +## 12. Documentation Confidence + +| Section | Confidence | Last Verified | +|---------|------------|---------------| +| Architecture Diagram | HIGH | 2026-02-04 | +| Capability Catalog | HIGH | 2026-02-04 | +| Hook Layer | HIGH | 2026-02-04 | +| Agent Layer | MEDIUM | 2026-02-04 | +| Infrastructure Layer | HIGH | 2026-02-04 | +| TLDR Analysis Results | MEDIUM | 2026-01-07 | +| Summary Statistics | HIGH | 2026-02-04 | + +--- + +*This architecture document is generated by TLDR 5-layer analysis. Token cost: ~5,000 (vs ~50,000 raw files = 90% savings).* + +*Last updated: 2026-02-04* diff --git a/.auto-doc-history/20260205-023154/README.md b/.auto-doc-history/20260205-023154/README.md new file mode 100644 index 00000000..fa689a34 --- /dev/null +++ b/.auto-doc-history/20260205-023154/README.md @@ -0,0 +1,1277 @@ +# Continuous Claude + +> A persistent, learning, multi-agent development environment built on Claude Code + +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) +[![Claude Code](https://img.shields.io/badge/Claude-Code-orange.svg)](https://claude.ai/code) +[![Skills](https://img.shields.io/badge/Skills-109-green.svg)](#skills-system) +[![Agents](https://img.shields.io/badge/Agents-32-purple.svg)](#agents-system) +[![Hooks](https://img.shields.io/badge/Hooks-30-blue.svg)](#hooks-system) + +**Continuous Claude** transforms Claude Code into a continuously learning system that maintains context across sessions, orchestrates specialized agents, and eliminates wasting tokens through intelligent code analysis. + +## Table of Contents + +- [Why Continuous Claude?](#why-continuous-claude) +- [Design Principles](#design-principles) +- [How to Talk to Claude](#how-to-talk-to-claude) +- [Quick Start](#quick-start) +- [Architecture](#architecture) +- [Core Systems](#core-systems) + - [Skills (109)](#skills-system) + - [Agents (32)](#agents-system) + - [Hooks (30)](#hooks-system) + - [TLDR Code Analysis](#tldr-code-analysis) + - [Memory System](#memory-system) + - [Continuity System](#continuity-system) + - [Math System](#math-system) +- [Workflows](#workflows) +- [Installation](#installation) +- [Updating](#updating) +- [Configuration](#configuration) +- [Contributing](#contributing) +- [License](#license) + +--- + +## Why Continuous Claude? + +Claude Code has a **compaction problem**: when context fills up, the system compacts your conversation, losing nuanced understanding and decisions made during the session. + +**Continuous Claude solves this with:** + +| Problem | Solution | +|---------|----------| +| Context loss on compaction | YAML handoffs - more token-efficient transfer | +| Starting fresh each session | Memory system recalls + daemon auto-extracts learnings | +| Reading entire files burns tokens | 5-layer code analysis + semantic index | +| Complex tasks need coordination | Meta-skills orchestrate agent workflows | +| Repeating workflows manually | 109 skills with natural language triggers | + +**The mantra: Compound, don't compact.** Extract learnings automatically, then start fresh with full context. + +### Why "Continuous"? Why "Compounding"? + +The name is a pun. **Continuous** because Claude maintains state across sessions. **Compounding** because each session makes the system smarter—learnings accumulate like compound interest. + +--- + +## Design Principles + +An agent is five things: **Prompt + Tools + Context + Memory + Model**. + +| Component | What We Optimize | +|-----------|------------------| +| **Prompt** | Skills inject relevant context; hooks add system reminders | +| **Tools** | TLDR reduces tokens; agents parallelize work | +| **Context** | Not just *what* Claude knows, but *how* it's provided | +| **Memory** | Daemon extracts learnings; recall surfaces them | +| **Model** | Becomes swappable when the other four are solid | + +### Anti-Complexity + +We resist plugin sprawl. Every MCP, subscription, and tool you add promises improvement but risks breaking context, tools, or prompts through clashes. + +**Our approach:** +- **Time, not money** — No required paid services. Perplexity and NIA are optional, high-value-per-token. +- **Learn, don't accumulate** — A system that learns handles edge cases better than one that collects plugins. +- **Shift-left validation** — Hooks run pyright/ruff after edits, catching errors before tests. + +The failure modes of complex systems are structurally invisible until they happen. A learning, context-efficient system doesn't prevent all failures—but it recovers and improves. + +--- + +## How to Talk to Claude + +**You don't need to memorize slash commands.** Just describe what you want naturally. + +### The Skill Activation System + +When you send a message, a hook injects context that tells **Claude** which skills and agents are relevant. Claude infers from a rule-based system and decides which tools to use. + +``` +> "Fix the login bug in auth.py" + +🎯 SKILL ACTIVATION CHECK +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +⚠️ CRITICAL SKILLS (REQUIRED): + → create_handoff + +📚 RECOMMENDED SKILLS: + → fix + → debug + +🤖 RECOMMENDED AGENTS (token-efficient): + → debug-agent + → scout + +ACTION: Use Skill tool BEFORE responding +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +### Priority Levels + +| Level | Meaning | +|-------|---------| +| ⚠️ **CRITICAL** | Must use (e.g., handoffs before ending session) | +| 📚 **RECOMMENDED** | Should use (e.g., workflow skills) | +| 💡 **SUGGESTED** | Consider using (e.g., optimization tools) | +| 📌 **OPTIONAL** | Nice to have (e.g., documentation helpers) | + +### Natural Language Examples + +| What You Say | What Activates | +|--------------|----------------| +| "Fix the broken login" | `/fix` workflow → debug-agent, scout | +| "Build a user dashboard" | `/build` workflow → plan-agent, kraken | +| "I want to understand this codebase" | `/explore` + scout agent | +| "What could go wrong with this plan?" | `/premortem` | +| "Help me figure out what I need" | `/discovery-interview` | +| "Done for today" | `create_handoff` (critical) | +| "Resume where we left off" | `resume_handoff` | +| "Research auth patterns" | oracle agent + perplexity | +| "Find all usages of this API" | scout agent + ast-grep | + +### Why This Approach? + +| Benefit | How | +|---------|-----| +| **More Discoverable** | Don't need to know commands exist | +| **Context-Aware** | System knows when you're 90% through context | +| **Reduces Cognitive Load** | Describe intent naturally, get curated suggestions | +| **Power User Friendly** | Still supports /fix, /build, etc. directly | + +### Skill vs Workflow vs Agent + +| Type | Purpose | Example | +|------|---------|---------| +| **Skill** | Single-purpose tool | `commit`, `tldr-code`, `qlty-check` | +| **Workflow** | Multi-step process | `/fix` (sleuth → premortem → kraken → commit) | +| **Agent** | Specialized sub-session | scout (exploration), oracle (research) | + +[See detailed skill activation docs →](docs/skill-activation.md) + +--- + +## Quick Start + +### Prerequisites + +- Python 3.11+ +- [uv](https://github.com/astral-sh/uv) package manager +- Docker (for PostgreSQL) +- Claude Code CLI + +### Installation + +```bash +# Clone +git clone https://github.com/parcadei/Continuous-Claude-v3.git +cd Continuous-Claude-v3/opc + +# Run setup wizard (12 steps) +uv run python -m scripts.setup.wizard +``` + +> **Note:** The `pyproject.toml` is in `opc/`. Always run `uv` commands from the `opc/` directory. + +### What the Wizard Does + +| Step | What It Does | +|------|--------------| +| 1 | Backup existing .claude/ config (if present) | +| 2 | Check prerequisites (Docker, Python, uv) | +| 3-5 | Database + API key configuration | +| 6-7 | Start Docker stack, run migrations | +| 8 | Install Claude Code integration (32 agents, 109 skills, 30 hooks) | +| 9 | Math features (SymPy, Z3, Pint - optional) | +| 10 | TLDR code analysis tool | +| 11-12 | Diagnostics tools + Loogle (optional) | + +### Remote Database Setup + +By default, CC-v3 runs PostgreSQL locally via Docker. For remote database setups: + +#### 1. Database Preparation + +```bash +# Connect to your remote PostgreSQL instance +psql -h hostname -U user -d continuous_claude + +# Enable pgvector extension (requires superuser or rds_superuser) +CREATE EXTENSION IF NOT EXISTS vector; + +# Apply the schema (from your local clone) +psql -h hostname -U user -d continuous_claude -f docker/init-schema.sql +``` + +> **Managed PostgreSQL tips:** +> - **AWS RDS**: Add `vector` to `shared_preload_libraries` in DB Parameter Group +> - **Supabase**: Enable via Database Extensions page +> - **Azure Database**: Use Extensions pane to enable pgvector + +#### 2. Connection Configuration + +Set `CONTINUOUS_CLAUDE_DB_URL` in `~/.claude/settings.json`: + +```json +{ + "env": { + "CONTINUOUS_CLAUDE_DB_URL": "postgresql://user:password@hostname:5432/continuous_claude" + } +} +``` + +Or export before running Claude: + +```bash +export CONTINUOUS_CLAUDE_DB_URL="postgresql://user:password@hostname:5432/continuous_claude" +claude +``` + +See `.env.example` for all available environment variables. + +### First Session + +```bash +# Start Claude Code +claude + +# Try a workflow +> /workflow +``` + +### First Session Commands + +| Command | What it does | +|---------|--------------| +| `/workflow` | Goal-based routing (Research/Plan/Build/Fix) | +| `/fix bug ` | Investigate and fix a bug | +| `/build greenfield ` | Build a new feature from scratch | +| `/explore` | Understand the codebase | +| `/premortem` | Risk analysis before implementation | + +--- + +## Architecture + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ CONTINUOUS CLAUDE │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ Skills │ │ Agents │ │ Hooks │ │ +│ │ (109) │───▶│ (32) │◀───│ (30) │ │ +│ └─────────────┘ └─────────────┘ └─────────────┘ │ +│ │ │ │ │ +│ ▼ ▼ ▼ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ TLDR Code Analysis │ │ +│ │ L1:AST → L2:CallGraph → L3:CFG → L4:DFG → L5:Slicing │ │ +│ │ (95% token savings) │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ │ │ │ +│ ▼ ▼ ▼ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ Memory │ │ Continuity │ │ Coordination│ │ +│ │ System │ │ Ledgers │ │ Layer │ │ +│ └─────────────┘ └─────────────┘ └─────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +### Data Flow: Session Lifecycle + +``` +SessionStart Working SessionEnd + │ │ │ + ▼ ▼ ▼ +┌─────────┐ ┌─────────┐ ┌─────────┐ +│ Load │ │ Track │ │ Save │ +│ context │─────────────────▶│ changes │──────────────────▶│ state │ +└─────────┘ └─────────┘ └─────────┘ + │ │ │ + ├── Continuity ledger ├── File claims ├── Handoff + ├── Memory recall ├── TLDR indexing ├── Learnings + └── Symbol index └── Blackboard └── Outcome + │ + ▼ + ┌─────────┐ + │ /clear │ + │ Fresh │ + │ context │ + └─────────┘ +``` + +### The Continuity Loop (Detailed) + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ THE CONTINUITY LOOP │ +└─────────────────────────────────────────────────────────────────────────────┘ + + 1. SESSION START 2. WORKING + ┌────────────────────┐ ┌────────────────────┐ + │ │ │ │ + │ Ledger loaded ────┼──▶ Context │ PostToolUse ──────┼──▶ Index handoffs + │ Handoff loaded │ │ UserPrompt ───────┼──▶ Skill hints + │ Memory recalled │ │ Edit tracking ────┼──▶ Dirty flag++ + │ TLDR cache warmed │ │ SubagentStop ─────┼──▶ Agent reports + │ │ │ │ + └────────────────────┘ └────────────────────┘ + │ │ + │ ▼ + │ ┌────────────────────┐ + │ │ 3. PRE-COMPACT │ + │ │ │ + │ │ Auto-handoff ─────┼──▶ thoughts/shared/ + │ │ (YAML format) │ handoffs/*.yaml + │ │ Dirty > 20? ──────┼──▶ TLDR re-index + │ │ │ + │ └────────────────────┘ + │ │ + │ ▼ + │ ┌────────────────────┐ + │ │ 4. SESSION END │ + │ │ │ + │ │ Stale heartbeat ──┼──▶ Daemon wakes + │ │ Daemon spawns ────┼──▶ Headless Claude + │ │ Thinking blocks ──┼──▶ archival_memory + │ │ │ + │ └────────────────────┘ + │ │ + │ │ + └──────────────◀────── /clear ◀──────┘ + Fresh context + state preserved +``` + +### Workflow Chains + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ META-SKILL WORKFLOWS │ +└─────────────────────────────────────────────────────────────────────────────┘ + + /fix bug /build greenfield + ───────── ───────────────── + ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ + │ sleuth │─▶│ premortem│ │discovery │─▶│plan-agent│ + │(diagnose)│ │ (risk) │ │(clarify) │ │ (design) │ + └──────────┘ └────┬─────┘ └──────────┘ └────┬─────┘ + │ │ + ▼ ▼ + ┌──────────┐ ┌──────────┐ + │ kraken │ │ validate │ + │ (fix) │ │ (check) │ + └────┬─────┘ └────┬─────┘ + │ │ + ▼ ▼ + ┌──────────┐ ┌──────────┐ + │ arbiter │ │ kraken │ + │ (test) │ │(implement│ + └────┬─────┘ └────┬─────┘ + │ │ + ▼ ▼ + ┌──────────┐ ┌──────────┐ + │ commit │ │ commit │ + └──────────┘ └──────────┘ + + + /tdd /refactor + ──── ───────── + ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ + │plan-agent│─▶│ arbiter │ │ phoenix │─▶│ warden │ + │ (design) │ │(tests 🔴)│ │(analyze) │ │ (review) │ + └──────────┘ └────┬─────┘ └──────────┘ └────┬─────┘ + │ │ + ▼ ▼ + ┌──────────┐ ┌──────────┐ + │ kraken │ │ kraken │ + │(code 🟢) │ │(transform│ + └────┬─────┘ └────┬─────┘ + │ │ + ▼ ▼ + ┌──────────┐ ┌──────────┐ + │ arbiter │ │ judge │ + │(verify ✓)│ │ (review) │ + └──────────┘ └──────────┘ +``` + +### Data Layer Architecture + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ DATA LAYER ARCHITECTURE │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ TLDR 5-LAYER CODE ANALYSIS SEMANTIC INDEX │ +│ ┌────────────────────────┐ ┌────────────────────────┐ │ +│ │ L1: AST (~500 tok) │ │ BGE-large-en-v1.5 │ │ +│ │ └── Functions, │ │ ├── All 5 layers │ │ +│ │ classes, sigs │ │ ├── 10 lines context │ │ +│ │ │ │ └── FAISS index │ │ +│ │ L2: Call Graph (+440) │ │ │ │ +│ │ └── Cross-file │──────────────│ Query: "auth logic" │ │ +│ │ dependencies │ │ Returns: ranked funcs │ │ +│ │ │ └────────────────────────┘ │ +│ │ L3: CFG (+110 tok) │ │ +│ │ └── Control flow │ │ +│ │ │ MEMORY (PostgreSQL+pgvector) │ +│ │ L4: DFG (+130 tok) │ ┌────────────────────────┐ │ +│ │ └── Data flow │ │ sessions (heartbeat) │ │ +│ │ │ │ file_claims (locks) │ │ +│ │ L5: PDG (+150 tok) │ │ archival_memory (BGE) │ │ +│ │ └── Slicing │ │ handoffs (embeddings) │ │ +│ └────────────────────────┘ └────────────────────────┘ │ +│ ~1,200 tokens │ +│ vs 23,000 raw │ +│ = 95% savings FILE SYSTEM │ +│ ┌────────────────────────┐ │ +│ │ thoughts/ │ │ +│ │ ├── ledgers/ │ │ +│ │ │ └── CONTINUITY_*.md│ │ +│ │ └── shared/ │ │ +│ │ ├── handoffs/*.yaml│ │ +│ │ └── plans/*.md │ │ +│ │ │ │ +│ │ .tldr/ │ │ +│ │ └── (daemon cache) │ │ +│ └────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Core Systems + +### Skills System + +Skills are modular capabilities triggered by natural language. Located in `.claude/skills/`. + +#### Meta-Skills (Workflow Orchestrators) + +| Meta-Skill | Chain | Use When | +|------------|-------|----------| +| `/workflow` | Router → appropriate workflow | Don't know where to start | +| `/build` | discovery → plan → validate → implement → commit | Building features | +| `/fix` | sleuth → premortem → kraken → test → commit | Fixing bugs | +| `/tdd` | plan → arbiter (tests) → kraken (implement) → arbiter | Test-first development | +| `/refactor` | phoenix → plan → kraken → reviewer → arbiter | Safe code transformation | +| `/review` | parallel specialized reviews → synthesis | Code review | +| `/explore` | scout (quick/deep/architecture) | Understand codebase | +| `/security` | vulnerability scan → verification | Security audits | +| `/release` | audit → E2E → review → changelog | Ship releases | + +#### Meta-Skill Reference + +Each meta-skill supports modes, scopes, and flags. Type the skill alone (e.g., `/build`) to get an interactive question flow. + +**`/build [options] [description]`** + +| Mode | Chain | Use For | +|------|-------|---------| +| `greenfield` | discovery → plan → validate → implement → commit → PR | New feature from scratch | +| `brownfield` | onboard → research → plan → validate → implement | Feature in existing codebase | +| `tdd` | plan → test-first → implement | Test-driven development | +| `refactor` | impact analysis → plan → TDD → implement | Safe refactoring | + +| Option | Effect | +|--------|--------| +| `--skip-discovery` | Skip interview phase (have clear spec) | +| `--skip-validate` | Skip plan validation | +| `--skip-commit` | Don't auto-commit | +| `--skip-pr` | Don't create PR description | +| `--parallel` | Run research agents in parallel | + +**`/fix [options] [description]`** + +| Scope | Chain | Use For | +|-------|-------|---------| +| `bug` | debug → implement → test → commit | General bug fix | +| `hook` | debug-hooks → hook-developer → implement → test | Hook issues | +| `deps` | preflight → oracle → plan → implement → qlty | Dependency errors | +| `pr-comments` | github-search → research → plan → implement → commit | PR feedback | + +| Option | Effect | +|--------|--------| +| `--no-test` | Skip regression test | +| `--dry-run` | Diagnose only, don't fix | +| `--no-commit` | Don't auto-commit | + +**`/explore [options]`** + +| Depth | Time | What It Does | +|-------|------|--------------| +| `quick` | ~1 min | tldr tree + structure overview | +| `deep` | ~5 min | onboard + tldr + research + documentation | +| `architecture` | ~3 min | tldr arch + call graph + layers | + +| Option | Effect | +|--------|--------| +| `--focus "area"` | Focus on specific area (e.g., `--focus "auth"`) | +| `--output handoff` | Create handoff for implementation | +| `--output doc` | Create documentation file | +| `--entry "func"` | Start from specific entry point | + +**`/tdd`, `/refactor`, `/review`, `/security`, `/release`** + +These follow their defined chains without mode flags. Just run: +``` +/tdd "implement retry logic" +/refactor "extract auth module" +/review # reviews current changes +/security "authentication code" +/release v1.2.0 +``` + +#### Key Skills (High-Value Tools) + +**Planning & Risk** +- **premortem**: TIGERS & ELEPHANTS risk analysis - use before any significant implementation +- **discovery-interview**: Transform vague ideas into detailed specs + +**Context Management** +- **create_handoff**: Capture session state for transfer +- **resume_handoff**: Resume from handoff with context +- **continuity_ledger**: Track state within session + +**Code Analysis (95% Token Savings)** +- **tldr-code**: Call graph, CFG, DFG, slicing +- **ast-grep-find**: Structural code search +- **morph-search**: Fast text search (20x faster than grep) + +**Research** +- **perplexity-search**: AI-powered web search +- **nia-docs**: Library documentation search +- **github-search**: Search GitHub code/issues/PRs + +**Quality** +- **qlty-check**: 70+ linters, auto-fix +- **braintrust-analyze**: Session analysis, replay, and debugging failed sessions + +**Math & Formal Proofs** +- **math**: Unified computation (SymPy, Z3, Pint) — one entry point for all math +- **prove**: Lean4 theorem proving with 5-phase workflow (Research → Design → Test → Implement → Verify) +- **pint-compute**: Unit-aware arithmetic and conversions +- **shapely-compute**: Computational geometry + +The `/prove` skill enables machine-verified proofs without learning Lean syntax. Used to create the first Lean formalization of Sylvester-Gallai theorem. + +#### The Thought Process + +``` +What do I want to do? +├── Don't know → /workflow (guided router) +├── Building → /build greenfield or brownfield +├── Fixing → /fix bug +├── Understanding → /explore +├── Planning → premortem first, then plan-agent +├── Researching → oracle or perplexity-search +├── Reviewing → /review +├── Proving → /prove (Lean4 formal verification) +├── Computing → /math (SymPy, Z3, Pint) +└── Shipping → /release +``` + +[See detailed skills breakdown →](docs/skills/) + +--- + +### Agents System + +Agents are specialized AI workers spawned via the Task tool. Located in `.claude/agents/`. + +#### Agent Categories (32 active) + +> **Note:** There are likely too many agents—consolidation is a v4 goal. Use what fits your workflow. + +**Orchestrators (2)** +- **maestro**: Multi-agent coordination with patterns (Pipeline, Swarm, Jury) +- **kraken**: TDD implementation agent with checkpoint/resume support + +**Planners (4)** +- **architect**: Feature planning + API integration +- **phoenix**: Refactoring + framework migration planning +- **plan-agent**: Lightweight planning with research/MCP tools +- **validate-agent**: Validate plans against best practices + +**Explorers (4)** +- **scout**: Codebase exploration (use instead of Explore) +- **oracle**: External research (web, docs, APIs) +- **pathfinder**: External repository analysis +- **research-codebase**: Document codebase as-is + +**Implementers (3)** +- **kraken**: TDD implementation with strict test-first workflow +- **spark**: Lightweight fixes and quick tweaks +- **agentica-agent**: Build Python agents using Agentica SDK + +**Debuggers (3)** +- **sleuth**: General bug investigation and root cause +- **debug-agent**: Issue investigation via logs/code search +- **profiler**: Performance profiling and race conditions + +**Validators (2)** - arbiter, atlas + +**Reviewers (6)** - critic, judge, surveyor, liaison, plan-reviewer, review-agent + +**Specialized (8)** - aegis, herald, scribe, chronicler, session-analyst, braintrust-analyst, memory-extractor, onboard + +#### Common Workflows + +| Workflow | Agent Chain | +|----------|-------------| +| Feature | architect → plan-reviewer → kraken → review-agent → arbiter | +| Refactoring | phoenix → plan-reviewer → kraken → judge → arbiter | +| Bug Fix | sleuth → spark/kraken → arbiter → scribe | + +[See detailed agent guide →](docs/agents/) + +--- + +### Hooks System + +Hooks intercept Claude Code at lifecycle points. Located in `.claude/hooks/`. + +#### Hook Events (30 hooks total) + +| Event | Key Hooks | Purpose | +|-------|-----------|---------| +| **SessionStart** | session-start-continuity, session-register, braintrust-tracing | Load context, register session | +| **PreToolUse** | tldr-read-enforcer, smart-search-router, tldr-context-inject, file-claims | Token savings, search routing | +| **PostToolUse** | post-edit-diagnostics, handoff-index, post-edit-notify | Validation, indexing | +| **PreCompact** | pre-compact-continuity | Auto-save before compaction | +| **UserPromptSubmit** | skill-activation-prompt, memory-awareness | Skill hints, memory recall | +| **SubagentStop** | subagent-stop-continuity | Save agent state | +| **SessionEnd** | session-end-cleanup, session-outcome | Cleanup, extract learnings | + +#### Key Hooks + +| Hook | Purpose | +|------|---------| +| **tldr-context-inject** | Adds code analysis to agent prompts | +| **smart-search-router** | Routes grep to AST-grep when appropriate | +| **post-edit-diagnostics** | Runs pyright/ruff after edits | +| **memory-awareness** | Surfaces relevant learnings | + +[See all 30 hooks →](docs/hooks/) + +--- + +### TLDR Code Analysis + +TLDR provides token-efficient code summaries through 5 analysis layers. + +#### The 5-Layer Stack + +| Layer | Name | What it provides | Tokens | +|-------|------|------------------|--------| +| **L1** | AST | Functions, classes, signatures | ~500 tokens | +| **L2** | Call Graph | Who calls what (cross-file) | +440 tokens | +| **L3** | CFG | Control flow, complexity | +110 tokens | +| **L4** | DFG | Data flow, variable tracking | +130 tokens | +| **L5** | PDG | Program slicing, impact analysis | +150 tokens | + +**Total: ~1,200 tokens vs 23,000 raw = 95% savings** + +#### CLI Commands + +```bash +# Structure analysis +tldr tree src/ # File tree +tldr structure src/ --lang python # Code structure (codemaps) + +# Search and extraction +tldr search "process_data" src/ # Find code +tldr context process_data --project src/ --depth 2 # LLM-ready context + +# Flow analysis +tldr cfg src/main.py main # Control flow graph +tldr dfg src/main.py main # Data flow graph +tldr slice src/main.py main 42 # What affects line 42? + +# Codebase analysis +tldr impact process_data src/ # Who calls this function? +tldr dead src/ # Find unreachable code +tldr arch src/ # Detect architectural layers + +# Semantic search (natural language) +tldr daemon semantic "find authentication logic" +``` + +#### Semantic Index + +Beyond structural analysis, TLDR builds a **semantic index** of your codebase: + +- **Natural language queries** — Ask "where is error handling?" instead of grepping +- **Auto-rebuild** — Dirty flag hook tracks file changes; index rebuilds after N edits +- **Selective indexing** — Use `.tldrignore` to control what gets indexed + +```bash +# .tldrignore example +__pycache__/ +*.test.py +node_modules/ +.venv/ +``` + +The semantic index uses all 5 layers plus 10 lines of surrounding code context—not just docstrings. + +#### Hook Integration + +TLDR is automatically integrated via hooks: + +- **tldr-read-enforcer**: Returns L1+L2+L3 instead of full file reads +- **smart-search-router**: Routes Grep to `tldr search` +- **post-tool-use-tracker**: Updates indexes when files change + +[See TLDR documentation →](opc/packages/tldr-code/) + +--- + +### Memory System + +Cross-session learning powered by PostgreSQL + pgvector. + +#### How It Works + +``` +Session ends → Database detects stale heartbeat (>5 min) + → Daemon spawns headless Claude (Sonnet) + → Analyzes thinking blocks from session + → Extracts learnings to archival_memory + → Next session recalls relevant learnings +``` + +The key insight: **thinking blocks contain the real reasoning**—not just what Claude did, but why. The daemon extracts this automatically. + +#### Conversational Interface + +| What You Say | What Happens | +|--------------|--------------| +| "Remember that auth uses JWT" | Stores learning with context | +| "Recall authentication patterns" | Searches memory, surfaces matches | +| "What did we decide about X?" | Implicit recall via memory-awareness hook | + +#### Database Schema (4 tables) + +| Table | Purpose | +|-------|---------| +| **sessions** | Cross-terminal awareness | +| **file_claims** | Cross-terminal file locking | +| **archival_memory** | Long-term learnings with BGE embeddings | +| **handoffs** | Session handoffs with embeddings | + +#### Recall Commands + +```bash +# Recall learnings (hybrid text + vector search) +cd opc && uv run python scripts/core/recall_learnings.py \ + --query "authentication patterns" + +# Store a learning explicitly +cd opc && uv run python scripts/core/store_learning.py \ + --session-id "my-session" \ + --type WORKING_SOLUTION \ + --content "What I learned" \ + --confidence high +``` + +#### Automatic Memory + +The **memory-awareness** hook surfaces relevant learnings when you send a message. You'll see `MEMORY MATCH` indicators—Claude can use these without you asking. + +--- + +### Continuity System + +Preserve state across context clears and sessions. + +#### Continuity Ledger + +Within-session state tracking. Location: `thoughts/ledgers/CONTINUITY_.md` + +```markdown +# Session: feature-x +Updated: 2026-01-08 + +## Goal +Implement feature X with proper error handling + +## Completed +- [x] Designed API schema +- [x] Implemented core logic + +## In Progress +- [ ] Add error handling + +## Blockers +- Need clarification on retry policy +``` + +#### Handoffs + +Between-session knowledge transfer. Location: `thoughts/shared/handoffs//` + +```yaml +--- +date: 2026-01-08T15:26:01+0000 +session_name: feature-x +status: complete +--- + +# Handoff: Feature X Implementation + +## Task(s) +| Task | Status | +|------|--------| +| Design API | Completed | +| Implement core | Completed | +| Error handling | Pending | + +## Next Steps +1. Add retry logic to API calls +2. Write integration tests +``` + +#### Commands + +| Command | Effect | +|---------|--------| +| "save state" | Updates continuity ledger | +| "done for today" / `/handoff` | Creates handoff document | +| "resume work" | Loads latest handoff | + +--- + +### Math System + +Two capabilities: **computation** (SymPy, Z3, Pint) and **formal verification** (Lean4 + Mathlib). + +#### The Stack + +| Tool | Purpose | Example | +|------|---------|---------| +| **SymPy** | Symbolic math | Solve equations, integrals, matrix operations | +| **Z3** | Constraint solving | Prove inequalities, SAT problems | +| **Pint** | Unit conversion | Convert miles to km, dimensional analysis | +| **Lean4** | Formal proofs | Machine-verified theorems | +| **Mathlib** | 100K+ theorems | Pre-formalized lemmas to build on | +| **Loogle** | Type-aware search | Find Mathlib lemmas by signature | + +#### Two Entry Points + +| Skill | Use When | +|-------|----------| +| `/math` | Computing, solving, calculating | +| `/prove` | Formal verification, machine-checked proofs | + +#### /math Examples + +```bash +# Solve equation +"Solve x² - 4 = 0" → x = ±2 + +# Compute eigenvalues +"Eigenvalues of [[2,1],[1,2]]" → {1: 1, 3: 1} + +# Prove inequality +"Is x² + y² ≥ 2xy always true?" → PROVED (equals (x-y)²) + +# Convert units +"26.2 miles to km" → 42.16 km +``` + +#### /prove - Formal Verification + +5-phase workflow for machine-verified proofs: + +``` +📚 RESEARCH → 🏗️ DESIGN → 🧪 TEST → ⚙️ IMPLEMENT → ✅ VERIFY +``` + +1. **Research**: Search Mathlib with Loogle, find proof strategy +2. **Design**: Create skeleton with `sorry` placeholders +3. **Test**: Search for counterexamples before proving +4. **Implement**: Fill sorries with compiler-in-the-loop feedback +5. **Verify**: Audit axioms, confirm zero sorries + +``` +/prove every group homomorphism preserves identity +/prove continuous functions on compact sets are uniformly continuous +``` + +**Achievement**: Used to create the first Lean formalization of the Sylvester-Gallai theorem. + +#### Prerequisites (Optional) + +Math features require installation via wizard step 9: + +```bash +# Installed automatically by wizard +uv pip install sympy z3-solver pint shapely + +# Lean4 (for /prove) +curl https://raw.githubusercontent.com/leanprover/elan/master/elan-init.sh -sSf | sh +``` + +--- + +## Workflows + +### /workflow - Goal-Based Router + +``` +> /workflow + +? What's your goal? + ○ Research - Understand codebase/docs + ○ Plan - Design implementation approach + ○ Build - Implement features + ○ Fix - Investigate and resolve issues +``` + +### /fix - Bug Resolution + +```bash +/fix bug "login fails silently" +``` + +**Chain:** sleuth → [checkpoint] → [premortem] → kraken → test → commit + +| Scope | What it does | +|-------|--------------| +| `bug` | General bug investigation | +| `hook` | Hook-specific debugging | +| `deps` | Dependency issues | +| `pr-comments` | Address PR feedback | + +### /build - Feature Development + +```bash +/build greenfield "user dashboard" +``` + +**Chain:** discovery → plan → validate → implement → commit → PR + +| Mode | What it does | +|------|--------------| +| `greenfield` | New feature from scratch | +| `brownfield` | Modify existing codebase | +| `tdd` | Test-first development | +| `refactor` | Safe code transformation | + +### /premortem - Risk Analysis + +```bash +/premortem deep thoughts/shared/plans/feature-x.md +``` + +**Output:** +- **TIGERS**: Clear threats (HIGH/MEDIUM/LOW severity) +- **ELEPHANTS**: Unspoken concerns + +Blocks on HIGH severity until user accepts/mitigates risks. + +--- + +## Installation + +### Full Installation (Recommended) + +```bash +# Clone +git clone https://github.com/parcadei/continuous-claude.git +cd continuous-claude/opc + +# Run the setup wizard +uv run python -m scripts.setup.wizard +``` + +The wizard walks you through all configuration options interactively. + +## Updating + +Pull latest changes and sync your installation: + +```bash +cd continuous-claude/opc +uv run python -m scripts.setup.update +``` + +This will: +- Pull latest from GitHub +- Update hooks, skills, rules, agents +- Upgrade TLDR if installed +- Rebuild TypeScript hooks if changed + +### What Gets Installed + +| Component | Location | +|-----------|----------| +| Agents (32) | ~/.claude/agents/ | +| Skills (109) | ~/.claude/skills/ | +| Hooks (30) | ~/.claude/hooks/ | +| Rules | ~/.claude/rules/ | +| Scripts | ~/.claude/scripts/ | +| PostgreSQL | Docker container | + +### Installation Mode: Copy vs Symlink + +The wizard offers two installation modes: + +| Mode | How It Works | Best For | +|------|--------------|----------| +| **Copy** (default) | Copies files from repo to `~/.claude/` | End users, stable setup | +| **Symlink** | Creates symlinks to repo files | Contributors, development | + +#### Copy Mode (Default) + +Files are copied from `continuous-claude/.claude/` to `~/.claude/`. Changes you make in `~/.claude/` are **local only** and will be overwritten on next update. + +```text +continuous-claude/.claude/ ──COPY──> ~/.claude/ + (source) (user config) +``` + +**Pros:** Stable, isolated from repo changes +**Cons:** Local changes lost on update, manual sync needed + +#### Symlink Mode (Recommended for Contributors) + +Creates symlinks so `~/.claude/` points directly to repo files. Changes in either location affect the same files. + +```text +~/.claude/rules ──SYMLINK──> continuous-claude/.claude/rules +~/.claude/skills ──SYMLINK──> continuous-claude/.claude/skills +~/.claude/hooks ──SYMLINK──> continuous-claude/.claude/hooks +~/.claude/agents ──SYMLINK──> continuous-claude/.claude/agents +``` + +**Pros:** +- Changes auto-sync to repo (can `git commit` improvements) +- No re-installation needed after `git pull` +- Contribute back easily + +**Cons:** +- Breaking changes in repo affect your setup immediately +- Need to manage git workflow + +#### Switching to Symlink Mode + +If you installed with copy mode and want to switch: + +```bash +# Backup current config +mkdir -p ~/.claude/backups/$(date +%Y%m%d) +cp -r ~/.claude/{rules,skills,hooks,agents} ~/.claude/backups/$(date +%Y%m%d)/ + +# Verify backup succeeded before proceeding +ls -la ~/.claude/backups/$(date +%Y%m%d)/ + +# Remove copies (only after verifying backup above) +rm -rf ~/.claude/{rules,skills,hooks,agents} + +# Create symlinks (adjust path to your repo location) +REPO="$HOME/continuous-claude" # or wherever you cloned +ln -s "$REPO/.claude/rules" ~/.claude/rules +ln -s "$REPO/.claude/skills" ~/.claude/skills +ln -s "$REPO/.claude/hooks" ~/.claude/hooks +ln -s "$REPO/.claude/agents" ~/.claude/agents + +# Verify +ls -la ~/.claude | grep -E "rules|skills|hooks|agents" +``` + +**Windows users:** Use PowerShell (as Administrator or with Developer Mode enabled): + +```powershell +# Enable Developer Mode first (Settings → Privacy & security → For developers) +# Or run PowerShell as Administrator + +# Backup current config +$BackupDir = "$HOME\.claude\backups\$(Get-Date -Format 'yyyyMMdd')" +New-Item -ItemType Directory -Path $BackupDir -Force +Copy-Item -Recurse "$HOME\.claude\rules","$HOME\.claude\skills","$HOME\.claude\hooks","$HOME\.claude\agents" $BackupDir + +# Verify backup succeeded before proceeding +Get-ChildItem $BackupDir + +# Remove copies (only after verifying backup above) +Remove-Item -Recurse "$HOME\.claude\rules","$HOME\.claude\skills","$HOME\.claude\hooks","$HOME\.claude\agents" + +# Create symlinks (adjust path to your repo location) +$REPO = "$HOME\continuous-claude" # or wherever you cloned +New-Item -ItemType SymbolicLink -Path "$HOME\.claude\rules" -Target "$REPO\.claude\rules" +New-Item -ItemType SymbolicLink -Path "$HOME\.claude\skills" -Target "$REPO\.claude\skills" +New-Item -ItemType SymbolicLink -Path "$HOME\.claude\hooks" -Target "$REPO\.claude\hooks" +New-Item -ItemType SymbolicLink -Path "$HOME\.claude\agents" -Target "$REPO\.claude\agents" + +# Verify +Get-ChildItem "$HOME\.claude" | Where-Object { $_.LinkType -eq "SymbolicLink" } +``` + +### For Brownfield Projects + +After installation, start Claude and run: +``` +> /onboard +``` + +This analyzes the codebase and creates an initial continuity ledger. + +--- + +## Configuration + +### .claude/settings.json + +Central configuration for hooks, tools, and workflows. + +```json +{ + "hooks": { + "SessionStart": [...], + "PreToolUse": [...], + "PostToolUse": [...], + "UserPromptSubmit": [...] + } +} +``` + +### .claude/skills/skill-rules.json + +Skill activation triggers. + +```json +{ + "rules": [ + { + "skill": "fix", + "keywords": ["fix this", "broken", "not working"], + "intentPatterns": ["fix.*(bug|issue|error)"] + } + ] +} +``` + +### Environment Variables + +| Variable | Purpose | Required | +|----------|---------|----------| +| `DATABASE_URL` | PostgreSQL connection string | Yes | +| `BRAINTRUST_API_KEY` | Session tracing | No | +| `PERPLEXITY_API_KEY` | Web search | No | +| `NIA_API_KEY` | Documentation search | No | +| `CLAUDE_OPC_DIR` | Path to CC's opc/ directory (set by wizard) | Auto | +| `CLAUDE_PROJECT_DIR` | Current project directory (set by SessionStart hook) | Auto | + +Services without API keys still work: +- Continuity system (ledgers, handoffs) +- TLDR code analysis +- Local git operations +- TDD workflow + +--- + +## Directory Structure + +``` +continuous-claude/ +├── .claude/ +│ ├── agents/ # 32 specialized AI agents +│ ├── hooks/ # 30 lifecycle hooks +│ │ ├── src/ # TypeScript source +│ │ └── dist/ # Compiled JavaScript +│ ├── skills/ # 109 modular capabilities +│ ├── rules/ # System policies +│ ├── scripts/ # Python utilities +│ └── settings.json # Hook configuration +├── opc/ +│ ├── packages/ +│ │ └── tldr-code/ # 5-layer code analysis +│ ├── scripts/ +│ │ ├── setup/ # Wizard, Docker, integration +│ │ └── core/ # recall_learnings, store_learning +│ └── docker/ +│ └── init-schema.sql # 4-table PostgreSQL schema +├── thoughts/ +│ ├── ledgers/ # Continuity ledgers (CONTINUITY_*.md) +│ └── shared/ +│ ├── handoffs/ # Session handoffs (*.yaml) +│ └── plans/ # Implementation plans +└── docs/ # Documentation +``` + +--- + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on: + +- Adding new skills +- Creating agents +- Developing hooks +- Extending TLDR + +--- + +## Acknowledgments + +### Patterns & Architecture +- **[@numman-ali](https://github.com/numman-ali)** - Continuity ledger pattern +- **[Anthropic](https://anthropic.com)** - Claude Code and "Code Execution with MCP" +- **[obra/superpowers](https://github.com/obra/superpowers)** - Agent orchestration patterns +- **[EveryInc/compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin)** - Compound engineering workflow +- **[yoloshii/mcp-code-execution-enhanced](https://github.com/yoloshii/mcp-code-execution-enhanced)** - Enhanced MCP execution +- **[HumanLayer](https://github.com/humanlayer/humanlayer)** - Agent patterns + +### Tools & Services +- **[uv](https://github.com/astral-sh/uv)** - Python packaging +- **[tree-sitter](https://tree-sitter.github.io/)** - Code parsing +- **[Braintrust](https://braintrust.dev)** - LLM evaluation, logging, and session tracing +- **[qlty](https://github.com/qltysh/qlty)** - Universal code quality CLI (70+ linters) +- **[ast-grep](https://github.com/ast-grep/ast-grep)** - AST-based code search and refactoring +- **[Nia](https://trynia.ai)** - Library documentation search +- **[Morph](https://www.morphllm.com)** - WarpGrep fast code search +- **[Firecrawl](https://www.firecrawl.dev)** - Web scraping API +- **[RepoPrompt](https://repoprompt.com)** - Token-efficient codebase maps + +--- + +## Star History + +[![Star History Chart](https://api.star-history.com/svg?repos=parcadei/Continuous-Claude-v2&type=timeline)](https://star-history.com/#parcadei/Continuous-Claude-v2&Date) + +--- + +## License + +[MIT](LICENSE) - Use freely, contribute back. + +--- + +## Documentation Confidence + +This documentation uses a 3-tier confidence system: + +| Tier | Meaning | Sections | +|------|---------|----------| +| **HIGH** | Verified against codebase, actively maintained | Architecture, Core Systems, Installation | +| **MEDIUM** | Based on code analysis, may have minor drift | Agent/Skill counts, Workflow chains | +| **LOW** | Inferred or aspirational, needs verification | Some advanced features | + +**Last verified:** 2026-02-04 + +### Component Counts (as of verification date) +- **Skills:** 108 active SKILL.md files across `.claude/skills/` +- **Agents:** 32 agent definitions in `.claude/agents/` +- **Hooks:** 34 TypeScript source files, ~30 registered in settings.json +- **MCP Servers:** 10 server integrations in `.claude/servers/` + +--- + +**Continuous Claude**: Not just a coding assistant—a persistent, learning, multi-agent development environment that gets smarter with every session. diff --git a/.auto-doc-timestamp b/.auto-doc-timestamp new file mode 100644 index 00000000..6c81425b --- /dev/null +++ b/.auto-doc-timestamp @@ -0,0 +1,22 @@ +# Auto-Documentation Timestamp +# Generated by Claude documentation agent + +last_run: 2026-02-05T02:32:00-08:00 +backup_dir: .auto-doc-history/20260205-023154 + +files_updated: + - README.md (updated component counts) + - docs/ARCHITECTURE.md (updated counts, added Lean proofs) + +verified_counts: + skills: 114 + agents: 48 + hooks_source: 34 + mcp_servers: 9 + lean_proofs: 108 + +notes: + - Updated component counts to match current codebase state + - Added Lean proof file count (108 files in proofs/) + - Existing documentation structure is comprehensive and accurate + - Backed up original files before modifications diff --git a/README.md b/README.md index 7d5d90ea..6f1cf9e3 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,9 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Claude Code](https://img.shields.io/badge/Claude-Code-orange.svg)](https://claude.ai/code) -[![Skills](https://img.shields.io/badge/Skills-109-green.svg)](#skills-system) -[![Agents](https://img.shields.io/badge/Agents-32-purple.svg)](#agents-system) -[![Hooks](https://img.shields.io/badge/Hooks-30-blue.svg)](#hooks-system) +[![Skills](https://img.shields.io/badge/Skills-114-green.svg)](#skills-system) +[![Agents](https://img.shields.io/badge/Agents-48-purple.svg)](#agents-system) +[![Hooks](https://img.shields.io/badge/Hooks-34-blue.svg)](#hooks-system) **Continuous Claude** transforms Claude Code into a continuously learning system that maintains context across sessions, orchestrates specialized agents, and eliminates wasting tokens through intelligent code analysis. @@ -18,9 +18,9 @@ - [Quick Start](#quick-start) - [Architecture](#architecture) - [Core Systems](#core-systems) - - [Skills (109)](#skills-system) - - [Agents (32)](#agents-system) - - [Hooks (30)](#hooks-system) + - [Skills (114)](#skills-system) + - [Agents (48)](#agents-system) + - [Hooks (34)](#hooks-system) - [TLDR Code Analysis](#tldr-code-analysis) - [Memory System](#memory-system) - [Continuity System](#continuity-system) @@ -184,7 +184,7 @@ uv run python -m scripts.setup.wizard | 2 | Check prerequisites (Docker, Python, uv) | | 3-5 | Database + API key configuration | | 6-7 | Start Docker stack, run migrations | -| 8 | Install Claude Code integration (32 agents, 109 skills, 30 hooks) | +| 8 | Install Claude Code integration (48 agents, 114 skills, 34 hooks) | | 9 | Math features (SymPy, Z3, Pint - optional) | | 10 | TLDR code analysis tool | | 11-12 | Diagnostics tools + Loogle (optional) | @@ -263,7 +263,7 @@ claude │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Skills │ │ Agents │ │ Hooks │ │ -│ │ (109) │───▶│ (32) │◀───│ (30) │ │ +│ │ (114) │───▶│ (48) │◀───│ (34) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ @@ -449,7 +449,7 @@ SessionStart Working SessionEnd ### Skills System -Skills are modular capabilities triggered by natural language. Located in `.claude/skills/`. +Skills are modular capabilities triggered by natural language. Located in `.claude/skills/` (114 skills). #### Meta-Skills (Workflow Orchestrators) @@ -584,7 +584,7 @@ What do I want to do? Agents are specialized AI workers spawned via the Task tool. Located in `.claude/agents/`. -#### Agent Categories (32 active) +#### Agent Categories (48 active) > **Note:** There are likely too many agents—consolidation is a v4 goal. Use what fits your workflow. @@ -636,7 +636,7 @@ Agents are specialized AI workers spawned via the Task tool. Located in `.claude Hooks intercept Claude Code at lifecycle points. Located in `.claude/hooks/`. -#### Hook Events (30 hooks total) +#### Hook Events (34 hooks total) | Event | Key Hooks | Purpose | |-------|-----------|---------| @@ -657,7 +657,7 @@ Hooks intercept Claude Code at lifecycle points. Located in `.claude/hooks/`. | **post-edit-diagnostics** | Runs pyright/ruff after edits | | **memory-awareness** | Surfaces relevant learnings | -[See all 30 hooks →](docs/hooks/) +[See all 34 hooks →](docs/hooks/) --- @@ -1012,9 +1012,9 @@ This will: | Component | Location | |-----------|----------| -| Agents (32) | ~/.claude/agents/ | -| Skills (109) | ~/.claude/skills/ | -| Hooks (30) | ~/.claude/hooks/ | +| Agents (48) | ~/.claude/agents/ | +| Skills (114) | ~/.claude/skills/ | +| Hooks (34) | ~/.claude/hooks/ | | Rules | ~/.claude/rules/ | | Scripts | ~/.claude/scripts/ | | PostgreSQL | Docker container | @@ -1182,11 +1182,11 @@ Services without API keys still work: ``` continuous-claude/ ├── .claude/ -│ ├── agents/ # 32 specialized AI agents -│ ├── hooks/ # 30 lifecycle hooks +│ ├── agents/ # 48 specialized AI agents +│ ├── hooks/ # 34 lifecycle hooks │ │ ├── src/ # TypeScript source │ │ └── dist/ # Compiled JavaScript -│ ├── skills/ # 109 modular capabilities +│ ├── skills/ # 114 modular capabilities │ ├── rules/ # System policies │ ├── scripts/ # Python utilities │ └── settings.json # Hook configuration @@ -1254,4 +1254,25 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on: --- +## Documentation Confidence + +This documentation uses a 3-tier confidence system: + +| Tier | Meaning | Sections | +|------|---------|----------| +| **HIGH** | Verified against codebase, actively maintained | Architecture, Core Systems, Installation | +| **MEDIUM** | Based on code analysis, may have minor drift | Agent/Skill counts, Workflow chains | +| **LOW** | Inferred or aspirational, needs verification | Some advanced features | + +**Last verified:** 2026-02-05 + +### Component Counts (as of verification date) +- **Skills:** 114 skill directories in `.claude/skills/` +- **Agents:** 48 agent definitions in `.claude/agents/` +- **Hooks:** 34 TypeScript source files in `.claude/hooks/src/` +- **MCP Servers:** 9 server integrations in `.claude/servers/` +- **Lean Proofs:** 108 `.lean` files in `proofs/` + +--- + **Continuous Claude**: Not just a coding assistant—a persistent, learning, multi-agent development environment that gets smarter with every session. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 5a74264d..0bb6a95e 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -40,7 +40,7 @@ The system has four main layers: **Skills** (what users can trigger), **Hooks** | v +-----------------------------------------------------------------------------------+ -| AGENT LAYER (41 agents) | +| AGENT LAYER (48 agents) | | | | ORCHESTRATORS IMPLEMENTERS EXPLORERS REVIEWERS | | +----------+ +----------+ +----------+ +----------+ | @@ -183,7 +183,7 @@ Hooks fire automatically at specific lifecycle points. Users don't invoke them d ## 3. Agent Layer -41 specialized agents, each with a defined role, model preference, and tool access. +48 specialized agents, each with a defined role, model preference, and tool access. ### Orchestration Agents @@ -781,8 +781,10 @@ Location: `.claude/hooks/src/` |--------|-------|-------| | Python functions | 2,328 | Across all `opc/scripts/` | | TypeScript hooks | 34 | Active in `.claude/hooks/src/` | -| Skills | 123 | In `.claude/skills/` | -| Agents | 41 | Defined in system prompt | +| Skills | 114 | Skill directories in `.claude/skills/` | +| Agents | 48 | Agent definitions in `.claude/agents/` | +| MCP Servers | 9 | Server integrations in `.claude/servers/` | +| Lean proofs | 108 | Formal verification files in `proofs/` | | Tests | 265+ | TLDR-code alone | | Entry layer functions | 1,057 | Called from outside | | Leaf functions | 729 | Utility/helper code | @@ -792,4 +794,20 @@ Location: `.claude/hooks/src/` --- +## 12. Documentation Confidence + +| Section | Confidence | Last Verified | +|---------|------------|---------------| +| Architecture Diagram | HIGH | 2026-02-04 | +| Capability Catalog | HIGH | 2026-02-04 | +| Hook Layer | HIGH | 2026-02-04 | +| Agent Layer | MEDIUM | 2026-02-04 | +| Infrastructure Layer | HIGH | 2026-02-04 | +| TLDR Analysis Results | MEDIUM | 2026-01-07 | +| Summary Statistics | HIGH | 2026-02-04 | + +--- + *This architecture document is generated by TLDR 5-layer analysis. Token cost: ~5,000 (vs ~50,000 raw files = 90% savings).* + +*Last updated: 2026-02-05*