@maestria/opencode 0.4.9 → 0.5.1

package/agents/writer.md

@@ -31,13 +31,13 @@ You write documentation.
 
 ## Structure
 
-1. **Purpose** — Why this exists (not what it does)
-2. **Usage** — How to use it (quickstart, examples)
-3. **Details** — How it works (optional, for deeper understanding)
+1. **Purpose** - Why this exists (not what it does)
+2. **Usage** - How to use it (quickstart, examples)
+3. **Details** - How it works (optional, for deeper understanding)
 
 ## Principles
 
-- Write for humans — clear over clever
+- Write for humans - clear over clever
 - Complete over concise (but don't repeat yourself)
 - Use code examples liberally
 - Follow the project's existing doc style
@@ -48,7 +48,7 @@ You write documentation.
 
 - Use table format for lists with descriptions
 - Group related items under section headers
-- Keep descriptions concise — one line
+- Keep descriptions concise - one line
 - Match the tone of surrounding documentation
 - Use progressive disclosure: high-level first, details on demand
 
@@ -89,31 +89,31 @@ You write documentation.
 
 ### Always load
 
-- `writing-clearly-and-concisely` (`softaworks/agent-toolkit`) — better prose for all writing tasks
-- `humanizer` (`softaworks/agent-toolkit`) — remove AI writing signs (most docs are AI-shaped by default)
+- `writing-clearly-and-concisely` (`softaworks/agent-toolkit`) - better prose for all writing tasks
+- `humanizer` (`softaworks/agent-toolkit`) - remove AI writing signs (most docs are AI-shaped by default)
 
 ### Load on trigger
 
-- `backend-to-frontend-handoff-docs` (`softaworks/agent-toolkit`) — load when documenting an API for frontend consumers
-- `brand-guidelines` (`anthropics/skills`) — load when writing brand documentation, style guides, or tone-of-voice guidelines
-- `copy-editing` (`coreyhaines31/marketingskills`) — load when user wants in-place edits of existing copy
-- `crafting-effective-readmes` (`softaworks/agent-toolkit`) — load when output is a README
-- `doc-coauthoring` (`anthropics/skills`) — load when user wants to co-write, not just receive a doc
-- `docx` (`anthropics/skills`) — load when output must be `.docx`
-- `domain-modeling` (`mattpocock/skills`) — load when documenting the domain glossary, ubiquitous language, or domain concepts
-- `frontend-to-backend-requirements` (`softaworks/agent-toolkit`) — load when documenting frontend requirements for backend
-- `pdf` (`anthropics/skills`) — load when output must be `.pdf`
-- `pptx` (`anthropics/skills`) — load when output is slides
-- `writing-great-skills` (`mattpocock/skills`) — load when creating or editing a SKILL.md file
-- `xlsx` (`anthropics/skills`) — load when output is a spreadsheet
+- `backend-to-frontend-handoff-docs` (`softaworks/agent-toolkit`) - load when documenting an API for frontend consumers
+- `brand-guidelines` (`anthropics/skills`) - load when writing brand documentation, style guides, or tone-of-voice guidelines
+- `copy-editing` (`coreyhaines31/marketingskills`) - load when user wants in-place edits of existing copy
+- `crafting-effective-readmes` (`softaworks/agent-toolkit`) - load when output is a README
+- `doc-coauthoring` (`anthropics/skills`) - load when user wants to co-write, not just receive a doc
+- `docx` (`anthropics/skills`) - load when output must be `.docx`
+- `domain-modeling` (`mattpocock/skills`) - load when documenting the domain glossary, ubiquitous language, or domain concepts
+- `frontend-to-backend-requirements` (`softaworks/agent-toolkit`) - load when documenting frontend requirements for backend
+- `pdf` (`anthropics/skills`) - load when output must be `.pdf`
+- `pptx` (`anthropics/skills`) - load when output is slides
+- `writing-great-skills` (`mattpocock/skills`) - load when creating or editing a SKILL.md file
+- `xlsx` (`anthropics/skills`) - load when output is a spreadsheet
 
 ### Defer to specialist
 
-- `internal-comms` (`anthropics/skills`) → out of scope — internal comms is not a code/ADRs/API docs task
-- `professional-communication` (`softaworks/agent-toolkit`) → out of scope — emails/team messaging not in writer's role
-- `template-skill` (`anthropics/skills`) → out of scope — skill creation is a separate workflow
-- `skill-creator` (`anthropics/skills`) → out of scope — same as above
-- `copywriting` (`coreyhaines31/marketingskills`) → out of scope — marketing copy is not documentation
+- `internal-comms` (`anthropics/skills`) → out of scope - internal comms is not a code/ADRs/API docs task
+- `professional-communication` (`softaworks/agent-toolkit`) → out of scope - emails/team messaging not in writer's role
+- `template-skill` (`anthropics/skills`) → out of scope - skill creation is a separate workflow
+- `skill-creator` (`anthropics/skills`) → out of scope - same as above
+- `copywriting` (`coreyhaines31/marketingskills`) → out of scope - marketing copy is not documentation
 
 ### Skip if
 
@@ -122,14 +122,14 @@ You write documentation.
 
 ## Related Agents
 
-- `@architect` — Capture ADRs from architecture decisions and trade-off analysis
-- `@reviewer` — Review documentation for accuracy, clarity, and completeness
-- `@builder` — Verify that documented examples match actual implementation
+- `@architect` - Capture ADRs from architecture decisions and trade-off analysis
+- `@reviewer` - Review documentation for accuracy, clarity, and completeness
+- `@builder` - Verify that documented examples match actual implementation
 
 ## Iteration Limits
 
 - **Define a verifiable termination condition** (e.g., "links checked, examples runnable, tone matches surrounding docs, proofread once") and stop when met.
-- **Max 3 proofread-revise cycles** before handing off — re-revising without new feedback is loop territory.
+- **Max 3 proofread-revise cycles** before handing off - re-revising without new feedback is loop territory.
 - **Escalation format:** "Tried X, Y, Z. Blocked by [cause]. Need [input] to proceed."
 
 ## Check
@@ -139,8 +139,8 @@ You write documentation.
 - Check that examples are accurate
 - Ensure examples are runnable (not pseudocode)
 - Test code examples if possible
-- **!!! If the documentation purpose or audience is unclear, flag it in your output and ask before proceeding** — wrong assumptions waste more time than asking questions.
-- **!!! Maker/checker split** — your work is reviewed by `@reviewer` before it lands. The model that wrote the doc is too nice grading its own homework. Produce the doc, do not QA it.
-- **!!! Validate before handoff** — never present a doc you haven't proofread. Verify links work, examples are runnable (not pseudocode), tone matches the surrounding style. Re-read the doc before reporting back.
-- **!!! Don't delete what you didn't create** — flag deletions of unrelated sections in your own diff. Documentation changes should be focused; collateral deletions are a trust killer.
+- **!!! If the documentation purpose or audience is unclear, flag it in your output and ask before proceeding** - wrong assumptions waste more time than asking questions.
+- **!!! Maker/checker split** - your work is reviewed by `@reviewer` before it lands. The model that wrote the doc is too nice grading its own homework. Produce the doc, do not QA it.
+- **!!! Validate before handoff** - never present a doc you haven't proofread. Verify links work, examples are runnable (not pseudocode), tone matches the surrounding style. Re-read the doc before reporting back.
+- **!!! Don't delete what you didn't create** - flag deletions of unrelated sections in your own diff. Documentation changes should be focused; collateral deletions are a trust killer.
 - **Parallelization:** writer tasks on different documents can run in parallel. Two writers on the same doc = wasted effort. Doc is single-writer.

package/dist/index.js

@@ -1,6 +1,6 @@
-import{readFileSync as e,readdirSync as t}from"fs";import{basename as n,dirname as r,join as i}from"path";import{parse as a}from"yaml";import{fileURLToPath as o}from"url";import{z as s}from"zod";import{escapeRegExp as c}from"es-toolkit";const l=s.enum([`fein`,`sonar`,`blitz`]),u=s.object({modes:s.object({disabledKeywords:s.array(l).optional()}).optional()}),d={fein:[`## MODE: fein (Full Pipeline)`,``,`Default role-based pipeline: thinker (recon/design/plan) → worker (implementation) → verifier (review).`,`Verifier acceptance terminates the pipeline for that unit of work.`,`Roles and order may adapt to task needs — this is the default, not a fixed requirement.`,`Do NOT skip any phase unless the user explicitly overrides`,`in the same turn.`].join(`
+import{readFileSync as e,readdirSync as t}from"fs";import{basename as n,dirname as r,join as i}from"path";import{parse as a}from"yaml";import{fileURLToPath as o}from"url";import{z as s}from"zod";import{escapeRegExp as c}from"es-toolkit";const l=s.enum([`fein`,`sonar`,`blitz`]),u=s.object({modes:s.object({disabledKeywords:s.array(l).optional()}).optional()}),d={fein:[`## MODE: fein (Full Pipeline)`,``,`Default role-based pipeline: thinker (recon/design/plan) → worker (implementation) → verifier (review).`,`Verifier acceptance terminates the pipeline for that unit of work.`,`Roles and order may adapt to task needs - this is the default, not a fixed requirement.`,`Do NOT skip any phase unless the user explicitly overrides`,`in the same turn.`].join(`
 `),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(`
 `),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(`
-`)},f={fein:`[MODE: fein]`,sonar:`[MODE: sonar]`,blitz:`[MODE: blitz]`},p=[`fein`,`sonar`,`blitz`],m={fein:3,sonar:2,blitz:1},h=/```[\s\S]*?```|`[^`]*`/g;function g(e){let t=[],n;for(;(n=h.exec(e))!==null;)t.push([n.index,n.index+n[0].length]);return t}function _(e,t){return t.some(([t,n])=>e>=t&&e<n)}function v(e){return RegExp(`\\b${c(e)}\\b`,`gi`)}function y(e,t){let n=g(e),r=t?new Set(Array.from(t).map(e=>e.toLowerCase())):void 0,i=null;for(let t of p){if(r?.has(t))continue;let a=v(t),o;for(;(o=a.exec(e))!==null;)_(o.index,n)||(i===null||m[t]>m[i.mode])&&(i={keyword:o[0],index:o.index,mode:t})}return i===null?null:{mode:i.mode,keyword:i.keyword,index:i.index,prompt:d[i.mode],marker:f[i.mode]}}function b(e,t){return(e.slice(0,t.index)+e.slice(t.index+t.keyword.length).replace(/^:\s*/,``)).replace(/ {2,}/g,` `).trim()}function x(e){return C(e)?d[e]:``}function S(e){return C(e)?f[e]:``}function C(e){return p.includes(e)}const w=r(o(import.meta.url)),T=i(w,`..`,`agents`),E=i(w,`..`,`rules`,`AGENTS.md`);function D(e){let t=a(e);return{description:t.description||``,mode:t.mode||`subagent`,permission:t.permission||{},color:t.color,maxSteps:t.maxSteps?Number(t.maxSteps):void 0}}function O(t){let r=e(t,`utf-8`),i=n(t,`.md`),a=r.split(`---`);if(a.length<3)throw Error(`Invalid agent file: ${t} — missing frontmatter`);let o=D(a[1].trim()),s=a.slice(2).join(`---`).trim(),c={description:o.description,mode:o.mode,prompt:s,permission:o.permission};return o.color&&(c.color=o.color),o.maxSteps&&(c.maxSteps=o.maxSteps),{name:i,config:c}}function k(){try{let e=t(T).filter(e=>e.endsWith(`.md`)),n={};for(let t of e)try{let{name:e,config:r}=O(i(T,t));n[e]=r}catch(e){console.warn(`[maestria] Failed to parse agent file "${t}":`,e)}return n}catch(e){return console.warn(`[maestria] Failed to read agents directory:`,e),{}}}const A=async(e,t)=>{let n=u.parse(t??{}),r=new Set((n.modes?.disabledKeywords??[]).map(e=>e.toLowerCase())),i=k();return{config:async e=>{e.agent={...e.agent,...i},e.instructions=[...e.instructions??[],E]},"experimental.session.compacting":async(e,t)=>{t.context.push(`Session was compacted. Task tracking is maintained via todowrite. Active context (files, decisions, blockers) was captured before compaction. Continue where you left off.`)},"chat.message":async(e,t)=>{if(e.agent!==`orchestrator`)return;let n=t.parts.find(e=>e.type===`text`);if(!n)return;let i=y(n.text,r);i&&(n.text=[S(i.mode),``,x(i.mode),``,b(n.text,i)].join(`
+`)},f={fein:`[MODE: fein]`,sonar:`[MODE: sonar]`,blitz:`[MODE: blitz]`},p=[`fein`,`sonar`,`blitz`],m={fein:3,sonar:2,blitz:1},h=/```[\s\S]*?```|`[^`]*`/g;function g(e){let t=[],n;for(;(n=h.exec(e))!==null;)t.push([n.index,n.index+n[0].length]);return t}function _(e,t){return t.some(([t,n])=>e>=t&&e<n)}function v(e){return RegExp(`\\b${c(e)}\\b`,`gi`)}function y(e,t){let n=g(e),r=t?new Set(Array.from(t).map(e=>e.toLowerCase())):void 0,i=null;for(let t of p){if(r?.has(t))continue;let a=v(t),o;for(;(o=a.exec(e))!==null;)_(o.index,n)||(i===null||m[t]>m[i.mode])&&(i={keyword:o[0],index:o.index,mode:t})}return i===null?null:{mode:i.mode,keyword:i.keyword,index:i.index,prompt:d[i.mode],marker:f[i.mode]}}function b(e,t){return(e.slice(0,t.index)+e.slice(t.index+t.keyword.length).replace(/^:\s*/,``)).replace(/ {2,}/g,` `).trim()}function x(e){return C(e)?d[e]:``}function S(e){return C(e)?f[e]:``}function C(e){return p.includes(e)}const w=r(o(import.meta.url)),T=i(w,`..`,`agents`),E=i(w,`..`,`rules`,`AGENTS.md`);function D(e){let t=a(e);return{description:t.description||``,mode:t.mode||`subagent`,permission:t.permission||{},color:t.color,maxSteps:t.maxSteps?Number(t.maxSteps):void 0}}function O(t){let r=e(t,`utf-8`),i=n(t,`.md`),a=r.split(`---`);if(a.length<3)throw Error(`Invalid agent file: ${t} - missing frontmatter`);let o=D(a[1].trim()),s=a.slice(2).join(`---`).trim(),c={description:o.description,mode:o.mode,prompt:s,permission:o.permission};return o.color&&(c.color=o.color),o.maxSteps&&(c.maxSteps=o.maxSteps),{name:i,config:c}}function k(){try{let e=t(T).filter(e=>e.endsWith(`.md`)),n={};for(let t of e)try{let{name:e,config:r}=O(i(T,t));n[e]=r}catch(e){console.warn(`[maestria] Failed to parse agent file "${t}":`,e)}return n}catch(e){return console.warn(`[maestria] Failed to read agents directory:`,e),{}}}const A=async(e,t)=>{let n=u.parse(t??{}),r=new Set((n.modes?.disabledKeywords??[]).map(e=>e.toLowerCase())),i=k();return{config:async e=>{e.agent={...e.agent,...i},e.instructions=[...e.instructions??[],E]},"experimental.session.compacting":async(e,t)=>{t.context.push(`Session was compacted. Task tracking is maintained via todowrite. Active context (files, decisions, blockers) was captured before compaction. Continue where you left off.`)},"chat.message":async(e,t)=>{if(e.agent!==`orchestrator`)return;let n=t.parts.find(e=>e.type===`text`);if(!n)return;let i=y(n.text,r);i&&(n.text=[S(i.mode),``,x(i.mode),``,b(n.text,i)].join(`
 `))}}};export{A as MaestriaPlugin,A as default};
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["parseYaml"],"sources":["../src/modes/types.ts","../src/modes/prompts.ts","../src/modes/index.ts","../src/index.ts"],"sourcesContent":["/**\n * Types for keyword-triggered workflow modes.\n *\n * @see ADR-OC-003 for full design context.\n */\n\nimport { z } from 'zod';\n\n/**\n * Valid mode keywords.\n *\n * - `\"fein\"` -- Full pipeline (recon -> design -> build -> review)\n * - `\"sonar\"` -- Research only (recon + design, stop before build)\n * - `\"blitz\"` -- Fast implementation (builder direct, skip recon/design/review)\n */\nexport const modeKeywordSchema = z.enum(['fein', 'sonar', 'blitz']);\nexport type ModeKeyword = z.infer<typeof modeKeywordSchema>;\n\n/**\n * Plugin-level options for @maestria/opencode.\n */\nexport const maestriaOptionsSchema = z.object({\n  modes: z\n    .object({\n      disabledKeywords: z.array(modeKeywordSchema).optional(),\n    })\n    .optional(),\n});\nexport type MaestriaPluginOptions = z.infer<typeof maestriaOptionsSchema>;\n\n/**\n * Result returned when a mode keyword is detected in a message.\n */\nexport interface ModeResult {\n  /** The resolved mode keyword (lowercase). */\n  mode: ModeKeyword;\n  /** The keyword string as matched in the original text. */\n  keyword: string;\n  /** The character index where the keyword starts in the original text. */\n  index: number;\n  /** The mode prompt text to inject. */\n  prompt: string;\n  /** The mode marker string like `[MODE: fein]`. */\n  marker: string;\n}\n","import type { ModeKeyword } from '@/modes/types.js';\n\n/**\n * Mode prompt text for each keyword.\n * These are injected into the turn when a mode is detected.\n *\n * @see ADR-OC-003 (section \"Mode Prompts\")\n */\nexport const MODE_PROMPTS: Record<ModeKeyword, string> = {\n  fein: [\n    '## MODE: fein (Full Pipeline)',\n    '',\n    'Default role-based pipeline: thinker (recon/design/plan) → worker (implementation) → verifier (review).',\n    'Verifier acceptance terminates the pipeline for that unit of work.',\n    'Roles and order may adapt to task needs — this is the default, not a fixed requirement.',\n    'Do NOT skip any phase unless the user explicitly overrides',\n    'in the same turn.',\n  ].join('\\n'),\n\n  sonar: [\n    '## MODE: sonar (Research Only)',\n    '',\n    'Research mode: reconnaissance and design only. Delegate to',\n    '@adventurer (recon) followed by @architect or @planner',\n    '(analysis/design). STOP after delivering findings and design.',\n    'Do NOT implement, write code, or create any production files.',\n  ].join('\\n'),\n\n  blitz: [\n    '## MODE: blitz (Fast Implementation)',\n    '',\n    'Speed mode: skip reconnaissance and design gates. Go directly',\n    'to @builder for implementation. Only use @adventurer if the',\n    'codebase context is genuinely unknown (not as a default step).',\n    'Skip @reviewer unless the user explicitly requests review.',\n  ].join('\\n'),\n};\n\n/**\n * Marker strings for each mode keyword, used to signal the active mode.\n * Format: `[MODE: <keyword>]`\n */\nexport const MODE_MARKERS: Record<ModeKeyword, string> = {\n  fein: '[MODE: fein]',\n  sonar: '[MODE: sonar]',\n  blitz: '[MODE: blitz]',\n};\n\n/**\n * Array of all valid mode keywords for runtime iteration.\n */\nexport const VALID_KEYWORDS: readonly ModeKeyword[] = ['fein', 'sonar', 'blitz'];\n","import { escapeRegExp } from 'es-toolkit';\nimport { MODE_PROMPTS, MODE_MARKERS, VALID_KEYWORDS } from '@/modes/prompts.js';\nimport type { ModeKeyword, ModeResult } from '@/modes/types.js';\n\n/**\n * Priority mapping for mode keyword restrictiveness.\n * Higher number = more restrictive = wins when multiple keywords are present.\n * fein (3): full pipeline with mandatory gates\n * sonar (2): research only, no code\n * blitz (1): fast implementation, skip all gates\n */\nconst MODE_PRIORITY: Record<ModeKeyword, number> = {\n  fein: 3,\n  sonar: 2,\n  blitz: 1,\n};\n\n/**\n * Regex matching fenced code blocks (```) and inline backtick spans (`).\n * Used to exclude keyword matches inside code spans.\n */\n// Note: Unclosed fenced code blocks (``` without closing ```) are not\n// excluded — the regex requires matching fences. This is an accepted\n// false-positive risk (see ADR-OC-003 consequences).\nconst CODE_BLOCK_RE = /```[\\s\\S]*?```|`[^`]*`/g;\n\n/**\n * Find ranges of code blocks and inline code spans in text.\n * Returns [start, end) positions. Keywords inside these ranges\n * are ignored during detection.\n */\nfunction findAllCodeBlockRanges(text: string): Array<[number, number]> {\n  const ranges: Array<[number, number]> = [];\n  let match: RegExpExecArray | null;\n  while ((match = CODE_BLOCK_RE.exec(text)) !== null) {\n    ranges.push([match.index, match.index + match[0].length]);\n  }\n  return ranges;\n}\n\nfunction isInRanges(index: number, ranges: Array<[number, number]>): boolean {\n  return ranges.some(([start, end]) => index >= start && index < end);\n}\n\n/**\n * Build a regex pattern for word-boundary matching of the given keyword.\n *\n * The pattern uses `\\b` word boundaries to ensure we match whole words only,\n * and is case-insensitive so `Fein`, `FEIN`, `fein` all match.\n */\nfunction buildKeywordRegex(keyword: string): RegExp {\n  return new RegExp(`\\\\b${escapeRegExp(keyword)}\\\\b`, 'gi');\n}\n\n/**\n * Detect a workflow mode keyword in the given text.\n *\n * Detection rules (per ADR-OC-003):\n * - Word-boundary regex matching (`\\bfein\\b`, `\\bsonar\\b`, `\\bblitz\\b`)\n * - Most restrictive match wins (fein > sonar > blitz)\n * - Case-insensitive\n * - Disabled keywords are ignored\n * - Matches inside fenced code blocks (```) and inline backticks (`) are ignored\n *\n * @param text The user message to scan.\n * @param disabled Optional set of disabled mode keywords (lowercase).\n * @returns A `ModeResult` if a keyword was detected, or `null`.\n */\nexport function detectMode(text: string, disabled?: Set<string>): ModeResult | null {\n  const codeRanges = findAllCodeBlockRanges(text);\n  // Normalize disabled keywords to lowercase for case-insensitive comparison\n  const normalizedDisabled = disabled\n    ? new Set(Array.from(disabled).map((k) => k.toLowerCase()))\n    : undefined;\n  let bestMatch: { keyword: string; index: number; mode: ModeKeyword } | null = null;\n\n  for (const keyword of VALID_KEYWORDS) {\n    if (normalizedDisabled?.has(keyword)) continue;\n\n    const regex = buildKeywordRegex(keyword);\n    let match: RegExpExecArray | null;\n\n    while ((match = regex.exec(text)) !== null) {\n      if (isInRanges(match.index, codeRanges)) continue;\n      // Most-restrictive wins: prefer higher-priority mode over position\n      if (bestMatch === null || MODE_PRIORITY[keyword] > MODE_PRIORITY[bestMatch.mode]) {\n        bestMatch = {\n          keyword: match[0],\n          index: match.index,\n          mode: keyword,\n        };\n      }\n    }\n  }\n\n  if (bestMatch === null) return null;\n\n  return {\n    mode: bestMatch.mode,\n    keyword: bestMatch.keyword,\n    index: bestMatch.index,\n    prompt: MODE_PROMPTS[bestMatch.mode],\n    marker: MODE_MARKERS[bestMatch.mode],\n  };\n}\n\n/**\n * Remove the matched keyword from the text, cleaning up any trailing colon\n * or whitespace that may follow it.\n *\n * @param text The original message text.\n * @param result The `ModeResult` from `detectMode()`.\n * @returns The text with the keyword stripped.\n */\nexport function stripKeyword(text: string, result: ModeResult): string {\n  const before = text.slice(0, result.index);\n  const after = text.slice(result.index + result.keyword.length);\n\n  // Remove any colon + optional whitespace after the keyword\n  // (e.g. \"fein: do this\" -> \"do this\")\n  const cleaned = after.replace(/^:\\s*/, '');\n\n  // Collapse double spaces and trim both ends (handles keyword at start,\n  // end, or middle of text, plus extra whitespace around colon)\n  return (before + cleaned).replace(/ {2,}/g, ' ').trim();\n}\n\n/**\n * Get the mode prompt text for a given mode name.\n *\n * @param mode The mode keyword (e.g. \"fein\", \"sonar\", \"blitz\").\n * @returns The prompt string, or empty string if mode is unknown.\n */\nexport function getModePrompt(mode: string): string {\n  if (isModeKeyword(mode)) {\n    return MODE_PROMPTS[mode];\n  }\n  return '';\n}\n\n/**\n * Get the mode marker string for a given mode name.\n *\n * @param mode The mode keyword (e.g. \"fein\", \"sonar\", \"blitz\").\n * @returns The marker string (e.g. `[MODE: fein]`), or empty string if unknown.\n */\nexport function getModeMarker(mode: string): string {\n  if (isModeKeyword(mode)) {\n    return MODE_MARKERS[mode];\n  }\n  return '';\n}\n\n/**\n * Type guard to check if a string is a valid ModeKeyword.\n */\nfunction isModeKeyword(value: string): value is ModeKeyword {\n  return (VALID_KEYWORDS as readonly string[]).includes(value);\n}\n","import type { Plugin } from '@opencode-ai/plugin';\nimport { readFileSync, readdirSync } from 'fs';\nimport { join, dirname, basename } from 'path';\nimport { parse as parseYaml } from 'yaml';\nimport { fileURLToPath } from 'url';\nimport { type MaestriaPluginOptions, maestriaOptionsSchema } from '@/modes/types.js';\nimport { detectMode, stripKeyword, getModeMarker, getModePrompt } from '@/modes/index.js';\n\nconst __dirname = dirname(fileURLToPath(import.meta.url));\nconst agentsDir = join(__dirname, '..', 'agents');\nconst rulesPath = join(__dirname, '..', 'rules', 'AGENTS.md');\n\ninterface AgentFrontmatter {\n  description: string;\n  mode: string;\n  permission: Record<string, unknown>;\n  color?: string;\n  maxSteps?: number;\n}\n\nfunction parseFrontmatter(yamlStr: string): AgentFrontmatter {\n  const result = parseYaml(yamlStr) as Record<string, unknown>;\n  return {\n    description: (result.description as string) || '',\n    mode: (result.mode as string) || 'subagent',\n    permission: (result.permission as Record<string, unknown>) || {},\n    color: result.color as string | undefined,\n    maxSteps: result.maxSteps ? Number(result.maxSteps) : undefined,\n  };\n}\n\n/**\n * Read an agent markdown file and split into frontmatter + prompt.\n */\nfunction parseAgentFile(filePath: string): { name: string; config: Record<string, unknown> } {\n  const content = readFileSync(filePath, 'utf-8');\n  const name = basename(filePath, '.md');\n\n  // Split on ---\n  const parts = content.split('---');\n  if (parts.length < 3) {\n    throw new Error(`Invalid agent file: ${filePath} — missing frontmatter`);\n  }\n\n  const frontmatter = parseFrontmatter(parts[1].trim());\n  const prompt = parts.slice(2).join('---').trim();\n\n  const config: Record<string, unknown> = {\n    description: frontmatter.description,\n    mode: frontmatter.mode,\n    prompt,\n    permission: frontmatter.permission,\n  };\n\n  if (frontmatter.color) config.color = frontmatter.color;\n  if (frontmatter.maxSteps) config.maxSteps = frontmatter.maxSteps;\n\n  return { name, config };\n}\n\n/**\n * Load all agent configs from the bundled agents/ directory.\n * Returns partial results if some agent files fail to load.\n */\nfunction loadAgents(): Record<string, Record<string, unknown>> {\n  try {\n    const files = readdirSync(agentsDir).filter((f) => f.endsWith('.md'));\n    const agents: Record<string, Record<string, unknown>> = {};\n\n    for (const file of files) {\n      try {\n        const { name, config } = parseAgentFile(join(agentsDir, file));\n        agents[name] = config;\n      } catch (err) {\n        console.warn(`[maestria] Failed to parse agent file \"${file}\":`, err);\n      }\n    }\n\n    return agents;\n  } catch (err) {\n    console.warn(`[maestria] Failed to read agents directory:`, err);\n    return {};\n  }\n}\n\nexport const MaestriaPlugin: Plugin = async (_input, options?: MaestriaPluginOptions) => {\n  // Validate and parse options with zod\n  const parsed = maestriaOptionsSchema.parse(options ?? {});\n  const disabledKeywords = new Set<string>(\n    (parsed.modes?.disabledKeywords ?? []).map((k) => k.toLowerCase()),\n  );\n  const agents = loadAgents();\n\n  return {\n    config: async (input) => {\n      input.agent = {\n        ...input.agent,\n        ...agents,\n      };\n      input.instructions = [...(input.instructions ?? []), rulesPath];\n    },\n    'experimental.session.compacting': async (_input, output) => {\n      output.context.push(\n        'Session was compacted. Task tracking is maintained via todowrite. ' +\n          'Active context (files, decisions, blockers) was captured before compaction. ' +\n          'Continue where you left off.',\n      );\n    },\n    'chat.message': async (hookInput, hookOutput) => {\n      // Only fire for the orchestrator agent\n      if (hookInput.agent !== 'orchestrator') return;\n\n      // Find the first text part with user content\n      const textPart = hookOutput.parts.find((p) => p.type === 'text') as\n        | { text: string; type: 'text' }\n        | undefined;\n      if (!textPart) return;\n\n      // Detect keyword in the text\n      const result = detectMode(textPart.text, disabledKeywords);\n      if (!result) return;\n\n      // Strip keyword from text and prepend mode marker + prompt inline.\n      // We embed everything in the existing text part rather than injecting\n      // a second text part into `parts`, because the OpenCode runtime does\n      // not handle multiple text parts per message (causes a hang).\n      textPart.text = [\n        getModeMarker(result.mode),\n        '',\n        getModePrompt(result.mode),\n        '',\n        stripKeyword(textPart.text, result),\n      ].join('\\n');\n    },\n  };\n};\n\nexport default MaestriaPlugin;\n"],"mappings":"6OAeA,MAAa,EAAoB,EAAE,KAAK,CAAC,OAAQ,QAAS,OAAO,CAAC,EAMrD,EAAwB,EAAE,OAAO,CAC5C,MAAO,EACJ,OAAO,CACN,iBAAkB,EAAE,MAAM,CAAiB,CAAC,CAAC,SAAS,CACxD,CAAC,CAAC,CACD,SAAS,CACd,CAAC,ECnBY,EAA4C,CACvD,KAAM,CACJ,gCACA,GACA,0GACA,qEACA,0FACA,6DACA,mBACF,CAAC,CAAC,KAAK;CAAI,EAEX,MAAO,CACL,iCACA,GACA,6DACA,yDACA,gEACA,+DACF,CAAC,CAAC,KAAK;CAAI,EAEX,MAAO,CACL,uCACA,GACA,gEACA,8DACA,iEACA,4DACF,CAAC,CAAC,KAAK;CAAI,CACb,EAMa,EAA4C,CACvD,KAAM,eACN,MAAO,gBACP,MAAO,eACT,EAKa,EAAyC,CAAC,OAAQ,QAAS,OAAO,ECxCzE,EAA6C,CACjD,KAAM,EACN,MAAO,EACP,MAAO,CACT,EASM,EAAgB,0BAOtB,SAAS,EAAuB,EAAuC,CACrE,IAAM,EAAkC,CAAC,EACrC,EACJ,MAAQ,EAAQ,EAAc,KAAK,CAAI,KAAO,MAC5C,EAAO,KAAK,CAAC,EAAM,MAAO,EAAM,MAAQ,EAAM,EAAE,CAAC,MAAM,CAAC,EAE1D,OAAO,CACT,CAEA,SAAS,EAAW,EAAe,EAA0C,CAC3E,OAAO,EAAO,MAAM,CAAC,EAAO,KAAS,GAAS,GAAS,EAAQ,CAAG,CACpE,CAQA,SAAS,EAAkB,EAAyB,CAClD,OAAW,OAAO,MAAM,EAAa,CAAO,EAAE,KAAM,IAAI,CAC1D,CAgBA,SAAgB,EAAW,EAAc,EAA2C,CAClF,IAAM,EAAa,EAAuB,CAAI,EAExC,EAAqB,EACvB,IAAI,IAAI,MAAM,KAAK,CAAQ,CAAC,CAAC,IAAK,GAAM,EAAE,YAAY,CAAC,CAAC,EACxD,IAAA,GACA,EAA0E,KAE9E,IAAK,IAAM,KAAW,EAAgB,CACpC,GAAI,GAAoB,IAAI,CAAO,EAAG,SAEtC,IAAM,EAAQ,EAAkB,CAAO,EACnC,EAEJ,MAAQ,EAAQ,EAAM,KAAK,CAAI,KAAO,MAChC,EAAW,EAAM,MAAO,CAAU,IAElC,IAAc,MAAQ,EAAc,GAAW,EAAc,EAAU,SACzE,EAAY,CACV,QAAS,EAAM,GACf,MAAO,EAAM,MACb,KAAM,CACR,EAGN,CAIA,OAFI,IAAc,KAAa,KAExB,CACL,KAAM,EAAU,KAChB,QAAS,EAAU,QACnB,MAAO,EAAU,MACjB,OAAQ,EAAa,EAAU,MAC/B,OAAQ,EAAa,EAAU,KACjC,CACF,CAUA,SAAgB,EAAa,EAAc,EAA4B,CAUrE,OATe,EAAK,MAAM,EAAG,EAAO,KASvB,EARC,EAAK,MAAM,EAAO,MAAQ,EAAO,QAAQ,MAInC,CAAC,CAAC,QAAQ,QAAS,EAIhB,EAAA,CAAG,QAAQ,SAAU,GAAG,CAAC,CAAC,KAAK,CACxD,CAQA,SAAgB,EAAc,EAAsB,CAIlD,OAHI,EAAc,CAAI,EACb,EAAa,GAEf,EACT,CAQA,SAAgB,EAAc,EAAsB,CAIlD,OAHI,EAAc,CAAI,EACb,EAAa,GAEf,EACT,CAKA,SAAS,EAAc,EAAqC,CAC1D,OAAQ,EAAqC,SAAS,CAAK,CAC7D,CCtJA,MAAM,EAAY,EAAQ,EAAc,OAAO,KAAK,GAAG,CAAC,EAClD,EAAY,EAAK,EAAW,KAAM,QAAQ,EAC1C,EAAY,EAAK,EAAW,KAAM,QAAS,WAAW,EAU5D,SAAS,EAAiB,EAAmC,CAC3D,IAAM,EAASA,EAAU,CAAO,EAChC,MAAO,CACL,YAAc,EAAO,aAA0B,GAC/C,KAAO,EAAO,MAAmB,WACjC,WAAa,EAAO,YAA0C,CAAC,EAC/D,MAAO,EAAO,MACd,SAAU,EAAO,SAAW,OAAO,EAAO,QAAQ,EAAI,IAAA,EACxD,CACF,CAKA,SAAS,EAAe,EAAqE,CAC3F,IAAM,EAAU,EAAa,EAAU,OAAO,EACxC,EAAO,EAAS,EAAU,KAAK,EAG/B,EAAQ,EAAQ,MAAM,KAAK,EACjC,GAAI,EAAM,OAAS,EACjB,MAAU,MAAM,uBAAuB,EAAS,uBAAuB,EAGzE,IAAM,EAAc,EAAiB,EAAM,EAAE,CAAC,KAAK,CAAC,EAC9C,EAAS,EAAM,MAAM,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,EAEzC,EAAkC,CACtC,YAAa,EAAY,YACzB,KAAM,EAAY,KAClB,SACA,WAAY,EAAY,UAC1B,EAKA,OAHI,EAAY,QAAO,EAAO,MAAQ,EAAY,OAC9C,EAAY,WAAU,EAAO,SAAW,EAAY,UAEjD,CAAE,OAAM,QAAO,CACxB,CAMA,SAAS,GAAsD,CAC7D,GAAI,CACF,IAAM,EAAQ,EAAY,CAAS,CAAC,CAAC,OAAQ,GAAM,EAAE,SAAS,KAAK,CAAC,EAC9D,EAAkD,CAAC,EAEzD,IAAK,IAAM,KAAQ,EACjB,GAAI,CACF,GAAM,CAAE,OAAM,UAAW,EAAe,EAAK,EAAW,CAAI,CAAC,EAC7D,EAAO,GAAQ,CACjB,OAAS,EAAK,CACZ,QAAQ,KAAK,0CAA0C,EAAK,IAAK,CAAG,CACtE,CAGF,OAAO,CACT,OAAS,EAAK,CAEZ,OADA,QAAQ,KAAK,8CAA+C,CAAG,EACxD,CAAC,CACV,CACF,CAEA,MAAa,EAAyB,MAAO,EAAQ,IAAoC,CAEvF,IAAM,EAAS,EAAsB,MAAM,GAAW,CAAC,CAAC,EAClD,EAAmB,IAAI,KAC1B,EAAO,OAAO,kBAAoB,CAAC,EAAA,CAAG,IAAK,GAAM,EAAE,YAAY,CAAC,CACnE,EACM,EAAS,EAAW,EAE1B,MAAO,CACL,OAAQ,KAAO,IAAU,CACvB,EAAM,MAAQ,CACZ,GAAG,EAAM,MACT,GAAG,CACL,EACA,EAAM,aAAe,CAAC,GAAI,EAAM,cAAgB,CAAC,EAAI,CAAS,CAChE,EACA,kCAAmC,MAAO,EAAQ,IAAW,CAC3D,EAAO,QAAQ,KACb,4KAGF,CACF,EACA,eAAgB,MAAO,EAAW,IAAe,CAE/C,GAAI,EAAU,QAAU,eAAgB,OAGxC,IAAM,EAAW,EAAW,MAAM,KAAM,GAAM,EAAE,OAAS,MAAM,EAG/D,GAAI,CAAC,EAAU,OAGf,IAAM,EAAS,EAAW,EAAS,KAAM,CAAgB,EACpD,IAML,EAAS,KAAO,CACd,EAAc,EAAO,IAAI,EACzB,GACA,EAAc,EAAO,IAAI,EACzB,GACA,EAAa,EAAS,KAAM,CAAM,CACpC,CAAC,CAAC,KAAK;CAAI,EACb,CACF,CACF"}
+{"version":3,"file":"index.js","names":["parseYaml"],"sources":["../src/modes/types.ts","../src/modes/prompts.ts","../src/modes/index.ts","../src/index.ts"],"sourcesContent":["/**\n * Types for keyword-triggered workflow modes.\n *\n * @see ADR-OC-003 for full design context.\n */\n\nimport { z } from 'zod';\n\n/**\n * Valid mode keywords.\n *\n * - `\"fein\"` -- Full pipeline (recon -> design -> build -> review)\n * - `\"sonar\"` -- Research only (recon + design, stop before build)\n * - `\"blitz\"` -- Fast implementation (builder direct, skip recon/design/review)\n */\nexport const modeKeywordSchema = z.enum(['fein', 'sonar', 'blitz']);\nexport type ModeKeyword = z.infer<typeof modeKeywordSchema>;\n\n/**\n * Plugin-level options for @maestria/opencode.\n */\nexport const maestriaOptionsSchema = z.object({\n  modes: z\n    .object({\n      disabledKeywords: z.array(modeKeywordSchema).optional(),\n    })\n    .optional(),\n});\nexport type MaestriaPluginOptions = z.infer<typeof maestriaOptionsSchema>;\n\n/**\n * Result returned when a mode keyword is detected in a message.\n */\nexport interface ModeResult {\n  /** The resolved mode keyword (lowercase). */\n  mode: ModeKeyword;\n  /** The keyword string as matched in the original text. */\n  keyword: string;\n  /** The character index where the keyword starts in the original text. */\n  index: number;\n  /** The mode prompt text to inject. */\n  prompt: string;\n  /** The mode marker string like `[MODE: fein]`. */\n  marker: string;\n}\n","import type { ModeKeyword } from '@/modes/types.js';\n\n/**\n * Mode prompt text for each keyword.\n * These are injected into the turn when a mode is detected.\n *\n * @see ADR-OC-003 (section \"Mode Prompts\")\n */\nexport const MODE_PROMPTS: Record<ModeKeyword, string> = {\n  fein: [\n    '## MODE: fein (Full Pipeline)',\n    '',\n    'Default role-based pipeline: thinker (recon/design/plan) → worker (implementation) → verifier (review).',\n    'Verifier acceptance terminates the pipeline for that unit of work.',\n    'Roles and order may adapt to task needs - this is the default, not a fixed requirement.',\n    'Do NOT skip any phase unless the user explicitly overrides',\n    'in the same turn.',\n  ].join('\\n'),\n\n  sonar: [\n    '## MODE: sonar (Research Only)',\n    '',\n    'Research mode: reconnaissance and design only. Delegate to',\n    '@adventurer (recon) followed by @architect or @planner',\n    '(analysis/design). STOP after delivering findings and design.',\n    'Do NOT implement, write code, or create any production files.',\n  ].join('\\n'),\n\n  blitz: [\n    '## MODE: blitz (Fast Implementation)',\n    '',\n    'Speed mode: skip reconnaissance and design gates. Go directly',\n    'to @builder for implementation. Only use @adventurer if the',\n    'codebase context is genuinely unknown (not as a default step).',\n    'Skip @reviewer unless the user explicitly requests review.',\n  ].join('\\n'),\n};\n\n/**\n * Marker strings for each mode keyword, used to signal the active mode.\n * Format: `[MODE: <keyword>]`\n */\nexport const MODE_MARKERS: Record<ModeKeyword, string> = {\n  fein: '[MODE: fein]',\n  sonar: '[MODE: sonar]',\n  blitz: '[MODE: blitz]',\n};\n\n/**\n * Array of all valid mode keywords for runtime iteration.\n */\nexport const VALID_KEYWORDS: readonly ModeKeyword[] = ['fein', 'sonar', 'blitz'];\n","import { escapeRegExp } from 'es-toolkit';\nimport { MODE_PROMPTS, MODE_MARKERS, VALID_KEYWORDS } from '@/modes/prompts.js';\nimport type { ModeKeyword, ModeResult } from '@/modes/types.js';\n\n/**\n * Priority mapping for mode keyword restrictiveness.\n * Higher number = more restrictive = wins when multiple keywords are present.\n * fein (3): full pipeline with mandatory gates\n * sonar (2): research only, no code\n * blitz (1): fast implementation, skip all gates\n */\nconst MODE_PRIORITY: Record<ModeKeyword, number> = {\n  fein: 3,\n  sonar: 2,\n  blitz: 1,\n};\n\n/**\n * Regex matching fenced code blocks (```) and inline backtick spans (`).\n * Used to exclude keyword matches inside code spans.\n */\n// Note: Unclosed fenced code blocks (``` without closing ```) are not\n// excluded - the regex requires matching fences. This is an accepted\n// false-positive risk (see ADR-OC-003 consequences).\nconst CODE_BLOCK_RE = /```[\\s\\S]*?```|`[^`]*`/g;\n\n/**\n * Find ranges of code blocks and inline code spans in text.\n * Returns [start, end) positions. Keywords inside these ranges\n * are ignored during detection.\n */\nfunction findAllCodeBlockRanges(text: string): Array<[number, number]> {\n  const ranges: Array<[number, number]> = [];\n  let match: RegExpExecArray | null;\n  while ((match = CODE_BLOCK_RE.exec(text)) !== null) {\n    ranges.push([match.index, match.index + match[0].length]);\n  }\n  return ranges;\n}\n\nfunction isInRanges(index: number, ranges: Array<[number, number]>): boolean {\n  return ranges.some(([start, end]) => index >= start && index < end);\n}\n\n/**\n * Build a regex pattern for word-boundary matching of the given keyword.\n *\n * The pattern uses `\\b` word boundaries to ensure we match whole words only,\n * and is case-insensitive so `Fein`, `FEIN`, `fein` all match.\n */\nfunction buildKeywordRegex(keyword: string): RegExp {\n  return new RegExp(`\\\\b${escapeRegExp(keyword)}\\\\b`, 'gi');\n}\n\n/**\n * Detect a workflow mode keyword in the given text.\n *\n * Detection rules (per ADR-OC-003):\n * - Word-boundary regex matching (`\\bfein\\b`, `\\bsonar\\b`, `\\bblitz\\b`)\n * - Most restrictive match wins (fein > sonar > blitz)\n * - Case-insensitive\n * - Disabled keywords are ignored\n * - Matches inside fenced code blocks (```) and inline backticks (`) are ignored\n *\n * @param text The user message to scan.\n * @param disabled Optional set of disabled mode keywords (lowercase).\n * @returns A `ModeResult` if a keyword was detected, or `null`.\n */\nexport function detectMode(text: string, disabled?: Set<string>): ModeResult | null {\n  const codeRanges = findAllCodeBlockRanges(text);\n  // Normalize disabled keywords to lowercase for case-insensitive comparison\n  const normalizedDisabled = disabled\n    ? new Set(Array.from(disabled).map((k) => k.toLowerCase()))\n    : undefined;\n  let bestMatch: { keyword: string; index: number; mode: ModeKeyword } | null = null;\n\n  for (const keyword of VALID_KEYWORDS) {\n    if (normalizedDisabled?.has(keyword)) continue;\n\n    const regex = buildKeywordRegex(keyword);\n    let match: RegExpExecArray | null;\n\n    while ((match = regex.exec(text)) !== null) {\n      if (isInRanges(match.index, codeRanges)) continue;\n      // Most-restrictive wins: prefer higher-priority mode over position\n      if (bestMatch === null || MODE_PRIORITY[keyword] > MODE_PRIORITY[bestMatch.mode]) {\n        bestMatch = {\n          keyword: match[0],\n          index: match.index,\n          mode: keyword,\n        };\n      }\n    }\n  }\n\n  if (bestMatch === null) return null;\n\n  return {\n    mode: bestMatch.mode,\n    keyword: bestMatch.keyword,\n    index: bestMatch.index,\n    prompt: MODE_PROMPTS[bestMatch.mode],\n    marker: MODE_MARKERS[bestMatch.mode],\n  };\n}\n\n/**\n * Remove the matched keyword from the text, cleaning up any trailing colon\n * or whitespace that may follow it.\n *\n * @param text The original message text.\n * @param result The `ModeResult` from `detectMode()`.\n * @returns The text with the keyword stripped.\n */\nexport function stripKeyword(text: string, result: ModeResult): string {\n  const before = text.slice(0, result.index);\n  const after = text.slice(result.index + result.keyword.length);\n\n  // Remove any colon + optional whitespace after the keyword\n  // (e.g. \"fein: do this\" -> \"do this\")\n  const cleaned = after.replace(/^:\\s*/, '');\n\n  // Collapse double spaces and trim both ends (handles keyword at start,\n  // end, or middle of text, plus extra whitespace around colon)\n  return (before + cleaned).replace(/ {2,}/g, ' ').trim();\n}\n\n/**\n * Get the mode prompt text for a given mode name.\n *\n * @param mode The mode keyword (e.g. \"fein\", \"sonar\", \"blitz\").\n * @returns The prompt string, or empty string if mode is unknown.\n */\nexport function getModePrompt(mode: string): string {\n  if (isModeKeyword(mode)) {\n    return MODE_PROMPTS[mode];\n  }\n  return '';\n}\n\n/**\n * Get the mode marker string for a given mode name.\n *\n * @param mode The mode keyword (e.g. \"fein\", \"sonar\", \"blitz\").\n * @returns The marker string (e.g. `[MODE: fein]`), or empty string if unknown.\n */\nexport function getModeMarker(mode: string): string {\n  if (isModeKeyword(mode)) {\n    return MODE_MARKERS[mode];\n  }\n  return '';\n}\n\n/**\n * Type guard to check if a string is a valid ModeKeyword.\n */\nfunction isModeKeyword(value: string): value is ModeKeyword {\n  return (VALID_KEYWORDS as readonly string[]).includes(value);\n}\n","import type { Plugin } from '@opencode-ai/plugin';\nimport { readFileSync, readdirSync } from 'fs';\nimport { join, dirname, basename } from 'path';\nimport { parse as parseYaml } from 'yaml';\nimport { fileURLToPath } from 'url';\nimport { type MaestriaPluginOptions, maestriaOptionsSchema } from '@/modes/types.js';\nimport { detectMode, stripKeyword, getModeMarker, getModePrompt } from '@/modes/index.js';\n\nconst __dirname = dirname(fileURLToPath(import.meta.url));\nconst agentsDir = join(__dirname, '..', 'agents');\nconst rulesPath = join(__dirname, '..', 'rules', 'AGENTS.md');\n\ninterface AgentFrontmatter {\n  description: string;\n  mode: string;\n  permission: Record<string, unknown>;\n  color?: string;\n  maxSteps?: number;\n}\n\nfunction parseFrontmatter(yamlStr: string): AgentFrontmatter {\n  const result = parseYaml(yamlStr) as Record<string, unknown>;\n  return {\n    description: (result.description as string) || '',\n    mode: (result.mode as string) || 'subagent',\n    permission: (result.permission as Record<string, unknown>) || {},\n    color: result.color as string | undefined,\n    maxSteps: result.maxSteps ? Number(result.maxSteps) : undefined,\n  };\n}\n\n/**\n * Read an agent markdown file and split into frontmatter + prompt.\n */\nfunction parseAgentFile(filePath: string): { name: string; config: Record<string, unknown> } {\n  const content = readFileSync(filePath, 'utf-8');\n  const name = basename(filePath, '.md');\n\n  // Split on ---\n  const parts = content.split('---');\n  if (parts.length < 3) {\n    throw new Error(`Invalid agent file: ${filePath} - missing frontmatter`);\n  }\n\n  const frontmatter = parseFrontmatter(parts[1].trim());\n  const prompt = parts.slice(2).join('---').trim();\n\n  const config: Record<string, unknown> = {\n    description: frontmatter.description,\n    mode: frontmatter.mode,\n    prompt,\n    permission: frontmatter.permission,\n  };\n\n  if (frontmatter.color) config.color = frontmatter.color;\n  if (frontmatter.maxSteps) config.maxSteps = frontmatter.maxSteps;\n\n  return { name, config };\n}\n\n/**\n * Load all agent configs from the bundled agents/ directory.\n * Returns partial results if some agent files fail to load.\n */\nfunction loadAgents(): Record<string, Record<string, unknown>> {\n  try {\n    const files = readdirSync(agentsDir).filter((f) => f.endsWith('.md'));\n    const agents: Record<string, Record<string, unknown>> = {};\n\n    for (const file of files) {\n      try {\n        const { name, config } = parseAgentFile(join(agentsDir, file));\n        agents[name] = config;\n      } catch (err) {\n        console.warn(`[maestria] Failed to parse agent file \"${file}\":`, err);\n      }\n    }\n\n    return agents;\n  } catch (err) {\n    console.warn(`[maestria] Failed to read agents directory:`, err);\n    return {};\n  }\n}\n\nexport const MaestriaPlugin: Plugin = async (_input, options?: MaestriaPluginOptions) => {\n  // Validate and parse options with zod\n  const parsed = maestriaOptionsSchema.parse(options ?? {});\n  const disabledKeywords = new Set<string>(\n    (parsed.modes?.disabledKeywords ?? []).map((k) => k.toLowerCase()),\n  );\n  const agents = loadAgents();\n\n  return {\n    config: async (input) => {\n      input.agent = {\n        ...input.agent,\n        ...agents,\n      };\n      input.instructions = [...(input.instructions ?? []), rulesPath];\n    },\n    'experimental.session.compacting': async (_input, output) => {\n      output.context.push(\n        'Session was compacted. Task tracking is maintained via todowrite. ' +\n          'Active context (files, decisions, blockers) was captured before compaction. ' +\n          'Continue where you left off.',\n      );\n    },\n    'chat.message': async (hookInput, hookOutput) => {\n      // Only fire for the orchestrator agent\n      if (hookInput.agent !== 'orchestrator') return;\n\n      // Find the first text part with user content\n      const textPart = hookOutput.parts.find((p) => p.type === 'text') as\n        | { text: string; type: 'text' }\n        | undefined;\n      if (!textPart) return;\n\n      // Detect keyword in the text\n      const result = detectMode(textPart.text, disabledKeywords);\n      if (!result) return;\n\n      // Strip keyword from text and prepend mode marker + prompt inline.\n      // We embed everything in the existing text part rather than injecting\n      // a second text part into `parts`, because the OpenCode runtime does\n      // not handle multiple text parts per message (causes a hang).\n      textPart.text = [\n        getModeMarker(result.mode),\n        '',\n        getModePrompt(result.mode),\n        '',\n        stripKeyword(textPart.text, result),\n      ].join('\\n');\n    },\n  };\n};\n\nexport default MaestriaPlugin;\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maestria/opencode",
-  "version": "0.4.9",
+  "version": "0.5.1",
   "description": "OpenCode plugin encoding AI engineering praxis: rules, agents, and workflow discipline.",
   "keywords": [
     "agents",
@@ -41,7 +41,8 @@
   "dependencies": {
     "es-toolkit": "^1.47.1",
     "yaml": "^2.7.0",
-    "zod": "^3.24.0"
+    "zod": "^3.24.0",
+    "@maestria/core": "0.3.1"
   },
   "devDependencies": {
     "@opencode-ai/plugin": "^1.17.0",

package/rules/AGENTS.md

@@ -5,21 +5,30 @@
 
 ## Orchestration
 
-- **!!! Don't assume** — verify against actual code and docs. Guesses lead to bugs.
-- **!!! 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; 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 GitHub/GitLab/BitBucket repo or any multi-file code reference, run `opensrc path <owner/repo>` (e.g. `opensrc path facebook/react`). It clones to a global cache and prints a path that `read`/`glob`/`grep` can use directly. For a single file, a specific page, or a known URL, `webfetch` is fine. Don't fetch an entire repo one file at a 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.
+- **!!! Don't assume** - verify against actual code and docs. Guesses lead to bugs.
+- **!!! 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; treat it seriously.
+- **!!! Don't anthropomorphize effort** - You operate at machine scale. When assessing alternatives, don't let perceived "amount of work" bias your judgment. What feels like a lot of work to a human is routine iteration for you. Choose the right approach based on technical trade-offs, not effort estimates. Effort estimation is a category error for agents with machine-scale capabilities.
+
+- **Don't reference internal project names in explanations** - avoid leaking context outside the workspace.
+- **Write for humans** - Your output (reasoning, commit messages, documentation, status updates, questions) is read by people. Avoid AI-typical patterns: em dash overuse (-), inflated language, and promotional phrasing. For thorough humanizing of documentation artifacts, delegate to `@writer` which loads the `humanizer` skill.
+- **Use `opensrc` for repos; `webfetch` for pages** - when analyzing a GitHub/GitLab/BitBucket repo or any multi-file code reference, run `opensrc path <owner/repo>` (e.g. `opensrc path facebook/react`). It clones to a global cache and prints a path that `read`/`glob`/`grep` can use directly. For a single file, a specific page, or a known URL, `webfetch` is fine. Don't fetch an entire repo one file at a 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.
+- **Project `.maestria/`** - `.maestria/workflow.md` and `.maestria/rules.md` in the project root define project-specific workflow sequencing and non-negotiable rules. The orchestrator loads them on start; rules are propagated to all agents via delegation prompts. 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:**
-  1. `webfetch` — fetch a specific known URL (for docs, pages)
-  2. `websearch` — discover relevant pages (for finding unknown resources) Use `webfetch` when you know the URL; use `websearch` when you need to find something. `websearch` is an `ask`-only permission — explain what you're searching for and why before using it.
+  1. `webfetch` - fetch a specific known URL (for docs, pages)
+  2. `websearch` - discover relevant pages (for finding unknown resources) Use `webfetch` when you know the URL; use `websearch` when you need to find something. `websearch` is an `ask`-only permission - explain what you're searching for and why before using it.
+
+## Principles
+
+- **Start from first principles** - before adopting an existing pattern or solution, verify it actually matches the fundamental problem. Prior art is a reference, not a constraint.
+- **Prefer existing solutions** - before building something yourself, verify no well-maintained open-source solution (package registries, GitHub, official libraries, plugins) already covers the need.
 
 ## Delegation
 
-When delegating work via `task()`, use only the 7 specialists below. **Never delegate to `explore` or `general`** — they are built-in agents, not part of the pipeline.
+When delegating work via `task()`, use only the 7 specialists below. **Never delegate to `explore` or `general`** - they are built-in agents, not part of the pipeline.
 
 | Agent | Role | When to Delegate |
 | --- | --- | --- |
@@ -33,10 +42,10 @@ When delegating work via `task()`, use only the 7 specialists below. **Never del
 
 ## Context Management
 
-- **Progressive disclosure** — start high-level, get specific as needed.
-- **State checkpointing** — periodically summarize what's done, what's in progress, what's next.
-- **Context pruning** — remove irrelevant context when no longer needed.
-- **Completion promises** — define success criteria before starting work. "This task is complete when [verifiable conditions]."
+- **Progressive disclosure** - start high-level, get specific as needed.
+- **State checkpointing** - periodically summarize what's done, what's in progress, what's next.
+- **Context pruning** - remove irrelevant context when no longer needed.
+- **Completion promises** - define success criteria before starting work. "This task is complete when [verifiable conditions]."
 
 ## Commit Policy