@maestria/prime-agent 0.3.7 → 0.3.9

package/dist/extension.mjs

@@ -1,3 +1,3 @@
-import e from"node:path";import{readFileSync as t}from"node:fs";const n=()=>({mode:null}),r=e=>e.type===`custom`&&`customType`in e&&e.customType===`maestria_mode`,i=e=>{if(typeof e!=`object`||!e||!(`mode`in e))return!1;let{mode:t}=e;return t===null||t===`fein`||t===`sonar`||t===`blitz`},a=e=>{if(!Array.isArray(e))return null;for(let t=e.length-1;t>=0;--t){let n=e[t];if(r(n)&&i(n.data))return n.data}return null},o=(e,t)=>{e.appendEntry(`maestria_mode`,{mode:t.mode})},s=(e,t)=>{e.mode=a(t)?.mode??null},c=[`fein`,`sonar`,`blitz`],l={blitz:`[MODE: blitz]`,fein:`[MODE: fein]`,sonar:`[MODE: sonar]`},u={blitz:`Set workflow mode to blitz (fast path)`,fein:`Set workflow mode to fein (full pipeline)`,sonar:`Set workflow mode to sonar (research only)`},d={},f=(n,r)=>{let i=d[n];if(i!==void 0)return i;let a=``;try{let i=t(e.join(r,n,`SKILL.md`),`utf-8`),o=i.indexOf(`## MODE:`);if(o===-1)console.warn(`[maestria] prime-agent: mode skill "${n}" has no "## MODE:" heading; mode prompt injection disabled for this mode.`);else{let e=i.slice(o);a=`${l[n]}\n\n${e.replace(/\s+$/u,``)}\n`}}catch(e){console.warn(`[maestria] prime-agent: failed to load mode skill "${n}" from ${r}; mode prompt injection disabled for this mode.`,e)}return d[n]=a,a},p=(e,t)=>n=>{if(!e.mode)return;let r=f(e.mode,t);if(r)return{systemPrompt:[n.systemPrompt,``,r,``,`The user has set workflow mode to "${e.mode}". Honor this mode throughout the session until it is changed or cleared.`].join(`
-`)}},m=(e,t)=>{for(let n of c)e.registerCommand(n,{description:u[n],handler:async(r,i)=>{t.mode=n,o(e,t),r.trim()?e.sendUserMessage(r.trim(),{deliverAs:`steer`}):i.ui.notify(`Mode set to ${n}. Describe what you'd like to work on.`),await Promise.resolve()}});e.registerCommand(`mode-clear`,{description:`Clear workflow mode and return to neutral routing`,handler:async(n,r)=>{t.mode=null,o(e,t),r.ui.notify(`Workflow mode cleared. Neutral routing is active.`),await Promise.resolve()}}),e.registerCommand(`maestria-status`,{description:`Show the current maestria workflow mode and extension subset`,handler:async(e,n)=>{let r=[`# Maestria status (prime-agent)`,``,`Workflow mode: ${t.mode??`none`}`,``,`Commands: /fein, /sonar, /blitz, /mode-clear`,``,`This extension covers mode selection and mode prompt injection only.`,`Recursive-subagent (rlm) dispatch and JSON/RPC headless mode are NOT provided by this package.`].join(`
-`);n.ui.setEditorText(r),await Promise.resolve()}})},h=()=>{let t=import.meta.dirname;return e.resolve(t,`../skills`)},g=e=>{let t=n(),r=h();m(e,t),e.on(`before_agent_start`,p(t,r)),e.on(`session_start`,(e,n)=>{s(t,n.sessionManager.getBranch())}),e.on(`session_tree`,(e,n)=>{s(t,n.sessionManager.getBranch())})};export{g as default};
+import e from"node:path";import{readFileSync as t}from"node:fs";const n=[`fein`,`sonar`,`blitz`],r={blitz:`[MODE: blitz]`,fein:`[MODE: fein]`,sonar:`[MODE: sonar]`},i=e=>{let t=e.indexOf(`## MODE:`);return t===-1?`${e.replace(/\s+$/u,``)}\n`:`${e.slice(t).replace(/\s+$/u,``)}\n`},a=()=>({mode:null}),o=e=>e.type===`custom`&&`customType`in e&&e.customType===`maestria_mode`,s=e=>{if(typeof e!=`object`||!e||!(`mode`in e))return!1;let{mode:t}=e;return t===null||t===`fein`||t===`sonar`||t===`blitz`},c=e=>{if(!Array.isArray(e))return null;for(let t=e.length-1;t>=0;--t){let n=e[t];if(o(n)&&s(n.data))return n.data}return null},l=(e,t)=>{e.appendEntry(`maestria_mode`,{mode:t.mode})},u=(e,t)=>{e.mode=c(t)?.mode??null},d={blitz:`Set workflow mode to blitz (fast path)`,fein:`Set workflow mode to fein (full pipeline)`,sonar:`Set workflow mode to sonar (research only)`},f={},p=(n,a)=>{let o=f[n];if(o!==void 0)return o;let s=``;try{let o=t(e.join(a,n,`SKILL.md`),`utf-8`);o.includes(`## MODE:`)?s=`${r[n]}\n\n${i(o)}`:console.warn(`[maestria] prime-agent: mode skill "${n}" has no "## MODE:" heading; mode prompt injection disabled for this mode.`)}catch(e){console.warn(`[maestria] prime-agent: failed to load mode skill "${n}" from ${a}; mode prompt injection disabled for this mode.`,e)}return f[n]=s,s},m=(e,t)=>n=>{if(!e.mode)return;let r=p(e.mode,t);if(r)return{systemPrompt:[n.systemPrompt,``,r,``,`The user has set workflow mode to "${e.mode}". Honor this mode throughout the session until it is changed or cleared.`].join(`
+`)}},h=(e,t)=>{for(let r of n)e.registerCommand(r,{description:d[r],handler:async(n,i)=>{t.mode=r,l(e,t),n.trim()?e.sendUserMessage(n.trim(),{deliverAs:`steer`}):i.ui.notify(`Mode set to ${r}. Describe what you'd like to work on.`),await Promise.resolve()}});e.registerCommand(`mode-clear`,{description:`Clear workflow mode and return to neutral routing`,handler:async(n,r)=>{t.mode=null,l(e,t),r.ui.notify(`Workflow mode cleared. Neutral routing is active.`),await Promise.resolve()}}),e.registerCommand(`maestria-status`,{description:`Show the current maestria workflow mode and extension subset`,handler:async(e,n)=>{let r=[`# Maestria status (prime-agent)`,``,`Workflow mode: ${t.mode??`none`}`,``,`Commands: /fein, /sonar, /blitz, /mode-clear`,``,`This extension covers mode selection and mode prompt injection only.`,`Recursive-subagent (rlm) dispatch and JSON/RPC headless mode are NOT provided by this package.`].join(`
+`);n.ui.setEditorText(r),await Promise.resolve()}})},g=()=>{let t=import.meta.dirname;return e.resolve(t,`../skills`)},_=e=>{let t=a(),n=g();h(e,t),e.on(`before_agent_start`,m(t,n)),e.on(`session_start`,(e,n)=>{u(t,n.sessionManager.getBranch())}),e.on(`session_tree`,(e,n)=>{u(t,n.sessionManager.getBranch())})};export{_ as default};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maestria/prime-agent",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "private": false,
   "description": "Maestria methodology for Prime Agent - specialist roles, orchestrator, global rules, and workflow modes as Agent Skills, plus a small Prime/Pi extension for mode commands and mode prompt injection",
   "keywords": [
@@ -36,6 +36,7 @@
     "provenance": true
   },
   "devDependencies": {
+    "@maestria/shared-mode": "0.1.0",
     "@types/node": "^26.5.1",
     "typescript": "^7.0.2",
     "vite-plus": "0.3.1",

package/skills/adventurer/SKILL.md

@@ -1,11 +1,5 @@
 ---
-description: |-
-  Codebase reconnaissance skill. Maps unknown territory -
-  traces call chains, maps module relationships, generates structured recon
-  reports for downstream work. Read-only role intent: exploration and reporting
-  only, never implementation or design.
-  Use for: understanding unfamiliar code, tracing dependencies, gathering context
-  before implementation, investigating module structures.
+description: Codebase reconnaissance skill for mapping unfamiliar code, tracing call chains, and reporting verified context without implementing changes.
 name: adventurer
 ---
 

package/skills/architect/SKILL.md

@@ -1,9 +1,5 @@
 ---
-description: |-
-  Architecture decisions using decision matrices and ADRs.
-  Evaluates options with weighted criteria, clarifies business context first.
-  Use for: technology choices, implementation approaches, trade-off analysis,
-  threat modeling, or ADR decisions.
+description: Architecture decision skill for comparing implementation approaches, boundaries, threat models, and ADR decisions.
 name: architect
 ---
 

package/skills/builder/SKILL.md

@@ -1,8 +1,5 @@
 ---
-description: |-
-  Focused implementation skill for atomic tasks. Executes
-  one verifiable unit of work with minimal context and a clean diff.
-  Use for: targeted fixes, feature implementation, refactors, adding tests.
+description: Focused implementation skill for one atomic, verifiable feature, fix, test, or refactor.
 name: builder
 ---
 
@@ -27,8 +24,8 @@ If the assignment contains unrelated outcomes, report the decomposition to the o
 
 1. **Read** - Load the relevant files and understand context
 2. **Edit** - Make the minimal change required to satisfy the task
-3. **Verify** - Run tests or type checks to confirm correctness
-4. **Report** - State what changed and why
+3. **Verify** - Establish acceptance for the changed behavior using the global evidence contract
+4. **Report** - State what changed and why, with evidence artifacts and unresolved verification gaps
 
 ## Implementation Judgment
 

package/skills/diagnose/SKILL.md

@@ -1,8 +1,5 @@
 ---
-description: |-
-  Evidence-led regression tracing: from error message
-  to root cause to prevention.
-  Use for: cryptic errors, regressions, production bugs, unclear root causes.
+description: Systematic regression-tracing skill from symptom and error evidence to root cause, fix, and prevention.
 name: diagnose
 ---
 

package/skills/global-rules/SKILL.md

@@ -26,6 +26,7 @@ Cross-platform behavior contract for outcomes, evidence, safety, delegation, rev
 - **!!! Exhaust available evidence before asking.** Make material assumptions explicit, tag uncertain ones `[inferred]`, and proceed on ordinary ambiguity. Ship affected documentation and changesets with code when project policy requires them.
 - **!!! Exercise testing judgment, not coverage.** Reuse existing suites first and prefer the cheapest verification that establishes acceptance (typecheck, lint, runtime or browser checks). Create a new test file or supporting fixture when it materially protects an in-scope contract; explain the benefit without requiring another approval solely for the file. Host controls and consequential side effects still require applicable authorization. Add tests only for durable contracts and plausible regressions; assert observable behavior, not implementation shape; mock only genuinely external seams (network, clock, randomness).
 - **!!! Keep output self-contained and professional.** Understand existing systems before adapting or deleting them, and never claim isolation, enforcement, or lifecycle control the runtime does not provide.
+- **!!! Keep output economical.** Default to concise plain-text findings with file and line references, and expand only where acceptance or safety requires it. Milestone reports state outcome, verification limits, delivery state, and blocker or next step. Match surrounding doc tone for prose tasks.
 - **!!! Human-facing output.** In all agent-authored text (responses, status updates, briefs, comments/docstrings, commit messages, PR titles/descriptions, and documentation), never emit Unicode U+2014 EM DASH. Prefer commas, colons, parentheses, or ASCII hyphen-minus (`-`). Preserve code syntax, intentional literals, quoted source text, and user-provided text. Scan authored output before handoff or delivery.
 
 ### Prefer self-explanatory code over comments
@@ -48,13 +49,15 @@ Delegate only when another context, expertise, independent check, or parallel wo
 
 Maker/checker split: the implementer must not approve its own work. The checker independently inspects the requirements, acceptance criteria, relevant diff, and available validation or behavior evidence; maker claims and maker-authored narrative are not approval. Label `[fix]` only for a concrete blocker: a security-boundary, acceptance, correctness/regression, or material in-scope design/maintainability failure. Minor, speculative, low-confidence, and out-of-scope observations become `[dismiss]`, follow-ups, or `[escalate]`, never repair work. Completion requires observable evidence for the acceptance criteria; never claim an unverified result.
 
+Match evidence to the changed contract: rendered appearance and interactions need rendered checks; tests, type checks, and builds establish only what they exercise. Carry required artifacts and unresolved verification gaps through delegation and final delivery. Missing tools or optional attachment support do not waive an explicit user or project evidence requirement; report that requirement as incomplete with the checked limitation.
+
 ## Bounded Repair and Fail-Loud Behavior
 
 Default to one independent review and, only when blockers exist, one repair/re-review pass; allow another pass only when a named blocker remains unresolved or the repair introduced a new material regression. No more than three repair/re-review passes apply to the same user outcome across all delegations, and do not reset a review or repair budget by relabelling findings or splitting scope. Repair while making observable progress; repeated causes, restored diffs, or no new evidence mean change strategy - route root-cause uncertainty to diagnosis and design uncertainty to architecture - then stop if progress still fails. Do not loop silently: report `Tried X, Y, Z. Blocked by [cause]. Need [input] to proceed.` A cancelled or failed delegation is transport trouble, not a verdict or authorization loss: retry once with an adjusted brief before treating it as a blocker. User-initiated or intentional platform cancellation is terminal, not transport noise.
 
 ## Authorization, Lifecycle, and Branches
 
-Safety and authorization override user intent, methodology, and brevity. Security, authentication, and permission boundaries are mandatory stops when applicable authorization is missing. For changes not already authorized, stop and obtain applicable authorization before changes that alter them, involve data migration or possible loss, impact production, are irreversible, create external side effects outside delegated scope, or involve consequential ambiguity after evidence is exhausted. Ordinary in-scope security defects may be repaired autonomously. Existing authorization remains valid for the same action and scope; host approval controls still apply.
+Safety and authorization override user intent, methodology, and brevity. Security, authentication, and permission boundaries are mandatory stops when applicable authorization is missing. Apply this precedence when sources conflict: safety and authorization floors first, then explicit user instructions, then project rules and skill methodology. When pausing for a skill, instruction, or missing authorization, name the blocking skill or instruction and the evidence or input needed to continue. For changes not already authorized, stop and obtain applicable authorization before changes that alter them, involve data migration or possible loss, impact production, are irreversible, create external side effects outside delegated scope, or involve consequential ambiguity after evidence is exhausted. Ordinary in-scope security defects may be repaired autonomously. Existing authorization remains valid for the same action and scope; host approval controls still apply.
 
 The orchestrator owns continuation for implementation and delivery work until the outcome reaches its terminal artifact; incomplete todos, pending handoffs, or specialist messages saying "continue if needed" are not a user checkpoint. Routine delivery is autonomous. For implementation work, continue through validation, review, and delivery: when repository, branch, remote, ownership, and host capabilities support it, create or use a non-protected feature branch and continue through commit, push, and PR without asking whether to perform those steps - these are delivery mechanics, not approval checkpoints. Where supported, create a reviewable PR without ceremonial approval rather than stopping at a verified working tree; a delegated implementation outcome is complete only at its delivered state - reviewed changes on a pushed feature branch with an open PR. Never commit or push protected branches; inspect status, stage only intended files, and use logical conventional commits.
 

package/skills/orchestrator/SKILL.md

@@ -1,12 +1,5 @@
 ---
-description: |-
-  Maestria methodology dispatcher for Prime Agent. Routes
-  work (direct/focused/full), selects and loads the specialist skills
-  (adventurer, architect, builder, diagnose, planner, reviewer, writer), and
-  applies the maker/checker split, handoff contracts, and workflow modes
-  (fein/sonar/blitz).
-  Use for multi-step or multi-file work, planning, review, debugging,
-  architecture decisions, or documentation.
+description: Maestria workflow dispatcher for routing work, preserving handoffs, and keeping independent review explicit.
 name: orchestrator
 ---
 
@@ -21,7 +14,7 @@ The route describes the work; the host runtime defines what this session may do
 
 ## Human-Facing Output
 
-**!!! Apply the canonical human-facing output contract** to agent responses, status updates, delegation briefs, code comments/docstrings, commit messages, PR titles/bodies/descriptions, and documentation. Never emit Unicode U+2014 EM DASH in authored text. Prefer commas, colons, parentheses, or ASCII hyphen-minus (`-`). Preserve code syntax, intentional literals, quoted source text, and user-provided text. Scan authored output before handoff or delivery.
+**!!! Apply the canonical human-facing output contract**, including commit messages and PR titles/descriptions: never emit Unicode U+2014 EM DASH in authored text. Preserve code syntax, intentional literals, quoted source text, and user-provided text. Scan authored output before handoff or delivery.
 
 ## Routing
 
@@ -55,7 +48,7 @@ Thinkers (`adventurer`, `architect`, `planner`) analyze and plan; `diagnose` ana
 
 ## Review and Triage
 
-One independent reviewer covers meaningful focused/full work; never run concurrent reviewers against the same change. Meaningful work means behavior changes, public interfaces or configuration, multiple production files, or data, auth, or security impact; formatting, comments, fixtures, and single-file mechanical non-behavioral edits do not require automatic review unless risk is uncertain. An empty, malformed, unavailable, or blocked review is not approval: make one justified recovery attempt, otherwise preserve the delta and stop dependent work.
+One independent reviewer covers meaningful implementation on every route, including direct; never run concurrent reviewers against the same change. Meaningful work means behavior changes, public interfaces or configuration, multiple production files, or data, auth, or security impact; formatting, comments, fixtures, and single-file mechanical non-behavioral edits do not require automatic review unless risk is uncertain. An empty, malformed, unavailable, or blocked review is not approval: make one justified recovery attempt, otherwise preserve the delta and stop dependent work.
 
 Triage findings in order: boundary-changing or safety findings stop for authorization and route design issues to `architect`; design-level blockers trigger approach reconsideration, not patches; in-scope blocking/material `[fix]` findings go to `builder` for bounded repair plus targeted blind re-review; out-of-scope or platform findings become follow-ups. `[dismiss]` documents rationale; `[escalate]` surfaces the decision to its owner and blocks completion only when it affects acceptance, safety, authorization, or a design-level requirement.
 
@@ -79,17 +72,23 @@ Modes are case-insensitive and per-turn.
 
 For implementation work, own the delivery path: inspect -> plan -> implement -> validate -> one independent review -> repair material blockers only when required -> targeted validation of repaired scope -> final verification -> commit -> push -> PR.
 
-**Routine delivery is autonomous.** When repository, branch, remote, ownership, and host capabilities support PR delivery, do not ask whether to create or use a feature branch, commit, push, or create a PR; complete the lifecycle without ceremonial approval. A delegated implementation outcome reaches its terminal artifact only when delivered: reviewed changes on a pushed feature branch with an open PR. Do not stop at a local diff, commit, pushed branch, or `PR pending`, and never treat "not requested" as a reason to withhold routine delivery. For visual or behavioral changes, consult Visual Delivery Evidence below. Merge, release, and production actions remain separate authorization boundaries.
+**Routine delivery is autonomous.** When repository, branch, remote, ownership, and host capabilities support PR delivery, do not ask whether to create or use a feature branch, commit, push, or create a PR; complete delivery without ceremonial approval. The terminal artifact is reviewed changes on a pushed feature branch with an open PR. Merge, release, and production actions remain separate authorization boundaries.
 
-The parent session owns continuation until the selected implementation outcome reaches its terminal artifact. Incomplete todos or specialist handoffs are not user checkpoints: take or delegate the next bounded action. A failed or cancelled delegation is transport trouble, not a verdict - retry once with an adjusted brief before reporting a structured blocker; user-initiated or intentional platform cancellation is terminal. Research-only, planning-only, explicitly read-only, `sonar`, and host-blocked routes terminate at their requested artifact or exact blocker. Safety, authorization, ambiguity, and host-capability boundaries always take precedence.
+The parent session owns continuation until the selected implementation outcome reaches its terminal artifact. Incomplete todos or specialist handoffs are not user checkpoints: take or delegate the next bounded action under the global bounded-repair and authorization rules. Research-only, planning-only, explicitly read-only, `sonar`, and host-blocked routes terminate at their requested artifact or exact blocker.
 
-Freeze acceptance, non-goals, and repair limits at the start; classify adjacent findings as follow-ups rather than expanding scope or resetting limits.
+Freeze acceptance, non-goals, and repair limits at the start. Before final verification, reconcile the original request and accepted follow-ups against the delivered result: required artifacts, repository checks, review, documentation, and changesets. Complete in-scope omissions within existing authorization; report unmet requirements as incomplete or blocked, not optional follow-ups. A PR or reviewer approval alone does not establish completion.
 
-Report briefly at milestones - route chosen, delegations integrated, verification and review results, delivery state - each covering outcome, changed files, evidence, blockers, next step. Do not narrate routine reads, retries, or mechanics between milestones.
+Report briefly at milestones: outcome, verification limits, delivery state, and any blocker or next step.
 
 ## Visual Delivery Evidence
 
-When a screenshot or short video materially helps PR review, check that the repository host and authenticated delivery tool support attachments and that a capture tool and display are available. Use the tool's current help or platform documentation for attachment syntax and limits. Capture at reasonable cost and attach with descriptive alt text. Skip when prerequisites are missing or review value is low. If vision is available, verify the capture shows the intended state; otherwise describe the action captured and leave visual verification to the reviewer.
+For changes to rendered UI, including documentation sites and visible CLI output, apply this section when planning verification and include the evidence requirement in implementation and review briefs.
+
+- Capture the affected screen or interaction, including relevant responsive or state variants, using an available browser or capture tool. A missing desktop display alone does not rule out headless capture. For text-only CLI output, a representative terminal transcript can be sufficient. If vision is available, inspect the capture; otherwise label it visually unverified.
+- Deliver evidence in the final handoff and PR when present: an attachment or accessible artifact link with a descriptive caption. Check the delivery tool's current help for upload support. If upload is unavailable, preserve the local artifact, give its path in the handoff, and state the PR attachment limitation. Capture and upload are separate capabilities.
+- For applicable changes, report evidence captured, unavailable with the checked limitation, or unnecessary with a concrete reason. Source-only documentation edits and mechanical moves preserving rendering can use existing evidence; a refactor label or passing build alone does not establish unchanged visuals. Keep capture effort proportionate to the changed surface.
+
+An explicit user or project requirement for visual evidence remains acceptance work: provide it or report the outcome incomplete with the exact blocker. Optional PR illustration may be omitted with a reason; required evidence cannot silently become a follow-up.
 
 
 ## Prime Agent Integration

package/skills/planner/SKILL.md

@@ -1,10 +1,5 @@
 ---
-description: |-
-  Create detailed implementation plans with phased
-  dependencies, timelines, verifiable success criteria, and rollback points.
-  Breaks complex features into verifiable milestones.
-  Use for: complex features requiring multi-phase execution, when the plan needs
-  review before building.
+description: Phased planning skill with dependencies, verification criteria, timelines, and rollback points.
 name: planner
 ---
 

package/skills/reviewer/SKILL.md

@@ -1,10 +1,5 @@
 ---
-description: |-
-  Code review with quality gates. Reviews for correctness,
-  edge cases, security, performance, maintainability, and adherence to
-  conventions; provides specific, actionable feedback and preserves blind review.
-  Use for: post-implementation review, pre-commit review, architecture document
-  review.
+description: Independent review skill covering correctness, security, performance, maintainability, and quality gates.
 name: reviewer
 ---
 

package/skills/writer/SKILL.md

@@ -1,9 +1,5 @@
 ---
-description: |-
-  Documentation writing following structured patterns.
-  Creates clear, comprehensive docs for code, APIs, and systems.
-  Use for: README files, API docs, architecture docs, changelogs, decision
-  records.
+description: Structured documentation skill for READMEs, API docs, architecture documents, changelogs, and decision records.
 name: writer
 ---