@task-boards/mcp-server 0.20.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@task-boards/mcp-server",
-  "version": "0.20.0",
+  "version": "0.25.0",
   "description": "MCP stdio server for Task Boards (IDE integration)",
   "type": "module",
   "main": "./build/cli.js",
@@ -9,6 +9,7 @@
   },
   "files": [
     "build",
+    "skills",
     "README.md"
   ],
   "engines": {
@@ -20,7 +21,7 @@
   },
   "scripts": {
     "build": "tsc --build tsconfig.json && node scripts/bundle.mjs",
-    "prepublishOnly": "node ../../scripts/assert-mcp-publish-deps.mjs && npm run build",
+    "prepublishOnly": "node ../../scripts/assert-mcp-publish-deps.mjs && node scripts/assert-bundled-skills.mjs && npm run build",
     "start": "node build/cli.js"
   },
   "dependencies": {

package/skills/task-boards-agent-runs/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: task-boards-agent-runs
+description: Task Boards agent run lifecycle — ack_agent_run, complete_agent_run, AGENTIC_SDLC outcomes, and per-run processing. Use when acknowledging dispatched runs, completing workflow transitions, or handling HANDOFF/SKIP outcomes.
+---
+
+# Task Boards Agent Runs
+
+## Lifecycle overview
+
+```
+DISPATCHED → ack_agent_run → ACKNOWLEDGED → complete_agent_run → COMPLETED
+```
+
+Logical orchestrator phases (not separate backend statuses): `dispatched` → `acknowledged` → `complete`.
+
+## Key MCP tools
+
+| Tool                  | Purpose                                                              |
+| --------------------- | -------------------------------------------------------------------- |
+| `list_agent_runs`     | Read-only inspection (prefer `wait_for_agent_runs` for orchestrator) |
+| `wait_for_agent_runs` | Long-poll with atomic claim                                          |
+| `ack_agent_run`       | `DISPATCHED` → `ACKNOWLEDGED` after Task dispatch                    |
+| `complete_agent_run`  | Apply workflow transition + optional work item patch                 |
+
+## Per-run processing (DISPATCHED)
+
+1. `list_work_item_attachments` / download if needed.
+2. `sync_project_subagents` if custom subagent slug.
+3. `Task(subagent_type, prompt, file_attachments)`.
+4. `ack_agent_run(agentRunId)`.
+5. Subagent work — IDE blockers → `report_agent_attention` (see attention skill).
+6. Human resolves → `clear_agent_attention`.
+7. `complete_agent_run` with appropriate outcome.
+8. Local `git commit` with `work-item:{uuid}` when code changed.
+
+## complete_agent_run outcomes (AGENTIC_SDLC)
+
+Columns: `backlog`, `in-analysis`, `in-development`, `in-qa`, `in-awaiting`, `done`, `released`.
+
+| Outcome               | Effect                                                            |
+| --------------------- | ----------------------------------------------------------------- |
+| `DEFAULT`             | Standard handoff per role and column                              |
+| `HANDOFF`             | Move to next analysis phase                                       |
+| `SKIP_DESIGN`         | Skip designer → in-development                                    |
+| `SKIP_DEV`            | Skip dev when `codeChangesRequired=false`                         |
+| `HAS_BUGS`            | QA → back to in-development                                       |
+| `NEEDS_CLARIFICATION` | Workflow questions → **`in-awaiting`** column (not IDE attention) |
+| `FAILED`              | No column move                                                    |
+
+## designerRequired
+
+On ARCHITECT `complete_agent_run`, optional `workItemPatch.designerRequired` controls DESIGNER runs. Default `false` — set `true` only when design phase is required.
+
+## Re-entry with attention
+
+If run has `requiresAttention: true`: `clear_agent_attention` first before resuming; do not re-dispatch Task until cleared.
+
+`complete_agent_run` deletes `.cursor/orchestrator-active-run.json` and pending attention state.

package/skills/task-boards-attention/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: task-boards-attention
+description: Task Boards IDE attention — report_agent_attention, clear_agent_attention, replace semantics, seven message categories, and distinction from workflow in-awaiting. Use when subagents need IDE approval or when configuring attention hooks.
+---
+
+# Task Boards IDE Attention
+
+## IDE attention vs workflow in-awaiting
+
+| Concern                                                    | Mechanism                                                    | Column change     |
+| ---------------------------------------------------------- | ------------------------------------------------------------ | ----------------- |
+| Subagent spec / stakeholder questions                      | `complete_agent_run(NEEDS_CLARIFICATION)` + `create_comment` | **`in-awaiting`** |
+| IDE approval (shell, git, network, Smart Mode, MCP, files) | `report_agent_attention` / `clear_agent_attention`           | **unchanged**     |
+
+Never move a story to `in-awaiting` for IDE shell approvals, git push prompts, MCP auth, or Smart Mode blocks.
+
+## report_agent_attention / clear_agent_attention
+
+1. Call `ack_agent_run` first (`DISPATCHED` → `ACKNOWLEDGED`).
+2. Call `report_agent_attention(agentRunId, message)` when blocked awaiting human action in the IDE.
+3. **One message per ACK run — replace on re-report** (latest message wins; do not append).
+4. After human resolves: `clear_agent_attention(agentRunId)`, then resume subagent work and `complete_agent_run`.
+5. `clear_agent_attention` requires `ACKNOWLEDGED` status.
+
+On poll timeout: do **not** call `clear_agent_attention` — board badge remains until resolved.
+
+## Message format (7 categories)
+
+Pattern: `[{category}] {detail}`
+
+| Category     | Example                                                       |
+| ------------ | ------------------------------------------------------------- |
+| `shell`      | `[shell] Approve shell command: npm install`                  |
+| `git`        | `[git] Approve git operation: git push origin feature/tb-180` |
+| `network`    | `[network] Approve network access: registry.npmjs.org`        |
+| `smart-mode` | `[smart-mode] Approve Smart Mode: blocked npm ci`             |
+| `mcp`        | `[mcp] Approve MCP / API action: token rotation test`         |
+| `file`       | `[file] Approve file change outside scope`                    |
+| `other`      | `[other] Human input required: staging credentials`           |
+
+## Auxiliary CLI bridge
+
+```bash
+task-boards-mcp attention report --agent-run-id <id> --message "[shell] ..."
+task-boards-mcp attention report-from-hook   # Cursor hooks stdin
+task-boards-mcp attention clear
+task-boards-mcp orchestrator write-active-run --agent-run-id ... --work-item-id ... --project-id ...
+task-boards-mcp orchestrator clear-active-run
+```
+
+Global user hooks (`~/.cursor/hooks.json`) auto-report shell/MCP/Smart Mode blocks when the workspace contains `.task-boards.yaml` and `WORKSPACE_ROOT` / API token are configured.
+
+## Auto bridge state files
+
+| File                                          | Purpose                     |
+| --------------------------------------------- | --------------------------- |
+| `.cursor/orchestrator-active-run.json`        | Written on `ack_agent_run`  |
+| `.cursor/orchestrator-attention-pending.json` | Pending flag for hook clear |
+
+`complete_agent_run` deletes both files.

package/skills/task-boards-git-sync/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: task-boards-git-sync
+description: Task Boards git sync — sync_git_releases, work-item commit tags, sync_project_subagents, and conventional commit policy. Use after git push, on poll timeout, or before dispatching custom subagent slugs.
+---
+
+# Task Boards Git Sync
+
+## sync_git_releases
+
+MCP tool: fetch origin and sync commits tagged with `work-item:{uuid}` from:
+
+- Default branch (`master` / `main`)
+- Current feature branch when cwd is not on default branch
+
+| When                                      | Action                              |
+| ----------------------------------------- | ----------------------------------- |
+| After `git push` on feature branch        | Call `sync_git_releases(projectId)` |
+| On `master`/`main` with local commit only | Sync without push                   |
+| Poll `timedOut: true`                     | Call before next poll cycle         |
+
+Requires MCP API token with `write` scope and `WORKSPACE_ROOT` set.
+
+## Git commit conventions
+
+After dev/QA when code is ready:
+
+1. Local `git commit` with conventional message: `<type>(<scope>): <subject>`
+2. Body must include `work-item:{uuid}` for release sync
+3. `git push` on feature branches or when user explicitly requests — not by default on `master`/`main`
+4. Never commit `.env`, `config.yaml`, or secrets
+
+See project `conventional-commits.mdc` for types and CI release rules.
+
+## sync_project_subagents
+
+Before `Task(subagent_type=custom-slug)` when `payload.suggestedSubagentType` is a **project custom slug**:
+
+```json
+{ "projectId": "f9ee1002-2b17-4803-9a7d-949741b9fd8d" }
+```
+
+Writes `{workspaceRoot}/.cursor/agents/{slug}.md` — idempotent overwrite.
+
+Built-in IDE subagents (`generalPurpose`, `explore`, etc.) do not need sync.
+
+## Orchestrator git timing
+
+- `run_orchestrator_once` does **not** auto-call `sync_git_releases`.
+- Orchestrator calls sync after batch complete and on poll timeout.
+- Do not clear IDE attention on timeout — badge remains until human resolves.
+
+## Related
+
+- `task-boards-orchestrator` — when to call sync in poll loop
+- `task-boards-agent-runs` — commit after `complete_agent_run` when code changed

package/skills/task-boards-orchestrator/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: task-boards-orchestrator
+description: Run the Task Boards orchestrator poll loop — run_orchestrator_once, wait_for_agent_runs, inflight recovery, timeout handling, and single-sleeper policy. Use when long-polling agent runs, dispatching subagents, or recovering orphaned runs.
+---
+
+# Task Boards Orchestrator Loop
+
+Canonical reference: `.cursor/rules/orchestrator.mdc` and package README.
+
+## Poll entry points
+
+| Tool                    | When                                                     |
+| ----------------------- | -------------------------------------------------------- |
+| `run_orchestrator_once` | Preferred — resolves project, claims runs, returns hints |
+| `wait_for_agent_runs`   | When `projectId` is already known                        |
+
+Defaults: `timeout=120`, `pollInterval=2`, `limit=1`.
+
+## Poll loop
+
+```
+1. resolve_project (if needed)
+2. run_orchestrator_once / wait_for_agent_runs
+   a. items.length > 0 → process newly claimed runs
+   b. inflightRuns.length > 0 → process recovered runs (no re-claim)
+   c. timedOut → sync_git_releases(projectId) → exit (true idle)
+3. For each run → process (ack, Task, attention, complete)
+4. sync_git_releases after batch
+5. Loop — never parallel polls
+```
+
+## Response fields
+
+| Field          | Meaning                                                      |
+| -------------- | ------------------------------------------------------------ |
+| `items`        | Newly claimed runs (`PENDING→DISPATCHED`)                    |
+| `inflightRuns` | Recovered `DISPATCHED`/`ACKNOWLEDGED` (orphan recovery)      |
+| `timedOut`     | `true` when deadline reached with no claimed and no inflight |
+
+Read `orchestrator.sleeperPolicy` on every response — one blocking poll per workspace.
+
+## Timeout behavior
+
+When `timedOut: true`:
+
+1. Call `sync_git_releases(projectId)`.
+2. Exit and poll again later.
+3. Do **not** call `clear_agent_attention` on timeout — IDE attention badge remains until the human resolves the blocker.
+4. Schedule at most one follow-up automation wake; prefer interval ≥ `timeout`.
+
+## Orphan recovery
+
+When claim returns empty, MCP lists inflight runs before sleeping:
+
+- `DISPATCHED` inflight → resume dispatch phase unless subagent already running.
+- `ACKNOWLEDGED` + `requiresAttention` → clear attention first; do not re-dispatch Task.
+- `ACKNOWLEDGED` without attention → resume subagent work → complete.
+
+`orchestrator.processRuns[].source` is `"claimed"` or `"inflight"`.
+
+## Prerequisite
+
+STORY items must be assigned to **Агент ИИ** (SERVICE user) before agent columns enqueue runs.
+
+## Related skills
+
+- `task-boards-agent-runs` — ack and complete lifecycle
+- `task-boards-attention` — IDE attention vs workflow `in-awaiting`
+- `task-boards-git-sync` — `sync_git_releases` and commits

package/skills/task-boards-setup/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: task-boards-setup
+description: Configure Task Boards MCP server for IDE agents — environment variables, WORKSPACE_ROOT, MCP client JSON, and quick start. Use when setting up @task-boards/mcp-server, troubleshooting connection issues, or onboarding a new workspace.
+---
+
+# Task Boards MCP Setup
+
+## Quick start
+
+```bash
+npx @task-boards/mcp-server
+```
+
+Install bundled Cursor skills after setup:
+
+```bash
+npx @task-boards/mcp-server skills install
+```
+
+## Environment variables
+
+| Variable                | Required         | Default                           | Purpose                                                        |
+| ----------------------- | ---------------- | --------------------------------- | -------------------------------------------------------------- |
+| `TASK_BOARDS_API_URL`   | No               | `https://task-boards.com/backend` | Backend base URL (without `/api/v1`)                           |
+| `TASK_BOARDS_API_TOKEN` | Yes (production) | —                                 | API token with `read` / `write` scopes                         |
+| `WORKSPACE_ROOT`        | No               | —                                 | Git repo root for attachments, sync tools, orchestrator bridge |
+
+Effective API base: `{TASK_BOARDS_API_URL}/api/v1`.
+
+## IDE MCP configuration
+
+Add to `.cursor/mcp.json` or IDE MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "task-boards": {
+      "command": "npx",
+      "args": ["-y", "@task-boards/mcp-server"],
+      "env": {
+        "TASK_BOARDS_API_URL": "https://task-boards.com/backend",
+        "TASK_BOARDS_API_TOKEN": "<your-api-token>",
+        "WORKSPACE_ROOT": "/path/to/your/repo"
+      }
+    }
+  }
+}
+```
+
+## Workspace resolution
+
+- Set `WORKSPACE_ROOT` to the git repository root when the MCP client cwd differs from the repo.
+- Project id lives in `.task-boards.yaml` or `.cursor/rules/task-boards.mdc`.
+- Use `resolve_project` MCP tool when project id is unknown.
+
+## Bundled skills install
+
+| Command                                   | Target                            |
+| ----------------------------------------- | --------------------------------- |
+| `task-boards-mcp skills install`          | `{workspaceRoot}/.cursor/skills/` |
+| `task-boards-mcp skills install --global` | `~/.cursor/skills/`               |
+
+Re-run after upgrading `@task-boards/mcp-server` to refresh skill content.
+
+## Documentation
+
+- Package README: orchestrator tools, poll fields, attention lifecycle
+- In-app guides: `/guide/mcp-orchestrator`, `/guide/agentic-prompts` (sign-in required)
+- `task-boards-mcp --help` — full MCP tool catalog (32 tools)

package/skills/task-boards-work-items/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: task-boards-work-items
+description: Manage Task Boards work items via MCP — create, update, move, search, estimation rules, and SERVICE assignee requirements. Use when creating stories, moving cards, or checking estimation gates before column transitions.
+---
+
+# Task Boards Work Items
+
+## Core MCP tools
+
+| Tool                                    | Purpose                               |
+| --------------------------------------- | ------------------------------------- |
+| `list_work_items` / `search_work_items` | Browse and find items                 |
+| `get_work_item`                         | Fetch by id                           |
+| `create_work_item`                      | Create under a project                |
+| `update_work_item`                      | Patch fields (fetches version first)  |
+| `move_work_item`                        | Change column (fetches version first) |
+| `get_board`                             | Board projection with columns         |
+
+## SERVICE assignee rule
+
+- MCP `create_work_item` attributes creator and default assignee to **Агент ИИ** (SERVICE user) unless `assigneeUserId` is set.
+- The orchestrator processes STORY items only when assignee is the SERVICE user.
+- Priority defaults to `LOW` when omitted.
+
+## Estimation gates
+
+When `project.estimationRequired` is true:
+
+- `storyPoints` and `estimate` are optional on create.
+- Before moving a STORY to any column except `backlog` (slug=backlog), active estimation is required.
+- `move_work_item` returns `ESTIMATION_REQUIRED_FOR_MOVE` (422) when estimation is missing.
+
+## Comments and labels
+
+| Tool                                                             | Purpose                                                                     |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `list_comments` / `create_comment`                               | Thread on work items — use for orchestrator `NEEDS_CLARIFICATION` questions |
+| `list_labels` / `create_label` / `update_label` / `delete_label` | Project labels                                                              |
+
+## Attachments
+
+| Tool                             | Purpose                             |
+| -------------------------------- | ----------------------------------- |
+| `list_work_item_attachments`     | List files                          |
+| `download_work_item_attachments` | Stage to `.task-boards/attachments` |
+| `upload_work_item_attachment`    | Upload local file (multipart)       |
+
+## Delete rules
+
+- MCP may hard-delete **SUBTASK** items only.
+- Use `get_work_item_delete_preview` before delete.
+
+## Work item tags in git
+
+Local commits must include `work-item:{uuid}` in the body for `sync_git_releases` — see `task-boards-git-sync` skill.