loki-mode 4.2.0 → 5.1.2

package/skills/model-selection.md

@@ -1,30 +1,77 @@
 # Model Selection & Task Tool
 
+## Multi-Provider Support (v5.0.0)
+
+Loki Mode supports three AI providers. Claude has full features; Codex and Gemini run in **degraded mode** (sequential execution only, no Task tool, no parallel agents).
+
+| Provider | Full Features | Degraded | CLI Flag |
+|----------|---------------|----------|----------|
+| **Claude Code** | Yes | No | `--provider claude` (default) |
+| **OpenAI Codex CLI** | No | Yes | `--provider codex` |
+| **Google Gemini CLI** | No | Yes | `--provider gemini` |
+
+**Degraded mode limitations:**
+- No Task tool (cannot spawn subagents)
+- No parallel execution (sequential RARV cycle only)
+- No MCP server integration
+- Single model with parameter adjustment (effort/thinking level)
+
+---
+
+## Abstract Model Tiers
+
+| Tier | Purpose | Claude | Codex | Gemini |
+|------|---------|--------|-------|--------|
+| **planning** | PRD analysis, architecture, system design | opus | effort=xhigh | thinking=high |
+| **development** | Feature implementation, complex bugs, tests | sonnet | effort=high | thinking=medium |
+| **fast** | Unit tests, docs, linting, simple tasks | haiku | effort=low | thinking=low |
+
+---
+
 ## Model Selection by SDLC Phase
 
-| Model | SDLC Phases | Examples |
-|-------|-------------|----------|
-| **Opus 4.5** | Bootstrap, Discovery, Architecture | PRD analysis, system design, technology selection, API contracts |
-| **Sonnet 4.5** | Development, QA, Deployment | Feature implementation, complex bugs, integration/E2E tests, code review, deployment |
-| **Haiku 4.5** | All other operations (parallel) | Unit tests, docs, bash commands, linting, monitoring |
+| Tier | SDLC Phases | Examples |
+|------|-------------|----------|
+| **planning** | Bootstrap, Discovery, Architecture | PRD analysis, system design, technology selection, API contracts |
+| **development** | Development, QA, Deployment | Feature implementation, complex bugs, integration/E2E tests, code review, deployment |
+| **fast** | All other operations (parallel for Claude) | Unit tests, docs, bash commands, linting, monitoring |
 
-## Task Tool Examples
+**Claude-specific model names:** opus, sonnet, haiku
+**Codex effort levels:** xhigh, high, medium, low
+**Gemini thinking levels:** high, medium, low
+
+## Task Tool Examples (Claude Only)
+
+**NOTE:** Task tool is Claude-specific. Codex and Gemini run in degraded mode without subagents.
 
 ```python
-# Opus for Bootstrap, Discovery, Architecture (planning ONLY)
+# Planning tier (opus) for Bootstrap, Discovery, Architecture
 Task(subagent_type="Plan", model="opus", description="Design system architecture", prompt="...")
 Task(subagent_type="Plan", model="opus", description="Analyze PRD requirements", prompt="...")
 
-# Sonnet for Development, QA, and Deployment
+# Development tier (sonnet) for Development, QA, and Deployment
 Task(subagent_type="general-purpose", model="sonnet", description="Implement API endpoint", prompt="...")
 Task(subagent_type="general-purpose", model="sonnet", description="Write integration tests", prompt="...")
 Task(subagent_type="general-purpose", model="sonnet", description="Deploy to production", prompt="...")
 
-# Haiku for everything else (PREFER for parallelization)
+# Fast tier (haiku) for everything else (PREFER for parallelization)
 Task(subagent_type="general-purpose", model="haiku", description="Run unit tests", prompt="...")
 Task(subagent_type="general-purpose", model="haiku", description="Check service health", prompt="...")
 ```
 
+### Provider Detection in Code
+
+```bash
+# In run.sh, check provider before using Task tool
+if [ "${PROVIDER_HAS_TASK_TOOL:-false}" = "true" ]; then
+    # Claude: Use Task tool with parallel agents
+    Task(model="haiku", description="Run tests", prompt="...")
+else
+    # Codex/Gemini: Run sequentially without subagents
+    # Execute RARV cycle in main thread
+fi
+```
+
 ## Task Categories
 
 **Opus (Bootstrap -> Architecture - Planning ONLY):**
@@ -45,14 +92,20 @@ Task(subagent_type="general-purpose", model="haiku", description="Check service
 - File operations, linting, static analysis
 - Monitoring, health checks, log analysis
 
-## Parallelization Strategy
+## Parallelization Strategy (Claude Only)
+
+**NOTE:** Parallelization requires Task tool, which is Claude-specific. Codex and Gemini run sequentially.
 
 ```python
-# Launch 10+ Haiku agents in parallel for unit test suite
+# Claude: Launch 10+ Haiku agents in parallel for unit test suite
 for test_file in test_files:
     Task(subagent_type="general-purpose", model="haiku",
          description=f"Run unit tests: {test_file}",
          run_in_background=True)
+
+# Codex/Gemini: Run tests sequentially (no parallelization)
+for test_file in test_files:
+    run_test(test_file)  # Sequential execution
 ```
 
 ## Extended Thinking Mode

package/skills/providers.md

@@ -0,0 +1,184 @@
+# Multi-Provider Support
+
+Loki Mode v5.0.0 supports three AI providers for autonomous execution.
+
+## Provider Comparison
+
+> **Note:** The model names for Codex (`gpt-5.2-codex`) and Gemini (`gemini-3-pro-medium`) are placeholder values. Update the provider configuration files (`providers/codex.sh` and `providers/gemini.sh`) with actual model identifiers when official CLI documentation becomes available.
+
+> **CLI Flags Verified:** The autonomous mode flags have been verified against actual CLI help output:
+> - Claude: `--dangerously-skip-permissions` (verified)
+> - Codex: `exec --dangerously-bypass-approvals-and-sandbox` (verified v0.89.0)
+> - Gemini: `--yolo` (verified v0.25.2) - Note: `-p` prompt flag is deprecated, using positional prompts
+
+| Feature | Claude Code | OpenAI Codex | Gemini CLI |
+|---------|-------------|--------------|------------|
+| **Full Features** | Yes | No (Degraded) | No (Degraded) |
+| **Task Tool (Subagents)** | Yes | No | No |
+| **Parallel Agents** | Yes (10+) | No | No |
+| **MCP Integration** | Yes | No | No |
+| **Context Window** | 200K | 128K | 1M |
+| **Model Tiers** | 3 (opus/sonnet/haiku) | 1 (effort param) | 1 (thinking param) |
+| **Skill Directory** | ~/.claude/skills | None | None |
+
+## Provider Selection
+
+```bash
+# Via environment variable
+export LOKI_PROVIDER=claude  # or codex, gemini
+
+# Via CLI flag
+./autonomy/run.sh --provider codex ./prd.md
+loki start --provider gemini ./prd.md
+```
+
+## Claude Code (Default, Full Features)
+
+**Best for:** All use cases. Full autonomous capability.
+
+**Capabilities:**
+- Task tool for spawning subagents
+- Parallel execution (10+ agents simultaneously)
+- MCP server integration
+- Three distinct models (opus/sonnet/haiku)
+- 200K context window
+
+**Invocation:**
+```bash
+claude --dangerously-skip-permissions -p "$prompt"
+```
+
+**Model Selection:**
+```python
+Task(model="opus", ...)    # Planning tier
+Task(model="sonnet", ...)  # Development tier
+Task(model="haiku", ...)   # Fast tier (parallelize)
+```
+
+---
+
+## OpenAI Codex CLI (Degraded Mode)
+
+**Best for:** Teams standardized on OpenAI. Accepts feature tradeoffs.
+
+**Limitations:**
+- No Task tool (cannot spawn subagents)
+- No parallel execution (sequential only)
+- No MCP integration
+- Single model with effort parameter
+- 128K context window
+
+**Invocation:**
+```bash
+codex exec --dangerously-bypass-approvals-and-sandbox "$prompt"
+```
+
+**Model Tiers via Effort (env var, not CLI flag):**
+
+Note: Codex does not support `--effort` as a CLI flag. Reasoning effort must be configured via environment variable or config file.
+
+```bash
+# Set effort via environment
+CODEX_MODEL_REASONING_EFFORT=high codex exec --dangerously-bypass-approvals-and-sandbox "$prompt"
+```
+
+| Tier | Effort | Use Case |
+|------|--------|----------|
+| planning | xhigh | Architecture, PRD analysis |
+| development | high | Feature implementation, tests |
+| fast | low | Simple fixes, docs |
+
+---
+
+## Google Gemini CLI (Degraded Mode)
+
+**Best for:** Teams standardized on Google. Large context needs (1M tokens).
+
+**Limitations:**
+- No Task tool (cannot spawn subagents)
+- No parallel execution (sequential only)
+- No MCP integration
+- Single model with thinking_level parameter
+- 1M context window (largest)
+
+**Invocation:**
+```bash
+# Note: -p flag is DEPRECATED. Using positional prompt.
+gemini --yolo "$prompt"
+```
+
+**Model Tiers via Thinking Level (settings.json, not CLI flag):**
+
+Note: Gemini CLI does not support `--thinking-level` as a CLI flag. Thinking mode must be configured in `~/.gemini/settings.json`.
+
+```json
+// ~/.gemini/settings.json
+{
+  "thinkingMode": "medium"  // high, medium, low
+}
+```
+
+| Tier | Thinking | Use Case |
+|------|----------|----------|
+| planning | high | Architecture, PRD analysis |
+| development | medium | Feature implementation, tests |
+| fast | low | Simple fixes, docs |
+
+---
+
+## Degraded Mode Behavior
+
+When running with Codex or Gemini:
+
+1. **RARV Cycle executes sequentially** - No parallel agents
+2. **Task tool calls are skipped** - Main thread handles all work
+3. **Model tier maps to provider configuration:**
+   - Codex: `CODEX_MODEL_REASONING_EFFORT` env var (xhigh/high/medium/low)
+   - Gemini: `~/.gemini/settings.json` thinkingMode (high/medium/low)
+4. **Quality gates run sequentially** - No 3-reviewer parallel review
+5. **Git worktree parallelism disabled** - `--parallel` flag has no effect
+
+**Example output:**
+```
+[INFO] Provider: OpenAI Codex CLI (codex)
+[WARN] Degraded mode: Parallel agents and Task tool not available
+[INFO] Limitations:
+[INFO]   - No Task tool subagent support - cannot spawn parallel agents
+[INFO]   - Single model with effort parameter - no cheap tier for parallelization
+```
+
+---
+
+## Provider Configuration Files
+
+Provider configs are shell-sourceable files in `providers/`:
+
+```
+providers/
+  claude.sh   # Full-featured provider
+  codex.sh    # Degraded mode, effort parameter
+  gemini.sh   # Degraded mode, thinking_level parameter
+  loader.sh   # Provider loader utility
+```
+
+**Key variables:**
+```bash
+PROVIDER_NAME="claude"
+PROVIDER_HAS_SUBAGENTS=true
+PROVIDER_HAS_PARALLEL=true
+PROVIDER_HAS_TASK_TOOL=true
+PROVIDER_DEGRADED=false
+```
+
+---
+
+## Choosing a Provider
+
+| If you need... | Choose |
+|----------------|--------|
+| Full autonomous capability | Claude |
+| Parallel agent execution | Claude |
+| MCP server integration | Claude |
+| OpenAI ecosystem compatibility | Codex |
+| Largest context window (1M) | Gemini |
+| Sequential-only is acceptable | Codex or Gemini |