@nst173/superpowers-ccg 1.3.0 → 1.3.1

package/README.md

@@ -1,54 +1,17 @@
 # Superpowers-CCG
 
-Superpowers-CCG is a fork/enhanced variant of [obra/superpowers](https://github.com/obra/superpowers). It keeps the same skills-driven workflow and adds **CCG multi-model orchestration**: Claude is the **pure orchestrator** (never writes code), routing implementation to **Codex MCP** (backend and systems) and **Gemini MCP** (frontend), with **Opus as the reviewer** for every code-changing path.
+Superpowers-CCG is a fork/enhanced variant of [obra/superpowers](https://github.com/obra/superpowers). It keeps the same skills-driven workflow and adds **CCG multi-model orchestration**: Claude is the **pure orchestrator** (never writes code), routing implementation to **Codex MCP** (backend and systems) and **Gemini MCP** (frontend), with **Claude CP4 final spec review** and **Haiku for trivial tasks and fast exploration**.
 
 > **CCG** = **C**laude + **C**odex + **G**emini
 
-## npm CLI
-
-This repo now also ships a project-level installer CLI for supported agents:
-
-- Claude Code
-- Cursor
-- Antigravity
-
-Run it with:
-
-```bash
-npx @nst173/superpowers-ccg setup
-```
-
-Install only specific agents:
-
-```bash
-npx @nst173/superpowers-ccg setup --agent claude-code --agent cursor
-```
-
-Install into another project directory:
-
-```bash
-npx @nst173/superpowers-ccg setup ../my-project --all
-```
-
-Preview changes without writing files:
-
-```bash
-npx @nst173/superpowers-ccg setup --dry-run
-```
-
-List supported agents:
-
-```bash
-npx @nst173/superpowers-ccg list
-```
-
 ## What You Get
 
 - **Claude as pure orchestrator**: Claude routes, coordinates, and integrates. It never writes implementation code.
 - **Multi-model routing (CCG)**: route tasks to Codex (backend and systems) or Gemini (frontend). Use **CROSS_VALIDATION** for full-stack or critical tasks.
-- **Opus reviewer**: Opus reviews all code-changing paths directly.
+- **Final spec review**: CP4 performs a pure spec check against the original request and CP1 success criteria.
 - **MCP tool integration**: external calls go through `mcp__codex__codex` and `mcp__gemini__gemini`.
-- **Collaboration checkpoints**: CP1/CP2/CP3 checkpoints are embedded in the main skills.
+- **Collaboration checkpoints**: CP0/CP1/CP2/CP3/CP4 checkpoints are embedded in the main skills.
+- **Smart context sharing**: CP0 produces reusable context artifacts, CP1 builds task-scoped bundles, and same-task follow-ups send deltas only.
 - **Fail-closed gate**: if a required external model call cannot complete, the workflow stops with `BLOCKED`.
 
 ## Quick Start (Claude Code)
@@ -81,10 +44,10 @@ claude mcp add gemini -s user --transport stdio -- uvx --from git+https://github
 
 You normally do **not** call MCP tools manually. Tell Claude what you want, and the workflow decides when to invoke external models.
 
-- Backend or systems: "Use Codex MCP for the API/database/CI parts, return a patch only."
-- Frontend: "Use Gemini MCP for UI/components/styles, return a patch only."
+- Backend or systems: "Use Codex MCP for the API/database/CI parts and return the final files directly."
+- Frontend: "Use Gemini MCP for UI/components/styles and return the final files directly."
 - Cross-validation: "Do CROSS_VALIDATION for this design and reconcile conflicts."
-- Code review runs automatically after implementation.
+- CP4 final spec review runs automatically at the end of the workflow.
 
 ## Model Selection
 
@@ -97,50 +60,22 @@ You normally do **not** call MCP tools manually. Tell Claude what you want, and
 
 The routing and checkpoint rules live in `skills/coordinating-multi-model-work/`.
 
-## Cursor Plugin
-
-This repo now also ships a Cursor Marketplace plugin scaffold based on `cursor/plugin-template`.
-
-- Marketplace manifest: [`.cursor-plugin/marketplace.json`](.cursor-plugin/marketplace.json)
-- Plugin package: [`plugins/superpowers-ccg`](plugins/superpowers-ccg)
-- Setup notes: [`docs/cursor-plugin.md`](docs/cursor-plugin.md)
-
-Validate the Cursor packaging with:
-
-```bash
-node scripts/validate-cursor-plugin.mjs
-```
-
-## Antigravity Port
-
-This repo now also includes an Antigravity-oriented port built around:
-
-- [`AGENTS.md`](AGENTS.md)
-- [`GEMINI.md`](GEMINI.md)
-- [`.agent/skills`](.agent/skills)
-- [`config/antigravity/mcp_config.example.json`](config/antigravity/mcp_config.example.json)
-- [`docs/antigravity.md`](docs/antigravity.md)
-
-Sync the project skills with:
-
-```bash
-node scripts/sync-antigravity-workspace.mjs
-```
-
 ## Checkpoint Protocol
 
 | Checkpoint | When | Purpose |
 |---|---|---|
-| CP1 | Before first Task call | Assess routing, invoke external model early |
-| CP2 | Mid-execution | Triggered by uncertainty, stalled debugging, or repeated failures |
-| CP3 | Before claiming completion | Final domain review and verification |
+| CP0 | Before CP1 | Context acquisition with Auggie for local code context and Grok Search for external research |
+| CP1 | Immediately after CP0, before first Task call | Task assessment and routing using the CP1 routing matrix |
+| CP2 | After CP1 when routed externally | External execution via Gemini/Codex/Cross-Validation with final file output |
+| CP3 | After CP2 when reconciliation is needed | Resolve external-model conflicts, gaps, and clarifications before CP4 |
+| CP4 | Final step of every workflow | Pure spec review against the original request and CP1 success criteria |
 
 ## Differences vs Superpowers (obra/superpowers)
 
 - **Claude as orchestrator-only**: Claude never writes implementation code.
 - **Built-in multi-model routing** via MCP tools (Codex, Gemini).
 - **Codex covers systems work**: scripts, CI/CD, Dockerfiles, and infrastructure route to Codex.
-- **Opus reviews all code** directly.
+- **CP4 final spec review is spec-only**: no automatic style, redundancy, or best-practice review is part of the checkpoint flow.
 - **CP checkpoints** enforce evidence-driven collaboration.
 - **Skill set changes** align the plugin with the CCG workflow.
 
@@ -167,5 +102,6 @@ See `tests/claude-code/README.md` for the Claude Code skills test suite.
 - [obra/superpowers](https://github.com/obra/superpowers) - Original Superpowers project
 - [BryanHoo/superpowers-ccg](https://github.com/BryanHoo/superpowers-ccg) - CCG collaboration fork
 - [fengshao1227/ccg-workflow](https://github.com/fengshao1227/ccg-workflow) - CCG workflow
+- [Danau5tin/multi-agent-coding-system](https://github.com/Danau5tin/multi-agent-coding-system) - Smart context-sharing inspiration
 - [GuDaStudio/geminimcp](https://github.com/GuDaStudio/geminimcp) - Gemini MCP
 - [GuDaStudio/codexmcp](https://github.com/GuDaStudio/codexmcp) - Codex MCP

package/agents/code-reviewer.md

@@ -2,7 +2,7 @@
 name: code-reviewer
 description: |
   Use this agent when a major project step has been completed and needs to be reviewed against the original plan and coding standards. Examples: <example>Context: The user is creating a code-review agent that should be called after a logical chunk of code is written. user: "I've finished implementing the user authentication system as outlined in step 3 of our plan" assistant: "Great work! Now let me use the code-reviewer agent to review the implementation against our plan and coding standards" <commentary>Since a major project step has been completed, use the code-reviewer agent to validate the work against the plan and identify any issues.</commentary></example> <example>Context: User has completed a significant feature implementation. user: "The API endpoints for the task management system are now complete - that covers step 2 from our architecture document" assistant: "Excellent! Let me have the code-reviewer agent examine this implementation to ensure it aligns with our plan and follows best practices" <commentary>A numbered step from the planning document has been completed, so the code-reviewer agent should review the work.</commentary></example>
-model: opus
+model: sonnet
 ---
 
 You are the final code review arbiter with expertise in software architecture, design patterns, and best practices. Your role is to review completed project steps against original plans, evaluate any assistant-review feedback, and make the final judgment on whether the implementation is ready.

package/bin/cli.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+import { install } from '../lib/installer.js';
+import { collectInteractiveConfig } from '../lib/prompts.js';
+import { writeMcpConfig } from '../lib/mcp-config.js';
+
+const AGENTS = new Set(['claude-code', 'cursor', 'antigravity']);
+const FLAG_TO_ENV = {
+  '--grok-api-url': 'GROK_API_URL',
+  '--grok-api-key': 'GROK_API_KEY',
+  '--tavily-api-url': 'TAVILY_API_URL',
+  '--tavily-api-key': 'TAVILY_API_KEY',
+  '--firecrawl-api-key': 'FIRECRAWL_API_KEY',
+  '--firecrawl-api-url': 'FIRECRAWL_API_URL'
+};
+
+async function main() {
+  const { command, flags } = parseArgs(process.argv.slice(2));
+
+  if (flags.help || command === 'help') {
+    printHelp();
+    return;
+  }
+
+  if (command === 'init') {
+    const { agents, mcpEnv } = await collectInteractiveConfig();
+    await runInstall(agents, mcpEnv);
+    return;
+  }
+
+  if (command === 'install') {
+    const agents = parseAgents(flags.agents);
+    const mcpEnv = collectFlagMcpEnv(flags);
+
+    ensureRequiredGrokConfig(mcpEnv);
+
+    await runInstall(agents, mcpEnv);
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+async function runInstall(agents, mcpEnv) {
+  await install(agents);
+  await writeMcpConfig(mcpEnv);
+
+  console.log(`Installed superpowers-ccg for: ${agents.join(', ')}`);
+  console.log('Updated project MCP settings in .claude/settings.json');
+}
+
+function parseArgs(argv) {
+  if (argv.length === 0) {
+    return {
+      command: 'init',
+      flags: {}
+    };
+  }
+
+  let command = 'init';
+  let index = 0;
+
+  if (!argv[0].startsWith('-')) {
+    command = argv[0];
+    index = 1;
+  }
+
+  const flags = {};
+
+  for (; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (!arg.startsWith('-')) {
+      throw new Error(`Unexpected argument: ${arg}`);
+    }
+
+    if (arg === '--help' || arg === '-h') {
+      flags.help = true;
+      continue;
+    }
+
+    const [name, inlineValue] = arg.split(/=(.*)/s, 2);
+
+    if (!(name in FLAG_TO_ENV) && name !== '--agents') {
+      throw new Error(`Unknown flag: ${name}`);
+    }
+
+    let value = inlineValue;
+
+    if (value === undefined) {
+      index += 1;
+
+      if (index >= argv.length) {
+        throw new Error(`Missing value for ${name}`);
+      }
+
+      value = argv[index];
+    }
+
+    flags[name.slice(2).replace(/-([a-z])/g, (_, char) => char.toUpperCase())] = value;
+  }
+
+  return { command, flags };
+}
+
+function parseAgents(value) {
+  if (!value) {
+    throw new Error('Missing required flag: --agents');
+  }
+
+  const agents = value
+    .split(',')
+    .map((agent) => agent.trim())
+    .filter(Boolean);
+
+  if (agents.length === 0) {
+    throw new Error('At least one agent must be provided.');
+  }
+
+  for (const agent of agents) {
+    if (!AGENTS.has(agent)) {
+      throw new Error(`Unsupported agent: ${agent}`);
+    }
+  }
+
+  return [...new Set(agents)];
+}
+
+function collectFlagMcpEnv(flags) {
+  const mcpEnv = {};
+
+  for (const [flag, envKey] of Object.entries(FLAG_TO_ENV)) {
+    const flagKey = flag.slice(2).replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+    const value = typeof flags[flagKey] === 'string' ? flags[flagKey].trim() : '';
+
+    if (value) {
+      mcpEnv[envKey] = value;
+    }
+  }
+
+  return mcpEnv;
+}
+
+function ensureRequiredGrokConfig(mcpEnv) {
+  const requiredKeys = ['GROK_API_URL', 'GROK_API_KEY'];
+  const missingKeys = requiredKeys.filter((key) => !mcpEnv[key]);
+
+  if (missingKeys.length > 0) {
+    throw new Error(`Missing required flags: ${missingKeys.map((key) => envKeyToFlag(key)).join(', ')}`);
+  }
+}
+
+function envKeyToFlag(envKey) {
+  return `--${envKey.toLowerCase().replace(/_/g, '-')}`;
+}
+
+function printHelp() {
+  console.log(`Usage:
+  superpowers-ccg [init]
+  superpowers-ccg install --agents <comma-list> --grok-api-url <url> --grok-api-key <key> [options]
+
+Agents:
+  claude-code,cursor,antigravity
+
+Options:
+  --agents <comma-list>
+  --grok-api-url <url>
+  --grok-api-key <key>
+  --tavily-api-url <url>
+  --tavily-api-key <key>
+  --firecrawl-api-key <key>
+  --firecrawl-api-url <url>
+  -h, --help`);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/hooks/pre-tool-use-task.sh

@@ -1,4 +1,4 @@
-#!/usr/bin/env bash
-# PreToolUse hook for Task tool - enforce model selection reminder
-
-echo "⚠️ Task model enforcement check: implementation/docs -> model:sonnet, search/exploration -> model:haiku" >&2
+#!/usr/bin/env bash
+# PreToolUse hook for Task tool - keep Task usage aligned with the CP workflow
+
+echo "⚠️ CP routing check: use Task for coordination, review, or exploration only; route implementation through CP1 to Codex or Gemini, and keep CP4 Final Spec Review in the Claude main thread." >&2

package/hooks/session-start.sh

@@ -14,11 +14,12 @@ fi
 COMPACT_CONTEXT="$(cat <<'ENDOFCOMPACT'
 You have superpowers.
 
-**Core Rules:**
-1. **1% Rule:** If there is even a 1% chance a skill applies, use the Skill tool to load it before responding.
-2. **Claude is orchestrator-only:** All implementation code goes through external models (Codex/Gemini MCP).
-3. **Checkpoint Protocol:** CP1 before first Task call, CP3 before claiming completion.
-4. **Fail-Closed:** If Routing != CLAUDE and MCP call fails, output BLOCKED (see GATE.md for tiered policy).
+**Core Rules:**
+1. **1% Rule:** If there is even a 1% chance a skill applies, use the Skill tool to load it before responding.
+2. **CP0 first:** Do minimal context acquisition before routing. Use Auggie for full local codebase context retrieval, and use Grok Search only for external/current knowledge or research.
+3. **Claude is orchestrator-only:** All implementation code goes through external models (Codex/Gemini MCP).
+4. **Checkpoint Protocol:** CP1 Task Assessment & Routing before the first Task call, CP2 External Execution when routing to external models, CP3 Reconciliation only after cross-validation or conflicting/non-trivial external feedback, and CP4 Final Spec Review as the last step.
+5. **Fail-Closed:** If Routing != CLAUDE and MCP call fails, output BLOCKED (see GATE.md for tiered policy).
 
 **Multi-Model Routing:**
 - Backend (API, DB, auth) → CODEX (`mcp__codex__codex`)
@@ -27,13 +28,11 @@ You have superpowers.
 - Full-stack/uncertain → CROSS_VALIDATION (multiple)
 - Docs/coordination only → CLAUDE
 
-**Shared Serena (HTTP 9121):** All agents share one Serena instance. `global/response_protocol` controls token-efficient agent output format.
-
-**Supplementary Tools (optional):** Grok Search/Tavily (research), Sequential-Thinking (complex reasoning), Serena (shared context bus), Magic (UI components), Morphllm (bulk edits).
+**Supplementary Tools (optional):** Grok Search/Tavily (research), Sequential-Thinking (complex reasoning), Magic (UI components), Morphllm (bulk edits).
 
 **Skill Namespace:** `superpowers-ccg:` — use Skill tool to load any skill by name.
 
-**To learn more:** Load `superpowers-ccg:using-superpowers` or `superpowers-ccg:coordinating-multi-model-work` for full instructions.
+**To learn more:** Load `superpowers-ccg:coordinating-multi-model-work` for the full orchestration workflow.
 ENDOFCOMPACT
 )"
 

package/hooks/user-prompt-submit.sh

@@ -3,29 +3,63 @@
 
 set -euo pipefail
 
-REMINDER_TEXT="[CP Protocol Threshold]
+# Print the reminder as literal text so markdown backticks never trigger shell execution.
+cat <<'EOF'
+[CP Protocol Threshold]
 
-Before the first Task call, output a short standalone [CP1 Assessment] block.
-Before claiming completion, output a short standalone [CP3 Assessment] block.
+Before the first Task call, do minimal CP0 context acquisition using Auggie for full local context retrieval and Grok Search only for external/current knowledge or research.
+Immediately after CP0 completes, run CP1 Task Assessment & Routing using the original user request and the CP0 context artifacts, then build one task-scoped context bundle for the next bounded task.
+CP1 routing guide:
+| Task Category | Model | Cross-Validation | Notes / Triggers |
+|---|---|---|---|
+| Pure Frontend / UI / Styling | Gemini | No | Fastest path |
+| Pure Backend / Logic / API | Codex | No | Use cross-validation only if the task becomes high-impact or architecture-heavy |
+| Full-Stack / Architecture | Cross-Validation (Codex + Gemini) | Yes | Both models run in parallel |
+| Docs / Comments / Simple Fix | Claude | No | Usually no external models |
+| Debugging / Performance | Codex | No | Escalate to cross-validation only if the failure mode stays ambiguous |
+| Infrastructure / DevOps | Codex | No | Use cross-validation only for high-risk changes |
+| Data / ML / Analytics | Codex | No | Use cross-validation only if the task becomes unusually complex |
+| Testing / Test Coverage | Cross-Validation (Codex + Gemini) | Yes | Useful when tests span frontend and backend behavior |
+| Cross-Cutting / Security | Codex | Yes | Extra safety layer |
+| Uncategorized / Ambiguous | Claude | No | Fail-closed: ask clarifying questions immediately |
+If the request is unclear or incomplete, route to Claude, output the CP1 block below, and then immediately ask clarifying questions.
+If CP1 routes to Gemini, Codex, or Cross-Validation, run CP2 External Execution using a task-scoped context bundle: compressed original request, context refs, hydrated context snippets, and the CP1 task summary plus success criteria. Reuse the same worker SESSION_ID only for follow-up fixes on that bounded task, and send deltas only on follow-up turns. Require final file contents directly (preferred) or a unified diff patch using External Response Protocol v1.1.
+If CP1 chose Cross-Validation or CP2 returned conflicts, overlap, PARTIAL/NO spec compliance, clarifications, CONTINUE_SESSION, or other non-trivial feedback, run CP3 Reconciliation. In CP3, parse every External Response Protocol block, resolve conflicts against the original requirement, decide whether to proceed, retry, continue, or ask the user, and do not apply file edits yourself.
+Always run CP4 Final Spec Review as the final step, after CP3 when reconciliation is needed or directly after Claude-only / non-reconciled work. In CP4, use the original user request, the CP1 task summary, and the files changed by the workflow to judge spec satisfaction only. Do not perform code quality, style, redundancy, or best-practice review in CP4.
 
-Use the minimal format below. Do not add extra narration to the checkpoint itself.
+Use the exact CP1, CP3, and CP4 formats below. Do not add extra narration inside those blocks. Use the literal headings and field labels exactly as written. Do not rename them. The CP1 route bullets must begin exactly with `- Model:`, `- Cross-Validation:`, and `- Reason:`. Legacy `[CP1 Assessment]`, `[CP1] Routing`, `[CP3 Assessment]`, and `[CP3] Verified` formats are invalid.
 
-[CP1 Assessment]
-- Task type: [Frontend/Backend/Full-stack/Other]
-- Complexity: [Trivial/Standard/Critical]
-- Routing decision: [CLAUDE/CODEX/GEMINI/CROSS_VALIDATION]
-- Rationale: [one sentence]
+# CP1 ROUTING DECISION
 
-Compact trivial form:
-[CP1] Routing: CLAUDE | Trivial: <reason>
+## Task Summary
+[One-sentence English summary of the request]
 
-[CP3 Assessment]
-- Task type: [Frontend/Backend/Full-stack/Other]
-- Routing decision: [CLAUDE/CODEX/GEMINI/CROSS_VALIDATION]
-- Rationale: [one sentence]
+## Route
+- Model: Gemini / Codex / Cross-Validation (Codex + Gemini) / Claude
+- Cross-Validation: Yes / No
+- Reason: [short 1-line justification]
 
-Compact trivial form:
-[CP3] Verified: <evidence>
-"
+## Next Action
+[Proceed to CP2 with the chosen model(s) OR handle directly OR ask user]
 
-printf '%s\n' "$REMINDER_TEXT"
+# CP3 RECONCILIATION COMPLETE
+
+## Summary
+[One-sentence summary of what was merged/applied]
+
+## Changes Applied
+- [List of files created/edited/deleted]
+
+## Status
+Ready for CP4
+
+# CP4 SPEC REVIEW COMPLETE
+
+## Result
+- **Status**: PASS / PARTIAL / FAIL
+- **Explanation**: [Clear, concise explanation]
+
+## Recommendation
+- If PASS: Task is complete
+- If PARTIAL/FAIL: [Specific gaps + suggested next action (e.g. re-run external model or ask user)]
+EOF

package/lib/installer.js

@@ -0,0 +1,50 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+
+const AGENTS = new Set(['claude-code', 'cursor', 'antigravity']);
+
+export async function install(agents) {
+  if (!Array.isArray(agents) || agents.length === 0) {
+    throw new Error('At least one agent must be selected for installation.');
+  }
+
+  for (const agent of agents) {
+    if (!AGENTS.has(agent)) {
+      throw new Error(`Unsupported agent: ${agent}`);
+    }
+
+    const sourceDir = new URL(`../templates/${agent}/`, import.meta.url);
+    await copyTree(sourceDir, process.cwd());
+  }
+
+  await copyTree(new URL('../skills/', import.meta.url), path.join(process.cwd(), 'skills'));
+  await copyTree(new URL('../agents/', import.meta.url), path.join(process.cwd(), 'agents'));
+}
+
+async function copyTree(sourceDir, destinationDir) {
+  const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const sourcePath = new URL(entry.isDirectory() ? `${entry.name}/` : entry.name, sourceDir);
+    const destinationPath = path.join(destinationDir, entry.name);
+
+    if (entry.isDirectory()) {
+      await fs.mkdir(destinationPath, { recursive: true });
+      await copyTree(sourcePath, destinationPath);
+      continue;
+    }
+
+    try {
+      await fs.access(destinationPath);
+      console.warn(`Skipping existing file: ${path.relative(process.cwd(), destinationPath)}`);
+      continue;
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        throw error;
+      }
+    }
+
+    await fs.mkdir(path.dirname(destinationPath), { recursive: true });
+    await fs.copyFile(sourcePath, destinationPath);
+  }
+}

package/lib/mcp-config.js

@@ -0,0 +1,85 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+
+const GROK_SEARCH_URL = 'git+https://github.com/GuDaStudio/GrokSearch@grok-with-tavily';
+const GEMINI_URL = 'git+https://github.com/GuDaStudio/codexmcp.git';
+const CODEX_URL = 'git+https://github.com/GuDaStudio/geminimcp.git';
+
+export async function writeMcpConfig(mcpEnv) {
+  const settingsDir = path.join(process.cwd(), '.claude');
+  const settingsPath = path.join(settingsDir, 'settings.json');
+
+  await fs.mkdir(settingsDir, { recursive: true });
+
+  const existingSettings = await readJson(settingsPath);
+  const nextSettings = {
+    ...existingSettings,
+    mcpServers: {
+      ...(existingSettings.mcpServers ?? {}),
+      ...buildMcpServers(mcpEnv)
+    }
+  };
+
+  await fs.writeFile(settingsPath, `${JSON.stringify(nextSettings, null, 2)}\n`, 'utf8');
+}
+
+function buildMcpServers(mcpEnv) {
+  return {
+    auggie: {
+      type: 'stdio',
+      command: 'auggie',
+      args: ['--mcp', '--mcp-auto-workspace']
+    },
+    'grok-search': {
+      type: 'stdio',
+      ...buildUvxCommand(GROK_SEARCH_URL, 'grok-search'),
+      env: omitEmptyEnv(mcpEnv)
+    },
+    gemini: {
+      type: 'stdio',
+      ...buildUvxCommand(GEMINI_URL, 'geminimcp')
+    },
+    codex: {
+      type: 'stdio',
+      ...buildUvxCommand(CODEX_URL, 'codexmcp')
+    }
+  };
+}
+
+function buildUvxCommand(url, entry) {
+  if (process.platform === 'win32') {
+    return {
+      command: 'cmd',
+      args: ['/c', 'uvx', '--from', url, entry]
+    };
+  }
+
+  return {
+    command: 'uvx',
+    args: ['--from', url, entry]
+  };
+}
+
+function omitEmptyEnv(mcpEnv = {}) {
+  return Object.fromEntries(
+    Object.entries(mcpEnv).filter(([, value]) => typeof value === 'string' && value.trim() !== '')
+  );
+}
+
+async function readJson(filePath) {
+  try {
+    const content = await fs.readFile(filePath, 'utf8');
+
+    if (!content.trim()) {
+      return {};
+    }
+
+    return JSON.parse(content);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return {};
+    }
+
+    throw error;
+  }
+}