swift-architecture

Files (11)

• SKILL.md
• _index.md · references/
• clean-architecture.md · references/
• coordinator.md · references/
• mvi.md · references/
• mvp.md · references/
• mvvm.md · references/
• reactive.md · references/
• selection-guide.md · references/
• tca.md · references/
• viper.md · references/

SKILL.md (first lines)

# Swift Architecture Skill

## Overview

Use this skill to pick the best Swift architecture playbook for SwiftUI/UIKit codebases and apply it to the user’s task.

For quick navigation across playbooks, use `references/_index.md`.

## Workflow

### Step 1: Analyze the Request Context

Before selecting an architecture, capture:
- task type (new feature, refactor, PR review, debugging)
- UI stack (SwiftUI, UIKit, or mixed)
- scope (single screen, multi-screen, app-wide)
- state and effect complexity
- team familiarity and dependency tolerance
- existing conventions to preserve

Then choose a delivery mode for the rest of the workflow:

- **Quick Recommendation Mode** — use when the scope is one feature or screen, constraints are clear enough to recommend one primary pattern, and the user mainly needs a recommendation, scaffold, or review checklist. Deliver: fit result (`fit` or `mismatch`), 1-2 reasons grounded in the request, the selected reference file, and concrete structure, state, dependency, async, and testing guidance scoped to the feature.
- **Deep Refactor Mode** — use when the request spans multiple modules or screens, the codebase already mixes architectures, or the user is migrating from one pattern to another. Deliver: current-state assessment, target architecture recommendation with fit or mismatch result, an incremental migration path with boundary changes called out, and risks, trade-offs, and verification points for the transition.

### Step 2: Select the Architecture

If the user explicitly names an architecture, treat it as the initial candidate and run a fit check before committing:
- validate against UI stack fit (SwiftUI/UIKit/mixed), state complexity, effect orchestration needs, team familiarity, and existing codebase conventions
- if it fits, proceed with the requested architecture
- if it mismatches key constraints, explicitly explain the mismatch and recommend the closest-fit alternative from `references/selection-guide.md`
- if the user still insists on a mismatched architecture, proceed with a risk-mitigated plan and state the risks up front

When no architecture is named, load `references/selection-guide.md` and infer the best fit from stated constraints (state complexity, team familiarity, testing goals, effect orchestration needs, and framework preferences). Explain the recommendation briefly.

Architecture reference mapping:
- MVVM → `references/mvvm.md`
- MVI → `references/mvi.md`
- TCA → `references/tca.md`
- Clean Architecture → `references/clean-architecture.md`
- VIPER → `references/viper.md`
- Reactive → `references/reactive.md`
- MVP → `references/mvp.md`
- Coordinator → `references/coordinator.md`

### Step 3: Analyze Existing Codebase (When Applicable)

When code already exists:
- detect current architecture and DI style
- note concurrency model (async/await, Combine, GCD, mixed)
- align recommendations to local conventions

### Guardrails

- Do not force an architecture switch for a small feature when the current local pattern is still a reasonable fit.
- Preserve existing conventions unless the mismatch is severe enough to justify change.
- Do not introduce new framework dependencies such as TCA unless the user explicitly accepts that trade-off or the codebase already uses them.
- Prefer the smallest architecture change that solves the request cleanly.
- Keep guidance architecture-specific; do not blend playbooks unless the boundary between patterns is explicit.

### Step 4: Produce Concrete Deliverables

Read the selected architecture reference and convert its guidance into deliverables tailored to the user's request:

- **File and module structure**: directory layout with file names specific to the feature
- **State and dependency boundaries**: concrete types, protocols, and injection points
- **Async strategy**: cancellation, actor isolation, and error paths
- **Testing strategy**: what to test, how to stub dependencies, and example test structure
- **Migration path** (for refactors): incremental steps to move from current to target architecture
- **UI stack adaptation**: where SwiftUI and UIKit guidance should differ for the chosen architecture

### Step 5: Validate with Checklist

End with the architecture-specific PR review checklist from the reference file, adapted to the user's feature.

## Output Requirements

- Keep recommendations scoped to the requested feature or review task.
- Prefer protocol-based dependency injection and explicit state modeling.
- Flag anti-patterns found in existing code and provide direct fixes.
- Include cancellation and error handling in all async flows.
- For explicit architecture requests, include a short fit result (`fit` or `mismatch`) with 1-2 reasons.
- For mismatch cases, include one closest-fit alternative and why it better matches the stated constraints.
- When writing code, include only the patterns relevant to the task — do not dump entire playbooks.
- Treat reference snippets as illustrative by default; add full compile scaffolding only if the user asks for runnable code.
- Ask only minimum blocking questions; otherwise proceed with explicit assumptions stated up front.
- When reviewing PRs, use the architecture-specific checklist and call out specific violations with line-level fixes.

From ducko-im/ducko, MIT.

More from ducko-im/ducko