swift-code-reviewer-skill 1.2.0 → 1.3.0

package/bin/install.js

@@ -84,7 +84,7 @@ function install() {
     'CHANGELOG.md'
   ];
 
-  const dirsToCopy = ['references'];
+  const dirsToCopy = ['references', 'skills', 'templates'];
 
   for (const file of filesToCopy) {
     const src = path.join(packageRoot, file);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swift-code-reviewer-skill",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Claude Code skill for comprehensive Swift/SwiftUI code reviews with multi-layer analysis",
   "keywords": [
     "claude",
@@ -41,6 +41,7 @@
   "files": [
     "bin/",
     "references/",
+    "skills/",
     "templates/",
     "SKILL.md",
     "README.md",

package/references/agent-loop-feedback.md

@@ -0,0 +1,148 @@
+# Agent Loop Feedback Reference
+
+When the code under review was generated by an AI agent, recurring mistakes
+are not just *code* problems — they are *instruction* problems. This document
+defines how the reviewer aggregates per-finding signals into rule suggestions
+that can be added to `.claude/CLAUDE.md` or an agent system prompt to prevent
+the same class of issue next time.
+
+---
+
+## 1. The ≥2 Threshold
+
+A single instance of a mistake is a slip. Two is a pattern. Three or more
+means the agent's instructions are silent on the topic and need an explicit
+rule.
+
+Rules of thumb:
+
+| Occurrences in diff | Treatment                                                                         |
+| ------------------- | --------------------------------------------------------------------------------- |
+| 1                   | Per-file finding only. Do not surface in Agent Loop Feedback.                     |
+| 2                   | Recurring pattern. Suggest a rule. Mark priority **medium**.                      |
+| 3+                  | Strong signal. Suggest a rule. Mark priority **high**.                            |
+| 2+ across PRs       | If the same rule has been suggested before (see §3), escalate to **high**.        |
+
+Count occurrences by **rule**, not by raw findings. For example, four force-unwrap
+findings in different files count as four occurrences of the rule
+*"never force-unwrap"*, not four separate rules.
+
+---
+
+## 2. Phrasing Rules as Directives
+
+Rules go in an instruction file the agent will *read*. Write them so the
+reader knows what to do without further interpretation.
+
+### Strong forms
+
+- **Never X.** — bans an action outright. Best for safety/security/crashes.
+- **Always Y.** — mandates an action. Best for required patterns.
+- **Prefer X over Y.** — gives a default with an implicit escape hatch. Best
+  for stylistic or modernization rules.
+- **Use X. Y is deprecated / forbidden.** — adds the *why* in five words.
+
+### Weak forms (avoid)
+
+- **"Try to..."** — agents will skip it under pressure.
+- **"It's a good idea to..."** — descriptive, not directive.
+- **"Consider..."** — fine in code review prose, useless as a rule.
+- **"X is bad"** — diagnostic, not prescriptive. Doesn't tell the agent what
+  to do instead.
+
+### Examples
+
+| Weak                                                   | Strong                                                                                              |
+| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| Force unwraps are dangerous.                           | Never use `!`, `try!`, or `as!`. Use `guard let` with an early return, typed throws, or `as?`.      |
+| It's better to use `NavigationStack`.                  | Use `NavigationStack` exclusively. `NavigationView` is deprecated as of iOS 16.                     |
+| Try to keep views simple.                              | Views must not contain business logic, network calls, or data transformations. Move all such work into the `@Observable` view model. |
+| Make sure UI updates happen on the main thread.        | Always annotate types that mutate `@Observable`/`@Published` state with `@MainActor`.               |
+| Don't put secrets in logs.                             | Never log values from `KeychainService`, `URLRequest.httpBody`, or types annotated `@Sensitive`.    |
+
+A good rule answers three questions in one sentence: *what is forbidden*,
+*what is the alternative*, and (briefly) *why*.
+
+---
+
+## 3. Checking Past Reviews
+
+Before suggesting a rule, check whether something similar was already
+suggested. If yes, the existing wording is not landing — escalate priority
+and consider strengthening the wording rather than restating it.
+
+```bash
+# Has anyone touched the rules file recently, and how?
+git log --oneline --follow .claude/CLAUDE.md
+git log -p --follow .claude/CLAUDE.md | grep -i "<keyword from new rule>"
+
+# Search for existing wording on the topic
+grep -in "force.unwrap\|navigationview\|mainactor" .claude/CLAUDE.md
+```
+
+If a rule on the same topic exists:
+
+1. Quote the current rule in the suggestion block.
+2. Explain why it is not preventing the pattern (too soft, too narrow,
+   buried, conditional).
+3. Propose a replacement, not an addition.
+
+If no rule exists, propose adding one in the most relevant section
+(`Concurrency`, `SwiftUI`, `Security`, `Architecture`, etc.).
+
+---
+
+## 4. Suggested-Rule Block — Template
+
+One block per recurring pattern. Place all blocks under a single
+`## Agent Loop Feedback` heading at the bottom of the report.
+
+```markdown
+### Pattern: <short name> (<N> occurrences)
+**Files**: <file:line>, <file:line>, ...
+
+**Suggested rule**:
+> <One-sentence directive in strong form. What is forbidden, what to do
+> instead, and one-clause why.>
+
+**Existing rule** (if any): <quote, with line reference into `.claude/CLAUDE.md`>
+
+**Why it's not landing** (only if existing rule): <too soft / too narrow / buried / etc.>
+
+**Priority**: <medium | high>
+```
+
+Worked example:
+
+```markdown
+### Pattern: Force-unwraps (4 occurrences)
+**Files**: LoginView.swift:89, NetworkService.swift:34, UserRepo.swift:12, UserRepo.swift: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.
+
+**Existing rule**: _.claude/CLAUDE.md:42_ — "Avoid force unwrapping when possible."
+
+**Why it's not landing**: "When possible" gives the agent a built-in opt-out.
+The replacement above bans the syntax outright and names the alternatives.
+
+**Priority**: high
+```
+
+---
+
+## 5. Human-Authored Code
+
+If the PR was written by a human (no AI assistance disclosed, no agent
+session metadata in commit messages), the same recurring patterns are still
+useful — but frame them as **team coding standards**, not agent instructions:
+
+- Replace "Suggested rule for the agent" with "Suggested team standard".
+- Drop the "Why it's not landing" clause; humans benefit more from a short
+  rationale than from instruction-tuning analysis.
+- Leave the directive phrasing intact — strong forms read better in human
+  style guides too.
+
+When unsure whether the code is AI-generated, default to the team-standards
+framing.

package/references/companion-skills.md

@@ -0,0 +1,70 @@
+# Companion Skills Reference
+
+Full attribution and update instructions: [`skills/README.md`](../skills/README.md)
+Original authors: [@AvdLee](https://github.com/AvdLee), [@Dimillian](https://github.com/Dimillian), [@bocato](https://github.com/bocato)
+
+---
+
+## swiftui-expert-skill · `skills/swiftui-expert-skill/`
+
+| Reference file                         | When to consult                                                           |
+| -------------------------------------- | ------------------------------------------------------------------------- |
+| `references/state-management.md`       | Property wrapper selection — @State, @Binding, @Observable, @Environment  |
+| `references/latest-apis.md`            | Deprecation detection — always check before flagging an API as deprecated |
+| `references/view-structure.md`         | View extraction rules and composition depth limits                        |
+| `references/performance-patterns.md`   | Equatable conformance, body evaluation cost, lazy loading                 |
+| `references/accessibility-patterns.md` | VoiceOver grouping, traits, Dynamic Type support                          |
+| `references/liquid-glass.md`           | iOS 26+ Liquid Glass adoption and availability gating                     |
+| `references/animation-basics.md`       | Implicit/explicit animation, withAnimation, matchedGeometryEffect         |
+| `references/macos-scenes.md`           | macOS-specific Scene types, window styling, settings                      |
+
+---
+
+## swift-concurrency · `skills/swift-concurrency/`
+
+| Reference file                     | When to consult                                             |
+| ---------------------------------- | ----------------------------------------------------------- |
+| `references/sendable.md`           | Sendable conformance, `@unchecked Sendable` justification   |
+| `references/actors.md`             | Actor isolation, custom actors vs @MainActor                |
+| `references/async-await-basics.md` | Structured vs unstructured tasks, `Task.detached` rationale |
+| `references/migration.md`          | Swift 6 migration patterns, minimum blast-radius approach   |
+| `references/testing.md`            | Concurrency-safe test patterns                              |
+| `references/threading.md`          | Thread safety, GCD interop, isolation boundaries            |
+
+---
+
+## swift-testing · `skills/swift-testing/`
+
+| Reference file                      | When to consult                                               |
+| ----------------------------------- | ------------------------------------------------------------- |
+| `references/test-organization.md`   | @Suite hierarchy, naming, tagging                             |
+| `references/test-doubles.md`        | Dummy / Fake / Stub / Spy / Mock taxonomy                     |
+| `references/async-testing.md`       | `#expect(throws:)`, async confirmation patterns               |
+| `references/parameterized-tests.md` | `@Test(arguments:)` for data-driven tests                     |
+| `references/migration-xctest.md`    | XCTest → Swift Testing migration checklist                    |
+| `references/fixtures.md`            | Fixture placement with `#if DEBUG`, test target vs app target |
+
+---
+
+## swift-expert · `skills/swift-expert/`
+
+| Reference file                     | When to consult                                                       |
+| ---------------------------------- | --------------------------------------------------------------------- |
+| `references/async-concurrency.md`  | Cross-cutting concurrency patterns                                    |
+| `references/protocol-oriented.md`  | Protocol hierarchies, associated types, existentials, `any` vs `some` |
+| `references/memory-performance.md` | Value vs reference semantics, ARC, retain cycles                      |
+| `references/swiftui-patterns.md`   | Additional SwiftUI architectural guidance                             |
+
+---
+
+## swiftui-ui-patterns · `skills/swiftui-ui-patterns/`
+
+| Reference file                   | When to consult                                           |
+| -------------------------------- | --------------------------------------------------------- |
+| `references/components-index.md` | Full component catalogue — start here for any UI pattern  |
+| `references/navigationstack.md`  | Route enums, RouterPath, `navigationDestination`          |
+| `references/sheets.md`           | Item-driven sheets, SheetDestination enum                 |
+| `references/theming.md`          | Semantic color enforcement via `@Environment(Theme.self)` |
+| `references/async-state.md`      | `.task(id:)`, LoadState enum, CancellationError           |
+| `references/tabview.md`          | Tab architecture, per-tab independent navigation history  |
+| `references/grids.md`            | LazyVGrid / LazyHGrid patterns and identity               |

package/references/spec-adherence.md

@@ -0,0 +1,157 @@
+# Spec Adherence Reference
+
+This document describes how the reviewer extracts the *intent* of a change from
+its PR description and linked issues, and how it then judges whether the code
+delivers on that intent. Spec adherence runs before the language- and
+framework-level checks: a clean diff that misses the point shouldn't pass.
+
+---
+
+## 1. Parsing `gh` / `glab` JSON Output
+
+Always prefer the JSON output of the platform CLI over scraping the web UI —
+it is stable, scriptable, and includes linked-issue metadata.
+
+### GitHub
+
+```bash
+# PR body, title, labels, and the issues this PR closes
+gh pr view <num> --json title,body,closingIssuesReferences,labels
+
+# Linked issue (one per closing reference)
+gh issue view <num> --json title,body,labels
+
+# Reviewer-friendly summary in one shot
+gh pr view <num> --json title,body,closingIssuesReferences \
+  --jq '{title, body, issues: [.closingIssuesReferences[].number]}'
+```
+
+Fields to read:
+
+| Field                       | Use                                               |
+| --------------------------- | ------------------------------------------------- |
+| `title`                     | Short statement of intent — start here.           |
+| `body`                      | Acceptance criteria, scope, non-goals.            |
+| `closingIssuesReferences`   | Numbers of issues that this PR will close.        |
+| `labels`                    | `bug`, `feature`, `tech-debt` shape expectations. |
+
+### GitLab
+
+```bash
+glab mr view <num>           # human-readable; pipe to less
+glab mr view <num> --output json
+glab issue view <num> --output json
+```
+
+GitLab's MR description and linked issues serve the same role as GitHub's PR
+body and `closingIssuesReferences`.
+
+---
+
+## 2. Finding Acceptance Criteria
+
+Acceptance criteria are rarely labeled as such. Look for these patterns, in
+roughly this order:
+
+1. **Markdown checkboxes** — `- [ ] ...` or `- [x] ...`. The most reliable
+   signal. Each box is a discrete requirement.
+2. **Gherkin / Given-When-Then** — phrases starting with `Given`, `When`,
+   `Then`, or `And`. Common in BDD-flavored teams.
+3. **Modal verbs** — `must`, `should`, `shall`, `will`, `needs to`. Each
+   sentence is a candidate requirement; `must`/`shall` outrank `should`.
+4. **Numbered or bulleted lists** under headings like `Acceptance Criteria`,
+   `Requirements`, `Scope`, `Goals`, `What this PR does`.
+5. **"Closes #N" / "Fixes #N"** — pull the linked issue and repeat 1–4 there.
+
+If the PR has none of the above, treat the **title** as the single requirement
+and note the lack of explicit criteria in the report.
+
+---
+
+## 3. Handling PRs With No Description
+
+A blank or near-blank description is itself a finding. Do not invent intent.
+
+1. Note in the report: _"PR description is empty / minimal — spec adherence
+   inferred from diff and commit messages, may be incomplete."_
+2. Use, in order: linked issues, commit messages (`git log <base>..HEAD`),
+   branch name, file paths touched.
+3. List every inferred requirement explicitly so the author can correct any
+   misreading, prefixed with `(inferred)`.
+4. Do not penalize the diff for failing to satisfy a requirement that was
+   only inferred — flag the missing description instead.
+
+---
+
+## 4. Scope Creep vs. Legitimate Adjacent Fixes
+
+Not every out-of-spec change is scope creep. Use this rubric:
+
+| Change type                                                                  | Verdict                               |
+| ---------------------------------------------------------------------------- | ------------------------------------- |
+| Touches a file required by the spec, fixes an obvious nearby bug, < ~10 LOC  | **Allow** — note it; don't flag.      |
+| Renames or restructures a file the spec requires editing                     | **Allow if minimal**, otherwise flag. |
+| Drive-by formatting / style changes across many files                        | **Flag** — recommend separate PR.     |
+| Refactor of a module unrelated to the spec                                   | **Flag** — scope creep.               |
+| New feature not mentioned anywhere in spec                                   | **Flag** — scope creep, must justify. |
+| Dependency version bumps                                                     | **Flag** — separate PR by convention. |
+| Test additions for the spec'd code                                           | **Allow** — expected.                 |
+| Test additions for unrelated existing code                                   | **Allow but note** — usually welcome. |
+
+When flagging scope creep, always recommend the concrete remediation
+("split out into a follow-up PR" or "move to a separate commit if the team
+allows partial review").
+
+---
+
+## 5. Intent Drift
+
+The trickier failure mode: the diff *runs* but solves a subtly different
+problem than the spec. Symptoms:
+
+- Naming uses different domain terms than the spec (e.g., spec says
+  "session", code says "token").
+- Data flow contradicts the spec's mental model (e.g., spec says the server
+  is the source of truth, code caches and treats local as authoritative).
+- Edge cases the spec called out are silently excluded by an early `return`.
+- The PR title says "fix" but the diff is a rewrite, or vice versa.
+
+When you suspect intent drift, quote both the spec sentence and the code
+location side-by-side in the finding.
+
+---
+
+## 6. Requirement Coverage Table — Template
+
+Drop this into the Spec Adherence section of the report, one row per
+requirement extracted in step 2.
+
+```markdown
+## Spec Adherence
+
+**Source**: PR #<num> / Issue #<num>
+
+| Requirement                              | Status                              | Location                       |
+|------------------------------------------|-------------------------------------|--------------------------------|
+| <verbatim or paraphrased criterion>      | ✅ Implemented                       | `<file>:<line>`                |
+| <criterion with edge case>               | ⚠️ Partial — <what's missing>        | `<file>:<line>`                |
+| <criterion>                              | ❌ Not implemented                   | —                              |
+| <inferred criterion>                     | ✅ Implemented (inferred)            | `<file>:<line>`                |
+
+**Scope creep**: <count> unrelated change(s) — <one-line summary, recommend split>.
+
+**Spec gaps**: <count> criterion/criteria not addressed — see "Must fix" in
+prioritized action items.
+```
+
+Status legend (use these exact glyphs for greppability):
+
+- ✅ Implemented — code satisfies the criterion and tests, if any, cover it.
+- ⚠️ Partial — happy path works, but at least one edge case or branch is
+  missing. Always say *what* is missing.
+- ❌ Not implemented — no code addresses the criterion.
+- ➖ Not assessed — no spec context available; do not guess.
+
+If `status` is anything other than ✅, the corresponding action item belongs
+in **Must fix** or **Should fix** depending on whether the criterion was
+flagged `must`/`shall` versus `should`.

package/skills/README.md

@@ -0,0 +1,43 @@
+# Bundled Companion Skills
+
+This directory contains five companion skills vendored directly into `swift-code-reviewer-skill` so that reviewers have a complete, self-contained knowledge base after a single install or clone — no extra setup required.
+
+## Thanks to the original authors
+
+These skills are based on the public Swift/SwiftUI work of three community contributors:
+
+| Author              | GitHub                                     | Known for                                                     |
+| ------------------- | ------------------------------------------ | ------------------------------------------------------------- |
+| Antoine van der Lee | [@AvdLee](https://github.com/AvdLee)       | SwiftLee — concurrency, testing, Swift 6 migration            |
+| Thomas Ricouard     | [@Dimillian](https://github.com/Dimillian) | IceCubesApp — SwiftUI architecture, Liquid Glass, UI patterns |
+| Eduardo Bocato      | [@bocato](https://github.com/bocato)       | Clean Architecture, protocol-oriented Swift, Swift expert     |
+
+Attribution is best-effort — upstream folders carried no `LICENSE` or `AUTHORS` files. If you are one of the original authors and want the attribution corrected or content removed, please [open an issue](https://github.com/Viniciuscarvalho/swift-code-reviewer-skill/issues).
+
+---
+
+## Skills index
+
+| Skill                                                 | Primary author | Description                                                                                     | References                                                                              |
+| ----------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| [swiftui-expert-skill](swiftui-expert-skill/SKILL.md) | @Dimillian     | Write, review, or improve SwiftUI code: state management, view composition, Liquid Glass, macOS | [19 files](swiftui-expert-skill/references/) · [NOTICE](swiftui-expert-skill/NOTICE.md) |
+| [swift-concurrency](swift-concurrency/SKILL.md)       | @AvdLee        | Expert guidance on actors, Sendable, async/await, Swift 6 migration, data races                 | [13 files](swift-concurrency/references/) · [NOTICE](swift-concurrency/NOTICE.md)       |
+| [swift-testing](swift-testing/SKILL.md)               | @AvdLee        | Modern Swift Testing framework: @Test, #expect, doubles, snapshots, XCTest migration            | [9 files](swift-testing/references/) · [NOTICE](swift-testing/NOTICE.md)                |
+| [swift-expert](swift-expert/SKILL.md)                 | @bocato        | Senior Swift 6+ specialist: protocol-oriented design, memory, concurrency, SwiftUI patterns     | [5 files](swift-expert/references/) · [NOTICE](swift-expert/NOTICE.md)                  |
+| [swiftui-ui-patterns](swiftui-ui-patterns/SKILL.md)   | @Dimillian     | Component-level SwiftUI patterns: navigation, lists, sheets, grids, theming, gestures           | [32 files](swiftui-ui-patterns/references/) · [NOTICE](swiftui-ui-patterns/NOTICE.md)   |
+
+---
+
+## Updating a skill
+
+Each skill is a verbatim copy of its source. To refresh one:
+
+```bash
+rsync -rL --exclude='.DS_Store' ~/.agents/skills/swiftui-expert-skill/ skills/swiftui-expert-skill/
+rsync -rL --exclude='.DS_Store' ~/.claude/skills/swift-concurrency/ skills/swift-concurrency/
+rsync -rL --exclude='.DS_Store' ~/.claude/skills/swift-testing/ skills/swift-testing/
+rsync -rL --exclude='.DS_Store' ~/.maestro/skills/swift-expert/ skills/swift-expert/
+rsync -rL --exclude='.DS_Store' ~/.maestro/skills/swiftui-ui-patterns/ skills/swiftui-ui-patterns/
+```
+
+Do not edit files under `skills/` directly — changes will be overwritten on the next sync.

package/skills/swift-concurrency/NOTICE.md

@@ -0,0 +1,18 @@
+# swift-concurrency — Attribution Notice
+
+Bundled into `swift-code-reviewer-skill` on 2026-04-21 from
+`~/.claude/skills/swift-concurrency`.
+
+Primary author (best-effort attribution): **Antoine van der Lee ([@AvdLee](https://github.com/AvdLee))**
+Also credited: [@Dimillian](https://github.com/Dimillian), [@bocato](https://github.com/bocato)
+
+These three authors' public Swift/SwiftUI content — including SwiftLee, IceCubesApp,
+and their various open-source contributions — informed the skills bundled here.
+
+License: the upstream folder did not contain a LICENSE file at the time of vendoring.
+Content is reproduced here in good faith for reference alongside this MIT-licensed
+project. If you are an upstream author and want the attribution corrected, the license
+clarified, or the content removed, please open an issue at:
+https://github.com/Viniciuscarvalho/swift-code-reviewer-skill/issues
+
+Changes from upstream: none (verbatim copy; `.DS_Store` files excluded).