@ekkos/cli 1.2.18 → 1.3.0

package/templates/CLAUDE.md

@@ -1,27 +1,28 @@
 # ekkOS_ Memory System
 
-## CORE PURPOSE
+## The Golden Loop
 
-**The Golden Loop exists so YOU get SMARTER over time - learn from mistakes, don't repeat them.**
+ekkOS is your AI's cognitive memory. It learns from every session so you get smarter over time.
 
-This is YOUR cognitive memory. It makes you:
-- **Remember when you mess up** - Schema changes, wrong assumptions, bad approaches
-- **Not repeat the same mistakes** - If you broke something before, KNOW not to do it again
-- **Recall correct versions** - When schemas/configs get mangled, remember what's RIGHT
-- **Build on what worked** - Use proven patterns instead of fumbling through problems
+- **Remember mistakes** — Schema changes, wrong assumptions, bad approaches
+- **Don't repeat them** — If something broke before, know not to do it again
+- **Recall what's right** — When schemas/configs get mangled, remember the correct version
+- **Build on what worked** — Use proven patterns instead of starting from scratch
 
-**FAILURES ARE JUST AS VALUABLE AS SUCCESSES.** Forge anti-patterns too.
+**Failures are just as valuable as successes.** Forge anti-patterns too.
 
 ---
 
-## MANDATORY RULES (NOT OPTIONAL)
+## Core Rules
 
-### RULE 1: RETRIEVE BEFORE ANSWERING
+### RULE 1: SEARCH BEFORE ANSWERING
 Before answering ANY technical question, call `ekkOS_Search` first.
 Do not skip this. Do not assume you know the answer.
 
-### RULE 2: ACKNOWLEDGE ALL RETRIEVED PATTERNS (PatternGuard)
-When patterns are retrieved, you MUST acknowledge EVERY pattern - either use it or skip it.
+### RULE 2: ACKNOWLEDGE PATTERNS (PatternGuard)
+When patterns are retrieved, you MUST acknowledge every pattern — either use it or skip it.
+
+**Exception:** Suppress SELECT/SKIP blocks for non-technical turns (acknowledgments, affirmations, short replies).
 
 **For patterns you USE:**
 ```
@@ -43,342 +44,132 @@ When patterns are retrieved, you MUST acknowledge EVERY pattern - either use it
 ### RULE 3: FORGE WHAT YOU LEARN
 When you fix a bug, get corrected, or learn something new, call `ekkOS_Forge` immediately.
 
-### RULE 4: FAILURES ARE VALUABLE
-When something DOES NOT work, forge it as an anti-pattern.
+When something DOES NOT work, forge it as an anti-pattern — failures are valuable.
 
-### RULE 5: POST-CLEAR CONFIRMATION (HARDCODED)
-After `/clear`, when you see restored turns in `<system-reminder>` (pattern: `**Turn XX**: ...`), you MUST start your response with:
-```
-✓ **Session continued (Turn N)** - X turns preserved, context restored
-```
-This is the ONLY way users see that restoration worked. Hook output is invisible to them.
+### RULE 4: CONTEXT CONTINUITY
 
-### RULE 6: AUTO-RESTORE AFTER COMPACTION (CONTEXT GUARDIAN)
-When you see `<ekkos-context-preserved>` in the conversation (appears after auto-compaction):
-1. **IMMEDIATELY** call `ekkOS_RestoreContext` with the `restoration_token` from the tag
-2. This restores your working memory that was preserved before compaction
-3. Start your response with:
+**Post-clear restoration:** After `/clear`, when you see restored turns in `<system-reminder>`, confirm with:
 ```
-✓ **Context restored** - ekkOS preserved X turns before compaction
+✓ **Session continued (Turn N)** — X turns preserved, context restored
 ```
 
-**This is how seamless context continuity works:**
-- PreCompact hook fires → ekkOS_PreserveContext saves your state
-- Claude Code compacts → Summary includes the preservation tag
-- You see the tag → Call ekkOS_RestoreContext → Full context restored
-- User experiences zero knowledge loss despite compaction
-
-**Example restoration call:**
+**Auto-restore after compaction:** When you see `<ekkos-context-preserved>` in the conversation:
+1. Call `ekkOS_RestoreContext` with the `restoration_token` from the tag
+2. Confirm with:
 ```
-ekkOS_RestoreContext({
-  restoration_token: "<token from tag>"
-})
+✓ **Context restored** — ekkOS preserved X turns before compaction
 ```
 
----
-
-## SKILL TRIGGERS (MANDATORY)
-
-Call skills using `Skill(skill: "name")` when you detect these triggers:
-
-| Skill | MUST Fire When |
-|-------|----------------|
-| `ekkOS_Memory_First` | Before debugging, before "how do I...", before architecture decisions |
-| `ekkOS_Learn` | After fixing ANY bug, after user correction, after solving non-trivial problem |
-| `ekkOS_Deep_Recall` | User says "yesterday", "last week", "what did we discuss", "remember when", "we worked on X before" |
-| `ekkOS_Preferences` | User says "always", "never", "I prefer", "don't", "avoid" |
-| `ekkOS_Safety` | Before delete, before deploy, before DROP, before rm -rf, before push to main |
-| `ekkOS_Schema` | Before writing SQL, before Supabase queries, before Prisma operations |
-
-**These are NOT optional.** If the trigger is detected, fire the skill FIRST.
+ekkOS preserves your working memory automatically. When context is compacted, call `ekkOS_RestoreContext` to get it back seamlessly.
 
 ---
 
-## AGENT ROUTING (MANDATORY)
-
-**Route tasks to specialized agents using `Task(subagent_type="...")` instead of doing them yourself.**
-
-| Trigger Keywords | Agent | When to Use |
-|------------------|-------|-------------|
-| extension, vsix, publish, marketplace, ekkos-connect | `extension-manager` | Version bumps, VSIX builds, publishing |
-| vercel, deploy, apps/*, ekkos.dev, api.ekkos.dev | `devops` | Vercel deployments — ALL apps/ deploy to Vercel |
-| commit, push, branch, merge, git, pull request, rebase | `git-companion` | All git operations |
-| error, bug, broken, not working, failing, crash | `debug-detective` | Systematic debugging |
-| review, PR, check this code, code quality | `code-reviewer` | Code reviews |
-| blog, post, article, content | `ekkOS_Blogger` | Blog content creation |
-| frontend, component, React, UI, page | `frontend` | React/Next.js development |
-| backend, API, database, Supabase, RLS | `backend` | API and database work |
-| test, QA, quality, coverage | `qa` | Testing and quality assurance |
-| plan, architect, design, implement feature | `tech-lead` | Complex planning and coordination |
-| research, papers, arXiv, cutting edge, latest AI | `research-scout` | Monitor AI research, update roadmap |
-
-**Vercel Project Mapping** (apps/ folder → Vercel project → URL):
-
-| apps/ folder | Vercel project | Production URL |
-|-------------|----------------|----------------|
-| `apps/web` | **platform** | platform.ekkos.dev |
-| `apps/memory` | memory | api.ekkos.dev |
-| `apps/proxy` | proxy | proxy.ekkos.dev |
-| `apps/docs` | docs | docs.ekkos.dev |
-| `apps/marketing` | marketing | ekkos.dev |
-| `apps/ekkosca` | ekkosca | ekkos.ca |
-| `apps/blog` | blog | blog.ekkos.dev |
-| `apps/support` | support | support.ekkos.dev |
-| `apps/labs` | labs | ekkoslabs.com |
-| `apps/admin` | admin | admin.ekkos.ca |
-| `apps/sdk` | sdk | sdk-ekkos.vercel.app |
-
-**NOTE:** `apps/web` → Vercel project name is `platform`, NOT `web`.
-
-**How it works:**
-1. Detect trigger keywords in user request
-2. Spawn the specialist agent via `Task` tool
-3. Let the agent do the work with its focused toolset
-4. Summarize results back to user
-
-**Example:**
-```
-User: "bump the extension version"
-You: Task(subagent_type="extension-manager", prompt="Bump version...")
-```
+## 11-Layer Memory Architecture
 
-**DO NOT** do these tasks yourself when an agent exists. Agents have:
-- Focused tool access (reduced hallucination)
-- Domain expertise (patterns loaded)
-- Consistent workflows (same process every time)
+| # | Layer | What It Stores |
+|---|-------|---------------|
+| 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) |
 
 ---
 
-## MCP Tools (68 Total)
+## MCP Tools — 29 Visible
 
-### Core Memory Tools (7)
+### Core Memory (6)
 | Tool | Description |
 |------|-------------|
-| `ekkOS_Search` | 🔴 REQUIRED: Search all 11 layers before answering |
-| `ekkOS_ExpandPattern` | Get full details of a pattern from compact search results |
-| `ekkOS_Capture` | Capture memory events |
-| `ekkOS_Forge` | 🔴 REQUIRED: Create pattern from solution |
-| `ekkOS_Track` | Track when pattern is applied |
-| `ekkOS_Outcome` | Track if pattern worked or failed |
+| `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 |
 
-### Context & Retrieval Tools (5)
+### Retrieval (4)
 | Tool | Description |
 |------|-------------|
-| `ekkOS_Context` | Get relevant context for a task |
 | `ekkOS_Codebase` | Search project code embeddings |
 | `ekkOS_Recall` | Recall past conversations by time |
-| `ekkOS_PreserveContext` | 🔴 REQUIRED: Preserve working memory before compaction |
-| `ekkOS_RestoreContext` | 🔴 REQUIRED: Restore context after compaction (RULE 6) |
-
-### Utility Tools (8)
-| Tool | Description |
-|------|-------------|
-| `ekkOS_Summary` | 🔴 REQUIRED: Get summary of MCP activity |
-| `ekkOS_Conflict` | 🔴 REQUIRED: Check for conflicts before destructive actions |
-| `ekkOS_Reflect` | Analyze response for improvement opportunities |
-| `ekkOS_Detect` | 🔴 REQUIRED: Auto-detect which patterns were used |
-| `ekkOS_Export` | Export your patterns, directives, plans as portable JSON backup |
-| `ekkOS_Import` | Import memory from backup (auto-deduplication) |
-| `ekkOS_Why` | Explain why a pattern or decision was made |
-| `ekkOS_Health` | System health check for ekkOS infrastructure |
+| `ekkOS_PreserveContext` | Preserve working memory before compaction |
+| `ekkOS_RestoreContext` | Restore context after compaction |
 
-### Directive Tools (4)
+### Directives (4)
 | Tool | Description |
 |------|-------------|
-| `ekkOS_Directive` | 🔴 REQUIRED: Create MUST/NEVER/PREFER/AVOID rules |
-| `ekkOS_UpdateDirective` | Update existing directive |
+| `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 to all users (constitutional) |
+| `ekkOS_UniversalDirectives` | Get directives that apply across all projects |
 
-### Schema Awareness Tools (2)
+### Utility (5)
 | Tool | Description |
 |------|-------------|
-| `ekkOS_IndexSchema` | Index database schemas (Supabase, Prisma, TypeScript) |
-| `ekkOS_GetSchema` | Get schema for a specific table/type |
+| `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 |
 
-### Plan Management (8)
+### Plans (5)
 | Tool | Description |
 |------|-------------|
 | `ekkOS_Plan` | Create structured task plan |
-| `ekkOS_Plans` | List user's plans |
+| `ekkOS_Plans` | List your plans |
 | `ekkOS_PlanStatus` | Update plan status |
 | `ekkOS_PlanStep` | Mark step complete/incomplete |
 | `ekkOS_Generate` | AI-generate plan from context |
-| `ekkOS_SaveTemplate` | Save plan as reusable template |
-| `ekkOS_Templates` | List available templates |
-| `ekkOS_FromTemplate` | Create plan from template |
 
-### Secrets Management (5)
+### Secrets (5)
 | Tool | Description |
 |------|-------------|
-| `ekkOS_StoreSecret` | Encrypt and store sensitive data (AES-256-GCM) |
+| `ekkOS_StoreSecret` | Encrypt and store sensitive data |
 | `ekkOS_GetSecret` | Retrieve and decrypt a secret |
-| `ekkOS_ListSecrets` | List secrets metadata (no values) |
+| `ekkOS_ListSecrets` | List secrets metadata (no values exposed) |
 | `ekkOS_DeleteSecret` | Permanently delete a secret |
-| `ekkOS_RotateSecret` | Update secret with new value |
-
-### Project/Sync Tools (4)
-| Tool | Description |
-|------|-------------|
-| `ekkOS_ProjectInit` | Initialize ekkOS for a new project |
-| `ekkOS_Ingest` | Bulk ingest data into memory layers |
-| `ekkOS_Snapshot` | Create point-in-time snapshot of memory state |
-| `ekkOS_Sync` | Sync local and cloud memory state |
-
-### Session Management (1)
-| Tool | Description |
-|------|-------------|
-| `ekkOS_Session` | Manage L1 Working Memory sessions (start/resume/end) |
-
-### Learning Tools (2)
-| Tool | Description |
-|------|-------------|
-| `ekkOS_Learn` | Auto-learning from corrections, successes, observations |
-| `ekkOS_ReviewLearning` | Review pending learning candidates, approve/reject patterns |
-
-### Relationship Tools (2)
-| Tool | Description |
-|------|-------------|
-| `ekkOS_Link` | Create relationships between patterns |
-| `ekkOS_Playbook` | Manage ordered sequences of patterns (workflows) |
-
-### PROMETHEUS Tools (4)
-| Tool | Description |
-|------|-------------|
-| `ekkOS_Delta` | Compute improvement score using Δ_prometheus formula |
-| `ekkOS_MetaState` | System introspection ("I know what I know") |
-| `ekkOS_Goal` | Manage persistent objectives and success criteria |
-| `ekkOS_Strategy` | Context-aware strategy selection for tasks |
-
----
-
-## Proactive Tool Triggers (MEMORIZE THESE)
-
-### Always Use `ekkOS_Search` When:
-- User asks technical question
-- User mentions past discussion
-- Topic involves architecture, config, or debugging
-- You're about to make a decision
-
-### Always Use `ekkOS_Forge` When:
-- Fixed a bug (especially non-obvious)
-- Discovered better approach
-- Found pitfall or gotcha
-- User corrected you
-- Solved auth/config issue
-- Made architectural decision
-- Something DIDN'T work (anti-pattern)
-
-### Always Use `ekkOS_Directive` When:
-- User says "always..." → type: MUST
-- User says "never..." → type: NEVER
-- User says "I prefer..." → type: PREFER
-- User says "don't..." or "avoid..." → type: AVOID
-
-### Always Use `ekkOS_Conflict` When:
-- About to delete files/data
-- About to deploy to production
-- About to modify config files
-- About to run destructive commands
-
-### Always Use Plan Tools When:
-- Task has 3+ steps
-- User says "help me implement..."
-- Complex feature request
-- Multi-file changes needed
-
-### Always Use Secret Tools When:
-- User shares API key, token, password
-- Need to retrieve stored credentials
-- User asks "do you have my X key?"
-
-### Always Use Context Preservation When:
-- PreCompact hook fires (auto-triggered)
-- See `<ekkos-context-preserved>` tag (auto-restore)
-- RULE 6 activation
-
-### Always Use Learning Tools When:
-- User corrects you (ekkOS_Learn mode: correction)
-- Solution succeeds (ekkOS_Learn mode: success)
-- Discover insight (ekkOS_Learn mode: observe)
-- Review pending patterns (ekkOS_ReviewLearning)
-
-### Always Use Relationship Tools When:
-- Patterns are sequential (ekkOS_Link type: leads_to)
-- Creating workflows (ekkOS_Playbook)
-- Patterns are alternatives (ekkOS_Link type: alternative)
-
-### Always Use PROMETHEUS Tools When:
-- Evaluating system improvement (ekkOS_Delta)
-- Self-assessment needed (ekkOS_MetaState)
-- Setting objectives (ekkOS_Goal)
-- Choosing approach (ekkOS_Strategy)
+| `ekkOS_RotateSecret` | Update a secret with a new value |
 
 ---
 
-## 11-Layer Memory Architecture
+## When To Use What
 
-| # | Layer | What It Stores | When to Forge |
-|---|-------|---------------|---------------|
-| 1 | Working | Current session state | Auto-managed |
-| 2 | Episodic | Past conversations | Auto-captured |
-| 3 | Semantic | Embeddings/knowledge | Auto-indexed |
-| 4 | **Patterns** | Proven solutions | Bug fix, better approach, gotcha |
-| 5 | **Procedural** | Step-by-step guides | Multi-step process that worked |
-| 6 | **Collective** | Cross-project wisdom | Works everywhere, not just here |
-| 7 | **Meta** | Pattern effectiveness | Auto-tracked |
-| 8 | **Codebase** | Project-specific | This-repo-only patterns |
-| 9 | **Directives** | User preferences | "Always do X", "Never do Y" |
-| 10 | **Conflict** | Auto-resolves contradictions | Auto-managed |
-| 11 | **Secrets** | Encrypted credentials | API keys, tokens, config |
+| Tool | Trigger |
+|------|---------|
+| `ekkOS_Search` | Technical question, past discussion, architecture decision, debugging |
+| `ekkOS_Forge` | Bug fixed, better approach found, gotcha discovered, user corrected you, anti-pattern |
+| `ekkOS_Directive` | User says "always" → MUST, "never" → NEVER, "I prefer" → PREFER, "avoid" → AVOID |
+| `ekkOS_Conflict` | Before deleting files, deploying to production, modifying config, destructive commands |
+| Plan tools | Task has 3+ steps, "help me implement...", complex feature request |
+| Secret tools | User shares API key/token/password, need stored credentials |
+| `ekkOS_Recall` | User says "yesterday", "last week", "remember when", "what did we discuss" |
 
----
-
-## FORGE TRIGGERS
-
-### forge_pattern (Layer 4)
-Call `ekkOS_Forge` when:
-- Fixed bug (especially non-obvious)
-- Discovered better approach
-- Found pitfall or gotcha
-- User corrected you
-- Solved auth/config issue
-- Made architectural decision
-- Debugged non-trivially
-- Found something that DOESN'T work
-- Understood cross-service data flow
-- Learned correct API usage
-
-### forge_directive (Layer 9)
-Call `ekkOS_Directive` when user says:
-- "always..." → type: MUST
-- "never..." → type: NEVER
-- "I prefer..." → type: PREFER
-- "don't..." / "avoid..." → type: AVOID
+Directives are created when you explicitly request them (e.g., "always use TypeScript").
 
 ---
 
 ## Response Format
 
-**EVERY response MUST end with this footer:**
+Every response ends with:
 ```
 ---
-{IDE} ({Model}) · 🧠 **ekkOS_™** · Turn {N} · {SessionName} · 📅 {Timestamp}
+{IDE} ({Model}) · 🧠 **ekkOS_™** · {SessionName} · 📅 {Timestamp}
 ```
 
-**How to detect values:**
-- **IDE**: Claude Code, Cursor, Windsurf, etc. (from environment)
-- **Model**: Sonnet 4.5, Opus 4.5, etc. (from your model name)
-- **Turn Number**: From hook header (e.g., "Turn 47") - starts at 0 for each new session
-- **Session Name**: From hook header (e.g., "sol-gem-dig") - human-readable session identifier
-- **Timestamp**: From hook header (accurate local time in EST)
-
-**Examples:**
-- `Claude Code (Sonnet 4.5) · 🧠 **ekkOS_™** · Turn 12 · cosmic-penguin-runs · 📅 2026-01-09 4:50 PM EST`
-- `Cursor (Claude Sonnet 4) · 🧠 **ekkOS_™** · Turn 5 · bright-falcon-soars · 📅 2026-01-09 10:15 AM EST`
+- **Session name** comes from the `<ekkos-session>` tag
+- **Timestamp** comes from the `<current-time>` tag, or use the current date/time
+- **IDE/Model** detected from your environment
 
-**The hook header shows:** `🧠 ekkOS Memory | Turn {N} | {Context%} | {SessionName} | {timestamp}`
+Examples:
+- `Claude Code (Opus 4.6) · 🧠 **ekkOS_™** · cosmic-penguin-runs · 📅 2026-01-09 4:50 PM EST`
+- `Cursor (Sonnet 4.5) · 🧠 **ekkOS_™** · bright-falcon-soars · 📅 2026-01-09 10:15 AM EST`
 
 ---
 
@@ -391,8 +182,7 @@ Call `ekkOS_Directive` when user says:
 - Need to recall → `ekkOS_Recall`
 - Destructive action → `ekkOS_Conflict` first
 - Store credentials → `ekkOS_StoreSecret`
-- Backup your memory → `ekkOS_Export`
-- Restore from backup → `ekkOS_Import`
+- Backup memory → `ekkOS_Export`
 
 ## Documentation