@brainervirus/workit-cursor 0.6.1 → 0.8.0

package/.cursor-plugin/plugin.json

@@ -2,9 +2,37 @@
   "name": "workit",
   "displayName": "Workit",
   "description": "OpenCode-style verify, PR, changelog, commit, and session handoff for Cursor",
-  "version": "0.6.1",
-  "skills": "../skills/",
-  "rules": "../rules/",
-  "mcpServers": "../mcp.json",
-  "hooks": "../hooks/hooks-cursor.json"
+  "version": "0.8.0",
+  "author": {
+    "name": "Cristhofer Pincetti"
+  },
+  "publisher": "BrainerVirus",
+  "homepage": "https://github.com/BrainerVirus/workit",
+  "repository": "https://github.com/BrainerVirus/workit",
+  "license": "MIT",
+  "logo": "assets/logo.svg",
+  "keywords": [
+    "agent",
+    "cursor",
+    "mcp",
+    "workflow",
+    "workit"
+  ],
+  "category": "Developer Tools",
+  "tags": [
+    "workflow",
+    "agent",
+    "mcp",
+    "pr",
+    "changelog",
+    "commit",
+    "handoff"
+  ],
+  "skills": [
+    "skills/",
+    "vendor/superpowers/skills/"
+  ],
+  "rules": "rules/",
+  "mcpServers": "mcp.json",
+  "hooks": "hooks/hooks-cursor.json"
 }

package/README.md

@@ -1,21 +1,103 @@
 # @brainervirus/workit-cursor
 
-Cursor plugin for workit — MCP server, hooks, rules, and skills for agentic coding workflows (specs, plans, YouTrack, CI-gated commits).
+Cursor plugin for workit — MCP server, session-start hook, rules, and skills for agentic coding workflows (specs, plans, YouTrack, CI-gated commits).
 
 ## Install
 
-Run the installer (recommended) or add the MCP server manually:
+**Wizard (recommended)** — configures Cursor and/or OpenCode and installs the platform packages:
 
 ```bash
 npx @brainervirus/workit-cli init
 ```
 
+**npm (package)** — the package is published as `@brainervirus/workit-cursor`; its `.cursor-plugin/plugin.json` identifies the plugin as `workit` (display name `Workit`) and registers its MCP server, hook, rules, and skills. A local (non-npm) install lives at `~/.cursor/plugins/local/workit` and writes `enabled_plugins.workit = true`; the installer migrates exact legacy `workflow-toolkit` entries only after the replacement succeeds.
+
+**Marketplace** — see [Marketplace](#marketplace).
+
+**Manual** — add the MCP server to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "workit": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--package=@brainervirus/workit-cursor@latest",
+        "workit-cursor-mcp",
+        "${workspaceFolder}"
+      ]
+    }
+  }
+}
+```
+
+### Requirements
+
+- **Node.js ≥ 22** — the MCP server and session-start hook are self-contained Node bundles invoked through `npx`.
+- **Network** — `npx -y …@latest` resolves and downloads the package on first run in each environment; a machine that cannot reach the npm registry cannot start the MCP server or hook (see [Runtime](#runtime)).
+
 ## What it provides
 
-- MCP server (41 `workflow_*` tools)
-- Session-start contract hook
-- Canonical rules (locale, branch policy, doc delivery)
-- The same 12 `wk-*` skills as OpenCode
+- MCP server exposing the `workflow_*` tools (branch setup, PR create/context, docs validate/promote, YouTrack post/log/time, templates, rules, presentation, doctor, handoff).
+- Session-start contract hook.
+- 4 rules and 12 `wk-*` skills (plus 14 sanitized Superpowers skills).
+
+## Host limitations
+
+Cursor adapts workit through policy-only confirmation: approvals and commits are recorded as policy decisions (`attested: false`) rather than fabricated delegated identity, and subagent-driven plan execution is not supported on this host. OpenCode records native `question` receipts and runs delegated tasks; see the root [README](../../README.md#host-capabilities) for the full host-capability matrix.
+
+## Configuration
+
+- Plugin metadata: `packages/workit-cursor/.cursor-plugin/plugin.json` (`name: "workit"`, `displayName: "Workit"`).
+- MCP server: `mcp.json`.
+- Session-start hook: `hooks/hooks-cursor.json`.
+- Rules: `rules/` (`ask-question-only.mdc`, `cursor-todowrite.mdc`, `no-worktrees.mdc`, `sdd-docs-path.mdc`).
+- Skills: `skills/` (12 `wk-*`) and `vendor/superpowers/skills/` (14).
+
+## Runtime
+
+Cursor launches the MCP server and session-start hook through `npx`, so the shipped manifests contain no repository-relative `dist` paths:
+
+- **MCP server** — `npx -y --package=@brainervirus/workit-cursor@latest workit-cursor-mcp ${workspaceFolder}`. It speaks the MCP stdio protocol; `stdout` is reserved for protocol messages and diagnostics go to `stderr`.
+- **Session-start hook** — `npx -y --package=@brainervirus/workit-cursor@latest workit-cursor-session-start`. It emits valid hook output and a diagnostic on runtime failure, and remains fail-open where Cursor's hook contract requires startup continuity.
+- `npx` startup or network failure is surfaced by Cursor as an MCP/hook startup failure; Workit never silently substitutes stale local runtime code.
+
+The `@latest` tag means the runtime updates independently of the Marketplace metadata: Cursor reviews plugin metadata from Git, while npm serves the runtime. See [Update review](#update-review).
+
+## Security and data handling
+
+- **Secrets** — tokens are stored in files with mode 600 (`~/.config/workit/*.token`) and are never printed by tools; edit them locally.
+- **Logs** — a persistent JSONL journal records redacted structured diagnostics under the configuration directory; Cursor keeps `stderr` diagnostics for protocol safety, and `stdout` remains reserved for the MCP/hook protocol (the logger never writes to it).
+- **External interactions** — Git/VCS (branch resolution, PR/MR creation) and YouTrack (task updates, time logging) happen only when you invoke the corresponding tools; local setup copies files under `~/.cursor/plugins/local/workit` and `~/.config/workit/`.
+
+## Plugin layout
+
+| Path | Contents |
+| --- | --- |
+| `mcp/` + `dist/mcp-server.js` | MCP server entry (built). |
+| `hooks/` | session-start hook manifest. |
+| `rules/` | 4 `.mdc` rules. |
+| `skills/` | 12 `wk-*` skills. |
+| `vendor/superpowers/skills/` | 14 sanitized Superpowers skills. |
+| `.cursor-plugin/plugin.json` | authoritative plugin manifest. |
+
+## Package scripts
+
+```bash
+bun run build   # bundle dist/mcp-server.js, dist/cursor-session-start.js, sanitize vendor skills
+```
+
+From the repository root, `bun run validate:cursor-marketplace` validates the tracked Marketplace artifact against the official Cursor JSON schemas and clean-checkout invariants (component paths, frontmatter, logo, sanitized vendor parity, no ignored-`dist` runtime references).
+
+## Marketplace
+
+The repository root carries `.cursor-plugin/marketplace.json`, indexing `packages/workit-cursor` (plugin `workit` / `Workit`). Cursor installs Marketplace plugins from Git and does not build the repository, so all declared skills, rules, and assets are tracked and validated in CI — the runtime is launched from npm as described in [Runtime](#runtime).
+
+- **Installing from Marketplace** — a Marketplace admin adds the repository URL through Cursor's authenticated publisher flow; end users then install the plugin from the Cursor Marketplace UI, which reads `.cursor-plugin/plugin.json` and the tracked components directly from Git.
+- **Submission** — Marketplace submission is a separate, later authenticated action at `https://cursor.com/marketplace/publish`. It is **not** performed here and no publication or acceptance is claimed; the repository is kept validated and submission-ready.
+- **Update review** — Git plugin metadata (manifest, rules, skills, assets) is reviewed by Cursor on Marketplace updates, while the npm runtime tagged `@latest` updates independently. Reviewing an npm runtime change is a manual step: pin `--package=@brainervirus/workit-cursor@<version>` in `mcp.json` / `hooks-cursor.json` if you need immutable reviewed code instead of `@latest`.
+- **Troubleshooting** — `workit doctor` (or the `workflow_doctor` tool) reports installation health including runtime, token, VCS/YouTrack, and log-writability checks; it exits nonzero on failure. An MCP/hook startup failure with no network is an `npx`/registry reachability issue, not a Workit defect.
 
 ## Docs
 

package/assets/logo.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <rect width="64" height="64" rx="14" fill="#111827"/>
+  <path d="M18 33l10 10 18-20" fill="none" stroke="#34d399" stroke-width="6" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/assets/templates/execution-contract.md

@@ -0,0 +1,58 @@
+Load `using-superpowers`, `subagent-driven-development`, `test-driven-development`, and `verification-before-completion` through OpenCode's `skill` tool. Implement the existing plan; do not re-plan.
+
+**Spec:** <SPEC_PATH>
+**Plan:** <PLAN_PATH>
+**Branch:** <BRANCH>
+**SDD:** `<SDD_DIR>`
+
+## Hard gates
+
+- The parent is coordinator-only: it does not edit product code or perform delegated exploration.
+- Never use a worktree. Branch changes are in-place through `workflow_branch_setup` on `feature/*` or `bugfix/*`; never commit on protected branches.
+- Working state, briefs, ledgers, and review diffs live only under gitignored `<SDD_DIR>` in `docs/<slug>/sdd/` and use `workflow_sdd_*` tools.
+- Use native `todowrite` for visible task state as well as the gitignored ledger.
+- Use native `question` for branch/stash choices and guarded external mutations; call mutation tools only after approval with `confirmed: true` (grounded in the recorded NativeChoiceEvidence).
+- Flow-tool confirmations are never agent-typed booleans and never caller-supplied evidence objects: on OpenCode the plugin records the user's native-`question` answer as a host-observed one-use receipt (`attested: true`, `callID`, `selectedLabel`, `recordedAt`) consumed by `workflow_spec_approve` / `workflow_plan_approve` / `workflow_plan_menu` — no evidence argument exists, and delegated worker status comes from host session parentage (`parentID`), never a caller `role` field. On Cursor, confirmations are policy-only (`attested: false`) and subagent-driven execution is rejected as unsupported.
+- On Cursor, for every repository-scoped `workflow_*` call, pass the active Cursor workspace as `workspace_root`; never rely on the MCP process default.
+- Use native `task` with only the built-in `explore` and `general` agents.
+
+## Flow gates (HARD)
+
+- `wk-implement` refuses to run unless the plan is `approved` (flow.json) and the post-plan menu was presented.
+- `wk-handoff` refuses to run unless both spec and plan are `approved`.
+- Sequence is enforced by tools: `workflow_spec_approve`, `workflow_plan_approve`, `workflow_plan_menu` — never skip a step (the spec/plan self-review runs automatically inside the transition; only the final approval asks for your confirmation).
+
+## Setup
+
+0. Call `workflow_docs_validate` with the linked spec/plan paths. Hard-fail on any error before todos or branch setup.
+1. Call `workflow_sdd_context` with `<PLAN_PATH>` and initialize `todowrite` from returned tasks.
+2. Call `workflow_plan_tasks`; cache each top-level task's `section_text`.
+3. Mark IDs in `completed_task_ids` completed and never redispatch them.
+4. Call `workflow_resolve_branch`, then show the current branch, target branch, and stash behavior before any in-place checkout/setup mutation.
+5. Always use `question`: for a clean tree ask whether to proceed or cancel; for a dirty tree add the stash choice and describe what will be stashed.
+6. Call `workflow_branch_setup` with `confirmed: true` only after approval.
+
+## Remaining-task loop
+
+For each top-level task absent from `completed_task_ids`:
+
+1. Mark it `in_progress` with `todowrite`.
+2. Create a working-state brief with `workflow_sdd_task_brief` and `confirmed: true`.
+3. Delegate read-only discovery, when needed, to an `explore` agent. Delegate implementation to a fresh `general` agent. Product changes follow TDD.
+4. Create a working-state diff with `workflow_sdd_review_package` and `confirmed: true`.
+5. Delegate spec-compliance review and code-quality review to separate `general` agents.
+6. **Blocking** findings (Critical, Important, or spec-compliance) may trigger at most **two** fix+re-review rounds per task. **Advisory** findings (Minor, style, YAGNI, taste) never pause the loop — append them to `<SDD_DIR>/advisories.md`.
+7. Append the validated ledger entry with `workflow_sdd_append_progress` and `confirmed: true`; mark the todo completed.
+
+## Final gate
+
+Run a separate full-branch code review, then `workflow_verify`. Present the full `<SDD_DIR>/advisories.md` roll-up once, then use native `question` so the user can choose which advisory items to fix, discuss, or discard. Report exact check results and never infer success. Use `workflow_git_context` for a commit preview and load `wk-commit` through `skill` for an approved commit. If working state contains a stash reference, preview reapplication through `question`, then call `workflow_branch_setup` with `confirmed: true` after approval.
+
+## Task order
+
+<TASK_LIST>
+
+## Quality gate (HARD)
+
+- Specs/plans are written from `templates/spec-template.md` / `templates/plan-template.md`.
+- After `workflow_docs_validate`, surface `quality` findings (spec scan). Hard findings (missing required section, missing CA-XX) block task start unless the user explicitly waives them. Warnings are advisory.

package/assets/templates/greeting.md

@@ -0,0 +1 @@
+{{greetingText}}

package/assets/templates/headers.md

@@ -0,0 +1,3 @@
+## Adjunto capturas
+
+## Archivos adjuntos

package/assets/templates/hygiene/.editorconfig

@@ -0,0 +1,8 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2

package/assets/templates/hygiene/.gitattributes

@@ -0,0 +1,3 @@
+* text=auto
+*.md text
+*.bat text eol=crlf

package/assets/templates/hygiene/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed

package/assets/templates/hygiene/CONTRIBUTING.md

@@ -0,0 +1,3 @@
+# Contributing
+
+<!-- How to report issues, propose changes, and the review process. -->

package/assets/templates/hygiene/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) <YEAR> <HOLDER>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/assets/templates/hygiene/README.md

@@ -0,0 +1,3 @@
+# <PROJECT>
+
+<!-- Describe the project: what it does, how to run it, how to contribute. -->

package/assets/templates/issue-update.md

@@ -0,0 +1,6 @@
+# Actualización
+{{greetingSection}}
+{{projectSection}}
+{{userNotesSection}}
+{{progressSection}}
+{{gitCommitsSection}}

package/assets/templates/plan-template.md

@@ -0,0 +1,25 @@
+# <Feature> Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Spec:** `docs/<slug>/spec.md`
+**Branch:** `feature/<slug>`
+
+**Goal:** <one sentence>
+
+## Global Constraints
+
+- <project-wide requirements, one line each>
+
+---
+
+### Task N: <Component>
+
+- [ ] **Step 1: <action>**
+
+<!-- per-task criteria: how this task is verified -->
+**Criteria:** <verifiable check>
+
+| Status | Task |
+| --- | --- |
+| pending | N: <Component> |

package/assets/templates/spec-template.md

@@ -0,0 +1,51 @@
+# Spec: <feature>
+
+**Branch:** `feature/<slug>`
+
+## Context
+
+<!-- Why does this exist? What problem does it solve? 1-3 sentences. -->
+
+## Goals
+
+- <!-- measurable, one per bullet -->
+
+## Non-goals
+
+- <!-- explicitly out of scope -->
+
+## Architecture
+
+<!-- REQUIRED if this spec has flows or architecture: render a mermaid diagram (workflow_present_flow). -->
+```mermaid
+flowchart TD
+  A[Start] --> B[Step]
+```
+
+<!-- REQUIRED if this spec touches UI: render an ASCII wireframe (workflow_present_ascii). -->
+```text
+┌──────────────┐
+│ Header       │
+└──────────────┘
+```
+
+## Data flow / contracts
+
+<!-- REQUIRED when there is a glossary, scope comparison, or contracts: use markdown tables. -->
+| Term | Meaning |
+| --- | --- |
+| <term> | <meaning> |
+
+## Acceptance criteria
+
+<!-- REQUIRED: enumerable, each verifiable. Numbered CA-01, CA-02, ... -->
+- CA-01 …
+- CA-02 …
+
+## Decisions
+
+- D-01 …
+
+## Future work
+
+- …

package/assets/templates/superpowers-doc-contract.md

@@ -0,0 +1,70 @@
+# Superpowers document contract
+
+Use OpenCode's native `question` for every bounded user choice. Give concise choices and allow a custom answer; if the tool is unavailable, ask one concise plain-text question. Use `skill` to load workflow and Superpowers skills, `todowrite` for task state, and `task` for delegated work.
+
+## Tracked document layout
+
+| Document | Path |
+| --- | --- |
+| Spec | `docs/<slug>/spec.md` |
+| Plan | `docs/<slug>/plan.md` |
+| SDD state | `docs/<slug>/sdd/` |
+
+An optional human mirror may live at `docs/specs/<same-basename>.md`; when present, keep its branch identical.
+
+Specs require:
+
+```markdown
+**Branch:** `feature/<slug>`
+```
+
+Plans require:
+
+```markdown
+**Spec:** `docs/<slug>/spec.md`
+**Branch:** `feature/<slug>`
+```
+
+`bugfix/<slug>` is also valid. Never use `main`, `develop`, `master`, or `prod`. Use plain backtick paths. Top-level headings are exactly `### Task N: Title`; steps use `- [ ] **Step N:** ...`; task headings never appear inside fences.
+
+Before writing **Branch:** into a new spec or plan, call `workflow_docs_branch` and write the returned `branch` verbatim. When `action` is `keep`, use the current feature/bugfix branch. When `action` is `create_from_develop` or `create_from_base`, create the branch only through `workflow_branch_setup`; it uses the configured workspace/global target branch.
+
+## Execution and handoff
+
+- Implementation uses `wk-implement` and subagent-driven development, with native `todowrite` and `task`.
+- Commits use `wk-commit` after its native `question` confirmation.
+- Continuation uses `wk-handoff`, whose `workflow_handoff_session` creates and seeds the OpenCode session automatically.
+- Never use worktrees. Resolve the declared branch with `workflow_resolve_branch`, preview dirty-tree stash choices with `question`, and apply an approved in-place checkout through `workflow_branch_setup` with `confirmed: true` (grounded in the recorded NativeChoiceEvidence).
+- Flow-tool confirmations are never agent-typed booleans and never caller-supplied evidence objects: on OpenCode the plugin records the user's native-`question` answer as a host-observed one-use receipt (`attested: true`, `callID`, `selectedLabel`, `recordedAt`) consumed by `workflow_spec_approve` / `workflow_plan_approve` / `workflow_plan_menu` — no evidence argument exists, and delegated worker status comes from host session parentage (`parentID`), never a caller `role` field. On Cursor, confirmations are policy-only (`attested: false`) and subagent-driven execution is rejected as unsupported.
+- Keep all SDD state under the gitignored `docs/<slug>/sdd/`; use `workflow_sdd_context` and the registered `workflow_sdd_*` tools.
+- After implementation, use `question` before an approved stash reapply through `workflow_branch_setup` with `confirmed: true`.
+
+## YouTrack content
+
+Chat follows the user's language. YouTrack task comments are Spanish (`es-CL`) and use `workflow_youtrack_draft` followed by reviewed `workflow_youtrack_post` with `confirmed: true`. Preserve the user's paragraph voice; do not inject commits, file paths, or robotic bullet reports.
+
+## Final self-check
+
+Before handoff, call `workflow_docs_validate` on the linked spec/plan pair. Hard-fail on any error; never offer execution when validation fails.
+
+Before handoff, verify the saved spec path, plan path, declared branch, top-level task numbering, and workflow-managed SDD directory through the registered read-only workflow tools. Report structured failures; never infer success.
+
+## Post-plan execution choice
+
+After saving a plan, call `workflow_docs_validate` on the spec/plan pair. On failure, stop and fix docs — do not offer execution.
+
+On success, use native `question` / Cursor `AskQuestion` with exactly these options (no stay, no A/B/C prose duplicate):
+
+1. Subagent-driven → load `wk-implement`
+2. Inline → execute in this session
+3. Handoff → load `wk-handoff` (new session only)
+4. Review spec first
+5. Review plan first
+
+Never emit Superpowers text beginning “Two execution options”.
+
+- Specs/plans must follow `templates/spec-template.md` / `templates/plan-template.md` (mandated diagrams, tables, CA-XX).
+
+## Doc delivery
+
+When delivering a spec or plan, use a clickable markdown link (\`[spec.md](docs/<slug>/spec.md)\`) and a 3-5 bullet summary of the content (Context, Goals, key decisions, status). Never reference docs with backtick-only paths.