@gethmy/mcp 3.8.0 → 3.9.0

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);
+}

package/src/tui/setup.ts

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import {
   existsSync,
@@ -23,7 +24,11 @@ import {
 } from "../config.js";
 import { loginWithBrowser, type OAuthTokens } from "../oauth-login.js";
 import { onboardNewUser } from "../onboard.js";
-import { buildSkillFile, HARMONY_WORKFLOW_PROMPT } from "../skills.js";
+import { buildSkillFile } from "../skills.js";
+import {
+  HARMONY_AGENTS_SECTION,
+  renderWorkflowPrompt,
+} from "./agent-instructions.js";
 import { type AgentId, detectAgents } from "./agents.js";
 import { confirmOrDefault, shouldAssumeYes } from "./confirm.js";
 import { runDocsStep } from "./docs.js";
@@ -61,11 +66,17 @@ export interface SetupOptions {
  * keep, especially under autonomous agent runs. New tools default to prompting
  * until someone classifies them here (safe failure mode). `--allow-all-tools`
  * overrides this with a blanket grant.
+ *
+ * Every name here must exist in the advertised `TOOLS` object in `server.ts`.
+ * `harmony_get_card_by_short_id` sat in this list for four minor versions after
+ * 2.14.0 dropped it, writing a permission rule for a tool that can never be
+ * offered — and the same dead name was being installed into AGENTS.md, where an
+ * agent read it and had to correct us. `setup-agent-files.test.ts` now fails on
+ * a name that is not advertised, in this list and in every generated file (#1124).
  */
-const SAFE_HARMONY_TOOLS = [
+export const SAFE_HARMONY_TOOLS = [
   // Reads
   "harmony_get_card",
-  "harmony_get_card_by_short_id",
   "harmony_search_cards",
   "harmony_get_board",
   "harmony_get_context",
@@ -77,12 +88,19 @@ const SAFE_HARMONY_TOOLS = [
   "harmony_get_comments",
   "harmony_get_plan",
   "harmony_list_plans",
+  "harmony_get_playbook",
+  "harmony_list_playbook",
   "harmony_get_agent_session",
+  // The checkpoint steering poll. Absent until #1124, so every checkpoint of
+  // every run raised a prompt for a read the workflow itself prescribes.
+  "harmony_get_pending_messages",
   "harmony_get_workspace_members",
   "harmony_list_agents",
   "harmony_resolve_links",
+  "harmony_suggest_relations",
   "harmony_recall",
   "harmony_memory_search",
+  "harmony_vault_index",
   "harmony_generate_prompt",
   // Routine writes
   "harmony_create_card",
@@ -91,6 +109,7 @@ const SAFE_HARMONY_TOOLS = [
   "harmony_assign_card",
   "harmony_create_subtask",
   "harmony_toggle_subtask",
+  "harmony_update_subtask",
   "harmony_add_label_to_card",
   "harmony_remove_label_from_card",
   "harmony_create_label",
@@ -98,6 +117,10 @@ const SAFE_HARMONY_TOOLS = [
   "harmony_update_comment",
   "harmony_add_link_to_card",
   "harmony_remove_link_from_card",
+  // The durable carrier for a PR link — the completion path calls it on every
+  // card that changed code, and it mirrors the card-link pair above.
+  "harmony_add_external_link",
+  "harmony_remove_external_link",
   "harmony_start_agent_session",
   "harmony_update_agent_progress",
   "harmony_end_agent_session",
@@ -112,6 +135,9 @@ const SAFE_HARMONY_TOOLS = [
   "harmony_remember",
   "harmony_relate",
   "harmony_update_memory",
+  // A ranking counter on a recalled memory. A write, not a read — it never
+  // deletes, hides or supersedes anything.
+  "harmony_recall_feedback",
   "harmony_process_command",
   "harmony_sync",
 ];
@@ -401,7 +427,8 @@ export async function resolveProjectSlug(
 export interface FileToWrite {
   path: string;
   content: string;
-  type: "text" | "json" | "toml";
+  /** `markdown` merges a Harmony-owned section into a file the project owns. */
+  type: "text" | "json" | "toml" | "markdown";
   tomlSection?: string;
   mode?: number;
 }
@@ -512,64 +539,15 @@ async function getAgentFiles(
     }
 
     case "codex": {
-      // AGENTS.md in project root (always local - project context)
-      const agentsContent = `# Harmony Integration
-
-This project uses Harmony for task management. When working on tasks:
-
-## Agent identity — always identify as yourself
-
-Every \`harmony_start_agent_session\` call passes \`agentIdentifier\` + \`agentName\`. **Use your own
-identity, never a hardcoded one from this file.** AGENTS.md is a cross-runtime convention file, so
-more than one kind of agent will read it; the board shows agents as teammates, and a session
-attributed to the wrong runtime misattributes the work in front of the whole team.
-
-- \`agentIdentifier\` — a stable kebab-case id for the runtime you actually are
-- \`agentName\` — its human-readable name
-
-Known values: \`claude-code\` / "Claude Code", \`codex\` / "OpenAI Codex", \`cursor\` / "Cursor",
-\`claude-desktop\` / "Claude Desktop". If you are a runtime not listed here, use your own name rather
-than borrowing the closest entry.
-
-## Starting Work on a Card
-
-When given a card reference (e.g., #42 or a card name), follow this workflow:
-
-1. Use \`harmony_get_card\` or \`harmony_search_cards\` to find the card
-2. Move the card to "In Progress" using \`harmony_move_card\`
-3. Add the "agent" label using \`harmony_add_label_to_card\`
-4. Start a session with \`harmony_start_agent_session\`, passing **your own** \`agentIdentifier\` +
-   \`agentName\` (see "Agent identity" above)
-5. Show the card details to the user
-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"
-
-## Auto-Detect Card for Implementation Tasks
-
-Before implementing a plan or feature, check if it maps to an existing Harmony card:
-
-1. Use \`harmony_search_cards\` with keywords from the task description
-2. If a match is found, call \`harmony_start_agent_session\` with **your own** \`agentIdentifier\` +
-   \`agentName\` (see "Agent identity" above), plus \`moveToColumn: "In Progress"\`, \`addLabels: ["agent"]\`
-3. Update progress with \`harmony_update_agent_progress\` at milestones
-4. When done, call \`harmony_end_agent_session\` with status: "completed", moveToColumn: "Review"
-
-Skip if: work was already started with a card reference, or no matching card exists.
-
-## Available Harmony Tools
-
-- \`harmony_get_card\`, \`harmony_get_card_by_short_id\`, \`harmony_search_cards\` - Find cards
-- \`harmony_move_card\` - Move cards between columns
-- \`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
-`;
+      // The Harmony section of AGENTS.md, written as type "markdown" so it is
+      // MERGED into whatever the project already has: the docs-step scaffold
+      // written earlier in this same run, or a file the user maintains by hand.
+      // A plain text write destroyed both — setup forces writes on a fresh
+      // install, and this push lands after the scaffold's (#1124).
       files.push({
         path: join(cwd, "AGENTS.md"),
-        content: agentsContent,
-        type: "text",
+        content: HARMONY_AGENTS_SECTION,
+        type: "markdown",
       });
 
       // Codex prompt file
@@ -582,7 +560,7 @@ arguments:
     required: true
 ---
 
-${HARMONY_WORKFLOW_PROMPT.replace("$ARGUMENTS", "{{card}}").replace("Your agent identifier", "codex").replace("Your agent name", "OpenAI Codex")}
+${renderWorkflowPrompt({ cardArgument: "{{card}}", agentIdentifier: "codex", agentName: "OpenAI Codex" })}
 `;
 
       if (installMode === "global") {
@@ -652,7 +630,7 @@ alwaysApply: false
 
 When the user asks you to work on a Harmony card (references like #42, card names, or UUIDs):
 
-${HARMONY_WORKFLOW_PROMPT.replace("$ARGUMENTS", "the card reference").replace("Your agent identifier", "cursor").replace("Your agent name", "Cursor AI")}
+${renderWorkflowPrompt({ cardArgument: "the card reference", agentIdentifier: "cursor", agentName: "Cursor" })}
 `;
 
       if (installMode === "global") {
@@ -708,7 +686,7 @@ description: Activate when user asks to work on a Harmony card (references like
 
 When working on a Harmony card:
 
-${HARMONY_WORKFLOW_PROMPT.replace("$ARGUMENTS", "the card reference").replace("Your agent identifier", "windsurf").replace("Your agent name", "Windsurf AI")}
+${renderWorkflowPrompt({ cardArgument: "the card reference", agentIdentifier: "windsurf", agentName: "Windsurf" })}
 `;
 
       if (installMode === "global") {
@@ -1576,6 +1554,11 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
       `  ${colors.success("\u2713")} ${colors.dim(formatPath(writtenLocalConfigPath, home))} ${colors.dim("(created)")}`,
     );
 
+    // The scan runs AFTER the global mirror below, deliberately: it spawns a
+    // child with inherited stdio for as long as this repo's test suite takes,
+    // and a Ctrl-C there must not cost the operator the global default that
+    // every server started outside this directory reads (#893).
+    //
     // Mirror the choice into the GLOBAL default, explicitly (#893). The local
     // file above already pins this directory; this second write is what gives a
     // server started elsewhere — Claude Desktop, another repo — a context at
@@ -1592,6 +1575,8 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
         { global: true },
       );
     }
+
+    await offerCommandScan(dirname(writtenLocalConfigPath), assumeYes);
   }
 
   // Step 10: Show completion message
@@ -1686,3 +1671,99 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
   }
   console.log("");
 }
+
+/**
+ * The command that proposes a repo's `commands` block by running it.
+ *
+ * `@latest` is this repo's own convention for an `npx` spec (`@gethmy/mcp@latest`
+ * in every documented invocation) and it is load-bearing here: `scan-commands`
+ * arrives in a release later than several already published, and a warm npx
+ * cache of an older `@gethmy/agent` would otherwise hand the operator the
+ * "may predate it" fallback forever with no way to see why.
+ */
+const SCAN_ARGV = ["--yes", "@gethmy/agent@latest", "scan-commands"] as const;
+
+function scanTip(): void {
+  console.log(
+    `  ${colors.dim("Tip: run")} ${colors.highlight(`npx ${SCAN_ARGV.slice(1).join(" ")}`)} ${colors.dim("to have the daemon prove which build, test and dev commands this repo has, and write them into the pin.")}`,
+  );
+}
+
+/**
+ * Offer to scan this repo's commands, and run the scanner when asked (#1116).
+ *
+ * Card 1116's first acceptance criterion is that the scanner RUNS when a
+ * project is set up — this is that moment, and a printed tip is not a run.
+ * What this package must not do is scan by itself: the scan executes the
+ * repo's own build, test and dev commands, and `@gethmy/mcp` neither depends
+ * on `@gethmy/harness` (which owns both the execution and the schema) nor
+ * spawns a toolchain anywhere else. So it does what the tip asked a person to
+ * do — spawn the agent CLI — which keeps the dependency direction intact
+ * (agent → harness → shared, mcp beside them) and re-types no schema.
+ *
+ * Three properties, each deliberate.
+ *
+ * **Asked, never assumed.** The scan starts this repo's build, test and dev
+ * commands, which is minutes of work and arbitrary code from the checkout. A
+ * person is present at setup and is the right one to say yes.
+ *
+ * **Non-interactive setups are not scanned at all** — `--yes`, a pipe, a
+ * coding agent — even though `--yes` means yes to everything else. Those two
+ * are not the same question: the other confirmations write files this command
+ * already owns, and this one hands control to another package's process for
+ * an unbounded time. They get the tip, i.e. exactly the behaviour that
+ * shipped before this.
+ *
+ * **A failure is not an error.** The published `@gethmy/agent` gains this
+ * subcommand only on its next release, and `npx` needs a network. Either way
+ * the fallback is the tip, so an older agent degrades to the previous
+ * behaviour rather than turning setup red over an optional convenience.
+ *
+ * It deliberately does NOT pass `--write`: the proposal is printed for a
+ * person to read, which is card 1116's fourth criterion (never applied
+ * silently), and `scan-commands --write` is the separate, explicit act.
+ */
+export async function offerCommandScan(
+  repoDir: string,
+  assumeYes: boolean,
+): Promise<void> {
+  if (assumeYes) {
+    scanTip();
+    return;
+  }
+
+  const scan = await confirmOrDefault(assumeYes, {
+    message:
+      "Scan this repo's commands now? It runs your build, test and dev scripts once to prove which ones exist. Nothing is written.",
+    initialValue: true,
+  });
+  // Ctrl-C ends setup, as it does at every other prompt in this file. A
+  // cancel folded into "no" would carry on through the remaining steps as if
+  // the person had answered, which is the one reading they did not give.
+  if (p.isCancel(scan)) {
+    p.cancel("Setup cancelled.");
+    process.exit(0);
+  }
+  if (!scan) {
+    scanTip();
+    return;
+  }
+
+  console.log(
+    `  ${colors.dim("Running")} ${colors.highlight(`npx ${SCAN_ARGV.slice(1).join(" ")}`)}${colors.dim(" …")}`,
+  );
+  const result = spawnSync("npx", [...SCAN_ARGV], {
+    cwd: repoDir,
+    stdio: "inherit",
+  });
+  if (result.error || result.status !== 0) {
+    console.log(
+      `  ${colors.dim("The scan did not run — your installed @gethmy/agent may predate it.")}`,
+    );
+    scanTip();
+    return;
+  }
+  console.log(
+    `  ${colors.dim("Re-run it with")} ${colors.highlight("--write")} ${colors.dim("to merge that block into the pin.")}`,
+  );
+}