swift-code-reviewer-skill 1.3.0 → 1.4.0

package/README.md

@@ -3,7 +3,11 @@
 [![GitHub Sponsors](https://img.shields.io/github/sponsors/Viniciuscarvalho?style=social)](https://github.com/sponsors/Viniciuscarvalho)
 [![npm version](https://img.shields.io/npm/v/swift-code-reviewer-skill)](https://www.npmjs.com/package/swift-code-reviewer-skill)
 
-A code review skill for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) that performs multi-layer analysis of Swift and SwiftUI code, combining Apple's best practices with your project-specific coding standards.
+Multi-layer Swift/SwiftUI code review for Claude Code, OpenAI Codex CLI, Google Gemini CLI, and Kiro — with spec adherence, agent loop feedback, and project-standards validation.
+
+![Init demo](assets/init-demo.gif)
+
+---
 
 ## Quick Start
 
@@ -13,185 +17,268 @@ A code review skill for [Claude Code](https://docs.anthropic.com/en/docs/claude-
 npx skills add Viniciuscarvalho/swift-code-reviewer-skill
 ```
 
-To update to the latest version later:
-
-```bash
-npx swift-code-reviewer-skill@latest
-```
-
-### 2. Add the review agent to your project (optional)
+### 2. Scaffold the review agent into your project
 
 ```bash
 cd ~/Projects/YourApp
 npx swift-code-reviewer-skill init
 ```
 
-This scaffolds two files into your project:
+The interactive prompt lets you choose which agent(s) to install:
 
 ```
-.claude/
-  agents/swift-code-reviewer.md   # review agent
-  commands/review.md              # /review slash command
+? Which agent(s) should the review guide be installed for?
+ ◉ Claude Code  (.claude/agents/ + .claude/commands/)
+ ○ OpenAI Codex CLI  (swift-code-reviewer.md at repo root)
+ ○ Google Gemini CLI  (swift-code-reviewer.md + .gemini/commands/review.toml)
+ ○ Kiro  (.kiro/steering/swift-code-reviewer.md, fileMatch: **/*.swift)
 ```
 
-Existing files are never overwritten.
+#### CI / scripted install (no prompt)
 
-### The review flow
+```bash
+npx swift-code-reviewer-skill init --agent claude          # Claude only (default in non-TTY)
+npx swift-code-reviewer-skill init --all                   # all agents at once
+npx swift-code-reviewer-skill init --agent codex,gemini    # specific subset
+npx swift-code-reviewer-skill init --dry-run               # preview without writing files
+```
+
+### 3. Run a review
 
 ```
-You code  -->  /review before push (free, local)  -->  done
+/review                      # Claude: staged + unstaged Swift changes
+@swift-code-reviewer         # Claude: invoke agent directly
 ```
 
-- `/review` runs the full review checklist against your staged or unstaged Swift changes
-- `@swift-code-reviewer` invokes the agent directly for deeper analysis
+For Gemini: `/review` (via `.gemini/commands/review.toml`).
+For Codex and Kiro: ask the agent to review your Swift changes directly.
 
-## Usage
+---
 
-![Swift Code Reviewer in action](assets/demo.png)
+## Choose Your Agent
 
-Ask Claude to review your code:
+| Agent           | Install target                          | `/review` command | Auto-activates  | Project standards file                |
+| --------------- | --------------------------------------- | :---------------: | :-------------: | ------------------------------------- |
+| **Claude Code** | `.claude/agents/swift-code-reviewer.md` |        ✅         |        —        | `.claude/CLAUDE.md`                   |
+| **Codex CLI**   | `swift-code-reviewer.md` (root)         |        ❌         |        —        | `AGENTS.md`                           |
+| **Gemini CLI**  | `swift-code-reviewer.md` (root)         |        ✅         |        —        | `GEMINI.md`                           |
+| **Kiro**        | `.kiro/steering/swift-code-reviewer.md` |         —         | ✅ `**/*.swift` | `.kiro/steering/project-standards.md` |
 
-```
-Review this PR
-Review LoginView.swift
-Review my uncommitted changes
-Review all ViewModels in the Features folder
-Check if this follows our coding standards
-```
+---
 
-Or use the slash command after running `init`:
+## Capability Matrix
+
+| Feature                         | Claude  |   Codex    |   Gemini   |    Kiro    |
+| ------------------------------- | :-----: | :--------: | :--------: | :--------: |
+| Phase 0 — Spec adherence        |   ✅    |     ✅     |     ✅     |     ✅     |
+| Phase 1 — Swift quality         |   ✅    |     ✅     |     ✅     |     ✅     |
+| Phase 2 — SwiftUI patterns      |   ✅    |     ✅     |     ✅     |     ✅     |
+| Phase 3 — Performance           |   ✅    |     ✅     |     ✅     |     ✅     |
+| Phase 4 — Security              |   ✅    |     ✅     |     ✅     |     ✅     |
+| Phase 5 — Architecture          |   ✅    |     ✅     |     ✅     |     ✅     |
+| Phase 6 — Project standards     |   ✅    |     ✅     |     ✅     |     ✅     |
+| Phase 2.5 — Agent loop feedback |   ✅    |     ✅     |     ✅     |     ✅     |
+| Companion skill cross-refs      | ✅ full | ⚡ inlined | ⚡ inlined | ⚡ inlined |
+| `/review` slash command         |   ✅    |     ❌     |     ✅     |     —      |
+| Auto-activates on Swift files   |    —    |     —      |     —      |     ✅     |
+
+---
+
+## Highlights
+
+- **Seven-layer analysis** — spec adherence, Swift 6+ concurrency, SwiftUI patterns, performance, security, architecture, and project standards
+- **Agent loop feedback** — detects recurring patterns and drafts `.claude/CLAUDE.md` rules to prevent them in future AI-generated code
+- **Spec-first** — validates every acceptance criterion in the PR description against the actual diff; flags scope creep and missing implementations
+- **Project-aware** — reads your project's standards file (`.claude/CLAUDE.md`, `AGENTS.md`, or `GEMINI.md`) and flags violations
+- **Four agents, one install** — interactive `init` scaffolds the right files for each agent with idempotent, non-destructive writes
+
+---
+
+## How It Works
 
 ```
-/review
+Phase 1  Context Gathering
+  → gh pr view / glab mr view + git diff + project standards file
+
+Phase 2  Analysis (per category)
+  0. Spec Adherence     — requirement coverage table, scope creep, missing work
+  1. Swift Quality      — concurrency, optionals, typed throws, naming
+  2. SwiftUI Patterns   — @Observable, NavigationStack, .task, accessibility
+  3. Performance        — ForEach identity, Equatable, lazy loading, GeometryReader
+  4. Security           — Keychain, HTTPS, no secrets in logs
+  5. Architecture       — MVVM/TCA, DI, testability
+  6. Project Standards  — custom rules from your project standards file
+
+Phase 2.5  Pattern Detection
+  → group findings by rule; flag any rule firing ≥2 times as a recurring pattern
+  → draft directives for your project standards file to prevent recurrence
+
+Phase 3  Report
+  → grouped by file, sorted by severity (Critical → High → Medium → Low)
+  → prioritized action items + agent loop feedback
 ```
 
-The skill automatically activates, reads your `.claude/CLAUDE.md` for project standards, and generates a structured report with severity levels, code examples, and prioritized action items.
+---
 
-### Example Output
+## Example Output
+
+The following is a representative excerpt from `examples/claude-tca-review.md`, generated
+against [pointfreeco/swift-composable-architecture](https://github.com/pointfreeco/swift-composable-architecture)
+at commit [`d9f965e`](https://github.com/pointfreeco/swift-composable-architecture/commit/d9f965e38a86c78279ff59dfab1754b637f097a2).
 
 ```markdown
-# Code Review Report
+# Code Review — FeatureReducer.swift, FeatureView.swift
 
 ## Summary
 
-- Files Reviewed: 3 | Critical: 0 | High: 1 | Medium: 2 | Low: 1
+Files: 2 | Critical: 0 | High: 2 | Medium: 1 | Low: 1
 
-## File: LoginViewModel.swift
+## Spec Adherence
 
-Pass **Excellent Modern API Usage** (line 12)
+**Source**: inferred from diff
 
-- Using @Observable instead of ObservableObject
+| Requirement                         | Status                                      | Location                |
+| ----------------------------------- | ------------------------------------------- | ----------------------- |
+| State mutations isolated to Reducer | ✅ Implemented                              | FeatureReducer.swift:34 |
+| View reads only from store          | ⚠️ Partial — direct URLSession call in body | FeatureView.swift:78    |
 
-Issue **Force Unwrap Detected** (line 89)
-Current: `let user = repository.currentUser!`
-Fix:
-guard let user = repository.currentUser else {
-logger.error("No current user")
-return
-}
+---
 
-Issue **Violates Design System Standard** (line 45)
-Current: `.foregroundColor(.blue)`
-Fix: `.foregroundColor(AppColors.primary)`
+## FeatureView.swift
 
-## Prioritized Action Items
+High **SwiftUI Patterns** (line 78)
+Current: `URLSession.shared.dataTask(with: url) { ... }.resume()`
+Fix: Move network call into the Reducer's Effect. Views in TCA must be
+pure transformations of State — side effects belong in Effects returned
+by the Reducer, not in the view body.
 
-1. [Must fix] Remove force unwrap at line 89
-2. [Should fix] Use design system colors at line 45
-```
+High **SwiftUI Patterns** (line 12)
+Current: `NavigationView { ... }`
+Fix: Replace with `NavigationStack`. NavigationView is deprecated as of iOS 16.
 
-## What It Reviews
+## Positive Observations
 
-| Category              | Checks                                                                                                    |
-| --------------------- | --------------------------------------------------------------------------------------------------------- |
-| **Swift Quality**     | Concurrency safety, actor isolation, Sendable, error handling, optionals, access control, naming          |
-| **SwiftUI Patterns**  | @Observable, state management, property wrappers, NavigationStack, .task, view composition, accessibility |
-| **Performance**       | View updates, Equatable, ForEach identity, GeometryReader, lazy loading, memory leaks                     |
-| **Security**          | Keychain, input validation, HTTPS, certificate pinning, API key protection, sensitive data logging        |
-| **Architecture**      | MVVM/MVI/TCA compliance, dependency injection, code organization, testability                             |
-| **Project Standards** | `.claude/CLAUDE.md` rules, design system, custom error patterns, testing requirements                     |
+FeatureReducer.swift correctly uses typed throws and @Sendable closures throughout.
 
-### Severity Levels
-
-| Icon     | Severity | Action                  |
-| -------- | -------- | ----------------------- |
-| Critical | Critical | Must fix before merge   |
-| High     | High     | Should fix before merge |
-| Medium   | Medium   | Fix in current sprint   |
-| Low      | Low      | Consider for future     |
+## Prioritized Action Items
 
-## Platform Support
+- [Must fix] Move URLSession call from view body into Reducer Effect (FeatureView.swift:78)
+- [Should fix] Replace NavigationView with NavigationStack (FeatureView.swift:12)
+- [Consider] Add Equatable conformance to FeatureView for diffing (FeatureView.swift:1)
 
-- Works with **GitHub PRs** (`gh`), **GitLab MRs** (`glab`), and **local git changes**
-- Swift 6.0+ | iOS 17+ | macOS 14+ | watchOS 10+ | tvOS 17+ | visionOS 1+
+---
 
-## Project-Specific Standards
+## Agent Loop Feedback
 
-Add a `.claude/CLAUDE.md` to your project and the skill will validate against your rules:
+### Pattern: NavigationView (2 occurrences)
 
-```markdown
-# MyApp Standards
+**Files**: FeatureView.swift:12, SettingsView.swift:44
+**Suggested rule for .claude/CLAUDE.md**:
 
-## Architecture
+> Use `NavigationStack` exclusively. `NavigationView` is deprecated as of iOS 16.
+```
 
-- ViewModels MUST use @Observable (iOS 17+)
-- All dependencies MUST be injected via constructor
-- Views MUST NOT contain business logic
+See [`examples/`](examples/) for three full review reports against real OSS projects.
 
-## Design System
+---
 
-- Use AppColors enum ONLY
-- Use AppFonts enum ONLY
+## Installation
 
-## Testing
+### Primary (recommended)
 
-- Minimum coverage: 80%
-- All ViewModels MUST have unit tests
+```bash
+npx skills add Viniciuscarvalho/swift-code-reviewer-skill
+npx swift-code-reviewer-skill init
 ```
 
-## Alternative Installation
-
-<details>
-<summary>NPX installer (installs skill only)</summary>
+### NPX installer (skill only, no `init`)
 
 ```bash
 npx swift-code-reviewer-skill
 ```
 
-</details>
-
-<details>
-<summary>Clone this repository</summary>
+### Clone (for offline or development use)
 
 ```bash
-git clone https://github.com/Viniciuscarvalho/swift-code-reviewer-skill.git ~/.claude/skills/swift-code-reviewer-skill
+git clone https://github.com/Viniciuscarvalho/swift-code-reviewer-skill.git \
+  ~/.claude/skills/swift-code-reviewer-skill
 ```
 
-</details>
-
-<details>
-<summary>Update to latest version</summary>
+### Update
 
 ```bash
 npx swift-code-reviewer-skill@latest
 ```
 
-This replaces the existing `~/.claude/skills/swift-code-reviewer-skill/` with the latest files.
-
-</details>
-
-<details>
-<summary>Uninstall</summary>
+### Uninstall
 
 ```bash
 npx swift-code-reviewer-skill uninstall
 ```
 
-</details>
+---
+
+## CLI Reference
+
+```
+npx swift-code-reviewer-skill [command] [options]
+
+Commands:
+  (none)     Install the skill to ~/.claude/skills/
+  init       Scaffold review agent into the current project
+  uninstall  Remove the skill from ~/.claude/skills/
+  help       Show help
+
+Options for init:
+  --agent <name[,name]>   Target specific agent(s): claude, codex, gemini, kiro
+  --all                   Install for all supported agents
+  --force                 Overwrite existing files
+  --dry-run               Preview writes without touching the filesystem
+```
+
+---
+
+## Configuration
 
-## Bundled Companion Skills
+The skill validates your code against a project-specific standards file. The file path differs by agent:
 
-This repo ships five companion skills under `skills/` so you get a complete, self-contained knowledge base after a single install — no extra steps required.
+| Agent       | Standards file                        |
+| ----------- | ------------------------------------- |
+| Claude Code | `.claude/CLAUDE.md`                   |
+| Codex CLI   | `AGENTS.md`                           |
+| Gemini CLI  | `GEMINI.md`                           |
+| Kiro        | `.kiro/steering/project-standards.md` |
+
+The file is optional — if absent, the skill falls back to Apple's official Swift API Design Guidelines.
+
+**Example `.claude/CLAUDE.md`:**
+
+```markdown
+# MyApp Standards
+
+## Architecture
+
+- ViewModels MUST use @Observable (iOS 17+)
+- All dependencies MUST be injected via constructor
+- Views MUST NOT contain business logic
+
+## Design System
+
+- Use AppColors enum ONLY
+- Use AppFonts enum ONLY
+
+## Testing
+
+- Minimum coverage: 80%
+- All ViewModels MUST have unit tests
+```
+
+---
+
+## Companion Skills (Claude)
+
+When installed via `npx skills add`, Claude can read supplementary reference files from the
+bundled companion skills for deeper context on specific topics:
 
 ```
 skills/
@@ -203,36 +290,146 @@ skills/
 └── swiftui-ui-patterns/         ← 32 component references (nav, sheets, grids…)
 ```
 
-The reviewer's `SKILL.md` points to specific reference files inside each skill, so during a review Claude can read the exact guidance it needs without any extra configuration.
+For Codex, Gemini, and Kiro, the must-load excerpts from these skills are inlined directly
+into the respective wrapper templates — no separate install step needed.
 
 ### Thanks to the original authors
 
-The bundled skills are based on the public Swift/SwiftUI work of:
-
 | Author              | GitHub                                     |
 | ------------------- | ------------------------------------------ |
 | Antoine van der Lee | [@AvdLee](https://github.com/AvdLee)       |
 | Thomas Ricouard     | [@Dimillian](https://github.com/Dimillian) |
 | Eduardo Bocato      | [@bocato](https://github.com/bocato)       |
 
-Each skill folder contains a `NOTICE.md` with attribution details. Upstream folders carried no `LICENSE` or `AUTHORS` files — if you are an original author and want attribution updated or content removed, please [open an issue](https://github.com/Viniciuscarvalho/swift-code-reviewer-skill/issues).
+Each skill folder contains a `NOTICE.md` with attribution details. If you are an original
+author and want attribution updated or content removed, please
+[open an issue](https://github.com/Viniciuscarvalho/swift-code-reviewer-skill/issues).
+
+---
+
+## Per-Agent Quirks & Limitations
+
+### Claude Code
+
+- Full companion-skill cross-references resolve automatically from `~/.claude/skills/swift-*/`
+- `/review` slash command available after `init`
+
+### OpenAI Codex CLI
+
+- No `/review` slash command — Codex CLI does not support custom slash commands
+- `@`-path mentions in `AGENTS.md` are **not** auto-resolved; Codex concatenates `AGENTS.md`
+  verbatim into the system prompt. After `init`, paste this into your `AGENTS.md` manually:
+
+  ```markdown
+  ## Swift code review
+
+  See swift-code-reviewer.md for the full review guide.
+  ```
+
+- Companion skill excerpts are inlined into `swift-code-reviewer.md`; no external files needed
+
+### Google Gemini CLI
+
+- `/review` available via `.gemini/commands/review.toml` — the TOML `prompt` field uses
+  `@./swift-code-reviewer.md` which Gemini **does** resolve at command invocation time
+- Companion skill excerpts are inlined; no external files needed
+
+### Kiro
+
+- Steering is workspace-scoped (`inclusion: fileMatch`, `fileMatchPattern: "**/*.swift"`) —
+  the guide activates automatically whenever you open or edit a Swift file
+- **Known bug**: Kiro global steering has a bug
+  ([kirodotdev/Kiro#6171](https://github.com/kirodotdev/Kiro/issues/6171)) — workspace-scoped
+  steering is the recommended path until it is resolved
+- No dedicated slash command — ask Kiro directly to review your Swift changes
+
+---
+
+## Project Layout
+
+```
+swift-code-reviewer-skill/
+├── core/
+│   └── swift-code-reviewer.core.md  ← canonical agent-agnostic source of truth
+├── templates/
+│   ├── agents/
+│   │   ├── claude/swift-code-reviewer.md
+│   │   ├── codex/swift-code-reviewer.md
+│   │   ├── gemini/swift-code-reviewer.md
+│   │   └── kiro/swift-code-reviewer.md
+│   └── commands/
+│       ├── claude/review.md
+│       └── gemini/review.toml
+├── references/                       ← detailed review checklists (agent-agnostic)
+│   ├── review-workflow.md
+│   ├── swift-quality-checklist.md
+│   ├── swiftui-review-checklist.md
+│   ├── performance-review.md
+│   ├── security-checklist.md
+│   ├── architecture-patterns.md
+│   ├── feedback-templates.md
+│   ├── spec-adherence.md
+│   ├── agent-loop-feedback.md
+│   └── custom-guidelines.md
+├── skills/                           ← bundled companion skills
+├── examples/                         ← real review reports (3 OSS projects)
+├── assets/
+│   ├── demo.png
+│   └── init-demo.tape                ← VHS script for init-demo.gif
+├── bin/
+│   ├── install.js                    ← CLI entry point
+│   └── lib/
+│       ├── agents.js                 ← per-agent install functions
+│       └── prompt.js                 ← TTY-aware agent selector
+├── __tests__/
+│   └── installer.test.js
+└── SKILL.md                          ← Claude Code skill descriptor
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/Viniciuscarvalho/swift-code-reviewer-skill.git
+cd swift-code-reviewer-skill
+npm install
+
+# Run installer tests
+node --test __tests__/installer.test.js
+
+# Preview init in a sandbox
+cd "$(mktemp -d)" && git init
+node /path/to/swift-code-reviewer-skill/bin/install.js init --dry-run
+node /path/to/swift-code-reviewer-skill/bin/install.js init --all
+node /path/to/swift-code-reviewer-skill/bin/install.js init  # interactive
+
+# Regenerate the demo GIF (requires vhs)
+brew install vhs
+vhs /path/to/swift-code-reviewer-skill/assets/init-demo.tape
+```
+
+---
 
 ## Contributing
 
-1. Edit `SKILL.md` for main skill logic
-2. Update reference files in `references/` for specific checklists
-3. Add/modify templates in `templates/` for agent and command scaffolding
-4. Test with real Swift/SwiftUI code
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide, including the
+[**Adding a new agent target**](CONTRIBUTING.md#adding-a-new-agent-target) checklist.
+
+1. Edit `SKILL.md` or `core/swift-code-reviewer.core.md` for review logic
+2. Update `references/` for specific checklists
+3. Add/modify per-agent templates in `templates/`
+4. Add tests in `__tests__/installer.test.js`
 5. Submit a pull request
 
+---
+
 ## License
 
-MIT License - See [LICENSE](LICENSE) file for details.
+MIT — see [LICENSE](LICENSE).
 
 ---
 
 **Made with care for the Swift community**
 
-If this skill helps your code reviews, please star the repository!
-
-- [Issues](https://github.com/Viniciuscarvalho/swift-code-reviewer-skill/issues) | [Discussions](https://github.com/Viniciuscarvalho/swift-code-reviewer-skill/discussions)
+[Issues](https://github.com/Viniciuscarvalho/swift-code-reviewer-skill/issues) · [Discussions](https://github.com/Viniciuscarvalho/swift-code-reviewer-skill/discussions) · [Sponsor](https://github.com/sponsors/Viniciuscarvalho)