@maestria/opencode 0.3.11 → 0.4.1

package/agents/orchestrator.md

@@ -94,6 +94,36 @@ These apply on every invocation without exception:
    - `ci`: CI/CD changes
    - `test`: Test additions or changes
 
+## Workflow Mode Override
+
+Modes override the default delegation pipeline. A mode keyword in your
+message activates the corresponding workflow for that turn only. The
+keyword is stripped before processing. Detection is case-insensitive.
+When detected, the hook injects `[MODE: fein]` at the front of your message.
+
+| Mode    | Pipeline                                                                                | When to use                              |
+| ------- | --------------------------------------------------------------------------------------- | ---------------------------------------- |
+| `fein`  | `@adventurer` → `@architect`/`@planner` → `@builder` → `@reviewer`                      | Production-grade, non-trivial changes    |
+| `sonar` | `@adventurer` → `@architect`/`@planner` → STOP                                          | Discovery, research, feasibility         |
+| `blitz` | `@builder` directly — skip recon/design/review unless the codebase is genuinely unknown | Quick fixes, prototypes, known territory |
+
+### Precedence
+
+1. If the mode marker is present, it overrides any conflicting intent
+   inferred from trigger phrases. For example, `"fein fix this bug"`
+   runs the full pipeline, not just `@diagnose`.
+2. If no mode is present, the normal trigger-phrase matching applies
+   (see **Trigger phrases** below).
+3. Mode is per-turn — each message independently activates its own
+   mode. Conversation history (subagent handoffs) tracks progress across
+   turns.
+
+### Deactivated modes
+
+If a mode keyword is disabled by the user's plugin config, it passes
+through as plain text — no mode logic applies. The orchestrator
+behaves as if no mode was specified.
+
 ## Available Specialists
 
 **Delegate to these specialists only — they are built-in agents for direct use, not for delegation.**

package/dist/index.js

@@ -2,6 +2,8 @@ import { readFileSync, readdirSync } from "fs";
 import { join, dirname, basename } from "path";
 import { parse as parseYaml } from "yaml";
 import { fileURLToPath } from "url";
+import { maestriaOptionsSchema } from "./modes/types.js";
+import { detectMode, stripKeyword, getModeMarker, getModePrompt } from "./modes/index.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const agentsDir = join(__dirname, "..", "agents");
 const rulesPath = join(__dirname, "..", "rules", "AGENTS.md");
@@ -52,7 +54,10 @@ function loadAgents() {
     }
     return agents;
 }
-export const MaestriaPlugin = async () => {
+export const MaestriaPlugin = async (_input, options) => {
+    // Validate and parse options with zod
+    const parsed = maestriaOptionsSchema.parse(options ?? {});
+    const disabledKeywords = new Set((parsed.modes?.disabledKeywords ?? []).map((k) => k.toLowerCase()));
     const agents = loadAgents();
     return {
         config: async (input) => {
@@ -67,6 +72,30 @@ export const MaestriaPlugin = async () => {
                 "Active context (files, decisions, blockers) was captured before compaction. " +
                 "Continue where you left off.");
         },
+        "chat.message": async (hookInput, hookOutput) => {
+            // Only fire for the orchestrator agent
+            if (hookInput.agent !== "orchestrator")
+                return;
+            // Find the first text part with user content
+            const textPart = hookOutput.parts.find((p) => p.type === "text");
+            if (!textPart)
+                return;
+            // Detect keyword in the text
+            const result = detectMode(textPart.text, disabledKeywords);
+            if (!result)
+                return;
+            // Strip keyword from text
+            textPart.text = stripKeyword(textPart.text, result);
+            // Inject mode marker + prompt at the front of parts
+            hookOutput.parts.unshift({
+                id: crypto.randomUUID(),
+                sessionID: hookInput.sessionID,
+                messageID: hookOutput.message.id,
+                type: "text",
+                text: [getModeMarker(result.mode), "", getModePrompt(result.mode)].join("\n"),
+                synthetic: true,
+            });
+        },
     };
 };
 export default MaestriaPlugin;

package/dist/modes/index.d.ts

@@ -0,0 +1,39 @@
+import type { ModeResult } from "./types.js";
+/**
+ * Detect a workflow mode keyword in the given text.
+ *
+ * Detection rules (per ADR-008):
+ * - Word-boundary regex matching (`\bfein\b`, `\bsonar\b`, `\bblitz\b`)
+ * - Most restrictive match wins (fein > sonar > blitz)
+ * - Case-insensitive
+ * - Disabled keywords are ignored
+ * - Matches inside fenced code blocks (```) and inline backticks (`) are ignored
+ *
+ * @param text The user message to scan.
+ * @param disabled Optional set of disabled mode keywords (lowercase).
+ * @returns A `ModeResult` if a keyword was detected, or `null`.
+ */
+export declare function detectMode(text: string, disabled?: Set<string>): ModeResult | null;
+/**
+ * Remove the matched keyword from the text, cleaning up any trailing colon
+ * or whitespace that may follow it.
+ *
+ * @param text The original message text.
+ * @param result The `ModeResult` from `detectMode()`.
+ * @returns The text with the keyword stripped.
+ */
+export declare function stripKeyword(text: string, result: ModeResult): string;
+/**
+ * Get the mode prompt text for a given mode name.
+ *
+ * @param mode The mode keyword (e.g. "fein", "sonar", "blitz").
+ * @returns The prompt string, or empty string if mode is unknown.
+ */
+export declare function getModePrompt(mode: string): string;
+/**
+ * Get the mode marker string for a given mode name.
+ *
+ * @param mode The mode keyword (e.g. "fein", "sonar", "blitz").
+ * @returns The marker string (e.g. `[MODE: fein]`), or empty string if unknown.
+ */
+export declare function getModeMarker(mode: string): string;

package/dist/modes/index.js

@@ -0,0 +1,144 @@
+import { escapeRegExp } from "es-toolkit";
+import { MODE_PROMPTS, MODE_MARKERS, VALID_KEYWORDS } from "./prompts.js";
+/**
+ * Priority mapping for mode keyword restrictiveness.
+ * Higher number = more restrictive = wins when multiple keywords are present.
+ * fein (3): full pipeline with mandatory gates
+ * sonar (2): research only, no code
+ * blitz (1): fast implementation, skip all gates
+ */
+const MODE_PRIORITY = {
+    fein: 3,
+    sonar: 2,
+    blitz: 1,
+};
+/**
+ * Regex matching fenced code blocks (```) and inline backtick spans (`).
+ * Used to exclude keyword matches inside code spans.
+ */
+// Note: Unclosed fenced code blocks (``` without closing ```) are not
+// excluded — the regex requires matching fences. This is an accepted
+// false-positive risk (see ADR-008 consequences).
+const CODE_BLOCK_RE = /```[\s\S]*?```|`[^`]*`/g;
+/**
+ * Find ranges of code blocks and inline code spans in text.
+ * Returns [start, end) positions. Keywords inside these ranges
+ * are ignored during detection.
+ */
+function findAllCodeBlockRanges(text) {
+    const ranges = [];
+    let match;
+    while ((match = CODE_BLOCK_RE.exec(text)) !== null) {
+        ranges.push([match.index, match.index + match[0].length]);
+    }
+    return ranges;
+}
+function isInRanges(index, ranges) {
+    return ranges.some(([start, end]) => index >= start && index < end);
+}
+/**
+ * Build a regex pattern for word-boundary matching of the given keyword.
+ *
+ * The pattern uses `\b` word boundaries to ensure we match whole words only,
+ * and is case-insensitive so `Fein`, `FEIN`, `fein` all match.
+ */
+function buildKeywordRegex(keyword) {
+    return new RegExp(`\\b${escapeRegExp(keyword)}\\b`, "gi");
+}
+/**
+ * Detect a workflow mode keyword in the given text.
+ *
+ * Detection rules (per ADR-008):
+ * - Word-boundary regex matching (`\bfein\b`, `\bsonar\b`, `\bblitz\b`)
+ * - Most restrictive match wins (fein > sonar > blitz)
+ * - Case-insensitive
+ * - Disabled keywords are ignored
+ * - Matches inside fenced code blocks (```) and inline backticks (`) are ignored
+ *
+ * @param text The user message to scan.
+ * @param disabled Optional set of disabled mode keywords (lowercase).
+ * @returns A `ModeResult` if a keyword was detected, or `null`.
+ */
+export function detectMode(text, disabled) {
+    const codeRanges = findAllCodeBlockRanges(text);
+    // Normalize disabled keywords to lowercase for case-insensitive comparison
+    const normalizedDisabled = disabled
+        ? new Set(Array.from(disabled).map((k) => k.toLowerCase()))
+        : undefined;
+    let bestMatch = null;
+    for (const keyword of VALID_KEYWORDS) {
+        if (normalizedDisabled?.has(keyword))
+            continue;
+        const regex = buildKeywordRegex(keyword);
+        let match;
+        while ((match = regex.exec(text)) !== null) {
+            if (isInRanges(match.index, codeRanges))
+                continue;
+            // Most-restrictive wins: prefer higher-priority mode over position
+            if (bestMatch === null || MODE_PRIORITY[keyword] > MODE_PRIORITY[bestMatch.mode]) {
+                bestMatch = {
+                    keyword: match[0],
+                    index: match.index,
+                    mode: keyword,
+                };
+            }
+        }
+    }
+    if (bestMatch === null)
+        return null;
+    return {
+        mode: bestMatch.mode,
+        keyword: bestMatch.keyword,
+        index: bestMatch.index,
+        prompt: MODE_PROMPTS[bestMatch.mode],
+        marker: MODE_MARKERS[bestMatch.mode],
+    };
+}
+/**
+ * Remove the matched keyword from the text, cleaning up any trailing colon
+ * or whitespace that may follow it.
+ *
+ * @param text The original message text.
+ * @param result The `ModeResult` from `detectMode()`.
+ * @returns The text with the keyword stripped.
+ */
+export function stripKeyword(text, result) {
+    const before = text.slice(0, result.index);
+    const after = text.slice(result.index + result.keyword.length);
+    // Remove any colon + optional whitespace after the keyword
+    // (e.g. "fein: do this" -> "do this")
+    const cleaned = after.replace(/^:\s*/, "");
+    // Collapse double spaces and trim both ends (handles keyword at start,
+    // end, or middle of text, plus extra whitespace around colon)
+    return (before + cleaned).replace(/\s{2,}/g, " ").trim();
+}
+/**
+ * Get the mode prompt text for a given mode name.
+ *
+ * @param mode The mode keyword (e.g. "fein", "sonar", "blitz").
+ * @returns The prompt string, or empty string if mode is unknown.
+ */
+export function getModePrompt(mode) {
+    if (isModeKeyword(mode)) {
+        return MODE_PROMPTS[mode];
+    }
+    return "";
+}
+/**
+ * Get the mode marker string for a given mode name.
+ *
+ * @param mode The mode keyword (e.g. "fein", "sonar", "blitz").
+ * @returns The marker string (e.g. `[MODE: fein]`), or empty string if unknown.
+ */
+export function getModeMarker(mode) {
+    if (isModeKeyword(mode)) {
+        return MODE_MARKERS[mode];
+    }
+    return "";
+}
+/**
+ * Type guard to check if a string is a valid ModeKeyword.
+ */
+function isModeKeyword(value) {
+    return VALID_KEYWORDS.includes(value);
+}

package/dist/modes/prompts.d.ts

@@ -0,0 +1,17 @@
+import type { ModeKeyword } from "./types.js";
+/**
+ * Mode prompt text for each keyword.
+ * These are injected into the turn when a mode is detected.
+ *
+ * @see ADR-008 (section "Mode Prompts")
+ */
+export declare const MODE_PROMPTS: Record<ModeKeyword, string>;
+/**
+ * Marker strings for each mode keyword, used to signal the active mode.
+ * Format: `[MODE: <keyword>]`
+ */
+export declare const MODE_MARKERS: Record<ModeKeyword, string>;
+/**
+ * Array of all valid mode keywords for runtime iteration.
+ */
+export declare const VALID_KEYWORDS: readonly ModeKeyword[];

package/dist/modes/prompts.js

@@ -0,0 +1,46 @@
+/**
+ * Mode prompt text for each keyword.
+ * These are injected into the turn when a mode is detected.
+ *
+ * @see ADR-008 (section "Mode Prompts")
+ */
+export const MODE_PROMPTS = {
+    fein: [
+        "## MODE: fein (Full Pipeline)",
+        "",
+        "Execute the complete fein pipeline: mandatory reconnaissance",
+        "(@adventurer) → design/plan (@architect or @planner) →",
+        "implementation (@builder) → review (@reviewer).",
+        "Do NOT skip any phase unless the user explicitly overrides",
+        "in the same turn.",
+    ].join("\n"),
+    sonar: [
+        "## MODE: sonar (Research Only)",
+        "",
+        "Research mode: reconnaissance and design only. Delegate to",
+        "@adventurer (recon) followed by @architect or @planner",
+        "(analysis/design). STOP after delivering findings and design.",
+        "Do NOT implement, write code, or create any production files.",
+    ].join("\n"),
+    blitz: [
+        "## MODE: blitz (Fast Implementation)",
+        "",
+        "Speed mode: skip reconnaissance and design gates. Go directly",
+        "to @builder for implementation. Only use @adventurer if the",
+        "codebase context is genuinely unknown (not as a default step).",
+        "Skip @reviewer unless the user explicitly requests review.",
+    ].join("\n"),
+};
+/**
+ * Marker strings for each mode keyword, used to signal the active mode.
+ * Format: `[MODE: <keyword>]`
+ */
+export const MODE_MARKERS = {
+    fein: "[MODE: fein]",
+    sonar: "[MODE: sonar]",
+    blitz: "[MODE: blitz]",
+};
+/**
+ * Array of all valid mode keywords for runtime iteration.
+ */
+export const VALID_KEYWORDS = ["fein", "sonar", "blitz"];

package/dist/modes/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Types for keyword-triggered workflow modes.
+ *
+ * @see ADR-008 for full design context.
+ */
+import { z } from "zod";
+/**
+ * Valid mode keywords.
+ *
+ * - `"fein"` -- Full pipeline (recon -> design -> build -> review)
+ * - `"sonar"` -- Research only (recon + design, stop before build)
+ * - `"blitz"` -- Fast implementation (builder direct, skip recon/design/review)
+ */
+export declare const modeKeywordSchema: z.ZodEnum<["fein", "sonar", "blitz"]>;
+export type ModeKeyword = z.infer<typeof modeKeywordSchema>;
+/**
+ * Plugin-level options for @maestria/opencode.
+ */
+export declare const maestriaOptionsSchema: z.ZodObject<{
+    modes: z.ZodOptional<z.ZodObject<{
+        disabledKeywords: z.ZodOptional<z.ZodArray<z.ZodEnum<["fein", "sonar", "blitz"]>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        disabledKeywords?: ("fein" | "sonar" | "blitz")[] | undefined;
+    }, {
+        disabledKeywords?: ("fein" | "sonar" | "blitz")[] | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    modes?: {
+        disabledKeywords?: ("fein" | "sonar" | "blitz")[] | undefined;
+    } | undefined;
+}, {
+    modes?: {
+        disabledKeywords?: ("fein" | "sonar" | "blitz")[] | undefined;
+    } | undefined;
+}>;
+export type MaestriaPluginOptions = z.infer<typeof maestriaOptionsSchema>;
+/**
+ * Result returned when a mode keyword is detected in a message.
+ */
+export interface ModeResult {
+    /** The resolved mode keyword (lowercase). */
+    mode: ModeKeyword;
+    /** The keyword string as matched in the original text. */
+    keyword: string;
+    /** The character index where the keyword starts in the original text. */
+    index: number;
+    /** The mode prompt text to inject. */
+    prompt: string;
+    /** The mode marker string like `[MODE: fein]`. */
+    marker: string;
+}

package/dist/modes/types.js

@@ -0,0 +1,24 @@
+/**
+ * Types for keyword-triggered workflow modes.
+ *
+ * @see ADR-008 for full design context.
+ */
+import { z } from "zod";
+/**
+ * Valid mode keywords.
+ *
+ * - `"fein"` -- Full pipeline (recon -> design -> build -> review)
+ * - `"sonar"` -- Research only (recon + design, stop before build)
+ * - `"blitz"` -- Fast implementation (builder direct, skip recon/design/review)
+ */
+export const modeKeywordSchema = z.enum(["fein", "sonar", "blitz"]);
+/**
+ * Plugin-level options for @maestria/opencode.
+ */
+export const maestriaOptionsSchema = z.object({
+    modes: z
+        .object({
+        disabledKeywords: z.array(modeKeywordSchema).optional(),
+    })
+        .optional(),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maestria/opencode",
-  "version": "0.3.11",
+  "version": "0.4.1",
   "description": "OpenCode plugin encoding AI engineering praxis: rules, agents, and workflow discipline.",
   "keywords": [
     "agents",
@@ -40,18 +40,21 @@
   },
   "dependencies": {
     "@opencode-ai/plugin": "^1.17.0",
-    "yaml": "^2.7.0"
+    "es-toolkit": "^1.47.1",
+    "yaml": "^2.7.0",
+    "zod": "^3.24.0"
   },
   "devDependencies": {
     "@types/node": "^24",
     "commit-and-tag-version": "^12.7.3",
-    "typescript": "^5"
+    "typescript": "^5",
+    "vitest": "npm:@voidzero-dev/vite-plus-test@^0.1.24"
   },
   "engines": {
     "node": ">=22.12.0"
   },
   "scripts": {
-    "build": "tsc",
-    "test": "vp test"
+    "build": "tsc && bash scripts/verify-imports.sh",
+    "test": "node ./node_modules/vitest/vitest.mjs run"
   }
 }

package/rules/AGENTS.md

@@ -7,7 +7,7 @@
 - **!!! Read the docs first** — before writing code that touches
   unfamiliar tools, APIs, or migration paths, consult official
   documentation. Don't guess at API changes. This rule is scar
-  tissue from repeated failures, not a preference.
+  tissue from repeated failures; treat it seriously.
 - **Don't reference internal project names in explanations** — avoid
   leaking context outside the workspace.
 - **Use `opensrc` for repos; `webfetch` for pages** — when analyzing a
@@ -19,6 +19,9 @@
   time — clone it once, then read locally. Use `--cwd` to resolve
   versions from the current project.
 - **Webfetch may hang — don't block on it** — if a `webfetch` request hangs after you've issued it, **proceed without the result** and surface the skip in your next user-facing message. Don't wait for a hung fetch to complete.
+- **Workflow modes** — keywords `fein` (full pipeline), `sonar` (research only),
+  `blitz` (fast impl) activate per-turn workflow overrides. See the
+  orchestrator prompt for details.
 - **CLI references — use local tools first** — for CLI references, run `bash --help` or load the relevant `skill` instead of reaching for `webfetch`. Local tools are faster and more reliable than fetching docs.
 - **Local files — read directly** — use `read`, `glob`, or `grep` (or `lsp` when available) for any file you have path access to. Don't `webfetch` a local file or a file in a checked-out repo.
 - **Tool hierarchy for external information:**