specrails-core 3.5.3 → 3.7.0

package/README.md

@@ -13,7 +13,7 @@ One command gives your repo a full team of specialized AI agents: architect, dev
 
 ```bash
 claude plugin install sr   # Claude Code plugin (recommended)
-/specrails:setup                  # configure for your project
+/specrails:enrich                 # configure for your project
 ```
 
 > **Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Codex CLI](https://github.com/openai/codex) (choose one), git
@@ -39,7 +39,7 @@ Every artifact (agents, rules, personas) is generated **specifically for your pr
 
 ```bash
 claude plugin install sr   # install the sr plugin
-/specrails:setup                  # run the 5-phase wizard (~5 min)
+/specrails:enrich                 # run the 5-phase wizard (~5 min)
 ```
 
 Updates automatically: `claude plugin update sr`
@@ -47,8 +47,8 @@ Updates automatically: `claude plugin update sr`
 ### Scaffold method (alternative)
 
 ```bash
-npx specrails-core@latest init --root-dir .   # copy project files
-/specrails:setup                                      # run the wizard
+npx specrails-core@latest init --root-dir .   # TUI agent selection + install files
+/specrails:enrich --from-config               # run AI analysis using your config
 ```
 
 ### Start building
@@ -71,10 +71,10 @@ That's it. The pipeline takes over.
 | **What it contains** | Agents, skills, hooks, references | Nothing — project data only |
 | **Install** | `claude plugin install sr` | `npx specrails-core@latest init` |
 | **Updates** | `claude plugin update sr` | Re-run npx |
-| **Project data** | Generated by `/specrails:setup` into `.specrails/` | Same |
+| **Project data** | Generated by `/specrails:enrich` into `.specrails/` | Same |
 | **Use case** | Recommended for most projects | When you need full offline control |
 
-The plugin contains the logic (agent prompts, skills, commands). Running `/specrails:setup` generates the project-specific data files (~8–10 files in `.specrails/`) — config, personas, memory, pipeline state. These are yours to edit and commit.
+The plugin contains the logic (agent prompts, skills, commands). Running `/specrails:enrich` generates the project-specific data files (~8–10 files in `.specrails/`) — config, personas, memory, pipeline state. These are yours to edit and commit.
 
 ---
 
@@ -89,7 +89,7 @@ The plugin contains the logic (agent prompts, skills, commands). Running `/specr
 | **Skills** | Plugin | OpenSpec skills (`/opsx:*`) included |
 | **Hooks & References** | Plugin | Agent hooks, reference docs |
 
-### Project data (generated by `/specrails:setup` — lives in your repo)
+### Project data (generated by `/specrails:enrich` — lives in your repo)
 
 | Category | Files | Purpose |
 |----------|-------|---------|
@@ -198,7 +198,7 @@ specrails-core ships with a built-in ticket system — no GitHub account or exte
 
 Tickets live in `.specrails/local-tickets.json` alongside your code. They're plain JSON and git-friendly.
 
-**Local tickets are the default.** The `/specrails:setup` wizard defaults to local tickets and skips GitHub/JIRA credential setup unless you opt in.
+**Local tickets are the default.** The `/specrails:enrich` wizard defaults to local tickets and skips GitHub/JIRA credential setup unless you opt in.
 
 ```bash
 /specrails:implement #1, #4           # implement by ticket ID
@@ -246,7 +246,7 @@ The plugin method has no Node.js requirement. The scaffold method checks for pre
 
 ## Supported stacks
 
-Stack-agnostic. The `/specrails:setup` wizard detects and adapts to whatever you're running:
+Stack-agnostic. The `/specrails:enrich` wizard detects and adapts to whatever you're running:
 
 **Backend:** Python/FastAPI, Node/Express, Go/Gin, Rust/Actix, Java/Spring, Ruby/Rails, .NET
 **Frontend:** React, Vue, Angular, Svelte, Next.js, Nuxt
@@ -272,8 +272,8 @@ Stack-agnostic. The `/specrails:setup` wizard detects and adapts to whatever you
 **Can I customize the agents after installation?**
 With the plugin method, project data files in `.specrails/` are yours to edit — personas, rules, config. With the scaffold method, `.claude/` agent files are also editable. To update plugin logic, run `claude plugin update sr`.
 
-**Can I re-run setup?**
-Run `/specrails:setup` again at any time to regenerate or update project data files.
+**Can I re-run the wizard?**
+Run `/specrails:enrich` again at any time to regenerate or update project data files.
 
 **Plugin vs scaffold — which should I use?**
 Plugin is recommended: it has no Node.js requirement, updates automatically, and separates logic from project data. Use scaffold if you need full offline control or want to version the agent prompts themselves.

package/bin/specrails-core.js

@@ -9,6 +9,7 @@ const COMMANDS = {
   update: "update.sh",
   doctor: "bin/doctor.sh",
   "perf-check": "bin/perf-check.sh",
+  enrich: null,
 };
 
 const args = process.argv.slice(2);
@@ -18,31 +19,38 @@ if (!subcommand) {
   console.log(`specrails-core — Agent Workflow System for Claude Code
 
 Usage:
-  specrails-core init       [--root-dir <path>]     Install into a repository
-  specrails-core update     [--only <component>]    Update an existing installation
-  specrails-core doctor                             Run health checks
-  specrails-core perf-check [--files <list>]        Performance regression check (CI)
+  specrails-core init       [--root-dir <path>] [--yes|-y]   Install into a repository
+  specrails-core update     [--only <component>]             Update an existing installation
+  specrails-core doctor                                      Run health checks
+  specrails-core perf-check [--files <list>]                 Performance regression check (CI)
+  specrails-core enrich     [--from-config <path>]           Run /specrails:enrich via Claude CLI
+
+Flags for init:
+  --root-dir <path>   Target repository path (default: current directory)
+  --yes | -y          Non-interactive; use defaults, skip TUI
+  --provider <value>  Force provider: claude or codex
+  --no-direct         Skip TUI; use the legacy interactive bash installer
+  --from-config       Skip TUI; use existing .specrails/install-config.yaml
 
 More info: https://github.com/fjpulidop/specrails-core`);
   process.exit(0);
 }
 
-const script = COMMANDS[subcommand];
-
-if (!script) {
+if (!(subcommand in COMMANDS)) {
   console.error(`Unknown command: ${subcommand}\n`);
-  console.error("Available commands: init, update, doctor, perf-check");
+  console.error("Available commands: init, update, doctor, perf-check, enrich");
   process.exit(1);
 }
 
-// Allowlisted flags per subcommand (defense-in-depth — spawnSync already
-// prevents shell injection, but an explicit allowlist rejects unknown flags
-// before the shell script is ever invoked).
+const script = COMMANDS[subcommand];
+
+// Allowlisted flags per subcommand
 const ALLOWED_FLAGS = {
-  init: ["--root-dir", "--yes", "-y"],
+  init: ["--root-dir", "--yes", "-y", "--provider", "--no-direct", "--from-config", "--quick", "--hub-json", "--agent-teams"],
   update: ["--only"],
   doctor: [],
   "perf-check": ["--files", "--context"],
+  enrich: ["--from-config", "--quick"],
 };
 
 const subargs = args.slice(1);
@@ -55,7 +63,92 @@ for (const arg of subargs) {
   }
 }
 
-const result = spawnSync("bash", [resolve(ROOT, script), ...subargs], {
+// ─── enrich subcommand ───────────────────────────────────────────────────────
+// Launches `claude --command "/specrails:enrich [flags]"` so the AI-powered
+// enrichment runs inside Claude Code with full model access.
+
+if (subcommand === "enrich") {
+  const enrichFlags = subargs.join(" ");
+  const claudeCmd = `/specrails:enrich${enrichFlags ? " " + enrichFlags : ""}`;
+  const claudeResult = spawnSync("claude", ["--command", claudeCmd, "--dangerously-skip-permissions"], {
+    stdio: "inherit",
+    cwd: process.cwd(),
+  });
+
+  if (claudeResult.error) {
+    console.error(
+      "\nFailed to launch Claude CLI for enrich:",
+      claudeResult.error.message,
+      "\nEnsure Claude Code is installed: npm install -g @anthropic-ai/claude-code\n"
+    );
+    process.exit(1);
+  }
+
+  process.exit(claudeResult.status ?? (claudeResult.error ? 1 : 0));
+}
+
+// ─── Direct mode (TUI) for `init` ─────────────────────────────────────────────
+//
+// Default behaviour: run the Node.js TUI to collect agent/model configuration,
+// write .specrails/install-config.yaml, then hand off to install.sh.
+//
+// Opt-out with: --no-direct   (legacy interactive bash installer)
+//               --from-config (config already on disk; skip TUI)
+//               --yes / -y    (write default config, no prompts)
+
+const isInit       = subcommand === "init";
+const hasNoTui     = subargs.includes("--no-direct") || subargs.includes("--from-config");
+const autoYes      = subargs.includes("--yes") || subargs.includes("-y");
+const useTui       = isInit && !hasNoTui;
+
+if (useTui) {
+  // Resolve the target directory for the TUI
+  const rootDirIdx = subargs.indexOf("--root-dir");
+  const rootDir    = rootDirIdx >= 0 ? resolve(subargs[rootDirIdx + 1]) : process.cwd();
+
+  // Build TUI args: pass rootDir + --yes if set
+  const tuiArgs = [resolve(ROOT, "bin/tui-installer.mjs"), rootDir];
+  if (autoYes) tuiArgs.push("--yes");
+
+  const tuiResult = spawnSync("node", tuiArgs, {
+    stdio: "inherit",
+    cwd: process.cwd(),
+  });
+
+  if (tuiResult.error) {
+    // @inquirer/prompts not installed (e.g. during development without npm install)
+    console.error(
+      "\nFailed to launch TUI installer:",
+      tuiResult.error.message,
+      "\nRun: npm install   or use --no-direct for the legacy installer.\n"
+    );
+    process.exit(1);
+  }
+
+  if (tuiResult.status !== 0) {
+    process.exit(tuiResult.status ?? 1);
+  }
+
+  // TUI succeeded — run install.sh with --from-config so it reads provider/
+  // agent_teams from install-config.yaml rather than prompting interactively.
+  const installArgs = subargs
+    .filter(a => a !== "--no-direct") // strip internal flags
+    .concat(["--yes", "--from-config"]);
+
+  const result = spawnSync("bash", [resolve(ROOT, script), ...installArgs], {
+    stdio: "inherit",
+    cwd: process.cwd(),
+  });
+
+  process.exit(result.status ?? (result.error ? 1 : 0));
+}
+
+// ─── Legacy / non-TUI path ────────────────────────────────────────────────────
+
+// Strip only --no-direct (internal flag) before passing args to the shell script
+const cleanArgs = subargs.filter(a => a !== "--no-direct");
+
+const result = spawnSync("bash", [resolve(ROOT, script), ...cleanArgs], {
   stdio: "inherit",
   cwd: process.cwd(),
 });

package/bin/tui-installer.mjs

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+/**
+ * specrails TUI installer — Phase 1
+ * Interactive agent selection + model configuration using @inquirer/prompts.
+ * Writes .specrails/install-config.yaml to the target repo directory.
+ *
+ * Usage: node bin/tui-installer.mjs [rootDir] [--yes]
+ *   rootDir  - target repo directory (default: cwd)
+ *   --yes    - skip TUI, write defaults immediately
+ */
+
+import { checkbox, select, input, Separator } from '@inquirer/prompts';
+import { writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { resolve } from 'node:path';
+
+// ─── Agent registry ───────────────────────────────────────────────────────────
+
+const AGENTS = [
+  // Architecture
+  { id: 'sr-architect',          category: 'Architecture', description: 'Architecture design, change specs, implementation planning' },
+  // Development
+  { id: 'sr-developer',          category: 'Development',  description: 'Full-stack implementation across all layers' },
+  { id: 'sr-frontend-developer', category: 'Development',  description: 'Frontend implementation (React, Vue, Angular, etc.)' },
+  { id: 'sr-backend-developer',  category: 'Development',  description: 'Backend specialization (APIs, databases, services)' },
+  // Review
+  { id: 'sr-reviewer',           category: 'Review',       description: 'General code review — the final quality gate' },
+  { id: 'sr-frontend-reviewer',  category: 'Review',       description: 'Frontend review (UI, accessibility, performance)' },
+  { id: 'sr-backend-reviewer',   category: 'Review',       description: 'Backend review (APIs, security, scalability)' },
+  { id: 'sr-security-reviewer',  category: 'Review',       description: 'Security analysis — OWASP, vulnerabilities, hardening' },
+  { id: 'sr-performance-reviewer', category: 'Review',     description: 'Performance analysis — profiling, bottlenecks, optimization' },
+  // Product
+  { id: 'sr-product-manager',    category: 'Product',      description: 'Product discovery, VPC personas, backlog management' },
+  { id: 'sr-product-analyst',    category: 'Product',      description: 'Backlog analysis, spec gap analysis, reporting' },
+  // Utilities
+  { id: 'sr-test-writer',        category: 'Utilities',    description: 'Comprehensive test generation (unit, integration, E2E)' },
+  { id: 'sr-doc-sync',           category: 'Utilities',    description: 'Documentation sync — keeps docs aligned with code' },
+  { id: 'sr-merge-resolver',     category: 'Utilities',    description: 'Merge conflict resolution with context awareness' },
+];
+
+const ALL_AGENT_IDS = AGENTS.map(a => a.id);
+
+const DEFAULT_SELECTED = new Set([
+  'sr-architect',
+  'sr-developer',
+  'sr-reviewer',
+  'sr-test-writer',
+  'sr-product-manager',
+]);
+
+// ─── Model presets ────────────────────────────────────────────────────────────
+
+const MODEL_PRESETS = {
+  balanced: {
+    label:       'Balanced (recommended) — Sonnet for all agents',
+    defaults:    'sonnet',
+    overrides:   {},
+  },
+  budget: {
+    label:       'Budget — Haiku for all agents (3× cheaper, faster)',
+    defaults:    'haiku',
+    overrides:   {},
+  },
+  max: {
+    label:       'Max quality — Opus for architect + PM, Sonnet for rest',
+    defaults:    'sonnet',
+    overrides:   { 'sr-architect': 'opus', 'sr-product-manager': 'opus' },
+  },
+};
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function detectProvider() {
+  let hasClaude = false;
+  let hasCodex  = false;
+  try { execSync('claude --version', { stdio: 'ignore' }); hasClaude = true; } catch { /* not installed */ }
+  try { execSync('codex --version',  { stdio: 'ignore' }); hasCodex  = true; } catch { /* not installed */ }
+  return { hasClaude, hasCodex };
+}
+
+function detectGitRoot(dir) {
+  try {
+    return execSync('git rev-parse --show-toplevel', { cwd: dir, stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString()
+      .trim();
+  } catch {
+    return dir;
+  }
+}
+
+function buildCheckboxChoices() {
+  const choices = [];
+  let currentCategory = null;
+  for (const agent of AGENTS) {
+    if (agent.category !== currentCategory) {
+      if (currentCategory !== null) choices.push(new Separator(''));
+      choices.push(new Separator(`── ${agent.category} ${'─'.repeat(Math.max(0, 46 - agent.category.length))}`));
+      currentCategory = agent.category;
+    }
+    choices.push({
+      value:   agent.id,
+      name:    `${agent.id.padEnd(28)} ${agent.description}`,
+      checked: DEFAULT_SELECTED.has(agent.id),
+    });
+  }
+  return choices;
+}
+
+function writeInstallConfig(specrailsDir, cfg) {
+  if (!existsSync(specrailsDir)) mkdirSync(specrailsDir, { recursive: true });
+
+  const overridesEntries = Object.entries(cfg.modelOverrides);
+  const overridesYaml   = overridesEntries.length > 0
+    ? '\n' + overridesEntries.map(([k, v]) => `    ${k}: ${v}`).join('\n')
+    : ' {}';
+
+  const yaml = [
+    '# specrails install config — generated by TUI installer',
+    '# Re-run: npx specrails-core@latest init  to regenerate',
+    `version: 1`,
+    `provider: ${cfg.provider}`,
+    `tier: ${cfg.tier}`,
+    `agents:`,
+    `  selected: [${cfg.selectedAgents.join(', ')}]`,
+    `  excluded: [${cfg.excludedAgents.join(', ')}]`,
+    `models:`,
+    `  preset: ${cfg.modelPreset}`,
+    `  defaults: { model: ${cfg.modelDefaults} }`,
+    `  overrides:${overridesYaml}`,
+    `quick_context:`,
+    `  product_description: "${cfg.productDescription.replace(/"/g, '\\"')}"`,
+    `  target_users: "${cfg.targetUsers.replace(/"/g, '\\"')}"`,
+    `agent_teams: ${cfg.agentTeams}`,
+    '',
+  ].join('\n');
+
+  writeFileSync(resolve(specrailsDir, 'install-config.yaml'), yaml, 'utf8');
+}
+
+function writeDefaultConfig(specrailsDir, provider) {
+  const defaultSelected = [...DEFAULT_SELECTED];
+  const defaultExcluded = ALL_AGENT_IDS.filter(id => !DEFAULT_SELECTED.has(id));
+  writeInstallConfig(specrailsDir, {
+    provider,
+    tier:           'full',
+    selectedAgents: defaultSelected,
+    excludedAgents: defaultExcluded,
+    modelPreset:    'balanced',
+    modelDefaults:  'sonnet',
+    modelOverrides: {},
+    productDescription: '',
+    targetUsers:    '',
+    agentTeams:     false,
+  });
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+async function run() {
+  const rawArgs  = process.argv.slice(2);
+  const autoYes  = rawArgs.includes('--yes') || rawArgs.includes('-y');
+  const rootArg  = rawArgs.find(a => !a.startsWith('-'));
+  const inputDir = rootArg ? resolve(rootArg) : process.cwd();
+  const rootDir  = detectGitRoot(inputDir);
+
+  const specrailsDir = resolve(rootDir, '.specrails');
+
+  console.log('\n╔══════════════════════════════════════════════╗');
+  console.log('║      specrails — Direct Install (v1)         ║');
+  console.log('║  Configure your AI agent workflow system     ║');
+  console.log('╚══════════════════════════════════════════════╝\n');
+
+  // Auto-yes: write defaults and exit
+  if (autoYes) {
+    const { hasClaude, hasCodex } = detectProvider();
+    const provider = hasCodex && !hasClaude ? 'codex' : 'claude';
+    writeDefaultConfig(specrailsDir, provider);
+    console.log(`  ✓ Default config written to .specrails/install-config.yaml`);
+    console.log(`  ✓ Provider: ${provider}, Tier: full, Agents: ${DEFAULT_SELECTED.size}/${ALL_AGENT_IDS.length}, Preset: balanced\n`);
+    return;
+  }
+
+  // ── Step 1: Provider ────────────────────────────────────────────────────────
+
+  const { hasClaude, hasCodex } = detectProvider();
+  let provider;
+
+  if (hasClaude && hasCodex) {
+    provider = await select({
+      message: 'Which AI provider will you use?',
+      choices: [
+        { value: 'claude', name: 'Claude Code (recommended)' },
+        { value: 'codex',  name: 'Codex' },
+      ],
+    });
+  } else if (hasCodex) {
+    provider = 'codex';
+    console.log('  → Provider: codex (auto-detected)\n');
+  } else {
+    provider = 'claude';
+    if (hasClaude) {
+      console.log('  → Provider: claude (auto-detected)\n');
+    } else {
+      console.log('  → Provider: claude (default — claude CLI not found, install it at claude.ai/download)\n');
+    }
+  }
+
+  // ── Step 2: Installation tier ───────────────────────────────────────────────
+
+  const tier = await select({
+    message: 'Installation tier:',
+    choices: [
+      {
+        value:       'full',
+        name:        'Full — AI-powered setup (recommended)',
+        description: 'After install, run /specrails:enrich to AI-customize all agents for your codebase',
+      },
+      {
+        value:       'quick',
+        name:        'Quick — Template-only install',
+        description: 'Agents installed with sensible defaults. No AI step required.',
+      },
+    ],
+  });
+
+  // ── Step 3: Agent selection ─────────────────────────────────────────────────
+
+  console.log('\n  Select agents to install.  Space = toggle,  a = all/none,  Enter = confirm.\n');
+
+  const selectedAgents = await checkbox({
+    message: 'Agents to install:',
+    choices: buildCheckboxChoices(),
+    validate: (selected) => selected.length > 0 || 'Select at least one agent.',
+  });
+
+  const excludedAgents = ALL_AGENT_IDS.filter(id => !selectedAgents.includes(id));
+
+  // ── Step 4: Model preset ────────────────────────────────────────────────────
+
+  const modelPreset = await select({
+    message: 'Model configuration:',
+    choices: Object.entries(MODEL_PRESETS).map(([key, val]) => ({
+      value:       key,
+      name:        `${key.padEnd(10)} ${val.label}`,
+    })),
+  });
+
+  const { defaults: modelDefaults, overrides: modelOverrides } = MODEL_PRESETS[modelPreset];
+
+  // ── Step 5: Agent Teams (Claude only) ──────────────────────────────────────
+
+  let agentTeams = false;
+  if (provider === 'claude') {
+    agentTeams = await select({
+      message: 'Install Agent Teams commands? (experimental)',
+      choices: [
+        { value: false, name: 'No  — standard single-agent workflow (recommended)' },
+        { value: true,  name: 'Yes — /specrails:team-review and :team-debug  (requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)' },
+      ],
+    });
+  }
+
+  // ── Step 6: Quick context ───────────────────────────────────────────────────
+
+  console.log('\n  Quick context helps specrails personalize agents for your project.\n');
+
+  const productDescription = await input({
+    message: 'Product description (2–3 sentences):',
+    validate: (v) => v.trim().length > 0 || 'Please enter a brief product description.',
+  });
+
+  const targetUsers = await input({
+    message: 'Target users (who will use this product?):',
+    validate: (v) => v.trim().length > 0 || 'Please describe your target users.',
+  });
+
+  // ── Write config ────────────────────────────────────────────────────────────
+
+  writeInstallConfig(specrailsDir, {
+    provider,
+    tier,
+    selectedAgents,
+    excludedAgents,
+    modelPreset,
+    modelDefaults,
+    modelOverrides,
+    productDescription: productDescription.trim(),
+    targetUsers:        targetUsers.trim(),
+    agentTeams,
+  });
+
+  console.log(`\n  ✓ Config written to .specrails/install-config.yaml`);
+  console.log(`  ✓ Provider: ${provider} | Tier: ${tier} | Agents: ${selectedAgents.length}/${ALL_AGENT_IDS.length} | Preset: ${modelPreset}`);
+  if (tier === 'full') {
+    console.log(`\n  Next: run /specrails:enrich --from-config inside ${provider} to AI-customize your agents.\n`);
+  } else {
+    console.log(`\n  Agents will be installed with template defaults.\n`);
+  }
+}
+
+run().catch(err => {
+  // Graceful Ctrl+C handling
+  if (err.name === 'ExitPromptError' || (err.message && err.message.includes('User force closed'))) {
+    console.error('\n  Installation cancelled by user.\n');
+    process.exit(130);
+  }
+  console.error('\n  TUI error:', err.message);
+  process.exit(1);
+});