@task-boards/mcp-server 0.20.0 → 0.22.0

package/build/cli.js

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
+import { fileURLToPath as __tb_fileURLToPath } from "node:url";
+import { dirname as __tb_dirname } from "node:path";
+const __filename = __tb_fileURLToPath(import.meta.url);
+const __dirname = __tb_dirname(__filename);
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -897,7 +901,8 @@ var require_notifications_enum = __commonJS({
       AGENT_IDE_ATTENTION: "AGENT_IDE_ATTENTION",
       AGENT_NEEDS_CLARIFICATION: "AGENT_NEEDS_CLARIFICATION",
       AGENT_RUN_FAILED: "AGENT_RUN_FAILED",
-      AGENT_QA_HAS_BUGS: "AGENT_QA_HAS_BUGS"
+      AGENT_QA_HAS_BUGS: "AGENT_QA_HAS_BUGS",
+      AGENT_BATCH_COMPLETED: "AGENT_BATCH_COMPLETED"
     };
   }
 });
@@ -1504,7 +1509,8 @@ var require_members_api = __commonJS({
       updateMemberRole: (projectId, memberId) => `/projects/${projectId}/members/${memberId}`,
       removeMember: (projectId, memberId) => `/projects/${projectId}/members/${memberId}`,
       listInvitations: (projectId) => `/projects/${projectId}/invitations`,
-      revokeInvitation: (projectId, invitationId) => `/projects/${projectId}/invitations/${invitationId}`
+      revokeInvitation: (projectId, invitationId) => `/projects/${projectId}/invitations/${invitationId}`,
+      ensureServiceMember: (projectId) => `/projects/${projectId}/members/ensure-service-member`
     };
   }
 });
@@ -1522,7 +1528,7 @@ var require_invitations_enums = __commonJS({
   "../shared/build/internal/members/invitations.enums.js"(exports) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
-    exports.INVITE_OUTCOME = exports.INVITATION_STATUS = void 0;
+    exports.ENSURE_SERVICE_MEMBER_OUTCOME = exports.INVITE_OUTCOME = exports.INVITATION_STATUS = void 0;
     exports.INVITATION_STATUS = {
       PENDING: "PENDING",
       ACCEPTED: "ACCEPTED",
@@ -1533,6 +1539,10 @@ var require_invitations_enums = __commonJS({
       MEMBER_ADDED: "MEMBER_ADDED",
       INVITATION_SENT: "INVITATION_SENT"
     };
+    exports.ENSURE_SERVICE_MEMBER_OUTCOME = {
+      ADDED: "added",
+      ALREADY_PRESENT: "already_present"
+    };
   }
 });
 
@@ -1631,6 +1641,7 @@ var require_exception_codes = __commonJS({
       CANNOT_DEMOTE_LAST_OWNER: "CANNOT_DEMOTE_LAST_OWNER",
       CANNOT_MODIFY_SERVICE_USER: "CANNOT_MODIFY_SERVICE_USER",
       CANNOT_REMOVE_SERVICE_USER: "CANNOT_REMOVE_SERVICE_USER",
+      SERVICE_MEMBER_ENSURE_NOT_APPLICABLE: "SERVICE_MEMBER_ENSURE_NOT_APPLICABLE",
       AGENT_RUN_NOT_COMPLETABLE: "AGENT_RUN_NOT_COMPLETABLE",
       AGENT_RUN_INFLIGHT: "AGENT_RUN_INFLIGHT",
       AGENT_RUN_NOT_RETRYABLE: "AGENT_RUN_NOT_RETRYABLE",
@@ -1703,7 +1714,8 @@ var require_exception_codes = __commonJS({
       PAYMENTS_DISABLED: "PAYMENTS_DISABLED",
       PAYMENTS_NOT_CONFIGURED: "PAYMENTS_NOT_CONFIGURED",
       PAYMENTS_PROBE_FAILED: "PAYMENTS_PROBE_FAILED",
-      SYSTEM_READ_ONLY: "SYSTEM_READ_ONLY"
+      SYSTEM_READ_ONLY: "SYSTEM_READ_ONLY",
+      ESTIMATION_REQUIRED_FOR_MOVE: "ESTIMATION_REQUIRED_FOR_MOVE"
     };
   }
 });
@@ -2502,6 +2514,8 @@ var require_agentic_sdlc_phase_chain = __commonJS({
     exports.advanceAnalysisPhaseSkippingUnbound = advanceAnalysisPhaseSkippingUnbound;
     exports.initPendingDevRoles = initPendingDevRoles;
     exports.removeDevRoleFromPending = removeDevRoleFromPending;
+    exports.isArchitectCompletionHandoff = isArchitectCompletionHandoff;
+    exports.resolvePostArchitectColumnWhenNoDevRoles = resolvePostArchitectColumnWhenNoDevRoles;
     var subagent_role_enum_1 = require_subagent_role_enum();
     var workflow_phase_enum_1 = require_workflow_phase_enum();
     var subagent_role_util_1 = require_subagent_role_util();
@@ -2553,6 +2567,15 @@ var require_agentic_sdlc_phase_chain = __commonJS({
     function removeDevRoleFromPending(pendingDevRoles, completedRole) {
       return pendingDevRoles.filter((role) => role !== completedRole);
     }
+    function isArchitectCompletionHandoff(completedAgentRole, transition) {
+      return completedAgentRole === subagent_role_enum_1.SUBAGENT_ROLE.ARCHITECT && transition.nextColumnSlug === "in-development" && transition.nextWorkflowPhase === null && (transition.kind === "MOVE" || transition.kind === "HANDOFF");
+    }
+    function resolvePostArchitectColumnWhenNoDevRoles(bindings) {
+      if (isRoleBound(bindings, subagent_role_enum_1.SUBAGENT_ROLE.QA)) {
+        return "in-qa";
+      }
+      return "done";
+    }
   }
 });
 
@@ -2561,7 +2584,7 @@ var require_agentic_sdlc_workflow = __commonJS({
   "../shared/build/workflows/agentic-sdlc.workflow.js"(exports) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
-    exports.removeDevRoleFromPending = exports.isRoleBound = exports.initPendingDevRoles = exports.getNextAnalysisPhase = exports.getFirstConfiguredAnalysisPhase = exports.advanceAnalysisPhaseSkippingUnbound = exports.IN_ANALYSIS_PHASE_CHAIN = exports.DEVELOPMENT_DEV_ROLES = exports.AGENTIC_SDLC_COLUMN_CLAIM_PRIORITY = exports.workflowPhaseToSubagentRole = exports.workflowPhaseToAgentRole = exports.subagentRoleToWorkflowPhase = exports.agentRoleToWorkflowPhase = exports.WORKFLOW_TRANSITION_KIND = exports.AGENTIC_SDLC_WORKFLOW = exports.AGENTIC_SDLC_AGENT_COLUMN_SLUGS = exports.IN_AWAITING_COLUMN_SLUG = void 0;
+    exports.resolvePostArchitectColumnWhenNoDevRoles = exports.removeDevRoleFromPending = exports.isRoleBound = exports.isArchitectCompletionHandoff = exports.initPendingDevRoles = exports.getNextAnalysisPhase = exports.getFirstConfiguredAnalysisPhase = exports.advanceAnalysisPhaseSkippingUnbound = exports.IN_ANALYSIS_PHASE_CHAIN = exports.DEVELOPMENT_DEV_ROLES = exports.AGENTIC_SDLC_COLUMN_CLAIM_PRIORITY = exports.workflowPhaseToSubagentRole = exports.workflowPhaseToAgentRole = exports.subagentRoleToWorkflowPhase = exports.agentRoleToWorkflowPhase = exports.WORKFLOW_TRANSITION_KIND = exports.AGENTIC_SDLC_WORKFLOW = exports.AGENTIC_SDLC_AGENT_COLUMN_SLUGS = exports.IN_AWAITING_COLUMN_SLUG = void 0;
     exports.isAgenticSdlcAgentColumnSlug = isAgenticSdlcAgentColumnSlug;
     exports.isInAnalysisPhaseColumn = isInAnalysisPhaseColumn;
     exports.resolveAgenticSdlcTransition = resolveAgenticSdlcTransition;
@@ -2798,12 +2821,18 @@ var require_agentic_sdlc_workflow = __commonJS({
     Object.defineProperty(exports, "initPendingDevRoles", { enumerable: true, get: function() {
       return agentic_sdlc_phase_chain_2.initPendingDevRoles;
     } });
+    Object.defineProperty(exports, "isArchitectCompletionHandoff", { enumerable: true, get: function() {
+      return agentic_sdlc_phase_chain_2.isArchitectCompletionHandoff;
+    } });
     Object.defineProperty(exports, "isRoleBound", { enumerable: true, get: function() {
       return agentic_sdlc_phase_chain_2.isRoleBound;
     } });
     Object.defineProperty(exports, "removeDevRoleFromPending", { enumerable: true, get: function() {
       return agentic_sdlc_phase_chain_2.removeDevRoleFromPending;
     } });
+    Object.defineProperty(exports, "resolvePostArchitectColumnWhenNoDevRoles", { enumerable: true, get: function() {
+      return agentic_sdlc_phase_chain_2.resolvePostArchitectColumnWhenNoDevRoles;
+    } });
   }
 });
 
@@ -2926,7 +2955,7 @@ var require_workflows = __commonJS({
   "../shared/build/workflows/index.js"(exports) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
-    exports.workflowPhaseToSubagentRole = exports.workflowPhaseToAgentRole = exports.subagentRoleToWorkflowPhase = exports.resolveAgenticSdlcTransition = exports.resolveAgenticSdlcNextColumnSlug = exports.removeDevRoleFromPending = exports.isRoleBound = exports.isInAnalysisPhaseColumn = exports.isAgenticSdlcAgentColumnSlug = exports.initPendingDevRoles = exports.getNextAnalysisPhase = exports.getFirstConfiguredAnalysisPhase = exports.agentRoleToWorkflowPhase = exports.advanceAnalysisPhaseSkippingUnbound = exports.WORKFLOW_TRANSITION_KIND = exports.IN_AWAITING_COLUMN_SLUG = exports.IN_ANALYSIS_PHASE_CHAIN = exports.DEVELOPMENT_DEV_ROLES = exports.AGENTIC_SDLC_WORKFLOW = exports.AGENTIC_SDLC_COLUMN_CLAIM_PRIORITY = exports.AGENTIC_SDLC_AGENT_COLUMN_SLUGS = exports.toPhysicalColumnSlug = exports.toLogicalColumnSlug = exports.shouldSyntheticEnqueue = exports.resolveLogicalColumnSlugForWorkItem = exports.isLogicalAgentColumnSlug = void 0;
+    exports.workflowPhaseToSubagentRole = exports.workflowPhaseToAgentRole = exports.subagentRoleToWorkflowPhase = exports.resolvePostArchitectColumnWhenNoDevRoles = exports.resolveAgenticSdlcTransition = exports.resolveAgenticSdlcNextColumnSlug = exports.removeDevRoleFromPending = exports.isRoleBound = exports.isInAnalysisPhaseColumn = exports.isAgenticSdlcAgentColumnSlug = exports.isArchitectCompletionHandoff = exports.initPendingDevRoles = exports.getNextAnalysisPhase = exports.getFirstConfiguredAnalysisPhase = exports.agentRoleToWorkflowPhase = exports.advanceAnalysisPhaseSkippingUnbound = exports.WORKFLOW_TRANSITION_KIND = exports.IN_AWAITING_COLUMN_SLUG = exports.IN_ANALYSIS_PHASE_CHAIN = exports.DEVELOPMENT_DEV_ROLES = exports.AGENTIC_SDLC_WORKFLOW = exports.AGENTIC_SDLC_COLUMN_CLAIM_PRIORITY = exports.AGENTIC_SDLC_AGENT_COLUMN_SLUGS = exports.toPhysicalColumnSlug = exports.toLogicalColumnSlug = exports.shouldSyntheticEnqueue = exports.resolveLogicalColumnSlugForWorkItem = exports.isLogicalAgentColumnSlug = void 0;
     var column_slug_mapping_1 = require_column_slug_mapping();
     Object.defineProperty(exports, "isLogicalAgentColumnSlug", { enumerable: true, get: function() {
       return column_slug_mapping_1.isLogicalAgentColumnSlug;
@@ -2980,6 +3009,9 @@ var require_workflows = __commonJS({
     Object.defineProperty(exports, "initPendingDevRoles", { enumerable: true, get: function() {
       return agentic_sdlc_workflow_1.initPendingDevRoles;
     } });
+    Object.defineProperty(exports, "isArchitectCompletionHandoff", { enumerable: true, get: function() {
+      return agentic_sdlc_workflow_1.isArchitectCompletionHandoff;
+    } });
     Object.defineProperty(exports, "isAgenticSdlcAgentColumnSlug", { enumerable: true, get: function() {
       return agentic_sdlc_workflow_1.isAgenticSdlcAgentColumnSlug;
     } });
@@ -2998,6 +3030,9 @@ var require_workflows = __commonJS({
     Object.defineProperty(exports, "resolveAgenticSdlcTransition", { enumerable: true, get: function() {
       return agentic_sdlc_workflow_1.resolveAgenticSdlcTransition;
     } });
+    Object.defineProperty(exports, "resolvePostArchitectColumnWhenNoDevRoles", { enumerable: true, get: function() {
+      return agentic_sdlc_workflow_1.resolvePostArchitectColumnWhenNoDevRoles;
+    } });
     Object.defineProperty(exports, "subagentRoleToWorkflowPhase", { enumerable: true, get: function() {
       return agentic_sdlc_workflow_1.subagentRoleToWorkflowPhase;
     } });
@@ -5029,6 +5064,10 @@ function isAttentionCliInvocation(argv) {
   return topLevel === "attention" || topLevel === "orchestrator";
 }
 
+// src/cli-help.ts
+import { readFileSync as readFileSync4 } from "node:fs";
+import { join as join5 } from "node:path";
+
 // src/config.ts
 var import_api = __toESM(require_build(), 1);
 function resolveSanitizeResponses() {
@@ -5047,15 +5086,22 @@ function resolveBlockSensitiveAttachments() {
   const normalized = raw.trim().toLowerCase();
   return normalized !== "false" && normalized !== "0" && normalized !== "no";
 }
+function resolveApiUrlFromEnv(env = process.env) {
+  const rawBaseUrl = (env.TASK_BOARDS_API_URL ?? "http://localhost:3000").replace(/\/$/, "");
+  return {
+    rawBaseUrl,
+    effectiveApiUrl: `${rawBaseUrl}${import_api.API_V1_PREFIX}`
+  };
+}
 function loadConfig() {
-  const apiUrl = process.env.TASK_BOARDS_API_URL ?? "http://localhost:3000";
+  const { effectiveApiUrl } = resolveApiUrlFromEnv();
   const apiToken = process.env.TASK_BOARDS_API_TOKEN;
   const workspaceRoot = process.env.WORKSPACE_ROOT;
   if (process.env.NODE_ENV === "production" && (apiToken === void 0 || apiToken.trim() === "")) {
     console.error("WARNING: TASK_BOARDS_API_TOKEN is not set. MCP server cannot authenticate to the Task Boards API.");
   }
   return {
-    apiUrl: `${apiUrl.replace(/\/$/, "")}${import_api.API_V1_PREFIX}`,
+    apiUrl: effectiveApiUrl,
     apiToken,
     workspaceRoot: workspaceRoot !== void 0 && workspaceRoot.trim() !== "" ? workspaceRoot : void 0,
     sanitizeResponses: resolveSanitizeResponses(),
@@ -5063,6 +5109,405 @@ function loadConfig() {
   };
 }
 
+// src/cli-help.ts
+var NPM_README_URL = "https://www.npmjs.com/package/@task-boards/mcp-server#readme";
+var CLI_ENV_VARS = [
+  {
+    name: "TASK_BOARDS_API_URL",
+    required: "No",
+    defaultDisplay: "http://localhost:3000",
+    description: "Task Boards backend base URL (without /api/v1 suffix)"
+  },
+  {
+    name: "TASK_BOARDS_API_TOKEN",
+    required: "Yes in production",
+    defaultDisplay: "(unset \u2014 value never printed)",
+    description: "API token with read / write scopes"
+  },
+  {
+    name: "WORKSPACE_ROOT",
+    required: "No",
+    defaultDisplay: "(unset)",
+    description: "Git repo root for attachments, sync tools, and orchestrator bridge state"
+  },
+  {
+    name: "TASK_BOARDS_MCP_SANITIZE",
+    required: "No",
+    defaultDisplay: "true (enabled)",
+    description: "Sanitize MCP tool responses; set false, 0, or no to disable"
+  },
+  {
+    name: "TASK_BOARDS_MCP_BLOCK_SENSITIVE_ATTACHMENTS",
+    required: "No",
+    defaultDisplay: "true (enabled)",
+    description: "Block sensitive attachment paths; set false, 0, or no to disable"
+  }
+];
+var CLI_TOOL_CATALOG = [
+  {
+    name: "list_projects",
+    description: "List task-boards projects (non-archived by default)."
+  },
+  {
+    name: "get_project",
+    description: "Get a project by id."
+  },
+  {
+    name: "create_project",
+    description: "Create a project and its board from the selected preset."
+  },
+  {
+    name: "update_project",
+    description: "Update project settings (name, description, estimation mode/required, task card estimation display, subagent role bindings). Requires write scope."
+  },
+  {
+    name: "resolve_project",
+    description: "Resolve the task-boards project for the current workspace (.task-boards.yaml, .cursor/rules, or folder name auto-match)."
+  },
+  {
+    name: "list_work_items",
+    description: "List work items for a project."
+  },
+  {
+    name: "search_work_items",
+    description: "Search work items by query string (title, description, acceptance criteria, display key)."
+  },
+  {
+    name: "get_work_item",
+    description: "Get a work item by id."
+  },
+  {
+    name: "create_work_item",
+    description: "Create a work item under a project. MCP/automation attributes creator and default assignee to the \xAB\u0410\u0433\u0435\u043D\u0442 \u0418\u0418\xBB service user (UserKind.SERVICE) unless assigneeUserId is set. The AI orchestrator processes STORY items only when assignee is that service user. Priority defaults to LOW when omitted. storyPoints and estimate are optional on create; when project.estimationRequired is true they are required before moving a STORY to any column except backlog (slug=backlog)."
+  },
+  {
+    name: "update_work_item",
+    description: "Update work item fields (fetches current version first)."
+  },
+  {
+    name: "move_work_item",
+    description: "Move a work item to another board column (fetches current version first). When project.estimationRequired is true, returns ESTIMATION_REQUIRED_FOR_MOVE (422) if the STORY lacks active storyPoints or estimate (per estimationMode) and the target column slug is not backlog."
+  },
+  {
+    name: "get_work_item_delete_preview",
+    description: "Preview hard-delete impact for a work item (cascade counts and eligibility). MCP may delete SUBTASK items only."
+  },
+  {
+    name: "delete_work_item",
+    description: "Hard-delete a SUBTASK work item (leaf delete with confirmCascade false). EPIC/STORY deletes are human-only."
+  },
+  {
+    name: "list_comments",
+    description: "List comments for a work item (newest last)."
+  },
+  {
+    name: "create_comment",
+    description: "Create a comment on a work item. Use for orchestrator NEEDS_CLARIFICATION questions before complete_agent_run."
+  },
+  {
+    name: "list_labels",
+    description: "List labels for a project."
+  },
+  {
+    name: "create_label",
+    description: "Create a project label."
+  },
+  {
+    name: "update_label",
+    description: "Update a project label."
+  },
+  {
+    name: "delete_label",
+    description: "Delete a project label."
+  },
+  {
+    name: "list_work_item_attachments",
+    description: "List file attachments for a work item."
+  },
+  {
+    name: "download_work_item_attachments",
+    description: "Download work item attachments into the local workspace staging directory (.task-boards/attachments)."
+  },
+  {
+    name: "upload_work_item_attachment",
+    description: "Upload a local workspace file as a work item attachment (multipart field file)."
+  },
+  {
+    name: "get_board",
+    description: "Get board projection for a project (columns and on-board work items)."
+  },
+  {
+    name: "list_agent_runs",
+    description: "List agent runs for a project (default status PENDING). Prefer wait_for_agent_runs for orchestrator long-polling."
+  },
+  {
+    name: "wait_for_agent_runs",
+    description: "Long-poll agent runs for a project: atomically claims PENDING runs (POST /agent-runs/claim). On empty claim, immediately lists inflight DISPATCHED/ACKNOWLEDGED runs (GET activeOnly) for orphan recovery before sleeping. Returns items (newly claimed), inflightRuns (resume candidates), and orchestrator hints. First claim is immediate; subsequent polls sleep pollInterval seconds only when both claim and inflight are empty."
+  },
+  {
+    name: "ack_agent_run",
+    description: "Acknowledge agent run delivery after Task subagent has been dispatched. Requires status DISPATCHED (DISPATCHED \u2192 ACKNOWLEDGED)."
+  },
+  {
+    name: "report_agent_attention",
+    description: "Signal that the in-flight subagent needs human attention while the run is ACKNOWLEDGED. Sets requiresAttention on the agent run for orchestrator/UI visibility."
+  },
+  {
+    name: "clear_agent_attention",
+    description: "Clear the human-attention flag after the blocker is resolved. Requires the run to still be ACKNOWLEDGED."
+  },
+  {
+    name: "complete_agent_run",
+    description: "Complete agent run: apply AGENTIC_SDLC workflow transition and optional work item patch. AGENTIC_SDLC has 7 columns: backlog, in-analysis (PRODUCT\u2192ANALYST\u2192ARCHITECT handoffs), in-development (DESIGNER optional, then parallel FRONTEND_DEVELOPER+DEVELOPER), in-qa, in-awaiting, done, released. Outcomes: Prerequisite: STORY assignee must be \u0410\u0433\u0435\u043D\u0442 \u0418\u0418 (SERVICE user) \u2014 otherwise no agent_run is enqueued or claimed. in-analysis: PRODUCT/ANALYST DEFAULT \u2192 HANDOFF next phase (skip unbound roles); ANALYST SKIP_DESIGN \u2192 in-development; ANALYST SKIP_DEV \u2192 released when codeChangesRequired=false (no git commit); ARCHITECT DEFAULT \u2192 in-development (set workItemPatch.designerRequired). in-development: DESIGNER DEFAULT \u2192 DEVELOPMENT; dev role DEFAULT removes role from pendingDevRoles, moves to in-qa when empty; SKIP_DESIGN skips DESIGNER. in-qa: DEFAULT \u2192 done; HAS_BUGS \u2192 in-development (re-init pendingDevRoles). NEEDS_CLARIFICATION \u2192 in-awaiting. FAILED \u2192 no move. Claim priority: in-development > in-qa > in-analysis (SERVICE-assigned stories only block analysis)."
+  },
+  {
+    name: "run_orchestrator_once",
+    description: "Resolve project (if needed), long-poll agent runs with atomic claim, and return orchestrator hints. Claims only STORY items assigned to \u0410\u0433\u0435\u043D\u0442 \u0418\u0418 (SERVICE user). Does not call sync_git_releases \u2014 the orchestrator agent decides when to sync."
+  },
+  {
+    name: "sync_git_releases",
+    description: "Fetch origin and sync commits tagged with work-item:{uuid} from the default branch (master/main) and, when cwd is on a feature branch, the current branch too. Use after git push on feature branches; on master/main local commit only. Requires MCP API token with write scope."
+  },
+  {
+    name: "sync_project_subagents",
+    description: "Sync project custom subagent definitions from the API to {workspaceRoot}/.cursor/agents/{slug}.md so the IDE Task tool can resolve custom slugs. Idempotent overwrite. Requires MCP API token with write scope."
+  }
+];
+var CLI_AUX_MODES = [
+  {
+    invocation: "task-boards-mcp",
+    description: "Default: MCP stdio server for IDE clients"
+  },
+  {
+    invocation: "task-boards-mcp attention report",
+    description: "Report IDE attention for an in-flight agent run (orchestrator hooks)"
+  },
+  {
+    invocation: "task-boards-mcp attention report-from-hook",
+    description: "Report IDE attention from Cursor hook stdin payload"
+  },
+  {
+    invocation: "task-boards-mcp attention clear",
+    description: "Clear local attention pending state"
+  },
+  {
+    invocation: "task-boards-mcp orchestrator write-active-run",
+    description: "Persist active agent run state to workspace bridge files"
+  },
+  {
+    invocation: "task-boards-mcp orchestrator clear-active-run",
+    description: "Clear orchestrator bridge state from workspace"
+  },
+  {
+    invocation: "task-boards-mcp skills install [--global]",
+    description: "Install bundled Task Boards Cursor skills to .cursor/skills/ (project) or ~/.cursor/skills/ (--global)"
+  }
+];
+function isHelpInvocation(argv) {
+  const topLevel = argv[0];
+  return topLevel === "-h" || topLevel === "--help";
+}
+function readPackageMeta() {
+  const pkgPath = join5(__dirname, "../package.json");
+  const pkg = JSON.parse(readFileSync4(pkgPath, "utf8"));
+  return {
+    name: pkg.name,
+    version: pkg.version
+  };
+}
+function formatEnvSection(env) {
+  const lines = ["ENVIRONMENT"];
+  for (const variable of CLI_ENV_VARS) {
+    lines.push(`  ${variable.name}`);
+    lines.push(`    Required: ${variable.required}`);
+    lines.push(`    Default: ${variable.defaultDisplay}`);
+    lines.push(`    ${variable.description}`);
+    lines.push("");
+  }
+  const { effectiveApiUrl } = resolveApiUrlFromEnv(env);
+  lines.push("  Effective API base: {TASK_BOARDS_API_URL without trailing slash}/api/v1");
+  lines.push(`  Example default: ${effectiveApiUrl}`);
+  return lines.join("\n");
+}
+function formatToolsSection() {
+  const lines = [`MCP TOOLS (${CLI_TOOL_CATALOG.length})`];
+  for (const tool of CLI_TOOL_CATALOG) {
+    lines.push(`  ${tool.name} \u2014 ${tool.description}`);
+  }
+  return lines.join("\n");
+}
+function formatAuxModesSection() {
+  const lines = ["AUXILIARY CLI MODES"];
+  for (const mode of CLI_AUX_MODES) {
+    lines.push(`  ${mode.invocation}`);
+    lines.push(`    ${mode.description}`);
+  }
+  lines.push("");
+  lines.push("  attention report|report-from-hook|clear");
+  lines.push("  orchestrator write-active-run|clear-active-run");
+  lines.push("  skills install [--global]");
+  return lines.join("\n");
+}
+function formatCliHelp(options = {}) {
+  const packageMeta = options.packageMeta ?? readPackageMeta();
+  const env = options.env ?? process.env;
+  const sections = [
+    `${packageMeta.name} ${packageMeta.version}`,
+    "",
+    "USAGE",
+    "  task-boards-mcp [--help|-h]",
+    "  task-boards-mcp [attention|orchestrator ...]   # auxiliary bridge modes",
+    "  task-boards-mcp skills install [--global]       # install bundled Cursor skills",
+    "  task-boards-mcp                                 # default: MCP stdio server",
+    "",
+    formatEnvSection(env),
+    "",
+    formatToolsSection(),
+    "",
+    formatAuxModesSection(),
+    "",
+    "DOCUMENTATION",
+    `  Orchestrator loop, IDE MCP config: ${NPM_README_URL}`,
+    "  Local development: packages/mcp-server/README.md",
+    ""
+  ];
+  return sections.join("\n");
+}
+
+// src/skills/install-bundled-skills.ts
+import { copyFileSync, existsSync as existsSync6, mkdirSync as mkdirSync3 } from "node:fs";
+import { join as join6 } from "node:path";
+
+// src/skills/bundled-skills-catalog.ts
+var BUNDLED_SKILL_NAMES = [
+  "task-boards-setup",
+  "task-boards-orchestrator",
+  "task-boards-work-items",
+  "task-boards-agent-runs",
+  "task-boards-attention",
+  "task-boards-git-sync"
+];
+
+// src/skills/install-bundled-skills.ts
+var BundledSkillsError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BundledSkillsError";
+  }
+};
+function installBundledSkills(params) {
+  const { bundledSkillsRoot, targetSkillsRoot } = params;
+  const packageMeta = readPackageMeta();
+  mkdirSync3(targetSkillsRoot, { recursive: true });
+  const skills = [];
+  for (const skillName of BUNDLED_SKILL_NAMES) {
+    const srcFile = join6(bundledSkillsRoot, skillName, "SKILL.md");
+    if (!existsSync6(srcFile)) {
+      throw new BundledSkillsError(`Missing bundled skill file: ${srcFile}`);
+    }
+    const destDir = join6(targetSkillsRoot, skillName);
+    const destFile = join6(destDir, "SKILL.md");
+    const action = existsSync6(destFile) ? "overwritten" : "installed";
+    mkdirSync3(destDir, { recursive: true });
+    copyFileSync(srcFile, destFile);
+    skills.push({
+      skillName,
+      targetPath: destFile,
+      action
+    });
+  }
+  return {
+    targetDirectory: targetSkillsRoot,
+    packageName: packageMeta.name,
+    packageVersion: packageMeta.version,
+    skills
+  };
+}
+
+// src/skills/resolve-bundled-skills-root.ts
+import { homedir } from "node:os";
+import { join as join7 } from "node:path";
+function resolveBundledSkillsRoot() {
+  return join7(__dirname, "../skills");
+}
+function resolveProjectSkillsTarget(workspaceRoot) {
+  return join7(workspaceRoot, ".cursor", "skills");
+}
+function resolveGlobalSkillsTarget(homeDirectory = homedir()) {
+  return join7(homeDirectory, ".cursor", "skills");
+}
+
+// src/skills/skills-cli.ts
+function defaultLog(message) {
+  process.stdout.write(`${message}
+`);
+}
+function defaultLogError(message) {
+  process.stderr.write(`${message}
+`);
+}
+function isSkillsCliInvocation(argv) {
+  return argv[0] === "skills";
+}
+function hasGlobalFlag(argv) {
+  return argv.includes("--global");
+}
+function formatSkillsInstallSummary(result) {
+  const lines = [
+    `Installed Task Boards skills (${result.packageName} ${result.packageVersion})`,
+    `Target: ${result.targetDirectory}`,
+    ""
+  ];
+  for (const skill of result.skills) {
+    lines.push(`  ${skill.skillName}: ${skill.action}`);
+  }
+  return lines.join("\n");
+}
+function runSkillsCli(argv, deps = {}) {
+  const log = deps.log ?? defaultLog;
+  const logError = deps.logError ?? defaultLogError;
+  const installFn = deps.installFn ?? installBundledSkills;
+  const resolveBundledRoot = deps.resolveBundledRoot ?? resolveBundledSkillsRoot;
+  const resolveWorkspace = deps.resolveWorkspace ?? resolveWorkspaceRoot;
+  const resolveGlobalTarget = deps.resolveGlobalTarget ?? resolveGlobalSkillsTarget;
+  const subcommand = argv[1];
+  if (subcommand !== "install") {
+    logError("Usage: task-boards-mcp skills install [--global]");
+    return 1;
+  }
+  const isGlobal = hasGlobalFlag(argv);
+  let targetSkillsRoot;
+  try {
+    if (isGlobal) {
+      targetSkillsRoot = resolveGlobalTarget();
+    } else {
+      const config = loadConfig();
+      const workspaceRoot = resolveWorkspace(void 0, config.workspaceRoot);
+      targetSkillsRoot = resolveProjectSkillsTarget(workspaceRoot);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Failed to resolve skills install target";
+    logError(message);
+    return 1;
+  }
+  try {
+    const result = installFn({
+      bundledSkillsRoot: resolveBundledRoot(),
+      targetSkillsRoot
+    });
+    log(formatSkillsInstallSummary(result));
+    return 0;
+  } catch (error) {
+    if (error instanceof BundledSkillsError) {
+      logError(error.message);
+      return 1;
+    }
+    const message = error instanceof Error ? error.message : "Failed to install bundled skills";
+    logError(message);
+    return 1;
+  }
+}
+
 // src/index.ts
 import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -5509,8 +5954,8 @@ function autoMatchProject(folderToken, projects) {
 }
 
 // src/workspace/parse-ide-rules.ts
-import { existsSync as existsSync6, readdirSync, readFileSync as readFileSync4 } from "node:fs";
-import { join as join5 } from "node:path";
+import { existsSync as existsSync7, readdirSync, readFileSync as readFileSync5 } from "node:fs";
+import { join as join8 } from "node:path";
 var PROJECT_ID_LINE_PATTERN = /projectId\s*[:=]\s*["']?([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})/gi;
 var TASK_BOARDS_UUID_PATTERN = /task-boards[^\n\r]*?([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})/gi;
 function extractUuids(content) {
@@ -5529,8 +5974,8 @@ function extractUuids(content) {
   return ids;
 }
 function parseIdeRules(workspaceRoot) {
-  const rulesDir = join5(workspaceRoot, ".cursor", "rules");
-  if (!existsSync6(rulesDir)) {
+  const rulesDir = join8(workspaceRoot, ".cursor", "rules");
+  if (!existsSync7(rulesDir)) {
     return { status: "missing" };
   }
   const entries = readdirSync(rulesDir, { withFileTypes: true });
@@ -5542,7 +5987,7 @@ function parseIdeRules(workspaceRoot) {
     if (!entry.name.endsWith(".mdc") && !entry.name.endsWith(".md")) {
       continue;
     }
-    const content = readFileSync4(join5(rulesDir, entry.name), "utf8");
+    const content = readFileSync5(join8(rulesDir, entry.name), "utf8");
     for (const id of extractUuids(content)) {
       allIds.add(id);
     }
@@ -6184,7 +6629,7 @@ function registerWorkItemTools(server, client) {
   server.registerTool(
     "create_work_item",
     {
-      description: "Create a work item under a project. MCP/automation attributes creator and default assignee to the \xAB\u0410\u0433\u0435\u043D\u0442 \u0418\u0418\xBB service user (UserKind.SERVICE) unless assigneeUserId is set. The AI orchestrator processes STORY items only when assignee is that service user. Priority defaults to LOW when omitted.",
+      description: "Create a work item under a project. MCP/automation attributes creator and default assignee to the \xAB\u0410\u0433\u0435\u043D\u0442 \u0418\u0418\xBB service user (UserKind.SERVICE) unless assigneeUserId is set. The AI orchestrator processes STORY items only when assignee is that service user. Priority defaults to LOW when omitted. storyPoints and estimate are optional on create; when project.estimationRequired is true they are required before moving a STORY to any column except backlog (slug=backlog).",
       inputSchema: {
         projectId: z11.string().uuid().describe("Project UUID"),
         type: z11.enum(workItemTypeValues).describe("Work item type"),
@@ -6193,9 +6638,11 @@ function registerWorkItemTools(server, client) {
         description: z11.string().nullable().optional().describe("Work item description"),
         acceptanceCriteria: z11.string().nullable().optional().describe("Acceptance criteria"),
         priority: z11.enum(priorityValues).nullable().optional().describe("Work item priority; defaults to LOW when omitted or null"),
-        storyPoints: z11.number().int().min(0).max(999).nullable().optional().describe("Story points (EPIC/STORY only). Required when project estimationRequired and mode is storyPoints"),
+        storyPoints: z11.number().int().min(0).max(999).nullable().optional().describe(
+          "Story points (EPIC/STORY only). Optional on create; required before move to non-backlog columns when project estimationRequired and mode is storyPoints"
+        ),
         estimate: z11.string().nullable().optional().describe(
-          "Estimate in hours as decimal string (EPIC/STORY only). Required when estimationRequired and mode is estimate"
+          "Estimate in hours as decimal string (EPIC/STORY only). Optional on create; required before move to non-backlog columns when estimationRequired and mode is estimate"
         ),
         assigneeUserId: z11.string().uuid().nullable().optional().describe(
           "Project member user id; defaults to creator (human) or \xAB\u0410\u0433\u0435\u043D\u0442 \u0418\u0418\xBB service user (MCP) when omitted"
@@ -6290,7 +6737,7 @@ function registerWorkItemTools(server, client) {
   server.registerTool(
     "move_work_item",
     {
-      description: "Move a work item to another board column (fetches current version first).",
+      description: "Move a work item to another board column (fetches current version first). When project.estimationRequired is true, returns ESTIMATION_REQUIRED_FOR_MOVE (422) if the STORY lacks active storyPoints or estimate (per estimationMode) and the target column slug is not backlog.",
       inputSchema: {
         workItemId: z11.string().uuid().describe("Work item UUID"),
         columnId: z11.string().uuid().describe("Target column UUID")
@@ -6364,12 +6811,20 @@ async function main() {
 // src/cli.ts
 async function main2() {
   const argv = process.argv.slice(2);
+  if (isHelpInvocation(argv)) {
+    process.stdout.write(formatCliHelp({ packageMeta: readPackageMeta() }));
+    process.exit(0);
+  }
   if (isAttentionCliInvocation(argv)) {
     const config = loadConfig();
     const client = new RestClient(config.apiUrl, config.apiToken);
     const exitCode = await runAttentionCli(argv, { config, client });
     process.exit(exitCode);
   }
+  if (isSkillsCliInvocation(argv)) {
+    const exitCode = runSkillsCli(argv);
+    process.exit(exitCode);
+  }
   await main();
 }
 main2().catch((error) => {