If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/pointfreeco/swift-composable-architecture shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2d ago
• 25+ active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 64% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live pointfreeco/swift-composable-architecture repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/pointfreeco/swift-composable-architecture.

What it runs against: a local clone of pointfreeco/swift-composable-architecture — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in pointfreeco/swift-composable-architecture | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of pointfreeco/swift-composable-architecture. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/pointfreeco/swift-composable-architecture.git
#   cd swift-composable-architecture
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of pointfreeco/swift-composable-architecture and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "pointfreeco/swift-composable-architecture(\\.git)?\\b" \\
  && ok "origin remote is pointfreeco/swift-composable-architecture" \\
  || miss "origin remote is not pointfreeco/swift-composable-architecture (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/pointfreeco/swift-composable-architecture"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

The Composable Architecture (TCA) is a Swift library for building iOS, macOS, iPadOS, visionOS, tvOS, and watchOS applications using a unidirectional state management pattern with reducers, effects, and composition primitives. It provides a cohesive framework for state mutations, side-effect handling, and feature composition that scales from simple SwiftUI views to complex multi-feature applications. Monorepo structure: Sources/ComposableArchitecture/ contains core logic for Store, Reducer, and Effect types; Examples/CaseStudies/ demonstrates patterns with both SwiftUI (.github/package.xcworkspace setup) and UIKit targets; Benchmarks/ contains performance regression tests; .github/workflows/ manages CI/CD. State flows unidirectionally through reducers via Actions, with Effects handling async side effects.

Swift developers building iOS/macOS applications (both SwiftUI and UIKit) who need predictable state management, comprehensive testability, and a structured way to compose large features from smaller, isolated modules without coupling across screens.

Production-ready and actively maintained. The repository shows 1.67M lines of Swift code, organized CI/CD pipelines (.github/workflows/ci.yml, .github/workflows/release.yml), comprehensive benchmarking infrastructure (Benchmarks/), and a mature example suite (Examples/CaseStudies/ with SwiftUI and UIKit implementations). Recent activity indicates ongoing development.

Low risk for core functionality, but moderate dependency on Point-Free's ecosystem (this is maintained by the Point-Free team). The library has a steep learning curve due to functional programming concepts, which may create knowledge silos in teams. Breaking changes can occur between major versions as the API evolves; check release notes carefully before upgrading.

The repository maintains active CI/CD workflows (format.yml, ci.yml, release.yml) and includes comprehensive benchmarking. The presence of multiple Swift scheme targets (ComposableArchitecture.xcscheme, swift-composable-architecture-benchmark.xcscheme) indicates ongoing optimization work. Case studies cover diverse topics (animations, alerts, bindings, etc.), suggesting the library continues evolving to cover real-world patterns.

Clone and open in Xcode: git clone https://github.com/pointfreeco/swift-composable-architecture.git && cd swift-composable-architecture && open ComposableArchitecture.xcworkspace. Alternatively, open Examples/CaseStudies/CaseStudies.xcodeproj to see working implementations. Use Swift Package Manager: add to your Xcode project via File > Add Packages > enter the GitHub URL.

Daily commands: Development: open ComposableArchitecture.xcworkspace in Xcode, select ComposableArchitecture scheme, build with Cmd+B. Run tests: Cmd+U on ComposableArchitecture target. Run examples: open Examples/CaseStudies/CaseStudies.xcodeproj, select target (SwiftUI or UIKit), Cmd+R. Benchmarks: open ComposableArchitecture.xcworkspace, select swift-composable-architecture-benchmark scheme, Cmd+R.

• Sources/ComposableArchitecture/Store.swift: Core runtime: manages state mutations, action dispatching, and observer notifications—every TCA app instantiates a Store
• Sources/ComposableArchitecture/Reducer.swift: Protocol defining state mutation logic; all business logic is expressed via Reducer conformance
• Sources/ComposableArchitecture/Effect.swift: Encapsulates async side effects (network, timers, sensors); critical for handling non-pure operations in a testable way
• Sources/ComposableArchitecture/Scope.swift: Enables feature composition by scoping parent state/actions to child domains—how large apps decompose into modules
• Tests/ComposableArchitectureTests/: Comprehensive test suite and examples of TestStore usage; learn testing patterns here before writing app tests
• Examples/CaseStudies/SwiftUICaseStudies/: Real-world patterns: animations, bindings, alerts, navigation—copy these patterns when building features
• .github/workflows/ci.yml: CI pipeline definition: shows how tests, formatting, and benchmarks are validated on every commit

Start in Sources/ComposableArchitecture/ (the core library). For new features: implement types conforming to Reducer protocol. For bug fixes: locate the relevant type (Store.swift, Effect.swift, Scope.swift) and add tests in Tests/ComposableArchitectureTests/. For documentation: Examples/CaseStudies/ demonstrates patterns—add a new SwiftUI view in Examples/CaseStudies/SwiftUICaseStudies/ or UIKit in Examples/CaseStudies/UIKitCaseStudies/. Run make format before committing (Makefile shows build tooling).

1. Reducer composition order matters: child domains must match parent's state/action structure exactly—type mismatches cause cryptic compile errors. 2) Effect cancellation requires explicit .cancel(id:) or the effect will run to completion; forgetting this causes memory leaks and stale data. 3) TestStore requires exact action ordering in tests; if you dispatch actions in an unexpected order, tests fail with unhelpful diffs—use SkipReplayingActions to debug. 4) SwiftUI View identity: when scoping a Store, ensure keyPath derivations don't create structural inequality; mismatched key paths cause view recreation. 5) No built-in dependency injection by default—use the Environment pattern in older versions or modern approach with @DependencyClient; injecting dependencies incorrectly breaks testability.

• Reducer Protocol & Pure State Mutations — All business logic in TCA is expressed via Reducer conformance; understanding how reducers transform (State, Action) → (State, Effect) is fundamental to writing any TCA feature
• Unidirectional Data Flow (Redux Pattern) — TCA enforces a strict action → reducer → state → view cycle; this pattern is core to TCA's predictability and testability, different from MVC or MVVM
• Effect<Action, Failure> & Async-Await Integration — Effects encapsulate side effects (network, timers, sensors) as first-class values; TCA's Effect type bridges async/await with reducer logic and is crucial for handling concurrency safely
• Feature Scoping & Reducer Composition — Scope type enables breaking large features into isolated sub-reducers that manage their own state/actions; critical pattern for building modular, testable apps without monolithic reducers
• TestStore & Deterministic Async Testing — TestStore verifies exact action sequences and state mutations; TCA provides deterministic clocks (ImmediateClock, UnimplementedClock) to make async tests reproducible without flakiness
• Environment & Dependency Injection — Early TCA versions used Environment struct for DI; modern TCA integrates with swift-dependencies library to inject services (API clients, loggers) in a testable way without hardcoding
• Action Equatability & Hashability for Testing — TestStore compares dispatched actions by value; all Actions must conform to Equatable (or CaseIterable); this enables TCA to catch unexpected mutations and verify exact behavior

• SwiftUIX/SwiftUIX — Extends SwiftUI with additional components and view modifiers commonly needed in TCA apps (custom environment, state bindings)
• pointfreeco/swift-dependencies — Companion library by the same team for dependency injection in TCA; essential for modern TCA projects to manage Environment and testable dependencies
• pointfreeco/swift-custom-dump — Testing utility by Point-Free used in TestStore for readable diffs of state/action mismatches in TCA tests
• ReSwift/ReSwift — Alternative Redux-like architecture for Swift; demonstrates similar unidirectional flow concepts if you want a lightweight comparison
• ReactiveX/RxSwift — Reactive programming framework; TCA's Effect type uses observable-like semantics (async + cancel), so RxSwift users transitioning to TCA find familiar patterns

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive benchmark suite documentation and CI integration for performance regressions

The repo has a Benchmarks directory with swift-composable-architecture-benchmark, but there's no evidence of automated benchmark running in CI (ci.yml). This is critical for an architecture library where performance characteristics matter. A new contributor could add: (1) GitHub Action workflow to run benchmarks on PRs and compare against main branch, (2) Documentation in Benchmarks/ explaining how to run and interpret benchmarks, (3) Performance regression detection thresholds.

• [ ] Review .github/workflows/ci.yml to identify where benchmark step should be added
• [ ] Create Benchmarks/README.md documenting benchmark purpose, how to run locally, and interpretation
• [ ] Add new GitHub Action workflow file .github/workflows/benchmark.yml to run benchmarks on PRs and compare baseline metrics
• [ ] Update Benchmarks/Benchmarks/swift-composable-architecture-benchmark/Benchmarks.swift with additional reducer performance tests if gaps exist

Complete example app documentation by adding architecture diagrams and decision guides for case studies

The Examples/CaseStudies directory contains 20+ example files covering various TCA patterns (navigation, effects, shared state, animations, etc.), but Examples/CaseStudies/README.md likely lacks detailed explanations of when/why to use each pattern. This creates friction for new users learning TCA. A contributor could systematically document each example category with decision trees.

• [ ] Expand Examples/CaseStudies/README.md with sections for each example category (Getting Started, Effects, Navigation, SharedState)
• [ ] For each major example file (e.g., 04-Navigation-Lists-NavigateAndLoad.swift), add inline documentation comments explaining the architectural pattern and trade-offs
• [ ] Create a decision matrix table in README showing which example to reference based on use case (e.g., 'Need form validation?' → see 01-GettingStarted-Bindings-Forms.swift)
• [ ] Add ASCII or Mermaid diagrams showing data flow for complex examples like 04-Navigation-Multiple-Destinations.swift

Add missing integration tests for Example apps to prevent regressions

The Examples directory contains full Xcode projects (CaseStudies.xcodeproj with SwiftUI and UIKit schemes) but there's no evidence of automated testing for these examples in CI. This means example code can rot without anyone noticing. A contributor should add snapshot or UI tests for the example apps.

• [ ] Check if Examples/CaseStudies has a test target; if not, create Examples/CaseStudies/CaseStudiesTests/
• [ ] Add snapshot tests for key example views using SnapshotTesting library (already a likely dependency) for SwiftUICaseStudies views
• [ ] Add a new CI workflow step in .github/workflows/ci.yml to build and test Examples/CaseStudies schemes (both SwiftUI and UIKit)
• [ ] Create Examples/CaseStudies/README.md Testing section documenting how to run example tests locally

• Write a case study example in Examples/CaseStudies/SwiftUICaseStudies/ for a common pattern not yet covered (e.g., form validation with async server-side checks, or paginated list loading)—template already exists, just add the Reducer logic and SwiftUI view
• Add comprehensive documentation comments to Effect.swift's public APIs; the file handles complex async logic but lacks inline examples of common patterns like retries, debouncing, and cancellation
• Create an integration test in Tests/ComposableArchitectureTests/ that combines Scope composition with Effect cancellation edge cases—the test suite exists but this pattern is under-tested

The Composable Architecture repository demonstrates good security practices overall. No critical vulnerabilities, hardcoded secrets, injection risks, or credential exposure were identified. The codebase appears to be a well-maintained Swift library without obvious SQL injection, XSS, or authentication vulnerabilities. Minor concerns relate to Xcode workspace and project file management practices rather than security risks. Docker/infrastructure configuration files were not present in the provided file structure. The project includes standard security governance (CODE_OF_CONDUCT.md, issue templates) and CI/CD workflows (GitHub Actions) for quality control. Dependency management appears standard through Swift Package Manager.

• Low · Workspace Configuration Files Checked Into Repository — ComposableArchitecture.xcworkspace/, Examples/CaseStudies/CaseStudies.xcodeproj/project.xcworkspace/, .github/package.xcworkspace/. Multiple Xcode workspace configuration files (.xcworkspace directories, Package.resolved) are committed to version control. While not inherently a security risk, these can contain environment-specific settings and resolved dependency versions that may diverge from development environments. Fix: Consider adding *.xcworkspace and Package.resolved to .gitignore to prevent environment-specific configuration drift, or document the inclusion rationale.
• Low · Generated Project Files in Repository — Examples/CaseStudies/CaseStudies.xcodeproj/project.pbxproj, xcshareddata/xcschemes/. Xcode project files (.pbxproj, xcscheme) are committed to version control. These generated files can cause merge conflicts and may inadvertently expose configuration details. Fix: Review whether generated Xcode files should be in version control. Consider using .gitignore for auto-generated build artifacts.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.