swift-code-reviewer-skill 1.2.1 → 1.4.0

package/SKILL.md

@@ -1,26 +1,68 @@
 ---
 name: swift-code-reviewer
-description: "Multi-layer code review agent for Swift and SwiftUI projects. Analyzes PRs, diffs, and files across six dimensions: Swift 6+ concurrency safety, SwiftUI state management and modern APIs, performance (view updates, ForEach identity, lazy loading), security (force unwraps, Keychain, input validation), architecture compliance (MVVM/MVI/TCA, dependency injection), and project-specific standards from .claude/CLAUDE.md. Outputs structured reports with Critical/High/Medium/Low severity, positive feedback, and prioritized action items with file:line references. Use when the user says review this PR, review my code, review my changes, check this file, code review, audit this codebase, check code quality, review uncommitted changes, review all ViewModels, or mentions reviewing .swift files, navigation, sheets, theming, or async patterns."
+description: "Perform thorough code reviews for Swift/SwiftUI code, including spec adherence (PR description + linked issues), code quality, architecture, performance, security, Swift 6+ best practices, project standards from .claude/CLAUDE.md, and meta-feedback on recurring patterns that suggest gaps in the agent's instructions. Use when reviewing PRs/MRs (especially AI-generated ones), performing quality audits, validating against original spec, or providing structured feedback with severity levels and improvement suggestions for both the code and the agent loop that produced it."
 ---
 
 # Swift/SwiftUI Code Review Skill
 
 Multi-layer review covering Swift 6+ concurrency, SwiftUI patterns, performance, security, architecture, and project-specific standards. Reads `.claude/CLAUDE.md` and outputs Critical/High/Medium/Low severity findings with `file:line` references and before/after code examples.
 
+## When to Use This Skill
+
+- "Review this PR"
+- "Review my code" / "Review my changes" / "Review uncommitted changes"
+- "Code review for [component]"
+- "Audit this codebase" / "Check code quality"
+- "Review against .claude/CLAUDE.md" / "Check if this follows our coding standards"
+- "Architecture review" / "Performance audit" / "Security review"
+- "Review this PR against the spec"
+- "Did the agent miss anything from issue #123?"
+- "What rules am I missing in CLAUDE.md based on this PR?"
+- "Review this AI-generated PR"
+
 ## Workflow
 
 ### Phase 1 — Context Gathering
 
-1. Try to load `.claude/CLAUDE.md`.
+1. **Read the Spec**
+   - For PRs: `gh pr view <num> --json title,body,closingIssuesReferences,labels`
+   - For linked issues: `gh issue view <num> --json title,body,labels`
+   - For MRs: `glab mr view <num>` and `glab issue view <num>`
+   - Extract:
+     - Stated goal / problem being solved
+     - Explicit acceptance criteria (look for checkboxes, "should", "must", "Given/When/Then")
+     - Edge cases or non-goals mentioned
+     - Out-of-scope items
+   - If no PR/issue context is available, note this and fall back to inferring intent from the diff.
+2. Try to load `.claude/CLAUDE.md`.
    - **If missing**: add a note to the report — _"No project standards file found — review uses default Apple guidelines"_ — then continue.
-2. Obtain the changeset: `git diff`, `git diff --cached`, or `gh pr diff <n>`.
+3. Obtain the changeset: `git diff`, `git diff --cached`, or `gh pr diff <n>`.
    - **If diff is empty**: stop and ask the user to specify files, a PR number, or a directory.
-3. Read each changed file plus key related files (imports, protocols it conforms to, corresponding test file if present).
+4. Read each changed file plus key related files (imports, protocols it conforms to, corresponding test file if present).
 
 ### Phase 2 — Analysis
 
 For each category, load the reference file before writing findings:
 
+#### 0. Spec Adherence
+
+Reference: `references/spec-adherence.md`
+
+- **Requirement Coverage**
+  - Does each acceptance criterion map to a concrete code change?
+  - Are edge cases mentioned in the spec handled?
+  - Are tests covering the scenarios described?
+- **Scope Discipline**
+  - Flag changes outside the stated scope (scope creep)
+  - Flag unrelated refactors bundled into the PR
+- **Missing Work**
+  - TODOs, `fatalError("not implemented")`, empty function bodies
+  - Stubbed mocks that should be real implementations
+  - Acceptance criteria with no corresponding diff
+- **Intent Drift**
+  - Code solves a *similar* but different problem than stated
+  - Naming/structure suggests a different mental model than the spec
+
 1. **Swift Quality** — concurrency, error handling, optionals, naming → `references/swift-quality-checklist.md`; for concurrency findings also read `skills/swift-concurrency/references/sendable.md` and `actors.md`
 2. **SwiftUI Patterns** — property wrappers, state management, deprecated APIs → `references/swiftui-review-checklist.md`; for wrapper selection read `skills/swiftui-expert-skill/references/state-management.md`
 3. **Performance** — view body cost, ForEach identity, lazy loading, retain cycles → `references/performance-review.md`
@@ -31,6 +73,28 @@ For each category, load the reference file before writing findings:
 For test file findings, consult `skills/swift-testing/references/test-organization.md`.
 For navigation/routing findings, consult `skills/swiftui-ui-patterns/references/navigationstack.md`.
 
+### Phase 2.5 — Pattern Detection (for Agent Loop Feedback)
+
+**Objective**: Identify recurring issues that point to gaps in the agent's
+instructions, not just the code.
+
+After collecting per-file findings, aggregate them:
+
+1. Group findings by rule (e.g., "force-unwrap", "deprecated NavigationView",
+   "missing @MainActor on UI mutation").
+2. Mark any rule that fires **≥2 times across the diff** as a recurring pattern.
+3. For each recurring pattern, draft a one-line rule suitable for
+   `.claude/CLAUDE.md` or an agent system prompt — written as a directive,
+   not a description.
+4. If the same recurring pattern appeared in past reviews (check git log of
+   `.claude/CLAUDE.md`), escalate priority — the existing rule isn't strong
+   enough or isn't being read.
+
+Threshold rationale: one occurrence is a slip; two is a pattern; three+ means
+the agent's instructions are silent on this and need an explicit rule.
+
+Reference: `references/agent-loop-feedback.md`.
+
 ### Phase 3 — Report
 
 Group findings by file → sort by severity within each file → write prioritized action items.
@@ -102,6 +166,22 @@ Also migrate from `ObservableObject`/`@Published` to `@Observable` (iOS 17+) —
 ## Summary
 Files: N | Critical: N | High: N | Medium: N | Low: N
 
+## Spec Adherence
+
+**Source**: PR #123 / Issue #456
+
+| Requirement | Status | Location |
+|-------------|--------|----------|
+| User can log in with email | ✅ Implemented | LoginView.swift:23 |
+| Show error on invalid credentials | ⚠️ Partial — missing 401 case | LoginViewModel.swift:67 |
+| Persist session in Keychain | ❌ Not implemented | — |
+| Rate limit retries | ❌ Not implemented | — |
+
+**Scope creep**: 1 unrelated change (UserSettings.swift refactor) — recommend
+splitting into a separate PR.
+
+---
+
 ## <Filename.swift>
 
 [Severity] **<Category>** (line N)
@@ -115,6 +195,33 @@ Fix: <explanation + corrected snippet>
 - [Must fix] ...
 - [Should fix] ...
 - [Consider] ...
+
+---
+
+## Agent Loop Feedback
+
+Recurring patterns suggest the following rules are missing or under-emphasized
+in `.claude/CLAUDE.md`:
+
+### Pattern: Force-unwraps (4 occurrences)
+**Files**: LoginView.swift:89, NetworkService.swift:34, UserRepo.swift:12,78
+
+**Suggested rule**:
+> Never use `!`, `try!`, or `as!`. Use `guard let` with explicit early return,
+> typed throws, or `as?` with handling. Force-unwraps are crashes waiting to happen.
+
+### Pattern: Deprecated NavigationView (2 occurrences)
+**Files**: ProfileView.swift:15, SettingsView.swift:22
+
+**Suggested rule**:
+> Use `NavigationStack` exclusively. `NavigationView` is deprecated as of iOS 16.
+
+### Pattern: Business logic in View body (3 occurrences)
+**Files**: LoginView.swift:45, ProfileView.swift:78, FeedView.swift:34
+
+**Suggested rule**:
+> Views must not contain business logic, network calls, or data transformations.
+> Move all such work into the @Observable view model.
 ```
 
 Full templates and severity classification: `references/feedback-templates.md`.
@@ -149,10 +256,21 @@ git diff HEAD~1      # last commit
 git diff -- path/to/file.swift
 ```
 
+## Limitations
+
+- Spec adherence checks require an accessible PR description or linked issue.
+  When reviewing local changes with no PR context, mark spec adherence as
+  "not assessed" rather than guessing intent.
+- Agent loop feedback assumes the code was AI-generated or AI-assisted. For
+  fully human-written code, recurring patterns are still useful but should be
+  framed as team coding standards rather than agent instructions.
+
 ## Reference Files
 
 - `references/review-workflow.md` — detailed process, diff parsing, git commands
 - `references/feedback-templates.md` — output templates, severity classification
+- `references/spec-adherence.md` — parsing PR/issue specs, requirement coverage tables, scope creep classification
+- `references/agent-loop-feedback.md` — recurring-pattern threshold, directive phrasing, suggested-rule template
 - `references/swift-quality-checklist.md` — Swift 6+, concurrency, optionals, naming
 - `references/swiftui-review-checklist.md` — property wrappers, state, modern APIs
 - `references/performance-review.md` — view optimization, ForEach, resource management

package/bin/install.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+'use strict';
 
 const fs = require('fs');
 const path = require('path');
@@ -6,7 +7,6 @@ const os = require('os');
 
 const SKILL_NAME = 'swift-code-reviewer-skill';
 
-// Colors for terminal output
 const colors = {
   reset: '\x1b[0m',
   bright: '\x1b[1m',
@@ -14,7 +14,7 @@ const colors = {
   yellow: '\x1b[33m',
   blue: '\x1b[34m',
   red: '\x1b[31m',
-  cyan: '\x1b[36m'
+  cyan: '\x1b[36m',
 };
 
 function log(message, color = colors.reset) {
@@ -23,14 +23,9 @@ function log(message, color = colors.reset) {
 
 function copyRecursive(src, dest) {
   const stats = fs.statSync(src);
-
   if (stats.isDirectory()) {
-    if (!fs.existsSync(dest)) {
-      fs.mkdirSync(dest, { recursive: true });
-    }
-
-    const entries = fs.readdirSync(src);
-    for (const entry of entries) {
+    if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src)) {
       copyRecursive(path.join(src, entry), path.join(dest, entry));
     }
   } else {
@@ -39,18 +34,20 @@ function copyRecursive(src, dest) {
 }
 
 function findPackageRoot() {
-  let packageRoot = __dirname;
-  while (!fs.existsSync(path.join(packageRoot, 'SKILL.md'))) {
-    const parent = path.dirname(packageRoot);
-    if (parent === packageRoot) {
+  let dir = __dirname;
+  while (!fs.existsSync(path.join(dir, 'SKILL.md'))) {
+    const parent = path.dirname(dir);
+    if (parent === dir) {
       log('  Error: Could not find SKILL.md in package', colors.red);
       process.exit(1);
     }
-    packageRoot = parent;
+    dir = parent;
   }
-  return packageRoot;
+  return dir;
 }
 
+// ---------- global install (default command) ----------
+
 function install() {
   log('\n  Swift Code Reviewer Skill Installer', colors.cyan + colors.bright);
   log('  ====================================\n', colors.cyan);
@@ -76,113 +73,70 @@ function install() {
 
   fs.mkdirSync(targetDir, { recursive: true });
 
-  const filesToCopy = [
-    'SKILL.md',
-    'README.md',
-    'LICENSE',
-    'CONTRIBUTING.md',
-    'CHANGELOG.md'
-  ];
-
-  const dirsToCopy = ['references', 'skills', 'templates'];
+  const filesToCopy = ['SKILL.md', 'README.md', 'LICENSE', 'CONTRIBUTING.md', 'CHANGELOG.md'];
+  const dirsToCopy = ['core', 'references', 'skills', 'templates'];
 
   for (const file of filesToCopy) {
     const src = path.join(packageRoot, file);
-    const dest = path.join(targetDir, file);
-
     if (fs.existsSync(src)) {
-      fs.copyFileSync(src, dest);
+      fs.copyFileSync(src, path.join(targetDir, file));
       log(`  Copied: ${file}`, colors.green);
     }
   }
 
   for (const dir of dirsToCopy) {
     const src = path.join(packageRoot, dir);
-    const dest = path.join(targetDir, dir);
-
     if (fs.existsSync(src)) {
-      copyRecursive(src, dest);
+      copyRecursive(src, path.join(targetDir, dir));
       log(`  Copied: ${dir}/`, colors.green);
     }
   }
 
   log('\n  Installation complete!', colors.green + colors.bright);
   log('\n  The skill is now available in Claude Code.', colors.reset);
-  log('  To add the review agent and /review command to a project, run:', colors.reset);
+  log('  To scaffold the review agent into a project, run:', colors.reset);
   log('\n    npx swift-code-reviewer-skill init\n', colors.cyan);
-  log('  Or use it directly by asking Claude to:', colors.reset);
-  log('\n    - "Review this PR"', colors.cyan);
-  log('    - "Review LoginView.swift"', colors.cyan);
-  log('    - "Review my uncommitted changes"', colors.cyan);
-  log('    - "Check if this follows our coding standards"\n', colors.cyan);
-
   log(`  Skill location: ${targetDir}`, colors.blue);
   log('  Documentation: https://github.com/Viniciuscarvalho/swift-code-reviewer-skill\n', colors.blue);
 }
 
-function init() {
+// ---------- init (project scaffolding) ----------
+
+async function init(flags) {
   log('\n  Swift Code Reviewer — Project Setup', colors.cyan + colors.bright);
   log('  =====================================\n', colors.cyan);
 
   const packageRoot = findPackageRoot();
   const cwd = process.cwd();
 
-  // Verify we're in a git repo (likely a real project)
   if (!fs.existsSync(path.join(cwd, '.git'))) {
     log('  Warning: Not a git repository. Running anyway.\n', colors.yellow);
   }
 
-  const claudeDir = path.join(cwd, '.claude');
-  const agentsDir = path.join(claudeDir, 'agents');
-  const commandsDir = path.join(claudeDir, 'commands');
+  const { selectAgents } = require('./lib/prompt');
+  const { AGENT_INSTALLERS } = require('./lib/agents');
 
-  const templateAgentSrc = path.join(packageRoot, 'templates', 'agents', 'swift-code-reviewer.md');
-  const templateCommandSrc = path.join(packageRoot, 'templates', 'commands', 'review.md');
+  const agents = await selectAgents({
+    allFlag: flags.all,
+    agentFlag: flags.agent,
+    isTTY: Boolean(process.stdout.isTTY),
+  });
 
-  // Check templates exist
-  if (!fs.existsSync(templateAgentSrc)) {
-    log('  Error: Agent template not found. Reinstall the skill with:', colors.red);
-    log('    npx swift-code-reviewer-skill\n', colors.cyan);
-    process.exit(1);
+  if (agents.length === 0) {
+    log('  No agents selected. Nothing to do.\n', colors.yellow);
+    return;
   }
 
-  fs.mkdirSync(agentsDir, { recursive: true });
-  fs.mkdirSync(commandsDir, { recursive: true });
-
-  let created = 0;
-  let skipped = 0;
-
-  // Copy agent
-  const agentDest = path.join(agentsDir, 'swift-code-reviewer.md');
-  if (fs.existsSync(agentDest)) {
-    log('  Skipped: .claude/agents/swift-code-reviewer.md (already exists)', colors.yellow);
-    skipped++;
-  } else {
-    fs.copyFileSync(templateAgentSrc, agentDest);
-    log('  Created: .claude/agents/swift-code-reviewer.md', colors.green);
-    created++;
+  const opts = { dryRun: flags.dryRun, force: flags.force };
+  for (const agent of agents) {
+    AGENT_INSTALLERS[agent](packageRoot, cwd, opts);
   }
 
-  // Copy command
-  const commandDest = path.join(commandsDir, 'review.md');
-  if (fs.existsSync(commandDest)) {
-    log('  Skipped: .claude/commands/review.md (already exists)', colors.yellow);
-    skipped++;
-  } else {
-    fs.copyFileSync(templateCommandSrc, commandDest);
-    log('  Created: .claude/commands/review.md', colors.green);
-    created++;
-  }
-
-  log(`\n  Done! ${created} file(s) created, ${skipped} skipped.`, colors.green + colors.bright);
-
-  if (created > 0) {
-    log('\n  Usage:', colors.reset);
-    log('    /review          — run a full code review before pushing', colors.cyan);
-    log('    @swift-code-reviewer — invoke the agent directly\n', colors.cyan);
-  }
+  log('\n  Done!\n', colors.green + colors.bright);
 }
 
+// ---------- uninstall ----------
+
 function uninstall() {
   log('\n  Uninstalling Swift Code Reviewer Skill', colors.yellow + colors.bright);
   log('  ======================================\n', colors.yellow);
@@ -199,29 +153,56 @@ function uninstall() {
   }
 }
 
+// ---------- help ----------
+
 function showHelp() {
   log('\n  Swift Code Reviewer Skill', colors.cyan + colors.bright);
   log('  =========================\n', colors.cyan);
-  log('  Usage: npx swift-code-reviewer-skill [command]\n', colors.reset);
+  log('  Usage: npx swift-code-reviewer-skill [command] [options]\n', colors.reset);
   log('  Commands:', colors.bright);
   log('    (none)     Install the skill to ~/.claude/skills/', colors.reset);
-  log('    init       Scaffold agent + /review command into current project', colors.reset);
+  log('    init       Scaffold review agent into the current project', colors.reset);
   log('    uninstall  Remove the skill from ~/.claude/skills/', colors.reset);
   log('    help       Show this help message\n', colors.reset);
+  log('  Options for init:', colors.bright);
+  log('    --agent <name[,name]>   Target specific agent(s): claude, codex, gemini, kiro', colors.reset);
+  log('    --all                   Install for all supported agents', colors.reset);
+  log('    --force                 Overwrite existing files', colors.reset);
+  log('    --dry-run               Preview writes without touching the filesystem\n', colors.reset);
   log('  Examples:', colors.bright);
-  log('    npx swift-code-reviewer-skill              # install skill globally', colors.cyan);
-  log('    npx swift-code-reviewer-skill init          # add agent + command to project', colors.cyan);
-  log('    npx swift-code-reviewer-skill uninstall     # remove skill\n', colors.cyan);
+  log('    npx swift-code-reviewer-skill              # install skill globally (Claude)', colors.cyan);
+  log('    npx swift-code-reviewer-skill init          # interactive agent picker', colors.cyan);
+  log('    npx swift-code-reviewer-skill init --all    # all agents at once', colors.cyan);
+  log('    npx swift-code-reviewer-skill init --agent codex,gemini', colors.cyan);
+  log('    npx swift-code-reviewer-skill init --dry-run', colors.cyan);
+  log('    npx swift-code-reviewer-skill uninstall\n', colors.cyan);
 }
 
-// Parse command line arguments
+// ---------- arg parsing ----------
+
+function parseFlags(argv) {
+  const flags = { all: false, agent: null, dryRun: false, force: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--all') flags.all = true;
+    else if (arg === '--dry-run') flags.dryRun = true;
+    else if (arg === '--force') flags.force = true;
+    else if (arg === '--agent' && argv[i + 1]) { flags.agent = argv[++i]; }
+    else if (arg.startsWith('--agent=')) { flags.agent = arg.slice('--agent='.length); }
+  }
+  return flags;
+}
+
+// ---------- entry point ----------
+
 const args = process.argv.slice(2);
-const command = args[0];
+const command = args.find((a) => !a.startsWith('-')) || '';
+const flags = parseFlags(args.filter((a) => a.startsWith('-') || args.indexOf(a) > 0));
 
 switch (command) {
   case 'init':
   case 'setup':
-    init();
+    init(flags).catch((err) => { console.error(err); process.exit(1); });
     break;
   case 'uninstall':
   case 'remove':

package/bin/lib/agents.js

@@ -0,0 +1,134 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+};
+
+function log(msg, color = colors.reset) {
+  console.log(`${color}${msg}${colors.reset}`);
+}
+
+function writeFile(dest, src, label, dryRun) {
+  const exists = fs.existsSync(dest);
+  if (dryRun) {
+    log(`  [dry-run] ${exists ? 'Update' : 'Create'}: ${label}`, colors.blue);
+    return;
+  }
+  if (exists) {
+    log(`  Updated: ${label}`, colors.yellow);
+  } else {
+    log(`  Created: ${label}`, colors.green);
+  }
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+}
+
+function skipFile(label, dryRun) {
+  if (dryRun) {
+    log(`  [dry-run] Skip (exists): ${label}`, colors.yellow);
+  } else {
+    log(`  Skipped: ${label} (already exists)`, colors.yellow);
+  }
+}
+
+function installClaude(packageRoot, cwd, { dryRun = false, force = false } = {}) {
+  log('\n  Installing for Claude Code…', colors.cyan);
+
+  const agentSrc = path.join(packageRoot, 'templates', 'agents', 'claude', 'swift-code-reviewer.md');
+  const cmdSrc = path.join(packageRoot, 'templates', 'commands', 'claude', 'review.md');
+
+  const agentDest = path.join(cwd, '.claude', 'agents', 'swift-code-reviewer.md');
+  const cmdDest = path.join(cwd, '.claude', 'commands', 'review.md');
+
+  if (!force && fs.existsSync(agentDest)) {
+    skipFile('.claude/agents/swift-code-reviewer.md', dryRun);
+  } else {
+    writeFile(agentDest, agentSrc, '.claude/agents/swift-code-reviewer.md', dryRun);
+  }
+
+  if (!force && fs.existsSync(cmdDest)) {
+    skipFile('.claude/commands/review.md', dryRun);
+  } else {
+    writeFile(cmdDest, cmdSrc, '.claude/commands/review.md', dryRun);
+  }
+
+  log('\n  Claude Code hints:', colors.reset);
+  log('    /review              — run a full Swift code review', colors.cyan);
+  log('    @swift-code-reviewer — invoke the agent directly\n', colors.cyan);
+}
+
+function installCodex(packageRoot, cwd, { dryRun = false, force = false } = {}) {
+  log('\n  Installing for OpenAI Codex CLI…', colors.cyan);
+
+  const agentSrc = path.join(packageRoot, 'templates', 'agents', 'codex', 'swift-code-reviewer.md');
+  const agentDest = path.join(cwd, 'swift-code-reviewer.md');
+
+  if (!force && fs.existsSync(agentDest)) {
+    skipFile('swift-code-reviewer.md', dryRun);
+  } else {
+    writeFile(agentDest, agentSrc, 'swift-code-reviewer.md', dryRun);
+  }
+
+  log('\n  Codex post-install — add this to your AGENTS.md:\n', colors.reset);
+  log('    ## Swift code review', colors.cyan);
+  log('    See swift-code-reviewer.md for the full review guide.\n', colors.cyan);
+  log('  Note: Codex concatenates AGENTS.md into the system prompt and does not', colors.yellow);
+  log('  auto-resolve @-path mentions. Paste the snippet above manually.\n', colors.yellow);
+}
+
+function installGemini(packageRoot, cwd, { dryRun = false, force = false } = {}) {
+  log('\n  Installing for Google Gemini CLI…', colors.cyan);
+
+  const agentSrc = path.join(packageRoot, 'templates', 'agents', 'gemini', 'swift-code-reviewer.md');
+  const cmdSrc = path.join(packageRoot, 'templates', 'commands', 'gemini', 'review.toml');
+
+  const agentDest = path.join(cwd, 'swift-code-reviewer.md');
+  const cmdDest = path.join(cwd, '.gemini', 'commands', 'review.toml');
+
+  if (!force && fs.existsSync(agentDest)) {
+    skipFile('swift-code-reviewer.md', dryRun);
+  } else {
+    writeFile(agentDest, agentSrc, 'swift-code-reviewer.md', dryRun);
+  }
+
+  if (!force && fs.existsSync(cmdDest)) {
+    skipFile('.gemini/commands/review.toml', dryRun);
+  } else {
+    writeFile(cmdDest, cmdSrc, '.gemini/commands/review.toml', dryRun);
+  }
+
+  log('\n  Gemini CLI hints:', colors.reset);
+  log('    /review              — run a full Swift code review (via review.toml)', colors.cyan);
+  log('    The command uses @./swift-code-reviewer.md to load the guide.\n', colors.cyan);
+}
+
+function installKiro(packageRoot, cwd, { dryRun = false, force = false } = {}) {
+  log('\n  Installing for Kiro…', colors.cyan);
+
+  const agentSrc = path.join(packageRoot, 'templates', 'agents', 'kiro', 'swift-code-reviewer.md');
+  const agentDest = path.join(cwd, '.kiro', 'steering', 'swift-code-reviewer.md');
+
+  if (!force && fs.existsSync(agentDest)) {
+    skipFile('.kiro/steering/swift-code-reviewer.md', dryRun);
+  } else {
+    writeFile(agentDest, agentSrc, '.kiro/steering/swift-code-reviewer.md', dryRun);
+  }
+
+  log('\n  Kiro hints:', colors.reset);
+  log('    Steering auto-activates for any *.swift file (fileMatch inclusion).', colors.cyan);
+  log('    Note: workspace-scoped steering only — global steering has a known', colors.yellow);
+  log('    bug (https://github.com/kirodotdev/Kiro/issues/6171).\n', colors.yellow);
+}
+
+const AGENT_INSTALLERS = { claude: installClaude, codex: installCodex, gemini: installGemini, kiro: installKiro };
+const VALID_AGENTS = Object.keys(AGENT_INSTALLERS);
+
+module.exports = { installClaude, installCodex, installGemini, installKiro, AGENT_INSTALLERS, VALID_AGENTS };

package/bin/lib/prompt.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const { VALID_AGENTS } = require('./agents');
+
+/**
+ * Resolve which agents to install based on CLI flags and TTY state.
+ *
+ * Priority:
+ *   1. --all flag → all agents
+ *   2. --agent <name[,name]> flag → named agents
+ *   3. TTY available → interactive @inquirer/prompts checkbox
+ *   4. Non-TTY without flags → ['claude'] (CI-safe fallback)
+ */
+async function selectAgents({ allFlag, agentFlag, isTTY } = {}) {
+  if (allFlag) return [...VALID_AGENTS];
+
+  if (agentFlag) {
+    const requested = agentFlag.split(',').map((s) => s.trim().toLowerCase());
+    const invalid = requested.filter((a) => !VALID_AGENTS.includes(a));
+    if (invalid.length > 0) {
+      console.error(`  Unknown agent(s): ${invalid.join(', ')}`);
+      console.error(`  Valid options: ${VALID_AGENTS.join(', ')}`);
+      process.exit(1);
+    }
+    return requested;
+  }
+
+  if (!isTTY) {
+    return ['claude'];
+  }
+
+  const { checkbox } = require('@inquirer/prompts');
+  const choices = VALID_AGENTS.map((name) => ({
+    name: agentLabel(name),
+    value: name,
+    checked: name === 'claude',
+  }));
+
+  const selected = await checkbox({
+    message: 'Which agent(s) should the review guide be installed for?',
+    choices,
+    validate: (val) => val.length > 0 || 'Select at least one agent.',
+  });
+
+  return selected;
+}
+
+function agentLabel(name) {
+  const labels = {
+    claude: 'Claude Code  (.claude/agents/ + .claude/commands/)',
+    codex:  'OpenAI Codex CLI  (swift-code-reviewer.md at repo root)',
+    gemini: 'Google Gemini CLI  (swift-code-reviewer.md + .gemini/commands/review.toml)',
+    kiro:   'Kiro  (.kiro/steering/swift-code-reviewer.md, fileMatch: **/*.swift)',
+  };
+  return labels[name] || name;
+}
+
+module.exports = { selectAgents };