open-xmen 0.1.0 → 0.1.2

package/README.md

@@ -130,7 +130,6 @@ open-xmen models
 | `/to-me-my-x-men [task]` | Autonomous full-team mode with Legion + Cypher intent consult and final Legion acceptance. |
 | `/cerebro-doctor` | Validate runtime health. |
 | `/cerebro-reset` | Reset runtime state after confirmation. |
-| `/cerebro-upgrade <ref>` | Gated template sync from an explicit upstream release/ref. |
 
 ---
 
@@ -180,7 +179,6 @@ npx tsc -p tsconfig.json --noEmit
 npm run doctor
 python3 .cerebro/scripts/validate-opencode-runtime.py
 python3 .cerebro/scripts/validate-team-runs.py
-python3 .cerebro/scripts/validate-upgrade-metadata.py
 npm run verify:release
 ```
 
@@ -188,6 +186,12 @@ npm run verify:release
 
 `/cerebro-doctor` runs the same class of checks from inside OpenCode.
 
+## Auto-Upgrades
+
+When the `open-xmen` plugin loads, it checks the npm registry for the latest package version. If a newer package is available and the plugin is running from a package-managed `node_modules/open-xmen` install, it best-effort updates that package and re-runs `open-xmen install --reset --no-deps` for the current project. Results are written to `.cerebro/auto-upgrade.json`; registry or install failures never block OpenCode startup.
+
+Set `OPEN_XMEN_SKIP_AUTO_UPGRADE=1` or `OPEN_XMEN_AUTO_UPGRADE=0` to disable this behavior.
+
 ## Spark Lane
 
 `gpt-5.3-codex-spark` is available as a fast draft lane. Cerebro should use it for instant code generation, boilerplate, test stubs, tiny low-risk diffs, and candidate patches. Full `gpt-5.3-codex` remains the default for Wolverine/Storm final implementation and verification.

package/dist/agents/cerebro.d.ts

@@ -0,0 +1,12 @@
+import { type AgentDefinition } from "./types.js";
+/**
+ * Build the cerebro agent prompt with optional agent filtering.
+ * Pass disabledAgents to exclude specific X-Men roles from the routing section.
+ */
+export declare function buildCerebroPrompt(disabledAgents?: Set<string>): string;
+/** @deprecated Use buildCerebroPrompt() instead */
+export declare const CEREBRO_PROMPT: string;
+export declare function createCerebroAgent(model?: string | Array<string | {
+    id: string;
+    variant?: string;
+}>, customPrompt?: string, customAppendPrompt?: string, disabledAgents?: Set<string>): AgentDefinition;

package/dist/agents/cerebro.js

@@ -0,0 +1,112 @@
+import { resolvePrompt } from "./types.js";
+const AGENT_DESCRIPTIONS = {
+    legion: `@legion
+- Role: Customer/product-owner proxy; owns WANT and final acceptance verdicts
+- Write boundary: \`.cerebro/notepads/customer/\` only; no code edits
+- **Delegate when:** Product vision or quality bar unclear • Customer acceptance verdict needed • Demand-side voice required for user stories
+- **Don't delegate when:** Technical or implementation questions • Requirements already established`,
+    cypher: `@cypher
+- Role: Business analyst; converts intent into requirements, user stories, and acceptance criteria
+- Write boundary: \`.cerebro/notepads/requirements/\` only; no code edits
+- **Delegate when:** Requirements are vague, conflicted, or product-shaped • Scope must be defined before planning begins
+- **Don't delegate when:** Requirements already clear • Work can proceed directly to planning or implementation`,
+    "professor-x": `@professor-x
+- Role: Strategic planner; authors Cerebro plans and product briefs from canonical templates
+- Write boundary: \`.cerebro/notepads/plans/\` (drafts only — Cerebro promotes to \`.cerebro/plans/\`)
+- **Delegate when:** Work is complex, multi-task, or high-risk and needs a structured plan • Product brief needed from requirements
+- **Don't delegate when:** Task is simple or obviously scoped • A clear plan already exists`,
+    cyclops: `@cyclops
+- Role: Field coordinator; sequences tasks, assigns owners, independently verifies worker results
+- Write boundary: Runtime state, task ledgers, and notepads
+- **Delegate when:** Parallel execution needs coordination across multiple workers • Worker claims require independent verification
+- **Don't delegate when:** Single-worker tasks • Cerebro can verify directly`,
+    wolverine: `@wolverine
+- Role: Implementation specialist for code, tests, scripts, and bug fixes
+- Permissions: Read/write files; maintains task-scoped todos under \`.cerebro/pending-todos/\`
+- **Delegate when:** Code implementation, test writing, bug fixes, or scripts • TDD work • Bounded multi-file implementation
+- **Don't delegate when:** Architecture or discovery work must happen first`,
+    storm: `@storm
+- Role: Frontend and visual engineering; UI, accessibility, responsive behavior, and visual polish
+- Permissions: Read/write files; maintains task-scoped todos
+- **Delegate when:** User-facing interfaces • Responsive layouts • Accessibility • Component UX states • Visual polish
+- **Don't delegate when:** Backend-only work • No visual surface involved`,
+    forge: `@forge
+- Role: Architecture consultant; system design, tradeoffs, migration strategy — read-only
+- Permissions: Read files only; no edits
+- **Delegate when:** Major architecture decisions • System-level tradeoffs • Migration approach unclear
+- **Don't delegate when:** Routine implementation within established patterns • Simple decisions`,
+    nightcrawler: `@nightcrawler
+- Role: Fast read-only codebase scout; file search, symbol discovery, and pattern mapping
+- Permissions: Read files; bash search; no edits
+- Stats: Fast and cheap — prefer for parallel discovery before planning or implementation
+- **Delegate when:** Need to find files, symbols, or patterns • Parallel searches across domains • Discovery needed before implementation
+- **Don't delegate when:** Already know the exact path • Single lookup immediately before editing`,
+    sage: `@sage
+- Role: Documentation and ecosystem researcher; official APIs, library behavior, and best practices
+- Permissions: Read files; web fetch allowed; no edits
+- **Delegate when:** Library APIs with frequent changes • Version-specific behavior • External docs needed for correct implementation
+- **Don't delegate when:** Standard usage you're confident about • General programming knowledge`,
+    beast: `@beast
+- Role: Gap analyst and plan/code critic — read-only
+- Permissions: Read files only; no edits
+- **Delegate when:** Plan needs gap review before execution • Missing edge cases or weak verification suspected • Code review for correctness or quality
+- **Don't delegate when:** Implementation work • Clear already-reviewed plans`,
+    "emma-frost": `@emma-frost
+- Role: Strict validator for high-risk, high-accuracy work — read-only
+- Permissions: Read files only; no edits
+- **Delegate when:** HIGH risk plans or approval gates • Auth, billing, migration, data integrity, or public API work • Final validation before irreversible actions
+- **Don't delegate when:** LOW/MEDIUM risk routine work • Already validated`,
+};
+const CEREBRO_RUNTIME_CONTRACT = `## Cerebro Runtime Contract
+
+- Runtime state lives in \`.cerebro/\`.
+- Use Cerebro custom tools for run/task/mailbox/checkpoint state when available.
+- Preserve command names and role names.
+- Do not read \`.env\`, secret, or credential files without explicit user authorization.
+- If assigned implementation or UI work, report with \`TASK_RESULT:\` including \`STATUS:\`, \`FILES CHANGED:\`, \`TESTS RUN:\`, \`VERIFICATION:\`, and \`ISSUES:\`.`;
+/**
+ * Build the cerebro agent prompt with optional agent filtering.
+ * Pass disabledAgents to exclude specific X-Men roles from the routing section.
+ */
+export function buildCerebroPrompt(disabledAgents) {
+    const enabledDescriptions = Object.entries(AGENT_DESCRIPTIONS)
+        .filter(([name]) => !disabledAgents?.has(name))
+        .map(([, desc]) => desc)
+        .join("\n\n");
+    return `# cerebro
+
+You are Cerebro, central intelligence and team lead. Preserve the cinematic Cerebro voice, but operate through OpenCode-native agents, child sessions, and the Cerebro custom tools. For every non-trivial workflow, create a run with cerebro_run_start, create tasks, route work to named agents, checkpoint durable state, verify pending todos, and synthesize only after verification evidence exists.
+
+## Role Routing
+
+${enabledDescriptions}
+
+${CEREBRO_RUNTIME_CONTRACT}`;
+}
+/** @deprecated Use buildCerebroPrompt() instead */
+export const CEREBRO_PROMPT = buildCerebroPrompt();
+export function createCerebroAgent(model, customPrompt, customAppendPrompt, disabledAgents) {
+    const basePrompt = buildCerebroPrompt(disabledAgents);
+    const prompt = resolvePrompt(basePrompt, customPrompt, customAppendPrompt);
+    const definition = {
+        name: "cerebro",
+        displayName: "Cerebro",
+        description: "Cerebro team lead for preserved commands and OpenCode-native orchestration.",
+        config: {
+            temperature: 0.2,
+            prompt,
+        },
+        opencode: {
+            mode: "primary",
+            steps: 60,
+            permission: { edit: "ask", bash: "ask", webfetch: "ask" },
+        },
+    };
+    if (Array.isArray(model)) {
+        definition._modelArray = model.map((m) => (typeof m === "string" ? { id: m } : m));
+    }
+    else if (typeof model === "string" && model) {
+        definition.config.model = model;
+    }
+    return definition;
+}

package/dist/agents/index.d.ts

@@ -0,0 +1,6 @@
+export declare const CEREBRO_AGENTS: readonly ["cerebro", "legion", "cypher", "professor-x", "cyclops", "wolverine", "storm", "forge", "nightcrawler", "sage", "beast", "emma-frost"];
+export type { AgentDefinition, OpenCodeMeta, OpenCodePermissionLevel } from "./types.js";
+export { resolvePrompt } from "./types.js";
+export { toOpenCodeMarkdown } from "./markdown.js";
+export { buildCerebroPrompt, createCerebroAgent, CEREBRO_PROMPT } from "./cerebro.js";
+export { createLegionAgent, createCypherAgent, createProfessorXAgent, createCyclopsAgent, createWolverineAgent, createStormAgent, createForgeAgent, createNightcrawlerAgent, createSageAgent, createBeastAgent, createEmmaFrostAgent, } from "./team.js";

package/dist/agents/index.js

@@ -0,0 +1,18 @@
+export const CEREBRO_AGENTS = [
+    "cerebro",
+    "legion",
+    "cypher",
+    "professor-x",
+    "cyclops",
+    "wolverine",
+    "storm",
+    "forge",
+    "nightcrawler",
+    "sage",
+    "beast",
+    "emma-frost",
+];
+export { resolvePrompt } from "./types.js";
+export { toOpenCodeMarkdown } from "./markdown.js";
+export { buildCerebroPrompt, createCerebroAgent, CEREBRO_PROMPT } from "./cerebro.js";
+export { createLegionAgent, createCypherAgent, createProfessorXAgent, createCyclopsAgent, createWolverineAgent, createStormAgent, createForgeAgent, createNightcrawlerAgent, createSageAgent, createBeastAgent, createEmmaFrostAgent, } from "./team.js";

package/dist/agents/markdown.d.ts

@@ -0,0 +1,6 @@
+import type { AgentDefinition } from "./types.js";
+/**
+ * Convert an AgentDefinition into an OpenCode agent markdown file
+ * (YAML frontmatter + prompt body).
+ */
+export declare function toOpenCodeMarkdown(definition: AgentDefinition): string;

package/dist/agents/markdown.js

@@ -0,0 +1,27 @@
+/**
+ * Convert an AgentDefinition into an OpenCode agent markdown file
+ * (YAML frontmatter + prompt body).
+ */
+export function toOpenCodeMarkdown(definition) {
+    const { config, description, opencode } = definition;
+    const meta = opencode ?? {};
+    const lines = ["---"];
+    if (description)
+        lines.push(`description: ${description}`);
+    if (meta.mode)
+        lines.push(`mode: ${meta.mode}`);
+    if (config.model)
+        lines.push(`model: ${config.model}`);
+    if (config.temperature !== undefined)
+        lines.push(`temperature: ${config.temperature}`);
+    if (meta.steps !== undefined)
+        lines.push(`steps: ${meta.steps}`);
+    if (meta.permission) {
+        lines.push("permission:");
+        for (const [key, value] of Object.entries(meta.permission)) {
+            lines.push(`  ${key}: ${value}`);
+        }
+    }
+    lines.push("---");
+    return `${lines.join("\n")}\n${config.prompt ?? ""}`;
+}

package/dist/agents/team.d.ts

@@ -0,0 +1,45 @@
+import { type AgentDefinition } from "./types.js";
+export declare function createLegionAgent(model?: string | Array<string | {
+    id: string;
+    variant?: string;
+}>, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;
+export declare function createCypherAgent(model?: string | Array<string | {
+    id: string;
+    variant?: string;
+}>, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;
+export declare function createProfessorXAgent(model?: string | Array<string | {
+    id: string;
+    variant?: string;
+}>, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;
+export declare function createCyclopsAgent(model?: string | Array<string | {
+    id: string;
+    variant?: string;
+}>, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;
+export declare function createWolverineAgent(model?: string | Array<string | {
+    id: string;
+    variant?: string;
+}>, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;
+export declare function createStormAgent(model?: string | Array<string | {
+    id: string;
+    variant?: string;
+}>, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;
+export declare function createForgeAgent(model?: string | Array<string | {
+    id: string;
+    variant?: string;
+}>, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;
+export declare function createNightcrawlerAgent(model?: string | Array<string | {
+    id: string;
+    variant?: string;
+}>, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;
+export declare function createSageAgent(model?: string | Array<string | {
+    id: string;
+    variant?: string;
+}>, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;
+export declare function createBeastAgent(model?: string | Array<string | {
+    id: string;
+    variant?: string;
+}>, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;
+export declare function createEmmaFrostAgent(model?: string | Array<string | {
+    id: string;
+    variant?: string;
+}>, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;

package/dist/agents/team.js

@@ -0,0 +1,255 @@
+import { resolvePrompt } from "./types.js";
+const CEREBRO_RUNTIME_CONTRACT = `## Cerebro Runtime Contract
+
+- Runtime state lives in \`.cerebro/\`.
+- Use Cerebro custom tools for run/task/mailbox/checkpoint state when available.
+- Preserve command names and role names.
+- Do not read \`.env\`, secret, or credential files without explicit user authorization.
+- If assigned implementation or UI work, report with \`TASK_RESULT:\` including \`STATUS:\`, \`FILES CHANGED:\`, \`TESTS RUN:\`, \`VERIFICATION:\`, and \`ISSUES:\`.`;
+const TASK_RESULT_CONTRACT = `## Output Contract
+
+Return exactly one final result block:
+
+\`\`\`text
+TASK_RESULT:
+STATUS: completed | blocked | failed
+TASK: [task id/name]
+SUMMARY: [what changed]
+FILES CHANGED:
+- [path]
+TESTS RUN:
+- [command or NOT RUN with reason]
+VERIFICATION:
+- [evidence]
+ISSUES:
+- [remaining issue or NONE]
+\`\`\``;
+const DEFAULT_OPENCODE_META = {
+    mode: "subagent",
+    steps: 60,
+    permission: { edit: "ask", bash: "ask", webfetch: "ask" },
+};
+function makeAgent(name, displayName, description, basePrompt, defaultModel, opencode, model, customPrompt, customAppendPrompt) {
+    const prompt = resolvePrompt(basePrompt, customPrompt, customAppendPrompt);
+    const definition = {
+        name,
+        displayName,
+        description,
+        config: { temperature: 0.2, prompt },
+        opencode,
+    };
+    if (Array.isArray(model)) {
+        definition._modelArray = model.map((m) => (typeof m === "string" ? { id: m } : m));
+    }
+    else if (typeof model === "string" && model) {
+        definition.config.model = model;
+    }
+    else {
+        definition.config.model = defaultModel;
+    }
+    return definition;
+}
+// ─── Legion ─────────────────────────────────────────────────────────────────
+const LEGION_PROMPT = `# legion
+
+You are Legion, the demanding customer proxy. Own WANT and JUDGMENT, not implementation. Produce customer visions and acceptance verdicts under .cerebro/notepads/customer/ when asked. Be concrete, opinionated, and unwilling to accept generic work.
+
+## Output Contracts
+
+When asked for customer vision, return:
+
+\`\`\`text
+CUSTOMER_VISION_READY
+WANT: [plain-language desired outcome]
+QUALITY BAR: [one-line standard that would make the result feel excellent]
+NON-NEGOTIABLES:
+- [must-have]
+ANTI-GOALS:
+- [what would disappoint the customer]
+\`\`\`
+
+When asked for acceptance, return:
+
+\`\`\`text
+CUSTOMER_VERDICT: ACCEPT | REJECT
+WOULD I USE THIS?: YES | NO
+REASON: [specific demand-side reason]
+NEXT DEMAND: [single most important improvement, or NONE]
+\`\`\`
+
+${CEREBRO_RUNTIME_CONTRACT}`;
+export function createLegionAgent(model, customPrompt, customAppendPrompt) {
+    return makeAgent("legion", "Legion", "Customer/product-owner proxy for opinionated demand-side vision and acceptance.", LEGION_PROMPT, "openai/gpt-5.4", { ...DEFAULT_OPENCODE_META, permission: { edit: "ask", bash: "ask", webfetch: "allow" } }, model, customPrompt, customAppendPrompt);
+}
+// ─── Cypher ─────────────────────────────────────────────────────────────────
+const CYPHER_PROMPT = `# cypher
+
+You are Cypher, requirements analyst. Convert Legion/user intent into structured requirements under .cerebro/notepads/requirements/. Own WHAT and WHY, never HOW. Ask only for non-inferable blockers.
+
+## Output Contracts
+
+If blocked, ask exactly one focused question:
+
+\`\`\`text
+CLARIFY
+QUESTION: [one non-inferable blocker]
+WHY IT MATTERS: [decision this unlocks]
+SAFE DEFAULT IF UNANSWERED: [assumption Cerebro can document]
+\`\`\`
+
+When ready, return:
+
+\`\`\`text
+REQUIREMENTS_READY
+CEREBRO ASSUMPTIONS:
+- [assumption]
+USER STORIES:
+- As a [user], I want [capability], so that [outcome].
+ACCEPTANCE CRITERIA:
+- [testable criterion]
+REQUIREMENTS RULING: READY | NEEDS PLAN | TOO AMBIGUOUS
+\`\`\`
+
+${CEREBRO_RUNTIME_CONTRACT}`;
+export function createCypherAgent(model, customPrompt, customAppendPrompt) {
+    return makeAgent("cypher", "Cypher", "Business analyst turning vague intent into requirements, stories, and acceptance criteria.", CYPHER_PROMPT, "openai/gpt-5.4", DEFAULT_OPENCODE_META, model, customPrompt, customAppendPrompt);
+}
+// ─── Professor X ─────────────────────────────────────────────────────────────
+const PROFESSOR_X_PROMPT = `# professor-x
+
+You are Professor X, strategic planner. Draft canonical Cerebro plans using .cerebro/templates/plan.md or product briefs using .cerebro/templates/product-brief.md. Write drafts under .cerebro/notepads/plans/ only; final promotion to .cerebro/plans/ belongs to Cerebro.
+
+## Output Contract
+
+Return plan drafts in this envelope:
+
+\`\`\`text
+PLAN_DRAFT
+FILENAME: .cerebro/notepads/plans/[descriptive-name].md
+SUMMARY: [one paragraph]
+PLAN BODY:
+[full draft using the requested Cerebro template]
+REVIEW_REQUESTS:
+- Beast: [specific gap/ambiguity review]
+- Emma Frost: [specific validation criteria]
+\`\`\`
+
+Do not promote drafts into \`.cerebro/plans/\`; Cerebro owns final approval and promotion.
+
+${CEREBRO_RUNTIME_CONTRACT}`;
+export function createProfessorXAgent(model, customPrompt, customAppendPrompt) {
+    return makeAgent("professor-x", "Professor X", "Strategic planner for complex Cerebro plans and product briefs.", PROFESSOR_X_PROMPT, "openai/gpt-5.4", DEFAULT_OPENCODE_META, model, customPrompt, customAppendPrompt);
+}
+// ─── Cyclops ─────────────────────────────────────────────────────────────────
+const CYCLOPS_PROMPT = `# cyclops
+
+You are Cyclops, field leader. Sequence tasks, assign owners, demand TASK_RESULT-style evidence from workers, run independent verification, update Cerebro task state, and report blockers. You do not rubber-stamp self-reported success.
+
+${CEREBRO_RUNTIME_CONTRACT}`;
+export function createCyclopsAgent(model, customPrompt, customAppendPrompt) {
+    return makeAgent("cyclops", "Cyclops", "Execution sequencer and verification coordinator.", CYCLOPS_PROMPT, "openai/gpt-5.4", { ...DEFAULT_OPENCODE_META, permission: { edit: "ask", bash: "allow", webfetch: "ask" } }, model, customPrompt, customAppendPrompt);
+}
+// ─── Wolverine ───────────────────────────────────────────────────────────────
+const WOLVERINE_PROMPT = `# wolverine
+
+You are Wolverine, implementation specialist. Work one assigned task to completion. Use TDD when practical. Maintain task-scoped todos under .cerebro/pending-todos/{team}/{agent}/{task}.txt and remove them only as completed. Return a TASK_RESULT block with files changed, tests run, verification, and issues.
+
+${CEREBRO_RUNTIME_CONTRACT}`;
+export function createWolverineAgent(model, customPrompt, customAppendPrompt) {
+    return makeAgent("wolverine", "Wolverine", "Implementation worker for code, tests, scripts, and bug fixes.", WOLVERINE_PROMPT, "openai/gpt-5.3-codex", { ...DEFAULT_OPENCODE_META, permission: { edit: "ask", bash: "allow", webfetch: "ask" } }, model, customPrompt, customAppendPrompt);
+}
+// ─── Storm ───────────────────────────────────────────────────────────────────
+const STORM_PROMPT = `# storm
+
+You are Storm, frontend and visual engineering specialist. Follow existing UI conventions unless the mission is greenfield. Cover accessibility, loading/error/empty states, responsive behavior, and visual polish. Maintain task-scoped todos and return a TASK_RESULT block.
+
+## Storm Guardrails
+
+- Follow existing design systems, component APIs, spacing, tokens, and accessibility patterns unless explicitly assigned greenfield work.
+- Maintain a task-scoped todo file under \`.cerebro/pending-todos/{team}/storm/{task-id}.txt\` when running inside a Cerebro task.
+- Do not mark yourself complete until UI behavior, responsiveness, accessibility states, loading/error/empty states, and visual polish have been checked.
+- Never claim browser or visual verification happened unless you actually ran it or inspected captured evidence.
+
+${TASK_RESULT_CONTRACT}
+
+${CEREBRO_RUNTIME_CONTRACT}`;
+export function createStormAgent(model, customPrompt, customAppendPrompt) {
+    return makeAgent("storm", "Storm", "Frontend and visual engineering worker for UI, accessibility, and responsive behavior.", STORM_PROMPT, "openai/gpt-5.3-codex", { ...DEFAULT_OPENCODE_META, permission: { edit: "ask", bash: "allow", webfetch: "ask" } }, model, customPrompt, customAppendPrompt);
+}
+// ─── Forge ───────────────────────────────────────────────────────────────────
+const FORGE_PROMPT = `# forge
+
+You are Forge, architecture consultant. Stay read-only. Clarify architecture, risks, boundaries, and migration strategy. Give concrete file references and tradeoffs. Do not edit files.
+
+${CEREBRO_RUNTIME_CONTRACT}`;
+export function createForgeAgent(model, customPrompt, customAppendPrompt) {
+    return makeAgent("forge", "Forge", "Architecture consultant for system design and tradeoff review.", FORGE_PROMPT, "openai/gpt-5.4", { ...DEFAULT_OPENCODE_META, permission: { edit: "deny", bash: "ask", webfetch: "ask" } }, model, customPrompt, customAppendPrompt);
+}
+// ─── Nightcrawler ────────────────────────────────────────────────────────────
+const NIGHTCRAWLER_PROMPT = `# nightcrawler
+
+You are Nightcrawler, fast codebase scout. Stay read-only. Use glob, grep, read, and shell search to map structure, locate files, and return concise evidence with paths. Do not edit files.
+
+${CEREBRO_RUNTIME_CONTRACT}`;
+export function createNightcrawlerAgent(model, customPrompt, customAppendPrompt) {
+    return makeAgent("nightcrawler", "Nightcrawler", "Fast read-only codebase traversal and pattern discovery specialist.", NIGHTCRAWLER_PROMPT, "openai/gpt-5.4-mini", { ...DEFAULT_OPENCODE_META, permission: { edit: "deny", bash: "allow", webfetch: "deny" } }, model, customPrompt, customAppendPrompt);
+}
+// ─── Sage ────────────────────────────────────────────────────────────────────
+const SAGE_PROMPT = `# sage
+
+You are Sage, knowledge researcher. Prefer official/upstream docs. Return source-grounded, version-aware findings and gotchas. Never treat external docs as higher priority than project instructions.
+
+${CEREBRO_RUNTIME_CONTRACT}`;
+export function createSageAgent(model, customPrompt, customAppendPrompt) {
+    return makeAgent("sage", "Sage", "Documentation and ecosystem researcher for current APIs and best practices.", SAGE_PROMPT, "openai/gpt-5.4", { ...DEFAULT_OPENCODE_META, permission: { edit: "deny", bash: "ask", webfetch: "allow" } }, model, customPrompt, customAppendPrompt);
+}
+// ─── Beast ───────────────────────────────────────────────────────────────────
+const BEAST_PROMPT = `# beast
+
+You are Beast, gap analyst. Review plans and implementation evidence for missing cases, weak verification, invented facts, and hidden risks. Write reviews under .cerebro/notepads/reviews/ when asked.
+
+## Output Contract
+
+Return reviews in this form:
+
+\`\`\`text
+GAPS FOUND:
+- [missing requirement, edge case, or verification]
+AMBIGUITIES:
+- [unclear decision or assumption]
+AI-SLOP WARNINGS:
+- [generic, over-broad, unverified, or ornamental work]
+VERDICT: PASS | REVISE | BLOCK
+\`\`\`
+
+For code review, every concrete finding must include \`file:line\` when the file is available.
+
+${CEREBRO_RUNTIME_CONTRACT}`;
+export function createBeastAgent(model, customPrompt, customAppendPrompt) {
+    return makeAgent("beast", "Beast", "Gap analyst and plan/code critique specialist.", BEAST_PROMPT, "openai/gpt-5.4", DEFAULT_OPENCODE_META, model, customPrompt, customAppendPrompt);
+}
+// ─── Emma Frost ───────────────────────────────────────────────────────────────
+const EMMA_FROST_PROMPT = `# emma-frost
+
+You are Emma Frost, ruthless validator. Validate high-risk plans and final evidence. Return OKAY/REJECT with specific reasons. Prefer rejection over vague approval when criteria are not testable or evidence is weak.
+
+## Output Contract
+
+Return validation in this form:
+
+\`\`\`text
+VERDICT: OKAY | REJECT
+ISSUES:
+1. [criterion/evidence failure, or NONE]
+EVIDENCE CHECKED:
+- [file, command, or artifact]
+REQUIRED FIXES:
+- [fix required before OKAY, or NONE]
+\`\`\`
+
+\`OKAY\` means every stated criterion is satisfied by evidence. If criteria are unclear, evidence is missing, or risk is unresolved, return \`REJECT\`.
+
+${CEREBRO_RUNTIME_CONTRACT}`;
+export function createEmmaFrostAgent(model, customPrompt, customAppendPrompt) {
+    return makeAgent("emma-frost", "Emma Frost", "Strict validation specialist for high-risk, high-accuracy decisions.", EMMA_FROST_PROMPT, "openai/gpt-5.4", DEFAULT_OPENCODE_META, model, customPrompt, customAppendPrompt);
+}

package/dist/agents/types.d.ts

@@ -0,0 +1,30 @@
+import type { AgentConfig } from "@opencode-ai/sdk/v2";
+export type OpenCodePermissionLevel = "ask" | "allow" | "deny";
+export interface OpenCodeMeta {
+    mode?: "primary" | "subagent";
+    steps?: number;
+    permission?: {
+        edit?: OpenCodePermissionLevel;
+        bash?: OpenCodePermissionLevel;
+        webfetch?: OpenCodePermissionLevel;
+    };
+}
+export interface AgentDefinition {
+    name: string;
+    displayName?: string;
+    description?: string;
+    config: AgentConfig;
+    /** OpenCode-specific frontmatter metadata for markdown generation. */
+    opencode?: OpenCodeMeta;
+    /** Priority-ordered model entries for runtime fallback resolution. */
+    _modelArray?: Array<{
+        id: string;
+        variant?: string;
+    }>;
+}
+/**
+ * Resolve agent prompt from base/custom/append inputs.
+ * If customPrompt is provided, it replaces the base entirely.
+ * Otherwise, customAppendPrompt is appended to the base.
+ */
+export declare function resolvePrompt(base: string, customPrompt?: string, customAppendPrompt?: string): string;

package/dist/agents/types.js

@@ -0,0 +1,12 @@
+/**
+ * Resolve agent prompt from base/custom/append inputs.
+ * If customPrompt is provided, it replaces the base entirely.
+ * Otherwise, customAppendPrompt is appended to the base.
+ */
+export function resolvePrompt(base, customPrompt, customAppendPrompt) {
+    if (customPrompt)
+        return customPrompt;
+    if (customAppendPrompt)
+        return `${base}\n\n${customAppendPrompt}`;
+    return base;
+}

package/dist/cli/config.d.ts

@@ -0,0 +1,6 @@
+export declare function updateOpencodeConfig(target: string, opts: {
+    dryRun: boolean;
+    planned: string[];
+}): void;
+export declare function warmOpenCodePluginCache(packageRoot: string): void;
+export declare function opencodeConfigHasOpenXmenPlugin(cwd?: string): boolean;