specrails-core 3.8.1 → 4.0.1

package/bin/specrails-core.js

@@ -10,11 +10,20 @@ const COMMANDS = {
   doctor: "bin/doctor.sh",
   "perf-check": "bin/perf-check.sh",
   enrich: null,
+  version: null,
 };
 
 const args = process.argv.slice(2);
 const subcommand = args[0];
 
+// ─── Global --version / -V flag ──────────────────────────────────────────────
+
+if (args.includes("--version") || args.includes("-V")) {
+  const pkg = require(resolve(ROOT, "package.json"));
+  console.log(`specrails-core v${pkg.version}`);
+  process.exit(0);
+}
+
 if (!subcommand) {
   console.log(`specrails-core — Agent Workflow System for Claude Code
 
@@ -24,6 +33,7 @@ Usage:
   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
+  specrails-core version                                     Show installed version
 
 Flags for init:
   --root-dir <path>   Target repository path (default: current directory)
@@ -32,13 +42,16 @@ Flags for init:
   --no-direct         Skip TUI; use the legacy interactive bash installer
   --from-config       Skip TUI; use existing .specrails/install-config.yaml
 
+Global flags:
+  --version | -V    Show installed version
+
 More info: https://github.com/fjpulidop/specrails-core`);
   process.exit(0);
 }
 
 if (!(subcommand in COMMANDS)) {
   console.error(`Unknown command: ${subcommand}\n`);
-  console.error("Available commands: init, update, doctor, perf-check, enrich");
+  console.error("Available commands: init, update, doctor, perf-check, enrich, version");
   process.exit(1);
 }
 
@@ -51,6 +64,7 @@ const ALLOWED_FLAGS = {
   doctor: [],
   "perf-check": ["--files", "--context"],
   enrich: ["--from-config", "--quick"],
+  version: [],
 };
 
 const subargs = args.slice(1);
@@ -63,6 +77,14 @@ for (const arg of subargs) {
   }
 }
 
+// ─── version subcommand ──────────────────────────────────────────────────────
+
+if (subcommand === "version") {
+  const pkg = require(resolve(ROOT, "package.json"));
+  console.log(`specrails-core v${pkg.version}`);
+  process.exit(0);
+}
+
 // ─── enrich subcommand ───────────────────────────────────────────────────────
 // Launches `claude --command "/specrails:enrich [flags]"` so the AI-powered
 // enrichment runs inside Claude Code with full model access.

package/bin/tui-installer.mjs

@@ -9,11 +9,26 @@
  *   --yes    - skip TUI, write defaults immediately
  */
 
-import { checkbox, select, input, Separator } from '@inquirer/prompts';
+import { checkbox, select, Separator } from '@inquirer/prompts';
 import { writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { execSync } from 'node:child_process';
 import { resolve } from 'node:path';
 
+// ─── Alternate screen buffer (fullscreen mode) ──────────────────────────────
+
+function enterFullscreen() {
+  process.stdout.write('\x1b[?1049h'); // switch to alternate screen buffer
+  process.stdout.write('\x1b[H');      // move cursor to top-left
+}
+
+function exitFullscreen() {
+  process.stdout.write('\x1b[?1049l'); // restore original screen buffer
+}
+
+function clearScreen() {
+  process.stdout.write('\x1b[2J\x1b[H'); // clear screen + cursor to top
+}
+
 // ─── Agent registry ───────────────────────────────────────────────────────────
 
 const AGENTS = [
@@ -40,10 +55,17 @@ const AGENTS = [
 
 const ALL_AGENT_IDS = AGENTS.map(a => a.id);
 
-const DEFAULT_SELECTED = new Set([
+// Core agents are always installed and cannot be deselected.
+// The implementation pipeline (implement / batch-implement) depends on them.
+const CORE_AGENTS = new Set([
   'sr-architect',
   'sr-developer',
   'sr-reviewer',
+  'sr-merge-resolver',
+]);
+
+const DEFAULT_SELECTED = new Set([
+  ...CORE_AGENTS,
   'sr-test-writer',
   'sr-product-manager',
 ]);
@@ -97,10 +119,12 @@ function buildCheckboxChoices() {
       choices.push(new Separator(`── ${agent.category} ${'─'.repeat(Math.max(0, 46 - agent.category.length))}`));
       currentCategory = agent.category;
     }
+    const isCore = CORE_AGENTS.has(agent.id);
     choices.push({
       value:   agent.id,
-      name:    `${agent.id.padEnd(28)} ${agent.description}`,
+      name:    `${agent.id.padEnd(28)} ${agent.description}${isCore ? ' (core)' : ''}`,
       checked: DEFAULT_SELECTED.has(agent.id),
+      disabled: isCore ? 'core — always installed' : false,
     });
   }
   return choices;
@@ -127,9 +151,6 @@ function writeInstallConfig(specrailsDir, cfg) {
     `  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');
@@ -148,8 +169,6 @@ function writeDefaultConfig(specrailsDir, provider) {
     modelPreset:    'balanced',
     modelDefaults:  'sonnet',
     modelOverrides: {},
-    productDescription: '',
-    targetUsers:    '',
     agentTeams:     false,
   });
 }
@@ -165,12 +184,7 @@ async function run() {
 
   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
+  // Auto-yes: write defaults and exit (no TUI needed)
   if (autoYes) {
     const { hasClaude, hasCodex } = detectProvider();
     const provider = hasCodex && !hasClaude ? 'codex' : 'claude';
@@ -180,6 +194,28 @@ async function run() {
     return;
   }
 
+  // ── Enter fullscreen ────────────────────────────────────────────────────────
+
+  enterFullscreen();
+
+  // Ensure we exit fullscreen on any exit path
+  const _exitFs = () => exitFullscreen();
+  process.on('exit', _exitFs);
+
+  const cols = process.stdout.columns || 80;
+  const banner = [
+    '',
+    '╔══════════════════════════════════════════════════════════════╗',
+    '║           specrails — Agent Workflow Installer              ║',
+    '║       Configure your AI agent workflow system               ║',
+    '╚══════════════════════════════════════════════════════════════╝',
+    '',
+    `  Target: ${rootDir}`,
+    `  ${'─'.repeat(Math.min(cols - 4, 60))}`,
+    '',
+  ];
+  console.log(banner.join('\n'));
+
   // ── Step 1: Provider ────────────────────────────────────────────────────────
 
   const { hasClaude, hasCodex } = detectProvider();
@@ -207,36 +243,52 @@ async function run() {
 
   // ── Step 2: Installation tier ───────────────────────────────────────────────
 
+  clearScreen();
+  console.log(`  Provider: ${provider}\n`);
+
   const tier = await select({
     message: 'Installation tier:',
+    default: 'quick',
     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',
+        name:        'Quick — Ready to use immediately (recommended)',
         description: 'Agents installed with sensible defaults. No AI step required.',
       },
+      {
+        value:       'full',
+        name:        'Full — AI-powered setup',
+        description: 'After install, run /specrails:enrich to AI-customize all agents for your codebase',
+      },
     ],
   });
 
   // ── Step 3: Agent selection ─────────────────────────────────────────────────
 
-  console.log('\n  Select agents to install.  Space = toggle,  a = all/none,  Enter = confirm.\n');
+  clearScreen();
+  console.log(`  Provider: ${provider}  |  Tier: ${tier}\n`);
+  console.log('  Select agents to install.  Space = toggle,  a = all/none,  Enter = confirm.\n');
+
+  // Use most of the terminal height for agent list (reserve 6 lines for header/footer)
+  const termRows = process.stdout.rows || 24;
+  const agentPageSize = Math.max(10, termRows - 6);
 
-  const selectedAgents = await checkbox({
+  const userSelected = await checkbox({
     message: 'Agents to install:',
     choices: buildCheckboxChoices(),
+    pageSize: agentPageSize,
     validate: (selected) => selected.length > 0 || 'Select at least one agent.',
   });
 
+  // Core agents are always included regardless of checkbox state
+  const selectedAgents = [...new Set([...CORE_AGENTS, ...userSelected])];
   const excludedAgents = ALL_AGENT_IDS.filter(id => !selectedAgents.includes(id));
 
   // ── Step 4: Model preset ────────────────────────────────────────────────────
 
+  clearScreen();
+  console.log(`  Provider: ${provider}  |  Tier: ${tier}  |  Agents: ${selectedAgents.length}/${ALL_AGENT_IDS.length}\n`);
+
   const modelPreset = await select({
     message: 'Model configuration:',
     choices: Object.entries(MODEL_PRESETS).map(([key, val]) => ({
@@ -249,6 +301,9 @@ async function run() {
 
   // ── Step 5: Agent Teams (Claude only) ──────────────────────────────────────
 
+  clearScreen();
+  console.log(`  Provider: ${provider}  |  Tier: ${tier}  |  Agents: ${selectedAgents.length}  |  Preset: ${modelPreset}\n`);
+
   let agentTeams = false;
   if (provider === 'claude') {
     agentTeams = await select({
@@ -260,21 +315,9 @@ async function run() {
     });
   }
 
-  // ── 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 & exit fullscreen ──────────────────────────────────────────
 
-  // ── Write config ────────────────────────────────────────────────────────────
+  exitFullscreen();
 
   writeInstallConfig(specrailsDir, {
     provider,
@@ -284,8 +327,6 @@ async function run() {
     modelPreset,
     modelDefaults,
     modelOverrides,
-    productDescription: productDescription.trim(),
-    targetUsers:        targetUsers.trim(),
     agentTeams,
   });
 
@@ -299,6 +340,7 @@ async function run() {
 }
 
 run().catch(err => {
+  exitFullscreen();
   // Graceful Ctrl+C handling
   if (err.name === 'ExitPromptError' || (err.message && err.message.includes('User force closed'))) {
     console.error('\n  Installation cancelled by user.\n');

package/commands/enrich.md

@@ -52,8 +52,6 @@ Parse the YAML and extract:
 - `config.models.preset` — `balanced`, `budget`, or `max` (see Model Presets below)
 - `config.models.defaults.model` — default model override (overrides preset)
 - `config.models.overrides` — per-agent model overrides (highest priority)
-- `config.quick_context.product_description` — product description seed
-- `config.quick_context.target_users` — target users seed
 - `config.agent_teams` — boolean; whether to install team-review/team-debug commands
 
 Store all values in variables prefixed `FC_`.
@@ -78,21 +76,19 @@ Set `SPECRAILS_DIR` and `CLI_PROVIDER` from resolved provider.
 ### FC3: If tier is `quick` — run Quick Mode with config context
 
 If `FC_tier == "quick"`:
-- Set `QS_PROJECT_DESCRIPTION = FC_quick_context.product_description`
-- Set `QS_TARGET_USERS = FC_quick_context.target_users`  
 - Set `FC_AGENTS_SELECTED` as the list of agents to generate (instead of defaults)
-- Execute Quick Mode (QS1–QS4) with these values injected, generating all `FC_AGENTS_SELECTED` agents (not just defaults)
+- Execute Quick Mode (QS1–QS4), generating all `FC_AGENTS_SELECTED` agents (not just defaults)
 - Then stop.
 
 ### FC4: If tier is `full` — run automated full wizard
 
 **Phase 1 (Silent):** Run the full Phase 1 analysis (1.1–1.4) without any user prompts. Store all detected values internally.
 
-**Phase 2 (Seeded VPC Discovery):** Run VPC persona generation using `FC_quick_context` as seeds:
-- Treat `FC_quick_context.product_description` as the answer to "Describe your product"
-- Treat `FC_quick_context.target_users` as the answer to "Who are your users"
-- Use AI to expand these seeds into full VPC personas (3 primary, 3 secondary)
-- Do not ask the user any questions — infer all answers from seeds + codebase analysis
+**Phase 2 (AI-Inferred VPC Discovery):** Run VPC persona generation from codebase analysis:
+- Analyze the codebase (README, package.json, source code, configs) to infer what the product does and who it serves
+- Generate `PROJECT_DESCRIPTION` (2–3 sentence summary) and `TARGET_USERS` from analysis
+- Use these inferred values to generate full VPC personas (3 primary, 3 secondary)
+- Do not ask the user any questions — infer everything from codebase analysis
 
 **Phase 3 (Silent):** Run Phase 3 normally without user prompts.
 
@@ -415,20 +411,26 @@ Update `.specrails/specrails-manifest.json` to reflect the new checksums for all
 
 When `--quick` or `--lite` is passed, run this streamlined 3-question setup. Do NOT run Phase 1–5. When QS4 is complete, stop.
 
-### QS1: Ask the 3 questions
+### QS1: Infer context and ask git access
 
-Display the following prompt EXACTLY ONCE and then wait for the user's responses. Do NOT repeat the questions — output them a single time only.
+**Step 1 — AI inference (silent):** Analyze the codebase to infer:
+- `QS_PROJECT_DESCRIPTION` — a 2–3 sentence summary of what this project does (from README, package.json, source code, configs)
+- `QS_TARGET_USERS` — who the target users are (from docs, UI copy, API design, domain language)
 
-Welcome to specrails! Let's get your AI agent team set up in 3 quick questions.
+**Step 2 — Ask one question:**
 
-1. What is this project? (one sentence)
-2. Who are the target users?
-3. Git access for agents — read-only or read-write?
+Display the following prompt EXACTLY ONCE:
+
+Welcome to specrails! Let's get your AI agent team set up.
+
+I've analyzed your codebase:
+- **Project:** {QS_PROJECT_DESCRIPTION}
+- **Target users:** {QS_TARGET_USERS}
+
+1. Git access for agents — read-only or read-write?
    (read-only = agents can read and suggest; read-write = agents can commit)
 
-Store the answers as:
-- `QS_PROJECT_DESCRIPTION` — answer to question 1
-- `QS_TARGET_USERS` — answer to question 2
+Store the answer as:
 - `QS_GIT_ACCESS` — "read-only" or "read-write" (normalize if user types "ro", "rw", "readonly", etc.)
 
 ### QS2: Apply opinionated defaults
@@ -490,8 +492,6 @@ Read `.specrails/setup-templates/claude-md/CLAUDE-quickstart.md` (or fall back t
 
 Replace placeholders:
 - `{{PROJECT_NAME}}` → derive from directory name or README.md first heading
-- `{{PROJECT_DESCRIPTION}}` → `QS_PROJECT_DESCRIPTION`
-- `{{TARGET_USERS}}` → `QS_TARGET_USERS`
 - `{{GIT_ACCESS}}` → `QS_GIT_ACCESS`
 
 Write to `CLAUDE.md` in the repo root. If `CLAUDE.md` already exists, ask:
@@ -506,8 +506,6 @@ For each default agent (sr-architect, sr-developer, sr-reviewer, sr-product-mana
 
 Fill placeholders with best-effort values from the limited context available:
 - `{{PROJECT_NAME}}` → directory name or README first heading
-- `{{PROJECT_DESCRIPTION}}` → `QS_PROJECT_DESCRIPTION`
-- `{{TARGET_USERS}}` → `QS_TARGET_USERS`
 - `{{GIT_ACCESS}}` → `QS_GIT_ACCESS`
 - `{{ARCHITECTURE_DIAGRAM}}` → "(Quick Mode — run `/specrails:enrich` for full architecture analysis)"
 - `{{TECH_EXPERTISE}}` → "(Quick Mode — run `/specrails:enrich` for codebase-specific expertise)"

package/docs/installation.md

@@ -280,9 +280,6 @@ agents:
 models:
   preset: balanced      # balanced | budget | max
   overrides: {}         # per-agent overrides: { sr-architect: opus }
-quick_context:
-  product_description: ""   # product description seed
-  target_users: ""          # target users seed
 agent_teams: false      # install team-review/team-debug commands
 ```