ultra-builder-pro-cli 0.5.0

package/bin/install.js

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+
+/**
+ * ultra-builder-pro-cli — multi-runtime installer.
+ *
+ * Distributes Ultra Builder Pro assets — commands, agents, skills, hooks,
+ * MCP server — to Claude Code, OpenCode, Codex CLI, and Gemini CLI via
+ * runtime-specific adapters under adapters/. Install is idempotent and
+ * uses atomic writes; uninstall reverses via sentinel/manifest blocks.
+ *
+ * Usage:
+ *   npx ultra-builder-pro-cli [options]
+ *
+ *   --claude / --opencode / --codex / --gemini   select runtime(s)
+ *   --all                                         install to all supported runtimes
+ *   -g, --global                                  install to runtime's global config dir
+ *   -l, --local                                   install into current working directory
+ *   -u, --uninstall                               remove installed assets
+ *   -c, --config-dir <path>                       override config directory
+ *       --skip-rtk                                do not detect / install RTK hook
+ *   -h, --help                                    show help
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const pkg = require('../package.json');
+const { validateConfigDir } = require('../adapters/_shared/validate.cjs');
+
+const SUPPORTED_RUNTIMES = ['claude', 'opencode', 'codex', 'gemini'];
+
+const COLORS = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+};
+
+function paint(color, text) {
+  if (!process.stdout.isTTY) return text;
+  return `${COLORS[color] || ''}${text}${COLORS.reset}`;
+}
+
+function printBanner() {
+  const banner = [
+    '',
+    paint('cyan', '  ██╗   ██╗██████╗ ██████╗     ██████╗██╗     ██╗'),
+    paint('cyan', '  ██║   ██║██╔══██╗██╔══██╗   ██╔════╝██║     ██║'),
+    paint('cyan', '  ██║   ██║██████╔╝██████╔╝   ██║     ██║     ██║'),
+    paint('cyan', '  ██║   ██║██╔══██╗██╔═══╝    ██║     ██║     ██║'),
+    paint('cyan', '  ╚██████╔╝██████╔╝██║        ╚██████╗███████╗██║'),
+    paint('cyan', '   ╚═════╝ ╚═════╝ ╚═╝         ╚═════╝╚══════╝╚═╝'),
+    '',
+    `  ${paint('bold', 'Ultra Builder Pro CLI')} ${paint('dim', 'v' + pkg.version)}`,
+    `  ${paint('dim', 'Multi-runtime installer for Claude Code, OpenCode, Codex, Gemini')}`,
+    '',
+  ];
+  console.log(banner.join('\n'));
+}
+
+function printHelp() {
+  console.log(`  ${paint('yellow', 'Usage:')} npx ultra-builder-pro-cli [options]
+
+  ${paint('yellow', 'Runtime selection (pick ≥1, or --all):')}
+    ${paint('cyan', '--claude')}           Claude Code
+    ${paint('cyan', '--opencode')}         OpenCode
+    ${paint('cyan', '--codex')}            Codex CLI (OpenAI)
+    ${paint('cyan', '--gemini')}           Gemini CLI (Google)
+    ${paint('cyan', '--all')}              all supported runtimes
+
+  ${paint('yellow', 'Scope:')}
+    ${paint('cyan', '-g, --global')}       install to runtime's global config directory
+    ${paint('cyan', '-l, --local')}        install to current working directory
+
+  ${paint('yellow', 'Other:')}
+    ${paint('cyan', '-u, --uninstall')}    remove installed assets
+    ${paint('cyan', '-c, --config-dir')}   override runtime's config directory (string path)
+    ${paint('cyan', '--skip-rtk')}        skip RTK hook registration (RTK is a soft dependency)
+    ${paint('cyan', '-h, --help')}         show this help
+    ${paint('cyan', '-v, --version')}      show CLI version
+
+  ${paint('yellow', 'Examples:')}
+    ${paint('dim', '# Install to Claude Code globally')}
+    npx ultra-builder-pro-cli --claude --global
+
+    ${paint('dim', '# Install to all 4 runtimes locally in this repo')}
+    npx ultra-builder-pro-cli --all --local
+
+    ${paint('dim', '# Uninstall from OpenCode')}
+    npx ultra-builder-pro-cli --opencode --global --uninstall
+`);
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const runtimes = new Set();
+  const flags = {
+    global: false,
+    local: false,
+    uninstall: false,
+    help: false,
+    version: false,
+    configDir: null,
+    skipRtk: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    switch (a) {
+      case '--claude': runtimes.add('claude'); break;
+      case '--opencode': runtimes.add('opencode'); break;
+      case '--codex': runtimes.add('codex'); break;
+      case '--gemini': runtimes.add('gemini'); break;
+      case '--all':
+        SUPPORTED_RUNTIMES.forEach(r => runtimes.add(r));
+        break;
+      case '-g': case '--global': flags.global = true; break;
+      case '-l': case '--local': flags.local = true; break;
+      case '-u': case '--uninstall': flags.uninstall = true; break;
+      case '-h': case '--help': flags.help = true; break;
+      case '-v': case '--version': flags.version = true; break;
+      case '--skip-rtk': flags.skipRtk = true; break;
+      case '-c': case '--config-dir':
+        flags.configDir = args[++i];
+        if (!flags.configDir || flags.configDir.startsWith('-')) {
+          bail(`--config-dir requires a path argument`);
+        }
+        {
+          const verdict = validateConfigDir(flags.configDir);
+          if (!verdict.ok) bail(verdict.error);
+        }
+        break;
+      default:
+        if (a.startsWith('--config-dir=')) {
+          flags.configDir = a.split('=')[1];
+          const verdict = validateConfigDir(flags.configDir);
+          if (!verdict.ok) bail(verdict.error);
+        } else if (a.startsWith('-')) {
+          bail(`unknown flag: ${a}`);
+        } else {
+          bail(`unexpected positional argument: ${a}`);
+        }
+    }
+  }
+
+  return { runtimes: Array.from(runtimes), flags };
+}
+
+function bail(msg) {
+  console.error(`  ${paint('red', '✗')} ${msg}`);
+  console.error(`  ${paint('dim', 'Run with --help for usage.')}`);
+  process.exit(1);
+}
+
+function expandTilde(p) {
+  if (p && p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+
+function loadAdapter(runtime) {
+  const adapterPath = path.join(__dirname, '..', 'adapters', `${runtime}.js`);
+  if (!fs.existsSync(adapterPath)) {
+    bail(`adapter not found for runtime: ${runtime}`);
+  }
+  return require(adapterPath);
+}
+
+function resolveScope(flags) {
+  if (flags.global && flags.local) bail('cannot use --global and --local together');
+  if (!flags.global && !flags.local) return 'local';
+  return flags.global ? 'global' : 'local';
+}
+
+async function main() {
+  const { runtimes, flags } = parseArgs(process.argv);
+
+  if (flags.version) {
+    console.log(`ultra-builder-pro-cli v${pkg.version}`);
+    return;
+  }
+
+  printBanner();
+
+  if (flags.help) {
+    printHelp();
+    return;
+  }
+
+  if (runtimes.length === 0) {
+    bail('no runtime selected; use --claude / --opencode / --codex / --gemini / --all');
+  }
+
+  const scope = resolveScope(flags);
+  const repoRoot = path.resolve(__dirname, '..');
+  const configDir = flags.configDir ? expandTilde(flags.configDir) : null;
+
+  const mode = flags.uninstall ? 'uninstall' : 'install';
+  console.log(`  ${paint('bold', 'Mode:')}     ${mode}`);
+  console.log(`  ${paint('bold', 'Scope:')}    ${scope}`);
+  console.log(`  ${paint('bold', 'Runtimes:')} ${runtimes.join(', ')}`);
+  if (configDir) console.log(`  ${paint('bold', 'ConfigDir:')} ${configDir}`);
+  console.log();
+
+  const ctx = { repoRoot, scope, configDir, homeDir: os.homedir() };
+
+  let failed = 0;
+  for (const runtime of runtimes) {
+    const adapter = loadAdapter(runtime);
+    try {
+      console.log(`  ${paint('cyan', '▸')} ${runtime} — starting ${mode}...`);
+      await adapter[mode](ctx);
+      console.log(`  ${paint('green', '✓')} ${runtime} — ${mode} complete`);
+    } catch (err) {
+      failed++;
+      console.error(`  ${paint('red', '✗')} ${runtime} — ${mode} failed: ${err.message}`);
+      if (process.env.UBP_DEBUG) console.error(err.stack);
+    }
+  }
+
+  console.log();
+  if (failed > 0) {
+    console.error(`  ${paint('red', `${failed} runtime(s) failed`)}`);
+    process.exit(1);
+  }
+
+  // Phase 6.1 — RTK hook (soft dependency; install continues on absence).
+  if (mode === 'install') {
+    const rtk = require('../adapters/_shared/rtk-detect.cjs');
+    const result = rtk.installHook({ skip: flags.skipRtk, scope });
+    if (result.skipped) {
+      console.log(`  ${paint('dim', '⤼ rtk skipped (--skip-rtk)')}`);
+    } else if (result.available && result.initialized) {
+      console.log(`  ${paint('green', '✓')} rtk hook registered (${result.version})`);
+    } else if (result.available && !result.initialized) {
+      console.log(`  ${paint('yellow', '!')} rtk present but init failed: ${result.init_error}`);
+    } else {
+      console.log(`  ${paint('dim', '⤼ ' + result.hint.replace(/\n/g, '\n    '))}`);
+    }
+  }
+
+  console.log(`  ${paint('green', 'Done.')}`);
+}
+
+main().catch(err => {
+  console.error(paint('red', '  Fatal: ') + err.message);
+  if (process.env.UBP_DEBUG) console.error(err.stack);
+  process.exit(1);
+});

package/bin/orchestrator.js

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+
+/**
+ * ubp-orchestrator — Phase 5.4 daemon CLI.
+ *
+ * Subcommands:
+ *   run     foreground daemon (debug / test).
+ *   start   detached background daemon, writes .ultra/orchestrator.pid.
+ *   stop    reads pidfile, SIGTERM the process, deletes pidfile.
+ *   status  prints pidfile + running session summary.
+ *
+ * Opt-in gate: `start` and `run` require settings.json
+ * `orchestrator.auto_dispatch: true` — default off per PLAN Phase 5.4 AC.
+ *
+ * The daemon never launches real runtime children in this phase — session
+ * rows + git worktrees are created, external adapters (Phase 4) attach to
+ * the worktree out-of-band. command/args can be passed via env for testing.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const REPO_ROOT = process.env.UBP_REPO_ROOT || process.cwd();
+const PIDFILE = path.join(REPO_ROOT, '.ultra', 'orchestrator.pid');
+const LOGFILE = path.join(REPO_ROOT, '.ultra', 'orchestrator.log');
+const SETTINGS_FILES = [
+  path.join(REPO_ROOT, 'settings.json'),
+  path.join(REPO_ROOT, '.claude', 'settings.json'),
+];
+
+function readSettings() {
+  for (const f of SETTINGS_FILES) {
+    if (fs.existsSync(f)) {
+      try { return JSON.parse(fs.readFileSync(f, 'utf8')) || {}; }
+      catch { /* fall through */ }
+    }
+  }
+  return {};
+}
+
+function optInAllowed(settings) {
+  return !!(settings && settings.orchestrator && settings.orchestrator.auto_dispatch === true);
+}
+
+function parseRuntimes() {
+  const raw = process.env.UBP_ORCH_RUNTIMES || 'claude,opencode,codex,gemini';
+  return raw.split(',').map((s) => s.trim()).filter(Boolean);
+}
+
+function cmdRun(opts = {}) {
+  const settings = readSettings();
+  if (!opts.skipOptIn && !optInAllowed(settings)) {
+    process.stderr.write(
+      'orchestrator.auto_dispatch is not enabled in settings.json.\n' +
+      'Set {"orchestrator":{"auto_dispatch":true}} to opt in.\n',
+    );
+    process.exit(2);
+  }
+  const { initStateDb } = require('../mcp-server/lib/state-db.cjs');
+  const { runDaemon } = require('../orchestrator/daemon.cjs');
+  const { db } = initStateDb(path.join(REPO_ROOT, '.ultra', 'state.db'));
+  const handle = runDaemon({
+    db,
+    repoRoot: REPO_ROOT,
+    runtimes: parseRuntimes(),
+    pollMs: Number(process.env.UBP_ORCH_POLL_MS || 1000),
+    onError: (err) => process.stderr.write(`orchestrator error: ${err.message}\n`),
+  });
+
+  // Phase 6.4 — optional code-graph watcher (opt-in via settings or CLI).
+  const watcherEnabled =
+    opts.withGraphWatcher === true ||
+    !!(settings && settings.orchestrator && settings.orchestrator.graph_watcher === true);
+  let watcherHandle = null;
+  if (watcherEnabled) {
+    try {
+      const { startWatcher } = require('../orchestrator/code-graph-watcher.cjs');
+      const jsonlPath = path.join(REPO_ROOT, '.ultra', 'code-graph-events.jsonl');
+      fs.mkdirSync(path.dirname(jsonlPath), { recursive: true });
+      watcherHandle = startWatcher({
+        repoRoot: REPO_ROOT,
+        onBatch: (batch) => {
+          try { fs.appendFileSync(jsonlPath, JSON.stringify(batch) + '\n'); }
+          catch (err) { process.stderr.write(`graph-watcher write error: ${err.message}\n`); }
+        },
+      });
+      process.stderr.write(`orchestrator: graph-watcher enabled → ${jsonlPath}\n`);
+    } catch (err) {
+      process.stderr.write(`orchestrator: graph-watcher disabled (${err.message})\n`);
+    }
+  }
+
+  const shutdown = (signal) => {
+    process.stderr.write(`orchestrator received ${signal}, stopping\n`);
+    handle.stop();
+    if (watcherHandle) watcherHandle.stop();
+    try { db.close(); } catch (_) { /* ignore */ }
+    process.exit(0);
+  };
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.stderr.write(`orchestrator running (pollMs=${Number(process.env.UBP_ORCH_POLL_MS || 1000)}, runtimes=${parseRuntimes().join(',')})\n`);
+  // Keep process alive while the setInterval is unref'd.
+  setInterval(() => {}, 60000);
+}
+
+function cmdStart() {
+  const settings = readSettings();
+  if (!optInAllowed(settings)) {
+    process.stderr.write('orchestrator.auto_dispatch is not enabled; refusing to start.\n');
+    process.exit(2);
+  }
+  if (fs.existsSync(PIDFILE)) {
+    const existing = Number(fs.readFileSync(PIDFILE, 'utf8'));
+    try { process.kill(existing, 0); }
+    catch (_) { fs.unlinkSync(PIDFILE); }
+    if (fs.existsSync(PIDFILE)) {
+      process.stderr.write(`orchestrator already running (pid=${existing}).\n`);
+      process.exit(1);
+    }
+  }
+  fs.mkdirSync(path.dirname(PIDFILE), { recursive: true });
+  const out = fs.openSync(LOGFILE, 'a');
+  const err = fs.openSync(LOGFILE, 'a');
+  const child = spawn(process.execPath, [__filename, 'run'], {
+    detached: true,
+    stdio: ['ignore', out, err],
+    env: { ...process.env, UBP_REPO_ROOT: REPO_ROOT },
+  });
+  child.unref();
+  fs.writeFileSync(PIDFILE, String(child.pid));
+  process.stdout.write(`orchestrator started (pid=${child.pid}, log=${LOGFILE})\n`);
+}
+
+function cmdStop() {
+  if (!fs.existsSync(PIDFILE)) {
+    process.stderr.write('no pidfile found; orchestrator not running.\n');
+    process.exit(1);
+  }
+  const pid = Number(fs.readFileSync(PIDFILE, 'utf8'));
+  try { process.kill(pid, 'SIGTERM'); }
+  catch (err) {
+    if (err.code === 'ESRCH') {
+      process.stderr.write(`pid ${pid} already dead; cleaning pidfile.\n`);
+      fs.unlinkSync(PIDFILE);
+      return;
+    }
+    throw err;
+  }
+  // Wait briefly for the process to exit, then clean up.
+  setTimeout(() => {
+    try { process.kill(pid, 0); }
+    catch (_) { /* dead; good */ }
+    if (fs.existsSync(PIDFILE)) fs.unlinkSync(PIDFILE);
+    process.stdout.write(`orchestrator stopped (pid=${pid})\n`);
+  }, 200);
+}
+
+function cmdStatus() {
+  const out = { pidfile: PIDFILE, running: false };
+  if (fs.existsSync(PIDFILE)) {
+    const pid = Number(fs.readFileSync(PIDFILE, 'utf8'));
+    try { process.kill(pid, 0); out.pid = pid; out.running = true; }
+    catch (_) { out.pid = pid; out.running = false; out.note = 'pidfile stale'; }
+  }
+  // Session summary.
+  try {
+    const Database = require('better-sqlite3');
+    const dbPath = path.join(REPO_ROOT, '.ultra', 'state.db');
+    if (fs.existsSync(dbPath)) {
+      const db = new Database(dbPath, { readonly: true });
+      const counts = db.prepare(
+        "SELECT status, COUNT(*) AS n FROM sessions GROUP BY status",
+      ).all();
+      out.sessions = {};
+      for (const r of counts) out.sessions[r.status] = r.n;
+      db.close();
+    }
+  } catch (err) {
+    out.session_error = err.message;
+  }
+  process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+}
+
+function usage() {
+  process.stderr.write(
+    'usage: ubp-orchestrator <run|start|stop|status>\n' +
+    '\n' +
+    '  run     foreground daemon (requires opt-in)\n' +
+    '  start   detached background daemon (requires opt-in)\n' +
+    '  stop    terminate running daemon\n' +
+    '  status  print pid + session counts\n',
+  );
+}
+
+const argv = process.argv.slice(2);
+const subcommand = argv[0];
+const runOpts = { withGraphWatcher: argv.includes('--with-graph-watcher') };
+switch (subcommand) {
+  case 'run':    cmdRun(runOpts); break;
+  case 'start':  cmdStart();      break;
+  case 'stop':   cmdStop();       break;
+  case 'status': cmdStatus();     break;
+  case '-h':
+  case '--help':
+  case 'help':
+    usage(); process.exit(0);
+    break;
+  default:
+    usage(); process.exit(1);
+}

package/commands/learn.md

@@ -0,0 +1,41 @@
+---
+description: Extract one reusable pattern into a valid user skill after explicit approval
+argument-hint: "[pattern-name]"
+allowed-tools: Read, Write, Grep, Glob, AskUserQuestion
+model: opus
+workflow-ref: "@skills/learn/SKILL.md"
+---
+
+# /learn
+
+## 目标
+
+扫当前会话挑一个最值得保存的「可复用模式」，以 Speculation 级别写到
+`~/.claude/skills/learned-<slug>-unverified/SKILL.md`。写入前必问用户确认。
+
+## 参数
+
+| 位 | 含义 | 缺省 |
+|----|------|------|
+| `$1` | pattern 文件名建议 slug | 由 skill 自动生成 |
+
+## Workflow
+
+完整 5 步见 `@skills/learn/SKILL.md`（review → pick one → draft → 用户确认 → write）。
+
+**命令入口做的事**：
+1. 回溯会话找可提炼的模式（错误修复 / 调试套路 / workaround / 项目级惯例）
+2. 选一个价值最高的（不是多个 — 一个文件一个模式）
+3. 按模板起草 → 直接询问用户选择 Save/Edit/Cancel
+4. 保存到 `~/.claude/skills/learned-<slug>-unverified/SKILL.md`（不覆盖已存在目录）
+
+## 用法
+
+```bash
+/learn                       # 自动挑
+/learn supabase-rls-debug    # 指定文件名 slug
+```
+
+## 下一步
+
+用户以后 review 后手动去掉 `_unverified` 后缀升为 Inference；多次成功使用后升为 Fact。

package/commands/ultra-deliver.md

@@ -0,0 +1,45 @@
+---
+description: Release preparation — docs + build + version bump + tag + push, gated by /ultra-test pass
+argument-hint: "[version-type]"
+allowed-tools: Task, Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion
+model: opus
+workflow-ref: "@skills/ultra-deliver/SKILL.md"
+cli_fallback: "direct user interaction"
+---
+
+# /ultra-deliver
+
+## 目标
+
+`/ultra-test` 绿灯后做发布准备：更新 CHANGELOG + technical-debt + README →
+production build → 版本号 + git tag + push。写 `.ultra/delivery-report.json`。
+
+## 参数
+
+| 位 | 含义 | 缺省 |
+|----|------|------|
+| `$1` | 版本跳跃（`patch`/`minor`/`major`） | 按 commit 类型自动判断 |
+
+## Workflow
+
+完整 5 步见 `@skills/ultra-deliver/SKILL.md`（validations → 文档 → build → 版本发布 → 产物报告）。
+
+**命令入口做的事**：
+1. 读 `.ultra/test-report.json` 验 `passed=true` + `git_commit === HEAD`
+2. `git status` 清洁检查；不干净 → 通过 Host 原生提问界面选处理方式
+3. 驱动 skill 跑文档 + build + 版本 + tag + push
+4. 写 `.ultra/delivery-report.json`
+5. 输出 release summary
+
+## 用法
+
+```bash
+/ultra-deliver              # 自动判断版本号
+/ultra-deliver major        # 强制 major bump（breaking changes）
+/ultra-deliver patch        # 强制 patch
+```
+
+## 下一步
+
+部署到 Railway / Vercel，或在 release channel 广播。`delivery-report.json` 里
+`pushed=true` 后即可视作发布完成。

package/commands/ultra-dev.md

@@ -0,0 +1,50 @@
+---
+description: Agile development execution — one task through TDD + review gate, writing state via MCP task.update
+argument-hint: "[task-id]"
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Task, AskUserQuestion, Skill
+model: opus
+workflow-ref: "@skills/ultra-dev/SKILL.md"
+mcp_tools_required:
+  - task.update
+  - task.get
+  - task.list
+cli_fallback: "task update"
+---
+
+# /ultra-dev
+
+## 目标
+
+把一个 task 从 `pending` 推到 `completed`：进入 feature 分支 → RED/GREEN/REFACTOR
+TDD → 质量门 → `/ultra-review all` → 完成 → commit/merge。**单写**：状态只通过
+MCP `task.update` 改一次；projector 自动更新 tasks.json + context-md frontmatter。
+
+## 参数
+
+| 位 | 含义 | 缺省 |
+|----|------|------|
+| `$1` | task id | 拓扑序第一个 `pending` |
+
+## Workflow
+
+完整 8 步流程见 `@skills/ultra-dev/SKILL.md`（Resume Check → Design Gate → 选 task →
+状态 in_progress → 环境 → TDD → 质量门 → checkpoint → review → 完成 → commit/merge → report）。
+
+**命令入口做的事**：
+1. 读 `.ultra/workflow-state.json` 决定新跑 vs resume
+2. 首跑通过 Host 原生提问触发 Design Approval Gate
+3. 驱动 skill 走 TDD + review 循环；状态仅通过 MCP `task.update`（双写消除）
+4. Step 4.5 review 通过 `/ultra-review` 和 Host 原生 subagent 执行
+5. Step 4.4 pre-review checkpoint 写入 workflow-state.json，不依赖 `/compact`
+
+## 用法
+
+```bash
+/ultra-dev          # 自动选下一个 pending task
+/ultra-dev 3        # 直接做 task 3
+```
+
+## 下一步
+
+单个 task 完成后自动提示下一个 `/ultra-dev`；所有 Walking Skeleton +
+critical-path task 完成 → `/ultra-test` 做交付前质量审计。

package/commands/ultra-init.md

@@ -0,0 +1,51 @@
+---
+description: Initialize Ultra Builder Pro project — scaffold .ultra/, seed tasks.json, optional git
+argument-hint: <name> <type> <stack> [git]
+allowed-tools: Read, Write, Bash, Grep, Glob, AskUserQuestion
+model: opus
+workflow-ref: "@skills/ultra-init/SKILL.md"
+mcp_tools_required:
+  - task.init_project
+cli_fallback: "task init-project"
+---
+
+# /ultra-init
+
+## 目标
+
+搭 `.ultra/` 骨架（specs + tasks + docs + reports）；写入带元数据的 `tasks.json`；
+按需初始化 git。4 个 runtime 行为一致，不依赖 Claude 独占工具。
+
+## 参数
+
+| 位 | 含义 | 缺省 |
+|----|------|------|
+| `$1` | 项目名 | 当前目录名 |
+| `$2` | 项目类型（`web`/`api`/`cli`/`fullstack`/`other`） | 从 package 文件识别 |
+| `$3` | 技术栈（逗号分隔） | 从 package 文件识别 |
+| `$4` | `git` → 初始化 git | 检测已有 `.git/` 时询问 |
+
+## Workflow
+
+完整流程见 `@skills/ultra-init/SKILL.md`（4 步：状态检测 → 参数补全 →
+`task.init_project` 拉起骨架 → git 集成）。
+
+**命令入口做的事**：
+1. 解析 `$1-$4`，补缺省
+2. 探测 runtime 能力：优先走 MCP `task.init_project`；不可达时退回 `ultra-tools task init-project`
+3. 按 skill 的 4 步工作流推进
+4. 完成后提示下一步命令
+
+## 用法
+
+```bash
+/ultra-init                          # 交互模式（自动识别）
+/ultra-init my-app                   # 带项目名
+/ultra-init my-app api               # 带类型
+/ultra-init my-app fullstack react,postgres git  # 完整 + git
+```
+
+## 下一步
+
+**CRITICAL**：跑 `/ultra-research` 做 17 步 discovery 把 spec 填满，
+**然后**才跑 `/ultra-plan` 生成任务。直接 plan 会产出基于模糊需求的任务。