superpowers-mcp 6.3.3 → 6.3.5

package/out/setup-runner.js

@@ -0,0 +1,67 @@
+"use strict";var q=Object.create;var x=Object.defineProperty;var O=Object.getOwnPropertyDescriptor;var T=Object.getOwnPropertyNames;var N=Object.getPrototypeOf,H=Object.prototype.hasOwnProperty;var K=(t,e)=>{for(var s in e)x(t,s,{get:e[s],enumerable:!0})},_=(t,e,s,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let r of T(e))!H.call(t,r)&&r!==s&&x(t,r,{get:()=>e[r],enumerable:!(n=O(e,r))||n.enumerable});return t};var b=(t,e,s)=>(s=t!=null?q(N(t)):{},_(e||!t||!t.__esModule?x(s,"default",{value:t,enumerable:!0}):s,t)),L=t=>_(x({},"__esModule",{value:!0}),t);var F={};K(F,{HARNESS_CONFIGS:()=>k,isPlainObject:()=>P,runSetup:()=>U,runSetupCli:()=>W,safeWriteConfig:()=>E,stripJsonComments:()=>R,updateJsonConfig:()=>I,updateYamlConfig:()=>D});module.exports=L(F);var i=b(require("fs")),o=b(require("path")),A=b(require("os")),$=b(require("crypto")),k={copilot:{name:"GitHub Copilot (VS Code)",aliases:["vscode","code","copilot"],getConfigPath:(t,e,s,n)=>t==="win32"?o.join(s||o.join(e,"AppData","Roaming"),"Code","User","mcp.json"):t==="darwin"?o.join(e,"Library","Application Support","Code","User","mcp.json"):o.join(e,".config","Code","User","mcp.json"),type:"json-servers",defaultConfig:(t,e)=>({command:t,args:e,type:"stdio"})},"copilot-insiders":{name:"GitHub Copilot (VS Code Insiders)",aliases:["vscode-insiders","code-insiders","insiders","insider","vscode-insider","code-insider","copilot-insider"],getConfigPath:(t,e,s,n)=>t==="win32"?o.join(s||o.join(e,"AppData","Roaming"),"Code - Insiders","User","mcp.json"):t==="darwin"?o.join(e,"Library","Application Support","Code - Insiders","User","mcp.json"):o.join(e,".config","Code - Insiders","User","mcp.json"),type:"json-servers",defaultConfig:(t,e)=>({command:t,args:e,type:"stdio"})},cursor:{name:"Cursor",aliases:["cursor"],getConfigPath:(t,e)=>o.join(e,".cursor","mcp.json"),type:"json-mcpServers",defaultConfig:(t,e)=>({command:t,args:e})},hermes:{name:"Hermes Desktop / Agent",aliases:["hermes","hermes-desktop"],getConfigPath:(t,e,s,n)=>{if(t==="win32"){let r=n||o.join(e,"AppData","Local");return o.join(r,"hermes","config.yaml")}return o.join(e,".hermes","config.yaml")},type:"yaml",defaultConfig:(t,e)=>({command:t,args:e})},kimi:{name:"Kimi Work / Kimi Code",aliases:["kimi","kimi-work","kimi-code"],getConfigPath:(t,e)=>o.join(e,".kimi-code","mcp.json"),type:"json-mcpServers",defaultConfig:(t,e)=>({command:t,args:e})},claude:{name:"Claude Desktop",aliases:["claude","claude-desktop"],getConfigPath:(t,e,s)=>t==="win32"?o.join(s||o.join(e,"AppData","Roaming"),"Claude","claude_desktop_config.json"):t==="darwin"?o.join(e,"Library","Application Support","Claude","claude_desktop_config.json"):o.join(e,".config","Claude","claude_desktop_config.json"),type:"json-mcpServers",defaultConfig:(t,e)=>({command:t,args:e})},devin:{name:"Devin Desktop (formerly Windsurf)",aliases:["devin","devin-desktop","windsurf","codeium"],getConfigPath:(t,e)=>{let s=o.join(e,".config","devin","mcp_config.json");return i.existsSync(s)?s:o.join(e,".codeium","windsurf","mcp_config.json")},type:"json-mcpServers",defaultConfig:(t,e)=>({command:t,args:e})},antigravity:{name:"Antigravity (Google DeepMind)",aliases:["antigravity","agy","gemini"],getConfigPath:(t,e)=>o.join(e,".gemini","config","mcp_config.json"),type:"json-mcpServers",defaultConfig:(t,e)=>({command:t,args:e})},"pi-desktop":{name:"Pi Desktop / Pi Agent",aliases:["pi-desktop","pi","pi-agent"],getConfigPath:(t,e,s)=>{if(t==="win32"){let l=o.join(s||o.join(e,"AppData","Roaming"),".pi","agent","mcp.json");if(i.existsSync(l))return l;let a=o.join(e,".pi","agent","mcp.json");if(i.existsSync(a))return a;let g=o.join(e,".pi","mcp.json");return i.existsSync(g)?g:a}let n=o.join(e,".pi","agent","mcp.json");if(i.existsSync(n))return n;let r=o.join(e,".pi","mcp.json");return i.existsSync(r)?r:n},type:"json-mcpServers",defaultConfig:(t,e)=>({command:t,args:e})},qwenpaw:{name:"QwenPaw (Personal Agent Workstation)",aliases:["qwenpaw","qwen-paw","copaw"],getConfigPath:(t,e)=>{let s=o.join(e,".qwenpaw","config.json");if(i.existsSync(s))return s;let n=o.join(e,".copaw","config.json");return i.existsSync(n)?n:s},type:"json-mcpServers",defaultConfig:(t,e)=>({command:t,args:e})},cline:{name:"Cline (VS Code / CLI)",aliases:["cline","claude-dev"],getConfigPath:(t,e,s)=>{let n="";if(t==="win32"?n=o.join(s||o.join(e,"AppData","Roaming"),"Code","User","globalStorage","saoudrizwan.claude-dev","settings","cline_mcp_settings.json"):t==="darwin"?n=o.join(e,"Library","Application Support","Code","User","globalStorage","saoudrizwan.claude-dev","settings","cline_mcp_settings.json"):n=o.join(e,".config","Code","User","globalStorage","saoudrizwan.claude-dev","settings","cline_mcp_settings.json"),i.existsSync(n))return n;let r=o.join(e,".cline","data","settings","cline_mcp_settings.json");return i.existsSync(r)?r:n},type:"json-mcpServers",defaultConfig:(t,e)=>({command:t,args:e})},kilo:{name:"Kilo Code",aliases:["kilo","kilocode","kilo-code"],getConfigPath:(t,e)=>{let s=o.join(e,".config","kilo","kilo.jsonc");if(i.existsSync(s))return s;let n=o.join(e,".config","kilo","kilo.json");return i.existsSync(n)?n:s},type:"json-mcp",defaultConfig:(t,e)=>({type:"local",command:[t,...e],enabled:!0})},qoder:{name:"Qoder",aliases:["qoder"],getConfigPath:(t,e)=>o.join(e,".qoder","settings.json"),type:"json-mcpServers",defaultConfig:(t,e)=>({command:t,args:e})},kiro:{name:"Kiro",aliases:["kiro","kiro-code"],getConfigPath:(t,e)=>o.join(e,".kiro","settings","mcp.json"),type:"json-mcpServers",defaultConfig:(t,e)=>({command:t,args:e})},trae:{name:"Trae",aliases:["trae"],getConfigPath:(t,e,s)=>{if(t==="win32"){let n=o.join(s||o.join(e,"AppData","Roaming"),"Trae","User","mcp.json");if(i.existsSync(n))return n;let r=o.join(s||o.join(e,"AppData","Roaming"),"Trae CN","User","mcp.json");return i.existsSync(r)?r:n}else if(t==="darwin"){let n=o.join(e,"Library","Application Support","Trae","User","mcp.json");if(i.existsSync(n))return n;let r=o.join(e,"Library","Application Support","Trae CN","User","mcp.json");return i.existsSync(r)?r:n}else{let n=o.join(e,".config","Trae","User","mcp.json");if(i.existsSync(n))return n;let r=o.join(e,".config","Trae CN","User","mcp.json");return i.existsSync(r)?r:n}},type:"json-mcpServers",defaultConfig:(t,e)=>({command:t,args:e})}};function P(t){return Object.prototype.toString.call(t)==="[object Object]"}function R(t){return t.replace(/\/\*[\s\S]*?\*\//g,"").replace(/(^|[^:])\/\/.*$/gm,"$1").replace(/,\s*([\]}])/g,"$1")}function D(t,e,s,n=!1){let r=t?t.split(/\r?\n/):[];if(n){let p=[],f=!1,S=0,m=!1,h=0;for(let w=0;w<r.length;w++){let y=r[w],j=y.match(/^(\s*)mcp_servers:\s*$/);if(j){f=!0,S=j[1].length,p.push(y);continue}if(f){let C=y.match(/^(\s*)/)?.[1].length||0;if(y.trim()!==""&&C<=S)f=!1,m=!1;else{let v=y.match(/^(\s*)superpowers:\s*$/);if(v&&v[1].length>S){m=!0,h=v[1].length;continue}if(m){if(C>h||y.trim()==="")continue;m=!1}}}p.push(y)}return p.join(`
+`)}let l="  ";for(let p of r){let f=p.match(/^(\s+)[a-zA-Z0-9_-]+:/);if(f&&f[1].length>0){l=f[1];break}}let a=JSON.stringify(e),g=JSON.stringify(s),c=[`${l}superpowers:`,`${l}${l}command: ${a}`,`${l}${l}args: ${g}`];if(!t||t.trim()==="")return`mcp_servers:
+${c.join(`
+`)}
+`;let d=r.findIndex(p=>/^\s*mcp_servers:\s*$/.test(p));if(d===-1)return`${t.trimEnd()}
+
+mcp_servers:
+${c.join(`
+`)}
+`;let u=-1;for(let p=d+1;p<r.length;p++){let f=r[p];if(/^[^\s#]/.test(f))break;if(/^\s+superpowers:\s*$/.test(f)){u=p;break}}if(u!==-1){let p=r[u].match(/^(\s*)/)?.[1].length||2,f=u+1;for(;f<r.length;){let S=r[f];if((S.match(/^(\s*)/)?.[1].length||0)>p||S.trim()==="")f++;else break}return r.splice(u,f-u,...c),r.join(`
+`)}else return r.splice(d+1,0,...c),r.join(`
+`)}function I(t,e,s,n,r=!1,l){let a={};if(t&&t.trim()!=="")try{let d=JSON.parse(t);P(d)?a=d:a={}}catch{try{let u=R(t),p=JSON.parse(u);P(p)?a=p:a={}}catch(u){let p=u instanceof Error?u.message:String(u);throw new Error(`Failed to parse existing JSON: ${p}`)}}let g="mcpServers";e==="json-servers"?g="servers":e==="json-mcp"&&(g="mcp"),P(a[g])||(a[g]={});let c=a[g];return r?delete c.superpowers:l?c.superpowers=l:e==="json-servers"?c.superpowers={command:s,args:n,type:"stdio"}:e==="json-mcp"?c.superpowers={type:"local",command:[s,...n],enabled:!0}:c.superpowers={command:s,args:n},JSON.stringify(a,null,2)+`
+`}function E(t,e,s=!1){let n=t;try{let c=i.lstatSync(t,{throwIfNoEntry:!1});if(c&&c.isSymbolicLink())try{n=i.realpathSync(t)}catch{let u=i.readlinkSync(t);n=o.resolve(o.dirname(t),u)}}catch{}let r=o.dirname(n);i.existsSync(r)||i.mkdirSync(r,{recursive:!0,mode:448});let l=384;if(i.existsSync(n)){try{l=i.statSync(n).mode}catch{}if(s){let c=i.readFileSync(n,"utf8"),d=`${n}.${Date.now()}.bak`;try{i.writeFileSync(d,c,{encoding:"utf8",mode:l})}catch(u){let p=u instanceof Error?u.message:String(u);throw new Error(`Failed to create safe backup before write: ${p}`)}}}let a=$.randomBytes(8).toString("hex"),g=o.join(r,`.tmp.${o.basename(n)}.${process.pid}.${a}`);try{i.writeFileSync(g,e,{encoding:"utf8",mode:l,flag:"wx"}),i.renameSync(g,n)}catch(c){try{i.existsSync(g)&&i.unlinkSync(g)}catch{}throw c}}async function U(t={}){let e=t.platform||A.platform(),s=t.homeDir||A.homedir(),n=t.appData||process.env.APPDATA,r=t.localAppData||process.env.LOCALAPPDATA,l=!!t.dryRun,a=!!t.remove,g=!!t.bun,c=t.target?t.target.toLowerCase():null,d=g?"bunx":"npx",u=["-y","superpowers-mcp"],p=[];if(!c)throw new Error(`No target client specified. Please specify which client to configure using --target <${Object.keys(k).join("|")}>.`);let f=Object.keys(k).find(m=>m===c||k[m].aliases.includes(c));if(!f)throw new Error(`Unknown harness target: "${c}". Supported targets: ${Object.keys(k).join(", ")}`);let S=[f];for(let m of S){let h=k[m],w=h.getConfigPath(e,s,n,r),y=i.existsSync(w);if(a&&!y){p.push({target:m,name:h.name,path:w,status:"up-to-date",message:"Already not configured (file does not exist)"});continue}try{let j="";y&&(j=i.readFileSync(w,"utf8"));let C="";if(h.type==="yaml")C=D(j,d,u,a);else{let v=typeof h.defaultConfig=="function"?h.defaultConfig(d,u):void 0;C=I(j,h.type,d,u,a,v)}if(j.trim()===C.trim()&&y){p.push({target:m,name:h.name,path:w,status:"up-to-date",message:a?"Already not configured":"Already configured and up-to-date"});continue}l||E(w,C,!!t.backup),p.push({target:m,name:h.name,path:w,status:a?"removed":y?"updated":"created",message:l?`[Dry Run] Would ${a?"remove from":y?"update":"create"} ${w}`:`Successfully ${a?"removed from":y?"updated":"configured"}!`})}catch(j){let C=j instanceof Error?j.message:String(j);p.push({target:m,name:h.name,path:w,status:"error",message:C})}}return p}async function W(t=process.argv.slice(2)){let e={dryRun:!1,remove:!1,bun:!1,backup:!1,target:null};for(let s=0;s<t.length;s++){let n=t[s];if(!(n==="setup"||n==="--setup"))if(n==="--dry-run")e.dryRun=!0;else if(n==="--remove"||n==="--uninstall")e.remove=!0;else if(n==="--bun")e.bun=!0;else if(n==="--backup")e.backup=!0;else if(n==="--target"||n==="-t"){let r=t[s+1];(!r||r.startsWith("-"))&&(console.error(`\u274C Error: Missing value for --target flag.
+`),process.exit(1)),e.target=t[++s]}else if(n.startsWith("--target=")){let r=n.split("=")[1];r||(console.error(`\u274C Error: Missing value for --target flag.
+`),process.exit(1)),e.target=r}else if(n==="--help"||n==="-h"){M();return}else!n.startsWith("-")&&!e.target&&n!=="setup"?e.target=n:n.startsWith("-")&&(console.error(`\u274C Error: Unknown option "${n}". Use --help for usage.
+`),process.exit(1))}if(console.log(`
+========================================================`),console.log("\u26A1 Superpowers MCP - Targeted Client Setup"),console.log(`========================================================
+`),!e.target){console.log(`Please select which AI Agent client you would like to configure:
+`),console.log("  npx -y superpowers-mcp setup --target antigravity # Antigravity (~/.gemini/config/mcp_config.json)"),console.log("  npx -y superpowers-mcp setup --target pi-desktop  # Pi Desktop / Pi Agent (~/.pi/agent/mcp.json)"),console.log("  npx -y superpowers-mcp setup --target cursor     # Cursor (~/.cursor/mcp.json)"),console.log("  npx -y superpowers-mcp setup --target copilot    # GitHub Copilot (VS Code mcp.json)"),console.log("  npx -y superpowers-mcp setup --target copilot-insiders # GitHub Copilot (VS Code Insiders mcp.json)"),console.log("  npx -y superpowers-mcp setup --target hermes     # Hermes Desktop / Agent"),console.log("  npx -y superpowers-mcp setup --target kimi       # Kimi Work / Kimi Code"),console.log("  npx -y superpowers-mcp setup --target claude     # Claude Desktop"),console.log("  npx -y superpowers-mcp setup --target devin      # Devin Desktop (formerly Windsurf)"),console.log("  npx -y superpowers-mcp setup --target qwenpaw    # QwenPaw / CoPaw (~/.qwenpaw/config.json)"),console.log("  npx -y superpowers-mcp setup --target cline      # Cline (~/.../cline_mcp_settings.json)"),console.log("  npx -y superpowers-mcp setup --target kilo       # Kilo Code (~/.config/kilo/kilo.jsonc)"),console.log("  npx -y superpowers-mcp setup --target qoder      # Qoder (~/.qoder/settings.json)"),console.log("  npx -y superpowers-mcp setup --target kiro       # Kiro (~/.kiro/settings/mcp.json)"),console.log(`  npx -y superpowers-mcp setup --target trae       # Trae (~/.../Trae/User/mcp.json)
+`),console.log("\u{1F4A1} Tip:"),console.log("   You can run this setup command from ANY folder on your system."),console.log(`   It automatically targets your global config files (~/...) without needing to clone this repo.
+`),console.log("\u{1F4A1} Privacy & Safety:"),console.log("   Superpowers MCP only configures the specific client you explicitly choose."),console.log(`   It will NEVER silently scan or modify unselected environments.
+`);return}try{let s=await U(e),n=0,r=0,l=0;for(let a of s){let g=a.status==="created"||a.status==="updated"||a.status==="removed"?"\u2705":a.status==="up-to-date"?"\u2728":a.status==="skipped"?"\u23ED\uFE0F ":"\u274C";console.log(`${g} [${a.name}] (${a.status})`),console.log(`   Path: ${a.path}`),console.log(`   Info: ${a.message}
+`),a.status==="created"||a.status==="updated"||a.status==="up-to-date"||a.status==="removed"?n++:a.status==="skipped"?r++:a.status==="error"&&l++}console.log("--------------------------------------------------------"),l>0&&(console.error(`\u26A0\uFE0F Setup finished with errors: ${l} failure(s), ${n} succeeded.`),process.exit(1)),console.log(`\u{1F389} Setup complete! ${n} environment(s) ready.`)}catch(s){let n=s instanceof Error?s.message:String(s);console.error(`\u274C Setup failed: ${n}
+`),process.exit(1)}}function M(){console.log(`
+Superpowers MCP - Targeted Global Setup
+
+Usage:
+  npx -y superpowers-mcp setup --target <name> [options]
+
+Options:
+  --target, -t <name>   Configure specific harness (Required):
+                        antigravity (agy, gemini), pi-desktop (pi, pi-agent), cursor,
+                        copilot (vscode), copilot-insiders (vscode-insiders, code-insiders, insiders),
+                        hermes, kimi, claude, devin (windsurf),
+                        qwenpaw (qwen-paw, copaw), cline (claude-dev), kilo (kilocode),
+                        qoder, kiro (kiro-code), trae
+  --bun                 Use "bunx" instead of "npx" in server commands
+  --backup              Create a timestamped .bak backup before modifying (Default: false, zero-pollution)
+  --remove              Remove superpowers MCP configuration from target
+  --dry-run             Preview changes without writing files
+  --help, -h            Show this help message
+
+Examples:
+  npx -y superpowers-mcp setup --target antigravity # Configure Antigravity only
+  npx -y superpowers-mcp setup --target pi-desktop  # Configure Pi Desktop / Pi Agent only
+  npx -y superpowers-mcp setup --target cursor      # Configure Cursor only
+  npx -y superpowers-mcp setup --target copilot     # Configure GitHub Copilot (VS Code) only
+  npx -y superpowers-mcp setup --target copilot-insiders # Configure GitHub Copilot (VS Code Insiders) only
+  npx -y superpowers-mcp setup --target hermes      # Configure Hermes Desktop only
+  npx -y superpowers-mcp setup --target kimi        # Configure Kimi Work only
+  npx -y superpowers-mcp setup --target claude      # Configure Claude Desktop only
+  npx -y superpowers-mcp setup --target devin       # Configure Devin Desktop (Windsurf) only
+  npx -y superpowers-mcp setup --target qwenpaw     # Configure QwenPaw only
+  npx -y superpowers-mcp setup --target cline       # Configure Cline only
+  npx -y superpowers-mcp setup --target kilo        # Configure Kilo Code only
+  npx -y superpowers-mcp setup --target qoder       # Configure Qoder only
+  npx -y superpowers-mcp setup --target kiro        # Configure Kiro only
+  npx -y superpowers-mcp setup --target trae        # Configure Trae only
+
+Any Directory:
+  You can run this command from ANY directory on your machine.
+  It automatically resolves global configuration paths based on your user home folder.
+
+Privacy & Safety:
+  Superpowers MCP only touches the client you explicitly choose.
+  It never bulk-modifies your environment without your consent.
+`)}0&&(module.exports={HARNESS_CONFIGS,isPlainObject,runSetup,runSetupCli,safeWriteConfig,stripJsonComments,updateJsonConfig,updateYamlConfig});

package/out/setup.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+"use strict";var O=Object.create;var x=Object.defineProperty;var T=Object.getOwnPropertyDescriptor;var N=Object.getOwnPropertyNames;var H=Object.getPrototypeOf,K=Object.prototype.hasOwnProperty;var L=(t,e)=>{for(var s in e)x(t,s,{get:e[s],enumerable:!0})},$=(t,e,s,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let r of N(e))!K.call(t,r)&&r!==s&&x(t,r,{get:()=>e[r],enumerable:!(n=T(e,r))||n.enumerable});return t};var b=(t,e,s)=>(s=t!=null?O(H(t)):{},$(e||!t||!t.__esModule?x(s,"default",{value:t,enumerable:!0}):s,t)),W=t=>$(x({},"__esModule",{value:!0}),t);var M={};L(M,{HARNESS_CONFIGS:()=>k,isPlainObject:()=>P,runSetup:()=>q,runSetupCli:()=>_,safeWriteConfig:()=>U,stripJsonComments:()=>D,updateJsonConfig:()=>I,updateYamlConfig:()=>E});module.exports=W(M);var i=b(require("fs")),o=b(require("path")),A=b(require("os")),R=b(require("crypto")),k={copilot:{name:"GitHub Copilot (VS Code)",aliases:["vscode","code","copilot"],getConfigPath:(t,e,s,n)=>t==="win32"?o.join(s||o.join(e,"AppData","Roaming"),"Code","User","mcp.json"):t==="darwin"?o.join(e,"Library","Application Support","Code","User","mcp.json"):o.join(e,".config","Code","User","mcp.json"),type:"json-servers",defaultConfig:(t,e)=>({command:t,args:e,type:"stdio"})},"copilot-insiders":{name:"GitHub Copilot (VS Code Insiders)",aliases:["vscode-insiders","code-insiders","insiders","insider","vscode-insider","code-insider","copilot-insider"],getConfigPath:(t,e,s,n)=>t==="win32"?o.join(s||o.join(e,"AppData","Roaming"),"Code - Insiders","User","mcp.json"):t==="darwin"?o.join(e,"Library","Application Support","Code - Insiders","User","mcp.json"):o.join(e,".config","Code - Insiders","User","mcp.json"),type:"json-servers",defaultConfig:(t,e)=>({command:t,args:e,type:"stdio"})},cursor:{name:"Cursor",aliases:["cursor"],getConfigPath:(t,e)=>o.join(e,".cursor","mcp.json"),type:"json-mcpServers",defaultConfig:(t,e)=>({command:t,args:e})},hermes:{name:"Hermes Desktop / Agent",aliases:["hermes","hermes-desktop"],getConfigPath:(t,e,s,n)=>{if(t==="win32"){let r=n||o.join(e,"AppData","Local");return o.join(r,"hermes","config.yaml")}return o.join(e,".hermes","config.yaml")},type:"yaml",defaultConfig:(t,e)=>({command:t,args:e})},kimi:{name:"Kimi Work / Kimi Code",aliases:["kimi","kimi-work","kimi-code"],getConfigPath:(t,e)=>o.join(e,".kimi-code","mcp.json"),type:"json-mcpServers",defaultConfig:(t,e)=>({command:t,args:e})},claude:{name:"Claude Desktop",aliases:["claude","claude-desktop"],getConfigPath:(t,e,s)=>t==="win32"?o.join(s||o.join(e,"AppData","Roaming"),"Claude","claude_desktop_config.json"):t==="darwin"?o.join(e,"Library","Application Support","Claude","claude_desktop_config.json"):o.join(e,".config","Claude","claude_desktop_config.json"),type:"json-mcpServers",defaultConfig:(t,e)=>({command:t,args:e})},devin:{name:"Devin Desktop (formerly Windsurf)",aliases:["devin","devin-desktop","windsurf","codeium"],getConfigPath:(t,e)=>{let s=o.join(e,".config","devin","mcp_config.json");return i.existsSync(s)?s:o.join(e,".codeium","windsurf","mcp_config.json")},type:"json-mcpServers",defaultConfig:(t,e)=>({command:t,args:e})},antigravity:{name:"Antigravity (Google DeepMind)",aliases:["antigravity","agy","gemini"],getConfigPath:(t,e)=>o.join(e,".gemini","config","mcp_config.json"),type:"json-mcpServers",defaultConfig:(t,e)=>({command:t,args:e})},"pi-desktop":{name:"Pi Desktop / Pi Agent",aliases:["pi-desktop","pi","pi-agent"],getConfigPath:(t,e,s)=>{if(t==="win32"){let l=o.join(s||o.join(e,"AppData","Roaming"),".pi","agent","mcp.json");if(i.existsSync(l))return l;let a=o.join(e,".pi","agent","mcp.json");if(i.existsSync(a))return a;let g=o.join(e,".pi","mcp.json");return i.existsSync(g)?g:a}let n=o.join(e,".pi","agent","mcp.json");if(i.existsSync(n))return n;let r=o.join(e,".pi","mcp.json");return i.existsSync(r)?r:n},type:"json-mcpServers",defaultConfig:(t,e)=>({command:t,args:e})},qwenpaw:{name:"QwenPaw (Personal Agent Workstation)",aliases:["qwenpaw","qwen-paw","copaw"],getConfigPath:(t,e)=>{let s=o.join(e,".qwenpaw","config.json");if(i.existsSync(s))return s;let n=o.join(e,".copaw","config.json");return i.existsSync(n)?n:s},type:"json-mcpServers",defaultConfig:(t,e)=>({command:t,args:e})},cline:{name:"Cline (VS Code / CLI)",aliases:["cline","claude-dev"],getConfigPath:(t,e,s)=>{let n="";if(t==="win32"?n=o.join(s||o.join(e,"AppData","Roaming"),"Code","User","globalStorage","saoudrizwan.claude-dev","settings","cline_mcp_settings.json"):t==="darwin"?n=o.join(e,"Library","Application Support","Code","User","globalStorage","saoudrizwan.claude-dev","settings","cline_mcp_settings.json"):n=o.join(e,".config","Code","User","globalStorage","saoudrizwan.claude-dev","settings","cline_mcp_settings.json"),i.existsSync(n))return n;let r=o.join(e,".cline","data","settings","cline_mcp_settings.json");return i.existsSync(r)?r:n},type:"json-mcpServers",defaultConfig:(t,e)=>({command:t,args:e})},kilo:{name:"Kilo Code",aliases:["kilo","kilocode","kilo-code"],getConfigPath:(t,e)=>{let s=o.join(e,".config","kilo","kilo.jsonc");if(i.existsSync(s))return s;let n=o.join(e,".config","kilo","kilo.json");return i.existsSync(n)?n:s},type:"json-mcp",defaultConfig:(t,e)=>({type:"local",command:[t,...e],enabled:!0})},qoder:{name:"Qoder",aliases:["qoder"],getConfigPath:(t,e)=>o.join(e,".qoder","settings.json"),type:"json-mcpServers",defaultConfig:(t,e)=>({command:t,args:e})},kiro:{name:"Kiro",aliases:["kiro","kiro-code"],getConfigPath:(t,e)=>o.join(e,".kiro","settings","mcp.json"),type:"json-mcpServers",defaultConfig:(t,e)=>({command:t,args:e})},trae:{name:"Trae",aliases:["trae"],getConfigPath:(t,e,s)=>{if(t==="win32"){let n=o.join(s||o.join(e,"AppData","Roaming"),"Trae","User","mcp.json");if(i.existsSync(n))return n;let r=o.join(s||o.join(e,"AppData","Roaming"),"Trae CN","User","mcp.json");return i.existsSync(r)?r:n}else if(t==="darwin"){let n=o.join(e,"Library","Application Support","Trae","User","mcp.json");if(i.existsSync(n))return n;let r=o.join(e,"Library","Application Support","Trae CN","User","mcp.json");return i.existsSync(r)?r:n}else{let n=o.join(e,".config","Trae","User","mcp.json");if(i.existsSync(n))return n;let r=o.join(e,".config","Trae CN","User","mcp.json");return i.existsSync(r)?r:n}},type:"json-mcpServers",defaultConfig:(t,e)=>({command:t,args:e})}};function P(t){return Object.prototype.toString.call(t)==="[object Object]"}function D(t){return t.replace(/\/\*[\s\S]*?\*\//g,"").replace(/(^|[^:])\/\/.*$/gm,"$1").replace(/,\s*([\]}])/g,"$1")}function E(t,e,s,n=!1){let r=t?t.split(/\r?\n/):[];if(n){let p=[],f=!1,S=0,m=!1,h=0;for(let w=0;w<r.length;w++){let y=r[w],j=y.match(/^(\s*)mcp_servers:\s*$/);if(j){f=!0,S=j[1].length,p.push(y);continue}if(f){let C=y.match(/^(\s*)/)?.[1].length||0;if(y.trim()!==""&&C<=S)f=!1,m=!1;else{let v=y.match(/^(\s*)superpowers:\s*$/);if(v&&v[1].length>S){m=!0,h=v[1].length;continue}if(m){if(C>h||y.trim()==="")continue;m=!1}}}p.push(y)}return p.join(`
+`)}let l="  ";for(let p of r){let f=p.match(/^(\s+)[a-zA-Z0-9_-]+:/);if(f&&f[1].length>0){l=f[1];break}}let a=JSON.stringify(e),g=JSON.stringify(s),c=[`${l}superpowers:`,`${l}${l}command: ${a}`,`${l}${l}args: ${g}`];if(!t||t.trim()==="")return`mcp_servers:
+${c.join(`
+`)}
+`;let d=r.findIndex(p=>/^\s*mcp_servers:\s*$/.test(p));if(d===-1)return`${t.trimEnd()}
+
+mcp_servers:
+${c.join(`
+`)}
+`;let u=-1;for(let p=d+1;p<r.length;p++){let f=r[p];if(/^[^\s#]/.test(f))break;if(/^\s+superpowers:\s*$/.test(f)){u=p;break}}if(u!==-1){let p=r[u].match(/^(\s*)/)?.[1].length||2,f=u+1;for(;f<r.length;){let S=r[f];if((S.match(/^(\s*)/)?.[1].length||0)>p||S.trim()==="")f++;else break}return r.splice(u,f-u,...c),r.join(`
+`)}else return r.splice(d+1,0,...c),r.join(`
+`)}function I(t,e,s,n,r=!1,l){let a={};if(t&&t.trim()!=="")try{let d=JSON.parse(t);P(d)?a=d:a={}}catch{try{let u=D(t),p=JSON.parse(u);P(p)?a=p:a={}}catch(u){let p=u instanceof Error?u.message:String(u);throw new Error(`Failed to parse existing JSON: ${p}`)}}let g="mcpServers";e==="json-servers"?g="servers":e==="json-mcp"&&(g="mcp"),P(a[g])||(a[g]={});let c=a[g];return r?delete c.superpowers:l?c.superpowers=l:e==="json-servers"?c.superpowers={command:s,args:n,type:"stdio"}:e==="json-mcp"?c.superpowers={type:"local",command:[s,...n],enabled:!0}:c.superpowers={command:s,args:n},JSON.stringify(a,null,2)+`
+`}function U(t,e,s=!1){let n=t;try{let c=i.lstatSync(t,{throwIfNoEntry:!1});if(c&&c.isSymbolicLink())try{n=i.realpathSync(t)}catch{let u=i.readlinkSync(t);n=o.resolve(o.dirname(t),u)}}catch{}let r=o.dirname(n);i.existsSync(r)||i.mkdirSync(r,{recursive:!0,mode:448});let l=384;if(i.existsSync(n)){try{l=i.statSync(n).mode}catch{}if(s){let c=i.readFileSync(n,"utf8"),d=`${n}.${Date.now()}.bak`;try{i.writeFileSync(d,c,{encoding:"utf8",mode:l})}catch(u){let p=u instanceof Error?u.message:String(u);throw new Error(`Failed to create safe backup before write: ${p}`)}}}let a=R.randomBytes(8).toString("hex"),g=o.join(r,`.tmp.${o.basename(n)}.${process.pid}.${a}`);try{i.writeFileSync(g,e,{encoding:"utf8",mode:l,flag:"wx"}),i.renameSync(g,n)}catch(c){try{i.existsSync(g)&&i.unlinkSync(g)}catch{}throw c}}async function q(t={}){let e=t.platform||A.platform(),s=t.homeDir||A.homedir(),n=t.appData||process.env.APPDATA,r=t.localAppData||process.env.LOCALAPPDATA,l=!!t.dryRun,a=!!t.remove,g=!!t.bun,c=t.target?t.target.toLowerCase():null,d=g?"bunx":"npx",u=["-y","superpowers-mcp"],p=[];if(!c)throw new Error(`No target client specified. Please specify which client to configure using --target <${Object.keys(k).join("|")}>.`);let f=Object.keys(k).find(m=>m===c||k[m].aliases.includes(c));if(!f)throw new Error(`Unknown harness target: "${c}". Supported targets: ${Object.keys(k).join(", ")}`);let S=[f];for(let m of S){let h=k[m],w=h.getConfigPath(e,s,n,r),y=i.existsSync(w);if(a&&!y){p.push({target:m,name:h.name,path:w,status:"up-to-date",message:"Already not configured (file does not exist)"});continue}try{let j="";y&&(j=i.readFileSync(w,"utf8"));let C="";if(h.type==="yaml")C=E(j,d,u,a);else{let v=typeof h.defaultConfig=="function"?h.defaultConfig(d,u):void 0;C=I(j,h.type,d,u,a,v)}if(j.trim()===C.trim()&&y){p.push({target:m,name:h.name,path:w,status:"up-to-date",message:a?"Already not configured":"Already configured and up-to-date"});continue}l||U(w,C,!!t.backup),p.push({target:m,name:h.name,path:w,status:a?"removed":y?"updated":"created",message:l?`[Dry Run] Would ${a?"remove from":y?"update":"create"} ${w}`:`Successfully ${a?"removed from":y?"updated":"configured"}!`})}catch(j){let C=j instanceof Error?j.message:String(j);p.push({target:m,name:h.name,path:w,status:"error",message:C})}}return p}async function _(t=process.argv.slice(2)){let e={dryRun:!1,remove:!1,bun:!1,backup:!1,target:null};for(let s=0;s<t.length;s++){let n=t[s];if(!(n==="setup"||n==="--setup"))if(n==="--dry-run")e.dryRun=!0;else if(n==="--remove"||n==="--uninstall")e.remove=!0;else if(n==="--bun")e.bun=!0;else if(n==="--backup")e.backup=!0;else if(n==="--target"||n==="-t"){let r=t[s+1];(!r||r.startsWith("-"))&&(console.error(`\u274C Error: Missing value for --target flag.
+`),process.exit(1)),e.target=t[++s]}else if(n.startsWith("--target=")){let r=n.split("=")[1];r||(console.error(`\u274C Error: Missing value for --target flag.
+`),process.exit(1)),e.target=r}else if(n==="--help"||n==="-h"){F();return}else!n.startsWith("-")&&!e.target&&n!=="setup"?e.target=n:n.startsWith("-")&&(console.error(`\u274C Error: Unknown option "${n}". Use --help for usage.
+`),process.exit(1))}if(console.log(`
+========================================================`),console.log("\u26A1 Superpowers MCP - Targeted Client Setup"),console.log(`========================================================
+`),!e.target){console.log(`Please select which AI Agent client you would like to configure:
+`),console.log("  npx -y superpowers-mcp setup --target antigravity # Antigravity (~/.gemini/config/mcp_config.json)"),console.log("  npx -y superpowers-mcp setup --target pi-desktop  # Pi Desktop / Pi Agent (~/.pi/agent/mcp.json)"),console.log("  npx -y superpowers-mcp setup --target cursor     # Cursor (~/.cursor/mcp.json)"),console.log("  npx -y superpowers-mcp setup --target copilot    # GitHub Copilot (VS Code mcp.json)"),console.log("  npx -y superpowers-mcp setup --target copilot-insiders # GitHub Copilot (VS Code Insiders mcp.json)"),console.log("  npx -y superpowers-mcp setup --target hermes     # Hermes Desktop / Agent"),console.log("  npx -y superpowers-mcp setup --target kimi       # Kimi Work / Kimi Code"),console.log("  npx -y superpowers-mcp setup --target claude     # Claude Desktop"),console.log("  npx -y superpowers-mcp setup --target devin      # Devin Desktop (formerly Windsurf)"),console.log("  npx -y superpowers-mcp setup --target qwenpaw    # QwenPaw / CoPaw (~/.qwenpaw/config.json)"),console.log("  npx -y superpowers-mcp setup --target cline      # Cline (~/.../cline_mcp_settings.json)"),console.log("  npx -y superpowers-mcp setup --target kilo       # Kilo Code (~/.config/kilo/kilo.jsonc)"),console.log("  npx -y superpowers-mcp setup --target qoder      # Qoder (~/.qoder/settings.json)"),console.log("  npx -y superpowers-mcp setup --target kiro       # Kiro (~/.kiro/settings/mcp.json)"),console.log(`  npx -y superpowers-mcp setup --target trae       # Trae (~/.../Trae/User/mcp.json)
+`),console.log("\u{1F4A1} Tip:"),console.log("   You can run this setup command from ANY folder on your system."),console.log(`   It automatically targets your global config files (~/...) without needing to clone this repo.
+`),console.log("\u{1F4A1} Privacy & Safety:"),console.log("   Superpowers MCP only configures the specific client you explicitly choose."),console.log(`   It will NEVER silently scan or modify unselected environments.
+`);return}try{let s=await q(e),n=0,r=0,l=0;for(let a of s){let g=a.status==="created"||a.status==="updated"||a.status==="removed"?"\u2705":a.status==="up-to-date"?"\u2728":a.status==="skipped"?"\u23ED\uFE0F ":"\u274C";console.log(`${g} [${a.name}] (${a.status})`),console.log(`   Path: ${a.path}`),console.log(`   Info: ${a.message}
+`),a.status==="created"||a.status==="updated"||a.status==="up-to-date"||a.status==="removed"?n++:a.status==="skipped"?r++:a.status==="error"&&l++}console.log("--------------------------------------------------------"),l>0&&(console.error(`\u26A0\uFE0F Setup finished with errors: ${l} failure(s), ${n} succeeded.`),process.exit(1)),console.log(`\u{1F389} Setup complete! ${n} environment(s) ready.`)}catch(s){let n=s instanceof Error?s.message:String(s);console.error(`\u274C Setup failed: ${n}
+`),process.exit(1)}}function F(){console.log(`
+Superpowers MCP - Targeted Global Setup
+
+Usage:
+  npx -y superpowers-mcp setup --target <name> [options]
+
+Options:
+  --target, -t <name>   Configure specific harness (Required):
+                        antigravity (agy, gemini), pi-desktop (pi, pi-agent), cursor,
+                        copilot (vscode), copilot-insiders (vscode-insiders, code-insiders, insiders),
+                        hermes, kimi, claude, devin (windsurf),
+                        qwenpaw (qwen-paw, copaw), cline (claude-dev), kilo (kilocode),
+                        qoder, kiro (kiro-code), trae
+  --bun                 Use "bunx" instead of "npx" in server commands
+  --backup              Create a timestamped .bak backup before modifying (Default: false, zero-pollution)
+  --remove              Remove superpowers MCP configuration from target
+  --dry-run             Preview changes without writing files
+  --help, -h            Show this help message
+
+Examples:
+  npx -y superpowers-mcp setup --target antigravity # Configure Antigravity only
+  npx -y superpowers-mcp setup --target pi-desktop  # Configure Pi Desktop / Pi Agent only
+  npx -y superpowers-mcp setup --target cursor      # Configure Cursor only
+  npx -y superpowers-mcp setup --target copilot     # Configure GitHub Copilot (VS Code) only
+  npx -y superpowers-mcp setup --target copilot-insiders # Configure GitHub Copilot (VS Code Insiders) only
+  npx -y superpowers-mcp setup --target hermes      # Configure Hermes Desktop only
+  npx -y superpowers-mcp setup --target kimi        # Configure Kimi Work only
+  npx -y superpowers-mcp setup --target claude      # Configure Claude Desktop only
+  npx -y superpowers-mcp setup --target devin       # Configure Devin Desktop (Windsurf) only
+  npx -y superpowers-mcp setup --target qwenpaw     # Configure QwenPaw only
+  npx -y superpowers-mcp setup --target cline       # Configure Cline only
+  npx -y superpowers-mcp setup --target kilo        # Configure Kilo Code only
+  npx -y superpowers-mcp setup --target qoder       # Configure Qoder only
+  npx -y superpowers-mcp setup --target kiro        # Configure Kiro only
+  npx -y superpowers-mcp setup --target trae        # Configure Trae only
+
+Any Directory:
+  You can run this command from ANY directory on your machine.
+  It automatically resolves global configuration paths based on your user home folder.
+
+Privacy & Safety:
+  Superpowers MCP only touches the client you explicitly choose.
+  It never bulk-modifies your environment without your consent.
+`)}_().catch(t=>{let e=t instanceof Error?t.message:String(t);console.error(`\u274C Fatal error: ${e}`),process.exit(1)});0&&(module.exports={HARNESS_CONFIGS,isPlainObject,runSetup,runSetupCli,safeWriteConfig,stripJsonComments,updateJsonConfig,updateYamlConfig});

package/package.json

@@ -2,7 +2,7 @@
   "name": "superpowers-mcp",
   "displayName": "Superpowers MCP",
   "description": "Superpowers skills library (TDD, debugging, collaboration workflows) as an MCP server for VSCode and Antigravity",
-  "version": "6.3.3",
+  "version": "6.3.5",
   "publisher": "superpowers",
   "license": "MIT",
   "repository": {
@@ -23,22 +23,27 @@
     "agent"
   ],
   "bin": {
-    "superpowers-mcp": "./out/server.js"
+    "superpowers-mcp": "./out/server.js",
+    "superpowers-setup": "./out/setup.js"
   },
   "files": [
     "out/server.js",
+    "out/setup.js",
+    "out/setup-runner.js",
+    "scripts",
     "skills"
   ],
   "overrides": {
-    "@hono/node-server": "2.0.11",
-    "fast-uri": "4.1.2",
-    "hono": "4.13.0"
+    "@hono/node-server": "^2.1.1",
+    "fast-uri": "^4.1.3",
+    "hono": "^4.13.7",
+    "qs": "^6.16.0"
   },
   "scripts": {
     "build": "node esbuild.js --production",
     "watch": "node esbuild.js --watch",
     "pretest": "npm run build",
-    "test": "node tests/edge_cases_test.js && node tests/run_test.js && node tests/brainstorm_server_test.js",
+    "test": "node tests/edge_cases_test.js && node tests/run_test.js && node tests/brainstorm_server_test.js && node tests/prompts_compositions_test.js && node tests/setup_test.js",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {

package/scripts/copy-skills.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * Copy skills from the parent superpowers repository into the extension's
+ * own skills/ directory so they are included in the .vsix package.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const src = path.join(__dirname, "..", "..", "target-learn", "skills");
+const dest = path.join(__dirname, "..", "skills");
+
+function copyRecursive(from, to) {
+    try {
+        if (!fs.existsSync(from)) {
+            console.error(`Source not found: ${from}`);
+            process.exit(1);
+        }
+
+        if (!fs.existsSync(to)) {
+            fs.mkdirSync(to, { recursive: true });
+        }
+
+        const entries = fs.readdirSync(from, { withFileTypes: true });
+        for (const entry of entries) {
+            const srcPath = path.join(from, entry.name);
+            const destPath = path.join(to, entry.name);
+
+            // 防禦性設計：過濾符號連結防止無限迴圈或任意讀寫
+            if (entry.isSymbolicLink()) {
+                console.warn(`Warning: Skipping symbolic link: ${srcPath}`);
+                continue;
+            }
+
+            if (entry.isDirectory()) {
+                copyRecursive(srcPath, destPath);
+            } else if (entry.isFile()) {
+                fs.copyFileSync(srcPath, destPath);
+            }
+        }
+    } catch (err) {
+        console.error(`Fatal error copying files from "${from}" to "${to}":`, err);
+        process.exit(1);
+    }
+}
+
+copyRecursive(src, dest);
+console.log(`Skills copied from ${src} to ${dest}`);

package/scripts/install.ps1

@@ -0,0 +1,59 @@
+# ==============================================================================
+# Superpowers MCP - One-Click Global Installer (Windows PowerShell)
+# Usage:
+#   irm https://raw.githubusercontent.com/Poseidoncode/superpowers-mcp/main/scripts/install.ps1 | iex
+#   & ([scriptblock]::Create((irm https://raw.githubusercontent.com/Poseidoncode/superpowers-mcp/main/scripts/install.ps1))) -Target cursor
+#   .\scripts\install.ps1 -Target cursor
+# ==============================================================================
+
+[CmdletBinding()]
+param (
+    [string]$Target = "",
+    [switch]$Bun,
+    [switch]$Remove,
+    [switch]$Backup,
+    [switch]$DryRun
+)
+
+$ErrorActionPreference = "Stop"
+
+Write-Host ""
+Write-Host "========================================================" -ForegroundColor Cyan
+Write-Host "⚡ Superpowers MCP - One-Click Global Setup (Windows)" -ForegroundColor Cyan
+Write-Host "========================================================" -ForegroundColor Cyan
+Write-Host ""
+
+$argsList = @()
+if ($Target) { $argsList += "--target", $Target }
+if ($Bun) { $argsList += "--bun" }
+if ($Remove) { $argsList += "--remove" }
+if ($Backup) { $argsList += "--backup" }
+if ($DryRun) { $argsList += "--dry-run" }
+
+# Check for local setup.js
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path -ErrorAction SilentlyContinue
+$localSetup = if ($scriptDir) { Join-Path $scriptDir "setup.js" } else { "" }
+
+if ($localSetup -and (Test-Path $localSetup) -and (Get-Command node -ErrorAction SilentlyContinue)) {
+    Write-Host "📦 Using local setup engine..." -ForegroundColor Green
+    & node $localSetup @argsList
+    exit $LASTEXITCODE
+}
+
+# Check for bunx or npx
+$runner = $null
+if (Get-Command bunx -ErrorAction SilentlyContinue) {
+    $runner = "bunx"
+} elseif (Get-Command npx -ErrorAction SilentlyContinue) {
+    $runner = "npx"
+}
+
+if ($runner) {
+    Write-Host "🚀 Running global setup via $runner..." -ForegroundColor Green
+    & $runner -y superpowers-mcp setup @argsList
+    exit $LASTEXITCODE
+}
+
+Write-Host "❌ Error: Node.js (npx) or Bun (bunx) is required to run Superpowers MCP." -ForegroundColor Red
+Write-Host "Please install Node.js from https://nodejs.org or Bun from https://bun.sh and try again." -ForegroundColor Yellow
+exit 1

package/scripts/install.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# Superpowers MCP - One-Click Global Installer (macOS & Linux)
+# Usage:
+#   curl -fsSL https://raw.githubusercontent.com/Poseidoncode/superpowers-mcp/main/scripts/install.sh | bash -s -- --target <client>
+#   ./scripts/install.sh --target <antigravity|pi-desktop|cursor|copilot|copilot-insiders|hermes|kimi|claude|devin|qwenpaw|cline|kilo|qoder|kiro|trae>
+# ==============================================================================
+
+set -euo pipefail
+
+echo ""
+echo "========================================================"
+echo "⚡ Superpowers MCP - One-Click Global Setup (macOS / Linux)"
+echo "========================================================"
+echo ""
+
+# Find Node / Bun runtime
+RUNNER=""
+if command -v bunx >/dev/null 2>&1; then
+    RUNNER="bunx"
+elif command -v npx >/dev/null 2>&1; then
+    RUNNER="npx"
+fi
+
+# Check if running from local repository clone safely
+SCRIPT_DIR=""
+if [ -n "${BASH_SOURCE[0]:-}" ]; then
+    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd || echo "")"
+fi
+
+if [ -n "$SCRIPT_DIR" ] && [ -f "$SCRIPT_DIR/setup.js" ] && command -v node >/dev/null 2>&1; then
+    echo "📦 Using local setup engine..."
+    exec node "$SCRIPT_DIR/setup.js" "$@"
+fi
+
+if [ -n "$RUNNER" ]; then
+    echo "🚀 Running global setup via $RUNNER..."
+    $RUNNER -y superpowers-mcp setup "$@"
+    exit $?
+fi
+
+echo "❌ Error: Node.js (npx) or Bun (bunx) is required to run Superpowers MCP."
+echo "Please install Node.js from https://nodejs.org or Bun from https://bun.sh and try again."
+exit 1

package/scripts/setup.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * Superpowers MCP - Global Setup Forwarder Wrapper
+ * Forwards calls to compiled out/setup.js (Single Source of Truth: src/setup-runner.ts)
+ */
+
+const path = require("path");
+const fs = require("fs");
+
+const compiledRunner = path.join(__dirname, "..", "out", "setup-runner.js");
+
+if (!fs.existsSync(compiledRunner)) {
+    const { execSync } = require("child_process");
+    try {
+        execSync("node esbuild.js", { cwd: path.join(__dirname, ".."), stdio: "inherit" });
+    } catch (e) {
+        console.error("Failed to build out/setup-runner.js automatically:", e.message);
+        process.exit(1);
+    }
+}
+
+const runner = require(compiledRunner);
+
+module.exports = runner;
+
+if (require.main === module) {
+    runner.runSetupCli().catch((err) => {
+        console.error("❌ Fatal error during setup execution:", err);
+        process.exit(1);
+    });
+}

package/skills/brainstorming/spec-document-reviewer-prompt.md

@@ -22,6 +22,7 @@ Subagent (general-purpose):
     | Consistency | Internal contradictions, conflicting requirements |
     | Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
     | Scope | Focused enough for a single plan — not covering multiple independent subsystems |
+    | Architecture | Units with clear boundaries, well-defined interfaces, independently understandable and testable |
     | YAGNI | Unrequested features, over-engineering |
 
     ## Calibration

package/skills/subagent-driven-development/implementer-prompt.md

@@ -17,6 +17,7 @@ Subagent (general-purpose):
 
     Read your task brief first: [BRIEF_FILE]
     It contains the full task text from the plan.
+    If your task brief specifies a **Recommended Skill** (e.g. `superpowers:test-driven-development`), adhere strictly to that skill's workflow and principles during implementation.
 
     ## Context
 

package/skills/using-superpowers/SKILL.md

@@ -30,6 +30,15 @@ When multiple skills apply, process skills come first — they set the approach,
 - "Let's build X" → superpowers:brainstorming first, then implementation skills.
 - "Fix this bug" → superpowers:systematic-debugging first, then domain skills.
 
+## Skill Compositions & Pipelines
+
+Complex engineering workflows chain multiple skills end-to-end (see `docs/skill-compositions.md`):
+
+- **Feature Pipeline:** `brainstorming` → `writing-plans` → `using-git-worktrees` → `subagent-driven-development` (with `test-driven-development`) → `verification-before-completion` → `requesting-code-review` → `finishing-a-development-branch`
+- **Troubleshooting Pipeline:** `systematic-debugging` → `using-git-worktrees` → `dispatching-parallel-agents` → `test-driven-development` → `verification-before-completion` → `requesting-code-review`
+- **Refactoring Pipeline:** `brainstorming` → `writing-plans` (skeleton-first) → `using-git-worktrees` → `subagent-driven-development` → `verification-before-completion` → `requesting-code-review`
+
+
 ## Red Flags
 
 These thoughts mean STOP—you're rationalizing:

package/skills/writing-plans/SKILL.md

@@ -108,6 +108,8 @@ include this section.]
 ````markdown
 ### Task N: [Component Name]
 
+**Recommended Skill:** `superpowers:test-driven-development` (or relevant skill)
+
 **Files:**
 - Create: `exact/path/to/file.py`
 - Modify: `exact/path/to/existing.py:123-145`
@@ -119,6 +121,7 @@ include this section.]
   and return types. A task's implementer sees only their own task; this
   block is how they learn the names and types neighboring tasks use.]
 
+
 - [ ] **Step 1: Write the failing test**
 
 ```python

package/skills/writing-plans/plan-document-reviewer-prompt.md

@@ -22,6 +22,7 @@ Subagent (general-purpose):
     | Completeness | TODOs, placeholders, incomplete tasks, missing steps |
     | Spec Alignment | Plan covers spec requirements, no major scope creep |
     | Task Decomposition | Tasks have clear boundaries, steps are actionable |
+    | Architecture | File structure has units with clear boundaries, no files growing too large to reason about |
     | Buildability | Could an engineer follow this plan without getting stuck? |
 
     ## Calibration