kraken-code 1.1.2 → 1.1.3

package/README.md

@@ -1,464 +1,217 @@
-# Kraken Code
+# Kraken Code v1.0
 
 <div align="center">
 
-![Version](https://img.shields.io/badge/v1.1.0-brightgreen?labelColor=0e8fd0&style=flat-square)
-![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)
-![Runtime](https://img.shields.io/badge/runtime-Bun%20%7C%20Node.js-darkgreen?style=flat-square)
-![Platform](https://img.shields.io/badge/platform-OpenCode-informational?style=flat-square)
-
-**Transform OpenCode into an autonomous, high-density development environment**
-
-[Documentation](#documentation) • [Quick Start](#quick-start) • [Examples](#examples) • [Changelog](CHANGELOG.md)
+![Version](https://img.shields.io/badge/v1.0-brightgreen?labelColor=0e8fd0&style=flat-square)
+![License](https://img.shields.io/badge/license-MIT?labelColor=black&style=flat-square)
+![Bun](https://img.shields.io/badge/bun-1.2%2B-white?labelColor=%231F27&style=flat-square)
+![OpenCode](https://img.shields.io/badge/compatibility-green?label=OpenCode&style=flat-square)
 
 </div>
 
 ---
 
-## 🦑 What is Kraken Code?
-
-Kraken Code is a comprehensive plugin that supercharges [OpenCode](https://opencode.ai) with:
-
-- **11 specialized AI agents** for every development phase
-- **TDD enforcement** via Blitzkrieg mode
-- **Persistent memory** across sessions with Kratos
-- **Dynamic skills** for custom workflows
-- **30+ hooks** for deep customization
-- **MCP integrations** for web search, documentation, and GitHub
-- **LSP tools** for code intelligence
-- **CLI utilities** for project management
-
-Think of it as giving OpenCode a second brain—one that remembers context, delegates intelligently, and enforces best practices automatically.
-
----
-
-## ✨ Key Features
-
-### 🧠 Specialized Agents
-| Agent | Specialty |
-|-------|-----------|
-| **Kraken** | Architecture & orchestration |
-| **Atlas** | Planning & task breakdown |
-| **Nautilus** | Code exploration & search |
-| **Abyssal** | Deep analysis & debugging |
-| **Coral** | Building & construction |
-| **Siren** | Documentation & communication |
-| **Scylla** | Testing & validation |
-| **Pearl** | Refactoring & optimization |
-| **Poseidon** | Data & infrastructure |
-| **Leviathan** | Large-scale refactoring |
-| **Maelstrom** | First-principles reasoning |
+> **Kraken Code transforms OpenCode into an autonomous, high-density development environment.**  
+> Think of it as giving OpenCode a second brain—one that remembers context, delegates intelligently, and enforces best practices automatically.
 
-### 🎯 Production Modes
-
-- **Blitzkrieg** - Strict TDD enforcement with guardrails
-- **Ultrawork** - Parallel agent execution for speed
-- **Ultrathink** - Maximum reasoning with expanded context
-
-### 💾 Persistent Memory
-
-- **Kratos MCP** - Ultra-lean memory system
-- Save decisions, patterns, and lessons
-- Natural language queries
-- Cross-session retention
-
-### 🪝 Extensibility
-
-- **Skills System** - Hot-reloadable workflow templates
-- **30+ Hooks** - Context, coordination, error recovery
-- **Commands** - Built-in and custom commands
-- **MCP Protocol** - Extensible server integrations
-
-### 🔍 Code Intelligence
-
-- **12 LSP tools** for code analysis
-- **16 language servers** supported
-- AST-based search with ast-grep
-- Context compression (70% token reduction)
-
----
-
-## 🚀 Quick Start
-
-### Installation
+## Quick Start
 
 ```bash
-# Using Bun (recommended)
+# Install Kraken Code
 bun install kraken-code
 
-# Using npm
+# Or with npm
 npm install kraken-code
-```
-
-### Configuration
-
-Add to your OpenCode config `~/.config/opencode/opencode.json`:
 
-```json
-{
-  "plugin": ["kraken-code"]
-}
-```
+# Or with curl (for non-package-manager users)
+bash scripts/install-curl.sh
 
-That's it! Kraken Code auto-configures and integrates seamlessly.
-
-### Initialize with Recommended Settings
-
-```bash
-# Full setup (all features)
-kraken-code init --full
-
-# Minimal setup (agents only)
+# Initialize with minimal setup (agents only)
 kraken-code init --minimal
-```
-
----
 
-## 🎨 Usage Examples
-
-### Using Specific Agents
-
-```bash
-# Planning
-opencode run --agent Atlas "Plan a REST API for a todo app"
-
-# Exploration
-opencode run --agent Nautilus "Find all async functions without error handling"
-
-# Debugging
-opencode run --agent Abyssal "Investigate why memory usage increases over time"
-
-# Testing
-opencode run --agent Scylla "Write tests for the authentication module"
-```
-
-### Blitzkrieg TDD Mode
-
-```bash
-# Enable Blitzkrieg for strict test-driven development
-opencode run "Enable Blitzkrieg mode"
-
-# Now all tasks enforce TDD
-opencode run "Implement user registration"
-# → Blitzkrieg: "Please provide a test plan first..."
-```
-
-### Memory with Kratos
-
-```bash
-# Save a decision
-opencode run "Save to Kratos: Decided to use PostgreSQL for better JSON support"
-
-# Search past decisions
-opencode run "Search Kratos for: what database did we choose and why?"
+# Or initialize with full setup (all features)
+kraken-code init --full
 
-# Natural language queries
-opencode run "Ask Kratos: what patterns have we used for error handling?"
+# Run OpenCode
+opencode
 ```
 
-### MCP Integrations
+**Important:** After installation, you must run `kraken-code init` to create the proper configuration. The CLI command adds the plugin to your `~/.config/opencode/opencode.json` file and sets up all Kraken Code features.
 
-```bash
-# Web search
-opencode run "Use websearch to find best practices for React state management"
-
-# Official docs
-opencode run "Use Context7 to find TypeScript utility types"
-
-# GitHub code search
-opencode run "Use grep-app to find Express middleware examples"
-```
+For detailed installation options, run: `kraken-code --help`
 
 ---
 
-## 🔧 CLI Commands
+## What Kraken Does for You
 
-Kraken Code includes a powerful CLI for project management:
+### 🧠 **Intelligent Delegation**
 
-```bash
-# Check installation status
-kraken-code status
+Don't do everything yourself. Kraken routes work to the right specialist automatically:
 
-# Run system diagnostics
-kraken-code doctor
+- **Architecture decisions?** → Ask **Atlas** (merged Maelstrom + Leviathan expertise)
+- **Deep analysis needed?** → Deploy **Abyssal** for external research
+- **Building UI?** → Hand to **Coral** for visual precision
+- **Writing docs?** → Let **Siren** craft clear documentation
+- **Complex test failures?** → Consult **Scylla** for test strategy
+- **Infrastructure work?** → **Poseidon** handles data pipelines and CI/CD
 
-# Check specific category
-kraken-code doctor -c agents
-kraken-code doctor -c blitzkrieg
+### ⚡ **Production Modes**
 
-# Verbose diagnostics
-kraken-code doctor --verbose
+Four expert modes that reconfigure the entire system:
 
-# JSON output for automation
-kraken-code doctor --json
-```
+- **Blitzkrieg** - TDD enforcement, rapid iteration with guardrails
+- **Search** - Multi-angle codebase exploration with Nautilus auto-firing
+- **Analyze** - Deep debugging with 100+ language keyword detection
+- **Ultrathink** - Maximum reasoning budget for complex problems
 
----
+### 🧠 **Persistent Memory**
 
-## ⚙️ Configuration
+Kratos remembers everything across sessions—conversations, decisions, code patterns. No more repeating yourself or asking the same questions.
 
-### Agent Configuration
+### 🛠 **Smart Tooling**
 
-```json
-{
-  "kraken_code": {
-    "agents": {
-      "default": "Kraken",
-      "enabled": ["Kraken", "Atlas", "Nautilus", "Abyssal", "Coral", "Siren", "Scylla", "Pearl", "Poseidon", "Leviathan", "Maelstrom"]
-    }
-  }
-}
-```
+- **GitHub integration** - PR/issue management, code search across repos
+- **Git integration** - Diff management, blame, commit optimization
+- **LSP superpowers** - Enhanced hover, code actions, refactoring
+- **Session search** - Find that solution from 3 sessions ago in seconds
 
-### Blitzkrieg Configuration
+### 📋 **Built-in Commands & Skills**
 
-```json
-{
-  "kraken_code": {
-    "blitzkrieg": {
-      "enabled": true,
-      "testPlanEnforcer": {
-        "enabled": true,
-        "requireTestPlan": true
-      },
-      "tddWorkflow": {
-        "enabled": true,
-        "enforceTestFirst": true
-      },
-      "evidenceVerifier": {
-        "enabled": true,
-        "requireTestResults": true
-      }
-    }
-  }
-}
-```
-
-### Kratos Memory Configuration
-
-```json
-{
-  "kraken_code": {
-    "kratos": {
-      "enabled": true,
-      "storagePath": "~/.kratos"
-    }
-  }
-}
-```
-
-### Schema Autocomplete
-
-Add to your config for IDE autocomplete:
-
-```json
-{
-  "$schema": "https://raw.githubusercontent.com/leviathofnoesia/kraken-code/main/assets/kraken-code.schema.json"
-}
-```
+10+ commands (`kraken-code --help`) and dynamic skill loading from `~/.config/opencode/skill/`. Write a skill once, use it everywhere.
 
 ---
 
-## 🏗️ Architecture
+## Why Kraken?
 
-### Core Components
+**OpenCode is powerful. Kraken makes it unstoppable.**
 
-- **Agent System** - 11 domain-specialized AI agents
-- **Feature System** - Skills, commands, MCP, memory
-- **Hook System** - 30+ hooks for customization
-- **Tool System** - grep, ast-grep, compression, session management
-- **Integrations** - GitHub SDK, Git SDK, LSP tools
+| OpenCode Alone | With Kraken |
+|---------------|--------------|
+| Ask a question → forgets context | Ask a question → Kratos remembers |
+| Do work → guess what's next | Do work → Blitzkrieg enforces quality |
+| Explore → manual grep searches | Explore → Nautilus auto-fires on patterns |
+| Multi-step tasks → one-shot guessing | Multi-step tasks → Atlas breaks down properly |
+| Change scope → context bloats out | Change scope → Kratos prunes intelligently |
 
-### File Structure
+**The Value Proposition:**
 
-```
-src/
-├── agents/          # Agent definitions and prompts
-├── features/        # Skills, blitzkrieg, kratos, commands
-├── hooks/           # Hook implementations
-├── tools/           # Tool implementations
-├── integrations/    # GitHub, Git, LSP, MCP
-├── config/          # Schema and validation
-└── cli/             # CLI commands
-```
+1. **You work faster** - Agents handle specialized tasks while you focus on the big picture
+2. **Your code is better** - Blitzkrieg enforces TDD, Scylla validates tests
+3. **You stop repeating work** - Kratos remembers solutions, patterns, decisions
+4. **You navigate larger codebases** - Nautilus finds patterns you'd miss
+5. **You get unstuck faster** - Atlas breaks down complex problems before you start
 
 ---
 
-## 📊 Production Readiness
-
-### Enterprise Features
-
-- ✅ **TDD Enforcement** - Blitzkrieg ensures code quality
-- ✅ **Persistent Memory** - Decisions survive across sessions
-- ✅ **Audit Trail** - Session history and tracking
-- ✅ **Customizable** - Skills, hooks, and configuration
-- ✅ **Diagnostics** - Built-in health checks
-- ✅ **Documentation** - Comprehensive guides and examples
-
-### Performance
+## Core Capabilities
 
-- **Context Pruning** - 70% token reduction with DCP engine
-- **Hook Performance** - <50ms execution (p95)
-- **Storage Efficiency** - JSONL for fast appends
-- **LSP Integration** - Native tool support
-
-### Reliability
-
-- **Zod Validation** - Type-safe configuration
-- **Error Recovery** - Multiple error recovery hooks
-- **Session Persistence** - Continue where you left off
-- **Auto-Update Checking** - Stay current with latest features
-
----
+### 🌊 **11 Sea-Themed Agents**
 
-## 🧪 Testing & Quality
+Each agent has a personality, a specialty, and knows when to step in:
 
-Run tests with:
-
-```bash
-bun test
 ```
-
-Type checking:
-
-```bash
-bun run typecheck
+Kraken     → Orchestrates everything, keeps you on track
+Atlas      → Breaks down complex tasks systematically
+Nautilus   → Explores codebases, finds patterns automatically
+Abyssal    → Researches external docs, libraries, APIs
+Coral       → Builds UI with design sensibility
+Siren       → Writes clear, structured documentation
+Scylla      → Creates comprehensive tests, validates coverage
+Pearl       → Refactors for performance, readability
+Maelstrom   → First-principles reasoning for hard problems
+Leviathan  → Manages large-scale refactors, architecture
+Poseidon    → Handles infrastructure, data pipelines
 ```
 
----
-
-## 📚 Documentation
-
-| Document | Description |
-|----------|-------------|
-| [FEATURES.md](FEATURES.md) | Complete feature overview |
-| [EXAMPLES.md](EXAMPLES.md) | Practical usage examples |
-| [FAQ.md](FAQ.md) | Common questions |
-| [TROUBLESHOOTING.md](TROUBLESHOOTING.md) | Common issues and solutions |
-| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution guidelines |
-| [CHANGELOG.md](CHANGELOG.md) | Version history |
+### 🏎️ **Blitzkrieg System**
 
-### Architecture Documentation
+Production-ready TDD workflow:
 
-- [Unified AI Memory Architecture](UNIFIED_AI_MEMORY_ARCHITECTURE.md) - Complete specification (600+ lines)
-- [Implementation Status](IMPLEMENTATION_STATUS.md) - Development progress
+- **Test Plan Enforcer** - No implementation without test plans
+- **TDD Workflow** - Write tests first, verify, then implement
+- **Evidence Verifier** - Requires passing tests before completion
+- **Planner Constraints** - Limits step complexity, prevents analysis paralysis
 
----
-
-## 🤝 Contributing
+### 💾 **Session & Memory Management**
 
-Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+- **Session tools** - List, read, search sessions
+- **Kratos memory** - Save, search, query memories naturally
+- **JSONL storage** - OpenCode-compatible transcript format
+- **Todo tracking** - Persistent task tracking across sessions
 
-### Development Setup
+### 🔌 **MCP Integration**
 
-```bash
-# Clone the repo
-git clone https://github.com/leviathofnoesia/kraken-code.git
-cd kraken-code
+Built-in MCP servers:
 
-# Install dependencies
-bun install
-
-# Build
-bun run build
-
-# Run tests
-bun test
-```
+- **Kratos** - Ultra-lean memory system
+- **Websearch** - Exa AI web search
+- **Context7** - Official documentation lookup
+- **Grep App** - GitHub code search
 
 ---
 
-## 📈 Roadmap
-
-### Upcoming Features
-
-- [ ] **Unified AI Memory** - Full integration of 4-layer learning system (in progress)
-  - Experience store with reinforcement learning
-  - Knowledge graph for entity relationships
-  - Pattern detection for wins/losses
-  - State machine for behavioral control
-  - FSRS scheduling for optimal review
-
-- [ ] **Hierarchical State Machines** - Nested FSM support
-- [ ] **Vector Embeddings** - Semantic similarity search
-- [ ] **Advanced RL** - ε-greedy exploration, off-policy evaluation
+## Configuration
 
-See [IMPLEMENTATION_STATUS.md](IMPLEMENTATION_STATUS.md) for details.
-
----
-
-## ❓ FAQ
-
-<details>
-<summary><b>How do I enable/disable specific agents?</b></summary>
-
-Edit your OpenCode config:
+All configuration lives in `~/.config/opencode/opencode.json`:
 
 ```json
 {
-  "kraken_code": {
-    "agents": {
-      "enabled": ["Atlas", "Nautilus", "Scylla"]
-    }
+  "default_agent": "Kraken",
+  "agents": {
+    "Kraken": { "enabled": true, "model": "..." }
+  },
+  "blitzkrieg": { "enabled": true, "enforcement": "strict" },
+  "kratos": { "enabled": true, "storagePath": "~/.kratos" },
+  "modes": {
+    "blitzkrieg": { "enabled": true },
+    "ultrathink": { "enabled": true, "thinkingBudget": 32000 }
   }
 }
 ```
-</details>
-
-<details>
-<summary><b>Can I use Kraken Code with other OpenCode plugins?</b></summary>
 
-Yes! Kraken Code is designed to work alongside other plugins. Configure multiple plugins in your `opencode.json`:
-
-```json
-{
-  "plugin": ["kraken-code", "other-plugin"]
-}
-```
-</details>
+Run `kraken-code init --full` for recommended defaults.
 
-<details>
-<summary><b>How do I create custom skills?</b></summary>
+---
 
-Create a directory with a `SKILL.md` file:
+## CLI Commands
 
 ```bash
-mkdir -p ~/.config/opencode/skill/my-workflow
-```
+# Install Kraken Code
+kraken-code install
 
-Create `~/.config/opencode/skill/my-workflow/SKILL.md` with your instructions. Skills are automatically discovered and hot-reloaded.
-</details>
-
-<details>
-<summary><b>Is the learning system (unified AI memory) available?</b></summary>
-
-The unified AI memory system architecture is complete but **not yet integrated**. Core implementation exists (3,400+ lines) but requires hook integration and tool registration. See [IMPLEMENTATION_STATUS.md](IMPLEMENTATION_STATUS.md) for progress.
-</details>
-
-<details>
-<summary><b>How do I troubleshoot issues?</b></summary>
+# Initialize with full setup
+kraken-code init --full
 
-Run diagnostics:
+# Check system health
+kraken-code doctor
 
-```bash
-kraken-code doctor --verbose
+# Show configuration
+kraken-code status
 ```
 
-Check [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common solutions.
-</details>
-
 ---
 
-## 🔗 Links
+## Architecture
+
+```
+src/
+├── agents/           # 11 sea-themed agents
+├── features/
+│   ├── skills/      # Skills system with discovery & hot-reload
+│   ├── mcp/        # Built-in MCP servers
+│   ├── blitzkrieg/  # TDD enforcement system
+│   └── storage/     # Session & memory management
+├── hooks/           # 31+ hooks for extensibility
+├── tools/           # LSP, session, GitHub, Git integrations
+├── cli/             # Commands & doctor
+└── config/           # Zod schema validation
+```
 
-- **GitHub**: https://github.com/leviathofnoesia/kraken-code
-- **Issues**: https://github.com/leviathofnoesia/kraken-code/issues
-- **OpenCode**: https://opencode.ai
-- **Discord**: https://discord.gg/clawd
+Each feature module can be enabled/disabled independently.
 
 ---
 
-## 📄 License
+## License
 
 MIT License - see [LICENSE](LICENSE) for details.
 
@@ -466,8 +219,8 @@ MIT License - see [LICENSE](LICENSE) for details.
 
 <div align="center">
 
-**Built with 🦑 by [LeviathofNoesia](https://github.com/leviathofnoesia)**
+**Built for developers who want more than just an AI assistant.**
 
-[⬆ Back to top](#kraken-code)
+**Built for autonomous development.**
 
 </div>