@ia-ccun/code-agent-cli 0.0.15 → 0.0.17

package/bin/cli.js

@@ -1,111 +1,180 @@
 #!/usr/bin/env node
+
 /**
- * CLI entry point for aicode-cli
- * Delegates to @mariozechner/pi-coding-agent
- * Shows wrapper version for --version flag
+ * aicode-cli
+ * AI Coding Agent CLI - 基于 @mariozechner/pi-coding-agent
  */
 
-import { readFileSync } from 'fs';
-import { dirname, join } from 'path';
+import { spawn, execSync } from 'child_process';
 import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { existsSync, readFileSync } from 'fs';
+import { getConfig, getConfigDir, loadConfig } from '../dist/config-loader.js';
+import { generateBanner } from '../dist/banner.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-// Check if --version or -v is requested
-const args = process.argv.slice(2);
-if (args.includes('--version') || args.includes('-v')) {
-  // Read wrapper package version
-  const packageJson = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
-  console.log(packageJson.version);
-  process.exit(0);
+// 解析命令行参数
+function parseArgs() {
+  const args = process.argv.slice(2);
+  let configDir;
+  let webMode = false;
+  let webPort;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--config' || arg === '-c') {
+      configDir = args[i + 1];
+      args.splice(i, 2);
+      i--;
+    } else if (arg === '--web' || arg === '--webui') {
+      webMode = true;
+      args.splice(i, 1);
+      i--;
+    } else if (arg === '--port' || arg === '-p') {
+      webPort = parseInt(args[i + 1], 10);
+      args.splice(i, 2);
+      i--;
+    }
+  }
+
+  return { remainingArgs: args, configDir, webMode, webPort };
 }
 
-// Print custom Banner (always show, not affected by quietStartup)
-const configPath = join(__dirname, '..', 'config.json');
-let showBanner = true;
-try {
-  const config = JSON.parse(readFileSync(configPath, 'utf-8'));
-  // Show banner only if banner field is set and not empty
-  showBanner = config.banner && config.banner !== '' && config.banner !== '""';
-} catch (e) {
-  // ignore
+const { remainingArgs, configDir: cliConfigDir, webMode, webPort } = parseArgs();
+
+// 优先使用命令行参数，其次使用环境变量，最后使用默认值
+const effectiveConfigDir = cliConfigDir || process.env.AICODE_CLI_CONFIG_DIR;
+
+// 如果指定了配置目录，加载该目录下的配置
+let config;
+if (effectiveConfigDir) {
+  // 临时覆盖环境变量
+  process.env.AICODE_CLI_CONFIG_DIR = effectiveConfigDir;
+  config = loadConfig();
+} else {
+  config = getConfig();
 }
 
-if (showBanner) {
-  // Read theme color from config
-  let themeColor = '#49bccf'; // default
-  try {
-    const config = JSON.parse(readFileSync(configPath, 'utf-8'));
-    if (config.themeColor) {
-      themeColor = config.themeColor;
+
+
+// 显示 Banner
+if (config.banner === '__default__' || config.banner !== '') {
+  console.log(generateBanner(config.themeColor));
+}
+
+// 检查新版本（后台异步执行，不阻塞启动）
+function checkForUpdates() {
+  setTimeout(async () => {
+    try {
+      // 读取本地版本
+      const pkgPath = new URL('../package.json', import.meta.url).pathname;
+      const localVersion = JSON.parse(readFileSync(pkgPath)).version;
+
+      // 获取当前 registry
+      const registry = execSync('npm config get registry', { encoding: 'utf8', stdio: 'pipe' }).trim();
+      const latestVersion = execSync(`npm view @nucc/code-agent-cli version --registry=${registry}`, { encoding: 'utf8', stdio: 'pipe' }).trim();
+
+      // 比较版本号
+      const localParts = localVersion.split('.').map(Number);
+      const latestParts = latestVersion.split('.').map(Number);
+      const needsUpdate = latestParts[0] > localParts[0] ||
+                         (latestParts[0] === localParts[0] && latestParts[1] > localParts[1]) ||
+                         (latestParts[0] === localParts[0] && latestParts[1] === localParts[1] && latestParts[2] > localParts[2]);
+
+      if (needsUpdate) {
+        console.log('\n\x1b[33m⚠️  发现新版本 v%s → v%s\x1b[0m', localVersion, latestVersion);
+        console.log('\x1b[36m   运行以下命令更新:\x1b[0m');
+        console.log('   npm install -g @nucc/code-agent-cli\n');
+      }
+    } catch (e) {
+      // 忽略检查失败
     }
-  } catch (e) {
-    // ignore
-  }
+  }, 100); // 延迟 100ms 确保不影响主流程
+}
+
+// WebUI 模式
+if (webMode) {
+  const webuiDir = join(__dirname, '..', 'webui', 'server');
 
-  // Generate colored banner
-  const hexToRgb = (hex) => {
-    hex = hex.replace('#', '');
-    return {
-      r: parseInt(hex.slice(0, 2), 16),
-      g: parseInt(hex.slice(2, 4), 16),
-      b: parseInt(hex.slice(4, 6), 16)
-    };
-  };
-
-  // Read banner config
-  let bannerConfig = '';
+  // 先构建 webui
+  console.log('🔨 Building WebUI...');
   try {
-    const config = JSON.parse(readFileSync(configPath, 'utf-8'));
-    bannerConfig = config.banner || '';
+    execSync('npm run build', { cwd: webuiDir, stdio: 'inherit' });
   } catch (e) {
-    // ignore
+    console.error('Failed to build WebUI:', e);
+    process.exit(1);
   }
 
-  const rgb = hexToRgb(themeColor);
-  const colorCode = `\x1b[38;2;${rgb.r};${rgb.g};${rgb.b}m`;
-  const resetCode = '\x1b[0m';
-
-  // Get terminal width for centering
-  const terminalWidth = process.stdout.columns || 80;
+  // 启动 WebUI 服务器
+  const portArgs = webPort ? ['--port', String(webPort)] : [];
+  const webuiProcess = spawn('node', ['dist/index.js', ...portArgs], {
+    cwd: webuiDir,
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      AICODE_CLI_CONFIG_DIR: config.configDir,
+    }
+  });
 
-  // If banner is "__default__", use ASCII art; otherwise use custom text
-  if (bannerConfig === '__default__') {
-    // Banner from scripts/banner.txt
-    let lines = [];
+  // 自动打开浏览器
+  const port = webPort || 3002;
+  setTimeout(() => {
     try {
-      const bannerPath = join(__dirname, '..', 'scripts', 'banner.txt');
-      const bannerContent = readFileSync(bannerPath, 'utf-8');
-      lines = bannerContent.trim().split('\n');
+      execSync(`open http://localhost:${port}`, { stdio: 'ignore' });
     } catch (e) {
-      // fallback - no banner
-    }
-    lines.forEach(line => console.log(colorCode + line + resetCode));
-  } else if (bannerConfig && bannerConfig !== '') {
-    // Custom text banner - handle both string and array
-    let quotes = [];
-    if (Array.isArray(bannerConfig)) {
-      quotes = bannerConfig;
-    } else if (typeof bannerConfig === 'string' && bannerConfig.startsWith('[')) {
-      try {
-        quotes = JSON.parse(bannerConfig);
-      } catch (e) {
-        quotes = [bannerConfig];
-      }
-    } else {
-      quotes = [bannerConfig];
+      // 忽略打开浏览器失败
     }
+  }, 2000);
 
-    // Random quote
-    const quote = quotes[Math.floor(Math.random() * quotes.length)];
+  webuiProcess.on('exit', (code) => {
+    process.exit(code ?? 0);
+  });
 
-    // Center the quote
-    const padding = Math.max(0, Math.floor((terminalWidth - quote.length) / 2));
-    console.log(colorCode + ' '.repeat(padding) + quote + resetCode);
-  }
-  console.log('');
+  webuiProcess.on('error', (err) => {
+    console.error('Failed to start WebUI:', err);
+    process.exit(1);
+  });
+
+  // WebUI 模式下不执行后续的 TUI 逻辑
+  checkForUpdates();
+  // 不阻塞，让 webui 进程继续运行
 }
 
-// Delegate to pi-coding-agent for all other commands
-import('../node_modules/@mariozechner/pi-coding-agent/dist/cli.js');
+checkForUpdates();
+
+// 获取 node_modules 中 pi-coding-agent 的 CLI 路径
+const piAgentPath = new URL('../node_modules/@mariozechner/pi-coding-agent/dist/cli.js', import.meta.url);
+
+// 设置环境变量
+const env = {
+  ...process.env,
+  AICODE_CLI_CONFIG_DIR: config.configDir,
+  AICODE_CLI_NAME: config.name,
+  PI_SKIP_VERSION_CHECK: '1'
+};
+
+// 传递配置目录给 pi
+// pi 使用 AICODE_CLI_CODING_AGENT_DIR 环境变量 (基于 piConfig.name)
+// 确保使用完整的绝对路径
+const fullPath = join(process.env.HOME || process.env.USERPROFILE, config.configDir);
+const agentDir = join(fullPath, 'agent');
+env.AICODE_CLI_CODING_AGENT_DIR = agentDir;
+
+
+
+// 启动 pi-coding-agent
+const child = spawn('node', [piAgentPath.pathname, ...remainingArgs], {
+  stdio: 'inherit',
+  env
+});
+
+child.on('exit', (code) => {
+  process.exit(code ?? 0);
+});
+
+child.on('error', (err) => {
+  console.error('Failed to start agent:', err);
+  process.exit(1);
+});

package/config/agent/extensions/working-msg.ts

@@ -11,22 +11,47 @@ import type { AssistantMessage } from "@mariozechner/pi-ai";
 const accentColor = "\x1b[38;2;73;188;207m";
 const reset = "\x1b[0m";
 
-// 随机消息列表
+// 随机消息列表 - 金融/支付/科技术语
 const workingMessages = [
-	"记得打卡~", "Thinking", "AICoding", "断直连", "备付金存管", "小额高频", "大额支付", "备用渠道", "聚合支付", "统一接口", "技术中台", "Processing","外包服务机构", "技术方案", "产品介绍", "业务量统计", "风险评级", "支付流程", "支付指令", "资金划转", "交易信息", "可追溯性", "支付成本", "支付创新", "数字翻译官", "信息转换", "安全保障", "指令传递", "协议适配", "系统对接", "技术规范", "交易透明度", "市场公平竞争", "路由", "支付转化率", "无感支付", "可靠性", "无主动确认支付", "资金流向相反", "批量付款", "收银台", "支付成功", "资金保障险", "72小时赔付", "盗刷赔付", "全链路服务", "资金查询", "结算服务", "对账服务", "生态完善",  "打卡了吗",
-	"Debugging", "Learning", "支付行业健康",  "Reasoning", "Summarizing", "一会儿吃啥","Planning", "Executing","Refactoring", "aicoding","Documenting", "Researching", "Evaluating", "Comparing", "Calculating","支付", "清算", "结算", "交易", "货币债权", "贷记业务", "借记业务", "预付价值", "卡组织", "商业银行", "非银行支付机构", "收单机构", "账户侧", "受理侧", "服务商", "代理商", "清算所", "中央银行", "Fetching", "Parsing", "Validating","双人复核","Building", "Testing", "Deploying", "Monitoring",  "四方模式", "本代本收单", "本代他收单", "银行卡支付", "实体卡", "数字卡", "贷记卡", "借记卡", "双标银行卡", "磁条卡", "芯片卡", "伪卡", "盗卡", "销售点终端（POS）", "POS签购单", "商户类别码（MCC）","Analyzing", "Reading", "Writing", "干活儿中","Searching", "Generating", "Compiling", "Running", "Optimizing", "非接触式支付", "拍卡过闸", "移动支付", "二维码支付", "条码支付", "NFC支付", "刷脸支付", "刷掌支付", "碰一下", "网关支付", "快捷支付", "认证支付", "IVR电话支付", "短信支付", "电子支付", "网上支付跨行清算系统（IBPS）", "mPOS", "数字钱包", "加密钱包支付", "账户对账户支付（A2A）", "先买后付（BNPL）", "稳定币", "代币化资产", "物联网+无感支付", "支付系统", "大额支付系统（HVPS）", "小额批量支付系统（BEPS）", "境内外币支付系统（CFXPS）", "清算账务系统", "账户系统", "登录账户", "支付账户", "银行接口", "对账", "冲正交易", "掉单", "补单", "参考号", "T+0", "T+1", "一清机", "二清机", "可信服务管理（TSM）", "风控系统", "反欺诈", "深度伪造（Deepfake）", "报文鉴别码（MAC）", "安全超文本传输协议（HTTPS）", "动态口令", "USB电子密钥", "侧录", "钓鱼网站", "非法移机", "调单", "一机一码", "一机一户", "259号文", "穿透式监管", "监管一致性", "支付牌照", "反洗钱（AML）", "无代码反洗钱采纳", "互联互通", "人工智能（AI）", "智能体（AI Agent）", "生成式AI（GenAI）", "数字身份", "虚拟卡", "循环经济", "法币抵押型稳定币", "加密资产抵押型稳定币", "算法稳定币", "商品抵押型稳定币", "支付型稳定币", "USDT", "USDC", "泰达币", "Circle", "美元稳定币", "港元稳定币", "离岸人民币稳定币", "稳定币发行方", "稳定币储备资产", "1:1锚定", "脱钩风险", "挤兑风险", "支付稳定币法案", "GENIUS法案", "稳定币条例", "稳定币沙盒", "链上法币", "跨境支付稳定币", "区块链", "分布式账本技术", "智能合约", "公有链", "联盟链", "最终性", "快速最终确认", "高吞吐量", "跨链", "Layer 2", "闪电网络", "DeFi", "去中心化金融", "RWA", "真实世界资产", "代币化", "资产代币化", "代币化存款", "加密钱包", "自托管钱包", "支付服务处理器", "支付网关", "出入金通道", "链上交易", "链下交易", "加密支付", "可编程支付", "可编程货币", "专用货币", "条件支付", "点对点支付", "加密编排层", "M0协议", "稳定币即服务", "第三方支付", "非金融机构支付", "互联网支付", "移动支付", "网络支付", "预付卡", "单用途预付卡", "多用途预付卡", "银行卡收单", "收单机构", "特约商户", "支付网关", "支付牌照", "支付中介", "网络支付接口", "受理终端", "聚合支付", "资金结算", "货币汇兑", "固定电话支付", "数字电视支付", "支付稳定币", "稳定币支付", "链上结算", "SWIFT替代", "跨境支付结算", "支付巨头稳定币布局", "支付基础设施", "商业银行稳定币", "监管一致性", "牌照管理", "合规成本", "生态协同", "网络效应", "真实采用", "商户结算", "稳定币交易手续费", "储备资产收益", "利息差额", "托管费", "无代码反洗钱采纳", "数字身份", "代币化资产", "物联网+无感支付", "循环经济", "网络安全", "信息安全", "数据安全", "加密技术", "数据加密", "传输加密", "存储加密", "端到端加密", "密钥管理", "密钥生命周期", "硬件安全模块(HSM)", "安全多方计算(MPC)", "可信执行环境(TEE)", "安全元件(SE)", "主机卡模拟(HCE)", "访问控制", "身份认证", "多因素认证(MFA)", "生物识别", "数据脱敏", "隐私计算", "差分隐私", "交易安全", "支付安全", "账户安全", "风控系统", "反欺诈", "实时风控", "行为分析", "设备指纹", "生物探针", "关联网络", "异常交易检测", "交易监控", "限额管理", "黑名单", "灰名单", "商户风险管理", "套现风险", "洗钱风险", "赌博风险", "欺诈交易", "盗刷", "账户盗用", "身份冒用", "薅羊毛", "恶意退款", "二次授权", "风险参数", "风险评分", "安全控件", "支付标记化", "终端安全", "移动安全", "应用安全", "代码混淆", "安全加固", "模拟器检测", "调试检测", "根检测", "Hook检测", "通信协议安全", "API安全", "网关安全", "服务器安全", "主机安全", "云安全", "容器安全", "中间件安全", "数据库安全", "Web应用防火墙(WAF)", "DDoS防护", "入侵检测", "入侵防御", "漏洞扫描", "渗透测试", "安全审计", "网络攻击", "黑客", "病毒", "木马", "蠕虫", "钓鱼", "鱼叉钓鱼", "短信钓鱼", "语音钓鱼", "恶意软件", "勒索软件", "间谍软件", "中间人攻击", "重放攻击", "会话劫持", "跨站脚本", "SQL注入", "撞库", "暴力破解", "密码猜测", "社会工程学", "伪基站", "嗅探", "侧录", "侧信道攻击", "冷板凳攻击", "智能合约安全", "重入攻击", "闪电贷攻击", "预言机攻击", "女巫攻击", "Sybil攻击", "51%攻击", "双花", "粉尘攻击", "蜜罐", "貔貅盘", "私钥安全", "助记词安全", "冷钱包", "热钱包", "多重签名", "私钥泄露", "授权攻击", "钓鱼签名", "假充值", "跨链桥安全", "共识算法安全", "零知识证明", "可信设置", "合规安全", "等级保护", "个人信息保护", "隐私政策", "安全标准", "PCI DSS", "PIN安全", "支付标记化标准", "EMVCo", "ISO 27001", "GDPR", "网络安全法", "数据安全法", "金融网络安全", "监管合规", "安全检查", "安全评估", "风险控制指标", "网络安全等级保护", "商用密码应用", "国密算法","断直连", "公共转接清算", "集中化清算", "透明化清算", "协议支付", "商业委托支付", "代收代扣", "付款业务", "退款业务", "辅助接口", "签约接口", "解约接口", "身份认证", "银行网关", "企业网银", "个人网银", "限额高", "体验流畅", "支付效率", "资金安全", "客户备付金", "风险控制", "跨行交易", "合法清算机构", "条码支付业务规范", "商户实名制", "交易风险监测", "本地化经营", "定期巡检", "业务创新"
+	// 金融支付类
+	"备付金", "网银支付", "快捷支付", "代付", "代收", "清算", "结算", "对账",
+	"交易路由", "风控", "反欺诈", "欺诈检测", "洗钱防控", "合规审查", "反洗钱",
+	"支付通道", "渠道商", "商户", "收款", "退款", "拒付", "冲正", "挂账",
+	"资金池", "沉淀资金", "T+1结算", "实时结算", "分账", "分润", "抽成",
+	"银行卡", "信用卡", "借记卡", "IC卡", "磁条卡", "虚拟卡", "预付费卡",
+	"二维码支付", "NFC支付", "刷脸支付", "指纹支付", "声纹支付",
+	"跨境支付", "外汇结算", "汇率", "国际清算", "SWIFT", "CIPS",
+
+	// 区块链/网络安全类
+	"区块链", "智能合约", "共识机制", "PoW", "PoS", "DPoS", "Gas费",
+	"加密货币", "比特币", "以太坊", "稳定币", "DeFi", "NFT", "Web3",
+	"数字签名", "哈希", "非对称加密", "对称加密", "公钥", "私钥", "证书",
+	"数字证书", "PKI体系", "CA中心", "SSL/TLS", "HTTPS", "国密算法",
+	"防火墙", "入侵检测", "DDoS防护", "WAF", "漏洞扫描", "渗透测试",
+
+	// 生产变更/运维类
+	"变更管理", "发布", "回滚", "灰度发布", "蓝绿部署", "金丝雀发布",
+	"熔断", "限流", "降级", "切流", "流量切换", "流量调度",
+	"监控", "告警", "日志", "链路追踪", "APM", "性能监控", "可用性",
+
+	// 技术通用类
+	"Proofing", "Thinking", "Analyzing", "Reading", "Writing", "Searching",
+	"Generating", "Compiling", "Running", "Optimizing", "Debugging", "Learning",
+	"Processing", "Reasoning", "Summarizing", "Planning", "Executing", "Fetching",
+	"Parsing", "Validating", "Building", "Testing", "Deploying", "Refactoring",
+	"Documenting", "Researching", "Evaluating", "Comparing", "Calculating",
+	"Algorithm", "Architecture", "Database", "Cache", "Queue", "Microservice",
 ];
 
+let intervalId: ReturnType<typeof setInterval> | null = null;
+let startTime = 0;
+let totalTokens = 0;
+
 function getNextMessage(): string {
-	// 随机选择词汇
 	const randomIndex = Math.floor(Math.random() * workingMessages.length);
 	return workingMessages[randomIndex];
 }
 
-let intervalId: ReturnType<typeof setInterval> | null = null;
-let startTime = 0;
-let totalTokens = 0;
-
 function formatTime(seconds: number): string {
 	if (seconds < 60) return `${seconds} s`;
 	const mins = Math.floor(seconds / 60);

package/config/agent/models.json

@@ -1,23 +1,53 @@
 {
   "providers": {
-    "GLM": {
-      "name": "GLM",
-      "baseUrl": "https://ai-llm.xxxxx.com/v1",
+    "openai": {
+      "name": "OpenAI",
+      "baseUrl": "https://api.openai.com/v1",
       "api": "openai-completions",
       "apiKey": "YOUR_API_KEY_HERE",
       "models": [
         {
-          "id": "GLM-4.7-W8A8",
-          "name": "GLM4.7",
-          "contextWindow": 200000,
-          "maxTokens": 100000,
+          "id": "gpt-4o",
+          "name": "GPT-4o",
+          "contextWindow": 128000,
+          "maxTokens": 16384,
+          "reasoning": false,
+          "input": ["text"],
+          "cost": {
+            "input": 2.5,
+            "output": 10
+          }
+        },
+        {
+          "id": "gpt-4o-mini",
+          "name": "GPT-4o Mini",
+          "contextWindow": 128000,
+          "maxTokens": 16384,
           "reasoning": false,
           "input": ["text"],
           "cost": {
-            "input": 5,
-            "output": 5,
-            "cacheRead": 0,
-            "cacheWrite": 0
+            "input": 0.075,
+            "output": 0.3
+          }
+        }
+      ]
+    },
+    "anthropic": {
+      "name": "Anthropic",
+      "baseUrl": "https://api.anthropic.com",
+      "api": "anthropic-messages",
+      "apiKey": "YOUR_API_KEY_HERE",
+      "models": [
+        {
+          "id": "claude-sonnet-4-20250514",
+          "name": "Claude Sonnet 4",
+          "contextWindow": 200000,
+          "maxTokens": 8192,
+          "reasoning": true,
+          "input": ["text"],
+          "cost": {
+            "input": 3,
+            "output": 15
           }
         }
       ]

package/config/agent/prompts/code-simplifier.md

@@ -0,0 +1,52 @@
+---
+name: code-simplifier
+description: Simplifies and refines code for clarity, consistency, and maintainability while preserving all functionality. Focuses on recently modified code unless instructed otherwise.
+autho: xujianjiang
+---
+
+You are an expert code simplification specialist focused on enhancing code clarity, consistency, and maintainability while preserving exact functionality. Your expertise lies in applying project-specific best practices to simplify and improve code without altering its behavior. You prioritize readable, explicit code over overly compact solutions. This is a balance that you have mastered as a result your years as an expert software engineer.
+
+You will analyze recently modified code and apply refinements that:
+
+1. **Preserve Functionality**: Never change what the code does - only how it does it. All original features, outputs, and behaviors must remain intact.
+
+2. **Apply Project Standards**: Follow the established coding standards from CLAUDE.md including:
+
+   - Use ES modules with proper import sorting and extensions
+   - Prefer `function` keyword over arrow functions
+   - Use explicit return type annotations for top-level functions
+   - Follow proper React component patterns with explicit Props types
+   - Use proper error handling patterns (avoid try/catch when possible)
+   - Maintain consistent naming conventions
+
+3. **Enhance Clarity**: Simplify code structure by:
+
+   - Reducing unnecessary complexity and nesting
+   - Eliminating redundant code and abstractions
+   - Improving readability through clear variable and function names
+   - Consolidating related logic
+   - Removing unnecessary comments that describe obvious code
+   - IMPORTANT: Avoid nested ternary operators - prefer switch statements or if/else chains for multiple conditions
+   - Choose clarity over brevity - explicit code is often better than overly compact code
+
+4. **Maintain Balance**: Avoid over-simplification that could:
+
+   - Reduce code clarity or maintainability
+   - Create overly clever solutions that are hard to understand
+   - Combine too many concerns into single functions or components
+   - Remove helpful abstractions that improve code organization
+   - Prioritize "fewer lines" over readability (e.g., nested ternaries, dense one-liners)
+   - Make the code harder to debug or extend
+
+5. **Focus Scope**: Only refine code that has been recently modified or touched in the current session, unless explicitly instructed to review a broader scope.
+
+Your refinement process:
+
+1. Identify the recently modified code sections
+2. Analyze for opportunities to improve elegance and consistency
+3. Apply project-specific best practices and coding standards
+4. Ensure all functionality remains unchanged
+5. Verify the refined code is simpler and more maintainable
+6. Document only significant changes that affect understanding
+
+You operate autonomously and proactively, refining code immediately after it's written or modified without requiring explicit requests. Your goal is to ensure all code meets the highest standards of elegance and maintainability while preserving its complete functionality.

package/config/agent/skills/brainstorming/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: brainstorming
+author: xujianjiang
+description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
+---
+
+# Brainstorming Ideas Into Designs
+
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
+
+<HARD-GATE>
+Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
+</HARD-GATE>
+
+## Anti-Pattern: "This Is Too Simple To Need A Design"
+
+Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
+
+## Checklist
+
+You MUST create a task for each of these items and complete them in order:
+
+1. **Explore project context** — check files, docs, recent commits
+2. **Offer visual companion** (if topic will involve visual questions) — this is its own message, not combined with a clarifying question. See the Visual Companion section below.
+3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
+4. **Propose 2-3 approaches** — with trade-offs and your recommendation
+5. **Present design** — in sections scaled to their complexity, get user approval after each section
+6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit
+7. **Spec review loop** — dispatch spec-document-reviewer subagent with precisely crafted review context (never your session history); fix issues and re-dispatch until approved (max 3 iterations, then surface to human)
+8. **User reviews written spec** — ask user to review the spec file before proceeding
+9. **Transition to implementation** — invoke writing-plans skill to create implementation plan
+
+## Process Flow
+
+```dot
+digraph brainstorming {
+    "Explore project context" [shape=box];
+    "Visual questions ahead?" [shape=diamond];
+    "Offer Visual Companion\n(own message, no other content)" [shape=box];
+    "Ask clarifying questions" [shape=box];
+    "Propose 2-3 approaches" [shape=box];
+    "Present design sections" [shape=box];
+    "User approves design?" [shape=diamond];
+    "Write design doc" [shape=box];
+    "Spec review loop" [shape=box];
+    "Spec review passed?" [shape=diamond];
+    "User reviews spec?" [shape=diamond];
+    "Invoke writing-plans skill" [shape=doublecircle];
+
+    "Explore project context" -> "Visual questions ahead?";
+    "Visual questions ahead?" -> "Offer Visual Companion\n(own message, no other content)" [label="yes"];
+    "Visual questions ahead?" -> "Ask clarifying questions" [label="no"];
+    "Offer Visual Companion\n(own message, no other content)" -> "Ask clarifying questions";
+    "Ask clarifying questions" -> "Propose 2-3 approaches";
+    "Propose 2-3 approaches" -> "Present design sections";
+    "Present design sections" -> "User approves design?";
+    "User approves design?" -> "Present design sections" [label="no, revise"];
+    "User approves design?" -> "Write design doc" [label="yes"];
+    "Write design doc" -> "Spec review loop";
+    "Spec review loop" -> "Spec review passed?";
+    "Spec review passed?" -> "Spec review loop" [label="issues found,\nfix and re-dispatch"];
+    "Spec review passed?" -> "User reviews spec?" [label="approved"];
+    "User reviews spec?" -> "Write design doc" [label="changes requested"];
+    "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
+}
+```
+
+**The terminal state is invoking writing-plans.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you invoke after brainstorming is writing-plans.
+
+## The Process
+
+**Understanding the idea:**
+
+- Check out the current project state first (files, docs, recent commits)
+- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
+- If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.
+- For appropriately-scoped projects, ask questions one at a time to refine the idea
+- Prefer multiple choice questions when possible, but open-ended is fine too
+- Only one question per message - if a topic needs more exploration, break it into multiple questions
+- Focus on understanding: purpose, constraints, success criteria
+
+**Exploring approaches:**
+
+- Propose 2-3 different approaches with trade-offs
+- Present options conversationally with your recommendation and reasoning
+- Lead with your recommended option and explain why
+
+**Presenting the design:**
+
+- Once you believe you understand what you're building, present the design
+- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
+- Ask after each section whether it looks right so far
+- Cover: architecture, components, data flow, error handling, testing
+- Be ready to go back and clarify if something doesn't make sense
+
+**Design for isolation and clarity:**
+
+- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
+- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
+- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
+- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.
+
+**Working in existing codebases:**
+
+- Explore the current structure before proposing changes. Follow existing patterns.
+- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
+- Don't propose unrelated refactoring. Stay focused on what serves the current goal.
+
+## After the Design
+
+**Documentation:**
+
+- Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
+  - (User preferences for spec location override this default)
+- Use elements-of-style:writing-clearly-and-concisely skill if available
+- Commit the design document to git
+
+**Spec Review Loop:**
+After writing the spec document:
+
+1. Dispatch spec-document-reviewer subagent (see spec-document-reviewer-prompt.md)
+2. If Issues Found: fix, re-dispatch, repeat until Approved
+3. If loop exceeds 3 iterations, surface to human for guidance
+
+**User Review Gate:**
+After the spec review loop passes, ask the user to review the written spec before proceeding:
+
+> "Spec written and committed to `<path>`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
+
+Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.
+
+**Implementation:**
+
+- Invoke the writing-plans skill to create a detailed implementation plan
+- Do NOT invoke any other skill. writing-plans is the next step.
+
+## Key Principles
+
+- **One question at a time** - Don't overwhelm with multiple questions
+- **Multiple choice preferred** - Easier to answer than open-ended when possible
+- **YAGNI ruthlessly** - Remove unnecessary features from all designs
+- **Explore alternatives** - Always propose 2-3 approaches before settling
+- **Incremental validation** - Present design, get approval before moving on
+- **Be flexible** - Go back and clarify when something doesn't make sense
+
+## Visual Companion
+
+A browser-based companion for showing mockups, diagrams, and visual options during brainstorming. Available as a tool — not a mode. Accepting the companion means it's available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser.
+
+**Offering the companion:** When you anticipate that upcoming questions will involve visual content (mockups, layouts, diagrams), offer it once for consent:
+> "Some of what we're working on might be easier to explain if I can show it to you in a web browser. I can put together mockups, diagrams, comparisons, and other visuals as we go. This feature is still new and can be token-intensive. Want to try it? (Requires opening a local URL)"
+
+**This offer MUST be its own message.** Do not combine it with clarifying questions, context summaries, or any other content. The message should contain ONLY the offer above and nothing else. Wait for the user's response before continuing. If they decline, proceed with text-only brainstorming.
+
+**Per-question decision:** Even after the user accepts, decide FOR EACH QUESTION whether to use the browser or the terminal. The test: **would the user understand this better by seeing it than reading it?**
+
+- **Use the browser** for content that IS visual — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
+- **Use the terminal** for content that is text — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions
+
+A question about a UI topic is not automatically a visual question. "What does personality mean in this context?" is a conceptual question — use the terminal. "Which wizard layout works better?" is a visual question — use the browser.
+
+If they agree to the companion, read the detailed guide before proceeding:
+`skills/brainstorming/visual-companion.md`