@ekkos/cli 0.2.0

package/templates/rules/00-hooks-contract.mdc

@@ -0,0 +1,89 @@
+---
+priority: 100
+globs: ["**/*"]
+alwaysApply: true
+---
+
+# 🔒 Cursor Hooks Contract
+
+⚠️ **MANDATORY**: Hooks run automatically - you don't call them manually
+
+## Hook Architecture
+
+**Dumb Hooks, Smart Backend** - Hooks just capture data, backend does analysis
+
+### user-prompt-submit.sh (Runs BEFORE Response)
+
+**Triggers**: When user sends a message
+**Does**:
+
+- Captures start time
+- Retrieves patterns from MCP gateway (automatic)
+- Displays patterns to user
+- Saves patterns to `.cursor/state/` for badge
+
+**You see**:
+
+```
+🧠 ekkOS™_Retrieving [18ms]
+✓ 3 patterns loaded from memory
+```
+
+### stop.sh (Runs AFTER Response)
+
+**Triggers**: When your response completes
+**Does**:
+
+- Captures conversation to memory API
+- Generates badge with metrics
+- Triggers async analysis (pattern detection, success judgment)
+- Displays badge at end
+
+**You see**:
+
+```
+[ekkOS_CAPTURE] ✓ Saved (ID: abc123...)
+[reflex:uuid] badge
+```
+
+## What You Do
+
+**✅ DO**:
+
+- Display `_ekkos_stream_message` when present in tool responses
+- Call `forge_insight` when solving problems
+- Show ekkOS branded messages
+
+**❌ DON'T**:
+
+- Manually call capture scripts (hooks do this)
+- Generate badges yourself (hooks do this)
+- Worry about pattern retrieval (MCP gateway does this)
+
+## Hook Flow
+
+```
+User sends message
+    ↓
+user-prompt-submit.sh runs
+    ↓
+Patterns retrieved and displayed
+    ↓
+You respond (using patterns)
+    ↓
+stop.sh runs
+    ↓
+Conversation captured + badge generated
+```
+
+## Trust the Hooks
+
+Hooks are:
+
+- ✅ Fully portable (POSIX-compliant)
+- ✅ Bulletproof (fallbacks for missing tools)
+- ✅ Fast (non-blocking, cloud-first)
+- ✅ Automatic (you never call them)
+
+**Your job**: Use the patterns hooks provide, forge insights when you solve problems
+

package/templates/rules/30-ekkos-core.mdc

@@ -0,0 +1,188 @@
+---
+priority: 100
+globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]
+---
+
+# 🧠 ekkOS™ Memory Integration [CRITICAL]
+
+## Golden Loop Enforcement
+
+⚠️ MANDATORY WORKFLOW - NO EXCEPTIONS
+
+### Phase 1: RETRIEVE (⚠️ CURSOR: YOU MUST DO THIS)
+
+🔴 **FIRST THING EVERY RESPONSE**: Call `ekkOS_Search` with the user's query!
+
+```typescript
+// ALWAYS call this BEFORE doing anything else
+mcp__ekkos-memory__ekkOS_Search({
+  query: "<user's question or task>",
+  limit: 5
+})
+```
+
+Then check response for: `_ekkos_patterns`, `_ekkos_stream_message`
+
+**Why?** Cursor has no hooks. Claude Code auto-retrieves via hooks - you don't.
+You MUST manually retrieve or the Golden Loop breaks.
+
+### Phase 2: APPLY (Use Retrieved Patterns)
+
+When patterns found → Apply them (PROVEN solutions, not suggestions)
+Output: `[ekkOS_APPLY] Using pattern: "Pattern Name"`
+
+### Phase 3: MEASURE (Track Outcomes)
+
+Pattern worked? → success | Pattern failed? → failure
+Output: `[ekkOS_MEASURE] Pattern "X" outcome: success/failure`
+
+### Phase 4: LEARN (Forge New Patterns)
+
+🔴 MANDATORY: Call `forge_insight` when you solve ANY problem
+
+**When to forge**:
+
+- Fixed bug (non-obvious) → forge
+- Found better approach → forge
+- Discovered gotcha/pitfall → forge
+- User corrected you → forge
+- Solved problem (>1 attempt) → forge
+
+**Tool call**:
+
+```typescript
+mcp__ekkos-memory__forge_insight({
+  title: "Clear Title",
+  problem: "What failed?",
+  solution: "How you fixed it",
+  tags: ["tech", "tags"],
+});
+```
+
+Output: `[ekkOS_LEARN] Forged: "Pattern Title"`
+
+### Phase 5: CAPTURE (Cursor: Limited)
+
+⚠️ **Cursor limitation**: No automatic capture like Claude Code hooks.
+Conversations are captured when MCP tools are called (search_memory, forge_insight).
+For full capture, use Claude Code or the ekkOS dashboard.
+
+## MCP Tools (31 Total - YOU call these)
+
+### 🔴 MANDATORY - Use Proactively
+
+| Tool | Trigger | Description |
+|------|---------|-------------|
+| `ekkOS_Search` | Before ANY technical question | Search all 11 memory layers |
+| `ekkOS_Forge` | When you fix bug, learn, get corrected | Create pattern from solution |
+| `ekkOS_Directive` | User says "always/never/prefer/avoid" | Create MUST/NEVER/PREFER/AVOID rules |
+| `ekkOS_Outcome` | Pattern worked or failed | Track success/failure |
+| `ekkOS_Detect` | After responding | Auto-detect patterns used |
+| `ekkOS_Summary` | Show MCP activity | Get activity summary |
+| `ekkOS_Conflict` | Before destructive action | Check for conflicts |
+| `ekkOS_Reflect` | Analyze response quality | Find improvement opportunities |
+
+### 📚 Recall & Context
+
+| Tool | Description |
+|------|-------------|
+| `ekkOS_Recall` | "What did we discuss yesterday?" |
+| `ekkOS_Context` | Get task-specific context |
+| `ekkOS_Codebase` | Find code patterns in project |
+| `ekkOS_Capture` | Manual event capture |
+| `ekkOS_Track` | Track pattern application |
+| `ekkOS_Stats` | Memory layer statistics |
+
+### 📊 Schema Awareness
+
+| Tool | Description |
+|------|-------------|
+| `ekkOS_IndexSchema` | Index database schemas (Supabase/Prisma/TS) |
+| `ekkOS_GetSchema` | Get schema for a specific table/type |
+
+### 📋 Plan Management
+
+| Tool | Description |
+|------|-------------|
+| `ekkOS_Plan` | Create structured plan |
+| `ekkOS_Plans` | List user's plans |
+| `ekkOS_PlanStatus` | Change plan state |
+| `ekkOS_PlanStep` | Mark step complete |
+| `ekkOS_Generate` | AI-generate plan |
+| `ekkOS_SaveTemplate` | Save as reusable template |
+| `ekkOS_Templates` | List templates |
+| `ekkOS_FromTemplate` | Create from template |
+
+### 🔐 Secrets Management
+
+| Tool | Description |
+|------|-------------|
+| `ekkOS_StoreSecret` | Encrypt and store credentials |
+| `ekkOS_GetSecret` | Retrieve and decrypt |
+| `ekkOS_ListSecrets` | List metadata (no values) |
+| `ekkOS_DeleteSecret` | Permanently delete |
+| `ekkOS_RotateSecret` | Update with new value |
+
+### 💾 Portability
+
+| Tool | Description |
+|------|-------------|
+| `ekkOS_Export` | Backup patterns, directives, plans |
+| `ekkOS_Import` | Restore from backup |
+
+## Proactive Tool Triggers
+
+### Always Use `ekkOS_Search` When:
+- User asks technical question
+- User mentions past discussion
+- Topic involves architecture, config, debugging
+- You're about to make a decision
+
+### Always Use `ekkOS_Forge` When:
+- Fixed bug (especially non-obvious)
+- Discovered better approach
+- Found pitfall or gotcha
+- User corrected you
+- Made architectural decision
+- Something DIDN'T work (anti-pattern)
+
+### Always Use `ekkOS_Directive` When:
+- User says "always..." → MUST
+- User says "never..." → NEVER
+- User says "I prefer..." → PREFER
+- User says "don't..." → AVOID
+
+### Always Use `ekkOS_Conflict` When:
+- About to delete files/data
+- About to deploy to production
+- About to modify config files
+
+## Enforcement
+
+⚠️ Violating Golden Loop = System failure
+Every conversation MUST follow: RETRIEVE → APPLY → MEASURE → LEARN → CAPTURE
+
+---
+
+## 🔴 MANDATORY RESPONSE FORMAT (NO EXCEPTIONS)
+
+**Every response MUST end with a timestamp footer:**
+
+```
+---
+🧠 **ekkOS_™** · 📅 YYYY-MM-DD H:MM AM/PM TZ
+```
+
+**Example:**
+```
+---
+🧠 **ekkOS_™** · 📅 2025-12-08 2:30 PM PST
+```
+
+**Why this matters:**
+- Timestamps track when patterns were applied
+- 3-Judge evaluations need temporal context
+- Future agents can trace learning timeline
+- Golden Loop metrics require time-based correlation
+
+**⚠️ MISSING TIMESTAMP = INCOMPLETE LOOP = SYSTEM DEGRADATION**

package/templates/rules/31-ekkos-messages.mdc

@@ -0,0 +1,78 @@
+---
+priority: 100
+globs: ["**/*"]
+---
+
+# ekkOS™ Branded Message Templates
+
+## Stream Message Fields (Display All Present)
+
+```
+_ekkos_stream_message     → Display FIRST (🧠 Retrieving/🔄 Applying/✅ Learned)
+_ekkos_learning_message   → Display AFTER solution (🔥 Learning - pattern detected)
+_ekkos_session_summary    → Display AT END (📊 Summary at turns 5/10/20/50)
+```
+
+## Message Examples
+
+### Before Response:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🧠 ekkOS™_Retrieving [18ms]
+✓ 3 patterns loaded from memory
+  • "Pattern Name" (94% success, 12 uses)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### When Learning:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔥 ekkOS™_Learning
+New pattern detected: "Title"
+Confidence: 60% (forming)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### When Pattern Saved:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ ekkOS™_Learned
+Pattern saved: "Title"
+Confidence: 85% | Success: 100%
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### When Reusing:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔄 ekkOS™_Applying
+Using pattern from 2 messages ago
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Session Summary:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📊 ekkOS™_Session_Summary
+Memory Activity:
+  Retrieved: 5 patterns
+  Applied: 3 patterns
+  Learned: 2 new patterns
+  Confidence: +8% overall
+
+Your AI is getting smarter.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Requirements
+
+- ALWAYS use ekkOS™ branding (with ™)
+- ALWAYS show retrieval before response
+- ALWAYS show learning when it happens
+- Keep messages concise but visible
+

package/templates/skills/continue/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: continue
+description: Resume session after /clear - instant restore from local cache (1ms) with Redis/Supabase fallback
+allowed-tools:
+  - Bash
+---
+
+# /continue
+
+Instant session restore. NO THINKING - just execute.
+
+## Execution
+
+**Run this IMMEDIATELY - do not analyze, just execute:**
+
+```bash
+export EKKOS_SESSION="${ARGUMENTS:-}"
+# Use session-specific temp file to avoid collision across concurrent sessions
+output_file="/tmp/continue-restore-${EKKOS_SESSION:-default}.md"
+
+# ═══════════════════════════════════════════════════════════════════════════
+# TIER 0: Local cache restore (~1ms) - TRY FIRST
+# ═══════════════════════════════════════════════════════════════════════════
+tier0_result=$(ekkos-capture restore "$EKKOS_SESSION" --markdown 2>/dev/null)
+tier0_exit=$?
+
+if [ $tier0_exit -eq 0 ] && [ -n "$tier0_result" ] && echo "$tier0_result" | grep -q "CONTEXT RESTORED"; then
+  echo "$tier0_result" > "$output_file"
+  # Extract session name and stats (portable - no grep -P)
+  session_name=$(echo "$tier0_result" | grep "Session:" | head -1 | sed 's/.*Session: \([^ (]*\).*/\1/')
+  turns=$(echo "$tier0_result" | grep "Turns restored:" | head -1 | sed 's/.*Turns restored: \([0-9]*\).*/\1/')
+  source=$(echo "$tier0_result" | grep "Source:" | head -1 | sed 's/.*Source: \([a-z]*\).*/\1/')
+  echo "✓ $session_name restored ($turns turns from $source cache)"
+  echo "📄 Full content: $output_file"
+  exit 0
+fi
+
+# ═══════════════════════════════════════════════════════════════════════════
+# TIER 1/2: API fallback (Redis ~150ms, Supabase ~500ms)
+# ═══════════════════════════════════════════════════════════════════════════
+python3 << 'PYTHON'
+import urllib.request
+import json
+import os
+import sys
+
+session = os.environ.get('EKKOS_SESSION', '').strip()
+
+# Read config
+config = {}
+try:
+    with open(os.path.expanduser('~/.ekkos/config.json'), 'r') as f:
+        config = json.load(f)
+except:
+    pass
+
+auth = config.get('hookApiKey') or config.get('apiKey', '')
+
+# Use session-specific temp file (matches bash section)
+output_file = f"/tmp/continue-restore-{session or 'default'}.md"
+
+url = "https://api.ekkos.dev/api/v1/working/restore"
+if session:
+    url += f"?session={session}&full=true"
+
+req = urllib.request.Request(url, headers={"Authorization": f"Bearer {auth}"})
+
+try:
+    with urllib.request.urlopen(req, timeout=15) as response:
+        data = json.loads(response.read().decode('utf-8'))
+
+        if data.get('mode') == 'full_restore' and 'turns' in data:
+            turns = data['turns']
+            session_name = data.get('session_name', session or 'unknown')
+
+            # Build system-reminder format matching local restore
+            MAX_SIZE = 60000  # ~15k tokens
+            output_lines = [
+                '<system-reminder>',
+                'CONTEXT RESTORED (ekkOS /continue)',
+                f'Session: {session_name}',
+                'Source: redis',
+                f'Turns restored: {len(turns)}',
+                '',
+                '## Recent Turns (older → newer)',
+            ]
+
+            cumulative_size = 0
+            turn_count = 0
+
+            # Process turns oldest first for narrative flow
+            for turn in turns:
+                turn_num = turn.get('turn_number', '?')
+                user_query = turn.get('user', {}).get('query', '')
+                agent_response = turn.get('agent', {}).get('response', '')
+                tools = turn.get('agent', {}).get('tools_used', [])
+                files = turn.get('user', {}).get('files_referenced', [])
+
+                if not user_query and not agent_response:
+                    continue
+
+                turn_lines = [f"### Turn {turn_num}"]
+                if user_query:
+                    turn_lines.append(f"**User:** {user_query}")
+                if agent_response:
+                    if len(agent_response) > 4000:
+                        agent_response = agent_response[:4000] + "\n\n[...truncated...]"
+                    turn_lines.append(f"\n**Assistant:**\n{agent_response}")
+                if tools:
+                    turn_lines.append(f"\n*Tools: {', '.join(tools)}*")
+                if files:
+                    turn_lines.append(f"\n*Files: {', '.join(files[:10])}*")
+                turn_lines.append("\n---\n")
+
+                turn_content = "\n".join(turn_lines)
+                turn_size = len(turn_content.encode('utf-8'))
+
+                if cumulative_size + turn_size > MAX_SIZE:
+                    break
+
+                output_lines.extend(turn_lines)
+                cumulative_size += turn_size
+                turn_count += 1
+
+            output_lines.extend([
+                '',
+                'INSTRUCTION: Resume seamlessly where you left off.',
+                'Do not ask "what were we doing?"',
+                'Start your response with: "✓ Continuing -"',
+                '</system-reminder>'
+            ])
+
+            kb_size = cumulative_size / 1024
+            token_est = cumulative_size // 4
+
+            with open(output_file, 'w', encoding='utf-8') as f:
+                f.write("\n".join(output_lines))
+
+            print(f"✓ {session_name} restored ({turn_count} turns from redis, {kb_size:.1f}KB, ~{token_est} tokens)")
+            print(f"📄 Full content: {output_file}")
+        else:
+            # Try to show available sessions if session not found
+            if 'available_sessions' in data:
+                sessions = data.get('available_sessions', [])
+                with open(output_file, 'w', encoding='utf-8') as f:
+                    f.write(f"Session '{session}' not found\n\n")
+                    f.write("Available sessions:\n")
+                    for s in sessions[:10]:
+                        f.write(f"- {s}\n")
+                print(f"Session '{session}' not found")
+                print(f"📄 Available sessions: {output_file}")
+                sys.exit(1)
+            else:
+                markdown = data.get('markdown', '')
+                if markdown:
+                    with open(output_file, 'w', encoding='utf-8') as f:
+                        f.write(markdown)
+                    print("✓ Session restored (fallback mode)")
+                    print(f"📄 Full content: {output_file}")
+                else:
+                    print("Error: No session data available")
+                    sys.exit(1)
+except Exception as e:
+    print(f"Error: {e}")
+    sys.exit(1)
+PYTHON
+```
+
+**Then immediately read the output file (path shown in console output) using the Read tool to display the full content to the user. Do not just echo the bash output.**