@maestria/cursor 0.1.8 → 0.1.9

package/README.md

@@ -1,61 +1,36 @@
 # @maestria/cursor
 
-A [Cursor](https://cursor.com/) plugin that brings Maestria's structured agent orchestration to Cursor IDE and Cursor CLI (`agent`).
+A declarative [Cursor](https://cursor.com/) plugin that brings Maestria's structured agent orchestration to Cursor IDE and Cursor CLI (`agent`) - 7 specialist Task agents, an orchestrator skill, always-on global rules, and workflow commands.
 
-## Features
-
-- **7 specialist agents** — adventurer, architect, builder, diagnose, planner, reviewer, writer (Task subagents)
-- **Orchestrator skill** — dispatcher methodology, handoff contracts, maker/checker guidance
-- **Always-on global rules** — `rules/maestria-global.mdc` with `alwaysApply: true`
-- **Workflow commands** — `/fein`, `/sonar`, `/blitz`
-- **IDE + CLI parity** — one plugin bundle for both surfaces
+> This package is part of Maestria. See [VISION.md](https://github.com/agustinusnathaniel/maestria/blob/main/VISION.md) for the project vision, motivation, and scope. The agents, skills, and rules are **generated** from the canonical directives in `packages/core/agent-directives/` by the [sync pipeline](https://github.com/agustinusnathaniel/maestria/blob/main/CONTRIBUTING.md#3-the-sync-pipeline-core-concept).
 
 ## Installation
 
-### Recommended: via maestria CLI
-
 ```bash
+# Recommended: via the maestria CLI (copies the plugin to ~/.cursor/plugins/local/maestria)
 pnpx maestria@latest install cursor
 ```
 
-Copies the plugin to `~/.cursor/plugins/local/maestria`. Restart Cursor IDE, or in CLI:
-
-```bash
-agent --plugin-dir ~/.cursor/plugins/local/maestria
-```
-
-### Alternative: local development
-
-From a checkout of this monorepo:
-
-```bash
-agent --plugin-dir ./packages/cursor
-```
-
-See [INSTALL.md](./INSTALL.md) for the full checklist.
+Restart Cursor IDE, or load the plugin in Cursor CLI with `agent --plugin-dir ~/.cursor/plugins/local/maestria`. See [INSTALL.md](https://github.com/agustinusnathaniel/maestria/blob/main/packages/cursor/INSTALL.md) for the full checklist, manual setup, verification, and uninstall.
 
-## Commands
+## What It Provides
 
-| Command  | Description                                        |
-| -------- | -------------------------------------------------- |
-| `/fein`  | Full pipeline: recon → design → implement → review |
-| `/sonar` | Research only: recon → design → stop               |
-| `/blitz` | Fast implementation via builder                    |
+- **7 specialist Task agents** - adventurer, architect, builder, diagnose, planner, reviewer, writer.
+- **Orchestrator skill** - dispatcher methodology, handoff contracts, maker/checker guidance.
+- **Always-on global rules** - `rules/maestria-global.mdc` with `alwaysApply: true`.
+- **Workflow commands** - `/fein` (full pipeline), `/sonar` (research only), `/blitz` (fast implementation).
 
-## Development
+## Support / Platform Notes
 
-```bash
-# Sync agents/skills/rules from core
-cd packages/cursor && pnpm exec tsx ../core/scripts/sync.ts --verbose
-
-# Test
-pnpm --filter @maestria/cursor test
+- Declarative plugin: manifest, agents, skills, rules, and commands only - no build step or runtime code.
+- Read-only roles use Cursor's `readonly: true` runtime flag where supported; everything else is advisory prompt guidance, not a sandbox.
+- The generated agents, skills, and rules are projections of the canonical core directives. To change behavior, edit `packages/core/agent-directives/` and re-run the sync pipeline - never edit the generated files under `agents/`, `skills/`, or `rules/` directly.
 
-# Format, lint, type-check (repo root)
-vp check
-```
+## Documentation and Changelog
 
-Canonical prompts live in `packages/core/agent-directives/`. Edit those, then sync. Never edit generated files under `agents/`, `skills/`, or `rules/` directly.
+- [User-facing documentation](https://maestria.sznm.dev/cursor/) on the docs site
+- [Installation checklist](https://github.com/agustinusnathaniel/maestria/blob/main/packages/cursor/INSTALL.md)
+- [Changelog](https://github.com/agustinusnathaniel/maestria/blob/main/packages/cursor/CHANGELOG.md)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maestria/cursor",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "private": false,
   "description": "Maestria methodology plugin for Cursor IDE and Cursor CLI - specialists, orchestrator, and workflow commands",
   "keywords": [

package/rules/maestria-global.mdc

@@ -37,6 +37,14 @@ This is the cross-platform behavior contract. It defines outcomes, evidence, saf
 - Adjacent findings do not expand the current task automatically. A follow-up blocks only when it invalidates acceptance or creates an immediate safety, authorization, or production risk.
 - Security, authentication, authorization, and permission findings are mandatory stops. Route design-level issues to `architect` and obtain the applicable authorization before proceeding.
 
+## Session Continuation and Delivery
+
+- **!!! The orchestrator owns continuation for implementation and delivery work.** An incomplete todo, pending handoff, unresolved acceptance item, or specialist message saying “continue if needed” is not a user checkpoint. Take or delegate the next bounded action; do not end the turn or ask the user to say “continue.” Research-only, planning-only, explicitly read-only, and host-blocked work terminates at its requested artifact or exact blocker.
+- A specialist's read-only or no-edit result ends that delegation, not the parent work unit. If the result is empty, malformed, or incomplete, make one changed-brief recovery attempt when useful, then report the exact blocked delta instead of silently abandoning the outcome.
+- Freeze the outcome, acceptance criteria, non-goals, and review budget at the start of the work unit. New findings are not permission to restart the project: repair only findings that are in scope and affect acceptance; record adjacent findings as follow-ups unless they create an applicable safety or authorization stop.
+- Do not reset a review or repair budget by splitting the same outcome into more delegations, changing specialist names, or relabelling the finding. A new scope requires a new outcome and acceptance criteria.
+- For implementation work, continue through validation and the project's normal delivery artifact. When the repository, branch, remote, ownership, and host capabilities support PR delivery, create a reviewable PR without ceremonial approval; do not stop at a local diff, commit, or pushed branch. Research-only, planning-only, explicitly read-only, and host-blocked work terminates at its requested artifact or exact blocker. Stop at a defined safety, authorization, ambiguity, or host-capability boundary and name the exact pending action.
+
 ## Delegation and Context
 
 Supported specialists are `adventurer`, `architect`, `builder`, `diagnose`, `planner`, `reviewer`, and `writer`.

package/skills/orchestrator/SKILL.md

@@ -95,7 +95,13 @@ Modes are case-insensitive and per-turn unless the platform documents another li
 
 ## Commit and Session Flow
 
-For normal engineering work, own the delivery path: `inspect -> plan -> implement -> validate -> review -> repair material blockers -> commit -> push -> PR`. Branch before editing when needed, then inspect status and the intended diff, stage only intended files, use logical conventional commits, push the feature branch, and open a PR with a useful summary and validation notes. Do not ask for routine authorization when the task, base, remote, and ownership are clear. Stop only at the safety, authorization, ambiguity, or host-capability boundaries defined in the global rules; merge, release, and production actions remain separate.
+For implementation work, own the delivery path: `inspect -> plan -> implement -> validate -> review -> repair -> commit -> push -> PR`.
+
+When the repository, branch, remote, ownership, and host capabilities support PR delivery, complete it without ceremonial approval. Do not stop at a local diff, commit, pushed branch, or `PR pending`. Merge, release, and production actions remain separate.
+
+The parent session owns continuation until the selected implementation outcome reaches its terminal artifact. Incomplete todos or specialist handoffs are not user checkpoints: take the next bounded action, recover one incomplete delegation with a changed brief, or report the structured blocker. Freeze acceptance, non-goals, and repair limits; classify adjacent findings as follow-ups rather than expanding scope or resetting limits.
+
+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.
 
 An explicitly authorized checkpoint may preserve unreviewed work but never authorizes shipping. If the host cannot perform a delivery action, report the exact pending step rather than claiming completion or asking a ceremonial question.