opencode-matrixx 0.0.1

package/LICENSE.md

@@ -0,0 +1,82 @@
+# License
+
+Portions of this software are licensed as follows:
+
+- All third party components incorporated into the Matrixx Software are licensed under the original license
+  provided by the owner of the applicable component.
+- Content outside of the above mentioned files or restrictions is available under the "Sustainable Use
+  License" as defined below.
+
+## Sustainable Use License
+
+Version 1.0
+
+### Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+### Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license
+to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject
+to the limitations below.
+
+### Limitations
+
+You may use or modify the software only for your own internal business purposes or for non-commercial or
+personal use. You may distribute the software or provide it to others only if you do so free of charge for
+non-commercial purposes. You may not alter, remove, or obscure any licensing, copyright, or other notices of
+the licensor in the software. Any use of the licensor's trademarks is subject to applicable law.
+
+### Patents
+
+The licensor grants you a license, under any patent claims the licensor can license, or becomes able to
+license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case
+subject to the limitations and conditions in this license. This license does not cover any patent claims that
+you cause to be infringed by modifications or additions to the software. If you or your company make any
+written claim that the software infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company makes such a claim, your patent
+license ends immediately for work on behalf of your company.
+
+### Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these
+terms. If you modify the software, you must include in any modified copies of the software a prominent notice
+stating that you have modified the software.
+
+### No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+### Termination
+
+If you use the software in violation of these terms, such use is not licensed, and your license will
+automatically terminate. If the licensor provides you with a notice of your violation, and you cease all
+violation of this license no later than 30 days after you receive that notice, your license will be reinstated
+retroactively. However, if you violate these terms after such reinstatement, any additional violation of these
+terms will cause your license to terminate automatically and permanently.
+
+### No Liability
+
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will
+not be liable to you for any damages arising out of these terms or the use or nature of the software, under
+any kind of legal claim.
+
+### Definitions
+
+The "licensor" is the entity offering these terms.
+
+The "software" is the software the licensor makes available under these terms, including any portion of it.
+
+"You" refers to the individual or entity agreeing to these terms.
+
+"Your company" is any legal entity, sole proprietorship, or other kind of organization that you work for, plus
+all organizations that have control over, are under the control of, or are under common control with that
+organization. Control means ownership of substantially all the assets of an entity, or the power to direct its
+management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+"Your license" is the license granted to you for the software under these terms.
+
+"Use" means anything you do with the software requiring your license.
+
+"Trademark" means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,222 @@
+>
+> [![Welcome to the Matrix!](./.github/assets/orchestrator-architect.png?v=3)](https://github.com/klpanagi/matrixx)
+>
+> Matrixx is **highly inspired by** [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) — the project that pioneered the "oh-my-zsh for OpenCode" concept.
+> Full credit to [code-yeongyu](https://github.com/code-yeongyu) for the original vision.
+>
+
+<div align="center">
+
+<h1>Matrixx</h1>
+
+**Multi-model agent orchestration for [OpenCode](https://github.com/sst/opencode).**<br/>
+**12 specialized agents. 41 lifecycle hooks. 25+ tools. One plugin.**
+
+*Use your existing ChatGPT, Claude, and Gemini subscriptions. OpenCode covers them all.*
+
+</div>
+
+---
+
+> *This is coding on steroids. Run background agents, delegate to specialists, refactor with LSP precision, and search the entire open-source ecosystem — all from your terminal.*
+
+---
+
+## Why Matrixx?
+
+[OpenCode](https://github.com/sst/opencode) is the most powerful open-source AI coding agent — endlessly extensible, zero screen flicker, mix-and-match models. But raw power needs direction.
+
+Matrixx turns a single agent into a **coordinated team** — each model doing what it does best, in parallel, with full context awareness. No more one-model-does-everything. No more context window bloat. No more agents that quit halfway.
+
+| Problem | Matrixx Solution |
+|---------|------------------|
+| One model does everything poorly | **12 specialists** — right model for the right job |
+| Agent forgets what it was doing | **Todo Continuation** — forces completion, no exceptions |
+| Slow sequential tool calls | **Parallel background agents** — 5+ running simultaneously |
+| AI-generated code looks like AI | **Comment Checker** — code indistinguishable from human-written |
+| Context window fills up fast | **Aggressive delegation** — subagents carry the load |
+| Fragile refactoring | **LSP + AST-Grep** — deterministic, safe, surgical |
+
+---
+
+## The Magic Word
+
+**Don't want to read docs? Just type `ultrawork` (or `ulw`) in your prompt.**
+
+That's it. Parallel agents, background tasks, deep exploration, relentless execution until completion. The agent figures out the rest.
+
+---
+
+## The Agent Team
+
+<table>
+<tr>
+<td width="50%">
+
+### Morpheus — *The Orchestrator*
+<img src=".github/assets/morpheus.png" width="120" align="right"/>
+
+**Claude Opus 4.6** &middot; Primary agent
+
+Plans, delegates, and executes. Fires background agents in parallel, leverages LSP for surgical refactoring, and never stops until the TODO list is empty.
+
+</td>
+<td width="50%">
+
+### Keymaker — *The Craftsman*
+<img src=".github/assets/keymaker.png" width="120" align="right"/>
+
+**GPT 5.3 Codex** &middot; Autonomous deep worker
+
+Give him a goal, not a recipe. Explores the codebase, matches your patterns, and delivers end-to-end. Inspired by [AmpCode's deep mode](https://ampcode.com).
+
+</td>
+</tr>
+<tr>
+<td>
+
+### Cipher — *The Language Architect*
+<img src=".github/assets/cipher.png" width="120" align="right"/>
+
+**Claude Opus 4.6** &middot; DSL specialist
+
+Grammars, parsers, type systems, code generators, metamodels. 11 composable skills covering textX, ANTLR4, tree-sitter, PyEcore, and more.
+
+</td>
+<td>
+
+### Niobe — *The Research Navigator*
+<img src=".github/assets/niobe.png" width="120" align="right"/>
+
+**Claude Opus 4.6** &middot; Research & technical leadership
+
+Academic papers, EU proposals, systematic reviews, project management, IP exploitation. 12 composable skills covering the full research lifecycle.
+
+</td>
+</tr>
+<tr>
+<td colspan="2">
+
+### Sentinel — *The Security Auditor*
+<img src=".github/assets/sentinel.png" width="120" align="right"/>
+
+**Claude Opus 4.6** &middot; Read-only security specialist
+
+Scans for vulnerabilities but never touches code. OWASP Top 10, SAST, DAST, dependency CVEs, secret detection, crypto audit, infrastructure hardening. 9 composable skills any agent can load.
+
+</td>
+</tr>
+</table>
+
+| Agent | Role | Model |
+|-------|------|-------|
+| **Oracle** | Strategic planning with interview mode | Claude Opus 4.6 |
+| **Merovingian** | Architecture decisions & debugging | GPT 5.2 |
+| **Architect** | Plan execution orchestrator | Kimi K2.5 (free) |
+| **Seraph** | Pre-planning analysis | Claude Opus 4.6 |
+| **Smith** | Plan validation & review | GPT 5.2 |
+| **Operator** | Documentation & OSS search | GLM 4.7 |
+| **Trinity** | Blazing fast codebase grep | Grok Code Fast |
+| **Construct** | PDF, image & diagram analysis | Kimi K2.5 (free) |
+
+Every agent, model, temperature, and permission is fully customizable. [**Meet the full team &rarr;**](docs/agents.md)
+
+---
+
+## Features at a Glance
+
+| | |
+|---|---|
+| **Agent Orchestration** | 12 agents, parallel background execution, category-based routing, session continuity |
+| **Developer Tools** | LSP (goto def, rename, diagnostics), AST-Grep (search & replace), Tmux terminal |
+| **41 Lifecycle Hooks** | Context injection, think mode, comment checking, todo enforcement, error recovery |
+| **36 Built-in Skills** | DSL engineering (11), research & leadership (12), security (9), browser, git, frontend |
+| **Curated MCPs** | Exa (web search), Context7 (official docs), Grep.app (GitHub code search), Document Reader (office docs) |
+| **Claude Code Compat** | Full compatibility — commands, agents, skills, MCPs, hooks from `settings.json` |
+
+[**Full feature list &rarr;**](docs/features.md) &nbsp;&middot;&nbsp; [**Configuration guide &rarr;**](docs/configurations.md) &nbsp;&middot;&nbsp; [**Architecture diagram &rarr;**](docs/agent-architecture.md)
+
+---
+
+## Security
+
+Matrixx includes a three-tier security layer: reactive hooks, configurable policies, and a dedicated security auditing agent.
+
+### Enforcement Hooks
+
+Built-in hooks protect against accidental secret exposure — no setup required.
+
+| Hook | What it does |
+|------|-------------|
+| **Secret Leak Guard** | Intercepts `git commit` and `git push`, runs [gitleaks](https://github.com/gitleaks/gitleaks) on staged changes, and **blocks the operation** if secrets are detected. |
+| **Env File Write Guard** | Blocks agents from writing to sensitive files (`.env`, `*.pem`, `*.key`, `credentials.json`, `id_rsa`, and 16 other patterns). |
+
+Both hooks are **enabled by default** and run before all other hooks in the execution pipeline. Configure via `matrixx.json`:
+
+```jsonc
+{
+  "security": {
+    "secret_scanning": { "enabled": true, "block_on_detection": true },
+    "env_file_guard": { "enabled": true, "allowed_paths": [".env.example"] }
+  }
+}
+```
+
+> **Note:** Secret scanning requires [gitleaks](https://github.com/gitleaks/gitleaks) installed in your PATH. Without it, the hook silently degrades.
+
+### Sentinel — Security Auditing Agent
+
+**Sentinel** is a read-only security specialist with 9 composable skills covering the full application security stack:
+
+| Skill | Domain |
+|-------|--------|
+| `security-core` | OWASP Top 10, CWE classification, threat modeling (STRIDE) |
+| `security-secrets` | Secret detection, credential scanning, pre-commit hooks |
+| `security-sast` | Static analysis, code vulnerability patterns, taint tracking |
+| `security-dast` | Dynamic analysis, runtime testing, fuzzing, penetration testing |
+| `security-dependencies` | CVE scanning, SBOM generation, supply chain security |
+| `security-api` | Authentication, authorization, CORS/CSRF, input validation |
+| `security-crypto` | Encryption audit, key management, TLS, password hashing |
+| `security-infra` | Container scanning, Dockerfile hardening, IaC audit, K8s security |
+| `security-review` | Structured audit reports, severity classification, remediation guidance |
+
+Sentinel never modifies code — it reports findings with CWE IDs, exact locations, and actionable remediation. Any agent can load individual security skills via `load_skills`.
+
+---
+
+## Get Started
+
+**For humans** — paste this into Claude Code, AmpCode, Cursor, or any LLM agent:
+
+```
+Install and configure matrixx by following the instructions here:
+https://raw.githubusercontent.com/klpanagi/matrixx/refs/heads/dev/docs/guide/installation.md
+```
+
+**For LLM agents** — fetch and follow:
+
+```bash
+curl -s https://raw.githubusercontent.com/klpanagi/matrixx/refs/heads/dev/docs/guide/installation.md
+```
+
+We strongly recommend letting an agent handle installation. [Manual guide &rarr;](docs/guide/installation.md) &nbsp;&middot;&nbsp; [Uninstall &rarr;](docs/guide/uninstallation.md)
+
+---
+
+## Documentation
+
+| | |
+|---|---|
+| [Overview](docs/guide/overview.md) | What Matrixx does, workflows, getting started |
+| [Agents Deep Dive](docs/agents.md) | Full agent descriptions, skills, workflows, example prompts |
+| [Architecture](docs/agent-architecture.md) | System diagrams, delegation flows, model routing |
+| [Features](docs/features.md) | Complete feature reference |
+| [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 |
+
+---
+
+**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.
+
+<sub>Productivity might spike too hard. Don't let your coworker notice. Actually — let's see who wins.</sub>

package/bin/matrixx.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// bin/oh-my-opencode.js
+// Wrapper script that detects platform and spawns the correct binary
+
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { getPlatformPackage, getBinaryPath } from "./platform.js";
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Detect libc family on Linux
+ * @returns {string | null} 'glibc', 'musl', or null if detection fails
+ */
+function getLibcFamily() {
+  if (process.platform !== "linux") {
+    return undefined; // Not needed on non-Linux
+  }
+  
+  try {
+    const detectLibc = require("detect-libc");
+    return detectLibc.familySync();
+  } catch {
+    // detect-libc not available
+    return null;
+  }
+}
+
+function main() {
+  const { platform, arch } = process;
+  const libcFamily = getLibcFamily();
+  
+  // Get platform package name
+  let pkg;
+  try {
+    pkg = getPlatformPackage({ platform, arch, libcFamily });
+  } catch (error) {
+    console.error(`\noh-my-opencode: ${error.message}\n`);
+    process.exit(1);
+  }
+  
+  // Resolve binary path
+  const binRelPath = getBinaryPath(pkg, platform);
+  
+  let binPath;
+  try {
+    binPath = require.resolve(binRelPath);
+  } catch {
+    console.error(`\noh-my-opencode: Platform binary not installed.`);
+    console.error(`\nYour platform: ${platform}-${arch}${libcFamily === "musl" ? "-musl" : ""}`);
+    console.error(`Expected package: ${pkg}`);
+    console.error(`\nTo fix, run:`);
+    console.error(`  npm install ${pkg}\n`);
+    process.exit(1);
+  }
+  
+  // Spawn the binary
+  const result = spawnSync(binPath, process.argv.slice(2), {
+    stdio: "inherit",
+  });
+  
+  // Handle spawn errors
+  if (result.error) {
+    console.error(`\noh-my-opencode: Failed to execute binary.`);
+    console.error(`Error: ${result.error.message}\n`);
+    process.exit(2);
+  }
+  
+  // Handle signals
+  if (result.signal) {
+    const signalNum = result.signal === "SIGTERM" ? 15 : 
+                      result.signal === "SIGKILL" ? 9 :
+                      result.signal === "SIGINT" ? 2 : 1;
+    process.exit(128 + signalNum);
+  }
+
+  process.exit(result.status ?? 1);
+}
+
+main();

package/bin/platform.js

@@ -0,0 +1,38 @@
+// bin/platform.js
+// Shared platform detection module - used by wrapper and postinstall
+
+/**
+ * Get the platform-specific package name
+ * @param {{ platform: string, arch: string, libcFamily?: string | null }} options
+ * @returns {string} Package name like "opencode-matrixx-darwin-arm64"
+ * @throws {Error} If libc cannot be detected on Linux
+ */
+export function getPlatformPackage({ platform, arch, libcFamily }) {
+  let suffix = "";
+  if (platform === "linux") {
+    if (libcFamily === null || libcFamily === undefined) {
+      throw new Error(
+        "Could not detect libc on Linux. " +
+        "Please ensure detect-libc is installed or report this issue."
+      );
+    }
+    if (libcFamily === "musl") {
+      suffix = "-musl";
+    }
+  }
+  
+  // Map platform names: win32 -> windows (for package name)
+  const os = platform === "win32" ? "windows" : platform;
+  return `opencode-matrixx-${os}-${arch}${suffix}`;
+}
+
+/**
+ * Get the path to the binary within a platform package
+ * @param {string} pkg Package name
+ * @param {string} platform Process platform
+ * @returns {string} Relative path like "opencode-matrixx-darwin-arm64/bin/matrixx"
+ */
+export function getBinaryPath(pkg, platform) {
+  const ext = platform === "win32" ? ".exe" : "";
+  return `${pkg}/bin/matrixx${ext}`;
+}

package/bin/platform.test.ts

@@ -0,0 +1,148 @@
+// bin/platform.test.ts
+import { describe, expect, test } from "bun:test";
+import { getPlatformPackage, getBinaryPath } from "./platform.js";
+
+describe("getPlatformPackage", () => {
+  // #region Darwin platforms
+  test("returns darwin-arm64 for macOS ARM64", () => {
+    // #given macOS ARM64 platform
+    const input = { platform: "darwin", arch: "arm64" };
+
+    // #when getting platform package
+    const result = getPlatformPackage(input);
+
+    // #then returns correct package name
+    expect(result).toBe("opencode-matrixx-darwin-arm64");
+  });
+
+  test("returns darwin-x64 for macOS Intel", () => {
+    // #given macOS x64 platform
+    const input = { platform: "darwin", arch: "x64" };
+
+    // #when getting platform package
+    const result = getPlatformPackage(input);
+
+    // #then returns correct package name
+    expect(result).toBe("opencode-matrixx-darwin-x64");
+  });
+  // #endregion
+
+  // #region Linux glibc platforms
+  test("returns linux-x64 for Linux x64 with glibc", () => {
+    // #given Linux x64 with glibc
+    const input = { platform: "linux", arch: "x64", libcFamily: "glibc" };
+
+    // #when getting platform package
+    const result = getPlatformPackage(input);
+
+    // #then returns correct package name
+    expect(result).toBe("opencode-matrixx-linux-x64");
+  });
+
+  test("returns linux-arm64 for Linux ARM64 with glibc", () => {
+    // #given Linux ARM64 with glibc
+    const input = { platform: "linux", arch: "arm64", libcFamily: "glibc" };
+
+    // #when getting platform package
+    const result = getPlatformPackage(input);
+
+    // #then returns correct package name
+    expect(result).toBe("opencode-matrixx-linux-arm64");
+  });
+  // #endregion
+
+  // #region Linux musl platforms
+  test("returns linux-x64-musl for Alpine x64", () => {
+    // #given Linux x64 with musl (Alpine)
+    const input = { platform: "linux", arch: "x64", libcFamily: "musl" };
+
+    // #when getting platform package
+    const result = getPlatformPackage(input);
+
+    // #then returns correct package name with musl suffix
+    expect(result).toBe("opencode-matrixx-linux-x64-musl");
+  });
+
+  test("returns linux-arm64-musl for Alpine ARM64", () => {
+    // #given Linux ARM64 with musl (Alpine)
+    const input = { platform: "linux", arch: "arm64", libcFamily: "musl" };
+
+    // #when getting platform package
+    const result = getPlatformPackage(input);
+
+    // #then returns correct package name with musl suffix
+    expect(result).toBe("opencode-matrixx-linux-arm64-musl");
+  });
+  // #endregion
+
+  // #region Windows platform
+  test("returns windows-x64 for Windows", () => {
+    // #given Windows x64 platform (win32 is Node's platform name)
+    const input = { platform: "win32", arch: "x64" };
+
+    // #when getting platform package
+    const result = getPlatformPackage(input);
+
+    // #then returns correct package name with 'windows' not 'win32'
+    expect(result).toBe("opencode-matrixx-windows-x64");
+  });
+  // #endregion
+
+  // #region Error cases
+  test("throws error for Linux with null libcFamily", () => {
+    // #given Linux platform with null libc detection
+    const input = { platform: "linux", arch: "x64", libcFamily: null };
+
+    // #when getting platform package
+    // #then throws descriptive error
+    expect(() => getPlatformPackage(input)).toThrow("Could not detect libc");
+  });
+
+  test("throws error for Linux with undefined libcFamily", () => {
+    // #given Linux platform with undefined libc
+    const input = { platform: "linux", arch: "x64", libcFamily: undefined };
+
+    // #when getting platform package
+    // #then throws descriptive error
+    expect(() => getPlatformPackage(input)).toThrow("Could not detect libc");
+  });
+  // #endregion
+});
+
+describe("getBinaryPath", () => {
+  test("returns path without .exe for Unix platforms", () => {
+    // #given Unix platform package
+    const pkg = "opencode-matrixx-darwin-arm64";
+    const platform = "darwin";
+
+    // #when getting binary path
+    const result = getBinaryPath(pkg, platform);
+
+    // #then returns path without extension
+    expect(result).toBe("opencode-matrixx-darwin-arm64/bin/matrixx");
+  });
+
+  test("returns path with .exe for Windows", () => {
+    // #given Windows platform package
+    const pkg = "opencode-matrixx-windows-x64";
+    const platform = "win32";
+
+    // #when getting binary path
+    const result = getBinaryPath(pkg, platform);
+
+    // #then returns path with .exe extension
+    expect(result).toBe("opencode-matrixx-windows-x64/bin/matrixx.exe");
+  });
+
+  test("returns path without .exe for Linux", () => {
+    // #given Linux platform package
+    const pkg = "opencode-matrixx-linux-x64";
+    const platform = "linux";
+
+    // #when getting binary path
+    const result = getBinaryPath(pkg, platform);
+
+    // #then returns path without extension
+    expect(result).toBe("opencode-matrixx-linux-x64/bin/matrixx");
+  });
+});

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

@@ -0,0 +1,7 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+import type { AgentFactory } from "./types";
+import type { CategoriesConfig, GitMasterConfig } from "../config/schema";
+import type { BrowserAutomationProvider } from "../config/schema";
+export type AgentSource = AgentFactory | AgentConfig;
+export declare function isFactory(source: AgentSource): source is AgentFactory;
+export declare function buildAgent(source: AgentSource, model: string, categories?: CategoriesConfig, gitMasterConfig?: GitMasterConfig, browserProvider?: BrowserAutomationProvider, disabledSkills?: Set<string>): AgentConfig;

package/dist/agents/architect/agent.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Atlas - Master Orchestrator Agent
+ *
+ * Orchestrates work via task() to complete ALL tasks in a todo list until fully done.
+ * You are the conductor of a symphony of specialized agents.
+ *
+ * Routing:
+ * 1. GPT models (openai/*, github-copilot/gpt-*) → gpt.ts (GPT-5.2 optimized)
+ * 2. Default (Claude, etc.) → default.ts (Claude-optimized)
+ */
+import type { AgentConfig } from "@opencode-ai/sdk";
+import type { AgentPromptMetadata } from "../types";
+import type { AvailableAgent, AvailableSkill } from "../dynamic-agent-prompt-builder";
+import type { CategoryConfig } from "../../config/schema";
+export type AtlasPromptSource = "default" | "gpt";
+/**
+ * Determines which Atlas prompt to use based on model.
+ */
+export declare function getAtlasPromptSource(model?: string): AtlasPromptSource;
+export interface OrchestratorContext {
+    model?: string;
+    availableAgents?: AvailableAgent[];
+    availableSkills?: AvailableSkill[];
+    userCategories?: Record<string, CategoryConfig>;
+}
+/**
+ * Gets the appropriate Atlas prompt based on model.
+ */
+export declare function getAtlasPrompt(model?: string): string;
+export declare function createAtlasAgent(ctx: OrchestratorContext): AgentConfig;
+export declare namespace createAtlasAgent {
+    var mode: "primary";
+}
+export declare const atlasPromptMetadata: AgentPromptMetadata;

package/dist/agents/architect/default.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Default Atlas system prompt optimized for Claude series models.
+ *
+ * Key characteristics:
+ * - Optimized for Claude's tendency to be "helpful" by forcing explicit delegation
+ * - Strong emphasis on verification and QA protocols
+ * - Detailed workflow steps with narrative context
+ * - Extended reasoning sections
+ */
+export declare const ATLAS_SYSTEM_PROMPT = "\n<identity>\nYou are Atlas - the Master Orchestrator from Matrixx.\n\nIn Greek mythology, Atlas holds up the celestial heavens. You hold up the entire workflow - coordinating every agent, every task, every verification until completion.\n\nYou are a conductor, not a musician. A general, not a soldier. You DELEGATE, COORDINATE, and VERIFY.\nYou never write code yourself. You orchestrate specialists who do.\n</identity>\n\n<mission>\nComplete ALL tasks in a work plan via `task()` until fully done.\nOne task per delegation. Parallel when independent. Verify everything.\n</mission>\n\n<delegation_system>\n## How to Delegate\n\nUse `task()` with EITHER category OR agent (mutually exclusive):\n\n```typescript\n// Option A: Category + Skills (spawns Mouse with domain config)\ntask(\n  category=\"[category-name]\",\n  load_skills=[\"skill-1\", \"skill-2\"],\n  run_in_background=false,\n  prompt=\"...\"\n)\n\n// Option B: Specialized Agent (for specific expert tasks)\ntask(\n  subagent_type=\"[agent-name]\",\n  load_skills=[],\n  run_in_background=false,\n  prompt=\"...\"\n)\n```\n\n{CATEGORY_SECTION}\n\n{AGENT_SECTION}\n\n{DECISION_MATRIX}\n\n{SKILLS_SECTION}\n\n{{CATEGORY_SKILLS_DELEGATION_GUIDE}}\n\n## 6-Section Prompt Structure (MANDATORY)\n\nEvery `task()` prompt MUST include ALL 6 sections:\n\n```markdown\n## 1. TASK\n[Quote EXACT checkbox item. Be obsessively specific.]\n\n## 2. EXPECTED OUTCOME\n- [ ] Files created/modified: [exact paths]\n- [ ] Functionality: [exact behavior]\n- [ ] Verification: `[command]` passes\n\n## 3. REQUIRED TOOLS\n- [tool]: [what to search/check]\n- context7: Look up [library] docs\n- ast-grep: `sg --pattern '[pattern]' --lang [lang]`\n\n## 4. MUST DO\n- Follow pattern in [reference file:lines]\n- Write tests for [specific cases]\n- Append findings to notepad (never overwrite)\n\n## 5. MUST NOT DO\n- Do NOT modify files outside [scope]\n- Do NOT add dependencies\n- Do NOT skip verification\n\n## 6. CONTEXT\n### Notepad Paths\n- READ: .matrix/notepads/{plan-name}/*.md\n- WRITE: Append to appropriate category\n\n### Inherited Wisdom\n[From notepad - conventions, gotchas, decisions]\n\n### Dependencies\n[What previous tasks built]\n```\n\n**If your prompt is under 30 lines, it's TOO SHORT.**\n</delegation_system>\n\n<workflow>\n## Step 0: Register Tracking\n\n```\nTodoWrite([{\n  id: \"orchestrate-plan\",\n  content: \"Complete ALL tasks in work plan\",\n  status: \"in_progress\",\n  priority: \"high\"\n}])\n```\n\n## Step 1: Analyze Plan\n\n1. Read the todo list file\n2. Parse incomplete checkboxes `- [ ]`\n3. Extract parallelizability info from each task\n4. Build parallelization map:\n   - Which tasks can run simultaneously?\n   - Which have dependencies?\n   - Which have file conflicts?\n\nOutput:\n```\nTASK ANALYSIS:\n- Total: [N], Remaining: [M]\n- Parallelizable Groups: [list]\n- Sequential Dependencies: [list]\n```\n\n## Step 2: Initialize Notepad\n\n```bash\nmkdir -p .matrix/notepads/{plan-name}\n```\n\nStructure:\n```\n.matrix/notepads/{plan-name}/\n  learnings.md    # Conventions, patterns\n  decisions.md    # Architectural choices\n  issues.md       # Problems, gotchas\n  problems.md     # Unresolved blockers\n```\n\n## Step 3: Execute Tasks\n\n### 3.1 Check Parallelization\nIf tasks can run in parallel:\n- Prepare prompts for ALL parallelizable tasks\n- Invoke multiple `task()` in ONE message\n- Wait for all to complete\n- Verify all, then continue\n\nIf sequential:\n- Process one at a time\n\n### 3.2 Before Each Delegation\n\n**MANDATORY: Read notepad first**\n```\nglob(\".matrix/notepads/{plan-name}/*.md\")\nRead(\".matrix/notepads/{plan-name}/learnings.md\")\nRead(\".matrix/notepads/{plan-name}/issues.md\")\n```\n\nExtract wisdom and include in prompt.\n\n### 3.3 Invoke task()\n\n```typescript\ntask(\n  category=\"[category]\",\n  load_skills=[\"[relevant-skills]\"],\n  run_in_background=false,\n  prompt=`[FULL 6-SECTION PROMPT]`\n)\n```\n\n### 3.4 Verify (MANDATORY \u2014 EVERY SINGLE DELEGATION)\n\n**You are the QA gate. Subagents lie. Automated checks alone are NOT enough.**\n\nAfter EVERY delegation, complete ALL of these steps \u2014 no shortcuts:\n\n#### A. Automated Verification\n1. `lsp_diagnostics(filePath=\".\")` \u2192 ZERO errors at project level\n2. `bun run build` or `bun run typecheck` \u2192 exit code 0\n3. `bun test` \u2192 ALL tests pass\n\n#### B. Manual Code Review (NON-NEGOTIABLE \u2014 DO NOT SKIP)\n\n**This is the step you are most tempted to skip. DO NOT SKIP IT.**\n\n1. `Read` EVERY file the subagent created or modified \u2014 no exceptions\n2. For EACH file, check line by line:\n   - Does the logic actually implement the task requirement?\n   - Are there stubs, TODOs, placeholders, or hardcoded values?\n   - Are there logic errors or missing edge cases?\n   - Does it follow the existing codebase patterns?\n   - Are imports correct and complete?\n3. Cross-reference: compare what subagent CLAIMED vs what the code ACTUALLY does\n4. If anything doesn't match \u2192 resume session and fix immediately\n\n**If you cannot explain what the changed code does, you have not reviewed it.**\n\n#### C. Hands-On QA (if applicable)\n| Deliverable | Method | Tool |\n|-------------|--------|------|\n| Frontend/UI | Browser | `/playwright` |\n| TUI/CLI | Interactive | `interactive_bash` |\n| API/Backend | Real requests | curl |\n\n#### D. Check Mission State Directly\n\nAfter verification, READ the plan file directly \u2014 every time, no exceptions:\n```\nRead(\".matrix/tasks/{plan-name}.yaml\")\n```\nCount remaining `- [ ]` tasks. This is your ground truth for what comes next.\n\n**Checklist (ALL must be checked):**\n```\n[ ] Automated: lsp_diagnostics clean, build passes, tests pass\n[ ] Manual: Read EVERY changed file, verified logic matches requirements\n[ ] Cross-check: Subagent claims match actual code\n[ ] Mission: Read plan file, confirmed current progress\n```\n\n**If verification fails**: Resume the SAME session with the ACTUAL error output:\n```typescript\ntask(\n  session_id=\"ses_xyz789\",  // ALWAYS use the session from the failed task\n  load_skills=[...],\n  prompt=\"Verification failed: {actual error}. Fix.\"\n)\n```\n\n### 3.5 Handle Failures (USE RESUME)\n\n**CRITICAL: When re-delegating, ALWAYS use `session_id` parameter.**\n\nEvery `task()` output includes a session_id. STORE IT.\n\nIf task fails:\n1. Identify what went wrong\n2. **Resume the SAME session** - subagent has full context already:\n    ```typescript\n    task(\n      session_id=\"ses_xyz789\",  // Session from failed task\n      load_skills=[...],\n      prompt=\"FAILED: {error}. Fix by: {specific instruction}\"\n    )\n    ```\n3. Maximum 3 retry attempts with the SAME session\n4. If blocked after 3 attempts: Document and continue to independent tasks\n\n**Why session_id is MANDATORY for failures:**\n- Subagent already read all files, knows the context\n- No repeated exploration = 70%+ token savings\n- Subagent knows what approaches already failed\n- Preserves accumulated knowledge from the attempt\n\n**NEVER start fresh on failures** - that's like asking someone to redo work while wiping their memory.\n\n### 3.6 Loop Until Done\n\nRepeat Step 3 until all tasks complete.\n\n## Step 4: Final Report\n\n```\nORCHESTRATION COMPLETE\n\nTODO LIST: [path]\nCOMPLETED: [N/N]\nFAILED: [count]\n\nEXECUTION SUMMARY:\n- Task 1: SUCCESS (category)\n- Task 2: SUCCESS (agent)\n\nFILES MODIFIED:\n[list]\n\nACCUMULATED WISDOM:\n[from notepad]\n```\n</workflow>\n\n<parallel_execution>\n## Parallel Execution Rules\n\n**For exploration (explore/librarian)**: ALWAYS background\n```typescript\ntask(subagent_type=\"trinity\", load_skills=[], run_in_background=true, ...)\ntask(subagent_type=\"operator\", load_skills=[], run_in_background=true, ...)\n```\n\n**For task execution**: NEVER background\n```typescript\ntask(category=\"...\", load_skills=[...], run_in_background=false, ...)\n```\n\n**Parallel task groups**: Invoke multiple in ONE message\n```typescript\n// Tasks 2, 3, 4 are independent - invoke together\ntask(category=\"bullet-time\", load_skills=[], run_in_background=false, prompt=\"Task 2...\")\ntask(category=\"bullet-time\", load_skills=[], run_in_background=false, prompt=\"Task 3...\")\ntask(category=\"bullet-time\", load_skills=[], run_in_background=false, prompt=\"Task 4...\")\n```\n\n**Background management**:\n- Collect results: `background_output(task_id=\"...\")`\n- Before final answer: `background_cancel(all=true)`\n</parallel_execution>\n\n<notepad_protocol>\n## Notepad System\n\n**Purpose**: Subagents are STATELESS. Notepad is your cumulative intelligence.\n\n**Before EVERY delegation**:\n1. Read notepad files\n2. Extract relevant wisdom\n3. Include as \"Inherited Wisdom\" in prompt\n\n**After EVERY completion**:\n- Instruct subagent to append findings (never overwrite, never use Edit tool)\n\n**Format**:\n```markdown\n## [TIMESTAMP] Task: {task-id}\n{content}\n```\n\n**Path convention**:\n- Plan: `.matrix/plans/{name}.md` (READ ONLY)\n- Notepad: `.matrix/notepads/{name}/` (READ/APPEND)\n</notepad_protocol>\n\n<verification_rules>\n## QA Protocol\n\nYou are the QA gate. Subagents lie. Verify EVERYTHING.\n\n**After each delegation \u2014 BOTH automated AND manual verification are MANDATORY:**\n\n1. `lsp_diagnostics` at PROJECT level \u2192 ZERO errors\n2. Run build command \u2192 exit 0\n3. Run test suite \u2192 ALL pass\n4. **`Read` EVERY changed file line by line** \u2192 logic matches requirements\n5. **Cross-check**: subagent's claims vs actual code \u2014 do they match?\n6. **Check mission state**: Read the plan file directly, count remaining tasks\n\n**Evidence required**:\n| Action | Evidence |\n|--------|----------|\n| Code change | lsp_diagnostics clean + manual Read of every changed file |\n| Build | Exit code 0 |\n| Tests | All pass |\n| Logic correct | You read the code and can explain what it does |\n| Mission state | Read plan file, confirmed progress |\n\n**No evidence = not complete. Skipping manual review = rubber-stamping broken work.**\n</verification_rules>\n\n<boundaries>\n## What You Do vs Delegate\n\n**YOU DO**:\n- Read files (for context, verification)\n- Run commands (for verification)\n- Use lsp_diagnostics, grep, glob\n- Manage todos\n- Coordinate and verify\n\n**YOU DELEGATE**:\n- All code writing/editing\n- All bug fixes\n- All test creation\n- All documentation\n- All git operations\n</boundaries>\n\n<critical_overrides>\n## Critical Rules\n\n**NEVER**:\n- Write/edit code yourself - always delegate\n- Trust subagent claims without verification\n- Use run_in_background=true for task execution\n- Send prompts under 30 lines\n- Skip project-level lsp_diagnostics after delegation\n- Batch multiple tasks in one delegation\n- Start fresh session for failures/follow-ups - use `resume` instead\n\n**ALWAYS**:\n- Include ALL 6 sections in delegation prompts\n- Read notepad before every delegation\n- Run project-level QA after every delegation\n- Pass inherited wisdom to every subagent\n- Parallelize independent tasks\n- Verify with your own tools\n- **Store session_id from every delegation output**\n- **Use `session_id=\"{session_id}\"` for retries, fixes, and follow-ups**\n</critical_overrides>\n";
+export declare function getDefaultAtlasPrompt(): string;