harmony-mcp 1.2.3 → 1.3.0

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

package/dist/cli.js

@@ -13792,79 +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
-
-Based on the card's title and description:
-1. Understand what needs to be done
-2. Explore the codebase as needed
-3. Implement the required changes
-4. 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)) {
@@ -13960,7 +13959,7 @@ When given a card reference (e.g., #42 or a card name), follow this workflow:
 3. Add the "agent" label using \`harmony_add_label_to_card\`
 4. Start a session with \`harmony_start_agent_session\` (agentIdentifier: "codex", agentName: "OpenAI Codex")
 5. Show the card details to the user
-6. Implement the solution based on the card description
+6. Use \`harmony_generate_prompt\` to get guidance, then implement the solution
 7. Update progress periodically with \`harmony_update_agent_progress\`
 8. When done, call \`harmony_end_agent_session\` and move to "Review"
 
@@ -13971,6 +13970,7 @@ When given a card reference (e.g., #42 or a card name), follow this workflow:
 - \`harmony_add_label_to_card\`, \`harmony_remove_label_from_card\` - Manage labels
 - \`harmony_start_agent_session\`, \`harmony_update_agent_progress\`, \`harmony_end_agent_session\` - Track work
 - \`harmony_get_board\` - Get board state
+- \`harmony_generate_prompt\` - Get role-based guidance and focus areas for the card
 `;
   const agentsPath = join(cwd, "AGENTS.md");
   const { created: agentsCreated, skipped: agentsSkipped } = writeFileIfNotExists(agentsPath, agentsContent, force);

package/dist/init.js

@@ -33,79 +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
-
-Based on the card's title and description:
-1. Understand what needs to be done
-2. Explore the codebase as needed
-3. Implement the required changes
-4. 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)) {
@@ -201,7 +200,7 @@ When given a card reference (e.g., #42 or a card name), follow this workflow:
 3. Add the "agent" label using \`harmony_add_label_to_card\`
 4. Start a session with \`harmony_start_agent_session\` (agentIdentifier: "codex", agentName: "OpenAI Codex")
 5. Show the card details to the user
-6. Implement the solution based on the card description
+6. Use \`harmony_generate_prompt\` to get guidance, then implement the solution
 7. Update progress periodically with \`harmony_update_agent_progress\`
 8. When done, call \`harmony_end_agent_session\` and move to "Review"
 
@@ -212,6 +211,7 @@ When given a card reference (e.g., #42 or a card name), follow this workflow:
 - \`harmony_add_label_to_card\`, \`harmony_remove_label_from_card\` - Manage labels
 - \`harmony_start_agent_session\`, \`harmony_update_agent_progress\`, \`harmony_end_agent_session\` - Track work
 - \`harmony_get_board\` - Get board state
+- \`harmony_generate_prompt\` - Get role-based guidance and focus areas for the card
 `;
   const agentsPath = join(cwd, "AGENTS.md");
   const { created: agentsCreated, skipped: agentsSkipped } = writeFileIfNotExists(agentsPath, agentsContent, force);

package/package.json

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