harmony-mcp 1.2.4 → 1.3.1

package/README.md

@@ -4,7 +4,7 @@ MCP (Model Context Protocol) server for Harmony Kanban board. Enables AI coding
 
 ## Features
 
-- **25+ MCP Tools** for full board control (cards, columns, labels, subtasks, links)
+- **29 MCP Tools** for full board control (cards, columns, labels, subtasks, links)
 - **Card Linking** - create relationships between cards (blocks, relates_to, duplicates, is_part_of)
 - **Prompt Builder** - generate AI-ready prompts from cards with context
 - **Agent Session Tracking** - track work progress with timer badges
@@ -98,10 +98,13 @@ harmony-mcp init               # Initialize for AI agents (interactive)
 harmony-mcp init --all         # Configure all supported agents
 harmony-mcp init --detect      # Auto-detect and configure installed agents
 harmony-mcp init --agent X Y   # Configure specific agents
-harmony-mcp status             # Show current config
+harmony-mcp init -w WS -p PROJ # Initialize with local workspace/project context
+harmony-mcp status             # Show current config (global and local)
 harmony-mcp reset              # Clear configuration
-harmony-mcp set-workspace ID   # Set active workspace
-harmony-mcp set-project ID     # Set active project
+harmony-mcp set-workspace ID   # Set active workspace (global)
+harmony-mcp set-workspace ID -l # Set active workspace (local project)
+harmony-mcp set-project ID     # Set active project (global)
+harmony-mcp set-project ID -l  # Set active project (local project)
 harmony-mcp serve              # Start MCP server
 ```
 
@@ -233,7 +236,9 @@ curl -X GET "https://gethmy.com/api/workspaces" \
 
 ## Configuration
 
-Your configuration is stored in `~/.harmony-mcp/config.json`:
+### Global Configuration
+
+Your global configuration is stored in `~/.harmony-mcp/config.json`:
 
 ```json
 {
@@ -244,6 +249,66 @@ Your configuration is stored in `~/.harmony-mcp/config.json`:
 }
 ```
 
+### Local Project Configuration
+
+For multi-project workflows, you can set project-specific context using local configuration. This is stored in `.harmony-mcp.json` in your project root:
+
+```json
+{
+  "workspaceId": "uuid-here",
+  "projectId": "uuid-here"
+}
+```
+
+**Priority**: Local config overrides global config for workspace and project context.
+
+**Security**: API key is never stored locally (only in global config) to prevent accidental commits.
+
+#### Setting Local Context
+
+```bash
+# During initialization
+harmony-mcp init --workspace <ws-id> --project <proj-id>
+
+# Or separately
+harmony-mcp set-workspace <id> --local
+harmony-mcp set-project <id> --local
+```
+
+#### Viewing Configuration
+
+```bash
+harmony-mcp status
+```
+
+Example output:
+
+```
+Status: Configured
+API Key: hmy_abc1...
+API URL: https://gethmy.com/api
+
+Global Context:
+  Workspace: <global-ws-id>
+  Project: <global-proj-id>
+
+Local Context (.harmony-mcp.json):
+  Workspace: <local-ws-id>
+  Project: <local-proj-id>
+
+Active (effective):
+  Workspace: <local-ws-id>  ← local
+  Project: <local-proj-id>  ← local
+```
+
+#### Recommended .gitignore
+
+Add this to prevent accidentally committing local config:
+
+```
+.harmony-mcp.json
+```
+
 ## Architecture
 
 ```

package/dist/cli.js

@@ -13792,77 +13792,78 @@ import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 var HARMONY_WORKFLOW_PROMPT = `# Harmony Card Workflow
 
-You are starting work on a Harmony card. Follow this workflow:
+Start work on a Harmony card. Card reference: $ARGUMENTS
 
-## Step 1: Find the Card
+## 1. Find & Fetch Card
 
-The user provided: $ARGUMENTS
+Parse the reference and fetch the card:
+- \`#42\` or \`42\` → \`harmony_get_card_by_short_id\` with \`shortId: 42\`
+- UUID → \`harmony_get_card\` with \`cardId\`
+- Name/text → \`harmony_search_cards\` with \`query\`
 
-Parse the card reference:
-- If it starts with \`#\` followed by numbers (e.g., \`#42\`), use \`harmony_get_card_by_short_id\` with the number
-- If it looks like a UUID, use \`harmony_get_card\` directly
-- Otherwise, use \`harmony_search_cards\` to find by name
+## 2. Get Board State
 
-## Step 2: Move to In Progress
+Call \`harmony_get_board\` to get columns and labels. From the response:
+- Find the "In Progress" (or "Progress") column ID
+- Find the "agent" label ID
 
-Once you have the card:
-1. Get the board using \`harmony_get_board\` to find the "In Progress" column ID
-2. Use \`harmony_move_card\` to move the card to "In Progress"
+## 3. Setup Card for Work
 
-## Step 3: Add Agent Label
+Execute these in sequence:
+1. \`harmony_move_card\` → Move to "In Progress" column
+2. \`harmony_add_label_to_card\` → Add "agent" label
+3. \`harmony_start_agent_session\`:
+   - \`cardId\`: Card UUID
+   - \`agentIdentifier\`: Your agent identifier
+   - \`agentName\`: Your agent name
+   - \`currentTask\`: "Analyzing card requirements"
 
-1. From the board response, find the label named "agent"
-2. Use \`harmony_add_label_to_card\` to add it to the card
+## 4. Generate Work Prompt
 
-## Step 4: Start Agent Session
+Call \`harmony_generate_prompt\` with:
+- \`cardId\` or \`shortId\` (+ \`projectId\` if using shortId)
+- \`variant\`: Select based on task:
+  - \`"execute"\` (default) → Clear tasks, bug fixes, well-defined work
+  - \`"analysis"\` → Complex features, unclear requirements
+  - \`"draft"\` → Medium complexity, want feedback first
 
-After adding the agent label, start tracking your work session:
-1. Use \`harmony_start_agent_session\` with:
-   - \`cardId\`: The card ID
-   - \`agentIdentifier\`: Your agent identifier
-   - \`agentName\`: Your agent name
-   - \`currentTask\`: A brief description of what you're about to do
-
-This enables the timer badge on the card to show your progress in real-time.
-
-## Step 5: Display Card Details
-
-Show the user:
-- Card title and short ID
-- Description (if any)
-- Priority
-- Current labels
-- Due date (if set)
-
-## Step 6: Implement the Solution
-
-1. Use \`harmony_generate_prompt\` with the card ID to get role-based guidance
-2. Follow the generated prompt to implement the solution
-3. Test the changes
-
-**During implementation, update your progress periodically:**
-- Use \`harmony_update_agent_progress\` to report:
-  - \`progressPercent\`: Estimated completion (0-100)
-  - \`currentTask\`: What you're currently doing
-  - \`blockers\`: Any issues blocking progress (set \`status: "blocked"\` if blocked)
-
-## Step 7: Complete Work
-
-When implementation is complete:
-1. Use \`harmony_end_agent_session\` with:
-   - \`cardId\`: The card ID
-   - \`status\`: "completed"
-   - \`progressPercent\`: 100
-2. Use \`harmony_move_card\` to move the card to the "Review" column
-3. Summarize what was accomplished
-
-## Important Notes
-- Always read the card description carefully before starting
-- If the task is unclear, ask for clarification
-- Make commits as appropriate during implementation
-- The "agent" label indicates AI is working on the card
-- Update progress at meaningful milestones, not constantly
-- If you need to pause work, call \`harmony_end_agent_session\` with \`status: "paused"\`
+The generated prompt provides role framing, focus areas, subtasks, linked cards, and suggested outputs.
+
+## 5. Display Card Summary
+
+Show the user: Card title, short ID, role, priority, labels, due date, description, and subtasks.
+
+## 6. Implement Solution
+
+Work on the card following the generated prompt's guidance. Update progress at milestones:
+- \`harmony_update_agent_progress\` with \`progressPercent\` (0-100), \`currentTask\`, \`status\`, \`blockers\`
+
+**Progress checkpoints:** 20% (exploration), 50% (implementation), 80% (testing), 100% (done)
+
+## 7. Complete Work
+
+When finished:
+1. \`harmony_end_agent_session\` with \`status: "completed"\`, \`progressPercent: 100\`
+2. \`harmony_move_card\` to "Review" column
+3. Summarize accomplishments
+
+If pausing: \`harmony_end_agent_session\` with \`status: "paused"\`
+
+## Key Tools Reference
+
+**Cards:** \`harmony_get_card\`, \`harmony_get_card_by_short_id\`, \`harmony_search_cards\`, \`harmony_create_card\`, \`harmony_update_card\`, \`harmony_move_card\`, \`harmony_delete_card\`, \`harmony_assign_card\`
+
+**Subtasks:** \`harmony_create_subtask\`, \`harmony_toggle_subtask\`, \`harmony_delete_subtask\`
+
+**Labels:** \`harmony_add_label_to_card\`, \`harmony_remove_label_from_card\`, \`harmony_create_label\`
+
+**Links:** \`harmony_add_link_to_card\`, \`harmony_remove_link_from_card\`, \`harmony_get_card_links\`
+
+**Board:** \`harmony_get_board\`, \`harmony_list_projects\`, \`harmony_get_context\`, \`harmony_set_project_context\`
+
+**Sessions:** \`harmony_start_agent_session\`, \`harmony_update_agent_progress\`, \`harmony_end_agent_session\`, \`harmony_get_agent_session\`
+
+**AI:** \`harmony_generate_prompt\`, \`harmony_process_command\`
 `;
 function ensureDir(dirPath) {
   if (!existsSync(dirPath)) {
@@ -25233,12 +25234,16 @@ import { homedir as homedir2 } from "node:os";
 import { join as join2 } from "node:path";
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
 var DEFAULT_API_URL = "https://gethmy.com/api";
+var LOCAL_CONFIG_FILENAME = ".harmony-mcp.json";
 function getConfigDir() {
   return join2(homedir2(), ".harmony-mcp");
 }
 function getConfigPath() {
   return join2(getConfigDir(), "config.json");
 }
+function getLocalConfigPath(cwd) {
+  return join2(cwd || process.cwd(), LOCAL_CONFIG_FILENAME);
+}
 function loadConfig() {
   const configPath = getConfigPath();
   if (!existsSync2(configPath)) {
@@ -25277,6 +25282,39 @@ function saveConfig(config2) {
   const newConfig = { ...existingConfig, ...config2 };
   writeFileSync2(configPath, JSON.stringify(newConfig, null, 2), { mode: 384 });
 }
+function loadLocalConfig(cwd) {
+  const localConfigPath = getLocalConfigPath(cwd);
+  if (!existsSync2(localConfigPath)) {
+    return null;
+  }
+  try {
+    const data = readFileSync2(localConfigPath, "utf-8");
+    const config2 = JSON.parse(data);
+    return {
+      workspaceId: config2.workspaceId || null,
+      projectId: config2.projectId || null
+    };
+  } catch {
+    return null;
+  }
+}
+function saveLocalConfig(config2, cwd) {
+  const localConfigPath = getLocalConfigPath(cwd);
+  const existingConfig = loadLocalConfig(cwd) || {
+    workspaceId: null,
+    projectId: null
+  };
+  const newConfig = { ...existingConfig, ...config2 };
+  const cleanConfig = {};
+  if (newConfig.workspaceId)
+    cleanConfig.workspaceId = newConfig.workspaceId;
+  if (newConfig.projectId)
+    cleanConfig.projectId = newConfig.projectId;
+  writeFileSync2(localConfigPath, JSON.stringify(cleanConfig, null, 2));
+}
+function hasLocalConfig(cwd) {
+  return existsSync2(getLocalConfigPath(cwd));
+}
 function getApiKey() {
   const config2 = loadConfig();
   if (!config2.apiKey) {
@@ -25289,16 +25327,32 @@ function getApiUrl() {
   const config2 = loadConfig();
   return config2.apiUrl;
 }
-function setActiveWorkspace(workspaceId) {
-  saveConfig({ activeWorkspaceId: workspaceId });
+function setActiveWorkspace(workspaceId, options) {
+  if (options?.local) {
+    saveLocalConfig({ workspaceId }, options.cwd);
+  } else {
+    saveConfig({ activeWorkspaceId: workspaceId });
+  }
 }
-function setActiveProject(projectId) {
-  saveConfig({ activeProjectId: projectId });
+function setActiveProject(projectId, options) {
+  if (options?.local) {
+    saveLocalConfig({ projectId }, options.cwd);
+  } else {
+    saveConfig({ activeProjectId: projectId });
+  }
 }
-function getActiveWorkspaceId() {
+function getActiveWorkspaceId(cwd) {
+  const localConfig = loadLocalConfig(cwd);
+  if (localConfig?.workspaceId) {
+    return localConfig.workspaceId;
+  }
   return loadConfig().activeWorkspaceId;
 }
-function getActiveProjectId() {
+function getActiveProjectId(cwd) {
+  const localConfig = loadLocalConfig(cwd);
+  if (localConfig?.projectId) {
+    return localConfig.projectId;
+  }
   return loadConfig().activeProjectId;
 }
 function isConfigured() {
@@ -26633,19 +26687,36 @@ You can now use the MCP server with Claude Code.`);
   }
 });
 program.command("status").description("Show configuration status").action(() => {
-  const config2 = loadConfig();
+  const globalConfig2 = loadConfig();
+  const localConfig = loadLocalConfig();
+  const hasLocal = hasLocalConfig();
   if (isConfigured()) {
     console.log("Status: Configured");
-    console.log(`API Key: ${config2.apiKey?.slice(0, 8)}...`);
-    console.log(`API URL: ${config2.apiUrl}`);
-    if (config2.activeWorkspaceId) {
-      console.log(`Active Workspace: ${config2.activeWorkspaceId}`);
-    }
-    if (config2.activeProjectId) {
-      console.log(`Active Project: ${config2.activeProjectId}`);
+    console.log(`API Key: ${globalConfig2.apiKey?.slice(0, 8)}...`);
+    console.log(`API URL: ${globalConfig2.apiUrl}`);
+    console.log(`
+Global Context:`);
+    console.log(`  Workspace: ${globalConfig2.activeWorkspaceId || "(not set)"}`);
+    console.log(`  Project: ${globalConfig2.activeProjectId || "(not set)"}`);
+    if (hasLocal) {
+      console.log(`
+Local Context (${getLocalConfigPath()}):`);
+      console.log(`  Workspace: ${localConfig?.workspaceId || "(not set)"}`);
+      console.log(`  Project: ${localConfig?.projectId || "(not set)"}`);
     }
+    const effectiveWorkspace = getActiveWorkspaceId();
+    const effectiveProject = getActiveProjectId();
+    console.log(`
+Active (effective):`);
+    const wsSource = localConfig?.workspaceId ? "local" : globalConfig2.activeWorkspaceId ? "global" : "";
+    const projSource = localConfig?.projectId ? "local" : globalConfig2.activeProjectId ? "global" : "";
+    console.log(`  Workspace: ${effectiveWorkspace || "(not set)"}${wsSource ? `  ← ${wsSource}` : ""}`);
+    console.log(`  Project: ${effectiveProject || "(not set)"}${projSource ? `  ← ${projSource}` : ""}`);
     console.log(`
-Config file: ${getConfigPath()}`);
+Global config: ${getConfigPath()}`);
+    if (hasLocal) {
+      console.log(`Local config: ${getLocalConfigPath()}`);
+    }
   } else {
     console.log("Status: Not configured");
     console.log(`
@@ -26661,15 +26732,27 @@ program.command("reset").description("Remove stored configuration").action(() =>
   });
   console.log("Configuration reset successfully");
 });
-program.command("set-workspace <workspaceId>").description("Set the active workspace context").action((workspaceId) => {
-  setActiveWorkspace(workspaceId);
-  console.log(`Active workspace set to: ${workspaceId}`);
+program.command("set-workspace <workspaceId>").description("Set the active workspace context").option("-l, --local", "Save to local project config (.harmony-mcp.json) instead of global").action((workspaceId, options) => {
+  const isLocal = options.local;
+  setActiveWorkspace(workspaceId, { local: isLocal });
+  if (isLocal) {
+    console.log(`Local workspace set to: ${workspaceId}`);
+    console.log(`Config file: ${getLocalConfigPath()}`);
+  } else {
+    console.log(`Global workspace set to: ${workspaceId}`);
+  }
 });
-program.command("set-project <projectId>").description("Set the active project context").action((projectId) => {
-  setActiveProject(projectId);
-  console.log(`Active project set to: ${projectId}`);
+program.command("set-project <projectId>").description("Set the active project context").option("-l, --local", "Save to local project config (.harmony-mcp.json) instead of global").action((projectId, options) => {
+  const isLocal = options.local;
+  setActiveProject(projectId, { local: isLocal });
+  if (isLocal) {
+    console.log(`Local project set to: ${projectId}`);
+    console.log(`Config file: ${getLocalConfigPath()}`);
+  } else {
+    console.log(`Global project set to: ${projectId}`);
+  }
 });
-program.command("init").description("Initialize Harmony MCP for AI coding agents (Claude Code, Codex, Cursor, Windsurf)").option("-a, --agent <agents...>", `Agent(s) to configure: ${SUPPORTED_AGENTS.join(", ")}`).option("--all", "Configure all supported agents").option("--detect", "Auto-detect installed agents and configure them").option("-f, --force", "Overwrite existing configuration files").option("-d, --directory <path>", "Project directory (default: current directory)").action(async (options) => {
+program.command("init").description("Initialize Harmony MCP for AI coding agents (Claude Code, Codex, Cursor, Windsurf)").option("-a, --agent <agents...>", `Agent(s) to configure: ${SUPPORTED_AGENTS.join(", ")}`).option("--all", "Configure all supported agents").option("--detect", "Auto-detect installed agents and configure them").option("-f, --force", "Overwrite existing configuration files").option("-d, --directory <path>", "Project directory (default: current directory)").option("-w, --workspace <id>", "Set local workspace context for this project").option("-p, --project <id>", "Set local project context for this project").action(async (options) => {
   console.log(`Harmony MCP Initialization
 `);
   let agents = [];
@@ -26767,6 +26850,19 @@ ${result.agent.toUpperCase()}:`);
       console.log("  No changes made");
     }
   }
+  if (options.workspace || options.project) {
+    console.log(`
+LOCAL CONTEXT:`);
+    if (options.workspace) {
+      saveLocalConfig({ workspaceId: options.workspace }, cwd);
+      console.log(`  ✓ Workspace: ${options.workspace}`);
+    }
+    if (options.project) {
+      saveLocalConfig({ projectId: options.project }, cwd);
+      console.log(`  ✓ Project: ${options.project}`);
+    }
+    console.log(`  Config file: ${getLocalConfigPath(cwd)}`);
+  }
   console.log(`
 ` + "─".repeat(60));
   if (!isConfigured()) {

package/dist/index.js

@@ -22996,12 +22996,16 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 var DEFAULT_API_URL = "https://gethmy.com/api";
+var LOCAL_CONFIG_FILENAME = ".harmony-mcp.json";
 function getConfigDir() {
   return join(homedir(), ".harmony-mcp");
 }
 function getConfigPath() {
   return join(getConfigDir(), "config.json");
 }
+function getLocalConfigPath(cwd) {
+  return join(cwd || process.cwd(), LOCAL_CONFIG_FILENAME);
+}
 function loadConfig() {
   const configPath = getConfigPath();
   if (!existsSync(configPath)) {
@@ -23040,6 +23044,39 @@ function saveConfig(config2) {
   const newConfig = { ...existingConfig, ...config2 };
   writeFileSync(configPath, JSON.stringify(newConfig, null, 2), { mode: 384 });
 }
+function loadLocalConfig(cwd) {
+  const localConfigPath = getLocalConfigPath(cwd);
+  if (!existsSync(localConfigPath)) {
+    return null;
+  }
+  try {
+    const data = readFileSync(localConfigPath, "utf-8");
+    const config2 = JSON.parse(data);
+    return {
+      workspaceId: config2.workspaceId || null,
+      projectId: config2.projectId || null
+    };
+  } catch {
+    return null;
+  }
+}
+function saveLocalConfig(config2, cwd) {
+  const localConfigPath = getLocalConfigPath(cwd);
+  const existingConfig = loadLocalConfig(cwd) || {
+    workspaceId: null,
+    projectId: null
+  };
+  const newConfig = { ...existingConfig, ...config2 };
+  const cleanConfig = {};
+  if (newConfig.workspaceId)
+    cleanConfig.workspaceId = newConfig.workspaceId;
+  if (newConfig.projectId)
+    cleanConfig.projectId = newConfig.projectId;
+  writeFileSync(localConfigPath, JSON.stringify(cleanConfig, null, 2));
+}
+function hasLocalConfig(cwd) {
+  return existsSync(getLocalConfigPath(cwd));
+}
 function getApiKey() {
   const config2 = loadConfig();
   if (!config2.apiKey) {
@@ -23052,16 +23089,32 @@ function getApiUrl() {
   const config2 = loadConfig();
   return config2.apiUrl;
 }
-function setActiveWorkspace(workspaceId) {
-  saveConfig({ activeWorkspaceId: workspaceId });
+function setActiveWorkspace(workspaceId, options) {
+  if (options?.local) {
+    saveLocalConfig({ workspaceId }, options.cwd);
+  } else {
+    saveConfig({ activeWorkspaceId: workspaceId });
+  }
 }
-function setActiveProject(projectId) {
-  saveConfig({ activeProjectId: projectId });
+function setActiveProject(projectId, options) {
+  if (options?.local) {
+    saveLocalConfig({ projectId }, options.cwd);
+  } else {
+    saveConfig({ activeProjectId: projectId });
+  }
 }
-function getActiveWorkspaceId() {
+function getActiveWorkspaceId(cwd) {
+  const localConfig = loadLocalConfig(cwd);
+  if (localConfig?.workspaceId) {
+    return localConfig.workspaceId;
+  }
   return loadConfig().activeWorkspaceId;
 }
-function getActiveProjectId() {
+function getActiveProjectId(cwd) {
+  const localConfig = loadLocalConfig(cwd);
+  if (localConfig?.projectId) {
+    return localConfig.projectId;
+  }
   return loadConfig().activeProjectId;
 }
 function isConfigured() {

package/dist/init.js

@@ -33,77 +33,78 @@ import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 var HARMONY_WORKFLOW_PROMPT = `# Harmony Card Workflow
 
-You are starting work on a Harmony card. Follow this workflow:
+Start work on a Harmony card. Card reference: $ARGUMENTS
 
-## Step 1: Find the Card
+## 1. Find & Fetch Card
 
-The user provided: $ARGUMENTS
+Parse the reference and fetch the card:
+- \`#42\` or \`42\` → \`harmony_get_card_by_short_id\` with \`shortId: 42\`
+- UUID → \`harmony_get_card\` with \`cardId\`
+- Name/text → \`harmony_search_cards\` with \`query\`
 
-Parse the card reference:
-- If it starts with \`#\` followed by numbers (e.g., \`#42\`), use \`harmony_get_card_by_short_id\` with the number
-- If it looks like a UUID, use \`harmony_get_card\` directly
-- Otherwise, use \`harmony_search_cards\` to find by name
+## 2. Get Board State
 
-## Step 2: Move to In Progress
+Call \`harmony_get_board\` to get columns and labels. From the response:
+- Find the "In Progress" (or "Progress") column ID
+- Find the "agent" label ID
 
-Once you have the card:
-1. Get the board using \`harmony_get_board\` to find the "In Progress" column ID
-2. Use \`harmony_move_card\` to move the card to "In Progress"
+## 3. Setup Card for Work
 
-## Step 3: Add Agent Label
+Execute these in sequence:
+1. \`harmony_move_card\` → Move to "In Progress" column
+2. \`harmony_add_label_to_card\` → Add "agent" label
+3. \`harmony_start_agent_session\`:
+   - \`cardId\`: Card UUID
+   - \`agentIdentifier\`: Your agent identifier
+   - \`agentName\`: Your agent name
+   - \`currentTask\`: "Analyzing card requirements"
 
-1. From the board response, find the label named "agent"
-2. Use \`harmony_add_label_to_card\` to add it to the card
+## 4. Generate Work Prompt
 
-## Step 4: Start Agent Session
+Call \`harmony_generate_prompt\` with:
+- \`cardId\` or \`shortId\` (+ \`projectId\` if using shortId)
+- \`variant\`: Select based on task:
+  - \`"execute"\` (default) → Clear tasks, bug fixes, well-defined work
+  - \`"analysis"\` → Complex features, unclear requirements
+  - \`"draft"\` → Medium complexity, want feedback first
 
-After adding the agent label, start tracking your work session:
-1. Use \`harmony_start_agent_session\` with:
-   - \`cardId\`: The card ID
-   - \`agentIdentifier\`: Your agent identifier
-   - \`agentName\`: Your agent name
-   - \`currentTask\`: A brief description of what you're about to do
-
-This enables the timer badge on the card to show your progress in real-time.
-
-## Step 5: Display Card Details
-
-Show the user:
-- Card title and short ID
-- Description (if any)
-- Priority
-- Current labels
-- Due date (if set)
-
-## Step 6: Implement the Solution
-
-1. Use \`harmony_generate_prompt\` with the card ID to get role-based guidance
-2. Follow the generated prompt to implement the solution
-3. Test the changes
-
-**During implementation, update your progress periodically:**
-- Use \`harmony_update_agent_progress\` to report:
-  - \`progressPercent\`: Estimated completion (0-100)
-  - \`currentTask\`: What you're currently doing
-  - \`blockers\`: Any issues blocking progress (set \`status: "blocked"\` if blocked)
-
-## Step 7: Complete Work
-
-When implementation is complete:
-1. Use \`harmony_end_agent_session\` with:
-   - \`cardId\`: The card ID
-   - \`status\`: "completed"
-   - \`progressPercent\`: 100
-2. Use \`harmony_move_card\` to move the card to the "Review" column
-3. Summarize what was accomplished
-
-## Important Notes
-- Always read the card description carefully before starting
-- If the task is unclear, ask for clarification
-- Make commits as appropriate during implementation
-- The "agent" label indicates AI is working on the card
-- Update progress at meaningful milestones, not constantly
-- If you need to pause work, call \`harmony_end_agent_session\` with \`status: "paused"\`
+The generated prompt provides role framing, focus areas, subtasks, linked cards, and suggested outputs.
+
+## 5. Display Card Summary
+
+Show the user: Card title, short ID, role, priority, labels, due date, description, and subtasks.
+
+## 6. Implement Solution
+
+Work on the card following the generated prompt's guidance. Update progress at milestones:
+- \`harmony_update_agent_progress\` with \`progressPercent\` (0-100), \`currentTask\`, \`status\`, \`blockers\`
+
+**Progress checkpoints:** 20% (exploration), 50% (implementation), 80% (testing), 100% (done)
+
+## 7. Complete Work
+
+When finished:
+1. \`harmony_end_agent_session\` with \`status: "completed"\`, \`progressPercent: 100\`
+2. \`harmony_move_card\` to "Review" column
+3. Summarize accomplishments
+
+If pausing: \`harmony_end_agent_session\` with \`status: "paused"\`
+
+## Key Tools Reference
+
+**Cards:** \`harmony_get_card\`, \`harmony_get_card_by_short_id\`, \`harmony_search_cards\`, \`harmony_create_card\`, \`harmony_update_card\`, \`harmony_move_card\`, \`harmony_delete_card\`, \`harmony_assign_card\`
+
+**Subtasks:** \`harmony_create_subtask\`, \`harmony_toggle_subtask\`, \`harmony_delete_subtask\`
+
+**Labels:** \`harmony_add_label_to_card\`, \`harmony_remove_label_from_card\`, \`harmony_create_label\`
+
+**Links:** \`harmony_add_link_to_card\`, \`harmony_remove_link_from_card\`, \`harmony_get_card_links\`
+
+**Board:** \`harmony_get_board\`, \`harmony_list_projects\`, \`harmony_get_context\`, \`harmony_set_project_context\`
+
+**Sessions:** \`harmony_start_agent_session\`, \`harmony_update_agent_progress\`, \`harmony_end_agent_session\`, \`harmony_get_agent_session\`
+
+**AI:** \`harmony_generate_prompt\`, \`harmony_process_command\`
 `;
 function ensureDir(dirPath) {
   if (!existsSync(dirPath)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harmony-mcp",
-  "version": "1.2.4",
+  "version": "1.3.1",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "type": "module",
   "main": "dist/index.js",