@ekkos/cli 1.0.30 → 1.0.32

package/templates/windsurf-skills/README.md

@@ -0,0 +1,58 @@
+# ekkOS Windsurf Skills
+
+6 skills following the [Agent Skills specification](https://agentskills.io/specification) for Windsurf Cascade.
+
+## Skills
+
+| # | Skill | Golden Loop Step | Description |
+|---|-------|-----------------|-------------|
+| 1 | `ekkos-golden-loop` | All 5 steps | Core loop — Search, Apply, Forge, Outcome, Reflect |
+| 2 | `ekkos-recall` | Search (deep) | Time-based and semantic recall across sessions |
+| 3 | `ekkos-safety` | Guard | Conflict checks before destructive operations |
+| 4 | `ekkos-vault` | Utility | AES-256-GCM encrypted credential storage |
+| 5 | `ekkos-continue` | Utility | Session resumption after clear/compaction |
+| 6 | `ekkos-insights` | Reflect (system) | Prometheus metrics, delta scores, system health |
+
+## Installation
+
+### Workspace Skills (per-project)
+
+```bash
+cp -r templates/windsurf-skills/* .windsurf/skills/
+```
+
+### Global Skills (all projects)
+
+```bash
+cp -r templates/windsurf-skills/* ~/.codeium/windsurf/skills/
+```
+
+### Via CLI
+
+```bash
+ekkos init --windsurf
+```
+
+## The Golden Loop (5 Steps)
+
+```
+SEARCH → APPLY → FORGE → OUTCOME → REFLECT
+  │        │        │        │          │
+  │        │        │        │          └─ Quality analysis
+  │        │        │        └─ Success/failure → Prometheus
+  │        │        └─ Save solution as pattern
+  │        └─ Use pattern + track usage
+  └─ Query memory before answering
+```
+
+Every step generates metrics consumed by the Prometheus Feedback Loop Worker (runs every 15 min):
+- **Auto-demotion**: Patterns >50% skip rate → quarantined
+- **Auto-promotion**: Patterns >85% success + 10 uses → collective layer (L6)
+- **Delta evaluation**: Δ_prometheus improvement score per interaction
+
+## Naming Convention
+
+All skills use lowercase-hyphenated names per the Agent Skills spec:
+- Directory name MUST match the `name` field in SKILL.md frontmatter
+- Names are 1-64 characters, lowercase alphanumeric + hyphens only
+- No consecutive hyphens (`--`), no leading/trailing hyphens

package/templates/windsurf-skills/ekkos-continue/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: ekkos-continue
+description: Resume session after clear or context compaction. Activate when the user types /continue or /clear, after context compaction occurs, or when you see an ekkos-context-preserved tag. Restores working memory from local cache (1ms) with Redis/Supabase fallback.
+allowed-tools:
+  - mcp__ekkos-memory__ekkOS_RestoreContext
+  - mcp__ekkos-memory__ekkOS_Recall
+  - mcp__ekkos-memory__ekkOS_Search
+---
+
+# ekkOS Continue
+
+Resume sessions seamlessly after `/clear` or context compaction.
+
+## When To Activate
+
+| Trigger | What Happened |
+|---------|--------------|
+| User types `/continue` | Manual resume request |
+| After `/clear` | Context was cleared, need to restore |
+| `<ekkos-context-preserved>` tag appears | Auto-compaction occurred |
+| Restored turns in `<system-reminder>` | Session was restored by hook |
+
+## Instructions
+
+### After `/clear` (Manual)
+
+If you see restored turns in a `<system-reminder>` tag (pattern: `**Turn XX**: ...`), respond with:
+
+```
+✓ **Session continued (Turn N)** - X turns preserved, context restored
+```
+
+Then resume the conversation naturally.
+
+### After Compaction (Automatic)
+
+When you see `<ekkos-context-preserved>` with a restoration token:
+
+```
+ekkOS_RestoreContext({
+  restoration_token: "<token from the tag>"
+})
+```
+
+Then respond with:
+```
+✓ **Context restored** - ekkOS preserved X turns before compaction
+```
+
+### Fallback: Semantic Recall
+
+If no restoration token is available:
+
+```
+ekkOS_Recall({
+  days_ago: 1,
+  semantic_query: "<topic from the conversation>",
+  include_full_content: true,
+  group_by_sessions: true,
+  limit: 5
+})
+```
+
+## How It Works
+
+1. **Local cache** (fastest, 1ms) — hooks save turns to local JSON
+2. **Redis** (fast, 10ms) — working memory backed up to Redis
+3. **Supabase** (reliable, 100ms) — episodic memory (L2) persists everything
+4. **Semantic search** (last resort) — find relevant context by meaning
+
+## Integration with Golden Loop
+
+Continue is a specialized SEARCH — it queries working memory (L1) and episodic memory (L2) to restore session state. After successful restoration, record it:
+
+```
+ekkOS_Outcome({ success: true })  // Restoration worked
+```
+
+---
+
+**Mantra**: No context is ever lost. Every session can be resumed.

package/templates/windsurf-skills/ekkos-golden-loop/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: ekkos-golden-loop
+description: The 5-step cognitive learning loop that makes AI smarter over time. Activate on every technical question, bug fix, architecture decision, debugging session, user correction, or when solving any non-trivial problem. Steps — Search, Apply, Forge, Outcome, Reflect. This is the core skill that drives all ekkOS memory operations.
+allowed-tools:
+  - mcp__ekkos-memory__ekkOS_Search
+  - mcp__ekkos-memory__ekkOS_Context
+  - mcp__ekkos-memory__ekkOS_Codebase
+  - mcp__ekkos-memory__ekkOS_Track
+  - mcp__ekkos-memory__ekkOS_Forge
+  - mcp__ekkos-memory__ekkOS_Outcome
+  - mcp__ekkos-memory__ekkOS_Reflect
+  - Read
+  - Glob
+---
+
+# ekkOS Golden Loop
+
+You are augmented with **ekkOS_ memory** — an 11-layer cognitive memory system. This skill defines the **5-step Golden Loop** that makes you smarter over time.
+
+## The 5 Steps
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  1. SEARCH  →  Query memory before answering               │
+│  2. APPLY   →  Use retrieved patterns, track usage          │
+│  3. FORGE   →  Save new solutions as patterns               │
+│  4. OUTCOME →  Record success or failure                    │
+│  5. REFLECT →  Analyze quality, forge improvements          │
+│       ↓                                                     │
+│  Prometheus collects metrics → demotion / promotion         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Every step feeds metrics to Prometheus** — skip rates, success rates, and delta scores that determine which patterns get promoted to collective wisdom and which get quarantined.
+
+## Step 1: SEARCH (Before Answering)
+
+Before answering ANY technical question, search memory first.
+
+```
+ekkOS_Search({
+  query: "<specific problem description>",
+  sources: ["patterns", "collective", "codebase"],
+  limit: 5
+})
+```
+
+**When to search:**
+- User asks a technical question
+- Debugging an error
+- Architecture or design discussion
+- "How do I..." questions
+- Configuration or deployment
+- Mid-response when you realize past context would help
+
+**For project-specific code:**
+```
+ekkOS_Codebase({
+  query: "<what you need from this project>",
+  limit: 5
+})
+```
+
+**For combined context (patterns + episodes):**
+```
+ekkOS_Context({
+  task: "<what you're trying to accomplish>"
+})
+```
+
+## Step 2: APPLY (Use Patterns, Track Usage)
+
+When patterns are retrieved, you MUST acknowledge every single one.
+
+**For patterns you USE:**
+```
+[ekkOS_SELECT]
+- id: <pattern_id>
+  reason: <why using>
+  confidence: <0.0-1.0>
+[/ekkOS_SELECT]
+```
+
+**For patterns NOT relevant:**
+```
+[ekkOS_SKIP]
+- id: <pattern_id>
+  reason: <why not relevant>
+[/ekkOS_SKIP]
+```
+
+Track is called automatically during search when patterns are found. The Track call creates an `application_id` that links your search to the outcome — this is how Prometheus knows which patterns are actually being used vs skipped.
+
+**Why this matters:** Every SKIP increments the pattern's skip rate. Patterns with >50% skip rate get auto-demoted by the Prometheus worker. Every SELECT reinforces the pattern.
+
+## Step 3: FORGE (Save Solutions)
+
+When you solve something non-trivial, save it immediately.
+
+```
+ekkOS_Forge({
+  title: "Descriptive, searchable title",
+  problem: "What went wrong or what was needed",
+  solution: "What worked and WHY it works",
+  tags: ["relevant", "tags"],
+  works_when: ["specific conditions"],
+  anti_patterns: ["what NOT to do"]
+})
+```
+
+**FORGE triggers — ask yourself after every solution:**
+- Was this non-trivial? → FORGE
+- Did the user correct me? → FORGE
+- Did something NOT work? → FORGE as anti-pattern
+- Would I want to remember this? → FORGE
+- Is this a gotcha or pitfall? → FORGE
+- Was an architecture decision made? → FORGE
+
+**Anti-patterns are equally valuable.** When something DOESN'T work:
+```
+ekkOS_Forge({
+  title: "Don't use setTimeout for rate limiting",
+  problem: "Tried setTimeout to throttle API calls — doesn't work",
+  solution: "Use proper debounce/throttle library instead",
+  anti_patterns: ["setTimeout for throttling", "manual timer-based rate limiting"]
+})
+```
+
+**Good titles:** Specific, searchable, actionable
+- "Fix CORS by setting Access-Control-Allow-Origin header"
+- "Use cursor pagination for tables over 100K rows"
+
+**Bad titles:** Vague, unsearchable
+- "Fixed the bug"
+- "Solution"
+
+## Step 4: OUTCOME (Record Success/Failure)
+
+After applying a pattern and seeing the result, record the outcome.
+
+```
+ekkOS_Outcome({
+  success: true,    // or false
+  model_used: "claude-sonnet-4-6"
+})
+```
+
+**When to record outcomes:**
+- User confirms solution works → `success: true`
+- User says "that's not right" → `success: false`
+- Applied pattern solved the problem → `success: true`
+- Pattern didn't apply well → `success: false`
+- After completing a complex task → record overall outcome
+
+**Why this matters:** Outcome feeds directly into Prometheus:
+- Success rates determine pattern quality scores
+- Patterns with >85% success + 10 uses → promoted to collective (L6)
+- Patterns with <30% success after 10 uses → quarantined
+- Delta scores (Δ_prometheus) track improvement over time
+
+## Step 5: REFLECT (Analyze and Improve)
+
+After complex tasks or when receiving feedback, analyze your response.
+
+```
+ekkOS_Reflect({
+  user_query: "Original question",
+  response: "Your response summary",
+  context: {
+    patterns_used: 3,
+    model: "claude-sonnet-4-6"
+  }
+})
+```
+
+**Reflection feeds back into the loop:**
+- Identify missed patterns → better future searches
+- Spot over-engineering → forge simplicity preferences
+- Record what worked → reinforce good patterns
+- Find gaps → forge new patterns to fill them
+
+## Metric Collection Summary
+
+Every step generates metrics that Prometheus uses:
+
+| Step | Metric Generated | Prometheus Impact |
+|------|-----------------|-------------------|
+| Search | retrieval count, latency | retrieval_precision |
+| Apply (SELECT) | application count | Reinforces pattern |
+| Apply (SKIP) | skip count | skip_rate → demotion risk |
+| Forge | new patterns | capability growth |
+| Outcome | success/failure | success_rate → promotion/demotion |
+| Reflect | quality scores | pattern_quality delta |
+
+The **Prometheus Feedback Loop Worker** (runs every 15 min) processes:
+1. **Auto-demotion**: Patterns >50% skip rate → quarantined
+2. **Auto-promotion**: Patterns >85% success + 10 uses → collective layer
+3. **Delta evaluation**: Δ_prometheus score per interaction
+
+## Response Format
+
+Every response MUST end with:
+```
+---
+🧠 **ekkOS_™**
+```
+
+## Fallback Behavior
+
+If the MCP server is unavailable:
+1. Proceed without memory
+2. Note: "Memory unavailable — solving from first principles"
+3. Solutions can still be forged when connection restores
+
+## What NOT To Do
+
+- **Don't skip Search** — always query memory first
+- **Don't skip Outcome** — this is how Prometheus learns
+- **Don't fabricate patterns** — only reference patterns actually retrieved
+- **Don't over-search** — one focused search beats many broad ones
+- **Don't forge trivial things** — "changed a variable name" isn't worth forging
+
+---
+
+**Mantra**: Search first. Apply what you find. Forge what you learn. Record what happened. Reflect and improve.

package/templates/windsurf-skills/ekkos-insights/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: ekkos-insights
+description: System introspection and improvement metrics powered by Prometheus. Activate when the user asks "how am I improving", "show my stats", "what does the system know", "ekkOS status", "memory summary", "pattern quality", "delta score", or wants to understand memory health, pattern effectiveness, or system performance.
+allowed-tools:
+  - mcp__ekkos-memory__ekkOS_Stats
+  - mcp__ekkos-memory__ekkOS_Summary
+  - mcp__ekkos-memory__ekkOS_Search
+  - mcp__ekkos-memory__ekkOS_Health
+---
+
+# ekkOS Insights (Prometheus)
+
+System introspection — see how ekkOS is improving over time.
+
+## When To Activate
+
+| Trigger | What To Show |
+|---------|-------------|
+| "How am I improving?" | Delta score and trends |
+| "Show my stats" | Layer statistics |
+| "What does ekkOS know?" | MetaState overview |
+| "ekkOS status" / "memory summary" | Activity summary |
+| "Pattern quality" | Success rates, skip rates |
+| "Is ekkOS healthy?" | System health check |
+| "What patterns are being used?" | Applied/skipped breakdown |
+| "Show me what you learned" | Recent forges and outcomes |
+
+## Instructions
+
+### Memory Statistics (All Layers)
+
+```
+ekkOS_Stats({
+  scope: "both"    // "personal", "collective", or "both"
+})
+```
+
+Shows counts across all 11 layers:
+- L1 Working — current session turns
+- L2 Episodic — past conversations
+- L3 Semantic — embedded knowledge
+- L4 Patterns — proven solutions
+- L5 Procedural — step-by-step guides
+- L6 Collective — cross-project wisdom
+- L7 Meta — pattern effectiveness
+- L8 Codebase — project-specific code
+- L9 Directives — user rules (MUST/NEVER/PREFER/AVOID)
+- L10 Conflict — auto-resolution
+- L11 Secrets — encrypted credentials
+
+### Activity Summary
+
+```
+ekkOS_Summary({
+  time_window_seconds: 3600    // last hour (default: 5 min)
+})
+```
+
+Shows recent activity: searches, forges, outcomes, tracks.
+
+### System Health
+
+```
+ekkOS_Health({
+  include_stats: true
+})
+```
+
+Checks connectivity to all services: Supabase, Redis, embeddings, etc.
+
+## Prometheus Metrics (What Gets Tracked)
+
+The Prometheus system quantifies improvement using:
+
+```
+Δ_prometheus = γ × Δ_performance + (1-γ) × Δ_ekkOS
+```
+
+### Performance Metrics (Δ_performance)
+| Metric | Weight | What It Measures |
+|--------|--------|-----------------|
+| Task Success | 0.4 | Are solutions working? (outcome success rate) |
+| Efficiency | 0.3 | Are we solving faster? (turns to solution) |
+| Stability | 0.2 | System reliability (1 - error_rate) |
+| Capability | 0.1 | New patterns forged / total patterns |
+
+### ekkOS Metrics (Δ_ekkOS)
+| Metric | Weight | What It Measures |
+|--------|--------|-----------------|
+| Pattern Quality | 0.4 | Avg success rate improvement |
+| Retrieval Precision | 0.3 | 1 - (skip_rate / total_retrievals) |
+| Directive Compliance | 0.2 | Compliant actions / total actions |
+| Collective Contribution | 0.1 | Patterns promoted to collective / forged |
+
+### Prometheus Worker Actions (Every 15 min)
+| Action | Threshold | Result |
+|--------|-----------|--------|
+| **Auto-demotion** | >50% skip rate, 5+ uses | Pattern quarantined |
+| **Auto-promotion** | >85% success, 10+ uses | Pattern → collective (L6) |
+| **Delta evaluation** | Per-interaction | Δ score stored for trending |
+
+## Presenting Insights
+
+When the user asks for insights, present them clearly:
+
+```
+📊 **ekkOS Memory Status**
+
+**Patterns:** 142 active, 8 quarantined, 12 promoted to collective
+**Success Rate:** 87% (↑ 3% this week)
+**Retrieval Precision:** 92% (low skip rate = patterns are relevant)
+**Most Used Pattern:** "Handle Supabase RLS errors" (23 applications, 96% success)
+**Recent Forges:** 4 new patterns this session
+
+**Prometheus Δ Score:** +0.12 (improving)
+  - Task success: +0.08
+  - Pattern quality: +0.15
+  - Retrieval precision: +0.11
+  - Collective contribution: +0.04
+
+**Health:** All systems operational ✓
+```
+
+## Integration with Golden Loop
+
+Insights is Step 5 (REFLECT) at the system level — instead of reflecting on a single response, it reflects on the entire memory system's health and improvement trajectory.
+
+The metrics displayed here are collected by Steps 1-4:
+1. **Search** → retrieval counts, latency
+2. **Apply** → skip rates, application counts
+3. **Forge** → new pattern counts, capability growth
+4. **Outcome** → success rates, delta scores
+
+Without proper Outcome tracking, these metrics are incomplete. This is why the Golden Loop skill emphasizes recording outcomes — it's what feeds Prometheus.
+
+---
+
+**Mantra**: What gets measured gets improved. Prometheus sees everything.

package/templates/windsurf-skills/ekkos-recall/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: ekkos-recall
+description: Deep memory retrieval across sessions and projects. Activate when the user says "yesterday", "last week", "remember when", "what did we discuss", "we worked on X before", "bring context from", or asks about past decisions, fixes, or discussions. Combines time-based recall with semantic search.
+allowed-tools:
+  - mcp__ekkos-memory__ekkOS_Recall
+  - mcp__ekkos-memory__ekkOS_Search
+  - mcp__ekkos-memory__ekkOS_Context
+  - mcp__ekkos-memory__ekkOS_RestoreContext
+---
+
+# ekkOS Deep Recall
+
+You can recall past conversations, decisions, and context from previous sessions.
+
+## When To Activate
+
+| Trigger | Example |
+|---------|---------|
+| Time reference | "yesterday", "last week", "last month" |
+| Past work | "remember when we...", "we worked on X before" |
+| Decision recall | "what did we decide about...", "why did we choose..." |
+| Context transfer | "bring context from the other project" |
+| Session continuity | "where did we leave off", "continue from last time" |
+
+## Instructions
+
+### Time-Based Recall
+
+```
+ekkOS_Recall({
+  days_ago: 1,                    // 1, 2, 7, 30...
+  semantic_query: "what we discussed about auth",
+  include_file_changes: true,     // show files modified
+  include_patterns: true,         // show patterns used
+  extract_decisions: true,        // pull out decisions made
+  group_by_sessions: true         // organize by session
+})
+```
+
+### Semantic Recall (By Topic)
+
+```
+ekkOS_Recall({
+  semantic_query: "database migration strategy",
+  limit: 10,
+  include_full_content: true
+})
+```
+
+### Session-Based Recall
+
+```
+ekkOS_Recall({
+  session_id: "<session-id>",
+  from_turn: 1,
+  to_turn: 50,
+  include_full_content: true
+})
+```
+
+### Context Restoration (After Compaction)
+
+When you see `<ekkos-context-preserved>` with a restoration token:
+
+```
+ekkOS_RestoreContext({
+  restoration_token: "<token from tag>"
+})
+```
+
+## Response Format
+
+Present recalled information clearly:
+
+```
+🧠 From [date/session]:
+
+**Topic:** [what was discussed]
+**Decision:** [what was decided]
+**Files changed:** [list]
+**Patterns used:** [list]
+**Key insight:** [the important takeaway]
+```
+
+## Integration with Golden Loop
+
+Recall is an extended SEARCH — it queries episodic memory (L2) instead of pattern memory (L4). Results should still be acknowledged and tracked like any retrieval.
+
+After recalling useful context, record the outcome:
+```
+ekkOS_Outcome({ success: true })
+```
+
+---
+
+**Mantra**: Nothing is forgotten. Every session is searchable. Context persists.

package/templates/windsurf-skills/ekkos-safety/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: ekkos-safety
+description: Check for conflicts before dangerous operations. Activate before deleting files, dropping tables, deploying to production, pushing to main, running destructive commands, modifying configuration files, force-pushing, or any irreversible action. Prevents accidents by checking user directives and patterns.
+allowed-tools:
+  - mcp__ekkos-memory__ekkOS_Conflict
+  - mcp__ekkos-memory__ekkOS_Search
+---
+
+# ekkOS Safety Guard
+
+Check for conflicts with user directives and patterns before destructive operations.
+
+## When To Activate
+
+**MUST fire before:**
+- `rm -rf`, `rm -r`, deleting files or directories
+- `DROP TABLE`, `DELETE FROM`, `TRUNCATE`
+- `git push --force`, `git reset --hard`
+- Deploying to production
+- Modifying CI/CD pipelines
+- Changing environment variables
+- Overwriting configuration files
+- Killing processes
+- Any command that is hard to reverse
+
+## Instructions
+
+### Step 1: Check for Conflicts
+
+```
+ekkOS_Conflict({
+  proposed_action: "delete all migration files in /db/migrations",
+  scope: "deployment"   // optional: deployment, auth, security, database
+})
+```
+
+### Step 2: Review Response
+
+The conflict check returns:
+- **Matching directives** — user rules that may prohibit the action
+- **Matching patterns** — past experiences relevant to this action
+- **Risk level** — safe, caution, or blocked
+
+### Step 3: Act Based on Result
+
+**If BLOCKED:** Do NOT proceed. Inform the user why.
+
+**If CAUTION:** Present the conflict to the user and ask for confirmation before proceeding.
+
+**If SAFE:** Proceed normally.
+
+## Example
+
+```
+User: "Drop the users table and recreate it"
+
+You: Let me check for conflicts first...
+
+ekkOS_Conflict({
+  proposed_action: "DROP TABLE users and recreate",
+  scope: "database"
+})
+
+Result: CAUTION — Directive found: "NEVER drop tables in production without backup"
+
+"⚠️ I found a directive: 'NEVER drop tables in production without backup.'
+Should I create a backup first, or is this a development database?"
+```
+
+## Integration with Golden Loop
+
+Safety checks are part of Step 1 (SEARCH) — they query the directive layer (L9) specifically. If a safety check prevents an accident, forge it:
+
+```
+ekkOS_Forge({
+  title: "Always backup before DROP TABLE",
+  problem: "Nearly dropped production table without backup",
+  solution: "ekkOS_Conflict caught the directive — always check first"
+})
+```
+
+Record the outcome:
+```
+ekkOS_Outcome({ success: true })  // Safety check prevented accident
+```
+
+---
+
+**Mantra**: Measure twice, cut once. Check before destroying.