kraken-code 1.1.3 → 1.2.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,68 @@
+# Kraken Code Architecture
+
+Kraken Code is structured as a plugin that augments OpenCode with orchestration, hooks, tooling, and a unified learning system.
+
+## High-Level Components
+
+```
+src/
+├── agents/                # Sea-themed agents with focused roles
+├── features/
+│   ├── memory/            # Unified learning system (experience store, knowledge graph)
+│   ├── mcp/               # Built-in MCP servers (websearch, context7, grep_app)
+│   ├── background-agent/  # Background task orchestration
+│   ├── skill-mcp-manager/ # Skill-defined MCP servers
+│   └── command-loader/    # Built-in command loader
+├── hooks/                 # Lifecycle hooks for OpenCode integration
+├── tools/                 # CLI-style tools exposed to OpenCode
+├── config/                # Zod schemas + config manager
+└── storage/               # Session transcripts and todo persistence
+```
+
+## Unified Learning System
+
+The learning subsystem is designed to replace the legacy Kratos memory integration with a cohesive, on-disk learning store.
+
+### Core Stores
+
+- **Experience Store**: Captures decisions, outcomes, and context from real sessions.
+- **Knowledge Graph**: Nodes and edges for structured knowledge and references.
+- **Pattern Detection**: Tracks recurring signals and confidence levels.
+- **Spaced Repetition**: Schedules reviews of important knowledge nodes.
+- **State Machines**: Tracks multi-step workflows and learning loops.
+
+### Persistence Model
+
+All learning data is stored in `~/.kraken/learning/learning-state.json` (configurable). The system loads once at startup and auto-saves on changes when enabled.
+
+### Tooling Integration
+
+Learning tools are exposed via `learning_*` commands and can be triggered from OpenCode:
+
+- `learning_add_experience`, `learning_search_experiences`
+- `learning_add_knowledge_node`, `learning_search_knowledge_nodes`, `learning_link_knowledge_nodes`
+- `learning_record_pattern`, `learning_list_patterns`
+- `learning_get_review_queue`, `learning_review_node`
+- `learning_create_state_machine`, `learning_list_state_machines`
+
+## Hook Lifecycle
+
+Hooks are used to intercept OpenCode lifecycle events (`tool.execute.before`, `tool.execute.after`, etc.) and provide:
+
+- Mode activation (Blitzkrieg, Analyze, Ultrathink)
+- Context injection
+- Error recovery
+- Session storage
+- Learning initialization
+
+## Configuration Flow
+
+1. `~/.config/opencode/kraken-code.json` is parsed by the config manager.
+2. Zod schemas validate and normalize values.
+3. Hook/config loaders consume validated config for runtime behavior.
+
+## Extensibility
+
+- Add new tools under `src/tools/`
+- Add new hooks under `src/hooks/`
+- Extend learning by adding new store helpers in `src/features/memory/`

package/docs/BLITZKRIEG_MODE.md

@@ -0,0 +1,85 @@
+# Blitzkrieg Mode
+
+Blitzkrieg Mode is an aggressive test-driven development workflow built into Kraken Code.
+
+## Activation
+
+Simply include "blitz" or "blz" in your request:
+- "Use blitz to implement auth system"
+- "Enable blz mode for this feature"
+- "Refactor with blitzkrieg standards"
+
+## Features
+
+### Test Plan Enforcement
+- Required before complex features
+- Minimum test cases specified
+- Coverage thresholds defined
+
+### TDD Workflow
+- Tests written before implementation
+- No code without tests
+- Refactoring allowed
+
+### Evidence Verification
+- Test execution evidence required
+- Assertion count verified
+- Edge cases checked
+
+### Planner Constraints
+- Test step required in plans
+- Verification step required
+- Complexity limits enforced
+
+## Common Workflow
+
+1. **Plan**: Create test plan for feature
+2. **Write Tests**: Implement test cases first
+3. **Implement**: Write production code
+4. **Verify**: Run tests and show evidence
+5. **Refine**: Add edge cases until coverage goal met
+
+## Test Plan Template
+
+For complex features, create a test plan:
+
+```typescript
+{
+  feature: "Feature name",
+  testCases: [
+    { description: "Happy path", category: "happy-path" },
+    { description: "Error case", category: "error-path" },
+    { description: "Edge case", category: "edge-case" }
+  ],
+  coverageTarget: 80
+}
+```
+
+## Evidence Requirements
+
+When asked for evidence, provide:
+- Test execution log
+- Number of assertions passed/failed
+- Edge cases covered
+- Coverage percentage (if available)
+
+## Configuration
+
+Blitzkrieg mode is **enabled by default** (opt-out). Configure in `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "blitzkrieg": {
+    "enabled": true,
+    "testPlan": {
+      "requiredBeforeImplementation": true,
+      "minTestCases": 3,
+      "coverageThresholdPercent": 80
+    },
+    "tddWorkflow": {
+      "enforceWriteTestFirst": true,
+      "forbidCodeWithoutTest": true
+    }
+  }
+}
+```

package/docs/EXAMPLES.md

@@ -0,0 +1,74 @@
+# Kraken Code Examples
+
+## Learning Tools
+
+### Capture an Experience
+
+```bash
+learning_add_experience --summary "Switched cache strategy" \
+  --details "Moved from LRU to segmented cache to handle bursty traffic." \
+  --tags ["performance", "caching"] \
+  --outcome "Reduced 99p latency by 12%" \
+  --confidence 0.8
+```
+
+### Create Knowledge Nodes
+
+```bash
+learning_add_knowledge_node --title "Cache segmentation" \
+  --content "Segment cache into hot/warm buckets to reduce churn." \
+  --type "decision" \
+  --tags ["performance", "design"]
+```
+
+### Link Knowledge Nodes
+
+```bash
+learning_link_knowledge_nodes --sourceId node_123 --targetId node_456 \
+  --relation "depends_on" --strength 0.7
+```
+
+### Record a Pattern
+
+```bash
+learning_record_pattern --name "cache-churn" \
+  --description "Cache churn increases once traffic exceeds 1k rps." \
+  --triggers ["cache", "traffic"]
+```
+
+### Review Queue
+
+```bash
+learning_get_review_queue --dueBefore "2025-01-01T00:00:00.000Z"
+```
+
+### Log a Review
+
+```bash
+learning_review_node --nodeId node_123 --quality 4
+```
+
+### State Machines
+
+```bash
+learning_create_state_machine --name "Release Checklist" \
+  --states ["planned", "in-progress", "verified", "released"] \
+  --transitions '[{"from":"planned","to":"in-progress","event":"start"},{"from":"in-progress","to":"verified","event":"qa"},{"from":"verified","to":"released","event":"ship"}]' \
+  --initialState "planned"
+```
+
+## Configuration Example
+
+```json
+{
+  "learning": {
+    "enabled": true,
+    "storagePath": "~/.kraken/learning",
+    "experienceStore": { "enabled": true, "maxEntries": 2000 },
+    "knowledgeGraph": { "enabled": true, "maxNodes": 5000 },
+    "patternDetection": { "enabled": true, "minConfidence": 0.6 },
+    "spacedRepetition": { "enabled": true, "initialIntervalDays": 1 },
+    "stateMachines": { "enabled": true }
+  }
+}
+```

package/docs/FAQ.md

@@ -0,0 +1,21 @@
+# Frequently Asked Questions
+
+## What replaced the Kratos memory integration?
+
+Kraken Code now uses a unified learning system that stores experiences, knowledge graph nodes, patterns, and spaced repetition schedules in a single on-disk store.
+
+## Where is learning data stored?
+
+By default at `~/.kraken/learning/learning-state.json`. You can change the path via the `learning.storagePath` setting.
+
+## Can I disable parts of the learning system?
+
+Yes. Each learning component has its own `enabled` flag (`experienceStore`, `knowledgeGraph`, `patternDetection`, `spacedRepetition`, `stateMachines`).
+
+## How do I migrate from the old memory config?
+
+If you already had a `memory` block in your config, Kraken Code will still read its `enabled`, `autoSave`, and `storagePath` values as defaults for the new learning config. Updating to the new `learning` block is recommended.
+
+## Does the learning system work without MCP?
+
+Yes. The learning tools are built-in and do not depend on external MCP servers.

package/docs/SKILLS_GUIDE.md

@@ -0,0 +1,45 @@
+# Skills Guide
+
+Skills in Kraken Code use natural language to guide the AI for specific tasks.
+
+## Available Skills
+
+### Memory Skills
+- **Remember**: Store important information in the unified learning system
+- **Recall**: Retrieve stored memories
+
+### Session Skills
+- **Summary**: Generate session summaries
+
+### Project Skills
+- **Bootstrap**: Initialize new projects with patterns
+- **Init**: Set up project structure
+
+### Git Skills
+- **GitHub Integration**: Manage PRs and issues
+- **Import Pattern**: Apply code patterns
+
+### Testing Skills
+- **Coverage**: Analyze and improve test coverage
+
+### Code Skills
+- **Code Analyzer**: Analyze code structure
+- **Code Simplifier**: Simplify complex code
+- **Video Generator**: Create documentation videos
+- **Blitzkrieg**: Aggressive TDD workflow
+
+## Using Skills
+
+Simply describe what you want in natural language:
+- "Remember that JWT expiration policy"
+- "Recall authentication patterns"
+- "Generate a session summary"
+- "Create tests for the auth module"
+
+The AI will automatically select and apply the appropriate skill.
+
+## Skill Auto-Loading
+
+Skills are automatically loaded from:
+- `~/.config/opencode/skill/` - User's custom skills
+- `~/.config/opencode/kraken-code/templates/skills/` - Built-in skills

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,29 @@
+# Troubleshooting
+
+## Learning data not updating
+
+1. Confirm `learning.enabled` is `true`.
+2. Ensure the storage path is writable.
+3. Check that `learning.autoSave` is not disabled.
+
+If changes still do not persist, delete `~/.kraken/learning/learning-state.json` to reset the store.
+
+## Learning tools return empty results
+
+- Verify that `kraken-code init --full` created the `learning` section.
+- Add at least one experience or knowledge node and retry.
+
+## Configuration errors
+
+If Kraken Code fails to load configuration:
+
+1. Validate JSON syntax in `~/.config/opencode/kraken-code.json`.
+2. Ensure `learning` keys use the expected types (booleans, numbers, strings).
+3. Remove deprecated keys such as `kratos`.
+
+## Hooks not firing
+
+Hooks may be disabled by configuration or external OpenCode settings:
+
+- Check `claudeCodeCompatibility.toggles.hooks` if present.
+- Ensure OpenCode is not running in a restricted mode that disables plugin hooks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kraken-code",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "Kraken Code - Transforms OpenCode into an autonomous, high-density development environment",
   "type": "module",
   "main": "dist/index.js",
@@ -10,7 +10,13 @@
     "kraken-code": "./dist/cli/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "scripts/install-curl.sh",
+    "assets",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "exports": {
     ".": {
@@ -21,13 +27,17 @@
       "types": "./dist/google-auth.d.ts",
       "import": "./dist/google-auth.js"
     },
-    "./schema.json": "./dist/kraken-code.schema.json"
+    "./schema.json": "./dist/kraken-code.schema.json",
+    "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "bun build src/index.ts src/google-auth.ts --outdir dist --target node --format esm --external @opencode-ai/plugin --external @opencode-ai/sdk --external zod && bun build src/cli/index.ts --outdir dist/cli --target bun --format esm --packages external && bun run build:schema",
+    "build": "bun run build:plugin && bun run build:cli && bun run build:schema",
+    "build:plugin": "bun build src/index.ts src/google-auth.ts --outdir dist --target node --format esm --external @opencode-ai/plugin --external @opencode-ai/sdk --external zod --minify",
+    "build:cli": "bun build src/cli/index.ts --outdir dist/cli --target bun --format esm --packages external --minify",
     "build:schema": "bun run script/build-schema.ts && mkdir -p dist && cp assets/kraken-code.schema.json dist/kraken-code.schema.json",
-    "clean": "rm -rf dist",
-    "prepublishOnly": "bun run clean && bun run build",
+    "build:binary": "bun build --compile src/cli/index.ts --outfile bin/kraken-code",
+    "clean": "rm -rf dist bin",
+    "prepublishOnly": "bun run clean && bun run build && bun run typecheck",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src/**/*.ts",
     "lint:fix": "eslint src/**/*.ts --fix",
@@ -36,7 +46,12 @@
     "test": "bun test",
     "test:watch": "bun test --watch",
     "install:curl": "bash scripts/install-curl.sh",
-    "postinstall": "kraken-code init --minimal"
+    "agent:docs": "npx skill-compiler compile",
+    "agent:docs:watch": "npx skill-compiler watch",
+    "agent:docs:check": "npx skill-compiler compile --check",
+    "agent:docs:suggest": "npx skill-compiler suggest",
+    "agent:docs:sync": "npx skill-compiler sync",
+    "postinstall": "npx skill-compiler compile --silent"
   },
   "keywords": [
     "opencode",
@@ -70,14 +85,10 @@
   },
   "homepage": "https://github.com/leviathofnoesia/kraken-code#readme",
   "dependencies": {
-    "@ast-grep/cli": "^0.40.0",
-    "@ast-grep/napi": "^0.40.0",
     "@clack/core": "^0.5.0",
     "@clack/prompts": "^1.0.0-alpha.9",
     "@modelcontextprotocol/sdk": "^1.25.1",
     "@openauthjs/openauth": "^0.4.3",
-    "@opencode-ai/plugin": "^1.1.1",
-    "@opencode-ai/sdk": "^1.1.1",
     "commander": "^14.0.2",
     "glob": "^11.0.0",
     "hono": "^4.10.4",
@@ -89,6 +100,14 @@
     "xdg-basedir": "^5.1.0",
     "zod": "4.1.8"
   },
+  "optionalDependencies": {
+    "@ast-grep/cli": "^0.40.0",
+    "@ast-grep/napi": "^0.40.0"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "^1.1.0",
+    "@opencode-ai/sdk": "^1.1.0"
+  },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/picomatch": "^3.0.2",
@@ -99,6 +118,7 @@
     "eslint-config-prettier": "^9.0.0",
     "eslint-plugin-prettier": "^5.0.0",
     "prettier": "^3.0.0",
+    "skill-compiler": "latest",
     "typescript": "^5.9.3",
     "typescript-language-server": "^5.1.3"
   },

package/scripts/install-curl.sh

@@ -0,0 +1,111 @@
+#!/bin/bash
+
+set -e
+
+VERSION="5.0.0"
+PACKAGE_NAME="kraken-code"
+REGISTRY_URL="https://registry.npmjs.org"
+OPENCODE_DIR="$HOME/.config/opencode"
+PLUGINS_DIR="$OPENCODE_DIR/plugins"
+
+echo "======================================"
+echo "Kraken Code v${VERSION} Installer"
+echo "======================================"
+echo ""
+
+# Check if curl is available
+if ! command -v curl &> /dev/null; then
+  echo "Error: curl is required but not installed"
+  echo "Install curl from https://curl.se/download.html"
+  exit 1
+fi
+
+# Check if tar is available
+if ! command -v tar &> /dev/null; then
+  echo "Error: tar is required but not installed"
+  exit 1
+fi
+
+# Create plugin directory
+echo "Creating plugin directory..."
+mkdir -p "$PLUGINS_DIR"
+
+# Download package
+echo "Downloading Kraken Code v${VERSION}..."
+TEMP_TGZ=$(mktemp)
+DOWNLOAD_URL="${REGISTRY_URL}/${PACKAGE_NAME}/-/${PACKAGE_NAME}-${VERSION}.tgz"
+
+if curl -fsSL --max-time 60 -o "$TEMP_TGZ" "$DOWNLOAD_URL"; then
+  echo "Download complete"
+else
+  echo "Error: Failed to download Kraken Code"
+  echo "URL: $DOWNLOAD_URL"
+  rm -f "$TEMP_TGZ"
+  exit 1
+fi
+
+# Extract package
+echo "Extracting package..."
+cd "$PLUGINS_DIR"
+
+if tar -xzf "$TEMP_TGZ"; then
+  echo "Extraction complete"
+else
+  echo "Error: Failed to extract package"
+  rm -f "$TEMP_TGZ"
+  exit 1
+fi
+
+# Verify installation
+PACKAGE_DIR="${PLUGINS_DIR}/package"
+if [ ! -d "$PACKAGE_DIR" ]; then
+  echo "Error: Package directory not found after extraction"
+  rm -f "$TEMP_TGZ"
+  exit 1
+fi
+
+# Clean up
+rm -f "$TEMP_TGZ"
+
+# Get kraken-code CLI path
+KRAKEN_CLI="$PACKAGE_DIR/dist/cli/index.js"
+
+# Initialize Kraken Code configuration
+if [ -f "$KRAKEN_CLI" ]; then
+  echo ""
+  echo "Initializing Kraken Code configuration..."
+  bun run "$KRAKEN_CLI" init --minimal
+  if [ $? -eq 0 ]; then
+    echo ""
+    echo "✓ Kraken Code initialized successfully!"
+  else
+    echo ""
+    echo "⚠️  Initialization failed. Run manually: kraken-code init --minimal"
+  fi
+else
+  echo ""
+  echo "⚠️  CLI not found. Run manually: kraken-code init --minimal"
+fi
+
+# Get actual package name (might be scoped)
+ACTUAL_PACKAGE_NAME=$(ls "$PLUGINS_DIR" | grep -v "^package$" | head -1)
+
+if [ -z "$ACTUAL_PACKAGE_NAME" ]; then
+  ACTUAL_PACKAGE_NAME="package"
+fi
+
+# Success message
+echo ""
+echo "======================================"
+echo "Installation Complete!"
+echo "======================================"
+echo ""
+echo "Kraken Code v${VERSION} installed to: $PLUGINS_DIR/$ACTUAL_PACKAGE_NAME"
+echo ""
+echo "Next Steps:"
+echo "1. Restart OpenCode to load plugin"
+echo "2. Use 'blitz' or 'blz' to activate Blitzkrieg Mode"
+echo "3. Run: kraken-code --help for more options"
+echo ""
+echo "Documentation: https://github.com/leviathofnoesia/kraken-code"
+echo ""