@ekkos/cli 1.3.1 → 1.3.5

package/templates/windsurf-rules/ekkos-memory.md

@@ -1,127 +0,0 @@
----
-trigger: always_on
-description: ekkOS Memory — 11-layer cognitive memory with 29 MCP tools
----
-
-# ekkOS Memory System
-
-You have access to **ekkOS memory** via 29 MCP tools. This is an 11-layer cognitive memory system that makes AI smarter over time by learning from past sessions.
-
-## MANDATORY RULES
-
-### RULE 1: SEARCH BEFORE ANSWERING
-Before answering ANY technical question, call `ekkOS_Search` first.
-
-### RULE 2: ACKNOWLEDGE RETRIEVED PATTERNS
-When patterns are retrieved, acknowledge each one:
-```
-[ekkOS_SELECT]
-- id: <pattern_id>
-  reason: <why using>
-  confidence: <0.0-1.0>
-[/ekkOS_SELECT]
-
-[ekkOS_SKIP]
-- id: <pattern_id>
-  reason: <why not relevant>
-[/ekkOS_SKIP]
-```
-
-Suppress SELECT/SKIP blocks for non-technical turns (acknowledgments, affirmations).
-
-### RULE 3: FORGE WHAT YOU LEARN
-When you fix a bug, get corrected, or learn something new, call `ekkOS_Forge` immediately.
-When something DOESN'T work, forge it as an anti-pattern.
-
-## MCP Tools — 29 Visible
-
-### Core Memory (6)
-| Tool | Description |
-|------|-------------|
-| `ekkOS_Search` | Search across all 11 memory layers |
-| `ekkOS_Forge` | Create pattern from learned solution |
-| `ekkOS_Track` | Track when a pattern is applied |
-| `ekkOS_Outcome` | Record if pattern worked or failed |
-| `ekkOS_Stats` | Get statistics for all layers |
-| `ekkOS_Context` | Get relevant context for a task |
-
-### Retrieval (4)
-| Tool | Description |
-|------|-------------|
-| `ekkOS_Codebase` | Search project code embeddings |
-| `ekkOS_Recall` | Recall past conversations by time |
-| `ekkOS_PreserveContext` | Preserve working memory before compaction |
-| `ekkOS_RestoreContext` | Restore context after compaction |
-
-### Directives (4)
-| Tool | Description |
-|------|-------------|
-| `ekkOS_Directive` | Create MUST/NEVER/PREFER/AVOID rules |
-| `ekkOS_UpdateDirective` | Update an existing directive |
-| `ekkOS_DeleteDirective` | Remove a directive |
-| `ekkOS_UniversalDirectives` | Get directives that apply across all projects |
-
-### Utility (5)
-| Tool | Description |
-|------|-------------|
-| `ekkOS_Summary` | Get summary of recent memory activity |
-| `ekkOS_Conflict` | Check for conflicts before destructive actions |
-| `ekkOS_Export` | Export patterns, directives, plans as JSON backup |
-| `ekkOS_Import` | Import memory from backup (auto-deduplication) |
-| `ekkOS_Health` | System health check |
-
-### Plans (5)
-| Tool | Description |
-|------|-------------|
-| `ekkOS_Plan` | Create structured task plan |
-| `ekkOS_Plans` | List your plans |
-| `ekkOS_PlanStatus` | Update plan status |
-| `ekkOS_PlanStep` | Mark step complete/incomplete |
-| `ekkOS_Generate` | AI-generate plan from context |
-
-### Secrets (5)
-| Tool | Description |
-|------|-------------|
-| `ekkOS_StoreSecret` | Encrypt and store sensitive data |
-| `ekkOS_GetSecret` | Retrieve and decrypt a secret |
-| `ekkOS_ListSecrets` | List secrets metadata (no values exposed) |
-| `ekkOS_DeleteSecret` | Permanently delete a secret |
-| `ekkOS_RotateSecret` | Update a secret with a new value |
-
-## 11-Layer Architecture
-
-| # | Layer | Purpose |
-|---|-------|---------|
-| 1 | Working | Current session state |
-| 2 | Episodic | Past conversations |
-| 3 | Semantic | Embeddings & knowledge |
-| 4 | Patterns | Proven solutions |
-| 5 | Procedural | Step-by-step guides |
-| 6 | Collective | Cross-project wisdom |
-| 7 | Meta | Pattern effectiveness |
-| 8 | Codebase | Project-specific code |
-| 9 | Directives | User rules (MUST/NEVER/PREFER/AVOID) |
-| 10 | Conflict | Auto-resolves contradictions |
-| 11 | Secrets | Encrypted credentials (AES-256-GCM) |
-
-## When To Use What
-
-| Tool | Trigger |
-|------|---------|
-| `ekkOS_Search` | Technical question, past discussion, architecture, debugging |
-| `ekkOS_Forge` | Bug fixed, better approach, gotcha, correction, anti-pattern |
-| `ekkOS_Directive` | User says "always" → MUST, "never" → NEVER, "prefer" → PREFER, "avoid" → AVOID |
-| `ekkOS_Conflict` | Before delete, deploy, config change, destructive commands |
-| Plan tools | Task has 3+ steps, complex feature request |
-| Secret tools | User shares API key/token/password, need stored credentials |
-| `ekkOS_Recall` | "yesterday", "last week", "remember when", "what did we discuss" |
-
-## Response Format
-
-End every response with:
-```
----
-🧠 **ekkOS_™** · 📅 YYYY-MM-DD H:MM AM/PM TZ
-```
-
-For more info: https://docs.ekkos.dev

package/templates/windsurf-skills/README.md

@@ -1,58 +0,0 @@
-# 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

@@ -1,81 +0,0 @@
----
-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

@@ -1,225 +0,0 @@
----
-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

@@ -1,138 +0,0 @@
----
-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.