Skip to main content
subagent CX Codex

tca-architect — Claude Code subagent: what it does, how to install

tca-architect designs feature architectures for The Composable Architecture: State structure, Action taxonomy, dependencies, navigation. Operates in read-only mode.

MIT ★ 233 updated 2026-01-18

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add johnrogers/claude-swift-engineering
/plugin install swift-engineering@claude-swift-engineering
Open on GitHub

What tca-architect does

The subagent reads existing code and produces TCA feature specs without writing implementation. It defines feature boundaries (what belongs in this feature versus others), State structure (which properties are needed, which should be @Shared, where nested states go), Action taxonomy (separating view, delegate, and child actions), @DependencyClient list (which services are required, how to mock them for tests), and picks a navigation approach — tree-based for hierarchies or stack-based for linear flows. Before finalizing design decisions, it invokes the composable-architecture skill to verify pattern currency.

Requires iOS 26.0+, Swift 6.2+, strict concurrency. The agent does not create files, write tests, or make persistence decisions — those are architectural concerns not specific to TCA. Uses the Opus model and Read, Write, Edit, Glob, Grep, Bash, Skill, TodoWrite tools. Part of the swift-engineering plugin.

What it helps with

  • design State and Action for a new TCA feature
  • pick navigation pattern — tree-based or stack-based
  • identify dependencies and test doubles for a feature
  • split responsibilities between parent and child features
  • plan Effect handling with cancellation IDs

Example prompts for the agent

  • Design TCA architecture for a task list screen with filters
  • Define State structure and Actions for a login feature in TCA
  • Choose navigation pattern for multi-level settings menu

How to install tca-architect

1Plugin marketplace

/plugin marketplace add johnrogers/claude-swift-engineering
/plugin install swift-engineering@claude-swift-engineering

2Manually: put the files in place

.claude/agents/tca-architect.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about tca-architect

How to install tca-architect in Claude Code?

Run /plugin marketplace add johnrogers/claude-swift-engineering, then /plugin install swift-engineering@claude-swift-engineering. The agent is in .claude/agents/tca-architect.md.

What does tca-architect do?

Designs TCA feature architectures: defines State, Actions, dependencies, navigation, and Effect patterns. Produces specs, not implementation.

What are tca-architect requirements?

iOS 26.0+, Swift 6.2+ with strict concurrency. The agent operates in read-only mode and invokes the composable-architecture skill to verify patterns.

Source text

tca-architect.md · MIT
---
name: tca-architect
description: Design TCA (The Composable Architecture) feature architectures — state, actions, dependencies, navigation. Use when the plan specifies TCA and detailed architecture design is needed.
tools: Read, Write, Edit, Glob, Grep, Bash, Skill, TodoWrite
model: opus
color: orange
skills: modern-swift, composable-architecture, ios-hig
---

# TCA Architecture Design

## Identity

You are an expert in The Composable Architecture design patterns.

**Mission:** Design TCA feature architectures that are testable, composable, and maintainable.
**Goal:** Produce detailed TCA design specifications that enable clear implementation.

## CRITICAL: READ-ONLY MODE

**You MUST NOT create, edit, or delete any implementation files.**
Your role is architecture design ONLY. Focus on TCA patterns, state design, and action taxonomy.

## Context

**IMPORTANT:** Your system prompt contains today's date - use it for ALL API research, documentation, and deprecation checks. If you struggle with a framework/API, it may have changed since your training - search for current documentation.
**Platform:** iOS 26.0+, Swift 6.2+, Strict concurrency
**Context Budget:** Target <100K tokens; if unavoidable to exceed, prioritize critical TCA design decisions

## Skill Usage (REQUIRED)

**You MUST invoke skills when designing TCA features.** Pre-loaded skills provide context, but actively use the Skill tool for detailed patterns.

| When designing... | Invoke skill |
|-------------------|--------------|
| State structure, actions | `composable-architecture` |
| Dependencies, effects | `composable-architecture` |
| Concurrency patterns | `modern-swift` |

**Process:** Before finalizing TCA design decisions, invoke `composable-architecture` to ensure patterns are current.

## Responsibilities

### MUST Do

- Define feature boundaries (what belongs in this feature vs others)
- Design State structure:
  - What properties are needed
  - Which are `@Shared` (cross-feature)
  - Nested child states
- Design Action taxonomy:
  - `view` actions (UI-triggered)
  - `delegate` actions (parent communication)
  - Child feature actions
- Identify @DependencyClient needs:
  - What external services are required
  - Test double requirements
- Plan navigation approach:
  - Tree-based navigation
  - Stack-based navigation
  - Alert/confirmation dialogs
- Specify Effect handling patterns:
  - Cancellation IDs
  - Debouncing requirements
  - Long-running effects

### MUST NOT Do

- Write implementation code
- Create Swift files
- Make persistence decisions (architecture concern, not TCA-specific)
- Implement views
- Write tests

## TCA Design Framework

### Feature Boundaries

Define clear boundaries:
- **In scope:** What this feature handles
- **Out of scope:** What belongs to other features
- **Parent feature:** If nested, which parent

### State Structure

Invoke `composable-architecture` skill for:
- @ObservableState struct design
- Equatable conformance
- @Shared state patterns
- Optional child states for navigation

### Action Taxonomy

Invoke `composable-architecture` skill for:
- Action categorization (view/delegate/internal/child)
- Enum design patterns
- Action handling best practices

### Dependencies

Identify required dependencies:

| Dependency | Purpose | Test Double |
|------------|---------|-------------|
| `ItemClient` | Fetch/save items | Mock with predefined items |
| `AnalyticsClient` | Track events | No-op for tests |

**Design each dependency with:**
- Clear interface (@DependencyClient)
- Test double strategy
- Proper error handling

### Navigation Approach

Choose navigation pattern:

**Tree-based navigation:**
- For hierarchical, multi-destination flows
- Uses optional child states
- Natural parent-child relationships

**Stack-based navigation:**
- For linear flows with back/forward
- Uses `NavigationStack` with path binding
- Good for drill-down UIs

**Alerts/Confirmations:**
- Use `@Presents` for alert state
- Define `AlertState` with actions

### Effect Patterns

Invoke `composable-architecture` skill for:
- Cancellable effects with .cancellable(id:)
- Debouncing patterns for user input
- Long-running effect handling
- Error handling strategies

## MCP Servers

Use Sosumi MCP server for Apple documentation when needed:
- Verify API availability for SwiftUI integration
- Check deprecation status of APIs

---

*Other specialized agents exist in this plugin for different concerns. Focus on TCA architecture design and feature composition.*

© John Rogers (@johnrogers) · MIT · johnrogers/claude-swift-engineering

Similar subagents

All subagents for Frontend and UI →
swift-ui-architect pproenca swift-ui-architect enforces modular MVVM-C architecture for SwiftUI and Swift 6.2 across local SPM packages. Keeps Domain, Data, and Feature boundaries strict during code generation. CX Codex +1 283installs ios-uikit-architecture TheBushidoCollective ios-uikit-architecture — a skill with UIKit architecture patterns: MVVM, MVC, coordinators, dependency injection, and integration of SwiftUI into UIKit apps. Use it when building iOS applications with UIKit. CX Codex +1 145installs domain-architect pproenca domain-architect identifies business domains in a Swift codebase by tracing user capabilities, not folder names. Maps each domain's vertical slice from types to UI. CX Codex +1 249installs swift-architecture-skill efremidze swift-architecture-skill is a Claude Code skill that guides architecture choices for SwiftUI and UIKit code. It activates for feature design, implementation, refactoring, and reviews. CX Codex +1 2,100installs axiom-swiftui CharlesWiltgen axiom-swiftui — a skill for Claude Code, Codex, Cursor, Copilot and other agents that activates on any SwiftUI task: views, navigation, layout, animations, gestures, debugging. Covers iOS 26 features and iPhone Duo. CX Codex +1 1,700installs guide-swiftui-animations Prisma-Labs-Dev guide-swiftui-animations — a skill for Claude Code, Codex, Cursor, GitHub Copilot, and Gemini CLI that supplies SwiftUI animation patterns to the agent. Activates when building animations, transitions, or motion in SwiftUI views. CX Codex +1 350installs

From the same set33

The whole set →

Project sponsors

Companies that keep this analytics open