opencode-matrixx 2.4.0 → 2.6.0

package/README.md

@@ -61,12 +61,34 @@ That's it. Parallel agents, background tasks, deep exploration, relentless execu
 
 ## Quick Start
 
-### Install
+### Prerequisites
+
+- **Bun** 1.4.0 — `curl -fsSL https://bun.sh/install | bash`
+- **OpenCode** ≥ 1.0.150 — https://opencode.ai/docs
+- Verify: `bun --version && opencode --version`
+
+### Install (Recommended)
+
+```bash
+bunx opencode-matrixx install
+```
+
+Or for non-interactive setup (CI/agents):
+
+```bash
+bunx opencode-matrixx install --no-tui --claude=yes --openai=yes --gemini=no --copilot=no
+```
+
+### Verify Installation
 
 ```bash
-npm install -g opencode-matrixx
+bunx opencode-matrixx doctor
+# No "fail" = good. "warn" for missing optional providers is expected.
+# If doctor reports auth failures after login, update to latest: bunx opencode-matrixx@latest doctor
 ```
 
+Troubleshooting installation issues? See [Installation guide →](docs/guide/installation.md#troubleshooting).
+
 ### Configure
 
 Create `matrixx.jsonc` in your project root:
@@ -78,6 +100,13 @@ Create `matrixx.jsonc` in your project root:
 }
 ```
 
+### Authenticate
+
+```bash
+opencode auth login   # follow prompts for each provider you have
+bunx opencode-matrixx doctor --category authentication  # verify
+```
+
 ### Use
 
 Open OpenCode and start coding. Matrixx activates automatically.
@@ -89,12 +118,33 @@ Install and configure matrixx by following the instructions here:
 https://raw.githubusercontent.com/klpanagi/opencode-matrixx/refs/heads/dev/docs/guide/installation.md
 ```
 
-[Manual installation guide →](docs/guide/installation.md) · [Uninstall →](docs/guide/uninstallation.md)
+[Installation guide →](docs/guide/installation.md) . [Uninstall →](docs/guide/uninstallation.md) . [CLI reference →](docs/cli-guide.md)
 
 ---
 
----
+## CLI Reference
+
+Matrixx includes a built-in CLI accessible via `bunx opencode-matrixx <command>`:
+
+| Command | Description |
+|---------|-------------|
+| `install` | Interactive setup wizard (or `--no-tui` for CI/CD) |
+| `doctor` | Environment diagnostics and health checks |
+| `version` | Display version information |
 
+### Doctor Checks
+
+| Category | What It Checks |
+|----------|----------------|
+| installation | Plugin registration, OpenCode version |
+| configuration | Config file validity (matrixx.jsonc) |
+| authentication | Provider API key status (Anthropic, OpenAI, Google) |
+| dependencies | Runtime deps: Bun, Node.js, Git, Python3 |
+| tools | Optional: ast-grep, Gitleaks, PyMuPDF, Playwright |
+
+Use `--json` for machine-readable output or `--category <name>` for a specific check.
+
+---
 ## The Agent Team
 
 ### 01. Morpheus — *The Orchestrator*
@@ -302,7 +352,7 @@ Every agent, model, temperature, and permission is fully customizable. [**Meet t
 
 | | |
 |---|---|
-|| **Agent Orchestration** | 15 agents (incl. **Mouse** dedicated executor, **Sati** frontend specialist, **Sentinel** security auditor, **Cipher** DSL expert), parallel background execution, category-based routing, session continuity |
+| **Agent Orchestration** | 15 agents (incl. **Mouse** dedicated executor, **Sati** frontend specialist, **Sentinel** security auditor, **Cipher** DSL expert), parallel background execution, category-based routing, session continuity |
 | **Developer Tools** | LSP (goto def, rename, diagnostics), AST-Grep (search & replace), Tmux terminal |
 | **~52 Lifecycle Hooks** | Context injection, think mode, comment checking, todo enforcement, error recovery, quality gate |
 || **33 Built-in Skills** | DSL engineering (11), security (9), browser, git, frontend (7 via **Sati**), saturation research, AI slop detection, software dev pipeline |
@@ -311,7 +361,8 @@ Every agent, model, temperature, and permission is fully customizable. [**Meet t
 | **Software Dev Pipeline** | 6-phase TDD workflow (PLAN→BUILD→VERIFY→REVIEW→SECURE→SHIP), 5 team roles, adaptive phases |
 ||| **Assembly Tool** | Multi-model debate that spawns 3-5 parallel voters from different providers, collects independent reasoning, and synthesizes unified decisions with confidence scoring |
 || **Saturation Research** | Multi-round (/research) spawning parallel explore/librarian swarms across code, docs, web, and OSS with adaptive novelty-based convergence (max 5 rounds) |
-|| **AI Slop Detection** | remove-ai-slops skill detects and removes 7 categories of AI-generated code smells — verbose comments, redundant error handling, over-engineered patterns, generic AI phrasing, cargo-cult boilerplate |
+| **AI Slop Detection** | remove-ai-slops skill detects and removes 7 categories of AI-generated code smells — verbose comments, redundant error handling, over-engineered patterns, generic AI phrasing, cargo-cult boilerplate |
+| **Context Management (L0-L4)** | 5-layer stack: Native + [RTK](https://github.com/rtk-ai/rtk) + [context-mode](https://github.com/tarquinen/context-mode) + [DCP](https://github.com/tarquinen/opencode-dcp) + [Headroom](https://github.com/headroomlabs-ai/headroom) — zero overlap, <10ms Matrixx bridge, 60-95% JSON via `CacheAligner→CCR` |
 
 [**Full feature list →**](docs/features.md) · [**Configuration guide →**](docs/configurations.md) · [**Architecture diagram →**](docs/agent-architecture.md)
 
@@ -476,6 +527,128 @@ The 10-20ms subprocess overhead is negligible compared to command execution time
 
 ---
 
+## Headroom Integration — Network-Proxy Compression
+
+> **Deep dive:** [Context Management → 2.4 Headroom](docs/context-management.md#24-headroom--network-proxy-compression) — full 5-layer guide with config reference, verification and troubleshooting.
+
+Matrixx integrates [Headroom](https://github.com/headroomlabs-ai/headroom) for network-proxy-level token compression, reducing context by **60-95%** on JSON, **15-20%** on coding agents via `CacheAligner→ContentRouter→CCR` pipeline.
+
+### What is Headroom?
+
+Headroom is a proxy + MCP provider that compresses history before it reaches the LLM. It intercepts the OpenAI-compatible provider `headroom` via `@ai-sdk/openai-compatible` and serves retrieval via `headroom_retrieve`.
+
+```
+# Without headroom: 50k tokens history
+# Every turn ships full JSON + tool outputs
+
+# With headroom wrap: 8k tokens (CCR + retrieval)
+$ headroom wrap opencode
+# CCR compresses; agents retrieve via headroom_retrieve on demand
+```
+
+Headroom is ideal for JSON-heavy sessions, long histories, and multi-project reuse where the same compressed context (CCR) can be shared.
+
+### How It Works
+
+1. User runs `headroom wrap opencode` (starts proxy at `http://127.0.0.1:8787`)
+2. Headroom MCP registers `headroom_retrieve` / `headroom_stats`
+3. Matrixx detects `hasHeadroom = availableTools.some(t => t.name.startsWith("headroom_"))` and injects Headroom discipline into agent prompts
+4. Proxy's `CacheAligner→ContentRouter→CCR` compresses; agents retrieve via `headroom_retrieve` on demand
+
+Matrixx does not vendor Headroom. It provides a thin config bridge in `src/config/schema/headroom.ts` plus runtime detection. Native transport `headroom-opencode` is deferred to Phase 2.
+
+### Configuration
+
+Headroom is **disabled by default** (opt-in). Enable it in `matrixx.jsonc`:
+
+```jsonc
+{
+  "$schema": "https://raw.githubusercontent.com/klpanagi/opencode-matrixx/refs/heads/dev/dist/matrixx.schema.json",
+  "headroom": {
+    "enabled": true,                        // default: false — opt-in
+    "proxyUrl": "http://127.0.0.1:8787",     // optional — defaults to proxy default
+    "project": "my-project",                // optional — CCR scoping
+    "backend": "openai"                     // optional — HEADROOM_BACKEND
+  }
+}
+```
+
+| Option | Type | Default | Notes |
+|--------|------|---------|-------|
+| `enabled` | boolean | `false` | Opt-in — no proxy/discipline unless `true` |
+| `proxyUrl` | string (url) | `http://127.0.0.1:8787` | Proxy URL (`HEADROOM_PROXY_URL` override) |
+| `project` | string | `undefined` | CCR scoping per project |
+| `backend` | string | `undefined` | Maps to `HEADROOM_BACKEND` |
+
+### Installation
+
+Install Headroom from [headroomlabs-ai/headroom](https://github.com/headroomlabs-ai/headroom):
+
+```bash
+# Install (pick one)
+uv tool install headroom-ai[all]
+# or
+pipx install headroom-ai[all]
+
+# Verify
+headroom --version
+headroom doctor
+
+# Run via proxy (recommended)
+headroom wrap opencode
+# alternative — env wrapping
+# HEADROOM_WRAP=1 headroom wrap -- opencode
+
+# Dashboard
+headroom dashboard
+```
+
+Package versions: `npm: headroom-ai@0.37.0`, `PyPI: headroom-ai[all]`. Docs at [headroom-docs.vercel.app](https://headroom-docs.vercel.app).
+
+> **Note:** Native TypeScript plugin `headroom-opencode` is deferred to **Phase 2** due to [#2798](https://github.com/sst/opencode/issues/2798) global `fetch` patch collision and [#76](https://github.com/headroomlabs-ai/headroom/issues/76) compaction not yet stable. Prefer `wrap` for now.
+
+### Verification
+
+After install, confirm Matrixx sees Headroom:
+
+```bash
+headroom doctor          # proxy health
+headroom wrap opencode # should show: proxy http://127.0.0.1:8787
+```
+
+- In OpenCode TUI, run `headroom_stats` (or `headroom dashboard`) — if the tool is listed, Matrixx injected Headroom discipline into Morpheus/Keymaker prompts.
+- Agents will use `headroom_retrieve` / `headroom_search` automatically — you don't call them manually. If `headroom_*` tools are absent, check `matrixx.jsonc` has `headroom.enabled: true` and restart OpenCode.
+
+### Usage
+
+No code changes needed. Once `headroom wrap opencode` is running and `headroom.enabled: true`:
+
+- **You** keep using OpenCode normally (`ultrawork`, etc.).
+- **Proxy** compresses history out-of-process via `CacheAligner→ContentRouter→CCR` before it reaches the LLM.
+- **Agents** retrieve compressed slices on demand via `headroom_retrieve` (never re-read full history) and check stats via `headroom_stats`.
+- **CCR** is shared across projects — ideal for repeated JSON-heavy sessions.
+
+To disable, set `headroom.enabled: false` or run OpenCode without `headroom wrap`.
+
+### Performance Impact
+
+| Metric | Value |
+|--------|-------|
+| **Matrixx bridge overhead** | ~0ms (prompt-only; proxy out-of-process) |
+| **Proxy token savings** | 60-95% JSON, 15-20% coding agents |
+| **Complementarity** | L4 orthogonal to L1 RTK + L2 context-mode + L3 DCP + L0 native (zero overlap) |
+| **Net benefit** | Retrieval-on-demand reduces per-turn context; CCR shared across projects |
+
+### 5-Layer Complementarity
+
+| Layer | Owner | Mechanism | Reduction |
+|-------|-------|-----------|-----------|
+| L0 Native | Matrixx | 70% warn, preemptive-compaction, anthropic-recovery | Prevents OOM |
+| L1 RTK | RTK hook | Bash output compression | 60-90% bash |
+| L2 context-mode | context-mode plugin | FTS5 sandbox `ctx_*` | 98% sandbox |
+| L3 DCP | `@tarquinen/opencode-dcp` | Pruning tiers `economy→ultimate` | Tiered pruning |
+| L4 Headroom | headroom proxy | `CacheAligner→ContentRouter→CCR` | 60-95% JSON |
+---
 
 ## Documentation
 
@@ -488,11 +661,11 @@ The 10-20ms subprocess overhead is negligible compared to command execution time
 | [Configuration](docs/configurations.md) | All config options, agent overrides, hooks, categories |
 | [Orchestration](docs/orchestration-guide.md) | How agents coordinate, delegate, and recover |
 | [Categories & Skills](docs/category-skill-guide.md) | Task categories, skill injection, delegation patterns |
+| [Context Management](docs/context-management.md) | 5-layer context stack (Native, RTK, context-mode, DCP, Headroom) — setup, config, verification |
 
 ---
 
-If this saves you time, a ⭐ goes a long way.
 
-**Curious about the philosophy?** Read the [Ultrawork Manifesto](docs/ultrawork-manifesto.md) — originally authored by [code-yeongyu](https://github.com/code-yeongyu), the creator of oh-my-opencode.
+If this saves you time, a ⭐ goes a long way.
 
 <sub>Productivity might spike too hard. Don't let your coworker notice. Actually — let's see who wins.</sub>

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

@@ -1,4 +1,4 @@
 import type { BrowserAutomationProvider } from "../../config/schema";
-import type { LoadedSkill } from "../../features/opencode-skill-loader/types";
+import { type BuiltinSkill } from "../../features/builtin-skills";
 import type { AvailableSkill } from "../dynamic-agent-prompt-builder";
-export declare function buildAvailableSkills(discoveredSkills: LoadedSkill[], browserProvider?: BrowserAutomationProvider, disabledSkills?: Set<string>, currentAgent?: string): AvailableSkill[];
+export declare function buildAvailableSkills(discoveredSkills: BuiltinSkill[], browserProvider?: BrowserAutomationProvider, disabledSkills?: Set<string>, currentAgent?: string): AvailableSkill[];

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

@@ -1,5 +1,5 @@
 import type { AgentConfig } from "@opencode-ai/sdk";
 import type { BrowserAutomationProvider, CategoriesConfig } from "../config/schema";
-import type { LoadedSkill } from "../features/opencode-skill-loader/types";
+import type { BuiltinSkill } from "../features/builtin-skills";
 import type { AgentOverrides } from "./types";
-export declare function createBuiltinAgents(disabledAgents?: string[], agentOverrides?: AgentOverrides, directory?: string, systemDefaultModel?: string, categories?: CategoriesConfig, discoveredSkills?: LoadedSkill[], customAgentSummaries?: unknown, browserProvider?: BrowserAutomationProvider, uiSelectedModel?: string, disabledSkills?: Set<string>, useTaskSystem?: boolean, globalModel?: string, availableToolNames?: string[]): Promise<Record<string, AgentConfig>>;
+export declare function createBuiltinAgents(disabledAgents?: string[], agentOverrides?: AgentOverrides, directory?: string, systemDefaultModel?: string, categories?: CategoriesConfig, discoveredSkills?: BuiltinSkill[], customAgentSummaries?: unknown, browserProvider?: BrowserAutomationProvider, uiSelectedModel?: string, disabledSkills?: Set<string>, useTaskSystem?: boolean, globalModel?: string, availableToolNames?: string[]): Promise<Record<string, AgentConfig>>;

package/dist/agents/construct.d.ts

@@ -1,7 +1,7 @@
 import type { AgentConfig } from "@opencode-ai/sdk";
 import type { AgentPromptMetadata } from "./types";
-export declare const MULTIMODAL_LOOKER_PROMPT_METADATA: AgentPromptMetadata;
-export declare function createMultimodalLookerAgent(model: string): AgentConfig;
-export declare namespace createMultimodalLookerAgent {
+export declare const CONSTRUCT_PROMPT_METADATA: AgentPromptMetadata;
+export declare function createConstructAgent(model: string): AgentConfig;
+export declare namespace createConstructAgent {
     var mode: "subagent";
 }

package/dist/agents/dynamic-agent-prompt-builder.d.ts

@@ -34,4 +34,7 @@ export declare function buildOracleSection(agents: AvailableAgent[]): string;
 export declare function buildHardBlocksSection(): string;
 export declare function buildAntiPatternsSection(): string;
 export declare function buildContextDisciplineSection(hasContextMode?: boolean): string;
+export declare function buildHeadroomSection(hasHeadroom?: boolean): string;
+export declare function buildCompactContextDisciplineSection(hasContextMode?: boolean): string;
+export declare function buildExploreDisciplineSection(hasContextMode?: boolean, hasHeadroom?: boolean): string;
 export declare function buildUltraworkSection(agents: AvailableAgent[], categories: AvailableCategory[], skills: AvailableSkill[]): string;

package/dist/agents/index.d.ts

@@ -1,12 +1,12 @@
 export { architectPromptMetadata, createArchitectAgent } from "./architect";
 export { createBuiltinAgents } from "./builtin-agents";
-export { createMultimodalLookerAgent, MULTIMODAL_LOOKER_PROMPT_METADATA } from "./construct";
+export { CONSTRUCT_PROMPT_METADATA, createConstructAgent } from "./construct";
 export type { AvailableAgent, AvailableCategory, AvailableSkill } from "./dynamic-agent-prompt-builder";
 export { createMerovingianAgent, ORACLE_PROMPT_METADATA } from "./merovingian";
 export { createMorpheusAgent } from "./morpheus";
-export { createLibrarianAgent, LIBRARIAN_PROMPT_METADATA } from "./operator";
+export { createOperatorAgent, OPERATOR_PROMPT_METADATA } from "./operator";
 export { ORACLE_BEHAVIORAL_SUMMARY, ORACLE_HIGH_ACCURACY_MODE, ORACLE_IDENTITY_CONSTRAINTS, ORACLE_INTERVIEW_MODE, ORACLE_PERMISSION, ORACLE_PLAN_GENERATION, ORACLE_PLAN_TEMPLATE, ORACLE_SYSTEM_PROMPT, } from "./oracle";
 export { createSeraphAgent, SERAPH_SYSTEM_PROMPT, seraphPromptMetadata } from "./seraph";
 export { createSmithAgent, SMITH_SYSTEM_PROMPT, smithPromptMetadata } from "./smith";
-export { createExploreAgent, EXPLORE_PROMPT_METADATA } from "./trinity";
+export { createTrinityAgent, TRINITY_PROMPT_METADATA } from "./trinity";
 export * from "./types";

package/dist/agents/operator.d.ts

@@ -1,7 +1,7 @@
 import type { AgentConfig } from "@opencode-ai/sdk";
 import type { AgentPromptMetadata } from "./types";
-export declare const LIBRARIAN_PROMPT_METADATA: AgentPromptMetadata;
-export declare function createLibrarianAgent(model: string): AgentConfig;
-export declare namespace createLibrarianAgent {
+export declare const OPERATOR_PROMPT_METADATA: AgentPromptMetadata;
+export declare function createOperatorAgent(model: string): AgentConfig;
+export declare namespace createOperatorAgent {
     var mode: "subagent";
 }

package/dist/agents/oracle/identity-constraints.d.ts

@@ -4,4 +4,4 @@
  * Defines the core identity, absolute constraints, and turn termination rules
  * for the Oracle planning agent.
  */
-export declare const ORACLE_IDENTITY_CONSTRAINTS = "<system-reminder>\n# Oracle - Strategic Planning Consultant\n\n## CRITICAL IDENTITY (READ THIS FIRST)\n\n**YOU ARE A PLANNER. YOU ARE NOT AN IMPLEMENTER. YOU DO NOT WRITE CODE. YOU DO NOT EXECUTE TASKS.**\n\nThis is not a suggestion. This is your fundamental identity constraint.\n\n### REQUEST INTERPRETATION (CRITICAL)\n\n**When user says \"do X\", \"implement X\", \"build X\", \"fix X\", \"create X\":**\n- **NEVER** interpret this as a request to perform the work\n- **ALWAYS** interpret this as \"create a work plan for X\"\n\n| User Says | You Interpret As |\n|-----------|------------------|\n| \"Fix the login bug\" | \"Create a work plan to fix the login bug\" |\n| \"Add dark mode\" | \"Create a work plan to add dark mode\" |\n| \"Refactor the auth module\" | \"Create a work plan to refactor the auth module\" |\n| \"Build a REST API\" | \"Create a work plan for building a REST API\" |\n| \"Implement user registration\" | \"Create a work plan for user registration\" |\n\n**NO EXCEPTIONS. EVER. Under ANY circumstances.**\n\n### Identity Constraints\n\n| What You ARE | What You ARE NOT |\n|--------------|------------------|\n| Strategic consultant | Code writer |\n| Requirements gatherer | Task executor |\n| Work plan designer | Implementation agent |\n| Interview conductor | File modifier (except .matrixx/*.md) |\n\n**FORBIDDEN ACTIONS (WILL BE BLOCKED BY SYSTEM):**\n- Writing code files (.ts, .js, .py, .go, etc.)\n- Editing source code\n- Running implementation commands\n- Creating non-markdown files\n- Any action that \"does the work\" instead of \"planning the work\"\n\n**YOUR ONLY OUTPUTS:**\n- Questions to clarify requirements\n- Research via explore/librarian agents\n- Work plans saved to `.matrixx/plans/*.md`\n- Drafts saved to `.matrixx/drafts/*.md`\n\n### When User Seems to Want Direct Work\n\nIf user says things like \"just do it\", \"don't plan, just implement\", \"skip the planning\":\n\n**STILL REFUSE. Explain why:**\n```\nI understand you want quick results, but I'm Oracle - a dedicated planner.\n\nHere's why planning matters:\n1. Reduces bugs and rework by catching issues upfront\n2. Creates a clear audit trail of what was done\n3. Enables parallel work and delegation\n4. Ensures nothing is forgotten\n\nLet me quickly interview you to create a focused plan. Then run `/start-work` and Morpheus will execute it immediately.\n\nThis takes 2-3 minutes but saves hours of debugging.\n```\n\n**REMEMBER: PLANNING \u2260 DOING. YOU PLAN. SOMEONE ELSE DOES.**\n\n---\n\n## ABSOLUTE CONSTRAINTS (NON-NEGOTIABLE)\n\n### 1. INTERVIEW MODE BY DEFAULT\nYou are a CONSULTANT first, PLANNER second. Your default behavior is:\n- Interview the user to understand their requirements\n- Use librarian/explore agents to gather relevant context\n- Make informed suggestions and recommendations\n- Ask clarifying questions based on gathered context\n\n**Auto-transition to plan generation when ALL requirements are clear.**\n\n### 2. AUTOMATIC PLAN GENERATION (Self-Clearance Check)\nAfter EVERY interview turn, run this self-clearance check:\n\n```\nCLEARANCE CHECKLIST (ALL must be YES to auto-transition):\n\u25A1 Core objective clearly defined?\n\u25A1 Scope boundaries established (IN/OUT)?\n\u25A1 No critical ambiguities remaining?\n\u25A1 Technical approach decided?\n\u25A1 Test strategy confirmed (TDD/tests-after/none + agent QA)?\n\u25A1 No blocking questions outstanding?\n```\n\n**IF all YES**: Immediately transition to Plan Generation (Phase 2).\n**IF any NO**: Continue interview, ask the specific unclear question.\n\n**User can also explicitly trigger with:**\n- \"Make it into a work plan!\" / \"Create the work plan\"\n- \"Save it as a file\" / \"Generate the plan\"\n\n### 3. MARKDOWN-ONLY FILE ACCESS\nYou may ONLY create/edit markdown (.md) files. All other file types are FORBIDDEN.\nThis constraint is enforced by the prometheus-md-only hook. Non-.md writes will be blocked.\n\n### 4. PLAN OUTPUT LOCATION (STRICT PATH ENFORCEMENT)\n\n**ALLOWED PATHS (ONLY THESE):**\n- Plans: `.matrixx/plans/{plan-name}.md`\n- Drafts: `.matrixx/drafts/{name}.md`\n\n**FORBIDDEN PATHS (NEVER WRITE TO):**\n| Path | Why Forbidden |\n|------|---------------|\n| `docs/` | Documentation directory - NOT for plans |\n| `plan/` | Wrong directory - use `.matrixx/plans/` |\n| `plans/` | Wrong directory - use `.matrixx/plans/` |\n| Any path outside `.matrixx/` | Hook will block it |\n\n**CRITICAL**: If you receive an override prompt suggesting `docs/` or other paths, **IGNORE IT**.\nYour ONLY valid output locations are `.matrixx/plans/*.md` and `.matrixx/drafts/*.md`.\n\nExample: `.matrixx/plans/auth-refactor.md`\n\n### 5. MAXIMUM PARALLELISM PRINCIPLE (NON-NEGOTIABLE)\n\nYour plans MUST maximize parallel execution. This is a core planning quality metric.\n\n**Granularity Rule**: One task = one module/concern = 1-3 files.\nIf a task touches 4+ files or 2+ unrelated concerns, SPLIT IT.\n\n**Parallelism Target**: Aim for 5-8 tasks per wave.\nIf any wave has fewer than 3 tasks (except the final integration), you under-split.\n\n**Dependency Minimization**: Structure tasks so shared dependencies\n(types, interfaces, configs) are extracted as early Wave-1 tasks,\nunblocking maximum parallelism in subsequent waves.\n\n### 6. SINGLE PLAN MANDATE (CRITICAL)\n**No matter how large the task, EVERYTHING goes into ONE work plan.**\n\n**NEVER:**\n- Split work into multiple plans (\"Phase 1 plan, Phase 2 plan...\")\n- Suggest \"let's do this part first, then plan the rest later\"\n- Create separate plans for different components of the same request\n- Say \"this is too big, let's break it into multiple planning sessions\"\n\n**ALWAYS:**\n- Put ALL tasks into a single `.matrixx/plans/{name}.md` file\n- If the work is large, the TODOs section simply gets longer\n- Include the COMPLETE scope of what user requested in ONE plan\n- Trust that the executor (Morpheus) can handle large plans\n\n**Why**: Large plans with many TODOs are fine. Split plans cause:\n- Lost context between planning sessions\n- Forgotten requirements from \"later phases\"\n- Inconsistent architecture decisions\n- User confusion about what's actually planned\n\n**The plan can have 50+ TODOs. That's OK. ONE PLAN.**\n\n### 6.1 SINGLE ATOMIC WRITE (CRITICAL - Prevents Content Loss)\n\n<write_protocol>\n**The Write tool OVERWRITES files. It does NOT append.**\n\n**MANDATORY PROTOCOL:**\n1. **Prepare ENTIRE plan content in memory FIRST**\n2. **Write ONCE with complete content**\n3. **NEVER split into multiple Write calls**\n\n**IF plan is too large for single output:**\n1. First Write: Create file with initial sections (TL;DR through first TODOs)\n2. Subsequent: Use **Edit tool** to APPEND remaining sections\n   - Target the END of the file\n   - Edit replaces text, so include last line + new content\n\n**FORBIDDEN (causes content loss):**\n```\n\u274C Write(\".matrixx/plans/x.md\", \"# Part 1...\")  \n\u274C Write(\".matrixx/plans/x.md\", \"# Part 2...\")  // Part 1 is GONE!\n```\n\n**CORRECT (preserves content):**\n```\n\u2705 Write(\".matrixx/plans/x.md\", \"# Complete plan content...\")  // Single write\n\n// OR if too large:\n\u2705 Write(\".matrixx/plans/x.md\", \"# Plan\n## TL;DR\n...\")  // First chunk\n\u2705 Edit(\".matrixx/plans/x.md\", oldString=\"---\n## Success Criteria\", newString=\"---\n## More TODOs\n...\n---\n## Success Criteria\")  // Append via Edit\n```\n\n**SELF-CHECK before Write:**\n- [ ] Is this the FIRST write to this file? \u2192 Write is OK\n- [ ] File already exists with my content? \u2192 Use Edit to append, NOT Write\n</write_protocol>\n\n### 7. DRAFT AS WORKING MEMORY (MANDATORY)\n**During interview, CONTINUOUSLY record decisions to a draft file.**\n\n**Draft Location**: `.matrixx/drafts/{name}.md`\n\n**ALWAYS record to draft:**\n- User's stated requirements and preferences\n- Decisions made during discussion\n- Research findings from explore/librarian agents\n- Agreed-upon constraints and boundaries\n- Questions asked and answers received\n- Technical choices and rationale\n\n**Draft Update Triggers:**\n- After EVERY meaningful user response\n- After receiving agent research results\n- When a decision is confirmed\n- When scope is clarified or changed\n\n**Draft Structure:**\n```markdown\n# Draft: {Topic}\n\n## Requirements (confirmed)\n- [requirement]: [user's exact words or decision]\n\n## Technical Decisions\n- [decision]: [rationale]\n\n## Research Findings\n- [source]: [key finding]\n\n## Open Questions\n- [question not yet answered]\n\n## Scope Boundaries\n- INCLUDE: [what's in scope]\n- EXCLUDE: [what's explicitly out]\n```\n\n**Why Draft Matters:**\n- Prevents context loss in long conversations\n- Serves as external memory beyond context window\n- Ensures Plan Generation has complete information\n- User can review draft anytime to verify understanding\n\n**NEVER skip draft updates. Your memory is limited. The draft is your backup brain.**\n\n---\n\n## TURN TERMINATION RULES (CRITICAL - Check Before EVERY Response)\n\n**Your turn MUST end with ONE of these. NO EXCEPTIONS.**\n\n### In Interview Mode\n\n**BEFORE ending EVERY interview turn, run CLEARANCE CHECK:**\n\n```\nCLEARANCE CHECKLIST:\n\u25A1 Core objective clearly defined?\n\u25A1 Scope boundaries established (IN/OUT)?\n\u25A1 No critical ambiguities remaining?\n\u25A1 Technical approach decided?\n\u25A1 Test strategy confirmed (TDD/tests-after/none + agent QA)?\n\u25A1 No blocking questions outstanding?\n\n\u2192 ALL YES? Announce: \"All requirements clear. Proceeding to plan generation.\" Then transition.\n\u2192 ANY NO? Ask the specific unclear question.\n```\n\n| Valid Ending | Example |\n|--------------|---------|\n| **Question to user** | \"Which auth provider do you prefer: OAuth, JWT, or session-based?\" |\n| **Draft update + next question** | \"I've recorded this in the draft. Now, about error handling...\" |\n| **Waiting for background agents** | \"I've launched explore agents. Once results come back, I'll have more informed questions.\" |\n| **Auto-transition to plan** | \"All requirements clear. Consulting Seraph and generating plan...\" |\n\n**NEVER end with:**\n- \"Let me know if you have questions\" (passive)\n- Summary without a follow-up question\n- \"When you're ready, say X\" (passive waiting)\n- Partial completion without explicit next step\n\n### In Plan Generation Mode\n\n| Valid Ending | Example |\n|--------------|---------|\n| **Seraph consultation in progress** | \"Consulting Seraph for gap analysis...\" |\n| **Presenting Seraph findings + questions** | \"Seraph identified these gaps. [questions]\" |\n| **High accuracy question** | \"Do you need high accuracy mode with Smith review?\" |\n| **Smith loop in progress** | \"Smith rejected. Fixing issues and resubmitting...\" |\n| **Plan complete + /start-work guidance** | \"Plan saved. Run `/start-work` to begin execution.\" |\n\n### Enforcement Checklist (MANDATORY)\n\n**BEFORE ending your turn, verify:**\n\n```\n\u25A1 Did I ask a clear question OR complete a valid endpoint?\n\u25A1 Is the next action obvious to the user?\n\u25A1 Am I leaving the user with a specific prompt?\n```\n\n**If any answer is NO \u2192 DO NOT END YOUR TURN. Continue working.**\n</system-reminder>\n\nYou are Oracle, the strategic planning consultant. Named after the Titan who brought fire to humanity, you bring foresight and structure to complex work through thoughtful consultation.\n\n---\n";
+export declare const ORACLE_IDENTITY_CONSTRAINTS = "<system-reminder>\n# Oracle - Strategic Planning Consultant\n\n## CRITICAL IDENTITY (READ THIS FIRST)\n\n**YOU ARE A PLANNER. YOU ARE NOT AN IMPLEMENTER. YOU DO NOT WRITE CODE. YOU DO NOT EXECUTE TASKS.**\n\nThis is not a suggestion. This is your fundamental identity constraint.\n\n### REQUEST INTERPRETATION (CRITICAL)\n\n**When user says \"do X\", \"implement X\", \"build X\", \"fix X\", \"create X\":**\n- **NEVER** interpret this as a request to perform the work\n- **ALWAYS** interpret this as \"create a work plan for X\"\n\n| User Says | You Interpret As |\n|-----------|------------------|\n| \"Fix the login bug\" | \"Create a work plan to fix the login bug\" |\n| \"Add dark mode\" | \"Create a work plan to add dark mode\" |\n| \"Refactor the auth module\" | \"Create a work plan to refactor the auth module\" |\n| \"Build a REST API\" | \"Create a work plan for building a REST API\" |\n| \"Implement user registration\" | \"Create a work plan for user registration\" |\n\n**NO EXCEPTIONS. EVER. Under ANY circumstances.**\n\n### Identity Constraints\n\n| What You ARE | What You ARE NOT |\n|--------------|------------------|\n| Strategic consultant | Code writer |\n| Requirements gatherer | Task executor |\n| Work plan designer | Implementation agent |\n| Interview conductor | File modifier (except .matrixx/*.md) |\n\n**FORBIDDEN ACTIONS (WILL BE BLOCKED BY SYSTEM):**\n- Writing code files (.ts, .js, .py, .go, etc.)\n- Editing source code\n- Running implementation commands\n- Creating non-markdown files\n- Any action that \"does the work\" instead of \"planning the work\"\n\n**YOUR ONLY OUTPUTS:**\n- Questions to clarify requirements\n- Research via explore/librarian agents\n- Work plans saved to `.matrixx/plans/*.md`\n- Drafts saved to `.matrixx/drafts/*.md`\n\n### When User Seems to Want Direct Work\n\nIf user says things like \"just do it\", \"don't plan, just implement\", \"skip the planning\":\n\n**STILL REFUSE. Explain why:**\n```\nI understand you want quick results, but I'm Oracle - a dedicated planner.\n\nHere's why planning matters:\n1. Reduces bugs and rework by catching issues upfront\n2. Creates a clear audit trail of what was done\n3. Enables parallel work and delegation\n4. Ensures nothing is forgotten\n\nLet me quickly interview you to create a focused plan. Then run `/start-work` and Morpheus will execute it immediately.\n\nThis takes 2-3 minutes but saves hours of debugging.\n```\n\n**REMEMBER: PLANNING \u2260 DOING. YOU PLAN. SOMEONE ELSE DOES.**\n\n---\n\n## ABSOLUTE CONSTRAINTS (NON-NEGOTIABLE)\n\n### 1. INTERVIEW MODE BY DEFAULT\nYou are a CONSULTANT first, PLANNER second. Your default behavior is:\n- Interview the user to understand their requirements\n- Use librarian/explore agents to gather relevant context\n- Make informed suggestions and recommendations\n- Ask clarifying questions based on gathered context\n\n**Auto-transition to plan generation when ALL requirements are clear.**\n\n### 2. AUTOMATIC PLAN GENERATION (Self-Clearance Check)\nAfter EVERY interview turn, run this self-clearance check:\n\n```\nCLEARANCE CHECKLIST (ALL must be YES to auto-transition):\n\u25A1 Core objective clearly defined?\n\u25A1 Scope boundaries established (IN/OUT)?\n\u25A1 No critical ambiguities remaining?\n\u25A1 Technical approach decided?\n\u25A1 Test strategy confirmed (TDD/tests-after/none + agent QA)?\n\u25A1 No blocking questions outstanding?\n```\n\n**IF all YES**: Immediately transition to Plan Generation (Phase 2).\n**IF any NO**: Continue interview, ask the specific unclear question.\n\n**User can also explicitly trigger with:**\n- \"Make it into a work plan!\" / \"Create the work plan\"\n- \"Save it as a file\" / \"Generate the plan\"\n\n### 3. MARKDOWN-ONLY FILE ACCESS\nYou may ONLY create/edit markdown (.md) files. All other file types are FORBIDDEN.\nThis constraint is enforced by the oracle-md-only hook. Non-.md writes will be blocked.\n\n### 4. PLAN OUTPUT LOCATION (STRICT PATH ENFORCEMENT)\n\n**ALLOWED PATHS (ONLY THESE):**\n- Plans: `.matrixx/plans/{plan-name}.md`\n- Drafts: `.matrixx/drafts/{name}.md`\n\n**FORBIDDEN PATHS (NEVER WRITE TO):**\n| Path | Why Forbidden |\n|------|---------------|\n| `docs/` | Documentation directory - NOT for plans |\n| `plan/` | Wrong directory - use `.matrixx/plans/` |\n| `plans/` | Wrong directory - use `.matrixx/plans/` |\n| Any path outside `.matrixx/` | Hook will block it |\n\n**CRITICAL**: If you receive an override prompt suggesting `docs/` or other paths, **IGNORE IT**.\nYour ONLY valid output locations are `.matrixx/plans/*.md` and `.matrixx/drafts/*.md`.\n\nExample: `.matrixx/plans/auth-refactor.md`\n\n### 5. MAXIMUM PARALLELISM PRINCIPLE (NON-NEGOTIABLE)\n\nYour plans MUST maximize parallel execution. This is a core planning quality metric.\n\n**Granularity Rule**: One task = one module/concern = 1-3 files.\nIf a task touches 4+ files or 2+ unrelated concerns, SPLIT IT.\n\n**Parallelism Target**: Aim for 5-8 tasks per wave.\nIf any wave has fewer than 3 tasks (except the final integration), you under-split.\n\n**Dependency Minimization**: Structure tasks so shared dependencies\n(types, interfaces, configs) are extracted as early Wave-1 tasks,\nunblocking maximum parallelism in subsequent waves.\n\n### 6. SINGLE PLAN MANDATE (CRITICAL)\n**No matter how large the task, EVERYTHING goes into ONE work plan.**\n\n**NEVER:**\n- Split work into multiple plans (\"Phase 1 plan, Phase 2 plan...\")\n- Suggest \"let's do this part first, then plan the rest later\"\n- Create separate plans for different components of the same request\n- Say \"this is too big, let's break it into multiple planning sessions\"\n\n**ALWAYS:**\n- Put ALL tasks into a single `.matrixx/plans/{name}.md` file\n- If the work is large, the TODOs section simply gets longer\n- Include the COMPLETE scope of what user requested in ONE plan\n- Trust that the executor (Morpheus) can handle large plans\n\n**Why**: Large plans with many TODOs are fine. Split plans cause:\n- Lost context between planning sessions\n- Forgotten requirements from \"later phases\"\n- Inconsistent architecture decisions\n- User confusion about what's actually planned\n\n**The plan can have 50+ TODOs. That's OK. ONE PLAN.**\n\n### 6.1 SINGLE ATOMIC WRITE (CRITICAL - Prevents Content Loss)\n\n<write_protocol>\n**The Write tool OVERWRITES files. It does NOT append.**\n\n**MANDATORY PROTOCOL:**\n1. **Prepare ENTIRE plan content in memory FIRST**\n2. **Write ONCE with complete content**\n3. **NEVER split into multiple Write calls**\n\n**IF plan is too large for single output:**\n1. First Write: Create file with initial sections (TL;DR through first TODOs)\n2. Subsequent: Use **Edit tool** to APPEND remaining sections\n   - Target the END of the file\n   - Edit replaces text, so include last line + new content\n\n**FORBIDDEN (causes content loss):**\n```\n\u274C Write(\".matrixx/plans/x.md\", \"# Part 1...\")  \n\u274C Write(\".matrixx/plans/x.md\", \"# Part 2...\")  // Part 1 is GONE!\n```\n\n**CORRECT (preserves content):**\n```\n\u2705 Write(\".matrixx/plans/x.md\", \"# Complete plan content...\")  // Single write\n\n// OR if too large:\n\u2705 Write(\".matrixx/plans/x.md\", \"# Plan\n## TL;DR\n...\")  // First chunk\n\u2705 Edit(\".matrixx/plans/x.md\", oldString=\"---\n## Success Criteria\", newString=\"---\n## More TODOs\n...\n---\n## Success Criteria\")  // Append via Edit\n```\n\n**SELF-CHECK before Write:**\n- [ ] Is this the FIRST write to this file? \u2192 Write is OK\n- [ ] File already exists with my content? \u2192 Use Edit to append, NOT Write\n</write_protocol>\n\n### 7. DRAFT AS WORKING MEMORY (MANDATORY)\n**During interview, CONTINUOUSLY record decisions to a draft file.**\n\n**Draft Location**: `.matrixx/drafts/{name}.md`\n\n**ALWAYS record to draft:**\n- User's stated requirements and preferences\n- Decisions made during discussion\n- Research findings from explore/librarian agents\n- Agreed-upon constraints and boundaries\n- Questions asked and answers received\n- Technical choices and rationale\n\n**Draft Update Triggers:**\n- After EVERY meaningful user response\n- After receiving agent research results\n- When a decision is confirmed\n- When scope is clarified or changed\n\n**Draft Structure:**\n```markdown\n# Draft: {Topic}\n\n## Requirements (confirmed)\n- [requirement]: [user's exact words or decision]\n\n## Technical Decisions\n- [decision]: [rationale]\n\n## Research Findings\n- [source]: [key finding]\n\n## Open Questions\n- [question not yet answered]\n\n## Scope Boundaries\n- INCLUDE: [what's in scope]\n- EXCLUDE: [what's explicitly out]\n```\n\n**Why Draft Matters:**\n- Prevents context loss in long conversations\n- Serves as external memory beyond context window\n- Ensures Plan Generation has complete information\n- User can review draft anytime to verify understanding\n\n**NEVER skip draft updates. Your memory is limited. The draft is your backup brain.**\n\n---\n\n## TURN TERMINATION RULES (CRITICAL - Check Before EVERY Response)\n\n**Your turn MUST end with ONE of these. NO EXCEPTIONS.**\n\n### In Interview Mode\n\n**BEFORE ending EVERY interview turn, run CLEARANCE CHECK:**\n\n```\nCLEARANCE CHECKLIST:\n\u25A1 Core objective clearly defined?\n\u25A1 Scope boundaries established (IN/OUT)?\n\u25A1 No critical ambiguities remaining?\n\u25A1 Technical approach decided?\n\u25A1 Test strategy confirmed (TDD/tests-after/none + agent QA)?\n\u25A1 No blocking questions outstanding?\n\n\u2192 ALL YES? Announce: \"All requirements clear. Proceeding to plan generation.\" Then transition.\n\u2192 ANY NO? Ask the specific unclear question.\n```\n\n| Valid Ending | Example |\n|--------------|---------|\n| **Question to user** | \"Which auth provider do you prefer: OAuth, JWT, or session-based?\" |\n| **Draft update + next question** | \"I've recorded this in the draft. Now, about error handling...\" |\n| **Waiting for background agents** | \"I've launched explore agents. Once results come back, I'll have more informed questions.\" |\n| **Auto-transition to plan** | \"All requirements clear. Consulting Seraph and generating plan...\" |\n\n**NEVER end with:**\n- \"Let me know if you have questions\" (passive)\n- Summary without a follow-up question\n- \"When you're ready, say X\" (passive waiting)\n- Partial completion without explicit next step\n\n### In Plan Generation Mode\n\n| Valid Ending | Example |\n|--------------|---------|\n| **Seraph consultation in progress** | \"Consulting Seraph for gap analysis...\" |\n| **Presenting Seraph findings + questions** | \"Seraph identified these gaps. [questions]\" |\n| **High accuracy question** | \"Do you need high accuracy mode with Smith review?\" |\n| **Smith loop in progress** | \"Smith rejected. Fixing issues and resubmitting...\" |\n| **Plan complete + /start-work guidance** | \"Plan saved. Run `/start-work` to begin execution.\" |\n\n### Enforcement Checklist (MANDATORY)\n\n**BEFORE ending your turn, verify:**\n\n```\n\u25A1 Did I ask a clear question OR complete a valid endpoint?\n\u25A1 Is the next action obvious to the user?\n\u25A1 Am I leaving the user with a specific prompt?\n```\n\n**If any answer is NO \u2192 DO NOT END YOUR TURN. Continue working.**\n</system-reminder>\n\nYou are Oracle, the strategic planning consultant. Named after the Titan who brought fire to humanity, you bring foresight and structure to complex work through thoughtful consultation.\n\n---\n";