@gethmy/mcp 1.0.0 → 2.1.0

package/src/tui/setup.ts

@@ -0,0 +1,1281 @@
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  symlinkSync,
+  unlinkSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import * as p from "@clack/prompts";
+import {
+  areSkillsInstalled,
+  getConfigPath,
+  getLocalConfigPath,
+  hasProjectContext,
+  isConfigured,
+  loadConfig,
+  saveLocalConfig,
+} from "../config.js";
+import { type AgentId, detectAgents } from "./agents.js";
+import { runDocsStep } from "./docs.js";
+import { colors, formatPath, messages } from "./theme.js";
+import { getWriteSummary, writeFilesWithProgress } from "./writer.js";
+
+export type InstallMode = "local" | "global";
+
+export interface SetupOptions {
+  force?: boolean;
+  apiKey?: string;
+  userEmail?: string;
+  agents?: AgentId[];
+  installMode?: InstallMode;
+  workspaceId?: string;
+  projectId?: string;
+  skipContext?: boolean;
+  skipDocs?: boolean;
+}
+
+// Central skills directory for global installation
+const GLOBAL_SKILLS_DIR = join(homedir(), ".agents", "skills");
+
+// API base URL
+const API_URL = "https://gethmy.com/api";
+
+// Harmony workflow prompt - shared across agents
+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_by_short_id\` 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\`, \`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\`
+`;
+
+// Harmony plan prompt - unified plan creation and execution workflow
+const HARMONY_PLAN_PROMPT = `# Harmony Plan Workflow
+
+Create a new plan or work on an existing one. Argument: $ARGUMENTS
+
+## Step 1 — Detect Intent
+
+Parse \`$ARGUMENTS\` to determine the workflow:
+
+- **UUID** (contains dashes, 36 chars) → call \`harmony_get_plan\` with \`planId\` directly → **Step 2A**
+- **\`#N\`** (short ID) → call \`harmony_get_card_by_short_id\` to get the card, then \`harmony_get_plan\` with \`cardId\` → **Step 2A**
+- **Text** (anything else) → call \`harmony_list_plans\` with \`search\` set to the text
+  - If **one match** → use it → **Step 2A**
+  - If **multiple matches** → list them with title, status, phase, and updated date. Ask the user to pick one using \`AskUserQuestion\` → **Step 2A**
+  - If **no matches** → ask user: "No existing plans found for '$ARGUMENTS'. Would you like to create a new plan on this topic?" → **Step 2B**
+- **Empty / vague topic** → **Step 2B** (create new plan)
+
+---
+
+## Step 2A — Work on Existing Plan
+
+### 2A.1 — Analyze & Display
+
+Once you have the plan ID, call \`harmony_get_plan\` to fetch the full plan with tasks. Show a structured summary:
+
+\\\`\\\`\\\`
+## [Plan Title]
+**Status:** draft/active/archived | **Phase:** plan/execute/verify/done
+**Tasks:** N total (X pending, Y in_progress, Z completed)
+**URL:** https://gethmy.com/plans/{id}
+\\\`\\\`\\\`
+
+If plan is in execute phase and tasks already have linked cards, note which tasks have cards and which don't.
+
+### 2A.2 — Recall Context
+
+Call \`harmony_memory_search\` with the plan title to find related knowledge, patterns, or decisions that may inform execution.
+
+### 2A.3 — Present Options
+
+Use \`AskUserQuestion\` to offer execution choices. Adapt options based on plan state:
+
+#### Default options (plan in \`plan\` phase):
+
+**(A) Single card** — Create one card with plan summary + link to plan. Best for simple plans.
+**(B) Multiple cards** — Create one card per task via \`harmony_advance_plan\`. Best for complex plans with independent tasks.
+**(C) Analyze only** — Review the plan and design an implementation approach. Create cards later.
+**(D) Skip** — Do nothing.
+
+#### If plan has no tasks:
+Only offer **(A) Single card**, **(C) Analyze only**, or **(D) Skip**.
+
+#### If plan is already in \`execute\` phase with existing cards:
+**(A) Work on existing cards** — List cards with short IDs, suggest \`/hmy #N\` to start
+**(B) Create cards for remaining tasks** — Only create cards for tasks without linked cards
+**(C) Analyze progress** — Review what's done vs remaining
+**(D) Skip**
+
+### 2A.4 — Execute Choice
+
+#### Option A — Single card
+1. Call \`harmony_create_card\` with:
+   - \`title\`: Plan title
+   - \`description\`: Brief 2-3 sentence summary of the plan + \`\\n\\n[View plan](https://gethmy.com/plans/{planId})\`
+   - \`priority\`: based on plan task priorities (use highest)
+2. Call \`harmony_update_plan\` to set \`status: "active"\`, \`workflowPhase: "execute"\`
+
+#### Option B — Multiple cards (advance plan)
+1. Call \`harmony_advance_plan\` with:
+   - \`planId\`: the plan ID
+   - \`phase\`: \`"execute"\`
+   - \`summary\`: Brief summary of the plan scope
+2. Display the created cards with their short IDs
+
+#### Option C — Analyze only
+1. Present a structured implementation analysis:
+   - Suggested order of tasks
+   - Dependencies between tasks
+   - Key technical considerations from memory search
+   - Estimated complexity
+2. Suggest creating cards when ready
+
+#### Option D — Skip
+Acknowledge and stop.
+
+### 2A.5 — Summary
+
+After execution, show:
+- Created card(s) with short IDs
+- Current plan phase
+- Suggest next step: \`/hmy #N\` to start working on a card
+
+---
+
+## Step 2B — Create New Plan
+
+### 2B.1 — Context Gathering
+
+Before interviewing, gather existing context:
+
+1. Call \`harmony_get_board\` for board state (columns, cards, labels)
+2. Call \`harmony_recall\` with relevant tags to find existing knowledge on the topic
+3. Call \`harmony_memory_search\` with the topic to find related patterns/decisions/lessons
+
+Note what you learn — reference it during the interview to ask smarter questions.
+
+### 2B.2 — Structured Interview (3-5 questions)
+
+Interview the user with **3-5 focused questions** using AskUserQuestion. Adapt based on complexity.
+
+#### Core Questions
+1. **Problem & Audience**: What problem are we solving? Who benefits?
+2. **Scope**: What's in v1, what's deferred?
+3. **Technical Constraints**: Any technical preferences, constraints, or existing patterns to follow?
+
+#### Adaptive Follow-ups (if needed)
+- Key user flows or interactions?
+- Integration points with existing systems?
+- Performance, security, or accessibility requirements?
+
+#### Interview Rules
+- Reference what you found in Step 2B.1 (board state, memories) to ask informed questions
+- Skip questions that aren't relevant — simple features need fewer questions
+- Tell the user when you have enough information to draft
+
+### 2B.3 — Plan Document
+
+Create a structured markdown document:
+
+\\\`\\\`\\\`markdown
+# [Title]
+
+## Problem
+[What problem we're solving and why]
+
+## Scope
+
+### In Scope
+- [Feature/capability 1]
+- [Feature/capability 2]
+
+### Out of Scope
+- [Deferred items]
+
+## Approach
+[Technical design, architecture decisions, key patterns]
+
+### Key Decisions
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| ... | ... | ... |
+
+## Tasks
+1. **[Task title]** — priority: high
+   [Brief description]
+
+2. **[Task title]** — priority: medium
+   [Brief description]
+
+[Continue for all tasks...]
+
+## Risks & Mitigations
+| Risk | Mitigation |
+|------|------------|
+| ... | ... |
+
+## Success Criteria
+- [ ] [Measurable criterion]
+\\\`\\\`\\\`
+
+### 2B.4 — Create Plan
+
+Call \`harmony_create_plan\` with:
+- \`title\`: The plan title
+- \`content\`: Full markdown document from Step 2B.3
+- \`source\`: \`"agent"\`
+- \`workflowPhase\`: \`"plan"\`
+- \`tasks\`: Array of tasks from the Tasks section, each with:
+  - \`content\`: Task title + brief description
+  - \`priority\`: \`"high"\`, \`"medium"\`, or \`"low"\`
+  - \`status\`: \`"pending"\`
+
+### 2B.5 — User Approval
+
+Show the user:
+- Plan URL: \`https://gethmy.com/plans/{id}\`
+- Number of tasks created
+- Brief summary
+
+Then ask: **"Ready to execute? I'll create board cards from these tasks and start the execution phase."**
+
+Options:
+1. **Yes, advance to Execute** — proceed to Step 2B.6
+2. **Let me review first** — end here, they can advance later from the UI
+3. **Make changes** — iterate on the plan
+
+### 2B.6 — Advance to Execute
+
+Call \`harmony_advance_plan\` with:
+- \`planId\`: The plan ID from Step 2B.4
+- \`phase\`: \`"execute"\`
+- \`summary\`: A 2-3 sentence summary of the key decisions made during planning
+
+Report the result:
+- "Created N cards in 'To Do'. Use \`/hmy #<id>\` to start working on any card."
+- List the created cards with their short IDs
+
+## Key Tools Reference
+
+**Discovery:** \`harmony_list_plans\`, \`harmony_get_plan\`, \`harmony_get_card_by_short_id\`
+**Context:** \`harmony_get_board\`, \`harmony_recall\`, \`harmony_memory_search\`
+**Planning:** \`harmony_create_plan\`, \`harmony_advance_plan\`, \`harmony_update_plan\`
+**Execution:** \`harmony_create_card\`, \`harmony_update_card\`
+`;
+
+/**
+ * Register MCP server using Claude CLI
+ * Returns true if successful, false if CLI unavailable or failed
+ */
+async function registerMcpServer(): Promise<boolean> {
+  try {
+    const { execSync } = await import("node:child_process");
+    // Use the official CLI command to register the MCP server (npx for no global install)
+    execSync(
+      "claude mcp add --transport stdio harmony -- npx -y @gethmy/mcp@latest serve",
+      {
+        stdio: "pipe",
+      },
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Write MCP server config directly to settings.json (fallback method)
+ */
+async function writeMcpConfigFallback(home: string): Promise<void> {
+  const { readFileSync, writeFileSync, mkdirSync, existsSync } = await import(
+    "node:fs"
+  );
+  const settingsPath = join(home, ".claude", "settings.json");
+  const settingsDir = dirname(settingsPath);
+
+  // Ensure directory exists
+  if (!existsSync(settingsDir)) {
+    mkdirSync(settingsDir, { recursive: true });
+  }
+
+  // Read existing settings or start fresh
+  let settings: Record<string, unknown> = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    } catch {
+      // Invalid JSON, start fresh
+    }
+  }
+
+  // Merge mcpServers config
+  const mcpServers = (settings.mcpServers as Record<string, unknown>) || {};
+  mcpServers.harmony = {
+    command: "npx",
+    args: ["-y", "@gethmy/mcp@latest", "serve"],
+  };
+  settings.mcpServers = mcpServers;
+
+  // Write back
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+}
+
+interface Workspace {
+  id: string;
+  name: string;
+}
+
+interface Project {
+  id: string;
+  name: string;
+  description?: string;
+}
+
+/**
+ * Validate API key by testing connectivity
+ */
+async function validateApiKey(
+  apiKey: string,
+  apiUrl = API_URL,
+): Promise<{ valid: boolean; email?: string; error?: string }> {
+  try {
+    const response = await fetch(`${apiUrl}/v1/workspaces`, {
+      method: "GET",
+      headers: {
+        "Content-Type": "application/json",
+        "X-API-Key": apiKey,
+      },
+    });
+
+    if (!response.ok) {
+      const data = await response.json().catch(() => ({}));
+      return {
+        valid: false,
+        error: data.error || `API returned ${response.status}`,
+      };
+    }
+
+    // Try to get user info from /me endpoint if available
+    const meResponse = await fetch(`${apiUrl}/v1/me`, {
+      method: "GET",
+      headers: {
+        "Content-Type": "application/json",
+        "X-API-Key": apiKey,
+      },
+    });
+
+    if (meResponse.ok) {
+      const meData = await meResponse.json();
+      return { valid: true, email: meData.user?.email };
+    }
+
+    return { valid: true };
+  } catch (error) {
+    return {
+      valid: false,
+      error: error instanceof Error ? error.message : "Connection failed",
+    };
+  }
+}
+
+/**
+ * Fetch workspaces from API
+ */
+async function fetchWorkspaces(apiKey: string): Promise<Workspace[]> {
+  const response = await fetch(`${API_URL}/v1/workspaces`, {
+    method: "GET",
+    headers: {
+      "Content-Type": "application/json",
+      "X-API-Key": apiKey,
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch workspaces: ${response.status}`);
+  }
+
+  const data = await response.json();
+  return data.workspaces || [];
+}
+
+/**
+ * Fetch projects from API
+ */
+async function fetchProjects(
+  apiKey: string,
+  workspaceId: string,
+): Promise<Project[]> {
+  const response = await fetch(
+    `${API_URL}/v1/workspaces/${workspaceId}/projects`,
+    {
+      method: "GET",
+      headers: {
+        "Content-Type": "application/json",
+        "X-API-Key": apiKey,
+      },
+    },
+  );
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch projects: ${response.status}`);
+  }
+
+  const data = await response.json();
+  return data.projects || [];
+}
+
+export interface FileToWrite {
+  path: string;
+  content: string;
+  type: "text" | "json" | "toml";
+  tomlSection?: string;
+}
+
+export interface SymlinkToCreate {
+  target: string;
+  link: string;
+}
+
+/**
+ * Generate agent configuration files
+ */
+function getAgentFiles(
+  agentId: AgentId,
+  cwd: string,
+  installMode: InstallMode = "global",
+): { files: FileToWrite[]; symlinks: SymlinkToCreate[] } {
+  const home = homedir();
+  const files: FileToWrite[] = [];
+  const symlinks: SymlinkToCreate[] = [];
+
+  switch (agentId) {
+    case "claude": {
+      // Claude Code skill file
+      const skillContent = `---
+name: hmy
+description: Start working on a Harmony card. Use when given a card reference like #42, UUID, or card name to implement.
+argument-hint: <card-reference>
+---
+
+${HARMONY_WORKFLOW_PROMPT.replace("Your agent identifier", "claude-code").replace("Your agent name", "Claude Code")}
+`;
+
+      // hmy-plan skill file (unified plan creation + execution)
+      const planSkillContent = `---
+name: hmy-plan
+description: Create a new plan or work on an existing one. Use when asked to plan a feature, execute a plan, review a plan, or given a plan reference.
+argument-hint: [plan name, ID, or topic to plan]
+---
+
+${HARMONY_PLAN_PROMPT.replace("$ARGUMENTS", "$ARGUMENTS")}
+`;
+
+      if (installMode === "global") {
+        // Global mode: Write skills to ~/.agents/skills/, symlink directories to ~/.claude/skills/
+        files.push({
+          path: join(GLOBAL_SKILLS_DIR, "hmy", "SKILL.md"),
+          content: skillContent,
+          type: "text",
+        });
+        symlinks.push({
+          target: join(GLOBAL_SKILLS_DIR, "hmy"),
+          link: join(home, ".claude", "skills", "hmy"),
+        });
+
+        files.push({
+          path: join(GLOBAL_SKILLS_DIR, "hmy-plan", "SKILL.md"),
+          content: planSkillContent,
+          type: "text",
+        });
+        symlinks.push({
+          target: join(GLOBAL_SKILLS_DIR, "hmy-plan"),
+          link: join(home, ".claude", "skills", "hmy-plan"),
+        });
+      } else {
+        // Local mode: Write skills directly to project directory
+        files.push({
+          path: join(cwd, ".claude", "skills", "hmy", "SKILL.md"),
+          content: skillContent,
+          type: "text",
+        });
+        files.push({
+          path: join(cwd, ".claude", "skills", "hmy-plan", "SKILL.md"),
+          content: planSkillContent,
+          type: "text",
+        });
+      }
+
+      // Note: MCP server registration is handled separately via `claude mcp add` CLI
+      // in runSetup() after file writing, with fallback to settings.json if CLI unavailable
+      break;
+    }
+
+    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:
+
+## 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_by_short_id\` 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\` (agentIdentifier: "codex", agentName: "OpenAI Codex")
+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"
+
+## 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
+`;
+      files.push({
+        path: join(cwd, "AGENTS.md"),
+        content: agentsContent,
+        type: "text",
+      });
+
+      // Codex prompt file
+      const promptContent = `---
+name: hmy
+description: Start working on a Harmony card
+arguments:
+  - name: card
+    description: Card reference (#42, UUID, or name)
+    required: true
+---
+
+${HARMONY_WORKFLOW_PROMPT.replace("$ARGUMENTS", "{{card}}").replace("Your agent identifier", "codex").replace("Your agent name", "OpenAI Codex")}
+`;
+
+      if (installMode === "global") {
+        // Global mode: Write prompt to central location, symlink to ~/.codex/prompts/
+        files.push({
+          path: join(GLOBAL_SKILLS_DIR, "codex", "hmy.md"),
+          content: promptContent,
+          type: "text",
+        });
+        symlinks.push({
+          target: join(GLOBAL_SKILLS_DIR, "codex", "hmy.md"),
+          link: join(home, ".codex", "prompts", "hmy.md"),
+        });
+      } else {
+        // Local mode: Write prompt directly to ~/.codex/prompts/
+        files.push({
+          path: join(home, ".codex", "prompts", "hmy.md"),
+          content: promptContent,
+          type: "text",
+        });
+      }
+
+      // Codex config.toml (always global)
+      const tomlContent = `
+# Harmony MCP Server
+[mcp_servers.harmony]
+command = "npx"
+args = ["-y", "@gethmy/mcp@latest", "serve"]
+`;
+      files.push({
+        path: join(home, ".codex", "config.toml"),
+        content: tomlContent,
+        type: "toml",
+        tomlSection: "mcp_servers.harmony",
+      });
+      break;
+    }
+
+    case "cursor": {
+      // Cursor MCP config (always project-level)
+      files.push({
+        path: join(cwd, ".cursor", "mcp.json"),
+        content: JSON.stringify(
+          {
+            mcpServers: {
+              harmony: {
+                command: "npx",
+                args: ["-y", "@gethmy/mcp@latest", "serve"],
+              },
+            },
+          },
+          null,
+          2,
+        ),
+        type: "json",
+      });
+
+      // Cursor rule file
+      const ruleContent = `---
+description: Harmony card workflow rule
+globs:
+  - "**/*"
+alwaysApply: false
+---
+
+# Harmony Integration
+
+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")}
+`;
+
+      if (installMode === "global") {
+        // Global mode: Write rule to central location, symlink to ~/.cursor/rules/
+        files.push({
+          path: join(GLOBAL_SKILLS_DIR, "cursor", "harmony.mdc"),
+          content: ruleContent,
+          type: "text",
+        });
+        symlinks.push({
+          target: join(GLOBAL_SKILLS_DIR, "cursor", "harmony.mdc"),
+          link: join(home, ".cursor", "rules", "harmony.mdc"),
+        });
+      } else {
+        // Local mode: Write rule directly to project directory
+        files.push({
+          path: join(cwd, ".cursor", "rules", "harmony.mdc"),
+          content: ruleContent,
+          type: "text",
+        });
+      }
+      break;
+    }
+
+    case "windsurf": {
+      // Windsurf global MCP config (always global)
+      files.push({
+        path: join(home, ".codeium", "windsurf", "mcp_config.json"),
+        content: JSON.stringify(
+          {
+            mcpServers: {
+              harmony: {
+                command: "npx",
+                args: ["-y", "@gethmy/mcp@latest", "serve"],
+                disabled: false,
+                alwaysAllow: [],
+              },
+            },
+          },
+          null,
+          2,
+        ),
+        type: "json",
+      });
+
+      // Windsurf rule file
+      const ruleContent = `---
+trigger: model_decision
+description: Activate when user asks to work on a Harmony card (references like #42, card names, or task management)
+---
+
+# Harmony Card Workflow
+
+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")}
+`;
+
+      if (installMode === "global") {
+        // Global mode: Write rule to central location, symlink to ~/.codeium/windsurf/rules/
+        files.push({
+          path: join(GLOBAL_SKILLS_DIR, "windsurf", "harmony.md"),
+          content: ruleContent,
+          type: "text",
+        });
+        symlinks.push({
+          target: join(GLOBAL_SKILLS_DIR, "windsurf", "harmony.md"),
+          link: join(home, ".codeium", "windsurf", "rules", "harmony.md"),
+        });
+      } else {
+        // Local mode: Write rule directly to project directory
+        files.push({
+          path: join(cwd, ".windsurf", "rules", "harmony.md"),
+          content: ruleContent,
+          type: "text",
+        });
+      }
+      break;
+    }
+  }
+
+  return { files, symlinks };
+}
+
+/**
+ * Main setup wizard with smart detection
+ */
+export async function runSetup(options: SetupOptions = {}): Promise<void> {
+  const cwd = process.cwd();
+  const home = homedir();
+
+  console.clear();
+  console.log(messages.header());
+
+  // Check existing configuration
+  const existingConfig = loadConfig();
+  const alreadyConfigured = isConfigured();
+  const skillsStatus = areSkillsInstalled(cwd);
+  const hasContext = hasProjectContext(cwd);
+
+  // Track what we need to do
+  let needsApiKey = !alreadyConfigured;
+  let needsSkills = !skillsStatus.installed || options.force;
+  let needsContext = !hasContext && !options.skipContext;
+
+  // If workspace/project provided via flags, we'll set context
+  if (options.workspaceId || options.projectId) {
+    needsContext = true;
+  }
+
+  // Step 1: API Key
+  let apiKey = options.apiKey || existingConfig.apiKey;
+  let userEmail: string | undefined =
+    options.userEmail || existingConfig.userEmail || undefined;
+
+  if (needsApiKey || !apiKey || !apiKey.startsWith("hmy_")) {
+    const keyInput = await p.text({
+      message: "Enter your Harmony API key",
+      placeholder: "hmy_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+      validate: (value) => {
+        if (!value) return "API key is required";
+        if (!value.startsWith("hmy_")) return 'API key must start with "hmy_"';
+        if (value.length < 20) return "API key is too short";
+        return undefined;
+      },
+    });
+
+    if (p.isCancel(keyInput)) {
+      p.cancel("Setup cancelled");
+      process.exit(0);
+    }
+
+    apiKey = keyInput as string;
+    needsApiKey = true;
+  } else {
+    p.log.success(`Using existing API key: ${apiKey.slice(0, 8)}...`);
+  }
+
+  // Validate API key
+  const spinner = p.spinner();
+  spinner.start("Validating API key...");
+
+  const validation = await validateApiKey(apiKey);
+
+  if (!validation.valid) {
+    spinner.stop(colors.error("API key validation failed"));
+    p.log.error(validation.error || "Could not connect to Harmony API");
+    p.log.info("Get an API key at: https://gethmy.com/user/keys");
+    process.exit(1);
+  }
+
+  if (!userEmail) {
+    userEmail = validation.email;
+  }
+  spinner.stop(
+    colors.success(
+      userEmail ? `Connected as ${userEmail}` : "API key validated",
+    ),
+  );
+
+  // Step 2: Check if skills are already installed
+  let selectedAgents: AgentId[] = [];
+  let installMode: InstallMode = options.installMode || "global";
+
+  if (skillsStatus.installed && !options.force) {
+    p.log.success(`Skills already installed (${skillsStatus.location})`);
+
+    const reinstall = await p.confirm({
+      message: "Reinstall skills?",
+      initialValue: false,
+    });
+
+    if (p.isCancel(reinstall)) {
+      p.cancel("Setup cancelled");
+      process.exit(0);
+    }
+
+    needsSkills = reinstall as boolean;
+  }
+
+  if (needsSkills) {
+    // Detect and select agents
+    const detectedAgents = detectAgents(cwd);
+
+    if (options.agents && options.agents.length > 0) {
+      selectedAgents = options.agents;
+    } else {
+      const agentOptions = detectedAgents.map((agent) => ({
+        value: agent.id,
+        label: agent.name,
+        hint: agent.detected
+          ? colors.success(`${agent.description} (detected)`)
+          : colors.dim(`${agent.description}`),
+      }));
+
+      const agentSelection = await p.multiselect({
+        message: "Select agents to configure",
+        options: agentOptions,
+        initialValues: detectedAgents
+          .filter((a) => a.detected)
+          .map((a) => a.id),
+        required: true,
+      });
+
+      if (p.isCancel(agentSelection)) {
+        p.cancel("Setup cancelled");
+        process.exit(0);
+      }
+
+      selectedAgents = agentSelection as AgentId[];
+    }
+
+    if (selectedAgents.length === 0) {
+      p.log.warning("No agents selected. Skipping skills installation.");
+      needsSkills = false;
+    } else if (!options.installMode) {
+      // Select install mode
+      const modeSelection = await p.select({
+        message: "Where should Harmony skills be installed?",
+        options: [
+          {
+            value: "global",
+            label: "Global (shared) - Recommended",
+            hint: "Skills in ~/.agents/skills/, available in all projects",
+          },
+          {
+            value: "local",
+            label: "Local (project directory)",
+            hint: "Skills in .claude/skills/, committed to git",
+          },
+        ],
+        initialValue: "global",
+      });
+
+      if (p.isCancel(modeSelection)) {
+        p.cancel("Setup cancelled");
+        process.exit(0);
+      }
+
+      installMode = modeSelection as InstallMode;
+    }
+  }
+
+  // Step 3: Workspace and Project Selection
+  let selectedWorkspaceId = options.workspaceId;
+  let selectedProjectId = options.projectId;
+  let selectedWorkspaceName: string | undefined;
+  let selectedProjectName: string | undefined;
+
+  if (needsContext && !options.skipContext) {
+    // Fetch workspaces
+    spinner.start("Fetching workspaces...");
+    let workspaces: Workspace[] = [];
+
+    try {
+      workspaces = await fetchWorkspaces(apiKey);
+      spinner.stop(colors.success(`Found ${workspaces.length} workspace(s)`));
+    } catch (_error) {
+      spinner.stop(colors.warning("Could not fetch workspaces"));
+      p.log.warning(
+        "Skipping workspace/project selection. You can set this later.",
+      );
+      needsContext = false;
+    }
+
+    if (needsContext && workspaces.length > 0) {
+      // Select workspace
+      if (!selectedWorkspaceId) {
+        const workspaceOptions = workspaces.map((ws) => ({
+          value: ws.id,
+          label: ws.name,
+        }));
+
+        const workspaceSelection = await p.select({
+          message: "Select workspace",
+          options: workspaceOptions,
+        });
+
+        if (p.isCancel(workspaceSelection)) {
+          p.cancel("Setup cancelled");
+          process.exit(0);
+        }
+
+        selectedWorkspaceId = workspaceSelection as string;
+      }
+
+      selectedWorkspaceName = workspaces.find(
+        (w) => w.id === selectedWorkspaceId,
+      )?.name;
+
+      // Fetch and select project
+      spinner.start("Fetching projects...");
+      let projects: Project[] = [];
+
+      try {
+        projects = await fetchProjects(apiKey, selectedWorkspaceId);
+        spinner.stop(colors.success(`Found ${projects.length} project(s)`));
+      } catch (_error) {
+        spinner.stop(colors.warning("Could not fetch projects"));
+        p.log.warning("Skipping project selection. You can set this later.");
+      }
+
+      if (projects.length > 0 && !selectedProjectId) {
+        const projectOptions = projects.map((proj) => ({
+          value: proj.id,
+          label: proj.name,
+          hint: proj.description
+            ? colors.dim(proj.description.slice(0, 50))
+            : undefined,
+        }));
+
+        const projectSelection = await p.select({
+          message: "Select project",
+          options: projectOptions,
+        });
+
+        if (p.isCancel(projectSelection)) {
+          p.cancel("Setup cancelled");
+          process.exit(0);
+        }
+
+        selectedProjectId = projectSelection as string;
+        selectedProjectName = projects.find(
+          (p) => p.id === selectedProjectId,
+        )?.name;
+      }
+    }
+  }
+
+  // Step 4: Collect all files and symlinks to create
+  const allFiles: FileToWrite[] = [];
+  const allSymlinks: SymlinkToCreate[] = [];
+
+  // Always save global config if we have an API key change
+  if (needsApiKey || !alreadyConfigured) {
+    allFiles.push({
+      path: getConfigPath(),
+      content: JSON.stringify(
+        {
+          apiKey,
+          apiUrl: API_URL,
+          userEmail: userEmail || null,
+          activeWorkspaceId: null,
+          activeProjectId: null,
+        },
+        null,
+        2,
+      ),
+      type: "text", // Use text to avoid merging
+    });
+  }
+
+  // Project docs scaffold / verification
+  if (!options.skipDocs) {
+    const docsResult = await runDocsStep(cwd);
+    if (!docsResult.skipped) {
+      for (const file of docsResult.files) {
+        allFiles.push(file);
+      }
+    }
+  }
+
+  // Agent-specific files
+  if (needsSkills && selectedAgents.length > 0) {
+    for (const agentId of selectedAgents) {
+      const { files, symlinks } = getAgentFiles(agentId, cwd, installMode);
+      allFiles.push(...files);
+      allSymlinks.push(...symlinks);
+    }
+  }
+
+  // Step 5: Show summary
+  const detectedAgents = detectAgents(cwd);
+
+  console.log("");
+  p.log.step("Summary");
+  console.log("");
+
+  console.log(`  ${colors.bold("API Key:")} ${apiKey.slice(0, 8)}...`);
+  if (userEmail) {
+    console.log(`  ${colors.bold("Email:")} ${userEmail}`);
+  }
+
+  if (needsSkills && selectedAgents.length > 0) {
+    console.log(
+      `  ${colors.bold("Agents:")} ${selectedAgents.map((a) => detectedAgents.find((d) => d.id === a)?.name).join(", ")}`,
+    );
+    console.log(
+      `  ${colors.bold("Install:")} ${installMode === "global" ? "Global (~/.agents/skills/)" : "Local (project)"}`,
+    );
+  } else {
+    console.log(
+      `  ${colors.bold("Skills:")} Already installed (${skillsStatus.location || "none"})`,
+    );
+  }
+
+  if (selectedWorkspaceId) {
+    console.log(
+      `  ${colors.bold("Workspace:")} ${selectedWorkspaceName || selectedWorkspaceId}`,
+    );
+  }
+  if (selectedProjectId) {
+    console.log(
+      `  ${colors.bold("Project:")} ${selectedProjectName || selectedProjectId}`,
+    );
+  }
+
+  if (allFiles.length > 0) {
+    const summary = getWriteSummary(allFiles, { force: options.force });
+
+    if (summary.toCreate.length > 0) {
+      console.log("");
+      console.log(`  ${colors.success("Files to create:")}`);
+      for (const path of summary.toCreate) {
+        console.log(`    ${colors.dim("\u2022")} ${path}`);
+      }
+    }
+
+    if (allSymlinks.length > 0) {
+      console.log("");
+      console.log(`  ${colors.info("Symlinks to create:")}`);
+      for (const symlink of allSymlinks) {
+        console.log(
+          `    ${colors.dim("\u{1F517}")} ${formatPath(symlink.link, home)} → ${formatPath(symlink.target, home)}`,
+        );
+      }
+    }
+
+    if (summary.toUpdate.length > 0) {
+      console.log("");
+      console.log(`  ${colors.info("Files to update:")}`);
+      for (const path of summary.toUpdate) {
+        console.log(`    ${colors.dim("\u2022")} ${path}`);
+      }
+    }
+
+    if (summary.toSkip.length > 0 && !options.force) {
+      console.log("");
+      console.log(`  ${colors.dim("Files to skip (already exist):")}`);
+      for (const path of summary.toSkip) {
+        console.log(`    ${colors.dim("\u2022")} ${path}`);
+      }
+    }
+  }
+
+  console.log("");
+
+  // Step 6: Confirm and execute
+  const shouldProceed = await p.confirm({
+    message: "Proceed with setup?",
+    initialValue: true,
+  });
+
+  if (p.isCancel(shouldProceed) || !shouldProceed) {
+    p.cancel("Setup cancelled");
+    process.exit(0);
+  }
+
+  console.log("");
+
+  // Step 7: Write files
+  if (allFiles.length > 0) {
+    await writeFilesWithProgress(allFiles, { force: options.force });
+  }
+
+  // Step 8: Create symlinks
+  if (allSymlinks.length > 0) {
+    for (const symlink of allSymlinks) {
+      try {
+        // Ensure parent directory exists
+        const linkDir = dirname(symlink.link);
+        if (!existsSync(linkDir)) {
+          mkdirSync(linkDir, { recursive: true });
+        }
+
+        // Check if link already exists
+        let linkExists = false;
+        try {
+          lstatSync(symlink.link);
+          linkExists = true;
+        } catch {
+          // Link doesn't exist
+        }
+
+        if (linkExists) {
+          if (options.force) {
+            unlinkSync(symlink.link);
+          } else {
+            // Skip existing symlink
+            continue;
+          }
+        }
+
+        symlinkSync(symlink.target, symlink.link);
+      } catch {
+        p.log.warning(`Failed to create symlink: ${symlink.link}`);
+      }
+    }
+  }
+
+  // Step 8b: Register MCP server for Claude (project-local scope)
+  const claudeDetected = detectAgents(cwd).some(
+    (a) => a.id === "claude" && a.detected,
+  );
+  if (claudeDetected || selectedAgents.includes("claude")) {
+    const mcpRegistered = await registerMcpServer();
+    if (mcpRegistered) {
+      console.log(
+        `  ${colors.success("\u2713")} ${colors.dim("MCP server registered via claude CLI")}`,
+      );
+    } else {
+      // Fallback: write directly to settings.json
+      try {
+        await writeMcpConfigFallback(home);
+        console.log(
+          `  ${colors.success("\u2713")} ${colors.dim(formatPath(join(home, ".claude", "settings.json"), home))} ${colors.dim("(updated)")}`,
+        );
+      } catch {
+        p.log.warning(
+          "Could not register MCP server. Run manually: claude mcp add --transport stdio harmony -- npx -y @gethmy/mcp@latest serve",
+        );
+      }
+    }
+  }
+
+  // Step 9: Save local context
+  if (selectedWorkspaceId || selectedProjectId) {
+    const localConfig: { workspaceId?: string; projectId?: string } = {};
+    if (selectedWorkspaceId) localConfig.workspaceId = selectedWorkspaceId;
+    if (selectedProjectId) localConfig.projectId = selectedProjectId;
+    saveLocalConfig(localConfig, cwd);
+    console.log(
+      `  ${colors.success("\u2713")} ${colors.dim(formatPath(getLocalConfigPath(cwd), home))} ${colors.dim("(created)")}`,
+    );
+  }
+
+  // Step 10: Show completion message
+  console.log("");
+  p.outro(colors.success("Setup complete!"));
+
+  console.log("");
+  console.log(`  ${colors.bold("Configuration:")}`);
+  console.log(`    API key:   ${formatPath(getConfigPath(), home)}`);
+  if (needsSkills && selectedAgents.length > 0) {
+    console.log(
+      `    Skills:    ${installMode === "global" ? "~/.agents/skills/ (global)" : ".claude/skills/ (local)"}`,
+    );
+  }
+  if (selectedWorkspaceId || selectedProjectId) {
+    console.log(`    Context:   ${formatPath(getLocalConfigPath(cwd), home)}`);
+  }
+
+  console.log("");
+  console.log(`  ${colors.bold("Usage:")}`);
+
+  if (!needsSkills || selectedAgents.includes("claude")) {
+    console.log(
+      `    ${colors.brand("Claude Code:")} ${colors.highlight("/hmy #42")} or ${colors.highlight("/hmy-plan")} ${colors.dim("(create or execute plans)")}`,
+    );
+  }
+
+  if (selectedAgents.includes("codex")) {
+    console.log(
+      `    ${colors.brand("Codex:")} ${colors.highlight("/prompts:hmy #42")}`,
+    );
+  }
+
+  if (
+    selectedAgents.includes("cursor") ||
+    selectedAgents.includes("windsurf")
+  ) {
+    console.log(
+      `    ${colors.brand("Cursor/Windsurf:")} MCP tools available automatically`,
+    );
+  }
+
+  console.log("");
+  console.log(`  ${colors.dim("Add to new project: npx @gethmy/mcp setup")}`);
+  console.log(
+    `  ${colors.dim("Need help? Visit https://gethmy.com/docs/mcp")}`,
+  );
+  console.log("");
+}