specrails-core 4.11.2 → 4.12.0

package/README.md

@@ -4,8 +4,7 @@
 [![GitHub Stars](https://img.shields.io/github/stars/fjpulidop/specrails-core?style=social)](https://github.com/fjpulidop/specrails-core)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm downloads](https://img.shields.io/npm/dw/specrails-core.svg)](https://www.npmjs.com/package/specrails-core)
-[![Claude Code](https://img.shields.io/badge/Built%20for-Claude%20Code-blueviolet)](https://docs.anthropic.com/en/docs/claude-code)
-[![Codex — Coming Soon](https://img.shields.io/badge/OpenAI%20Codex-Coming%20Soon%20(in%20lab)-lightgrey)](https://github.com/openai/codex)
+[![AI providers](https://img.shields.io/badge/providers-Claude%20%7C%20Codex%20%7C%20Gemini%20%7C%20Kimi-6f42c1)](#provider-support)
 
 **Your agentic development team. From idea to production code.**
 
@@ -13,12 +12,12 @@ One command turns your repo into a spec-driven pipeline with a team of specializ
 
 ```bash
 npx specrails-core@latest init   # install into the current repo
-/specrails:enrich                # optional: deep codebase analysis
+/specrails:enrich                # Claude/Gemini (Kimi: /skill:specrails-enrich)
 ```
 
-> **Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code), git, Node 20+. Cross-platform: macOS, Linux, Windows.
->
-> **🧪 Codex (OpenAI) support — Coming Soon:** We are testing Codex integration in our lab. Installation is disabled for now, but the feature will be available shortly. Follow the repo for updates.
+> **Requirements:** one supported AI CLI, git, and Node 20.19.0+. Cross-platform:
+> macOS, Linux, and Windows. Use `--provider claude|codex|gemini|kimi` to
+> override auto-detection.
 
 ---
 
@@ -44,7 +43,8 @@ npx specrails-core@latest init
 
 The TUI asks you to pick a tier:
 
-- **Quick** (default) — agents and commands installed straight to `.claude/`, ready to use immediately. No AI interaction.
+- **Quick** (default) — provider-native agents/skills and commands are installed
+  under `.claude/`, `.codex/`, `.gemini/`, or `.kimi-code/`. No AI interaction.
 - **Full** — same as Quick plus `/specrails:enrich` (5-phase deep analysis: stack detection, VPC personas, competitive research). ~5 min.
 
 ```bash
@@ -61,15 +61,34 @@ That's it. The pipeline takes over.
 
 ---
 
+## Provider support
+
+| Provider | Runtime command | Project surface | Workflow syntax |
+|----------|-----------------|-----------------|-----------------|
+| Claude Code | `claude` | `.claude/` | `/specrails:<command>` |
+| Codex CLI | `codex` | `.codex/` | provider-native skills |
+| Gemini CLI | `gemini` | `.gemini/` | `/specrails:<command>` |
+| Kimi Code | managed Node skill runner → external `kimi -p` | `.kimi-code/` | `/skill:specrails-<command>` in the TUI |
+
+Kimi is an external CLI dependency, just like the other providers. SpecRails
+does not bundle a Kimi binary, start `kimi web`, or own a Kimi server. Install
+Kimi Code separately, run `kimi login` once, then select it explicitly or let
+the installer detect it. Parallel Kimi roles are submitted as one bounded
+foreground wave; Core creates/reuses their git worktrees, attributes each
+child stream, and waits for aggregate completion—without a server. See the
+[Kimi setup guide](./docs/user-docs/getting-started-kimi.md).
+
 ## What gets installed
 
 Everything lands in your repo — nothing auto-updates, nothing phones home. You own it, you commit it.
 
 | Category | Location | Purpose |
 |----------|----------|---------|
-| **Agents** | `.claude/agents/` | 14 specialised AI agents |
-| **Commands** | `.claude/commands/specrails/` | 17 workflow commands (`/specrails:implement`, `/specrails:get-backlog-specs`, `/specrails:why`, …) |
-| **OpenSpec skills** | `.claude/commands/opsx/` | `/opsx:*` commands for spec artefacts |
+| **Provider workflows** | `.claude/`, `.codex/`, `.gemini/`, or `.kimi-code/` | Provider-native SpecRails commands and role definitions |
+| **Kimi workflow skills** | `.kimi-code/skills/specrails-*/SKILL.md` | `/skill:specrails-*` directory-form skills |
+| **Kimi role skills** | `.kimi-code/skills/sr-*/SKILL.md` | Specialized role prompts used by Kimi workflows; Kimi discovers only direct skill children |
+| **Kimi headless runner** | `.kimi-code/specrails/run-skill.mjs` | Materializes Kimi's native skill-activation prompt before launching the external CLI |
+| **OpenSpec skills** | Provider-native skills directory | Structured proposal/design/tasks/apply workflows |
 | **Config** | `.specrails/config.yaml` | Stack, CI commands, git workflow |
 | **Personas** | `.specrails/personas/*.md` | VPC user profiles, generated from your users |
 | **Rules** | `.specrails/rules/*.md` | Per-layer coding conventions |
@@ -204,7 +223,8 @@ Profiles are declarative JSON files that tell `/specrails:implement` which agent
 When running the pipeline, the active profile is resolved in this order:
 
 1. `$SPECRAILS_PROFILE_PATH` environment variable (absolute path to a JSON snapshot)
-2. `<cwd>/.specrails/profiles/project-default.json`
+2. Provider default: `<cwd>/.specrails/profiles/project-default.json` for
+   Claude, or `<cwd>/.specrails/profiles/kimi-default.json` for Kimi
 3. No profile — legacy behavior (identical to pre-4.1.0)
 
 Tools such as [specrails-desktop](https://github.com/fjpulidop/specrails-desktop) set `$SPECRAILS_PROFILE_PATH` to a job-scoped snapshot so concurrent rails can run independent profiles.
@@ -240,6 +260,9 @@ The following paths are **reserved** — `specrails-core update` will never crea
 
 - `.specrails/profiles/**` — profile JSON files (yours and desktop-authored).
 - `.claude/agents/custom-*.md` — your custom agents. Use the `custom-` prefix to opt in to this protection.
+- `.kimi-code/skills/custom-*/**` — your custom Kimi role skills. Pre-release
+  `.kimi-code/skills/rails/custom-*` roles are also reserved while Core safely
+  migrates them into this discoverable direct-child layout.
 
 This contract is what lets you safely hand-author (or let specrails-desktop author) profiles and custom agents without fear of the next `update` overwriting your work. Other paths managed by specrails-core (`.specrails/install-config.yaml`, `.specrails/specrails-version`, etc.) remain under update's control. Audited by `src/installer/__tests__/reserved-paths.test.ts` on every CI run.
 
@@ -287,10 +310,10 @@ Each persona scores features 0–5. Features are ranked by score / effort ratio.
 
 | Tool | Required | Purpose |
 |------|----------|---------|
-| **Claude Code** | Yes | AI agent runtime |
-| **Codex CLI** _(coming soon — in lab)_ | 🧪 Not yet | OpenAI Codex support is being tested in our lab and will be available shortly. |
+| **One supported AI CLI** | Yes | Claude Code, Codex CLI, Gemini CLI, or Kimi Code |
+| **Kimi Code 0.27.0+** | For Kimi projects | Install from the [official Kimi Code guide](https://www.kimi.com/code/docs/en/kimi-code-cli/guides/getting-started), then run `kimi login` |
 | **git** | Yes | Repository detection |
-| **Node 20+** | Yes | Needed for `npx specrails-core@latest init`. Cross-platform: macOS, Linux, Windows (10/11, x64 + ARM64 via emulation). |
+| **Node 20.19.0+** | Yes | Needed for `npx specrails-core@latest init` (the floor required by the pinned OpenSpec 1.4.1 CLI). Cross-platform: macOS, Linux, Windows (10/11, x64 + ARM64 via emulation). |
 | **GitHub CLI** (`gh`) | Optional | Backlog sync to GitHub Issues, PR creation. Not needed with local tickets. |
 | **JIRA CLI** (`jira`) | Optional | Backlog sync to JIRA. Not needed with local tickets. |
 
@@ -324,7 +347,9 @@ Stack-agnostic. The `/specrails:enrich` wizard detects and adapts to whatever yo
 ## FAQ
 
 **Can I customise the agents after installation?**
-Yes. Everything under `.claude/` and `.specrails/` is yours to edit — agent prompts, personas, rules, config. Commit what makes sense, gitignore what's transient.
+Yes. Everything in the selected provider tree and `.specrails/` is yours to
+edit. For Kimi, customize `.kimi-code/skills/`, `.kimi-code/rules/`, and the
+managed block in `.kimi-code/AGENTS.md`; `custom-*` role skills are preserved.
 
 **Can I re-run the wizard?**
 Run `/specrails:enrich` again at any time to regenerate or update project data files. Re-running `npx specrails-core@latest init` refreshes the agents/commands without touching `.specrails/`.
@@ -336,13 +361,24 @@ Yes. Local tickets are the default and need no external tools. `/specrails:imple
 Not simultaneously for the same project — backlog commands use one active provider at a time. You can migrate from GitHub Issues to local tickets using the [migration guide](./docs/migration-guide.md).
 
 **How much does it cost to run?**
-A full `/specrails:implement` cycle for one feature typically costs a few dollars in Claude API usage. The sr-product-manager uses Opus; all other agents use Sonnet or Haiku.
+Cost depends on the selected provider, model, and workload. SpecRails does not
+add a model surcharge. Kimi's stream output does not currently report a native
+USD cost, so consumers must display it as unavailable rather than inventing an
+estimate.
 
 **Does it work with private repos?**
-Yes. Everything runs locally through Claude Code. No external services beyond the model API.
-
-**How do I use specrails with Codex?**
-🧪 **Coming Soon — in lab.** OpenAI Codex support is currently being tested in our lab and will be available shortly. The install path will remain the same (`npx specrails-core@latest init --root-dir .`) — the installer will detect Codex and adjust the agent configuration automatically. See [docs/user-docs/getting-started-codex.md](./docs/user-docs/getting-started-codex.md) for the preview documentation.
+Yes. Orchestration runs through the selected local CLI. The provider still
+connects to its model API and any MCP/integration endpoints you configure.
+
+**How do I use specrails with Kimi?**
+Install and authenticate Kimi Code, then run
+`npx specrails-core@latest init --provider kimi`. Invoke the generated workflows
+as `/skill:specrails-implement`, `/skill:specrails-enrich`, and so on in Kimi's
+interactive TUI. Headless callers use the managed
+`.kimi-code/specrails/run-skill.mjs` helper: Kimi 0.27 sends a slash command
+passed directly to `kimi -p` as literal text, so the helper first renders the
+same skill prompt as Kimi's native activation path and then starts external
+`kimi -p --output-format stream-json`. No server installation is required.
 
 ---
 

package/bin/specrails-core.mjs

@@ -6,8 +6,8 @@
  * in-process via the Node installer under dist/installer/. This file
  * only keeps logic that is local to the dispatcher:
  *   - `profile validate` / `profile show` — schema validation via ajv.
- *   - `enrich`                            — spawns Claude Code with
- *                                           the /specrails:enrich command.
+ *   - `enrich`                            — launches the installed provider's
+ *                                           native enrich workflow.
  *   - `init` TUI short-circuit            — spawns tui-installer.mjs
  *                                           then re-enters init with
  *                                           --from-config.
@@ -31,7 +31,11 @@ const subcommand = args[0]
 
 // ─── Global --version / -V flag ──────────────────────────────────────────────
 
-if (args.includes('--version') || args.includes('-V')) {
+// Treat version as a GLOBAL flag only when it is the command itself. Offline
+// lifecycle commands also carry a required `--version <target>` option; scanning
+// the whole argv would intercept `swap-current --version 4.12.0` here and exit 0
+// without ever validating or moving the framework pointer.
+if (subcommand === '--version' || subcommand === '-V') {
   const pkg = require_(path.resolve(ROOT, 'package.json'))
   console.log(`specrails-core v${pkg.version}`)
   process.exit(0)
@@ -51,6 +55,7 @@ const KNOWN_SUBCOMMANDS = new Set([
   'update',
   'doctor',
   'install-framework',
+  'swap-current',
   'assemble',
   'enrich',
   'version',
@@ -61,7 +66,7 @@ const KNOWN_SUBCOMMANDS = new Set([
 if (!KNOWN_SUBCOMMANDS.has(subcommand)) {
   console.error(`Unknown command: ${subcommand}\n`)
   console.error(
-    'Available commands: init, update, doctor, install-framework, assemble, enrich, version, profile, help',
+    'Available commands: init, update, doctor, install-framework, swap-current, assemble, enrich, version, profile, help',
   )
   process.exit(1)
 }
@@ -90,25 +95,91 @@ if (subcommand === 'profile') {
 }
 
 // ─── enrich ──────────────────────────────────────────────────────────────────
-// Launches Claude Code with the /specrails:enrich slash command.
+// Launches the configured provider's native enrich workflow.
 
 if (subcommand === 'enrich') {
-  const enrichFlags = subargs.join(' ')
-  const claudeCmd = `/specrails:enrich${enrichFlags ? ' ' + enrichFlags : ''}`
+  const workspace = await resolveEnrichWorkspace(process.cwd())
+  const { provider, model: explicitModel, workflowArgs } = resolveEnrichOptions(
+    workspace.codeRoot,
+    subargs,
+    workspace.artifactRoot,
+  )
+  const model =
+    explicitModel ??
+    resolveConfiguredEnrichModel(workspace.codeRoot, workspace.artifactRoot) ??
+    'k3'
+  const enrichFlags = serializeWorkflowArgs(workflowArgs)
+  const launch =
+    provider === 'kimi'
+      ? {
+          command: process.execPath,
+          args: [
+            path.resolve(
+              workspace.artifactRoot,
+              '.kimi-code',
+              'specrails',
+              'run-skill.mjs',
+            ),
+            '--skill',
+            'specrails-enrich',
+            '--model',
+            model,
+            '--add-dir',
+            workspace.codeRoot,
+            ...(enrichFlags ? ['--args', enrichFlags] : []),
+          ],
+          label: 'Kimi Code',
+        }
+      : provider === 'gemini'
+        ? {
+            command: 'gemini',
+            args: [
+              '-p',
+              `/specrails:enrich${enrichFlags ? ` ${enrichFlags}` : ''}`,
+              '--output-format',
+              'stream-json',
+            ],
+            label: 'Gemini CLI',
+          }
+        : provider === 'codex'
+          ? {
+              command: 'codex',
+              args: [
+                'exec',
+                `run enrich${enrichFlags ? ` ${enrichFlags}` : ''}`,
+              ],
+              label: 'Codex CLI',
+            }
+          : {
+              command: 'claude',
+              args: [
+                '--command',
+                `/specrails:enrich${enrichFlags ? ` ${enrichFlags}` : ''}`,
+                '--dangerously-skip-permissions',
+              ],
+              label: 'Claude Code',
+            }
   const result = spawnSync(
-    'claude',
-    ['--command', claudeCmd, '--dangerously-skip-permissions'],
+    launch.command,
+    launch.args,
     {
       stdio: 'inherit',
-      cwd: process.cwd(),
-      shell: process.platform === 'win32',
+      cwd: provider === 'kimi' ? workspace.artifactRoot : process.cwd(),
+      env:
+        provider === 'kimi'
+          ? {
+              ...process.env,
+              SPECRAILS_REPO_DIR: workspace.codeRoot,
+            }
+          : process.env,
+      shell: process.platform === 'win32' && provider !== 'kimi',
     },
   )
   if (result.error) {
     console.error(
-      '\nFailed to launch Claude CLI for enrich:',
+      `\nFailed to launch ${launch.label} for enrich:`,
       result.error.message,
-      '\nEnsure Claude Code is installed: npm install -g @anthropic-ai/claude-code\n',
+      `\nEnsure the configured ${provider} provider is installed and initialized.\n`,
     )
     process.exit(1)
   }
@@ -144,6 +215,7 @@ if (subcommand === 'init') {
     const tuiArgs = [path.resolve(ROOT, 'bin', 'tui-installer.mjs'), rootDir]
     if (providerVal) tuiArgs.push('--provider', providerVal)
     else if (providerEqArg) tuiArgs.push(providerEqArg)
+    if (subargs.includes('--with-profiles')) tuiArgs.push('--with-profiles')
     const tuiResult = spawnSync('node', tuiArgs, {
       stdio: 'inherit',
       cwd: process.cwd(),
@@ -189,20 +261,25 @@ process.exit(0)
 // ─────────────────────────────────────────────────────────────────────────────
 
 function printUsage() {
-  console.log(`specrails-core — Agent Workflow System for Claude Code
+  console.log(`specrails-core — Provider-independent AI agent workflow system
 
 Usage:
   specrails-core init       [--root-dir <path>] [--yes|-y] [--no-tui]  Install into a repository
   specrails-core update     [--only <component>] [--dry-run]           Update an existing installation
   specrails-core doctor                                                 Run health checks
-  specrails-core enrich     [--from-config <path>]                      Run /specrails:enrich via Claude CLI
+  specrails-core install-framework --framework-dir <path> --provider <value> --version <value>
+                                                                        Materialize an offline framework version
+  specrails-core swap-current --framework-dir <path> --version <value> [--providers <csv>]
+                                                                        Validate and atomically expose a framework version
+  specrails-core assemble   --workspace <path> --framework-dir <path>   Assemble a workspace from the framework
+  specrails-core enrich     [--provider <value>] [workflow flags]       Run the configured provider's enrich workflow
   specrails-core profile    <validate|show> [<path>]                    Validate or pretty-print a profile JSON
   specrails-core version                                                Show installed version
 
 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 (codex coming soon)
+  --provider <value>  Force provider: claude, codex, gemini, or kimi
   --no-tui            Skip TUI; use defaults / flags directly
   --from-config       Skip TUI; use existing .specrails/install-config.yaml
 
@@ -212,6 +289,174 @@ Global flags:
 More info: https://github.com/fjpulidop/specrails-core`)
 }
 
+function resolveEnrichOptions(cwd, argv, artifactRoot = cwd) {
+  const workflowArgs = []
+  let explicitProvider
+  let model
+  for (let index = 0; index < argv.length; index++) {
+    const token = argv[index]
+    if (token === '--provider' || token === '--model') {
+      const value = argv[++index]
+      if (!value) {
+        console.error(`${token} requires a value`)
+        process.exit(1)
+      }
+      if (token === '--provider') explicitProvider = value
+      else model = value
+      continue
+    }
+    if (token.startsWith('--provider=')) {
+      explicitProvider = token.slice('--provider='.length)
+      continue
+    }
+    if (token.startsWith('--model=')) {
+      model = token.slice('--model='.length)
+      continue
+    }
+    workflowArgs.push(token)
+  }
+
+  const supported = new Set(['claude', 'codex', 'gemini', 'kimi'])
+  if (explicitProvider && !supported.has(explicitProvider)) {
+    console.error(
+      `Unsupported provider "${explicitProvider}". Expected claude, codex, gemini, or kimi.`,
+    )
+    process.exit(1)
+  }
+
+  let provider = explicitProvider
+  if (!provider) {
+    for (const root of [cwd, artifactRoot]) {
+      const manifestPath = path.join(
+        root,
+        '.specrails',
+        'specrails-manifest.json',
+      )
+      if (existsSync(manifestPath)) {
+        try {
+          const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+          if (supported.has(manifest.primary_provider)) {
+            provider = manifest.primary_provider
+            break
+          }
+        } catch {
+          // A malformed manifest is diagnosed by `specrails-core doctor`;
+          // enrich continues to config/directory fallback.
+        }
+      }
+    }
+  }
+  if (!provider) {
+    for (const root of [cwd, artifactRoot]) {
+      const configPath = path.join(root, '.specrails', 'install-config.yaml')
+      if (!existsSync(configPath)) continue
+      const match = readFileSync(configPath, 'utf8').match(
+        /^provider:\s*(claude|codex|gemini|kimi)\s*$/m,
+      )
+      if (match) {
+        provider = match[1]
+        break
+      }
+    }
+  }
+  if (!provider) {
+    provider =
+      ['claude', 'codex', 'gemini', 'kimi'].find((candidate) =>
+        existsSync(
+          path.join(
+            artifactRoot,
+            candidate === 'kimi' ? '.kimi-code' : `.${candidate}`,
+          ),
+        ),
+      ) ?? 'claude'
+  }
+  return { provider, model, workflowArgs }
+}
+
+async function resolveEnrichWorkspace(cwd) {
+  const registryModulePath = path.resolve(
+    ROOT,
+    'dist',
+    'installer',
+    'util',
+    'registry.js',
+  )
+  if (!existsSync(registryModulePath)) {
+    return { artifactRoot: cwd, codeRoot: cwd }
+  }
+  try {
+    const registry = await import(pathToFileURL(registryModulePath).href)
+    const resolution = registry.resolveArtifacts(cwd, { allocate: false })
+    return {
+      artifactRoot: path.resolve(resolution.artifactRoot),
+      codeRoot: path.resolve(resolution.codeRoot),
+    }
+  } catch {
+    // Doctor reports malformed registry state. Enrich retains the legacy
+    // in-repository fallback instead of guessing another relocated workspace.
+    return { artifactRoot: cwd, codeRoot: cwd }
+  }
+}
+
+function resolveConfiguredEnrichModel(codeRoot, artifactRoot) {
+  const activeProfile = process.env.SPECRAILS_PROFILE_PATH
+  if (activeProfile) {
+    const activePath = path.isAbsolute(activeProfile)
+      ? activeProfile
+      : path.resolve(codeRoot, activeProfile)
+    const activeModel = readProfileOrchestratorModel(activePath)
+    if (activeModel) return activeModel
+  }
+  const configCandidates = [
+    path.join(codeRoot, '.specrails', 'install-config.yaml'),
+    path.join(artifactRoot, '.specrails', 'install-config.yaml'),
+  ]
+  for (const configPath of configCandidates) {
+    if (!existsSync(configPath)) continue
+    try {
+      const config = require_('js-yaml').load(readFileSync(configPath, 'utf8'))
+      const configured = config?.models?.defaults?.model
+      if (typeof configured === 'string' && configured.trim() !== '') {
+        return configured.trim()
+      }
+    } catch {
+      // The installer/doctor owns full config diagnostics. Continue to a
+      // provider profile rather than extracting a value from malformed YAML.
+    }
+  }
+  const profileCandidates = [
+    path.join(artifactRoot, '.specrails', 'profiles', 'kimi-default.json'),
+    path.join(codeRoot, '.specrails', 'profiles', 'kimi-default.json'),
+  ]
+  for (const profilePath of profileCandidates) {
+    const configured = readProfileOrchestratorModel(profilePath)
+    if (configured) return configured
+  }
+  return null
+}
+
+function readProfileOrchestratorModel(profilePath) {
+  if (!existsSync(profilePath)) return null
+  try {
+    const profile = JSON.parse(readFileSync(profilePath, 'utf8'))
+    const configured = profile?.orchestrator?.model
+    return typeof configured === 'string' && configured.trim() !== ''
+      ? configured.trim()
+      : null
+  } catch {
+    // Profile validation provides the actionable error. Fall through.
+    return null
+  }
+}
+
+function serializeWorkflowArgs(argv) {
+  return argv
+    .map((value) =>
+      value === '' || /\s|["']/u.test(value) ? JSON.stringify(value) : value,
+    )
+    .join(' ')
+}
+
 /**
  * Loads the compiled Node CLI (dist/installer/cli.js) and invokes its
  * `main` function with the given argv array. Propagates the returned
@@ -244,11 +489,33 @@ async function runProfile(subargs) {
     process.exit(1)
   }
 
+  const workspace = await resolveEnrichWorkspace(process.cwd())
   const resolveProfilePath = () => {
     if (pathArg) return path.resolve(pathArg)
     if (process.env.SPECRAILS_PROFILE_PATH) return path.resolve(process.env.SPECRAILS_PROFILE_PATH)
-    const projectDefault = path.resolve(process.cwd(), '.specrails', 'profiles', 'project-default.json')
-    if (existsSync(projectDefault)) return projectDefault
+    const configRoots = [workspace.codeRoot, workspace.artifactRoot]
+    let provider
+    for (const root of configRoots) {
+      const configPath = path.join(root, '.specrails', 'install-config.yaml')
+      if (!existsSync(configPath)) continue
+      const match = readFileSync(configPath, 'utf8').match(
+        /^provider:\s*(claude|codex|gemini|kimi)\s*$/m,
+      )
+      if (match) {
+        provider = match[1]
+        break
+      }
+    }
+    const names =
+      provider === 'kimi'
+        ? ['kimi-default.json', 'project-default.json']
+        : ['project-default.json', 'kimi-default.json']
+    for (const root of [workspace.artifactRoot, workspace.codeRoot]) {
+      for (const name of names) {
+        const candidate = path.join(root, '.specrails', 'profiles', name)
+        if (existsSync(candidate)) return candidate
+      }
+    }
     return null
   }
 
@@ -256,7 +523,9 @@ async function runProfile(subargs) {
   if (!profilePath) {
     console.error('No profile path given and none could be resolved.')
     console.error('Pass an explicit path or set SPECRAILS_PROFILE_PATH, or place a profile at')
-    console.error('  .specrails/profiles/project-default.json')
+    console.error(
+      '  .specrails/profiles/project-default.json (or kimi-default.json for Kimi)',
+    )
     process.exit(1)
   }
   if (!existsSync(profilePath)) {
@@ -298,8 +567,12 @@ async function runProfile(subargs) {
   const schema = JSON.parse(readFileSync(schemaPath, 'utf8'))
   const ajv = new Ajv({ allErrors: true, strict: false })
   const validate = ajv.compile(schema)
+  const schemaValid = validate(profile)
+  const semanticErrors = schemaValid
+    ? validateProfileSemantics(profile)
+    : []
 
-  if (validate(profile)) {
+  if (schemaValid && semanticErrors.length === 0) {
     console.log(`✓ ${profilePath} is a valid v1 profile.`)
     process.exit(0)
   }
@@ -307,5 +580,55 @@ async function runProfile(subargs) {
   for (const err of validate.errors || []) {
     console.error(`    ${err.instancePath || '/'} ${err.message} (${JSON.stringify(err.params)})`)
   }
+  for (const err of semanticErrors) {
+    console.error(`    ${err}`)
+  }
   process.exit(1)
 }
+
+/**
+ * JSON Schema validates each profile entry in isolation. These invariants span
+ * multiple array entries and therefore require a second, semantic validation
+ * pass after AJV has established the profile's structural shape.
+ */
+function validateProfileSemantics(profile) {
+  const errors = []
+  const firstAgentIndex = new Map()
+
+  for (const [index, agent] of profile.agents.entries()) {
+    const previous = firstAgentIndex.get(agent.id)
+    if (previous !== undefined) {
+      errors.push(
+        `/agents/${index}/id duplicates agent id "${agent.id}" first declared at /agents/${previous}/id`,
+      )
+    } else {
+      firstAgentIndex.set(agent.id, index)
+    }
+  }
+
+  const knownAgents = new Set(firstAgentIndex.keys())
+  const defaultIndices = []
+  for (const [index, rule] of profile.routing.entries()) {
+    if (!knownAgents.has(rule.agent)) {
+      errors.push(
+        `/routing/${index}/agent references unknown agent "${rule.agent}"`,
+      )
+    }
+    if (rule.default === true) {
+      defaultIndices.push(index)
+    }
+  }
+
+  if (defaultIndices.length > 1) {
+    errors.push(
+      `/routing must contain at most one default rule (found ${defaultIndices.length})`,
+    )
+  }
+  for (const index of defaultIndices) {
+    if (index !== profile.routing.length - 1) {
+      errors.push(`/routing/${index} default rule must be the last routing entry`)
+    }
+  }
+
+  return errors
+}