agentleFS
tddworkstddworks/asc-cli/.claude/skills/app-implement-feature/SKILL.md

app-implement-feature

Skill393 starsChanged 37 days agoApache-2.0View on GitHub

Guide for implementing features following architecture-first design, TDD, rich domain models, and Swift 6.2 patterns. Use this skill when: (1) Adding new functionality to a Swift app (2) Creating domain models that follow user's mental model (3) Building SwiftUI views that consume domain models directly (4) User asks "how do I implement X" or "add feature Y" (5) Implementing any feature that spans Domain, Infrastructure, and App layers

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. tddworks/baguette★ 2.3ksame name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository4 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 8 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before writing any code, create an architecture diagram and get user approval.

    line 41
  2. Distinctive:

    Use ASCII diagram showing all components and their interactions:

    line 53
  3. Distinctive:

    IMPORTANT: Always ask user to review the architecture before implementing.

    line 102
  4. Distinctive:

    Use AskUserQuestion tool with options:

    line 104
  5. Distinctive:

    Do NOT proceed to Phase 1 until user explicitly approves.

    line 108
  6. Distinctive:

    Chicago School TDD: - Test state, not interactions

    line 192
  7. Distinctive:

    Test state changes and return values, not interactions

    line 198
  8. Distinctive:

    Test state and computed properties:

    line 205

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Implement Feature

Implement features using architecture-first design, TDD, rich domain models, and Swift 6.2 patterns.

Workflow Overview

┌─────────────────────────────────────────────────────────────┐
│  1. ARCHITECTURE DESIGN (Required - User Approval Needed)   │
├─────────────────────────────────────────────────────────────┤
│  • Analyze requirements                                      │
│  • Create component diagram                                  │
│  • Show data flow and interactions                           │
│  • Present to user for review                                │
│  • Wait for approval before proceeding                       │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼ (User Approves)
┌─────────────────────────────────────────────────────────────┐
│  2. TDD IMPLEMENTATION                                       │
├─────────────────────────────────────────────────────────────┤
│  • Domain model tests → Domain models                        │
│  • Infrastructure tests → Implementations                    │
│  • Integration and views                                     │
└─────────────────────────────────────────────────────────────┘

Phase 0: Architecture Design (MANDATORY)

Before writing any code, create an architecture diagram and get user approval.

Step 1: Analyze Requirements

Identify:

  • What new models/types are needed
  • Which existing components will be modified
  • Data flow between components
  • External dependencies (APIs, databases, CLI tools)

Step 2: Create Architecture Diagram

Use ASCII diagram showing all components and their interactions:

┌─────────────────────────────────────────────────────────────────────┐
│                           ARCHITECTURE                               │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌─────────────┐     ┌──────────────────┐     ┌──────────────────┐  │
│  │  External   │     │  Infrastructure  │     │     Domain       │  │
│  └─────────────┘     └──────────────────┘     └──────────────────┘  │
│                                                                      │
│  ┌─────────────┐     ┌──────────────────┐     ┌──────────────────┐  │
│  │  API/DB     │────▶│  Repository/     │────▶│  DomainModel     │  │
│  │  (external) │     │  Client          │     │  (rich behavior) │  │
│  └─────────────┘     └──────────────────┘     └──────────────────┘  │
│                              │                         │             │
│                              │                         ▼             │
│                              │              ┌──────────────────┐     │
│                              │              │  DomainService   │     │
│                              └─────────────▶│  (actor)         │     │
│                                             └──────────────────┘     │
│                                                       │              │
│                                                       ▼              │
│                              ┌──────────────────────────────────┐   │
│                              │  App Layer                        │   │
│                              │  ┌────────────────────────────┐   │   │
│                              │  │ SwiftUI Views              │   │   │
│                              │  └────────────────────────────┘   │   │
│                              └──────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘

Step 3: Document Component Interactions

List each component with:

  • Purpose: What it does
  • Inputs: What it receives
  • Outputs: What it produces
  • Dependencies: What it needs
| Component       | Purpose              | Inputs         | Outputs        | Dependencies   |
|-----------------|----------------------|----------------|----------------|----------------|
| UserRepository  | Fetch user data      | userId         | User           | NetworkClient  |
| OrderService    | Manage order logic   | Order, User    | OrderResult    | UserRepository |

Step 4: Present for User Approval

IMPORTANT: Always ask user to review the architecture before implementing.

Use AskUserQuestion tool with options:

  • "Approve - proceed with implementation"
  • "Modify - I have feedback on the design"

Do NOT proceed to Phase 1 until user explicitly approves.


Core Principles

1. Rich Domain Models (User's Mental Model)

Domain models encapsulate behavior, not just data:

// Rich domain model with behavior
public struct Order: Sendable, Equatable {
    public let items: [OrderItem]
    public let status: OrderStatus

    // Domain behavior - computed from state
    public var totalAmount: Decimal {
        items.reduce(0) { $0 + $1.subtotal }
    }

    public var canBeCancelled: Bool {
        [.pending, .processing].contains(status)
    }

    public var itemCount: Int { items.count }
}

2. Swift 6.2 Patterns (No ViewModel Layer)

Views consume domain models directly:

// Views consume domain directly - NO ViewModel layer
struct OrderListView: View {
    let orders: [Order]

    var body: some View {
        ForEach(orders, id: \.id) { order in
            OrderRow(order: order)
        }
    }
}

struct OrderRow: View {
    let order: Order  // Domain model directly

    var body: some View {
        HStack {
            Text(order.status.displayName)
            Spacer()
            Text(order.totalAmount, format: .currency(code: "USD"))
        }
    }
}

3. Protocol-Based DI with @Mockable

@Mockable
public protocol OrderRepository: Sendable {
    func fetch(id: OrderId) async throws -> Order
    func save(_ order: Order) async throws
}

@Mockable
public protocol NetworkClient: Sendable {
    func request<T: Decodable>(_ endpoint: Endpoint) async throws -> T
}

Architecture

LayerLocationPurpose
DomainSources/Domain/Rich models, protocols, actors (single source of truth)
InfrastructureSources/Infrastructure/Repositories, clients, adapters
AppSources/App/SwiftUI views consuming domain directly (no ViewModel)

Key patterns:

  • Repository Pattern - Abstract data access behind protocols
  • Protocol-Based DI - @Mockable for testing
  • Chicago School TDD - Test state, not interactions
  • No ViewModel layer - Views consume domain directly

TDD Workflow (Chicago School)

We follow Chicago school TDD (state-based testing):

  • Test state changes and return values, not interactions
  • Focus on the "what" (observable outcomes), not the "how" (method calls)
  • Mocks stub dependencies to return data, not to verify calls
  • Design emerges from tests (emergent design)

Phase 1: Domain Model Tests

Test state and computed properties:

@Suite
struct OrderTests {
    @Test func `order computes total from items`() {
        // Given
        let order = Order(items: [
            OrderItem(price: 10, quantity: 2),
            OrderItem(price: 5, quantity: 1)
        ], status: .pending)

        // When/Then
        #expect(order.totalAmount == 25)
    }

    @Test func `pending order can be cancelled`() {
        // Given
        let order = Order(items: [], status: .pending)

        // When/Then
        #expect(order.canBeCancelled == true)
    }

    @Test func `shipped order cannot be cancelled`() {
        // Given
        let order = Order(items: [], status: .shipped)

        // When/Then
        #expect(order.canBeCancelled == false)
    }
}

Phase 2: Infrastructure Tests

Stub dependencies to return data, assert on resulting state:

@Suite
struct OrderServiceTests {
    @Test func `service returns order on success`() async throws {
        // Given - stub dependency to return data (not verify calls)
        let mockRepo = MockOrderRepository()
        let expectedOrder = Order(items: [], status: .pending)
        given(mockRepo).fetch(id: any()).willReturn(expectedOrder)

        let service = OrderService(repository: mockRepo)

        // When
        let result = try await service.getOrder(id: "123")

        // Then - verify returned state, not interactions
        #expect(result.status == .pending)
    }
}

Phase 3: Integration

Wire up in app entry point and create views.

References

  • Architecture diagram patterns - ASCII diagram examples
  • Swift 6.2 @Observable patterns
  • Rich domain model patterns
  • TDD test patterns

Checklist

Architecture Design (Phase 0)

  • Analyze requirements and identify components
  • Create ASCII architecture diagram with component interactions
  • Document component table (purpose, inputs, outputs, dependencies)
  • Get user approval before proceeding

Implementation (Phases 1-3) - Chicago School TDD

  • Write failing test asserting expected STATE (Red)
  • Write minimal code to pass the test (Green)
  • Refactor while keeping tests green
  • Define domain models in Sources/Domain/ with behavior
  • Test state changes and return values (not interactions)
  • Define protocols with @Mockable for external dependencies
  • Stub mocks to return data, assert on resulting state
  • Implement infrastructure in Sources/Infrastructure/
  • Create views consuming domain models directly
  • Run swift test to verify all tests pass

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.