Don't let LLMs make decisions. Design gates they cannot bypass.

┌─────────────────────────────────────────────────────────────┐
│  Upper Layer: Spec-Driven Development Workflow               │
│  Define "what to build" (spec creation, task decomposition)  │
└─────────────────────────────────────────────────────────────┘
                         ↓ Pass specs/tasks
┌─────────────────────────────────────────────────────────────┐
│  This Tool: Code Intelligence MCP Server                     │
│  Enforce "build exactly as specified"                        │
│  - Force 19-step execution: explore → verify rules → impl    │
│  - Server controls phase transitions (LLM cannot skip)       │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                    MCP Clients (Claude Code)                 │
└─────────────────────────────────────────────────────────────┘
                               │
                               ▼
                    ┌─────────────────┐
                    │   code-intel    │  ← Unified MCP server
                    │ (orchestrator)  │
                    └─────────────────┘
                               │
               ┌───────────────┼───────────────┐
               ▼               ▼               ▼
        ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
        │ ChromaDB    │ │ ripgrep     │ │ ctags       │
        │ (map/forest)│ │ (search)    │ │ (symbols)   │
        └─────────────┘ └─────────────┘ └─────────────┘
               │
               ▼
    ┌───────────────────┐
    │ Project/.code-intel│  ← Project-specific
    │ ├─ config.json     │
    │ ├─ chroma/         │  ← ChromaDB data
    │ ├─ agreements/     │
    │ ├─ logs/           │  ← DecisionLog, OutcomeLog
    │ └─ sync_state.json │
    └───────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│  Session Start                                                              │
│  Step 1: start_session (Intent detection → Initialization)                  │
│  Step 2: BRANCH_INTERVENTION (only when stale detected)                     │
│  Step 3: DOCUMENT_RESEARCH ← Skip with --no-doc                            │
│  Step 4: QUERY_FRAME                                                        │
└─────────────────────────────────────────────────────────────────────────────┘
                                    ↓
┌─────────────────────────────────────────────────────────────────────────────┐
│  Exploration Phase ← Skip with --fast/--quick                               │
│  Step 5:  EXPLORATION                                                       │
│  Step 6:  Q1 (SEMANTIC necessity check)                                     │
│  Step 7:  SEMANTIC (only when Q1=true)                                      │
│  Step 8:  Q2 (VERIFICATION necessity check)                                 │
│  Step 9:  VERIFICATION (only when Q2=true)                                  │
│  Step 10: Q3 (IMPACT_ANALYSIS necessity check)                              │
│  Step 11: IMPACT_ANALYSIS (only when Q3=true / research: SESSION_COMPLETE)  │
└─────────────────────────────────────────────────────────────────────────────┘
                                    ↓
┌─────────────────────────────────────────────────────────────────────────────┐
│  Implementation Phase                                                        │
│  Step 12: READY (task planning + branch creation)                           │
│  Step 13: READY (implementation ×N)                                         │
│  Step 14: READY (all tasks completion check)                                │
│  Step 15: POST_IMPL_VERIFY ← Skip with --no-verify / fail→Step 12          │
│  Step 16: VERIFY_INTERVENTION (only when failure_count ≥ 3)                 │
│  Step 17: PRE_COMMIT                                                        │
│  Step 18: QUALITY_REVIEW ← Skip with --no-quality                          │
│  Step 19: MERGE → SESSION_COMPLETE                                          │
└─────────────────────────────────────────────────────────────────────────────┘

# Clone the repository
git clone https://github.com/tech-spoke/llm-helper.git
cd llm-helper

# Setup server (venv, dependencies)
./setup.sh

# Initialize target project (indexes entire project)
./init-project.sh /path/to/your-project

# Option: Index specific directories only
./init-project.sh /path/to/your-project --include=src,packages

# Option: Specify additional exclude patterns
./init-project.sh /path/to/your-project --exclude=tests,docs,*.log

your-project/
├── .claude/
│   ├── CLAUDE.md          〇 Project rules for LLM (can add rules)
│   └── commands/          ← Skill files (auto-generated)
└── .code-intel/
    ├── config.json           ← Configuration (auto-generated)
    ├── context.yml           ◎ Project settings (see Step 6)
    ├── phase_contract.yml    ← Phase contract definitions (v1.13)
    ├── task_planning.md      〇 Task decomposition guide (v1.11)
    ├── user_escalation.md    〇 User escalation procedures
    ├── chroma/               ← ChromaDB data (auto-managed)
    ├── sessions/             ← Checkpoints (auto-managed)
    ├── agreements/           ← Success patterns (auto-managed)
    ├── logs/                 ← DecisionLog, OutcomeLog (auto-managed)
    ├── verifiers/            ★ Verification prompts (can add/modify)
    ├── doc_research/         ★ Document research prompts (can add/modify)
    ├── interventions/        ★ Intervention prompts (can add/modify)
    └── review_prompts/       ★ Quality review prompts (can add/modify)

{
  "mcpServers": {
    "code-intel": {
      "type": "stdio",
      "command": "/path/to/llm-helper/venv/bin/python",
      "args": ["/path/to/llm-helper/code_intel_server.py"],
      "env": {"PYTHONPATH": "/path/to/llm-helper"}
    }
  }
}

# In Claude Code
/code --help

cp -r /path/to/llm-helper/templates/skills/codex/* "$CODEX_HOME/skills/"

# Project rules (auto-detected: CLAUDE.md, .claude/CLAUDE.md, CONTRIBUTING.md)
project_rules:
  source: "CLAUDE.md"

# Document search settings for analyze_impact
document_search:
  include_patterns:
    - "**/*.md"
    - "**/README*"
    - "**/docs/**/*"
  exclude_patterns:
    - "node_modules/**"
    - "vendor/**"
    - ".git/**"

# v1.3: Document research settings
doc_research:
  enabled: true
  docs_path:
    - "docs/"
  default_prompts:
    - "default.md"

# v1.4: Intervention system settings
interventions:
  enabled: true
  prompts_dir: "interventions/"
  threshold: 3  # Failure count before intervention triggers

# Verifier settings
verifiers:
  suggest_improvements: true

/code Fix the bug in AuthService's login function where no error is shown when password is empty

# Full mode (default): exploration + implementation + verification + cleanup + quality
/code add login feature

# Skip verification (also skips intervention)
/code --no-verify fix this bug

# Skip quality review only
/code --no-quality fix simple typo

# Verification only (check existing implementation)
/code -v sample/hello.html

# Exploration only (no implementation, for investigation)
/code -e investigate issues in the codebase

# Fast mode (skip exploration, with branch, for known fixes)
/code -f fix known issue in login validation

# Quick mode (minimal, no branch)
/code -q change the button color to blue

# Skip document research (v1.3)
/code --no-doc-research fix typo

# Resume from checkpoint
/code -r

# Clean up stale sessions
/code -c

# Force rebuild all indexes
/code --rebuild

llm-helper/
├── code_intel_server.py    ← MCP server main
├── tools/                  ← Tool implementations
│   ├── session.py          ← Session management
│   ├── query_frame.py      ← QueryFrame
│   ├── router.py           ← Query routing
│   ├── chromadb_manager.py ← ChromaDB management
│   ├── ast_chunker.py      ← AST chunking
│   ├── sync_state.py       ← Sync state management
│   ├── outcome_log.py      ← Improvement cycle logging
│   ├── context_provider.py ← Required context (v1.1)
│   ├── impact_analyzer.py  ← Impact analysis (v1.1)
│   ├── branch_manager.py   ← Git branch isolation (v1.2)
│   └── ...
├── setup.sh                ← Server setup
├── init-project.sh         ← Project initialization
└── templates/
    ├── code-intel/         ← .code-intel templates
    └── skills/
        ├── claude/         ← Claude skill templates
        └── codex/          ← Codex skill templates