oh-my-claudecode 0.2.8 → 0.2.9

package/README.md

@@ -10,7 +10,7 @@
 >
 > **The agentic operations system for [Claude Code](https://claude.ai/code).**
 
-oh-my-claudecode (OMC) turns a raw Claude Code session into a fully-orchestrated agentic environment. Instead of typing to a single model that loses its mind between sessions, you talk to **Cthulhu** — a primary orchestrator that plans, delegates to ten specialized Elder God subagents, remembers what it learned last time via a persistent archive, and trims its own context between delegations so long sessions stay sharp. It is opinionated, integrated, and end-to-end: one install, one command, every piece wired into every other piece.
+oh-my-claudecode (OMC) turns a raw Claude Code session into a fully-orchestrated agentic environment. Instead of typing to a single model that loses its mind between sessions, you talk to **Cthulhu** — a primary orchestrator that plans, delegates to eleven specialized Elder God subagents, remembers what it learned last time via a persistent archive, and trims its own context between delegations so long sessions stay sharp. The specialists are real Claude Code subagents — the installer renders them into `~/.claude/agents/`, so `Agent(subagent_type: "shoggoth")` resolves natively. It is opinionated, integrated, and end-to-end: one install, one command, every piece wired into every other piece.
 
 ---
 
@@ -34,7 +34,7 @@ OMC's three pillars address each problem directly.
  │  │  ORCHESTRATION │  │      MEMORY     │  │    CONTEXT    │   │
  │  │                │  │                 │  │  DISCIPLINE   │   │
  │  │   Cthulhu +    │  │  Yith Archive   │  │     Block     │   │
- │  │  10 Elder God  │  │   cross-session │  │   Summarizer  │   │
+ │  │  11 Elder God  │  │   cross-session │  │   Summarizer  │   │
  │  │   specialists  │  │   persistent    │  │   in-session  │   │
  │  │  intent gate   │  │   retrieval     │  │   trimming    │   │
  │  │  delegation    │  │                 │  │               │   │
@@ -56,18 +56,18 @@ These aren't three plugins you pick and choose. They're one integrated system th
 
 | Capability | What it does |
 |---|---|
-| **11 Elder God agents** | Cthulhu orchestrator + 10 specialists (search, advisory, planning, review, docs, autonomy, vision, etc.) |
+| **12 Elder God agents** | Cthulhu orchestrator + 11 specialists (search, advisory, planning, review, docs, autonomy, vision, design). Installed as native Claude Code subagents in `~/.claude/agents/` by `oh-my-claudecode sync` — spawnable via the Agent tool, customizable via config. |
 | **Yith Archive** | Persistent cross-session memory with retrieval-based injection. Dozens of memory primitives: remember, search, consolidate, evict, crystallize, reflect, temporal graph, pattern extraction, and more. Exposed to Claude Code as a stdio MCP server with 7 tools. |
 | **Work-packet protocol** | LLM-requiring memory ops (consolidate, summarize, reflect, etc.) run in sessions with no API key — each function has a state-machine variant that emits prompts for the parent agent to execute with its own subscription auth. |
 | **Block Summarizer** | In-session delegation summarization with on-disk block archive |
-| **8 lifecycle hooks** | Auto-activation, memory redirect, continuous Yith capture, todo enforcement, completion loops, code-quality checks, rule injection, write guards |
+| **11 lifecycle hooks** | Auto-activation, agent sync, memory redirect, continuous Yith capture (session start + every turn), todo enforcement, completion loops, code-quality checks, rule injection, write guards, research/design routing |
 | **10 slash commands** | Direct-invoke any mode or flow from the Claude Code chat bar |
 | **Intent gate** | Every user message is classified and routed before Cthulhu acts |
 | **Work plan system** | Multi-step planning flow with interview → scope → plan → review before execution |
 | **3-level config** | Defaults → user (`~/.claude/oh-my-claudecode.jsonc`) → project (`.claude/...`) with Zod validation and partial parsing |
 | **Background agent manager** | Circuit breaker, concurrency limits, task lifecycle tracking |
 | **Project activation** | `.elder-gods/` marker directory opts a project into Cthulhu mode — unrelated repos stay default Claude Code |
-| **Installer + doctor** | Interactive wizard, health diagnostics, agent listing |
+| **Installer + doctor + dashboard** | OpenTUI install wizard, health diagnostics, and a full-screen stats/settings dashboard (`oh-my-claudecode dashboard`) |
 | **CI/CD** | GitHub Actions publishing pipeline with auto-bump, tag, release, and npm push |
 
 ## Installation
@@ -76,19 +76,26 @@ These aren't three plugins you pick and choose. They're one integrated system th
 npx oh-my-claudecode install
 ```
 
-The installer asks a few questions and then:
+When [Bun](https://bun.sh) is installed, the questions come as a full-screen
+OpenTUI wizard; otherwise plain prompts collect the same choices. The
+installer then:
 
 1. Drops hook scripts into `~/.claude/hooks/`
 2. Registers them in `~/.claude/settings.json`
-3. Registers the Yith Archive MCP server in `~/.claude.json` 
+3. Registers the Yith Archive MCP server in `~/.claude.json`
 4. Copies slash command definitions to `~/.claude/commands/`
 5. Creates `~/.claude/oh-my-claudecode.jsonc` with sensible defaults
-6. Leaves your existing Claude Code config intact (backup is made)
+6. Renders all 12 agent definitions into `~/.claude/agents/` (same as `oh-my-claudecode sync`)
+7. Downloads the local embedding model (~137 MB, progress bar) into `~/.oh-my-claudecode/models/` and verifies it with a probe embedding (opt-out `--no-model`)
+8. Installs a background ingestion cron (every 6h, opt-out) so the memory archive stays current even when Claude Code is closed
+9. Raises Claude Code's transcript retention (`cleanupPeriodDays: 365`, opt-out) so session history is never deleted before it's ingested
+10. Leaves your existing Claude Code config intact (backup is made)
 
 Non-interactive install (for CI or scripts):
 
 ```bash
-npx oh-my-claudecode install --no-tui
+npx oh-my-claudecode install --no-tui          # accept all defaults
+npx oh-my-claudecode install --no-cron --no-retention  # skip the durability extras
 ```
 
 ### Requirements
@@ -97,7 +104,13 @@ npx oh-my-claudecode install --no-tui
 - Node.js 20 or newer
 - `~/.claude/` directory writable
 - (Optional for Yith Archive summarization/consolidation) `ANTHROPIC_API_KEY` in `~/.oh-my-claudecode/yith/.env` or as an environment variable
-- (Optional for semantic memory retrieval) `@xenova/transformers` — install with `npm install @xenova/transformers` if you want embedding-backed search instead of BM25-only
+- (Optional for the `dashboard` TUI and the graphical install wizard) [Bun](https://bun.sh) — `npm install -g bun`. Everything else works without it.
+
+Semantic memory retrieval needs nothing extra: `@huggingface/transformers` ships
+as a bundled dependency and the local embedding model is downloaded during
+install. If `npm install` fails inside `sharp` on a machine with a system-wide
+libvips (some Arch/CachyOS setups), retry with
+`SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g oh-my-claudecode`.
 
 ## Quick tour — what a session looks like
 
@@ -117,19 +130,26 @@ On your next session in the same project, steps 4 and the initial memory injecti
 
 ## Agent Roster
 
-| Elder God | Model | Mode | Role |
-|-----------|-------|------|------|
-| **Cthulhu** | Opus | primary | Main orchestrator — intent gate, delegation, parallel execution, verification |
-| **Nyarlathotep** | Opus | subagent | Deep autonomous worker — end-to-end goal execution |
-| **Azathoth** | Opus | primary | First-message planner — initial context sweep and routing |
-| **Shub-Niggurath** | Opus | primary | Strategic planner — interview → scope → plan → Tsathoggua review |
-| **Yog-Sothoth** | Opus | subagent | Architecture/debug advisor — read-only, high-reasoning consultation |
-| **Hastur** | Sonnet | subagent | Lightweight sub-orchestrator for bounded tasks |
-| **Ithaqua** | Sonnet | subagent | Pre-planning consultant — intent classification, anti-slop guardrails |
-| **Tsathoggua** | Sonnet | subagent | Work plan reviewer — blocker-finder, not perfectionist |
-| **Dagon** | Sonnet | subagent | External documentation and GitHub source research |
-| **The Deep One** | Sonnet | subagent | Vision agent — images, screenshots, diagrams |
-| **Shoggoth** | Haiku | subagent | Fast parallel codebase search |
+Every agent below is installed as a real Claude Code subagent file in
+`~/.claude/agents/<name>.md` — spawn any of them with the Agent tool
+(`subagent_type: "<name>"`). `oh-my-claudecode sync` regenerates the files
+from your config; the `agent-sync` hook re-runs it automatically at session
+start so config edits land in the next session.
+
+| Elder God | Model tier | Role |
+|-----------|-----------|------|
+| **Cthulhu** | Opus | Main orchestrator — intent gate, delegation, parallel execution, verification |
+| **Nyarlathotep** | Opus | Deep autonomous worker — end-to-end goal execution |
+| **Azathoth** | Opus | First-message planner — initial context sweep and routing |
+| **Shub-Niggurath** | Opus | Strategic planner — interview → scope → plan → Tsathoggua review |
+| **Yog-Sothoth** | Opus | Architecture/debug advisor — read-only, high-reasoning consultation |
+| **Nodens** | Opus | Frontend design specialist — intent → spec → impl → polish, vision-capable |
+| **Hastur** | Sonnet | Lightweight sub-orchestrator for bounded tasks |
+| **Ithaqua** | Sonnet | Pre-planning consultant — intent classification, anti-slop guardrails |
+| **Tsathoggua** | Sonnet | Work plan reviewer — blocker-finder, not perfectionist |
+| **Dagon** | Sonnet | External documentation and GitHub source research |
+| **The Deep One** | Sonnet | Vision agent — images, screenshots, diagrams |
+| **Shoggoth** | Haiku | Fast parallel codebase search |
 
 ## Agent Behavior Enhancements (v0.2.6)
 
@@ -137,14 +157,17 @@ v0.2.6 introduces three orthogonal agent behavior improvements, all enabled by d
 
 ### Web Research Enforcement
 
-Agents automatically trigger web search when they encounter queries about:
+When a conversation involves date-sensitive knowledge, the `web-research-detector`
+PreToolUse hook detects it and injects a directive to spawn a **background Dagon
+research agent** (Agent tool, `subagent_type: "dagon"`, `run_in_background: true`)
+before answering — so current information lands in the context window instead of
+a stale training-data guess. Trigger patterns include:
+
 - **Version checks**: "v1.0", "Node 18", "2024", "latest"
 - **API updates and breaking changes**: "what changed", "deprecated", "breaking"
 - **Framework release schedules**: "Next.js 15 coming soon", "LTS version"
-- **Security vulnerabilities**: CVE references, vulnerability announcements
-- **Package management**: npm audit patterns, outdated dependencies
 
-Powered by the PreToolUse hook which detects these patterns and injects a Dagon background research agent prompt before the user's message reaches the main orchestrator. Results are available in the context window for the agent to reference.
+Active only in OMC-activated projects (`.elder-gods/` present).
 
 **Default**: Enabled
 
@@ -160,14 +183,19 @@ Powered by the PreToolUse hook which detects these patterns and injects a Dagon
 
 ### TypeScript Type Safety Linting
 
-Automatic validation enforces type safety across the codebase:
-- **Bans `any` types** — forces explicit typing or `unknown` with type guards
-- **Unsafe casts** — flags `as any` and `as unknown` patterns
-- **Missing return types** — detects functions without explicit return type annotations
-- **@ts-ignore without reason** — requires inline comments explaining suppression
-- **Auto-fix support** — safe violations can be fixed automatically via pre-commit hook
+`oh-my-claudecode lint` is an AST-based type-safety linter:
+- **Bans `any` types** — forces explicit typing or `unknown` with type guards (error)
+- **Unsafe casts** — flags `as any` and `as unknown` (error); structured narrowing casts are allowed
+- **Missing return types** — functions without explicit return type annotations (warn)
+- **@ts-ignore without reason** — requires inline comments explaining suppression (warn)
+- **Auto-fix support** — `lint --fix` repairs the mechanical violations (`: any` → `: unknown`, `as any` → `as unknown`, bare `@ts-ignore` → reasoned)
+- **Reasoned escape hatch** — a `@ts-safety: <reason>` comment on the violating line acknowledges an intentional exception
 
-The linter runs at pre-commit time and blocks unsafe code from entering the repository. Type safety metrics are exported for CI/CD dashboards to track compliance over time.
+Run it at pre-commit time to block unsafe code from entering the repository
+(`oh-my-claudecode lint --staged` exits 1 on errors — this repo's own
+`.husky/pre-commit` does exactly that), and export metrics for CI/CD
+dashboards with `lint --metrics <path>` (score percentage, issue counts by
+rule, trend-comparable JSON snapshots).
 
 **Default**: Enabled
 
@@ -183,14 +211,19 @@ The linter runs at pre-commit time and blocks unsafe code from entering the repo
 
 ### Nodens — Design Specialization Agent
 
-A dedicated design agent routes UI/component design tasks and provides:
-- **Accessibility automation**: WCAG compliance testing, keyboard navigation, screen reader support via Axe-core
-- **Responsive design**: Automatically generates component variants for multiple breakpoints
-- **Playwright test generation**: Creates visual regression and interaction tests
-- **Figma integration**: Extracts design tokens (colors, typography, spacing) from Figma files
-- **Vision capability**: Analyzes screenshots and design mockups with Claude Opus
+Nodens is a real Claude Code subagent (installed at `~/.claude/agents/nodens.md`,
+Opus tier) with a design-first system prompt covering:
+- **Accessibility**: WCAG compliance checks, keyboard navigation, screen-reader
+  support — run via Axe-core/tooling through its Bash access
+- **Responsive design**: component variants across breakpoints
+- **Playwright test generation**: visual regression and interaction tests
+- **Figma awareness**: design-token extraction (colors, typography, spacing)
+- **Vision capability**: analyzes screenshots and design mockups (Opus tier)
 
-When design-related queries are detected (via the design-detector hook), they are automatically routed to Nodens instead of the general orchestrator. Nodens has a design-first system prompt and specialized tools for component generation, accessibility testing, and design token management.
+When design-related queries are detected, the design-detector hook injects a
+routing directive telling the session to delegate the task to Nodens
+(`Agent` tool, `subagent_type: "nodens"`) instead of handling the design
+inline. Active only in OMC-activated projects.
 
 **Default**: Enabled
 
@@ -283,11 +316,34 @@ work-packet loop. Either:
 
 - Open Claude Code and run `/necronomicon-bind` — uses your
   subscription auth via the MCP work-packet protocol.
-- Or install a cron entry that spawns `claude -p` on an interval:
-  ```bash
-  oh-my-claudecode bind --install-cron --interval 1h
-  ```
-  The cron tick drives compression unattended. No API key needed.
+- Or rely on the ingestion cron (installed by default during
+  `oh-my-claudecode install`; reinstall or retune with
+  `oh-my-claudecode bind --install-cron --interval 6h`). The cron tick
+  ingests new transcripts and drives compression unattended via
+  `claude -p`. No API key needed.
+
+### Capture durability
+
+Three mechanisms guarantee session history reaches the archive before
+Claude Code's transcript cleanup can delete it:
+
+1. **Session hooks** — `yith-capture` ingests at session start, after
+   every assistant turn, immediately before context compaction, and when
+   a session ends (`/clear`, exit) — so neither forced compaction nor a
+   manual clear can lose anything: the full pre-compaction transcript is
+   already in the archive, and the post-compact/post-clear session can
+   recall it with `yith_search`. Compression drains when the queue passes
+   20 observations or any observation sits raw for 24 hours.
+2. **Background cron** — the default 6-hour `bind --resume` tick captures
+   even when Claude Code never opens.
+3. **Retention raise** — the installer sets `cleanupPeriodDays: 365` in
+   Claude Code's settings (with your consent) so the deletion window can
+   never outrun ingestion.
+
+Every successful transcript ingestion stamps a health beacon
+(`~/.oh-my-claudecode/yith/.last-bind-success`). `oh-my-claudecode doctor`
+and the Cthulhu session preflight warn when the beacon is stale, the CLI is
+missing, or the cron is gone — capture can't silently break.
 
 ### Work-packet protocol — LLM ops without an API key
 
@@ -336,7 +392,8 @@ Yith Archive reads its own variables from `~/.oh-my-claudecode/yith/.env` (or th
 | Variable | Purpose |
 |---|---|
 | `ANTHROPIC_API_KEY` | LLM calls for summarization, consolidation, reflection |
-| `EMBEDDING_PROVIDER` | `xenova` for local embeddings, unset for BM25-only |
+| `EMBEDDING_PROVIDER` | `local` (default — install pins it) or an explicit hosted opt-in: `gemini`/`openai`/`voyage`/`cohere`/`openrouter` with the matching API key. Ambient API keys in your shell are deliberately ignored — your session history never routes through a hosted API unless you ask. |
+| `YITH_MODEL_CACHE` | Where the local model lives (default `~/.oh-my-claudecode/models`) |
 | `AUTO_FORGET_ENABLED` | `false` to disable background eviction sweeps |
 | `CONSOLIDATION_ENABLED` | `false` to disable automatic memory consolidation |
 | `YITH_GRAPH_WEIGHT` | Weight of graph retrieval in hybrid search (default `0.3`) |
@@ -390,18 +447,21 @@ After installation these are available in Claude Code sessions:
 
 ## Lifecycle Hooks
 
-8 hooks are installed into Claude Code's `settings.json`. They provide the connective tissue between OMC's subsystems and the live session.
-
-| Hook | Event | Description |
-|------|-------|-------------|
-| `cthulhu-auto` | SessionStart | Auto-activate Cthulhu orchestrator mode when `.elder-gods/` is present in the project |
-| `memory-override` | SessionStart | Redirect persistent memory writes from Claude Code's built-in auto-memory to Yith Archive |
-| `yith-capture` | Stop | Continuous Yith ingestion — after every assistant turn, spawns a background `bind --resume --claude-only` to pull new transcript lines into the archive, and occasionally spawns `claude -p` to drain pending compression when the queue grows past threshold. Debounced; non-blocking; fail-safe. |
-| `todo-continuation` | Stop | Inject a reminder to continue if incomplete todos exist when stopping |
-| `elder-loop` | Stop | Self-referential completion loop — keeps running until the promise is met |
-| `comment-checker` | PostToolUse | Warn when AI-slop comments are introduced (comments that explain obvious code) |
-| `rules-injector` | PreToolUse | Auto-inject `.elder-gods/rules/*.md` into every agent's context |
-| `write-guard` | PreToolUse | Warn when `Write` is used on an existing file (suggest `Edit` instead) |
+11 hooks are installed into Claude Code's `settings.json`. They provide the connective tissue between OMC's subsystems and the live session. Hooks marked **scoped** only act in OMC-activated projects (`.elder-gods/` present) — unrelated repos keep stock Claude Code behavior. `yith-capture` and `agent-sync` are deliberately global: memory capture and agent freshness apply machine-wide.
+
+| Hook | Event | Scope | Description |
+|------|-------|-------|-------------|
+| `cthulhu-auto` | SessionStart | scoped | Auto-activate Cthulhu orchestrator mode; reports Necronomicon binding state and capture health |
+| `memory-override` | SessionStart | scoped | Redirect persistent memory writes from Claude Code's built-in auto-memory to Yith Archive |
+| `agent-sync` | SessionStart | global | Re-render `~/.claude/agents/` (and project-level overrides) in the background so config edits land in the next session |
+| `yith-capture` | SessionStart + Stop + PreCompact + SessionEnd | global | Continuous Yith ingestion — at session start, after every assistant turn, immediately before context compaction, and when the session ends (`/clear`, exit), spawns a background `bind --resume --claude-only` to pull new transcript lines into the archive, and spawns `claude -p` to drain pending compression when the queue passes 20 observations or sits raw for 24h. PreCompact/SessionEnd bypass the debounce. Non-blocking; fail-safe. |
+| `todo-continuation` | Stop | global | Inject a reminder to continue if incomplete todos exist when stopping |
+| `elder-loop` | Stop | self-gating | Self-referential completion loop — acts only while a loop you started via `/elder-loop` is active |
+| `comment-checker` | PostToolUse | scoped | Warn when AI-slop comments are introduced (comments that explain obvious code) |
+| `rules-injector` | PreToolUse | scoped | Auto-inject `.elder-gods/rules/*.md` into every agent's context |
+| `write-guard` | PreToolUse | scoped | Warn when `Write` is used on an existing file (suggest `Edit` instead) |
+| `web-research-detector` | PreToolUse | scoped | Detect date-sensitive queries and direct a background Dagon research spawn |
+| `design-detector` | PreToolUse | scoped | Detect design/frontend tasks and direct routing to Nodens |
 
 Disable specific hooks via config:
 
@@ -429,6 +489,14 @@ Turn auto-activation off globally with:
 
 Config file: `~/.claude/oh-my-claudecode.jsonc` (user-level) and/or `.claude/oh-my-claudecode.jsonc` (project-level). Project config overrides user config for scalar and object fields. Array fields like `disabled_*` are unioned across levels.
 
+Agent settings are applied by `oh-my-claudecode sync` (run automatically at
+install and by the `agent-sync` hook at session start): user-level config
+renders into `~/.claude/agents/`, and project-level agent overrides render
+into the project's `.claude/agents/`, where they shadow the user-level agent
+of the same name. One limitation: an agent can be disabled machine-wide
+(`disabled_agents` at user level) but not per-project — Claude Code's project
+agents shadow, they don't remove.
+
 ```jsonc
 {
   // Override models for specific agents
@@ -464,13 +532,14 @@ Config file: `~/.claude/oh-my-claudecode.jsonc` (user-level) and/or `.claude/oh-
 
 ### Available models
 
-Only Claude models are supported:
+Only Claude models are supported. Agent definitions use the tier aliases
+`opus` / `sonnet` / `haiku` — Claude Code resolves each alias to the current
+model of that tier at runtime, so installed agents never go stale when a new
+model ships. To pin an exact snapshot, set a full `claude-*` model ID in the
+agent's `model` field instead; it passes through verbatim.
 
-| Short Alias | Full Model ID |
-|-------------|--------------|
-| `opus` | `claude-opus-4-6` |
-| `sonnet` | `claude-sonnet-4-6` |
-| `haiku` | `claude-haiku-4-5` |
+After editing config, run `oh-my-claudecode sync` (or just start a new
+session — the `agent-sync` hook re-renders automatically).
 
 ## Project-Level Setup
 
@@ -511,6 +580,34 @@ Use `/invoke-shub` to start the planning flow:
 
 Use `/old-ones-init` to generate `AGENTS.md` files at the root and in key subdirectories. These give every agent project context at a glance, without repeated exploration and without consuming tool-budget on re-discovery.
 
+## Dashboard
+
+```bash
+oh-my-claudecode dashboard
+```
+
+A full-screen control panel rendered with [OpenTUI](https://opentui.com) (the
+terminal UI engine behind opencode) — gruvbox dark soft, a colorized ASCII
+wordmark splash, and a calm editorial layout: health is a one-line verdict,
+detail is opt-in. Four tabs:
+
+- **Overview** — archive counts (memories, observations, sessions, pending
+  compression), embedding provider and model-cache size, capture health with
+  last-ingest age, disk usage, and binding-ritual phase states
+- **Doctor** — the verdict plus only the checks that need attention
+  (`a` reveals the full suite)
+- **Agents** — the Elder God roster with model tier, category, cost, and
+  install state
+- **Settings** — toggle the three pillars, individual hooks, and individual
+  agents with the keyboard; changes write `~/.claude/oh-my-claudecode.jsonc`
+  and re-sync agents automatically
+
+Keys: `←→`/`1-4` tabs · `↑↓` select · `enter` toggle · `a` all checks ·
+`r` refresh · `q` quit.
+Requires Bun (`npm install -g bun`) for OpenTUI's native renderer — the
+command tells you exactly that if Bun is missing. `oh-my-claudecode stats
+[--json]` prints the same data headlessly.
+
 ## Diagnostics
 
 ```bash
@@ -523,17 +620,23 @@ Checks:
 - `settings.json` present
 - All hook scripts installed
 - Hooks registered in settings
+- Agent definitions installed and in sync with config
 - Slash commands installed
 - Plugin config valid
+- Yith archive boots; MCP server registered in `~/.claude.json`
+- Background ingestion cron installed
+- Capture health — when transcript ingestion last succeeded
+- Transcript retention window (`cleanupPeriodDays`) high enough that history can't be deleted before ingestion
 
 ## Project Structure
 
 ```
 oh-my-claudecode/
 ├── src/
-│   ├── agents/               # 11 Elder God agent definitions + builder
+│   ├── agents/               # 12 Elder God agent definitions + builder + markdown renderer
 │   ├── config/               # Zod schema — full type system
 │   ├── hooks/                # Lifecycle hook scripts and configs
+│   ├── linters/              # AST type-safety linter (lint CLI engine)
 │   ├── features/
 │   │   ├── yith-archive/     # Persistent cross-session memory (~14k LOC)
 │   │   │   ├── functions/    #   40+ memory primitives
@@ -547,9 +650,8 @@ oh-my-claudecode/
 │   │   ├── background-agent/ # BackgroundManager (circuit breaker, concurrency)
 │   │   ├── skill-loader/     # Discovers user skills from .claude/skills/
 │   │   └── mcp-manager/      # Skill-scoped MCP lifecycle
-│   ├── plugin-handlers/      # 5-phase config pipeline
 │   ├── shared/               # Logging, deep-merge, model resolution
-│   └── cli/                  # Installer, doctor, list-agents
+│   └── cli/                  # Installer, sync, doctor, lint, bind, list-agents
 ├── commands/                 # Markdown slash commands (installed to ~/.claude/commands/)
 ├── CHANGELOG.md              # Release history
 ├── LICENSE                   # MIT

package/commands/cthulhu.md

@@ -42,6 +42,9 @@ Use the Agent tool with these subagent_type values:
 | Nyarlathotep | "nyarlathotep" | End-to-end autonomous execution |
 | Shub-Niggurath | "shub-niggurath" | Strategic planning (interview → plan → tsathoggua review) |
 | The Deep One | "the-deep-one" | Image/screenshot/diagram analysis |
+| Nodens | "nodens" | Frontend/UI design and component work |
+
+If a spawn fails with "Agent type not found", the agent definitions are missing — tell the user to run `oh-my-claudecode sync` and continue inline for now.
 
 ## Operating Mode
 
@@ -52,7 +55,12 @@ For the current request from the user:
 3. **Act accordingly**:
    - Trivial → direct tools
    - Exploratory → parallel Shoggoth agents (run_in_background=true)
-   - Implementation → plan → delegate or execute
+   - Implementation, small (single file, obvious change) → todos, then execute directly
+   - Implementation, substantial (2+ files, new feature, refactor, unclear scope) → the
+     pipeline is MANDATORY: spawn "shub-niggurath" to write a plan into `.elder-gods/plans/`,
+     spawn "tsathoggua" to review it, fix any blockers, then execute the approved plan,
+     delegating to specialists per its steps
+   - Design/UI work → delegate to "nodens"
    - Ambiguous → one clarifying question
 
 Begin now.

package/commands/invoke-shub.md

@@ -20,7 +20,8 @@ First, create the `.elder-gods/plans/` directory if it doesn't exist.
 Then, survey the codebase:
 - Read AGENTS.md or CLAUDE.md if present
 - Identify the area of the codebase relevant to the user's request
-- Find existing patterns to follow
+- Find existing patterns to follow (spawn parallel `subagent_type: "shoggoth"` agents
+  via the Agent tool when the area is unfamiliar)
 
 Then ask the user:
 1. What is the exact goal? (one sentence)
@@ -29,4 +30,9 @@ Then ask the user:
 4. How do we verify it's done? (specific test/command)
 5. Any other constraints?
 
-After receiving answers, create the work plan and proceed with Tsathoggua review.
+After receiving answers, write the work plan to `.elder-gods/plans/[task-name].md`,
+then spawn a real reviewer: Agent tool, `subagent_type: "tsathoggua"`, with the plan
+path and a pointer to the surveyed files. Tsathoggua returns OKAY or REJECT with at
+most 3 blocking issues — fix blockers and re-review until OKAY, then hand off to
+Cthulhu for execution. If a spawn fails with "Agent type not found", tell the user
+to run `oh-my-claudecode sync` and perform that role inline as a fallback.

package/commands/shoggoth.md

@@ -3,32 +3,22 @@ name: shoggoth
 description: Invoke Shoggoth — formless codebase search entity. Fast parallel pattern matching. Find files, code, implementations. Fire multiple in parallel.
 ---
 
-You are Shoggoth — a formless pattern-matcher flowing through the codebase.
+Run the user's search through real Shoggoth subagents.
 
-**Mission**: Find files and code. Return actionable results.
+**Search brief**: $ARGUMENTS
 
-**Immediate action**: Launch 3+ parallel searches for the user's request.
+**How**:
 
-**Required output format**:
+1. Break the brief into distinct search angles (by keyword, by file pattern, by
+   module, by usage site). One angle = one agent.
+2. Spawn the agents **in parallel** with the Agent tool, `subagent_type: "shoggoth"`,
+   one per angle — 3+ agents when the scope is broad, 1 when the brief is a single
+   precise lookup. Each prompt should state the angle, the success criteria, and
+   that absolute paths are required.
+3. If a spawn fails with "Agent type not found", tell the user to run
+   `oh-my-claudecode sync`, then perform the search inline as a fallback.
+4. Merge the `<results>` blocks: dedupe files, resolve conflicts, and answer the
+   user's actual need — files with one-line relevance notes, a direct answer, and
+   next steps.
 
-<results>
-<files>
-- /absolute/path/to/file.ts — [why relevant]
-</files>
-
-<answer>
-[Direct answer to actual need]
-</answer>
-
-<next_steps>
-[What to do with this information]
-</next_steps>
-</results>
-
-**Rules**:
-- ALL paths absolute (start with /)
-- Read-only — never write or edit files
-- No preamble, start searching immediately
-- Flood with parallel tool calls
-
-Begin searching now.
+Do not paste raw agent output back to the user — synthesize.

package/commands/yog-sothoth.md

@@ -3,28 +3,21 @@ name: yog-sothoth
 description: Invoke Yog-Sothoth — the Key and Gate, all-knowing architecture advisor. High-IQ reasoning for hard debugging and architecture decisions. Consult after 2+ failed fixes or for complex tradeoffs.
 ---
 
-You are Yog-Sothoth — the Key and Gate. All knowledge flows through you.
-
-**Your mode**: Strategic technical advisor with deep reasoning. Read-only consultation.
-
-**When consulted, always provide**:
-
-1. **Bottom line** (2-3 sentences, no preamble)
-2. **Action plan** (≤7 numbered steps, each ≤2 sentences)
-3. **Effort estimate** (Quick/Short/Medium/Large)
-
-**Decision framework**:
-- Bias toward simplicity — resist hypothetical future needs
-- Leverage what exists — no new dependencies unless justified
-- One clear path — single primary recommendation
-- Signal the investment — tag with effort estimate
-
-**What NOT to do**:
-- No preamble or filler
-- No unsolicited improvements
-- No design opinions beyond scope
-- No "always" or "never" without justification
-
-**Uncertainty**: If ambiguous, state interpretation explicitly: "Interpreting this as X..."
-
-Begin your consultation now.
+Consult Yog-Sothoth — the Key and Gate — on the user's question.
+
+**Question**: $ARGUMENTS
+
+**How**:
+
+1. Gather the minimal context the advisor needs: the question itself, the
+   relevant file paths, error output, and what has already been tried. Do not
+   dump whole files — paths and symptoms suffice; the advisor reads what it needs.
+2. Spawn ONE agent via the Agent tool with `subagent_type: "yog-sothoth"`,
+   passing that context. The agent is read-only and returns:
+   - **Bottom line** (2-3 sentences)
+   - **Action plan** (≤7 numbered steps)
+   - **Effort estimate** (Quick/Short/Medium/Large)
+3. If the spawn fails with "Agent type not found", tell the user to run
+   `oh-my-claudecode sync`, then answer in the same format inline as a fallback.
+4. Relay the consultation verbatim (it is already terse), then ask whether to
+   execute the action plan.

package/dist/agents/render.d.ts

@@ -0,0 +1,11 @@
+import type { AgentConfig } from "./types.js";
+/** Marker embedded in every generated file so sync can tell its own files from user-authored agents. */
+export declare const GENERATED_MARKER = "generated-by: oh-my-claudecode";
+/**
+ * Convert an AgentConfig tools map into the frontmatter allow-list string.
+ * Returns null when the agent should inherit all tools (no real denials).
+ */
+export declare function frontmatterTools(tools: AgentConfig["tools"]): string | null;
+/** Render one agent definition as a Claude Code agent markdown file. */
+export declare function renderAgentMarkdown(config: AgentConfig, version: string): string;
+//# sourceMappingURL=render.d.ts.map

package/dist/agents/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/agents/render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAkC7C,wGAAwG;AACxG,eAAO,MAAM,gBAAgB,mCAAmC,CAAA;AAEhE;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,CAU3E;AAOD,wEAAwE;AACxE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAiBhF"}

package/dist/agents/render.js

@@ -0,0 +1,69 @@
+import { resolveModel } from "../shared/model-resolution.js";
+/**
+ * Renders AgentConfig objects into Claude Code custom-agent markdown files
+ * (the `~/.claude/agents/*.md` format: YAML frontmatter with name /
+ * description / tools / model, body = system prompt).
+ *
+ * This is the bridge that turns the in-repo agent definitions into agents
+ * Claude Code can actually spawn via `Agent(subagent_type: "<name>")`.
+ */
+/**
+ * Tool names Claude Code can grant to a subagent via the frontmatter
+ * `tools:` allow-list. AgentConfig uses a deny-style map, so we convert:
+ * allow-list = universe minus denied. Agents that deny nothing omit the
+ * field entirely and inherit every tool (including future ones).
+ */
+const TOOL_UNIVERSE = [
+    "Bash",
+    "Glob",
+    "Grep",
+    "Read",
+    "Edit",
+    "Write",
+    "WebFetch",
+    "WebSearch",
+    "TodoWrite",
+    "Task",
+];
+/** AgentConfig calls the subagent-spawning tool "Agent"; frontmatter calls it "Task". */
+const TOOL_NAME_MAP = { Agent: "Task" };
+/** Marker embedded in every generated file so sync can tell its own files from user-authored agents. */
+export const GENERATED_MARKER = "generated-by: oh-my-claudecode";
+/**
+ * Convert an AgentConfig tools map into the frontmatter allow-list string.
+ * Returns null when the agent should inherit all tools (no real denials).
+ */
+export function frontmatterTools(tools) {
+    if (!tools)
+        return null;
+    const denied = new Set(Object.entries(tools)
+        .filter(([, allowed]) => allowed === false)
+        .map(([name]) => TOOL_NAME_MAP[name] ?? name));
+    const allowed = TOOL_UNIVERSE.filter((t) => !denied.has(t));
+    if (allowed.length === TOOL_UNIVERSE.length)
+        return null;
+    return allowed.join(", ");
+}
+/** Collapse a description to a single YAML-safe line. */
+function oneLine(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/** Render one agent definition as a Claude Code agent markdown file. */
+export function renderAgentMarkdown(config, version) {
+    const lines = ["---"];
+    lines.push(`name: ${config.name}`);
+    lines.push(`description: ${JSON.stringify(oneLine(config.description))}`);
+    const tools = frontmatterTools(config.tools);
+    if (tools)
+        lines.push(`tools: ${tools}`);
+    lines.push(`model: ${resolveModel(config.model)}`);
+    lines.push("---");
+    lines.push("");
+    lines.push(`<!-- ${GENERATED_MARKER} v${version} — regenerated by \`oh-my-claudecode sync\`. ` +
+        `Do not edit by hand: customize via ~/.claude/oh-my-claudecode.jsonc instead. -->`);
+    lines.push("");
+    lines.push(config.prompt.trim());
+    lines.push("");
+    return lines.join("\n");
+}
+//# sourceMappingURL=render.js.map