@maestria/cursor 0.2.6 → 0.2.8

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "maestria",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Maestria methodology for Cursor - pipeline specialists, orchestrator skill, and workflow commands",
   "author": {
     "name": "agustinusnathaniel"

package/agents/adventurer.md

@@ -1,5 +1,5 @@
 ---
-description: Codebase reconnaissance agent. Maps unknown territory, traces call chains, maps module relationships. Use before implementation in unfamiliar code. Read-only - never implement or design.
+description: Codebase reconnaissance agent for mapping unfamiliar code, tracing call chains, and reporting verified context without implementing changes.
 name: adventurer
 readonly: true
 ---

package/agents/architect.md

@@ -1,5 +1,5 @@
 ---
-description: Architecture decisions using decision matrices and ADRs. Evaluates options with weighted criteria. Use for technology choices, implementation approaches, trade-off analysis.
+description: Architecture decision agent for comparing implementation approaches, boundaries, threat models, and ADR decisions.
 name: architect
 ---
 

package/agents/builder.md

@@ -1,5 +1,5 @@
 ---
-description: Focused implementation agent for atomic tasks. Executes one verifiable unit of work. Use for targeted fixes, feature implementation, refactors, adding tests.
+description: Focused implementation agent for one atomic, verifiable feature, fix, test, or refactor.
 name: builder
 ---
 
@@ -24,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/agents/diagnose.md

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

package/agents/planner.md

@@ -1,5 +1,5 @@
 ---
-description: Create detailed implementation plans with phased dependencies, timelines, and success criteria. Use for complex multi-phase features before building.
+description: Phased planning agent with dependencies, verification criteria, timelines, and rollback points.
 name: planner
 readonly: true
 ---

package/agents/reviewer.md

@@ -1,5 +1,5 @@
 ---
-description: Code review with quality gates. Reviews correctness, edge cases, security, performance, maintainability. Use for post-implementation validation; in full routes, review after the integrated builder batch is reconciled. Read-only - never edit.
+description: Independent review agent covering correctness, security, performance, maintainability, and quality gates.
 name: reviewer
 readonly: true
 ---

package/agents/writer.md

@@ -1,5 +1,5 @@
 ---
-description: Documentation writing following structured patterns. Use for README files, API docs, architecture docs, changelogs, decision records.
+description: Structured documentation agent for READMEs, API docs, architecture documents, changelogs, and decision records.
 name: writer
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maestria/cursor",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "private": false,
   "description": "Maestria methodology plugin for Cursor IDE and Cursor CLI - specialists, orchestrator, and workflow commands",
   "keywords": [
@@ -38,7 +38,7 @@
     "provenance": true
   },
   "devDependencies": {
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.5.1",
     "typescript": "^7.0.2"
   },
   "scripts": {

package/rules/maestria-global.mdc

@@ -20,6 +20,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
@@ -44,13 +45,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,5 +1,5 @@
 ---
-description: Maestria dispatcher for Cursor. Delegates to specialist agents (adventurer, architect, builder, diagnose, planner, reviewer, writer) via Task. Enforces maker/checker split, handoff contracts, and workflow modes (fein/sonar/blitz). Use for multi-step or multi-file work.
+description: Maestria workflow dispatcher for Cursor routing, handoffs, and independent review.
 name: orchestrator
 ---
 
@@ -14,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
 
@@ -48,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.
 
@@ -72,32 +72,28 @@ 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.
 
-## Specialist Agents (Cursor)
+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.
 
-Delegate via the `Task` tool to these custom agents (plugin `agents/`). Pass a complete handoff contract in the prompt.
 
-| Agent | Role | When |
-| --- | --- | --- |
-| `adventurer` | Gather data; describe the terrain | Before any implementation in unfamiliar code |
-| `architect` | Evaluate options; document decisions | When multiple approaches exist |
-| `builder` | Implement; test; refactor | When the design is locked |
-| `diagnose` | Find root cause; write regression test | When something is broken |
-| `planner` | Break down work; sequence milestones | Before starting a multi-step feature |
-| `reviewer` | Review; QA; check correctness | After the integrated builder batch is reconciled; general review first, then risk-matched lenses sequentially |
-| `writer` | Document APIs; write README; create ADRs | When code needs human-facing docs |
+## Specialist Agents (Cursor)
+
+Delegate via the `Task` tool to the plugin's custom agents (`agents/`). Pass a complete handoff contract in the prompt.
 
 ### How to invoke
 
@@ -123,13 +119,3 @@ Users can trigger modes with slash commands from this plugin:
 | `/fein` | Full pipeline: adventurer → architect/planner → builder → reviewer |
 | `/sonar` | Research only: adventurer → architect/planner → STOP |
 | `/blitz` | Fast path: builder directly (skip optional recon/design unless unknown; required review remains) |
-
-## Related Agents
-
-- `adventurer` - Codebase reconnaissance
-- `architect` - Architecture decisions + ADRs
-- `builder` - Focused implementation
-- `diagnose` - evidence-led bug tracing
-- `planner` - Multi-phase plans
-- `reviewer` - Code review with quality gates
-- `writer` - Documentation