Agent-Skills.md

Agent Skills: App Planner

>

UncategorizedID: pproenca/dot-skills/app-planner

Repository

pproenca/dot-skills
pproencaLicense: MIT
865

Install this agent skill to your local

pnpm dlx add-skill https://github.com/pproenca/dot-skills/tree/HEAD/skills/.experimental/app-planner

Skill Files

Browse the full folder contents for app-planner.

Download Skill

Loading file tree…

skills/.experimental/app-planner/SKILL.md

Skill Metadata

Name
app-planner
Description
>

App Planner

You produce a design-plan — a living document in the same format as exec-plans — that maps an app domain to feature groups organized by Apple Design DNA patterns. Each feature group becomes one milestone, buildable in a single ios-taste session.

The output is a markdown file saved to docs/design-plans/ (or wherever the project keeps its plans). It drives the entire build process across multiple sessions.

What You Produce

A design-plan document with these sections:

  1. Purpose / Big Picture (what the redesign achieves)
  2. User & Moments (personas + frequency-ranked interactions)
  3. Progress (living checkboxes, updated each session)
  4. Design Milestones (one per screen, pattern-mapped)
  5. Deliberate Omissions (what's NOT in scope)
  6. Decision Log (updated during execution)
  7. Surprises & Discoveries (updated during execution)

What You Do NOT Produce

  • SwiftUI code or data models
  • Layouts, wireframes, or mockups
  • Colors, typography, or spacing choices
  • Navigation architecture diagrams
  • The entire app in one go

Building happens later. One milestone at a time. Using ios-taste.

The Pattern-First Approach

Read references/apple-design-dna.md in the ios-taste skill directory (~/.claude/skills/ios-taste/references/apple-design-dna.md). It contains 22 patterns extracted from 6 Apple apps. These are your building blocks.

| Pattern | From | Best For | |---------|------|----------| | Time Grid | Calendar | Scheduling, appointments, day planning | | Poster Detail | Contacts | Person/entity profiles, identity views | | Glass-on-Gradient | Contacts | Premium detail views, record displays | | Dashboard Cards | Fitness | At-a-glance metrics, daily summaries | | Modular Card Grid | Weather | Multi-metric displays, status dashboards | | Hierarchical Zoom | Calendar | Browsing across time scales or detail levels | | Haptic State Transitions | Calendar | Mode changes, drag interactions, snap points | | Metric Detail Template | Health | Data drill-down with chart + education | | Semantic Domain Colors | Health | Multi-category systems needing visual coding | | Dense Grid | Photos | Image/thumbnail collections | | Annotation Layer | Photos Markup | Drawing/marking/annotating on images | | Signature Capture | Photos Markup | Consent, sign-off, handwritten input | | Card vs Row Grammar | Fitness/Contacts | Dashboard (cards) vs detail (rows) | | Inline Data Enhancement | Contacts/Fitness | Previews embedded in rows | | Empty State Skeletons | Fitness | Show structure before data exists |

Output Format

Save the design-plan as a markdown file. Structure it EXACTLY like this:

# [App Name] Design Plan — [Focus]

This DesignPlan is a living document. Progress, Decision Log, and
Surprises & Discoveries must stay up to date as work proceeds.

## Purpose / Big Picture

[1-3 sentences: what the user can do AFTER this plan is executed.
Outcome-focused, not feature-list.]

## User & Moments

- **[Persona 1]**: [who, when, device context]
- **[Persona 2]**: [who, when, device context]

| Frequency | Moment | What they do |
|-----------|--------|-------------|
| 50x/day | [moment name] | [one line] |
| 10x/day | [moment name] | [one line] |
| 5x/day | [moment name] | [one line] |
| 1x/day | [moment name] | [one line] |
| 1x/week | [moment name] | [one line] |

## Progress

- [ ] Milestone 1: [screen name]
- [ ] Milestone 2: [screen name]
- [ ] Milestone 3: [screen name]
...

## Design Milestones

### Milestone 1: [Screen Name]

**User goal**: "[What the user is trying to do — in their words]"
**Pattern**: [Apple Design DNA pattern name] (from [source app])
**Priority**: Must-have
**Frequency**: [how often this screen is used]
**Existing TCA domain**: [which reducer/feature this touches]

**Features**:
- [Feature] — [why the user needs it]
- [Feature] — [why the user needs it]
- [Feature] — [why the user needs it]

**Acceptance criteria**:
1. [Observable proof — what the screen shows/does]
2. [User test — "show to [persona], they say X"]
3. [Technical — builds, tests pass, no raw design tokens]

**ios-taste prompt** (use this to start the build session):
> "[Exact prompt to give ios-taste to build this screen, including
> user context, emotional intent, and which pattern to reference]"

---

### Milestone 2: [Screen Name]
...

## Deliberate Omissions

- [Feature] — [why it's excluded]
- [Feature] — [why it's excluded]

## Decision Log

_Updated during execution._

## Surprises & Discoveries

_Updated during execution._

Rules

  1. Group by user goal, not technical category. "See my day at a glance" not "Calendar Module."

  2. Every milestone = ONE screen = ONE pattern = ONE ios-taste session. If a milestone needs two patterns, split it into two milestones.

  3. Build order follows frequency. The 50x/day screen is Milestone 1.

  4. Max 8 milestones. More than 8 means over-scoping. Merge or defer.

  5. Every feature has a "why". Not "patient search" but "patient search — because she's on the phone and needs to find the caller's record one-handed."

  6. Include the ios-taste prompt. Each milestone has a pre-written prompt that starts the build session. The person building doesn't need to figure out what to ask — it's ready to paste.

  7. Reference existing code. If the project has existing reducers, models, or domains, name them in each milestone so the builder knows what they're working with.

  8. Acceptance criteria are testable. Not "looks good" but "the receptionist can identify the next patient in under 2 seconds."