Skip to main content
skill CX Codex

domain-architect — Claude Code skill: what it does, how to install

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.

MIT 249 installs ★ 227 updated 2026-08-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pproenca/dot-skills --skill domain-architect -a claude-code
Open on GitHub

What domain-architect does

The skill walks the project and finds what users can do: book, pay, browse. Each capability is a domain. For each domain, domain-architect assembles a vertical slice: data types, client interfaces (@DependencyClient), repositories, state reducers (@Reducer), dependency wiring, and SwiftUI views. It separates domains from providers (SDK wrappers like Stripe or Firebase) and cross-cutting layers such as logging, formatting, and constants.

The output is a domain map that decides folder structure, SPM target boundaries, and refactoring checkpoints. The skill reads @main, reducers, Package.swift, files with @DependencyClient and @Reducer. Without access to project code, it cannot build the map.

You get a list of domains with boundaries, a list of providers, and a list of ambiguous cases to discuss with the team. The skill triggers on requests about codebase structure, domain boundaries, or project reorganization.

What it helps with

  • figure out what business domains exist in a Swift project
  • separate domains from infrastructure layers
  • decide where new code belongs
  • plan a refactoring of module structure
  • check whether domains and providers are mixed

Example prompts for the agent

  • What domains are in this project?
  • Where should this code go — domain or infrastructure?
  • Map the domains in this Swift codebase

How to install domain-architect

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill domain-architect -a claude-code

2Manually: put the files in place

~/.claude/skills/domain-architect/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/domain-architect/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about domain-architect

How to install domain-architect in Claude Code?

Run npx skills add pproenca/dot-skills --skill domain-architect -a claude-code, then open ~/.claude/skills/domain-architect/SKILL.md.

What does domain-architect do?

It identifies business domains in a Swift codebase by tracing product capabilities, not folders. It maps each domain's vertical slice from types to UI and shows boundaries, providers, and ambiguous areas.

What does domain-architect need to work?

The skill requires access to project files: @main, reducers, Package.swift, files with @DependencyClient and @Reducer. Without reading the code, it cannot build the domain map.

Source text

SKILL.md · MIT
---
name: domain-architect
description: >
  Discovers business domains in a Swift codebase by tracing what users
  can DO — not by reading folder names or architecture docs. Maps each
  domain's vertical slice (Types → Config → Repo → Service → Runtime → UI),
  identifies providers (external SDK bridges), and separates cross-cutting
  concerns. Produces a domain map that drives all downstream decisions:
  folder structure, SPM targets, enforcement specs, migration plans.
  Use this skill whenever the user wants to understand their codebase
  domains, find what's cross-cutting vs domain-specific, restructure a
  Swift project, figure out where code belongs, or map a product's
  capabilities to architectural boundaries. Triggers on "what are my
  domains", "where does this belong", "map this codebase", "what's
  cross-cutting", "organize this project", "is this a domain or infra",
  "restructure this", "architecture review", or any request to understand
  the business domain structure of a Swift codebase.
allowed-tools: Read, Glob, Grep, Write, Edit, Bash
---

# Domain Architect

You discover business domains by tracing what users can DO — the
product's capabilities — and mapping each capability to a vertical
slice through the architecture.

You do NOT start from folder names, architecture docs, or file counts.
You start from the product.

## What You Produce

A **domain map** — the single artifact that drives everything else:

```
Domain Map
├── Business Domains (vertical slices the user would recognize)
│   └── Per domain: Types, Config clients, Service reducers, UI views
├── Providers (external SDK bridges)
├── Cross-Cutting Concerns (Infra, Utils)
└── Questions (ambiguous boundaries to discuss with the team)
```

Once the domain map is right, folder structure, SPM targets, enforcement
specs, and migration plans all follow mechanically. Get the domains wrong
and everything downstream is wrong.

## How Domains Work

Read `references/architecture.md` for the full layer spec.
Read `references/architecture.als` for the formally verifiable model.

### A domain is a user capability

**Litmus test**: Can you describe it to a non-engineer in one sentence?

- "Scheduling appointments" — domain (Calendar)
- "Collecting payments" — domain (Payments)
- "Browsing available treatments" — domain (Treatments)
- "Handling HTTP requests" — NOT a domain (infrastructure)
- "Formatting dates" — NOT a domain (utils)

### Each domain owns a vertical slice

```
Types    → pure data definitions for this domain's nouns
Config   → @DependencyClient interfaces (what you can ask for)
Repo     → implementations (how it's done — API, persistence, sync)
Service  → @Reducer state machines (business decisions)
Runtime  → dependency wiring (Config interfaces → Repo implementations)
UI       → SwiftUI views (pixels)
```

Not every domain needs every layer. A thin domain might only have
Config + Service + UI. But Types, Config, and Service are the minimum
for something to be a real domain.

### Domains don't import each other's internals

Cross-domain communication happens through:
- Delegate actions to a parent reducer
- Shared Types (the universal vocabulary)
- Shared Config interfaces (when two domains use the same client)

Never by importing another domain's Service or Repo.

### What's NOT a domain

| Thing | What it is | Where it lives |
|-------|-----------|---------------|
| Error handling | Cross-cutting | Infra |
| Logging/telemetry | Cross-cutting | Infra |
| Formatters, constants | Cross-cutting | Utils |
| Sentry, Stripe SDK, APNS | Provider (SDK bridge) | Providers |
| HTTP transport, persistence engine | Shared infrastructure | Repo |
| Design system tokens | Shared UI | DesignSystem |
| Background task scheduling | Platform integration | Runtime |

---

## The Process

### Step 1: What can users DO?

Start from the entry point. Read `@main`, the root reducer, the tab
structure. Every child scope or tab is a candidate domain.

```bash
grep -r "@main" <project-root> --include="*.swift" -l
```

Read the root reducer. Trace its `Scope` and `CombineReducers` to find
every child feature. Trace the tab enum to find every top-level
capability.

For multi-app products (e.g., patient app + clinic app), do this for
EACH app. The same business domain often appears in both apps with
different verbs.

### Step 2: What verbs exist?

Every `@DependencyClient` is a verb — a capability the system can perform.

```bash
grep -r "@DependencyClient" <project-root> --include="*.swift" -l
```

Read each client file. For each client, note:
- The **verbs** (closure names: `fetch`, `create`, `cancel`, `observe`)
- The **nouns** (types flowing through: `Appointment`, `Treatment`, `Patient`)
- Which **domain** it belongs to (infer from the nouns)

Group clients by domain. This gives you the Config layer map.

### Step 3: What nouns exist?

The nouns are in the Types layer — the universal vocabulary.

```bash
find <project-root> -name "Package.swift" -not -path "*/.build/*"
```

Read Package.swift files to find the Types target. Read its source files
to understand the domain language: what entities exist, what IDs are
typed, what operations are defined.

### Step 4: Map each domain's vertical slice

For each domain discovered in Steps 1-2, trace its full vertical:

| Layer | Question | How to find it |
|-------|----------|---------------|
| **Types** | What nouns does this domain speak? | Grep for domain nouns in Types package |
| **Config** | What can you ask for? | The `@DependencyClient` files from Step 2 |
| **Repo** | How is data fetched/stored? | Grep for `DataService`, `Repository`, `Store` + domain nouns |
| **Service** | What decisions are made? | Grep for `@Reducer` + domain name |
| **Runtime** | Where is it wired? | Grep for `Registration` + domain name |
| **UI** | What does the user see? | Grep for `View` + domain name |

**Read at least one file per layer per domain.** Don't guess from names.

### Step 5: Identify providers

Providers wrap external SDKs. They're NOT domains — they're bridges.

Look for:
- Third-party framework imports (Stripe, Firebase, Sentry, Amplitude)
- SDK initialization code
- Protocol conformances that bridge external types to domain types

```bash
grep -r "import Stripe\|import Firebase\|import Sentry\|import Amplitude" <project-root> --include="*.swift" -l
```

### Step 6: Identify cross-cutting concerns

What's left after domains and providers? Cross-cutting concerns:

- **Infra**: Error types, telemetry protocols, logging abstractions
- **Utils**: Pure formatters, constants, accessibility IDs
- **DesignSystem**: Tokens, styles, shared UI components

These are importable by any domain but contain no domain knowledge.

### Step 7: Flag ambiguities

Some things are genuinely ambiguous. Flag them as questions:

- "Is Profile a domain or part of Auth?" — Profile has its own client
  and UI, but avatar upload goes through Auth. Discuss with the team.
- "Is Booking part of Calendar or its own domain?" — It has distinct
  clients but lives inside the Calendar tab. Depends on complexity.
- "Are Notifications a domain or cross-cutting?" — It has its own UI
  and client, but very thin Types. Borderline.

Present these as questions, not decisions. The team has context you don't.

---

## Output Format

### Domain Map

For each domain:

```markdown
### [Domain Name] — "[one-sentence description]"

**Nouns**: [Types this domain speaks — Appointment, Treatment, etc.]
**Verbs**: [Client capabilities — fetch, create, cancel, observe]

| Layer | Files/Modules | Status |
|-------|--------------|--------|
| Types | [what exists] | present / missing / partial |
| Config | [clients] | present / missing |
| Repo | [implementations] | present / missing |
| Service | [reducers] | present / missing |
| Runtime | [wiring] | present / missing |
| UI | [views] | present / missing |

**Cross-app**: Patient app: [verbs]. Clinic app: [verbs].
```

### Providers

```markdown
| Provider | SDK | Used by domains |
|----------|-----|----------------|
| Sentry | Error monitoring | All (Infra) |
| Stripe Terminal | In-person payments | Payments |
```

### Cross-Cutting

```markdown
| Concern | Layer | Purpose |
|---------|-------|---------|
| AppDomainError | Infra | Error vocabulary |
| Telemetry | Infra | Monitoring |
| AccessibilityId | Utils | UI testing |
```

### Questions

```markdown
1. Is Profile a domain or part of Auth? [evidence for each]
2. Should Booking be extracted from Calendar? [evidence]
```

---

## Anti-Shortcut Rules

1. **Start from the product, not the files.** "What can users do?"
   comes before "what files exist?"

2. **Do not classify by folder path.** A file in `Services/` might
   be UI code. Read before classifying.

3. **Do not read architecture docs before forming your own opinion.**
   If harness-spec.yml or ARCHITECTURE.md exists, read it AFTER you've
   mapped the domains. Compare your map against theirs — disagreements
   are the most valuable findings.

4. **Do not skip domains because they look similar.** Each domain gets
   its own vertical trace. Auth is not Profile.

5. **Use subagents for codebases with >200 files.** One agent per
   domain, each traces the full vertical. This prevents shortcuts from
   context pressure.

6. **Flag ambiguities instead of deciding.** You lack the team's
   context. Present evidence for both sides. Let the team decide.

---

## Depth Requirements

1. **100% client discovery** — every `@DependencyClient` found and assigned to a domain
2. **100% reducer discovery** — every `@Reducer` found and assigned to a domain
3. **Vertical trace per domain** — at least one file read per layer per domain
4. **Evidence for boundaries** — cite the nouns/verbs that justify each domain boundary
5. **Explicit gaps** — report missing layers (domain has Service but no Config = finding)
6. **Questions over assumptions** — when unsure, ask rather than guess

© pproenca · MIT · pproenca/dot-skills

Similar skills

All skills for Code review and refactoring →

From the same set139

The whole set →
nginx-c-module-debug The nginx-c-module-debug skill guides diagnosis of nginx C module crashes, memory faults, and request-flow problems. Use it for GDB, core dumps, and tracing. CX Codex +1 260installs rust-write-tests rust-write-tests guides coding agents in writing deep Rust tests that target invariants, isolate test files, and systematically eradicate flaky async test runs. CX Codex +1 257installs rails-application-ui-blocks rails-application-ui-blocks is a Claude Code skill that assembles UI blocks in Ruby on Rails ERB views while preserving Turbo, Stimulus, and accessibility hooks. CX Codex +1 257installs rust-implement rust-implement enforces a four-pass discipline for Rust development, moving from strict type design to implementation, simplification, and automated linting. CX Codex +1 254installs app-planner app-planner creates a structured Markdown design plan using Apple Design DNA patterns before coding starts. Organizes screens into buildable milestones for ios-taste. CX Codex +1 244installs threat-model threat-model maps attack surfaces and trust boundaries across a codebase by tracing untrusted inputs directly to execution sinks. CX Codex +1 243installs opencode-ts The opencode-ts skill guides TypeScript implementation, tests, and refactoring in Effect-based projects. It gives the agent a workflow tied to the project’s architecture and conventions. CX Codex +1 240installs exec-plan exec-plan manages self-contained Markdown execution plans across agent sessions for tasks touching more than three files or taking over an hour. CX Codex +1 239installs

Project sponsors

Companies that keep this analytics open