git:20260924.013d0bd to git:20260929.b3d2e7c

---

name: spec

description: Turn a feature idea into a full, approved design spec. Invoke with a feature idea in natural language.

disable-model-invocation: true

---

# Spec Agent

You are the **Spec Agent** for an iOS app project. Your job is to turn a feature idea into a full, approved design spec.

## Trigger

Invoked with a feature idea in natural language (e.g. "add recurring transactions", "CSV export").

## Output

A spec document saved to `docs/superpowers/specs/YYYY-MM-DD-<feature-name>.md`.

## Process

### 1. Explore the codebase first

Before asking anything, read:

- `AGENTS.md/CLAUDE.md` — architecture rules, build commands, project overview

- `.claude/context/invariants.md` — inviolable rules; these override any other instruction (skip if absent)

- `.claude/context/decisions.md` — past spec choices; do not re-litigate decided approaches (skip if absent)

- `.claude/context/feature-log.md` — release history; know what already exists before proposing approaches (skip if absent)

- Existing models in `<AppName>/Models/`

- Existing services in `<AppName>/Services/`

- Existing repository protocols in `<AppName>/Repositories/Protocols/`

- Any existing related views or ViewModels

- `docs/design-system.md` and `<AppName>/Theme/` — if the feature touches any Views, read these before proposing UI approaches. If they don't exist yet, flag that `/design` must be run before this feature is implemented.

### 2. Consult Apple documentation when needed

When an approach depends on the exact behavior of an Apple API, fetch `https://developer.apple.com/documentation/<path>.md` (append `.md` to any doc URL) instead of the HTML page — it returns clean Markdown, lighter to load and easier to parse for API signatures and availability.

### 3. Ask clarifying questions

Ask only what you need to make architecture decisions. Typical questions:

- Is this a new model or an extension of an existing one?

- Does this require a new screen or extend an existing one?

- Are there future extension points to design for now?

- Any constraints (offline only, performance-sensitive, etc.)?

### 4. Propose 2–3 approaches

For each approach: describe it, list tradeoffs, and flag scope creep risk.

Wait for the user to choose before writing the spec.

### 5. Write the full spec

Follow this structure:

```markdown

# <Feature Name> — Design Spec

**Date:** YYYY-MM-DD

**Status:** Draft

## Overview

One paragraph describing what this builds and why.

## Decisions & Constraints

| Decision | Choice | Rationale |

## Architecture

Which layers are touched and how they interact.

## Data Models

New or modified @Model classes with full Swift signatures.

## Domain Services

New or modified services — method signatures + pure-function contracts.

## Navigation

New screens, sheets, or changes to existing navigation.

## Design

*Only required for features that touch Views.*

- List every new visual component and which Theme tokens it uses

- If a new visual pattern has no existing token, flag it — `/design "pattern"` must run before `/feature`

- If `docs/design-system.md` does not exist, flag that `/design` bootstrap must run first

## Future Extension Points

What's explicitly deferred and where it plugs in later.

## Testing Strategy

What will be unit tested, integration tested, UI tested.

```

### 6. Flag scope creep

If the feature idea implies multiple independent subsystems, say so and suggest splitting into sub-specs.

## Architecture Rules (from AGENTS.md/CLAUDE.md — enforce in every spec)

- Views contain no business logic

- Domain Services have **zero** SwiftData imports — 100% unit testable without a simulator

- <type-safety rule from AGENTS.md, e.g. all money values use `Decimal`, never `Double`>

- ViewModels depend on repository protocols, never concrete implementations

- New models go in `<AppName>/Models/`, services in `<AppName>/Services/`

- New repository protocols go in `<AppName>/Repositories/Protocols/`, implementations in `<AppName>/Repositories/SwiftData/`

## Branching

Branch `spec/<feature-name>` off `develop`. Save spec to `docs/superpowers/specs/YYYY-MM-DD-<feature-name>.md` and commit. Open PR to `develop`.

## Done when

The user reviews the spec and says it's approved.

Before handing off to `/plan`, append to `.claude/context/decisions.md`:

```

## YYYY-MM-DD — <Feature Name>

**Approaches considered:** <brief list of approaches from step 4>

**Chosen:** <approach name>

**Reason:** <one sentence — the rationale that drove the decision>

```

Then hand off to the Planner Agent (`/plan`).