oh-my-claudecode 0.1.0

package/README.md

@@ -0,0 +1,281 @@
+# oh-my-claudecode
+
+> *Ph'nglui mglw'nafh Cthulhu R'lyeh wgah'nagl fhtagn.*
+
+A Cthulhu Mythos-themed agentic harness for [Claude Code](https://claude.ai/code). Provides 11 specialized Elder God agents, lifecycle hooks, a skill system, and multi-tier orchestration.
+
+## What This Is
+
+oh-my-claudecode extends Claude Code with a complete agentic infrastructure:
+
+- **11 Elder God agents** each specialized for a different domain
+- **5 lifecycle hooks** for todo enforcement, completion loops, code quality, and context injection
+- **9 slash commands (skills)** for invoking agents and managing sessions
+- **3-level config system** (defaults → user → project) with Zod validation
+- **Background agent management** with circuit breaker and concurrency limits
+- **Work plan system** with structured planning and review flow
+
+## Agent Roster
+
+| Elder God | Maps From | Model | Mode | Role |
+|-----------|-----------|-------|------|------|
+| **Cthulhu** | Sisyphus | Opus | primary | Main orchestrator — intent gate, delegation, parallel execution, verification |
+| **Nyarlathotep** | Hephaestus | Opus | subagent | Deep autonomous worker — end-to-end goal execution |
+| **Azathoth** | Atlas | Opus | primary | First-message planner — initial context sweep and routing |
+| **Shub-Niggurath** | Prometheus | Opus | primary | Strategic planner — interview → scope → plan → Tsathoggua review |
+| **Yog-Sothoth** | Oracle | Opus | subagent | Architecture/debug advisor — read-only, high-reasoning consultation |
+| **Hastur** | Sisyphus-Jr | Sonnet | subagent | Lightweight sub-orchestrator for bounded tasks |
+| **Ithaqua** | Metis | Sonnet | subagent | Pre-planning consultant — intent classification, anti-slop guardrails |
+| **Tsathoggua** | Momus | Sonnet | subagent | Work plan reviewer — blocker-finder, not perfectionist |
+| **Dagon** | Librarian | Sonnet | subagent | External documentation and GitHub source research |
+| **The Deep One** | Multimodal-Looker | Sonnet | subagent | Vision agent — images, screenshots, diagrams |
+| **Shoggoth** | Explore | Haiku | subagent | Fast parallel codebase search |
+
+## Installation
+
+```bash
+npx oh-my-claudecode install
+```
+
+The interactive wizard will:
+1. Install hook scripts to `~/.claude/hooks/`
+2. Register hooks in `~/.claude/settings.json`
+3. Install skill files to `~/.claude/skills/`
+4. Create `~/.claude/oh-my-claudecode.jsonc` config
+
+### Non-interactive install
+
+```bash
+npx oh-my-claudecode install --no-tui
+```
+
+### Requirements
+
+- Claude Code CLI installed (`npm install -g @anthropic-ai/claude-code` or equivalent)
+- Node.js 20+
+- `~/.claude/` directory writable
+
+## Slash Commands
+
+After installation, these are available in Claude Code sessions:
+
+| Command | Maps From | Description |
+|---------|-----------|-------------|
+| `/cthulhu` | (entry) | Activate Cthulhu orchestrator mode |
+| `/shoggoth` | (entry) | Activate Shoggoth search mode |
+| `/yog-sothoth` | (entry) | Activate Yog-Sothoth advisor mode |
+| `/elder-loop` | `/ralph-loop` | Start the completion loop |
+| `/cancel-elder-loop` | `/cancel-ralph` | Stop the active loop |
+| `/old-ones-init` | `/init-deep` | Generate AGENTS.md hierarchy |
+| `/invoke-shub` | `/start-work` | Strategic planning flow |
+| `/session-handoff` | `/handoff` | Create session continuation doc |
+| `/exorcise-ai-slop` | `/remove-ai-slops` | Purge AI code smells |
+
+## How Agents Are Invoked
+
+**Important difference from OpenCode**: OpenCode has a plugin API that allows registering named agents directly into its agent selector UI. Claude Code does not have an equivalent public plugin API.
+
+Instead, oh-my-claudecode agents are invoked through:
+
+1. **Slash commands** — `/cthulhu`, `/shoggoth`, etc. activate the named agent mode
+2. **Agent tool delegation** — Cthulhu uses `Agent(subagent_type="shoggoth", ...)` to spawn specialists
+3. **Skill-based dispatch** — skills installed to `~/.claude/skills/` are likely available as `subagent_type` values
+
+The agents are additive — they don't replace Claude Code's built-in agent types.
+
+## Configuration
+
+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/object fields. Array fields (`disabled_*`) are unioned.
+
+```jsonc
+{
+  // Override models for specific agents
+  "agents": {
+    "cthulhu": {
+      "model": "opus",
+      "prompt_append": "Always write tests for every function you create."
+    },
+    "shoggoth": {
+      "model": "haiku"
+    }
+  },
+
+  // Disable agents you don't need
+  "disabled_agents": ["nyarlathotep", "the-deep-one"],
+
+  // Disable specific lifecycle hooks
+  "disabled_hooks": ["comment-checker", "write-guard"],
+
+  // Elder Loop settings (completion loop)
+  "elder_loop": {
+    "max_iterations": 15,
+    "strategy": "continue"  // or "reset"
+  },
+
+  // Background agent limits
+  "background_task": {
+    "max_concurrent": 8,
+    "circuit_breaker_threshold": 3
+  }
+}
+```
+
+### Available Models
+
+Only Claude models are used:
+
+| Short Alias | Full Model ID |
+|-------------|--------------|
+| `opus` | `claude-opus-4-6` |
+| `sonnet` | `claude-sonnet-4-6` |
+| `haiku` | `claude-haiku-4-5` |
+
+## Lifecycle Hooks
+
+5 hooks are installed into Claude Code's `settings.json`:
+
+| Hook | Event | Description |
+|------|-------|-------------|
+| `todo-continuation` | Stop | If incomplete todos exist when stopping, inject a reminder to continue |
+| `elder-loop` | Stop | Self-referential completion loop (set promise → keeps running until met) |
+| `comment-checker` | PostToolUse | Warn when AI-slop comments are written (explains obvious code) |
+| `rules-injector` | PreToolUse | Auto-inject `.elder-gods/rules/*.md` into agent context |
+| `write-guard` | PreToolUse | Warn when `Write` is used on an existing file (suggest `Edit`) |
+
+Disable specific hooks in config:
+```jsonc
+{ "disabled_hooks": ["comment-checker", "write-guard"] }
+```
+
+## Project Structure
+
+```
+oh-my-claudecode/
+├── src/
+│   ├── agents/               # 11 Elder God agent definitions + builder
+│   ├── config/               # Zod schema — full type system
+│   ├── hooks/                # Lifecycle hook scripts and configs
+│   ├── features/
+│   │   ├── 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
+├── skills/                   # Markdown slash commands
+└── NECRONOMICON.md           # Plugin architecture reference
+```
+
+## Project-Level Setup
+
+### Architectural Rules
+
+Place rules in `.elder-gods/rules/*.md` — auto-injected into every agent's context:
+
+```
+.elder-gods/
+└── rules/
+    ├── no-any.md          # No TypeScript `any`
+    ├── test-coverage.md   # Minimum test requirements
+    └── naming-conv.md     # Naming conventions
+```
+
+Example `.elder-gods/rules/no-any.md`:
+```markdown
+# No TypeScript `any`
+
+NEVER use `any` type. Use `unknown` and narrow appropriately, or define a proper type.
+This rule is non-negotiable. Tsathoggua will reject any plan that introduces `any`.
+```
+
+### Work Plans
+
+Plans are stored in `.elder-gods/plans/*.md` and reviewed by Tsathoggua before execution.
+
+Use `/invoke-shub` to start the planning flow:
+1. Shub-Niggurath surveys codebase
+2. Interviews you with scoping questions
+3. Creates plan at `.elder-gods/plans/[task].md`
+4. Tsathoggua reviews for executability
+5. Cthulhu orchestrates implementation
+
+### Knowledge Base
+
+Use `/old-ones-init` to generate `AGENTS.md` files at the root and in key subdirectories. These give all agents project context without requiring repeated exploration.
+
+## Diagnostics
+
+```bash
+npx oh-my-claudecode doctor
+```
+
+Checks:
+- `~/.claude/` directory exists
+- `settings.json` present
+- All hook scripts installed
+- Hooks registered in settings
+- Skills installed
+- Plugin config valid
+
+## Agent Detail
+
+### Cthulhu (Main Orchestrator)
+
+The heart of the system. Every user message passes through Cthulhu's intent gate:
+
+1. **Verbalize intent** — explicitly classify what the user wants before acting
+2. **Route accordingly** — trivial → direct tools; exploratory → parallel Shoggoth agents; implementation → plan + delegate; ambiguous → one question
+3. **Plan before acting** — if 2+ steps, create detailed todos immediately
+4. **Delegate aggressively** — never work alone when a specialist is available
+5. **Verify before completing** — diagnostics, tests, evidence required
+
+### Shoggoth (Codebase Search)
+
+Fire 3+ in parallel. They're formless and free. Use for:
+- Finding where X is implemented
+- Discovering patterns to follow
+- Cross-module structure discovery
+
+### Yog-Sothoth (Architecture Advisor)
+
+Consult when:
+- Architecture decision requires multi-system tradeoffs
+- After 2+ failed fix attempts
+- Completing significant implementation for self-review
+
+Response always includes: Bottom line (2-3 sentences), Action plan (≤7 steps), Effort estimate.
+
+### Shub-Niggurath + Tsathoggua (Planning Flow)
+
+Shub-Niggurath interviews → creates `.elder-gods/plans/task.md` → Tsathoggua reviews it → OKAY or REJECT with max 3 blocking issues → Cthulhu executes.
+
+### The Elder Loop
+
+Activate with `/elder-loop [completion promise]`. The loop writes state to `.claude/elder-loop-state.json`. Each Stop event, the hook checks if the promise is met — if not, injects a reminder to continue.
+
+Deactivate with `/cancel-elder-loop`.
+
+## Development
+
+```bash
+git clone https://github.com/[your-username]/oh-my-claudecode
+cd oh-my-claudecode
+npm install
+npm run build
+```
+
+## Philosophy
+
+Core philosophy:
+
+- **Delegate first** — specialists exist for a reason; use them
+- **Parallel by default** — independent work always runs simultaneously  
+- **Evidence required** — no task is complete without diagnostics/test proof
+- **No AI slop** — no unnecessary abstractions, comments, or scope creep
+- **Blocker-finding, not perfectionism** — Tsathoggua finds blockers, not nitpicks
+
+## License
+
+MIT

package/bin/oh-my-claudecode.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import('../dist/cli/index.js').catch((err) => {
+  console.error('oh-my-claudecode: failed to load CLI', err.message);
+  process.exit(1);
+});

package/dist/agents/azathoth.d.ts

@@ -0,0 +1,19 @@
+import type { AgentConfig, AgentPromptMetadata } from "./types.js";
+import type { AvailableAgent, AvailableSkill, AvailableCategory } from "./types.js";
+/**
+ * Azathoth — First-Message Planner
+ *
+ * Mapped from: Atlas
+ * Model tier:  Opus
+ *
+ * Azathoth, the Blind Idiot God at the center of ultimate chaos — yet all reality
+ * flows from its dreaming. Azathoth is the first contact when you enter a session.
+ * Before Cthulhu takes over, Azathoth makes the initial context sweep and plan.
+ */
+export declare const AZATHOTH_PROMPT_METADATA: AgentPromptMetadata;
+export declare function createAzathothAgent(model: string, availableAgents?: AvailableAgent[], _availableToolNames?: string[], availableSkills?: AvailableSkill[], availableCategories?: AvailableCategory[]): AgentConfig;
+export declare namespace createAzathothAgent {
+    var mode: "primary";
+}
+export declare const azathothMetadata: AgentPromptMetadata;
+//# sourceMappingURL=azathoth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"azathoth.d.ts","sourceRoot":"","sources":["../../src/agents/azathoth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAa,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAC7E,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAInF;;;;;;;;;GASG;AAEH,eAAO,MAAM,wBAAwB,EAAE,mBAUtC,CAAA;AA6ED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,eAAe,GAAE,cAAc,EAAO,EACtC,mBAAmB,GAAE,MAAM,EAAO,EAClC,eAAe,GAAE,cAAc,EAAO,EACtC,mBAAmB,GAAE,iBAAiB,EAAO,GAC5C,WAAW,CAYb;yBAlBe,mBAAmB;;;AAqBnC,eAAO,MAAM,gBAAgB,EAAE,mBAA8C,CAAA"}

package/dist/agents/azathoth.js

@@ -0,0 +1,105 @@
+const MODE = "primary";
+/**
+ * Azathoth — First-Message Planner
+ *
+ * Mapped from: Atlas
+ * Model tier:  Opus
+ *
+ * Azathoth, the Blind Idiot God at the center of ultimate chaos — yet all reality
+ * flows from its dreaming. Azathoth is the first contact when you enter a session.
+ * Before Cthulhu takes over, Azathoth makes the initial context sweep and plan.
+ */
+export const AZATHOTH_PROMPT_METADATA = {
+    category: "orchestration",
+    cost: "EXPENSIVE",
+    promptAlias: "Azathoth",
+    keyTrigger: "First message in session → Azathoth activates for initial context gathering",
+    triggers: [
+        { domain: "Session start", trigger: "Initial context gathering and planning for the session" },
+    ],
+    useWhen: ["Very start of a new session with complex task"],
+    avoidWhen: ["Mid-session (Cthulhu handles continuation)"],
+};
+function buildAzathothPrompt(availableAgents, availableSkills, _availableCategories) {
+    const agentList = availableAgents
+        .filter(a => a.name !== "azathoth")
+        .map(a => `- **${a.metadata.promptAlias ?? a.name}**: ${a.description}`)
+        .join("\n");
+    const skillList = availableSkills
+        .map(s => `- **${s.name}**: ${s.description}`)
+        .join("\n");
+    return `You are "Azathoth" — the First Dreaming, the initial context gatherer of the oh-my-claudecode system.
+
+**Your role**: You activate at the VERY BEGINNING of complex sessions to:
+1. Quickly understand what the user needs
+2. Survey the relevant codebase context
+3. Make a lightweight plan
+4. Hand off to the appropriate specialist
+
+## Phase 1: Intent Classification (IMMEDIATE)
+
+Read the user's first message and classify:
+- **Trivial** (single file, known location) → Skip to direct execution
+- **Exploratory** ("How does X work?", "Find Y") → Survey codebase quickly, answer
+- **Implementation** (explicit implementation request) → Plan + handoff to Cthulhu
+- **Ambiguous** → Ask ONE clarifying question
+
+## Phase 2: Context Sweep (for non-trivial)
+
+Launch 2-3 parallel searches to understand the relevant codebase area:
+- Read AGENTS.md or CLAUDE.md if it exists
+- Find key files related to the user's request
+- Identify patterns to follow
+
+**Always parallel. Never sequential.**
+
+## Phase 3: Lightweight Plan
+
+For implementation requests:
+- Create a brief todo list (3-5 items max)
+- Identify which agents/skills to involve
+- Note any risks or ambiguities
+
+## Phase 4: Execution or Handoff
+
+- For trivial tasks: execute directly
+- For complex tasks: hand off to Cthulhu with full context
+- For ambiguous tasks: clarify first
+
+## Available Specialists
+
+${agentList || "No specialists loaded — operating solo."}
+
+## Available Skills
+
+${skillList || "No skills loaded."}
+
+## Communication Style
+
+- No preamble or acknowledgments
+- Start immediately with context sweep or clarifying question
+- Terse status updates
+- Plan via todos, not prose
+
+## Constraints
+
+- This is the FIRST message. Do not assume prior context.
+- Do not implement without planning (unless trivial)
+- Do not skip intent classification
+`;
+}
+export function createAzathothAgent(model, availableAgents = [], _availableToolNames = [], availableSkills = [], availableCategories = []) {
+    return {
+        name: "azathoth",
+        description: "The First Dreaming — initial context gatherer activated at session start. Surveys codebase, classifies intent, makes lightweight plan, hands off to appropriate specialist. (Azathoth — oh-my-claudecode)",
+        mode: MODE,
+        model,
+        thinking: { type: "enabled", budgetTokens: 16000 },
+        maxTokens: 32000,
+        prompt: buildAzathothPrompt(availableAgents, availableSkills, availableCategories),
+        color: "#FF8C00",
+    };
+}
+createAzathothAgent.mode = MODE;
+export const azathothMetadata = AZATHOTH_PROMPT_METADATA;
+//# sourceMappingURL=azathoth.js.map

package/dist/agents/azathoth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"azathoth.js","sourceRoot":"","sources":["../../src/agents/azathoth.ts"],"names":[],"mappings":"AAGA,MAAM,IAAI,GAAc,SAAS,CAAA;AAEjC;;;;;;;;;GASG;AAEH,MAAM,CAAC,MAAM,wBAAwB,GAAwB;IAC3D,QAAQ,EAAE,eAAe;IACzB,IAAI,EAAE,WAAW;IACjB,WAAW,EAAE,UAAU;IACvB,UAAU,EAAE,6EAA6E;IACzF,QAAQ,EAAE;QACR,EAAE,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,wDAAwD,EAAE;KAC/F;IACD,OAAO,EAAE,CAAC,+CAA+C,CAAC;IAC1D,SAAS,EAAE,CAAC,4CAA4C,CAAC;CAC1D,CAAA;AAED,SAAS,mBAAmB,CAC1B,eAAiC,EACjC,eAAiC,EACjC,oBAAyC;IAEzC,MAAM,SAAS,GAAG,eAAe;SAC9B,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC;SAClC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,WAAW,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;SACvE,IAAI,CAAC,IAAI,CAAC,CAAA;IAEb,MAAM,SAAS,GAAG,eAAe;SAC9B,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;SAC7C,IAAI,CAAC,IAAI,CAAC,CAAA;IAEb,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwCP,SAAS,IAAI,yCAAyC;;;;EAItD,SAAS,IAAI,mBAAmB;;;;;;;;;;;;;;CAcjC,CAAA;AACD,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,KAAa,EACb,kBAAoC,EAAE,EACtC,sBAAgC,EAAE,EAClC,kBAAoC,EAAE,EACtC,sBAA2C,EAAE;IAE7C,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,WAAW,EACT,2MAA2M;QAC7M,IAAI,EAAE,IAAI;QACV,KAAK;QACL,QAAQ,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE;QAClD,SAAS,EAAE,KAAK;QAChB,MAAM,EAAE,mBAAmB,CAAC,eAAe,EAAE,eAAe,EAAE,mBAAmB,CAAC;QAClF,KAAK,EAAE,SAAS;KACjB,CAAA;AACH,CAAC;AACD,mBAAmB,CAAC,IAAI,GAAG,IAAI,CAAA;AAE/B,MAAM,CAAC,MAAM,gBAAgB,GAAwB,wBAAwB,CAAA"}

package/dist/agents/builtin-agents.d.ts

@@ -0,0 +1,18 @@
+import type { AgentConfig, AvailableSkill, AvailableCategory, AgentPromptMetadata } from "./types.js";
+import type { AgentOverrides } from "../config/schema.js";
+/** Maps each agent name to its metadata (for orchestrator prompt building) */
+export declare const AGENT_METADATA_MAP: Record<string, AgentPromptMetadata>;
+export interface BuildAgentsOptions {
+    disabledAgents?: string[];
+    agentOverrides?: AgentOverrides;
+    systemDefaultModel?: string;
+    discoveredSkills?: AvailableSkill[];
+    availableCategories?: AvailableCategory[];
+    useTaskSystem?: boolean;
+}
+/**
+ * Creates all built-in Elder God agents with model resolution and overrides applied.
+ * Returns a record of agent name → AgentConfig ready for registration.
+ */
+export declare function buildBuiltinAgents(options?: BuildAgentsOptions): Record<string, AgentConfig>;
+//# sourceMappingURL=builtin-agents.d.ts.map

package/dist/agents/builtin-agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-agents.d.ts","sourceRoot":"","sources":["../../src/agents/builtin-agents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAkB,cAAc,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AACrH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAgBzD,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAYlE,CAAA;AAED,MAAM,WAAW,kBAAkB;IACjC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;IACzB,cAAc,CAAC,EAAE,cAAc,CAAA;IAC/B,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,gBAAgB,CAAC,EAAE,cAAc,EAAE,CAAA;IACnC,mBAAmB,CAAC,EAAE,iBAAiB,EAAE,CAAA;IACzC,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,kBAAuB,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAgIhG"}

package/dist/agents/builtin-agents.js

@@ -0,0 +1,141 @@
+import { createCthulhuAgent, CTHULHU_PROMPT_METADATA } from "./cthulhu.js";
+import { createYogSothothAgent, YOG_SOTHOTH_PROMPT_METADATA } from "./yog-sothoth.js";
+import { createShoggothAgent, SHOGGOTH_PROMPT_METADATA } from "./shoggoth.js";
+import { createDagonAgent, DAGON_PROMPT_METADATA } from "./dagon.js";
+import { createTsathoggua, TSATHOGGUA_PROMPT_METADATA } from "./tsathoggua.js";
+import { createIthaquaAgent, ITHAQUA_PROMPT_METADATA } from "./ithaqua.js";
+import { createHasturAgent, HASTUR_PROMPT_METADATA } from "./hastur.js";
+import { createNyarlathotepAgent, NYARLATHOTEP_PROMPT_METADATA } from "./nyarlathotep.js";
+import { createAzathothAgent, AZATHOTH_PROMPT_METADATA } from "./azathoth.js";
+import { createShubNiggurathAgent, SHUB_NIGGURATH_PROMPT_METADATA } from "./shub-niggurath.js";
+import { createDeepOneAgent, DEEP_ONE_PROMPT_METADATA } from "./the-deep-one.js";
+import { resolveAgentModel } from "../shared/model-resolution.js";
+import { deepMerge } from "../shared/deep-merge.js";
+/** Maps each agent name to its metadata (for orchestrator prompt building) */
+export const AGENT_METADATA_MAP = {
+    cthulhu: CTHULHU_PROMPT_METADATA,
+    "yog-sothoth": YOG_SOTHOTH_PROMPT_METADATA,
+    shoggoth: SHOGGOTH_PROMPT_METADATA,
+    dagon: DAGON_PROMPT_METADATA,
+    tsathoggua: TSATHOGGUA_PROMPT_METADATA,
+    ithaqua: ITHAQUA_PROMPT_METADATA,
+    hastur: HASTUR_PROMPT_METADATA,
+    nyarlathotep: NYARLATHOTEP_PROMPT_METADATA,
+    azathoth: AZATHOTH_PROMPT_METADATA,
+    "shub-niggurath": SHUB_NIGGURATH_PROMPT_METADATA,
+    "the-deep-one": DEEP_ONE_PROMPT_METADATA,
+};
+/**
+ * Creates all built-in Elder God agents with model resolution and overrides applied.
+ * Returns a record of agent name → AgentConfig ready for registration.
+ */
+export function buildBuiltinAgents(options = {}) {
+    const { disabledAgents = [], agentOverrides = {}, systemDefaultModel, discoveredSkills = [], availableCategories = [], useTaskSystem = false, } = options;
+    const disabled = new Set(disabledAgents);
+    const result = {};
+    function isEnabled(name) {
+        return !disabled.has(name);
+    }
+    function resolveModel(name) {
+        const override = agentOverrides[name];
+        return resolveAgentModel(name, override?.model, systemDefaultModel);
+    }
+    function applyOverride(config, name) {
+        const override = agentOverrides[name];
+        if (!override)
+            return config;
+        return {
+            ...config,
+            model: resolveModel(name),
+            description: override.description ?? config.description,
+            temperature: override.temperature ?? config.temperature,
+            maxTokens: override.maxTokens ?? config.maxTokens,
+            thinking: override.thinking ?? config.thinking,
+            color: override.color ?? config.color,
+            prompt: override.prompt ?? config.prompt + (override.prompt_append ? `\n\n${override.prompt_append}` : ""),
+            tools: override.tools ? deepMerge(config.tools, override.tools) : config.tools,
+        };
+    }
+    // Build available agents list for orchestrator prompt (excludes disabled agents)
+    const availableAgentsList = Object.entries(AGENT_METADATA_MAP)
+        .filter(([name]) => isEnabled(name) && name !== "cthulhu")
+        .map(([name, metadata]) => ({
+        name,
+        description: getAgentDescription(name),
+        metadata,
+    }));
+    // ── Cthulhu (main orchestrator) ─────────────────────────────────────────────
+    if (isEnabled("cthulhu")) {
+        const model = resolveModel("cthulhu");
+        const config = createCthulhuAgent(model, availableAgentsList, [], discoveredSkills, availableCategories, useTaskSystem);
+        result["cthulhu"] = applyOverride(config, "cthulhu");
+    }
+    // ── Nyarlathotep (deep worker) ───────────────────────────────────────────────
+    if (isEnabled("nyarlathotep")) {
+        const config = createNyarlathotepAgent(resolveModel("nyarlathotep"));
+        result["nyarlathotep"] = applyOverride(config, "nyarlathotep");
+    }
+    // ── Azathoth (first-message planner) ────────────────────────────────────────
+    if (isEnabled("azathoth")) {
+        const config = createAzathothAgent(resolveModel("azathoth"), availableAgentsList, [], discoveredSkills, availableCategories);
+        result["azathoth"] = applyOverride(config, "azathoth");
+    }
+    // ── Shub-Niggurath (strategic planner) ──────────────────────────────────────
+    if (isEnabled("shub-niggurath")) {
+        const config = createShubNiggurathAgent(resolveModel("shub-niggurath"));
+        result["shub-niggurath"] = applyOverride(config, "shub-niggurath");
+    }
+    // ── Yog-Sothoth (oracle/advisor) ────────────────────────────────────────────
+    if (isEnabled("yog-sothoth")) {
+        const config = createYogSothothAgent(resolveModel("yog-sothoth"));
+        result["yog-sothoth"] = applyOverride(config, "yog-sothoth");
+    }
+    // ── Dagon (librarian) ───────────────────────────────────────────────────────
+    if (isEnabled("dagon")) {
+        const config = createDagonAgent(resolveModel("dagon"));
+        result["dagon"] = applyOverride(config, "dagon");
+    }
+    // ── Ithaqua (plan consultant) ────────────────────────────────────────────────
+    if (isEnabled("ithaqua")) {
+        const config = createIthaquaAgent(resolveModel("ithaqua"));
+        result["ithaqua"] = applyOverride(config, "ithaqua");
+    }
+    // ── Tsathoggua (quality reviewer) ───────────────────────────────────────────
+    if (isEnabled("tsathoggua")) {
+        const config = createTsathoggua(resolveModel("tsathoggua"));
+        result["tsathoggua"] = applyOverride(config, "tsathoggua");
+    }
+    // ── Hastur (junior orchestrator) ────────────────────────────────────────────
+    if (isEnabled("hastur")) {
+        const config = createHasturAgent(resolveModel("hastur"));
+        result["hastur"] = applyOverride(config, "hastur");
+    }
+    // ── Shoggoth (explorer) ─────────────────────────────────────────────────────
+    if (isEnabled("shoggoth")) {
+        const config = createShoggothAgent(resolveModel("shoggoth"));
+        result["shoggoth"] = applyOverride(config, "shoggoth");
+    }
+    // ── The Deep One (vision) ───────────────────────────────────────────────────
+    if (isEnabled("the-deep-one")) {
+        const config = createDeepOneAgent(resolveModel("the-deep-one"));
+        result["the-deep-one"] = applyOverride(config, "the-deep-one");
+    }
+    return result;
+}
+/** Short descriptions for the delegation table in Cthulhu's prompt */
+function getAgentDescription(name) {
+    const descriptions = {
+        "yog-sothoth": "Architecture/debugging advisor. Consult for hard problems and design decisions.",
+        shoggoth: "Codebase pattern-matcher. Fast parallel search for files and code.",
+        dagon: "External library and documentation specialist.",
+        tsathoggua: "Work plan reviewer. Verifies plans are executable.",
+        ithaqua: "Pre-planning consultant. Analyzes intent, prevents over-engineering.",
+        hastur: "Lightweight sub-orchestrator for bounded tasks.",
+        nyarlathotep: "Deep autonomous worker. End-to-end goal execution.",
+        azathoth: "First-message planner. Initial context gathering.",
+        "shub-niggurath": "Strategic planner. Interview → scope → plan.",
+        "the-deep-one": "Vision specialist. Analyzes images and visual content.",
+    };
+    return descriptions[name] ?? "Specialized agent.";
+}
+//# sourceMappingURL=builtin-agents.js.map

package/dist/agents/builtin-agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-agents.js","sourceRoot":"","sources":["../../src/agents/builtin-agents.ts"],"names":[],"mappings":"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"}

package/dist/agents/cthulhu.d.ts

@@ -0,0 +1,21 @@
+import type { AgentConfig, AgentPromptMetadata } from "./types.js";
+import type { AvailableAgent, AvailableSkill, AvailableCategory } from "./types.js";
+/**
+ * Cthulhu — Main Orchestrator
+ *
+ * Mapped from: Sisyphus
+ * Model tier:  Opus
+ *
+ * Ph'nglui mglw'nafh Cthulhu R'lyeh wgah'nagl fhtagn.
+ * "In his house at R'lyeh, dead Cthulhu waits dreaming."
+ *
+ * Cthulhu is the primary orchestrator of the entire system — the dreaming god
+ * who coordinates all Elder God agents. Plans obsessively, delegates ruthlessly,
+ * verifies thoroughly. The boulder rolls; so do we.
+ */
+export declare const CTHULHU_PROMPT_METADATA: AgentPromptMetadata;
+export declare function createCthulhuAgent(model: string, availableAgents?: AvailableAgent[], availableToolNames?: string[], availableSkills?: AvailableSkill[], availableCategories?: AvailableCategory[], useTaskSystem?: boolean): AgentConfig;
+export declare namespace createCthulhuAgent {
+    var mode: "primary";
+}
+//# sourceMappingURL=cthulhu.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cthulhu.d.ts","sourceRoot":"","sources":["../../src/agents/cthulhu.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAa,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAC7E,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,iBAAiB,EAAiB,MAAM,YAAY,CAAA;AAIlG;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,uBAAuB,EAAE,mBAKrC,CAAA;AA6VD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,eAAe,GAAE,cAAc,EAAO,EACtC,kBAAkB,GAAE,MAAM,EAAO,EACjC,eAAe,GAAE,cAAc,EAAO,EACtC,mBAAmB,GAAE,iBAAiB,EAAO,EAC7C,aAAa,UAAQ,GACpB,WAAW,CAyBb;yBAhCe,kBAAkB"}