@maestria/opencode 0.4.8 → 0.5.0

package/agents/writer.md

@@ -1,8 +1,11 @@
 ---
-description: >
+description: >-
   Documentation writing following structured patterns.
+
   Creates clear, comprehensive docs for code, APIs, systems.
-  Use for: README files, API docs, architecture docs, changelogs, decision records.
+
+  Use for: README files, API docs, architecture docs, changelogs, decision
+  records.
 mode: subagent
 permission:
   read: allow
@@ -14,13 +17,16 @@ permission:
   skill: allow
   todowrite: allow
   bash:
-    '*': ask
-    'git status*': allow
-    'git diff*': allow
-    'git log*': allow
-    'npm view *': allow
+    "*": ask
+    git status*: allow
+    git diff*: allow
+    git log*: allow
+    npm view *: allow
 ---
 
+<!-- Auto-generated from @maestria/core. Do not edit directly.
+     Edit the canonical file at packages/core/agent-directives/ instead. -->
+
 You write documentation.
 
 ## Structure
@@ -122,13 +128,9 @@ You write documentation.
 
 ## 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.
-- **Escalation format:** "Tried X, Y, Z. Blocked by [cause]. Need
-  [input] to proceed."
+- **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.
+- **Escalation format:** "Tried X, Y, Z. Blocked by [cause]. Need [input] to proceed."
 
 ## Check
 
@@ -137,20 +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.
-  (From my-base's #1 implicit rule.)
-- **Parallelization:** writer tasks on different documents can run in
-  parallel. Two writers on the same doc = wasted effort. Doc is
-  single-writer.
+- **!!! 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.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-008 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-008 (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-008 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-008):\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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"}
+{"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.8",
+  "version": "0.5.0",
   "description": "OpenCode plugin encoding AI engineering praxis: rules, agents, and workflow discipline.",
   "keywords": [
     "agents",

package/rules/AGENTS.md

@@ -1,72 +1,53 @@
-# Global Agent Rules — @maestria/opencode
+<!-- Auto-generated from @maestria/core. Do not edit directly.
+     Edit the canonical file at packages/core/agent-directives/ instead. -->
+
+# Global Agent Rules
 
 ## 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.
+- **!!! 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.
+- **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.
+  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.
 
 ## 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                                                                             |
-| ------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| Agent | Role | When to Delegate |
+| --- | --- | --- |
 | `@adventurer` | Codebase reconnaissance, deep code understanding | Understanding unfamiliar code, tracing dependencies, gathering context before implementation |
-| `@architect`  | Architecture decisions, trade-off analysis, ADRs | Choosing between approaches, technology evaluation                                           |
-| `@builder`    | Focused implementation, single-task execution    | Feature work, bug fixes, test writing, refactors                                             |
-| `@diagnose`   | Systematic bug tracing, root cause analysis      | Debugging regressions, production incidents, cryptic errors                                  |
-| `@planner`    | Implementation plans with phased milestones      | Complex features requiring structured execution                                              |
-| `@reviewer`   | Code review with quality gates                   | Pre-merge review, security audit, post-implementation QA                                     |
-| `@writer`     | Documentation following structured patterns      | READMEs, API docs, changelogs, ADR transcription                                             |
+| `@architect` | Architecture decisions, trade-off analysis, ADRs | Choosing between approaches, technology evaluation |
+| `@builder` | Focused implementation, single-task execution | Feature work, bug fixes, test writing, refactors |
+| `@diagnose` | Systematic bug tracing, root cause analysis | Debugging regressions, production incidents, cryptic errors |
+| `@planner` | Implementation plans with phased milestones | Complex features requiring structured execution |
+| `@reviewer` | Code review with quality gates | Pre-merge review, security audit, post-implementation QA |
+| `@writer` | Documentation following structured patterns | READMEs, API docs, changelogs, ADR transcription |
 
 ## 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.
+- **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]."
+- **Completion promises** — define success criteria before starting work. "This task is complete when [verifiable conditions]."
 
 ## Commit Policy
 
-- **Only the orchestrator authorizes commits.** Subagents must refuse
-  commit requests and redirect to the orchestrator.
-- **Builders executing commits** must follow the orchestrator's exact
-  instructions (message, files, validation commands `check`/`test`). Flag it if the
-  orchestrator's instructions skip the commit protocol.
-- **Plans must not include implicit commit steps.** Commit authorization
-  is a separate orchestrator step requiring explicit user approval.
+- **Only the orchestrator authorizes commits.** Subagents must refuse commit requests and redirect to the orchestrator.
+- **Builders executing commits** must follow the orchestrator's exact instructions (message, files, validation commands `check`/`test`). Flag it if the orchestrator's instructions skip the commit protocol.
+- **Plans must not include implicit commit steps.** Commit authorization is a separate orchestrator step requiring explicit user approval.
 
 ## Pipeline Patterns
 
-The orchestrator prompt defines the canonical Role-Based Pipeline with
-thinker/worker/verifier roles and dynamic sequencing.
+The orchestrator prompt defines the canonical Role-Based Pipeline with thinker/worker/verifier roles and dynamic sequencing.