swift-engineering — плагин для Claude Code
Плагин swift-engineering для Claude Code включает субагентов и скиллы для планирования, разработки на Swift и TCA, тестирования и ревью iOS- и macOS-приложений.
MIT ★ 233 обновлён 2026-01-18
/plugin marketplace add johnrogers/claude-swift-engineering
/plugin install swift-engineering@claude-swift-engineeringЧто делает swift-engineering
Плагин добавляет в Claude 12 субагентов и 18 скиллов под Swift и SwiftUI: архитектура, реализация, тесты, документация, ревью. Ветка на TCA разделена на два агента — один проектирует состояние, экшены и эффекты, второй пишет редьюсер.
Агенты общаются через файл плана в docs/plans/<feature-name>.md. Каждый читает его, дописывает статус и заметки для следующего, так что контекст не приходится передавать руками. Обычный проход начинается с @swift-architect и заканчивается на @swift-code-reviewer; если состояние простое, TCA пропускают и идут через @swift-engineer.
Для работы нужен Sosumi MCP Server в настройках Claude: агенты сверяют вызовы Apple API с документацией. Без него шаг проверки API не заработает. Версия 0.1.28 помечена как experimental, поэтому имена агентов и порядок шагов ещё меняются. Код рассчитан на iOS 26+ и Swift 6.2 со strict concurrency.
Какие задачи решает
- Спланировать фичу на TCA и получить файл плана в
docs/plans/ - Разложить состояние, экшены и эффекты до написания редьюсера
- Собрать вьюху на SwiftUI отдельно от бизнес-логики
- Покрыть редьюсер тестами на Swift Testing
- Прогнать ревью модуля перед релизом
Примеры запросов агенту
- @swift-architect спланируй фичу счётчика с кнопками плюс и минус
- @tca-engineer реализуй редьюсер счётчика по плану
- @swift-code-reviewer проверь модуль авторизации на безопасность
Как установить swift-engineering
Через маркетплейс плагинов
/plugin marketplace add johnrogers/claude-swift-engineering/plugin install swift-engineering@claude-swift-engineeringПо шагам, с командами для каждой платформы: Плагины Claude Code: маркетплейсы, установка и как собрать свой
Вопросы о swift-engineering
Как установить swift-engineering в Claude Code?
Через маркетплейс: сначала /plugin marketplace add johnrogers/claude-swift-engineering, затем /plugin install swift-engineering@claude-swift-engineering.
Что делает swift-engineering?
Даёт Claude субагентов и скиллы для полного цикла Swift-фичи: архитектура, реализация на TCA или чистом Swift, тесты, документация и код-ревью.
Что нужно настроить до первого запуска?
Sosumi MCP Server в настройках Claude: через него агенты смотрят документацию Apple и сверяют актуальные API.
Исходный текст
swift-engineering · MIT
# Swift Engineering Plugin
**Version:** 0.1.28
> ⚠️ **Experimental** — This plugin is actively developed. APIs, agents, and workflows may evolve.
Modern Swift/SwiftUI development toolkit with TCA support for Claude Code. Provides 12 specialized agents and 18 comprehensive skills for planning, implementing, testing, and shipping production iOS/macOS applications.
## Features at a Glance
- **12 specialized agents** — Planning, architecture, implementation, testing, and documentation
- **18 comprehensive skills** — Architecture patterns, frameworks, design guidelines, and development tools
- **Ultra-modern Swift** — iOS 26+, Swift 6.2, strict concurrency, SwiftUI-only
- **TCA-first architecture** — Separate architect and engineer agents with coordinated handoffs
- **Production-ready** — Built-in code review, testing, and quality assurance workflows
- **Coordination via plans** — All agents share state through plan files, no manual coordination needed
## Table of Contents
- [Core Capabilities](#core-capabilities)
- [Prerequisites](#prerequisites)
- [Getting Started](#getting-started)
- [Using Agents](#using-agents)
- [Agents](#agents)
- [Skills](#skills)
- [Installation](#installation)
- [Advanced Features](#advanced-features)
- [Workflow](#workflow)
- [Agent Handoff Model](#agent-handoff-model)
- [Plan File Format](#plan-file-format)
- [Architecture Conventions](#architecture-conventions)
- [Model Usage](#model-usage)
- [Quality Assurance](#quality-assurance)
- [Contributing](#contributing)
- [License](#license)
- [Feedback](#feedback)
## Core Capabilities
### Planning & Architecture
- Design features with UI mockups or descriptions
- Architecture decisions (TCA vs vanilla Swift)
- TCA-specific design (state, actions, effects, dependencies)
### Implementation
- Reducers and effects (TCA)
- Business logic and models (vanilla Swift)
- SwiftUI views with accessibility
- Modern async/await patterns
- Database operations (SQLite, CloudKit sync)
### Quality Assurance
- Comprehensive testing with Swift Testing
- Code review (security, performance, HIG compliance)
- Modernization (legacy to modern Swift conversion)
- Documentation generation
### Coordination
- Shared plan files for agent handoffs
- Automatic status tracking
- Clear ownership and next steps
## Prerequisites
**Sosumi MCP Server** — Required for Apple documentation lookup. Agents use this to verify modern API usage (2025). Configure in your Claude Code settings before using this plugin.
## Getting Started
1. **Install** this plugin in your Claude Code plugins directory
2. **Build a feature** by invoking agents in order (start with `@swift-architect` for new features)
3. **Agents coordinate** through plan files — no manual handoffs needed
4. **End with code review** via `@swift-code-reviewer` before shipping
For detailed workflows and examples, see [Using Agents](#using-agents) section below.
## Using Agents
This plugin provides ultra-specialized agents that you invoke directly to build features. Each agent has a specific role and understands when to hand off to the next agent in the workflow.
### Basic Workflow: Building a TCA Feature
For a typical feature using The Composable Architecture:
**Step 1: Plan the architecture**
```
@swift-architect Design a counter feature with increment/decrement buttons using TCA
```
This creates a plan file at `docs/plans/counter.md` with architecture decisions.
**Step 2: Design TCA architecture**
```
@tca-architect Design the state, actions, and effects for the counter based on the plan
```
Updates the plan with TCA-specific design details.
**Step 3: Implement the reducer**
```
@tca-engineer Implement the counter reducer and effects following the TCA design
```
Creates the actual Reducer implementation.
**Step 4: Create SwiftUI views**
```
@swiftui-specialist Create the counter view that displays the state and handles actions
```
Implements the UI without mixing in business logic.
**Step 5: Write tests**
```
@swift-test-creator Write comprehensive tests for the counter using Swift Testing
```
Creates test files with test cases.
**Step 6: Code review and verification**
```
@swift-code-reviewer Review the implementation for quality, security, and performance
```
Verifies code meets project standards before shipping.
### Alternative Workflow: Vanilla Swift Feature (No TCA)
For simpler features without complex state management:
**Step 1: Plan architecture**
```
@swift-architect Design a calculator utility (vanilla Swift, no UI)
```
**Step 2: Implement core logic**
```
@swift-engineer Implement the calculator logic following the plan
```
**Step 3: Write tests**
```
@swift-test-creator Write tests for the calculator using Swift Testing
```
**Step 4: Code review**
```
@swift-code-reviewer Review the implementation for quality and performance
```
### Common Tasks by Agent
| Task | Agent | Example |
|------|-------|---------|
| Analyze UI mockups/screenshots | `@swift-ui-design` | Analyze this design mockup and create UI specifications |
| Plan new features | `@swift-architect` | Plan a user authentication system |
| Design TCA architecture | `@tca-architect` | Design state/actions/effects for authentication |
| Implement TCA features | `@tca-engineer` | Implement the authentication reducer |
| Implement vanilla Swift | `@swift-engineer` | Implement the Settings model and persistence |
| Build SwiftUI views | `@swiftui-specialist` | Create the authentication UI following the design |
| Create tests | `@swift-test-creator` | Write tests for the authentication flow |
| Code review | `@swift-code-reviewer` | Review the authentication module for security and quality |
| Modernize code | `@swift-modernizer` | Migrate this legacy code to async/await |
| Documentation | `@swift-documenter` | Document the public API surface |
| Project docs | `@documentation-generator` | Create comprehensive project documentation |
| Fast code search | `@search` | Find all UserDefaults usage in the codebase |
| Code review | `@swift-code-reviewer` | Review the implementation for quality and security |
### Plan File Coordination
All agents coordinate through a shared plan file at `docs/plans/<feature-name>.md`. This file:
- Records architecture decisions (created by `@swift-architect`)
- Tracks implementation status
- Contains handoff notes from each agent to the next
- Ensures continuity across agent handoffs
Each agent will automatically read the plan, update it with their work, and add notes for the next agent.
### Key Principles
- **Start with `@swift-architect`** for new features to get architecture decisions
- **Use `@swift-ui-design`** if you have mockups or screenshots to analyze
- **Choose your path** — TCA for complex state, vanilla Swift for simpler features
- **Always end with `@swift-code-reviewer`** to verify quality before shipping
- **Agents coordinate via plan files** — No manual handoff needed, just invoke the next agent
## Agents
### Planning Agents (Opus, READ-ONLY)
| Agent | Purpose | Model |
|-------|---------|-------|
| `@swift-ui-design` | Analyze mockups OR descriptions into UI specifications | Opus |
| `@swift-architect` | Architecture decisions (TCA vs vanilla, persistence) | Opus |
| `@tca-architect` | TCA-specific design (state, actions, dependencies) | Opus |
### Implementation Agents (Inherit)
| Agent | Purpose | Model |
|-------|---------|-------|
| `@tca-engineer` | TCA implementation (reducers, effects) | Inherit |
| `@swift-engineer` | Vanilla Swift implementation (models, services) | Inherit |
| `@swiftui-specialist` | SwiftUI views (declarative only, no business logic) | Inherit |
| `@swift-test-creator` | Create tests using Swift Testing | Inherit |
| `@swift-documenter` | Generate API documentation and comments | Haiku |
| `@documentation-generator` | Generate comprehensive, LLM-optimized project documentation | Inherit |
| `@swift-code-reviewer` | Review code quality, security, performance | Inherit |
| `@swift-modernizer` | Migrate legacy patterns to modern Swift | Inherit |
### Utility Agents (Haiku)
| Agent | Purpose | Model |
|-------|---------|-------|
| `@search` | Fast code search to prevent grep noise from polluting context | Haiku |
## Skills
### Architecture & Patterns
| Skill | Purpose |
|-------|---------|
| `composable-architecture` | TCA patterns, reducers, effects, testing, performance |
| `swiftui-patterns` | iOS 17+ SwiftUI (@Observable, @Bindable, navigation, accessibility) |
| `swiftui-advanced` | Advanced gestures, adaptive layout, architecture decisions |
| `modern-swift` | Swift 6.2 concurrency (async/await, actors, @MainActor, Sendable) |
### Frameworks & Libraries
| Skill | Purpose |
|-------|---------|
| `sqlite-data` | SQLiteData library (@Table, migrations, CloudKit sync) |
| `grdb` | GRDB direct SQLite access (complex queries, performance) |
| `storekit` | StoreKit 2 in-app purchases and subscriptions |
| `foundation-models` | Apple on-device AI (iOS 26+, summarization, extraction) |
| `swift-networking` | Network.framework (TCP/UDP, custom protocols) |
### Platform & Design
| Skill | Purpose |
|-------|---------|
| `ios-hig` | Apple Human Interface Guidelines (accessibility, dark mode, haptics) |
| `ios-26-platform` | iOS 26 features (Liquid Glass, new APIs, backward compatibility) |
| `haptics` | Haptic feedback (UIFeedbackGenerator, Core Haptics, AHAP patterns) |
| `localization` | Internationalization (String Catalogs, pluralization, RTL) |
### Development Tools
| Skill | Purpose |
|-------|---------|
| `swift-testing` | Swift Testing framework (@Test, parameterized tests, async) |
| `swift-style` | Code style conventions (naming, golden path, organization) |
| `swift-diagnostics` | Systematic debugging (navigation, build issues, memory) |
| `generating-swift-package-docs` | Generate API docs for Swift package dependencies |
## Advanced Features
### Helper Scripts
**get-recent-simulator.sh**
Gets the most recent iOS simulator available for Xcode builds.
Usage:
```bash
bash scripts/get-recent-simulator.sh
```
Used by build automation to select the correct simulator for testing.
**bump-plugin-version.sh**
Automates version bumping across plugin metadata files.
Usage:
```bash
bash scripts/bump-plugin-version.sh <new-version>
```
This script updates version numbers in:
- `.claude-plugin/plugin.json`
- Any other version-managed files
### Development Rules
**five-whys.md**
Root cause analysis technique for debugging complex issues:
- Structured approach to dig deeper into problems
- Leads to systemic improvements rather than symptoms
- Useful for understanding agent failures and design decisions
**thinking-partner.md**
Collaborative problem-solving approach for design decisions and complex architecture questions.
## Installation
### Local Development
Drop this folder into your Claude Code plugins directory:
```bash
~/.claude/plugins/swift-engineering/
```
Then in Claude Code:
```
/plugin reload
```
### Configuration
Before using agents, ensure the **Sosumi MCP Server** is configured in your Claude Code settings for Apple documentation lookup.
Optional: Configure hooks for git automation. See [hooks-scripts/README.md](hooks-scripts/README.md) for details.
### First Run
1. Navigate to your Swift project directory
2. Invoke an agent: `@swift-architect Design a new feature`
3. Agent creates a plan file at `docs/plans/<feature-name>.md`
4. Each subsequent agent updates the plan and adds handoff notes
## Workflow
```
UI description/mockup? ──yes──► @swift-ui-design (Opus)
│ │
no │
│◄──────────────────────────────
▼
@swift-architect (Opus) → docs/plans/<feature>.md
│
├── TCA chosen ──► @tca-architect (Opus) ──► @tca-engineer (Inherit)
│ │
└── Vanilla chosen ───────────────► @swift-engineer (Inherit)
│
▼
@swiftui-specialist (Inherit)
│
▼
@swift-test-creator (Inherit)
│
▼
@swift-code-reviewer (Inherit)
│
▼
@swift-documenter (optional)
```
## Agent Handoff Model
Each agent knows exactly when to hand off:
| From | To | Condition |
|------|----|-----------|
| @swift-ui-design | @swift-architect | UI analysis complete |
| @swift-architect | @tca-architect | TCA architecture chosen |
| @swift-architect | @swift-engineer | Vanilla architecture chosen |
| @tca-architect | @tca-engineer | TCA design complete |
| @tca-engineer | @swiftui-specialist | Implementation complete |
| @swift-engineer | @swiftui-specialist | Implementation complete |
| @swiftui-specialist | @swift-test-creator | Views complete |
| @swift-test-creator | @swift-code-reviewer | Tests written |
| @swift-code-reviewer | @swift-documenter | Code review complete |
## Plan File Format
All agents share state via a plan file at `docs/plans/<feature-name>.md`:
```markdown
# Feature: <FeatureName>
## Status
- [ ] UI design (@swift-ui-design)
- [ ] Architecture (@swift-architect)
- [ ] TCA design (@tca-architect) — if TCA
- [ ] Implementation (@tca-engineer or @swift-engineer)
- [ ] Views (@swiftui-specialist)
- [ ] Tests (@swift-test-creator)
- [ ] Code review (@swift-code-reviewer)
- [ ] Documentation (@swift-documenter)
## MCP Servers
- **sosumi** — Apple documentation lookup (2025 APIs)
## Handoff Log
### @agent-name (YYYY-MM-DD)
**Work done:** [Summary]
**Files created:** [List]
**Notes for next agent:** [Context]
**Next:** @agent-name — [Reason]
```
## Architecture Conventions
- **iOS 26.0+** minimum deployment target
- **Swift 6.2** with strict concurrency checking
- **SwiftUI only** (no UIKit unless explicitly requested)
- **TCA** for complex state management, vanilla Swift for simpler features
- **SQLite** for persistence (never SwiftData)
- **Swift Testing** framework (no XCTest)
- **async/await** exclusively (no completion handlers)
## Model Usage
| Model | Agents | Rationale |
|-------|--------|-----------|
| Opus | @swift-architect, @swift-ui-design, @tca-architect | Best reasoning for architecture decisions |
| Inherit | Implementation agents (engineer, test, review, modernizer, docs) | Balanced quality and cost (uses parent session model) |
| Haiku | @search, @swift-documenter | Fast, efficient for mechanical tasks |
## Quality Assurance
### Validation Checklist
When modifying agents or skills:
- [ ] All agents have `name`, `description`, `tools`, `model` fields
- [ ] Planning agents (`@swift-architect`, `@swift-ui-design`, `@tca-architect`) are Opus
- [ ] Implementation agents use Inherit (allows cost-effective scaling with session model)
- [ ] Utility agents (`@search`, `@swift-documenter`) are Haiku
- [ ] Planning agents have explicit no-modify constraints
- [ ] All handoffs are documented in Agent Handoff Model
- [ ] All skill references exist in `skills/` directory
## Contributing
Contributions are welcome! Areas of focus:
- **New agents** — Specialized agents for underserved tasks
- **Skill enhancements** — Additional frameworks, patterns, or design guidance
- **Bug fixes** — Issues, regressions, or edge cases in existing agents
- **Documentation** — Clarity, examples, or new guides
- **Testing** — Verify agent workflows work end-to-end
Please ensure:
- Agents follow the established [specification](#agents)
- Skills adhere to [writing-skills best practices](https://github.com/anthropics/claude-code/blob/main/docs/skills.md)
- Changes are tested with actual Swift projects
- Documentation is updated
## License
This plugin is available under the MIT License. See [LICENSE](LICENSE) file for details.
## Feedback
Report issues or suggest features at the [GitHub repository](https://github.com/johnrogers/claude-swift-engineering/issues).
© John Rogers (@johnrogers) · MIT · johnrogers/claude-swift-engineering