codymaster 4.8.0 → 5.2.0

package/CHANGELOG.md

@@ -4,6 +4,55 @@ All notable changes to this project will be documented in this file.
 
 Categories: 🚀 **Improvements** | 🐛 **Bug Fixes** | 🔒 **Security**
 
+## [Unreleased]
+
+### 🚀 Improvements — Zero-Token Skill Discovery
+- Removed LLM token waste on skill search by porting deterministic tech-stack parsing natively into `src/indexer/skills.ts`.
+- Introduced `cm index skills` CLI command to compile `.cm/project-skills.md` locally.
+- Updated Fission framework (`cm-project-bootstrap`, `cm-skill-index`, `AGENTS.md`) to prioritize zero-token local indexes over massive community directory sweeps.
+
+### 🚀 Improvements — CodyMaster v6.0 "Self-Evolving Brain"
+
+- **Smart Brain Router** — `src/smart-brain-router.ts` adds a zero-cost keyword-based classifier that dynamically selects the optimal memory tiers for incoming tasks, reducing token waste by up to 60-80% for simple tasks.
+- **Skill Execution Cache** — `src/skill-execution-cache.ts` introduces an FTS5-backed warm cache for successful execution chains (effectiveness >= 0.70), skipping BM25 and LLM selection entirely for recurring task patterns.
+- **Per-Tier Adaptive Token Budgeting** — Enhanced `src/token-budget.ts` controls budgets natively per memory tier and visually outputs budget and savings reports.
+- **Evolution Engine (Skill Evolver)** — `src/skill-evolver.ts` brings true autonomy. CodyMaster now auto-repairs and auto-generates `SKILL.md` files locally with three modes: `FIX` (adds warnings to broken skills), `DERIVED` (clones highly successful fallback paths), and `CAPTURED` (creates new skills completely autonomously when a task completes without predefined skills). Ships with anti-loop protection and automatic `.md` backups.
+- **Learning Promoter** — `src/learning-promoter.ts` scans working memory for recurring failures or patterns (reinforced >= 3 times) and automatically promotes them into permanent `cm-learned-*` skills.
+- **New CLI Tools** — `cm smart plan/tiers`, `cm token report/savings`, and a full `cm evolve` lifecycle toolkit (`status`, `run`, `history`, `rollback`, `candidates`, `promote`).
+- **Comprehensive Testing** — Extensively covered the new architectures with 62 new testing scenarios (system currently sits at 302 passed tests natively).
+
+### 🚀 Improvements — OpenViking De-scope
+
+- Removed OpenViking auto-installation from `install.sh` and `scripts/postinstall.js`; CodyMaster now keeps the normal install path focused on the supported Node-first stack.
+- Updated runtime/config/docs guidance so `storage.backend: viking` is treated as a deprecated experimental path instead of a default-facing feature.
+- Removed the remaining OpenViking runtime backend, demo script, and dedicated tests; legacy `storage.backend: viking` configs now warn and fall back to SQLite.
+
+### 🚀 Improvements — Advisory Loop Productization
+
+- Added `cm advisory report`, `cm advisory metrics`, and `cm advisory handoff` so operators can inspect execution analyses, review per-skill quality, and generate structured recovery notes for `cm-skill-health` / `cm-skill-evolution`.
+- `selectTopSkills()` now uses recorded `skill_metrics` as a quality-weighted boost for optional step ranking, while mandatory `always` steps remain unchanged.
+- Added `src/advisory-handoff.ts` as the shared contract between analyzer output and self-healing workflows; the handoff can be emitted as Markdown or JSON.
+- Exposed the advisory loop to MCP clients via `cm_advisory_report`, `cm_advisory_metrics`, and `cm_advisory_handoff` in `src/mcp-context-server.ts`.
+- Added workflow and API docs for the advisory loop under `docs/workflows/advisory-loop.md` and `docs/api/api-reference.md`.
+
+## [5.1.0] - 2026-04-11
+
+### 🚀 Improvements — SkillsBench Intelligence + Ecosystem Reach
+
+- **Intelligent Skill Selection (`selectTopSkills`)** — `src/skill-chain.ts` now applies SkillsBench research findings at runtime. Each chain execution dynamically selects the top-3 most relevant skills for the current task (scored by BM25 token overlap + mandatory-step priority bonus). Result: 2-3 focused skills → **+18.6pp** improvement vs 4+ loaded statically (+5.9pp). Chains with >3 mandatory steps still execute fully with a performance advisory logged to stderr. New exported functions: `scoreStepRelevance()`, `selectTopSkills()`.
+
+- **`cm mcp-serve` command** — New `src/cli/commands/mcp-serve.ts` registers `cm mcp-serve [--project <path>] [--print-config]`. Spawns `dist/mcp-context-server.js` over stdio with SIGINT/SIGTERM forwarding. `--print-config` prints ready-to-paste JSON config for **Goose** and **Claude Desktop**, enabling one-command ecosystem integration. Goose extension config: `{ "type": "stdio", "cmd": "npx", "args": ["codymaster", "mcp-serve"] }`.
+
+- **CodyBench v0.1** — New `cm bench` command backed by `src/codybench/` scaffolding. Three eval suites with A/B comparison (with vs without CodyMaster): `tdd-regression` (bug catch rate), `token-efficiency` (savings vs documented 78% claim), `memory-retention` (SQLite recall hit rate). Runner: `claude-code`. Judge: automated (mean/min/max/stddev). Results written to `codybench/reports/`. Methodology mirrors Goose's transparent benchmark publication strategy.
+
+- **NLI Memory Interface (`cm_memory_write` + `cm_natural`)** — MCP server now exposes **15 tools** (up from 13). `cm_memory_write` persists a learning to SQLite with auto-detected category (arch_decision / bug_fix / user_pref / code_pattern / context), configurable scope (session/project/global), TTL, and importance. `cm_natural` is a natural language router: "remember that…" → write, "forget about…" → decay, "what did we learn about…" → FTS5 query. Zero new npm dependencies; pattern matching via regex.
+
+- **Goose integration guide** — `docs/integrations/goose.md` — step-by-step tutorial: install CodyMaster → `cm mcp-serve --print-config` → paste YAML config into Goose → test with `cm_natural`. Tool reference table included.
+
+- **GitHub community templates** — `.github/ISSUE_TEMPLATE/` now includes `good-first-skill.md` (with SkillsBench 12-point quality checklist), `benchmark-needed.md` (CodyBench eval request), `skill-improvement.md` (rubric-based improvement proposal).
+
+- **Version bump** — `package.json` version: `5.0.0` → `5.1.0`. CLI command count: 18 → 20 (`mcp-serve`, `bench`). MCP tool count: 13 → 15.
+
 ## [4.8.0] - 2026-04-10
 
 ### 🚀 Improvements — Documentation site & README accuracy
@@ -27,8 +76,8 @@ Categories: 🚀 **Improvements** | 🐛 **Bug Fixes** | 🔒 **Security**
 
 ### 🚀 Improvements — OpenViking Backend (Real Implementation)
 
-- **`VikingBackend` — real implementation** — `src/backends/viking-backend.ts` implements all 11 `StorageBackend` methods by calling the [OpenViking REST API](https://github.com/volcengine/OpenViking) (default: `http://localhost:1933`). Replaces the placeholder stub from v4.5.5.
-- **`VikingHttpClient`** — New `src/backends/viking-http-client.ts`: thin fetch-based HTTP client wrapping OpenViking's `/write`, `/read`, `/ls`, `/search`, `/abstract`, `/overview`, `/health`, `/mkdir` endpoints. Zero new npm dependencies (uses Node.js built-in `fetch`).
+- `**VikingBackend` — real implementation** — `src/backends/viking-backend.ts` implements all 11 `StorageBackend` methods by calling the [OpenViking REST API](https://github.com/volcengine/OpenViking) (default: `http://localhost:1933`). Replaces the placeholder stub from v4.5.5.
+- `**VikingHttpClient`** — New `src/backends/viking-http-client.ts`: thin fetch-based HTTP client wrapping OpenViking's `/write`, `/read`, `/ls`, `/search`, `/abstract`, `/overview`, `/health`, `/mkdir` endpoints. Zero new npm dependencies (uses Node.js built-in `fetch`).
 - **URI layout in OpenViking workspace:** `learnings/<id>.json`, `decisions/<id>.json`, `indexes/<resource>/<level>.md`, `skill-outputs/<sessionId>/<id>.json`.
 - **Semantic vector search** — `queryLearnings()` and `queryDecisions()` now call OpenViking's `/search` endpoint, which uses embedding-based vector similarity. Finds related memories even when query terms don't match exactly (e.g. "async timeout" matches "network latency spike").
 - **Auto L0/L1 via engine** — `getL0Abstract()` and `getL1Overview()` call OpenViking's `/abstract` and `/overview` endpoints. No manual `cm continuity index` needed with Viking backend.
@@ -42,10 +91,10 @@ Categories: 🚀 **Improvements** | 🐛 **Bug Fixes** | 🔒 **Security**
 
 ### 🚀 Improvements — StorageBackend Interface (OpenViking Swap Path)
 
-- **`StorageBackend` interface** — New `src/storage-backend.ts` defines an 11-method abstraction over CodyMaster's persistent memory store. Swapping storage engines is now a config change, not a code rewrite.
-- **`SqliteBackend`** — Thin wrapper around `context-db.ts`. Zero logic duplication; all existing callers untouched. New callers use `getBackend(projectPath)` for polymorphism.
-- **`VikingBackend` stub** — All methods throw a descriptive `NotImplementedError` with step-by-step install instructions for `@openviking/client`. Explicit swap path documented.
-- **`getBackend(projectPath)` factory** — Reads `.cm/config.yaml → storage.backend` (`sqlite` | `viking`). Defaults to `sqlite` when config is absent or malformed.
+- `**StorageBackend` interface** — New `src/storage-backend.ts` defines an 11-method abstraction over CodyMaster's persistent memory store. Swapping storage engines is now a config change, not a code rewrite.
+- `**SqliteBackend`** — Thin wrapper around `context-db.ts`. Zero logic duplication; all existing callers untouched. New callers use `getBackend(projectPath)` for polymorphism.
+- `**VikingBackend` stub** — All methods throw a descriptive `NotImplementedError` with step-by-step install instructions for `@openviking/client`. Explicit swap path documented.
+- `**getBackend(projectPath)` factory** — Reads `.cm/config.yaml → storage.backend` (`sqlite` | `viking`). Defaults to `sqlite` when config is absent or malformed.
 - **Config template updated** — `cm continuity init` now writes a `storage:` section to `.cm/config.yaml` with the backend switch commented out.
 - **Zero breaking changes** — `context-db.ts` and all existing callers unchanged. StorageBackend is additive.
 - **Test suite expanded** — `test/storage-backend.test.ts` (23 tests): factory defaults, config-driven dispatch, SqliteBackend full roundtrip, VikingBackend error messages. Total: **178 passed · 16 skipped · 0 failed**.
@@ -107,7 +156,6 @@ Categories: 🚀 **Improvements** | 🐛 **Bug Fixes** | 🔒 **Security**
 - **OpenSpec Protocol Upgrade** — Enhanced integration with Fission-AI OpenSpec format (`openspec/changes/[initiative]/proposal.md`) for seamless context handoffs to downstream skills (`cm-planning` & `cm-execution`).
 - **Skill Evolution Engine** — Successfully executed automated self-healing mechanisms (Mode: FIX) for `cm-tdd` and `cm-debugging` after health monitor alerts.
 
-
 ## [4.3.0] - 2026-03-27
 
 ### 🚀 Improvements

package/README.md

@@ -1,22 +1,10 @@
-<div align="center">
-
 [English](README.md) | [Tiếng Việt](README-vi.md) | [中文](README-zh.md) | [Русский](README-ru.md) | [한국어](README-ko.md) | [हिन्दी](README-hi.md)
 
 # 🧠 CodyMaster
 
 ### Your AI Agent is smart. CodyMaster makes it *wise*.
 
-**68+ Skills · 18 Commands · 1 Plugin · 7+ Platforms · 6 Languages**
-
-<p align="center">
-  <img alt="Version" src="https://img.shields.io/badge/version-4.8.0-blue.svg?cacheSeconds=2592000" />
-  <img alt="Skills" src="https://img.shields.io/badge/skills-68+-success.svg" />
-  <img alt="Platforms" src="https://img.shields.io/badge/platforms-7+-orange.svg" />
-  <img alt="Open Source" src="https://img.shields.io/badge/license-ISC-purple.svg" />
-  <a href="https://github.com/tody-agent/codymaster#readme" target="_blank">
-    <img alt="Documentation" src="https://img.shields.io/badge/documentation-yes-brightgreen.svg" />
-  </a>
-</p>
+**60+ Skills · 20+ Commands · 1 Plugin · 8+ Platforms · 6 Languages · v6.0.0**
 
 ```
     ( . \ --- / . )
@@ -28,11 +16,11 @@
   Your smart coding companion.
 ```
 
-![CodyMaster Kanban Dashboard](assets/images/dashboard.png)
+CodyMaster Kanban Dashboard
 
-### 🌟 If CodyMaster saves you time, give it a [Star](https://github.com/tody-agent/codymaster)! 🌟
+[![Discord](https://img.shields.io/badge/Discord-Join-7289da?logo=discord&logoColor=white)](https://discord.gg/codymaster)
 
-</div>
+### 🌟 If CodyMaster saves you time, give it a [Star](https://github.com/tody-agent/codymaster)! 🌟
 
 ---
 
@@ -42,14 +30,16 @@ You installed an AI coding agent. It's *brilliant*. It writes code faster than a
 
 But then reality hits:
 
-| 😤 What Actually Happens                                                            | 💀 The Real Cost                               |
-| ----------------------------------------------------------------------------------- | ---------------------------------------------- |
+
+| 😤 What Actually Happens                                                     | 💀 The Real Cost                               |
+| ---------------------------------------------------------------------------- | ---------------------------------------------- |
 | AI designs**differently every single time** — same brand, 3 different styles | Clients think you're 3 different companies     |
-| AI fixes one bug,**silently breaks 5 other things**                           | You redo the same work 3-4 times               |
-| AI**forgets everything** between sessions                                     | You re-explain the same codebase every morning |
-| AI writes zero tests, zero docs                                                     | Your codebase becomes a house of cards         |
+| AI fixes one bug,**silently breaks 5 other things**                          | You redo the same work 3-4 times               |
+| AI**forgets everything** between sessions                                    | You re-explain the same codebase every morning |
+| AI writes zero tests, zero docs                                              | Your codebase becomes a house of cards         |
 | You install 15 different skills —**none of them talk to each other**         | Frankenstein toolkit with zero synergy         |
-| Deploy to production =**deploy and pray** 🙏                                  | Broken deploys at 2 AM, no rollback            |
+| Deploy to production =**deploy and pray** 🙏                                 | Broken deploys at 2 AM, no rollback            |
+
 
 > *"AI gave me 100 hands. But without discipline, those hands created chaos."*
 > — **Tody Le**, Head of Product · 10+ years · Creator of CodyMaster
@@ -77,6 +67,8 @@ graph TD
     class B,C,D,E,F,G,H team;
 ```
 
+
+
 ---
 
 ## ⚡ What Makes CodyMaster Different
@@ -105,6 +97,8 @@ graph LR
     class A,B,C,D,E,F,G,H,I,J,K,L phase;
 ```
 
+
+
 ### 🧠 The Unified Brain: 5-Tier Memory + Smart Spine
 
 Your AI doesn't just execute — it **understands and remembers** using a multi-scale, 5-Tier + Smart Spine architecture that persists across sessions and machines:
@@ -116,13 +110,16 @@ Your AI doesn't just execute — it **understands and remembers** using a multi-
 5. **Structural Memory (`cm-codeintell`)** — AST-based CodeGraph. Up to 95% token compression for full codebase context.
 
 🦴 **Smart Spine (v4.6+)** — The nervous system connecting all 5 tiers:
+
 - **SQLite + FTS5** — BM25-ranked keyword search replaces flat JSON scans.
-- **Progressive Loading (L0/L1/L2)** — Context loaded at cheapest sufficient depth. 78% token savings.
+- **Progressive Loading (L0/L1/L2)** & **Smart Brain Router** — Context loaded at cheapest sufficient depth via a robust task classifier. Up to **80% token savings** on standard workflows.
+- **Skill Execution Cache** — Warm FTS5 cache tracks successful agent skill chains. Matches bypass token-heavy LLM decision loops for instant task resolution.
 - **cm:// URI Scheme** — Skills request context by URI, not file paths.
 - **Token Budget** — 200k window pre-allocated by category. No more silent overflow.
 - **Context Bus** — Skills share outputs in real-time within a chain.
-- **MCP Server** — 13 tools exposed to Claude Desktop and any MCP client (`src/mcp-context-server.ts`).
-- **OpenViking Backend natively integrated** — Inspired by OpenViking's architecture, CodyMaster defaults to `openviking` auto-installation. It delivers true semantic vector graph memory, automatic session compression, and temporal context layering. (One config line change: `storage.backend: viking`).
+- **MCP Server** — 18 tools exposed to Claude Desktop, Goose, and any MCP client (`src/mcp-context-server.ts`). Includes memory tools (`cm_memory_write`, `cm_natural`) plus advisory JSON surfaces (`cm_advisory_report`, `cm_advisory_metrics`, `cm_advisory_handoff`).
+- **Intelligent Skill Selection** — `selectTopSkills()` dynamically picks the 2-3 most task-relevant skills per chain execution. Backed by SkillsBench research: 2-3 focused skills = **+18.6pp** vs 4+ loaded statically.
+- **SQLite-first memory stack** — CodyMaster ships a supported default path built on SQLite + FTS5, token-budgeted context loading, and optional `qmd` / code intelligence layers. The older OpenViking path has been removed from the runtime.
 
 ☁️ **The Cloud Brain (`cm-notebooklm`)**
 High-value knowledge and design patterns are synced to NotebookLM, providing a universal, cross-machine "Soul" for your project. Auto-generate podcasts and flashcards to onboard human developers alongside the AI.
@@ -153,6 +150,8 @@ flowchart LR
     style G fill:#4cd137,stroke:#44bd32,color:#fff
 ```
 
+
+
 > **Result:** Zero leaked secrets. Zero wrong-account deploys. Zero "worked on my machine" failures.
 
 ### 🎨 Design System Builder — Even From Old Products
@@ -161,7 +160,7 @@ Got a legacy product with no design system? **cm-design-system** scans your webs
 
 ### 📝 Zero Documentation? No Problem.
 
-Don't know what the old code does? **`cm-dockit`** reads your entire codebase and generates:
+Don't know what the old code does? `**cm-dockit`** reads your entire codebase and generates:
 
 - 📚 Technical architecture docs
 - 📖 User guides & SOPs
@@ -173,47 +172,51 @@ Don't know what the old code does? **`cm-dockit`** reads your entire codebase an
 
 ### 💡 Strategic Brainstorming (Design Thinking + 9 Windows)
 
-Before diving into code for complex requests, **`cm-brainstorm-idea`** evaluates your product using multi-dimensional analysis (Tech, Product, Design, Business). It generates 2-3 qualified options using the 9 Windows (TRIZ) framework and provides a visual UI Preview via **Pencil.dev** or **Google Stitch** to validate the direction before detailed planning. 
+Before diving into code for complex requests, `**cm-brainstorm-idea`** evaluates your product using multi-dimensional analysis (Tech, Product, Design, Business). It generates 2-3 qualified options using the 9 Windows (TRIZ) framework and provides a visual UI Preview via **Pencil.dev** or **Google Stitch** to validate the direction before detailed planning. 
 
 📖 [TRIZ-parallel workflow & UI preview handoff →](docs/architecture/triz-parallel-engine.md)
 
-
 ### 🏭 AI Content Factory v2.0 & Visual Dashboard
 
-Need to scale content? **`cm-content-factory`** is a self-learning, multi-agent content engine. It automatically researches, writes, audits (SEO & Persuasion), and deploys high-converting articles with the Content Mastery framework (StoryBrand + Cialdini) to guarantee conversion.
+Need to scale content? `**cm-content-factory`** is a self-learning, multi-agent content engine. It automatically researches, writes, audits (SEO & Persuasion), and deploys high-converting articles with the Content Mastery framework (StoryBrand + Cialdini) to guarantee conversion.
 
 Track it all on the **Visual Dashboard** (`cm-dashboard`): No more guessing. Track every task, every agent, every deployment on a real-time Kanban board. Pipeline progress, token tracker, event log — all on one screen.
 
-### 🧬 Self-Healing AI (Skills That Fix Themselves)
+### 🧬 Self-Healing Skills (Recovery, Search, and Evolution)
 
-CodyMaster doesn't just run skills — it **watches them, scores them, and heals them automatically.**
+CodyMaster ships a dedicated self-healing skill family for keeping the skill library usable as the repo evolves.
 
-- **`cm-skill-health`** monitors every invocation: success rate, token usage, error patterns.
-- **`cm-skill-evolution`** auto-patches degraded skills (Mode: FIX) when health scores drop below threshold.
-- **`cm-skill-chain` Auto-Dispatch** — Inspired by OpenSpace automation orchestrators, sequence dispatching is now 100% automated with intelligent task detection, zero-touch handoffs, and multi-agent coordination.
-- **`cm-skill-search`** uses BM25 ranking to find the right skill for any task.
-- **`cm-skill-share`** exports & imports skills across teams and machines.
+- `**cm-skill-health`** audits a skill's real health from shipped signals: docs drift, broken references, retro notes, validation, and gates.
+- `**cm-skill-evolution`** (Skill Evolver) completes the autonomy loop with three modes: `FIX`, `DERIVED`, and `CAPTURED`. It modifies, clones, and generates new skills automatically based on analyzer recommendations, paired with anti-loop protection and `.md` backups.
+- `**cm-learning-promoter`** searches your database for recurring task struggles and automatically graduates them into permanently coded skills (`cm-learned-*`) when appropriately reinforced.
+- `**cm advisory report` / `metrics` / `handoff`** turn execution telemetry into a reviewable operator loop before any skill repair begins. 
+- Integrated Evolution commands (`cm evolve run/status/promote`) give immediate insight into all mutations.
+- `**cm-skill-chain` Auto-Dispatch** — sequence dispatching remains automated with task detection and multi-step handoffs.
+- `**cm-skill-search`** finds the best skill through `cm suggest`, skill indexes, and repo search.
+- `**cm-skill-share`** packages a skill safely across repos and machines without dropping companion files.
 
-> **Think of it like an immune system for your AI toolkit.** Skills that break get healed. Skills that work well get reinforced. Dead skills get archived.
+> **Think of it like an immune system for your AI toolkit.** First inspect the telemetry, then diagnose the skill, then repair it deliberately, then capture the learning.
 
 ### 🚀 Growth Hacking Engine
 
-Need popups, booking flows, or lead capture? **`cm-growth-hacking`** generates complete conversion systems: Bottom Sheet + Calendar CTA + Tracking. Auto-detects industry, selects the right pattern, wires up **`cm-booking-calendar`** for appointments and **`cm-ads-tracker`** for pixel tracking. Zero dependencies.
+Need popups, booking flows, or lead capture? `**cm-growth-hacking`** generates complete conversion systems: Bottom Sheet + Calendar CTA + Tracking. Auto-detects industry, selects the right pattern, wires up `**cm-booking-calendar`** for appointments and `**cm-ads-tracker**` for pixel tracking. Zero dependencies.
 
 ---
 
 ## 🆚 Scattered Skills vs CodyMaster
 
-|                            | 😵 15 Random Skills                         | 🧠 CodyMaster                                                         |
-| -------------------------- | ------------------------------------------- | --------------------------------------------------------------------- |
-| **Integration**      | Each skill is standalone, no shared context | 68+ skills that chain, share memory, and communicate                   |
-| **Lifecycle**        | Covers coding only                          | Covers Idea → Design → Code → Test → Deploy → Docs → Learn      |
-| **Memory**           | Forgets everything between sessions         | 5-tier Unified Brain: Sensory → Working → Long-term → Semantic → Structural + Cloud Brain. Optional **OpenViking** backend for vector search + auto memory compression. |
-| **Safety**           | YOLO deploys                                | 4-layer protection: TDD → Security → Isolation → Multi-gate deploy |
-| **Design**           | Random UI every time                        | Extracts & enforces design system + visual preview                    |
-| **Documentation**    | "Maybe write a README later"                | Auto-generates complete docs, SOPs, API refs from code                |
-| **Self-improvement** | Static — what you install is what you get  | Self-healing: monitors health → auto-patches → reinforces winners   |
-| **Maintenance**      | Update 15 repos separately                  | One `npm i -g codymaster` updates everything                        |
+
+|                      | 😵 15 Random Skills                         | 🧠 CodyMaster                                                                                                                                                           |
+| -------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Integration**      | Each skill is standalone, no shared context | 68+ skills that chain, share memory, and communicate                                                                                                                    |
+| **Lifecycle**        | Covers coding only                          | Covers Idea → Design → Code → Test → Deploy → Docs → Learn                                                                                                              |
+| **Memory**           | Forgets everything between sessions         | 5-tier Unified Brain: Sensory → Working → Long-term → Semantic → Structural + Cloud Brain, powered by SQLite + FTS5 by default with optional local semantic layers like `qmd`. |
+| **Safety**           | YOLO deploys                                | 4-layer protection: TDD → Security → Isolation → Multi-gate deploy                                                                                                      |
+| **Design**           | Random UI every time                        | Extracts & enforces design system + visual preview                                                                                                                      |
+| **Documentation**    | "Maybe write a README later"                | Auto-generates complete docs, SOPs, API refs from code                                                                                                                  |
+| **Self-improvement** | Static — what you install is what you get   | Advisory-driven self-healing: inspect telemetry → diagnose → repair with FIX / DERIVED / CAPTURED                                                                     |
+| **Maintenance**      | Update 15 repos separately                  | One `npm i -g codymaster` updates everything                                                                                                                            |
+
 
 ---
 
@@ -242,47 +245,56 @@ If you prefer:
 
 ## 🚀 1-Minute Install
 
-### 1. Install AI Skills (All Platforms)
+### ✨ NEW: Claude Desktop Plugin (Zero Terminal Required)
+
+The easiest way to install CodyMaster — no npm, no terminal, no setup.
 
-One command installs all 68+ skills to your environment. Supports Claude Code, Gemini CLI, Cursor, Aider, Windsurf, Cline, OpenCode, and more:
+**Claude Desktop / Claude Cowork:**
+
+Run the auto-installer to inject the MCP Servers into your Claude Desktop config automatically:
 
 ```bash
-bash <(curl -fsSL https://raw.githubusercontent.com/tody-agent/codymaster/main/install.sh) --all
+npx codymaster mcp-serve --install-claude
 ```
 
-#### After `install.sh --all` (verify)
-
-- **Restart** Claude Code, Cursor, or Gemini / Antigravity so they reload config and rules from disk.
-- **Cursor:** rules go to **`~/.cursor/rules`** (always under your home folder, not wherever you ran the script). In Agent chat, run **`/add-plugin cody-master`**. To install rules **only inside one git repo**, run from that repo: `bash install.sh --cursor --cursor-project`.
-- **Gemini / Antigravity:** skills live in `~/.gemini/antigravity/skills`. The installer **creates or appends** `~/.gemini/GEMINI.md` with `@~/.gemini/antigravity/skills/cm-skill-index/SKILL.md` when that hint is missing.
-- **Claude Code:** if commands like `/cm:demo` do not appear, run `claude plugin marketplace add tody-agent/codymaster` then `claude plugin install cm@codymaster --scope user` (or `--scope project`).
-- **Non-interactive:** `--all` skips the onboarding menu. For a single platform, add **`--yes`** (e.g. `bash install.sh --gemini --yes`).
+All 68+ skills will be wired up instantly via MCP stdio. Remember to restart Claude Desktop to load the new config.
 
-#### Google Antigravity / Gemini CLI / Windsurf (token budget)
+---
 
-Antigravity and some Windsurf builds count **skills + MCP** against a customization token budget. Installing every skill globally can trigger truncation or unstable agent runs (especially if an MCP server errors and retries).
+### 2. Install AI Skills (All Other Platforms)
 
-- **Recommended:** install a **small global profile**, add the rest per project.
+CodyMaster uses **Native Plugin Extensions** for zero-friction installation. No bash scripts, no manual folder copying. Select your platform below:
 
+**Claude Code CLI:**
 ```bash
-# Core only → ~/.gemini/antigravity/skills (merge more profiles later with the same command)
-bash <(curl -fsSL https://raw.githubusercontent.com/tody-agent/codymaster/main/install.sh) --gemini --profile core
+claude plugin marketplace add tody-agent/codymaster
+claude plugin install cm@codymaster --scope user
+```
 
-# Optional packs (re-run to add folders alongside core)
-bash install.sh --gemini --profile growth
-bash install.sh --gemini --profile design
-bash install.sh --gemini --profile knowledge
+**Cursor (in Agent Chat):**
+```text
+/add-plugin cody-master
 ```
 
-- **Paths:** Antigravity / Gemini CLI skills → `~/.gemini/antigravity/skills`. This repo’s installer for **Windsurf** writes to **project** `.windsurf/rules` when you run `install.sh --windsurf` from a repo root. Some Windsurf/Codeium setups also use a **global** skills directory (e.g. under Codeium); if you copy skills there manually, use the same `--profile` flags to avoid duplicating hundreds of rules.
-- **MCP:** Disable MCP servers you are not using in the IDE settings. Flaky or rate-limited MCPs can cause “MCP Error” loops until the agent terminates.
-- **Progressive disclosure:** Add `@~/.gemini/antigravity/skills/cm-skill-index/SKILL.md` to `GEMINI.md` so the model loads the index before pulling full skills.
+**Gemini CLI / Google Antigravity:**
+```bash
+gemini extensions install https://github.com/tody-agent/codymaster
+```
+*(Progressive disclosure: Add `@~/.gemini/antigravity/skills/cm-skill-index/SKILL.md` to your `GEMINI.md` to save tokens)*
 
-Profiles are defined under [`skills/profiles/`](skills/profiles/README.md).
+**OpenCode / OpenClaw:**
+Tell your agent:
+```text
+Fetch and follow instructions from https://raw.githubusercontent.com/tody-agent/codymaster/main/.opencode/INSTALL.md
+```
 
-*For Cursor IDE users, you can also just type `/add-plugin cody-master` in your agent chat.*
+**Codex:**
+Tell your agent:
+```text
+Fetch and follow instructions from https://raw.githubusercontent.com/tody-agent/codymaster/main/.codex/INSTALL.md
+```
 
-### 2. Install Mission Control Dashboard (Optional but Recommended)
+### 3. Install Mission Control Dashboard (Optional but Recommended)
 
 Visualize your progress, manage tasks, and track your 10x coding streak with Cody the Hamster 🐹.
 
@@ -319,22 +331,63 @@ The CLI will greet you and keep you organized on your long coding sessions!
 │  ○ 🧩  Browse Skills
 ```
 
-</details>
+---
+
+## Use with Goose
+
+CodyMaster works as a [Goose](https://block.github.io/goose/) MCP extension, giving Goose persistent memory, skill orchestration, and token management.
+
+**3-step setup:**
+
+```bash
+# 1. Install CodyMaster
+npm install -g codymaster
+
+# 2. Get your Goose config snippet
+cm mcp-serve --print-config
+
+# 3. Paste the output into your Goose config (~/.config/goose/config.yaml)
+```
+
+See [full Goose integration guide](docs/integrations/goose.md) for details.
 
 ---
 
-## 🧰 The 68+ Skill Arsenal
+## 🎯 Real-World Use Cases
 
-| Domain                    | Skills                                                                                                                                                          |
-| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🔧 **Engineering**   | `cm-tdd` `cm-debugging` `cm-quality-gate` `cm-test-gate` `cm-code-review` `cm-clean-code`                                                                             |
-| ⚙️ **Operations**  | `cm-safe-deploy` `cm-identity-guard` `cm-secret-shield` `cm-security-gate` `cm-git-worktrees` `cm-terminal` `cm-safe-i18n`                                             |
+> **Tip:** Start any session with `/cm:start <your goal>` and CodyMaster will pick the right skills automatically.
+
+
+| Scenario                                   | Skills Used                                                                      | What You Say                         |
+| ------------------------------------------ | -------------------------------------------------------------------------------- | ------------------------------------ |
+| 🐛 **Fix a bug without breaking anything** | `cm-debugging` → `cm-tdd` → `cm-quality-gate`                                    | *"Debug this crash"*                 |
+| 🚀 **Ship a feature safely**               | `cm-planning` → `cm-tdd` → `cm-code-review` → `cm-safe-deploy`                   | *"Build the login flow"*             |
+| 🎨 **Build a new UI from scratch**         | `cm-ux-master` → `cm-design-system` → `cm-ui-preview`                            | *"Design the dashboard page"*        |
+| 🔒 **Deploy to production**                | `cm-secret-shield` → `cm-security-gate` → `cm-identity-guard` → `cm-safe-deploy` | *"Deploy to prod"*                   |
+| 📝 **Understand a legacy codebase**        | `cm-codeintell` → `cm-dockit`                                                    | *"What does this code do?"*          |
+| 📈 **Launch a landing page**               | `cm-brainstorm-idea` → `cm-cro-methodology` → `cm-content-factory`               | *"Build a landing page for my SaaS"* |
+| 🌍 **Add multi-language support**          | `cm-safe-i18n`                                                                   | *"Add Vietnamese and Japanese"*      |
+| 🔄 **Start a new project**                 | `cm-project-bootstrap` → `cm-planning`                                           | *"Bootstrap a Next.js SaaS"*         |
+| 🧠 **Resume after a break**                | `cm-continuity` → `cm-status`                                                    | *"What was I working on?"*           |
+| 🏭 **Scale SEO content**                   | `cm-content-factory` → `cm-auto-publisher` → `cm-ads-tracker`                    | *"Create 20 articles for my blog"*   |
+
+
+---
+
+## 🧰 The 60+ Skill Arsenal
+
+
+| Domain               | Skills                                                                                                                                        |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔧 **Engineering**   | `cm-tdd` `cm-debugging` `cm-quality-gate` `cm-test-gate` `cm-code-review` `cm-clean-code`                                                     |
+| ⚙️ **Operations**    | `cm-safe-deploy` `cm-identity-guard` `cm-secret-shield` `cm-security-gate` `cm-git-worktrees` `cm-terminal` `cm-safe-i18n`                    |
 | 🎨 **Product & UX**  | `cm-planning` `cm-design-system` `cm-ux-master` `cm-ui-preview` `cm-project-bootstrap` `cm-jtbd` `cm-brainstorm-idea` `cm-dockit` `cm-readit` |
-| 📈 **Growth & CRO**    | `cm-content-factory` `cm-auto-publisher` `cm-ads-tracker` `cm-cro-methodology` `cm-growth-hacking` `cm-booking-calendar` `cm-google-form`                                                                                                   |
-| 🏢 **Enterprise**  | `cm-reactor` `cm-notebooklm`                                                                                                  |
-| 🧬 **Self-Healing**   | `cm-skill-health` `cm-skill-evolution` `cm-skill-search` `cm-skill-share` `cm-skill-chain` `cm-skill-mastery` `cm-skill-index`             |
-| 🎯 **Orchestration** | `cm-execution` `cm-continuity` `cm-deep-search` `cm-codeintell` `cm-how-it-work`             |
-| 🖥️ **Workflow**    | `cm-start` `cm-dashboard` `cm-status`                                                                                                                     |
+| 📈 **Growth & CRO**  | `cm-content-factory` `cm-auto-publisher` `cm-ads-tracker` `cm-cro-methodology` `cm-growth-hacking` `cm-booking-calendar` `cm-google-form`     |
+| 🏢 **Enterprise**    | `cm-reactor` `cm-notebooklm`                                                                                                                  |
+| 🧬 **Self-Healing**  | `cm-skill-health` `cm-skill-evolution` `cm-skill-search` `cm-skill-share` `cm-skill-chain` `cm-skill-mastery` `cm-skill-index`                |
+| 🎯 **Orchestration** | `cm-execution` `cm-continuity` `cm-deep-search` `cm-codeintell` `cm-how-it-work`                                                              |
+| 🖥️ **Workflow**     | `cm-start` `cm-dashboard` `cm-status`                                                                                                         |
+
 
 ---
 
@@ -356,6 +409,7 @@ cm config [key] [value]   → Config helper
 cm open                     → Open dashboard in browser
 cm browse …                 → Local Playwright browse daemon (QA)
 cm guardian …               → Destructive-command / path checks
+cm index skills             → Zero-Token tech stack and skill local indexer
 cm sprint …                 → Sprint pipeline + .cm/sprint
 cm design-studio [init|status]
 cm distro validate …        → Validate skill pack layout
@@ -363,13 +417,9 @@ cm distro validate …        → Validate skill pack layout
 
 **Memory, bus, budgets, `cm://` resolution:** use the **MCP context server** — see [docs/api/api-reference.md](docs/api/api-reference.md).
 
-**Engineering (browse, guardian, sprint):** [docs/workflows/engineering-pipeline.md](docs/workflows/engineering-pipeline.md) · [docs/architecture/servers-and-mcp.md](docs/architecture/servers-and-mcp.md)
+**Engineering (browse, guardian, sprint):** [docs/workflows/engineering-pipeline.md](docs/workflows/engineering-pipeline.md) · [docs/browse-daemon.md](docs/browse-daemon.md) · [docs/workflows/guardian-hooks.md](docs/workflows/guardian-hooks.md) · [docs/architecture/servers-and-mcp.md](docs/architecture/servers-and-mcp.md)
 
-```bash
-# OpenViking backend (optional — semantic vector search)
-pip install openviking && openviking start
-# Then set storage.backend: viking in .cm/config.yaml
-```
+Legacy configs that still say `storage.backend: viking` are automatically routed back to SQLite.
 
 **Slash Commands (inside AI agents):**
 
@@ -398,7 +448,7 @@ pip install openviking && openviking start
 - 🌍 [Website](https://cody.todyle.com) — Overview & demos
 - 📖 [Documentation (site)](https://cody.todyle.com/docs) — Hosted deep-dive
 - 📘 [Documentation (repo)](docs/index.md) — Markdown source; run `npm run docs:dev` for VitePress
-- 🛠️ [Skills Reference](skills/) — Browse **56** bundled `cm-*` SKILL.md packs (profiles/installer can add more)
+- 🛠️ [Skills Reference](skills/) — Browse **56** bundled `cm-`* SKILL.md packs (profiles/installer can add more)
 - 📖 [Our Story](https://cody.todyle.com/story) — Why this exists
 
 ---
@@ -413,11 +463,8 @@ CI runs `npm ci` and `npm run test:gate:kit` on pushes and pull requests (see `.
 
 ---
 
-<div align="center">
+*ISC License — Free to use, modify, and distribute.*   
 
-*ISC License — Free to use, modify, and distribute.* <br/>
 **Built with ❤️ for the vibe coding community.**
 
 *"CodyMaster" = "Code Đi" (Vietnamese: "Go code!") — just start building.*
-
-</div>

package/dist/advisory-handoff.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAdvisoryHandoff = buildAdvisoryHandoff;
+exports.formatAdvisoryHandoffMarkdown = formatAdvisoryHandoffMarkdown;
+const execution_analyzer_1 = require("./execution-analyzer");
+function resolveAnalysis(backend, options) {
+    var _a;
+    const analyses = backend.getExecutionAnalyses((_a = options.searchLimit) !== null && _a !== void 0 ? _a : 50);
+    if (analyses.length === 0) {
+        throw new Error('No execution analyses recorded yet.');
+    }
+    if (!options.analysisId)
+        return analyses[0];
+    const match = analyses.find((analysis) => analysis.id.startsWith(options.analysisId));
+    if (!match) {
+        throw new Error(`No advisory analysis found for id prefix: ${options.analysisId}`);
+    }
+    return match;
+}
+function resolveSkillName(analysis, explicitSkill) {
+    var _a;
+    if (explicitSkill)
+        return explicitSkill;
+    return (_a = analysis.skill_judgments.find((judgment) => judgment.selected || judgment.applied)) === null || _a === void 0 ? void 0 : _a.skill;
+}
+function buildNextStep(consumer, action, skill) {
+    const subject = skill !== null && skill !== void 0 ? skill : 'the affected skill';
+    if (consumer === 'cm-skill-health') {
+        return `Run cm-skill-health on ${subject} and confirm whether ${action} is still the truthful recovery path.`;
+    }
+    return `Run cm-skill-evolution in ${action} mode for ${subject} using this advisory evidence as the starting note.`;
+}
+function buildAdvisoryHandoff(backend, options) {
+    var _a, _b;
+    const analysis = resolveAnalysis(backend, options);
+    const skillName = resolveSkillName(analysis, options.skill);
+    const judgment = skillName
+        ? analysis.skill_judgments.find((item) => item.skill === skillName)
+        : undefined;
+    const metric = skillName ? backend.getSkillMetric(skillName) : null;
+    const action = (_a = analysis.recommended_action) !== null && _a !== void 0 ? _a : 'NONE';
+    return {
+        version: 1,
+        generated_at: new Date().toISOString(),
+        consumer: options.consumer,
+        recommendation: {
+            action,
+            confidence: analysis.confidence,
+        },
+        source: {
+            analysis_id: analysis.id,
+            task_title: analysis.task_title,
+            task_status: analysis.status,
+            source_task_type: analysis.source_task_type,
+            created_at: analysis.created_at,
+        },
+        skill: {
+            name: skillName,
+            judgment,
+            metric: metric ? Object.assign(Object.assign({}, metric), { quality_weight: (0, execution_analyzer_1.qualityWeight)(metric) }) : null,
+        },
+        evidence: {
+            summary: analysis.summary,
+            selected_skills: (_b = analysis.selected_skills) !== null && _b !== void 0 ? _b : [],
+            target_skills: analysis.skill_judgments
+                .filter((item) => item.selected || item.applied)
+                .map((item) => item.skill),
+        },
+        next_step: buildNextStep(options.consumer, action, skillName),
+    };
+}
+function formatAdvisoryHandoffMarkdown(handoff) {
+    var _a, _b, _c;
+    return [
+        '## Advisory Handoff',
+        `- Consumer: ${handoff.consumer}`,
+        `- Skill: ${(_a = handoff.skill.name) !== null && _a !== void 0 ? _a : '-'}`,
+        `- Recovery path: ${handoff.recommendation.action}`,
+        `- Confidence: ${(_c = (_b = handoff.recommendation.confidence) === null || _b === void 0 ? void 0 : _b.toFixed(2)) !== null && _c !== void 0 ? _c : '-'}`,
+        `- Source analysis: ${handoff.source.analysis_id}`,
+        `- Task: ${handoff.source.task_title}`,
+        `- Status: ${handoff.source.task_status}`,
+        `- Evidence: ${handoff.evidence.summary}`,
+        `- Selected skills: ${handoff.evidence.selected_skills.join(', ') || '-'}`,
+        `- Target skills: ${handoff.evidence.target_skills.join(', ') || '-'}`,
+        `- Quality weight: ${handoff.skill.metric ? handoff.skill.metric.quality_weight.toFixed(2) : '-'}`,
+        `- Next step: ${handoff.next_step}`,
+    ].join('\n');
+}