@gethmy/mcp 3.7.0 → 3.9.0

package/src/skills.ts

@@ -11,86 +11,12 @@ import { getClient } from "./api-client.js";
 import { areSkillsInstalled, isConfigured } from "./config.js";
 import { loadHmyConfig } from "./hmy-config.js";
 
-/**
- * Legacy workflow prompt used by Codex / Cursor agents. Kept inline because
- * those agents install via AGENTS.md and not via /v1/skills. Claude Code
- * agents use the DB-backed skill_resource registry (see Phase 0 of card #162).
- */
-export const HARMONY_WORKFLOW_PROMPT = `# Harmony Card Workflow
-
-Start work on a Harmony card. Card reference: $ARGUMENTS
-
-## 1. Find & Fetch Card
-
-Parse the reference and fetch the card:
-- \`#42\` or \`42\` → \`harmony_get_card\` with \`shortId: 42\`
-- UUID → \`harmony_get_card\` with \`cardId\`
-- Name/text → \`harmony_search_cards\` with \`query\`
-
-## 2. Get Board State
-
-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
-
-## 3. Setup Card for Work
-
-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"
-
-## 4. Generate Work Prompt
-
-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
-
-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\` (by \`cardId\`, \`shortId\`, or \`shortIds\`), \`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\`
-`;
+// The workflow prompt for Codex / Cursor / Windsurf — which install via their
+// own rule files rather than /v1/skills — used to live here. It moved to
+// `tui/agent-instructions.ts` (#1124) so a test can read it alongside the
+// AGENTS.md section and assert every tool it names is actually advertised.
+// Import it from there; this module is not in the package `exports` map, so a
+// re-export would have had no reachable consumer.
 
 /**
  * Shape of a /v1/skills/{name} response. Used by buildSkillFile + tests.

package/src/tui/agent-instructions.ts

@@ -0,0 +1,335 @@
+/**
+ * The instruction text `hmy setup` installs into a project.
+ *
+ * Two strings, one job: tell an agent how to work a Harmony card correctly.
+ * They live here rather than inline in `setup.ts` so a test can read them —
+ * `setup-agent-files.test.ts` asserts every `harmony_*` name they mention is
+ * advertised by the server's `TOOLS` object. Nothing checked that before
+ * #1124, which is how `harmony_get_card_by_short_id` stayed in the installed
+ * `AGENTS.md` for four minor versions after 2.14.0 removed it.
+ *
+ * Both strings are governed by one rule: say only what the tool schemas do not
+ * already say. The schemas are in the agent's own tool listing, with live
+ * descriptions; restating them here creates a second source of truth that
+ * drifts, and that drift is this file's entire history.
+ */
+
+/**
+ * The plan rule, in one wording for every runtime.
+ *
+ * A plan that prescribes the code is transcribed faithfully, defects included —
+ * so the rule has to reach the project, not only this repository. It ships three
+ * ways: this constant (Codex's `AGENTS.md` section and the Cursor / Windsurf
+ * rule files), and the `hmy-plan` skill body for Claude Code. It lives in one
+ * constant because a rule that is worded differently in three places is three
+ * rules, and only the differences get read.
+ *
+ * No heading of its own — each caller supplies the level its host file needs.
+ */
+export const HARMONY_PLAN_RULE = `**A plan says what must be true and why. It does not contain the code.** In it: the architecture
+and technology decisions with their reasons, the data model and the API contracts, a short
+signature or schema sketch wherever an interpretation gap would otherwise remain, and success
+criteria a test can check. Not in it: function bodies, control flow, error handling, test code.
+Detail follows risk — a throwaway script gets a rough plan, while auth, money, migrations and
+anything security-relevant get their contracts and edge cases written out.
+
+Code in a plan carries the authority of a plan and the quality of a draft that no compiler, test
+or review has read, and an implementer transcribes it faithfully, defects included. So when the
+plan and the code disagree, the code is the evidence: check it, record the decision as a comment,
+and correct the plan as well as the code.`;
+
+/**
+ * The Harmony section of a project's `AGENTS.md`. Written between the
+ * `<!-- harmony:start -->` / `<!-- harmony:end -->` markers by
+ * `mergeMarkdownSection`, so the rest of the file stays the project's.
+ */
+export const HARMONY_AGENTS_SECTION = `## Harmony
+
+This project uses Harmony for task management. The \`harmony_*\` MCP tools are in your tool
+listing with live schemas — read them there. This section covers only what the schemas do not say.
+
+### Identify as yourself
+
+Every session call takes \`agentIdentifier\` + \`agentName\`. Use your OWN, never a value copied
+from this file. The board shows agents as teammates, so a session attributed to the wrong runtime
+misattributes the work in front of the whole team.
+
+Known values: \`claude-code\` / "Claude Code" · \`codex\` / "OpenAI Codex" · \`cursor\` / "Cursor" ·
+\`claude-desktop\` / "Claude Desktop". If you are none of these, use your own name.
+
+### Starting work — one call, not three
+
+\`harmony_start_agent_session\` moves the card and adds the labels itself. Do not call
+\`harmony_move_card\` or \`harmony_add_label_to_card\` first, and do not fetch the board for a
+column id or a label id — both arguments match by name.
+
+\`\`\`
+harmony_start_agent_session({
+  cardId,
+  agentIdentifier, agentName,   // your own
+  currentTask: "Reading the auth middleware to find the affected routes",
+  moveToColumn: "In Progress",
+  addLabels: ["agent"],
+  steerable: true,              // only if you will poll for steering — see below
+})
+\`\`\`
+
+**Then read the reply, because the setup half fails quietly.** \`movedTo\` names the column it
+actually moved to and \`labelsAdded\` the labels it actually added; a miss leaves them null or
+empty and raises no error. The column match is a case-insensitive **substring**, so a board with
+"Ready for Review" ahead of "Review" can take the wrong one. If \`movedTo\` is null or not the
+column you meant, call \`harmony_move_card\` — it matches exactly first and fails loudly, listing
+the columns.
+
+Keep the returned \`session.id\`; the steering poll needs it. Then call
+\`harmony_generate_prompt\` for role framing and focus areas — \`variant\` is \`execute\`
+(default), \`analysis\`, or \`draft\`.
+
+### Progress — \`actions\` is what survives as evidence
+
+On the card itself, \`progressPercent\` and \`currentTask\` each overwrite one field, so the live
+status shows only your latest checkpoint. The timeline keeps more: a checkpoint that carries both
+a \`progressPercent\` and a \`currentTask\` different from the last one leaves a row saying what you
+were **about to do**, and **each entry in \`actions\` leaves a row saying what you actually did**.
+Report four checkpoints with no \`actions\` and a two-hour run reads as four intentions and no
+evidence.
+
+Name what you DID since the last checkpoint: the file you edited and why, the gate you ran and
+what it said, the approach you ruled out and on what evidence.
+
+\`\`\`
+harmony_update_agent_progress({
+  cardId, agentIdentifier, agentName,
+  progressPercent: 50,
+  currentTask: "Extracting refreshIfExpired() in auth.ts",
+  actions: [
+    { description: "Read auth.ts and middleware/session.ts — the refresh path is duplicated in both, which is the actual bug" },
+    { description: "Ruled out patching verifyToken(): three routes depend on its current behaviour" },
+    { description: "Ran bun run lint — green, exit 0" },
+  ],
+})
+\`\`\`
+
+Three to six entries per checkpoint, one sentence each; past 512 characters an entry is silently truncated. Facts, not
+intentions — one vague entry is worse than none. Checkpoints: 20% explored · 50% implementing ·
+80% verifying · 100% done. \`currentTask\` is what you are doing now — never leave it generic.
+
+### Steering and Stop
+
+If you passed \`steerable: true\`, poll right after every progress update:
+
+\`\`\`
+harmony_get_pending_messages({ cardId, sessionId, sinceSeq })   // sinceSeq starts at 0
+\`\`\`
+
+Messages come back oldest first. Fold them into the next step and advance \`sinceSeq\` to the
+largest \`seq\` returned, so each is handled exactly once.
+
+Two flags come back and mean opposite things:
+
+| flag | meaning | what to do |
+|---|---|---|
+| \`stopped: true\` | a human pressed Stop | **Terminal.** Make no further edits, commits, pushes, card moves, comments or progress writes. Report what is finished and where any uncommitted work lives. |
+| \`sessionStale: true\` | your session id is no longer live — usually the inactivity sweep | **Nobody stopped you.** Carry on — with a new id. |
+
+\`harmony_update_agent_progress\` reports the same two flags, and the recovery from a stale session
+differs by which call told you:
+
+- From the **progress** call, a replacement session has already been opened for you and inherited
+  the steering channel. Take the new \`session.id\` from that reply and keep going.
+- From the **poll**, nothing was opened. Call \`harmony_start_agent_session\` yourself and poll
+  with the id it returns.
+
+If the two flags ever disagree, the stop wins.
+
+### Finishing
+
+\`\`\`
+harmony_end_agent_session({ cardId, status: "completed", progressPercent: 100, moveToColumn: "Review" })
+\`\`\`
+
+One call: it moves the card, and on \`status: "completed"\` it also removes the \`agent\` label. Use
+\`status: "paused"\` when you stop mid-flight — that leaves the label on, which is what you want.
+
+Attach a PR **after** the session end has moved the card, both ways: \`harmony_add_external_link\`
+(durable — it survives a later description edit) and a \`PR: <url>\` line in the description.
+
+### Writing a plan
+
+${HARMONY_PLAN_RULE}
+
+### Traps
+
+- **A \`shortId\` is project-scoped, and the two ways it can miss are opposites.** With **no**
+  active project the number is resolved across every project you can reach, so it may come back
+  \`needsDisambiguation\` with \`candidates\` — ask which one is meant. With an active project the
+  number resolves only inside it, and a card that lives elsewhere fails with an error naming the
+  projects it is really in — switch with \`harmony_set_project_context\` or pass \`projectId\`.
+  Either way, check \`resolvedProject\` matches the card you meant before starting work.
+- **Fetch many cards in one call:** \`harmony_get_card({ shortIds: [400, 401, 402] })\`, max 100.
+- **Moving a card to a terminal column ends your session** — a column that marks cards done, or
+  one named \`done\`, \`completed\` or \`review\`. The response says \`sessionEnded\`.
+- **Read \`harmony_get_comments\` before you act.** Steering messages do not include comments, and
+  a later comment outranks an earlier one it contradicts.
+- **Report findings and decisions as comments, not description edits.** \`harmony_add_comment\`
+  takes a \`commentType\`: \`question\` and \`blocker\` signal that you need a human; \`decision\`,
+  \`finding\`, \`summary\`, \`progress\` and \`message\` are the rest.`;
+
+/**
+ * The per-runtime workflow prompt installed as the Codex prompt file and the
+ * Cursor / Windsurf rule files. Rendered through `renderWorkflowPrompt`.
+ */
+export const HARMONY_WORKFLOW_PROMPT = `# Harmony Card Workflow
+
+Work a Harmony card. Card reference: $ARGUMENTS
+
+The \`harmony_*\` MCP tools are in your tool listing with live schemas — read them there. This
+prompt covers only what the schemas do not say.
+
+## 1. Fetch the card
+
+- \`#42\` or \`42\` → \`harmony_get_card({ shortId: 42 })\`
+- UUID → \`harmony_get_card({ cardId })\`
+- A name or phrase → \`harmony_search_cards({ query })\`
+- Several at once → \`harmony_get_card({ shortIds: [40, 41, 42] })\`, max 100
+
+A \`shortId\` is project-scoped, and the two ways it can miss are opposites. With **no** active
+project the number is resolved across every project you can reach, so it may come back
+\`needsDisambiguation\` with \`candidates\` — ask which one is meant. With an active project the
+number resolves only inside it, and a card that lives elsewhere fails with an error naming the
+projects it is really in; switch with \`harmony_set_project_context\` or pass \`projectId\`.
+Either way, check \`resolvedProject\` before you start.
+
+Read \`harmony_get_comments\` too: a later comment outranks an earlier one it contradicts.
+
+## 2. Start the session — one call, not three
+
+\`harmony_start_agent_session\` moves the card and adds the labels itself. Do not call
+\`harmony_move_card\` or \`harmony_add_label_to_card\` first, and do not fetch the board for a
+column id or a label id — both arguments match by name.
+
+\`\`\`
+harmony_start_agent_session({
+  cardId,
+  agentIdentifier: "$AGENT_IDENTIFIER",
+  agentName: "$AGENT_NAME",
+  currentTask: "Reading the auth middleware to find the affected routes",
+  moveToColumn: "In Progress",
+  addLabels: ["agent"],
+  steerable: true,
+})
+\`\`\`
+
+\`currentTask\` says what you are about to do, specifically. Never "Analyzing card requirements".
+Keep the returned \`session.id\` — step 4 needs it.
+
+**Read the reply, because the setup half fails quietly.** \`movedTo\` names the column it actually
+moved to and \`labelsAdded\` the labels it actually added; a miss leaves them null or empty and
+raises no error. The column match is a case-insensitive **substring**, so a board with "Ready for
+Review" ahead of "Review" can take the wrong one. If \`movedTo\` is null or not the column you
+meant, call \`harmony_move_card\` — it matches exactly first and fails loudly, listing the columns.
+
+## 3. Get the work prompt
+
+\`harmony_generate_prompt\` with \`cardId\` (or \`shortId\` plus \`projectId\`) and a \`variant\`:
+\`execute\` (default) for well-defined work, \`analysis\` for unclear requirements, \`draft\` when
+you want feedback on a design first. It returns role framing, focus areas, subtasks and links.
+
+Then show the user the card: title, short id, priority, labels, due date, description, subtasks.
+
+## 4. Implement, and check in at every milestone
+
+Checkpoints: 20% explored · 50% implementing · 80% verifying · 100% done.
+
+On the card itself, \`progressPercent\` and \`currentTask\` each overwrite one field, so the live
+status shows only your latest checkpoint. The timeline keeps more: a checkpoint that carries both
+a \`progressPercent\` and a \`currentTask\` different from the last one leaves a row saying what you
+were **about to do**, and **each entry in \`actions\` leaves a row saying what you actually did** —
+that is the evidence the team can still read afterwards.
+
+\`\`\`
+harmony_update_agent_progress({
+  cardId, agentIdentifier: "$AGENT_IDENTIFIER", agentName: "$AGENT_NAME",
+  progressPercent: 50,
+  currentTask: "Extracting refreshIfExpired() in auth.ts",
+  actions: [
+    { description: "Read auth.ts and middleware/session.ts — the refresh path is duplicated in both, which is the actual bug" },
+    { description: "Ruled out patching verifyToken(): three routes depend on its current behaviour" },
+    { description: "Ran bun run lint — green, exit 0" },
+  ],
+  status: "working",   // or blocked / waiting / paused
+  blockers: [],
+})
+\`\`\`
+
+Three to six entries per checkpoint, one sentence each; past 512 characters an entry is silently truncated. Say what you did,
+not what you intend to do.
+
+Right after each update, poll for steering:
+
+\`\`\`
+harmony_get_pending_messages({ cardId, sessionId, sinceSeq })   // sinceSeq starts at 0
+\`\`\`
+
+Fold any messages into the next step and advance \`sinceSeq\` to the largest \`seq\` returned. Two
+flags come back and mean opposite things:
+
+- \`stopped: true\` — a human pressed Stop. **Terminal.** Make no further edits, commits, pushes,
+  card moves, comments or progress writes; report what is finished and where any uncommitted work
+  lives.
+- \`sessionStale: true\` — your session id is no longer live, usually the inactivity sweep. **Nobody stopped you.**
+  Carry on, with a new id: the **poll** opens nothing, so call \`harmony_start_agent_session\`
+  yourself; the **progress** call has already opened a replacement that inherited the steering
+  channel, so just take the new \`session.id\` from its reply.
+
+If the two flags ever disagree, the stop wins.
+
+Report findings and decisions with \`harmony_add_comment\` (\`commentType\`: \`question\` and
+\`blocker\` signal that you need a human; \`decision\`, \`finding\`, \`summary\`, \`progress\`,
+\`message\`), not by editing the card description.
+
+## 5. Finish
+
+\`\`\`
+harmony_end_agent_session({ cardId, status: "completed", progressPercent: 100, moveToColumn: "Review" })
+\`\`\`
+
+One call: it moves the card, and on \`status: "completed"\` it also removes the \`agent\` label. Use
+\`status: "paused"\` when you stop mid-flight — that leaves the label on, which is what you want.
+
+Opened a PR? Attach it **after** the session end has moved the card, both ways:
+\`harmony_add_external_link\` (durable — it survives a later description edit) and a
+\`PR: <url>\` line in the description.
+
+Then summarise what changed.
+
+## Writing a plan
+
+${HARMONY_PLAN_RULE}
+
+## Worth knowing
+
+- Moving a card to a terminal column ends your session — a column that marks cards done, or one
+  named \`done\`, \`completed\` or \`review\`. The response says \`sessionEnded\`.
+- \`harmony_add_label_to_card\` and \`harmony_start_agent_session\`'s \`addLabels\` both CREATE a
+  label that does not exist yet. Check the spelling.
+- \`harmony_add_comment\` works on any card you can see, including one you hold no session on.`;
+
+/**
+ * Render the workflow prompt for one runtime.
+ *
+ * The placeholders are explicit tokens rather than prose. The previous version
+ * chained `.replace("Your agent identifier", …)` over the prompt text, which
+ * substitutes only the FIRST occurrence and no-ops silently the moment that
+ * exact sentence is reworded — so a prompt could ship telling Cursor to call
+ * itself "Your agent name" with nothing failing (#1124).
+ */
+export function renderWorkflowPrompt(opts: {
+  cardArgument: string;
+  agentIdentifier: string;
+  agentName: string;
+}): string {
+  return HARMONY_WORKFLOW_PROMPT.replaceAll("$ARGUMENTS", opts.cardArgument)
+    .replaceAll("$AGENT_IDENTIFIER", opts.agentIdentifier)
+    .replaceAll("$AGENT_NAME", opts.agentName);
+}