Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,25 @@ commands, or moved skill-reference paths.

### Added

- **Design version pinning** (#97), tool-agnostic: every design tool exports
PNGs.
- **`plan`:** a new "Design Pin" step for UI phases copies the exported
frames to `.planning/design/phase-N/pinned/`, hashes them into
`pin.tsv`, and records a `<design-pin>` tag (source, version, link,
scale) in PLAN.md. It asks once, or uses frames already in the folder;
it never asks under `autonomous`, and skips silently with no design file.
`plan` gains `Bash` and `AskUserQuestion`.
- **`verify`:** a new step 3.7c compares a fresh export with the pin by
name and hash and reports added / removed / changed screens, with both
image paths and a one-line description, as **change requests, not
defects**. They never affect PASS / PARTIAL / FAIL. Check 8 compares
against the pinned frame.
- **Optional Figma add-on:** with `FIGMA_TOKEN` in the environment, `plan`
records the file's version id and `verify` skips the re-export when it
hasn't changed.
- New sections in the `PLAN.md` and `VERIFICATION.md` templates, plus a
help Planning Files row.

- **New command `/apple:debt [area | rule-set] [--report]`** (#102). It
measures an existing app against the rules SwiftShip already enforces on
new work, then pays the debt down safely:
Expand Down
1 change: 1 addition & 0 deletions commands/help.md
Original file line number Diff line number Diff line change
Expand Up @@ -319,6 +319,7 @@ All planning files are stored in `.planning/`:
| `PROTOTYPE.md` | UI direction exploration | `/apple:prototype` |
| `DESIGN-SYSTEM.md` | Tokens, text styles, components, lint status | `/apple:design-system` |
| `DEBT.md` | Debt by area, backlog, trend | `/apple:debt` |
| `.planning/design/phase-N/` | Pinned design frames + hashes per UI phase | `/apple:plan` (compared by `/apple:verify`) |
| `ROADMAP.md` | Development phases | `/apple:roadmap` |
| `RELEASE.md` | Release scope (features + bugs) | `/apple:release` |
| `STATE.md` | Current position | `/apple:roadmap` |
Expand Down
49 changes: 48 additions & 1 deletion commands/plan.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
description: Create detailed task plan for current or specified phase
argument-hint: [phase-number]
allowed-tools: Read, Write, Glob, Grep
allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
---

# Plan Phase
Expand Down Expand Up @@ -217,6 +217,53 @@ A task list verifies that *screens exist and compile*. It is blind to whether th

After building a flow's slice, run `/apple:walkthrough [flow-id]` — it drives the flow in the Simulator (UI test + per-step screenshots), statically audits the nav graph for dead-ends, and produces a human discoverability checklist. Do this **per flow-slice, not just at phase end**.

## Design Pin (UI phases)

A design that keeps changing after work starts is how projects overrun
without anyone noticing. Pin the design this phase is built against, so
`/apple:verify` can tell "same design" from "four screens changed", and
report changes as **change requests, not defects**
(`design/design-system`, rule 21). It works with any design tool, because
every tool exports PNGs.

**Skip silently** when the phase adds or changes no UI, or the project has
no design file (screens designed in SwiftUI previews or `/apple:prototype`).

1. **Find the frames.** If `.planning/design/phase-N/pinned/` already has
PNGs (the user dropped them there), use them. Otherwise ask once
(`AskUserQuestion`): "Is this phase built against exported design
frames?" with options **Folder of exported PNGs** (path via Other) /
**No design file for this phase**. Under `/apple:autonomous`, never ask:
pin an existing folder or skip.
2. **Copy and hash.** One PNG per screen, named after the frame (e.g.
`Profile Edit.png`), all exported at the **same scale**:
```bash
pin=.planning/design/phase-N
mkdir -p "$pin/pinned" && cp "<export folder>"/*.png "$pin/pinned/"
( cd "$pin/pinned" && shasum -a 256 -- *.png ) | sed -E 's/^([0-9a-f]+) [ *](.*)$/\2 \1/' | sort > "$pin/pin.tsv"
```
3. **Record it** in PLAN.md, right after `<flows>`:
```xml
<design-pin source="[Figma | Sketch | Penpot | XD | other]" version="[version name or export date]"
link="[file URL, optional]" scale="[1x | 2x]" frames=".planning/design/phase-N/pinned/"
figma-version-id="[only with FIGMA_TOKEN, see below]"/>
```
Name each UI task's frame in its `<action>` ("match `Profile Edit.png`"),
so build agents and verify check 8 compare against the right image.
4. **Optional, Figma only:** when `FIGMA_TOKEN` is set in the environment
(read-only scope; never ask for it in chat, never print it), record the
file's current version so verify can check for changes without a
re-export. The file key is the segment after `/file/` or `/design/` in
the URL:
```bash
curl -sf -H "X-Figma-Token: $FIGMA_TOKEN" "https://api.figma.com/v1/files/<key>/versions" \
| jq -r '.versions[0] | "\(.id)\t\(.label // "autosave")\t\(.created_at)"'
```
Put the id in `figma-version-id`. No token, or the call fails → leave it
out; the PNG pin is enough.

Commit `.planning/design/phase-N/` with PLAN.md (PNGs, `pin.tsv`).

## Task Generation

Create `.planning/PLAN.md` with detailed tasks:
Expand Down
53 changes: 52 additions & 1 deletion commands/verify.md
Original file line number Diff line number Diff line change
Expand Up @@ -161,7 +161,7 @@ one:
| 5 | View file under ~300 lines | `wc -l`. Over 300 → ❌ with the sections to split |
| 6 | Previews for each state | Stateful screen: `#Preview`s for default/loading/empty/error + large Dynamic Type (iOS) / narrow + wide window (macOS) / smallest + largest watch (watchOS). Trivial view: one preview is enough |
| 7 | Identifiers, and tests use them | Interactive elements carry `accessibilityIdentifier`; this phase's UI tests locate by identifier (`app.buttons["editor.save"]`), not visible text |
| 8 | Matches the design | Optional: with a design frame (exported PNG, or `.planning/design/phase-N/` once design pinning exists), compare a screenshot via `/apple:visual-qa`; otherwise ask in UAT |
| 8 | Matches the design | Optional: with a pinned frame (`.planning/design/phase-N/pinned/`, named in the task's `<action>`) or another exported PNG, compare a screenshot via `/apple:visual-qa`; otherwise ask in UAT. Compare against the **pinned** frame, not a newer export: newer changes are 3.7c's change requests |

**No design system yet** (no token file, no `ds_*` lint rules)? Checks 1–4
don't apply: record them as "—". Checks 5–8 still run, since they don't
Expand All @@ -173,6 +173,46 @@ not FAIL; a lint violation already fails the phase through 3.5. Under
`/apple:autonomous` a PARTIAL with DoD gaps stops the run, which is the
point: fix per phase, not at redesign time.

### 3.7c Design Changes Since Pin (UI phases with a pin)

Run this when PLAN.md has a `<design-pin>` (from `/apple:plan`). It answers
one question: did the design change after this phase was planned? Changes
are **change requests, not defects**: they never fail the phase and never
become fix tasks here (`design/design-system`, rule 21).

1. **Figma shortcut (optional).** If the pin has `figma-version-id` and
`FIGMA_TOKEN` is set, fetch the latest version (same `curl … /versions`
call as `/apple:plan`; never print the token). Same id → "Design
unchanged since pin (Figma version history)", done. Different → note the
named versions since the pin and continue to step 2 to find which screens.
2. **Get a fresh export.** Ask once: "Export the same frames again (same
scale) to a folder, to compare with the pin?" with options **Folder**
(path via Other) / **Skip: the design hasn't changed**. Under
`/apple:autonomous`, use `.planning/design/phase-N/current/` if it exists,
else skip and record "not checked".
3. **Compare** by file name and image hash:
```bash
pin=.planning/design/phase-N; new="<fresh export folder>"
t="${TMPDIR:-/tmp}/pin.$$"
( cd "$new" && shasum -a 256 -- *.png ) | sed -E 's/^([0-9a-f]+) [ *](.*)$/\2 \1/' | sort > "$t"
awk -F'\t' 'FNR==NR { old[$1]=$2; next }
{ seen[$1]=1; if (!($1 in old)) print "added\t" $1; else if (old[$1] != $2) print "changed\t" $1 }
END { for (n in old) if (!(n in seen)) print "removed\t" n }' "$pin/pin.tsv" "$t" | sort
rm -f "$t"
```
**Every** screen changed usually means a different export scale or
setting, not a redesign. Check that before reporting.
4. **Report** each added / removed / changed screen in VERIFICATION.md's
"Design Changes Since Pin" table with both image paths for a side-by-side
look. The hash says *that* a screen changed, not *what*; Read both PNGs and
describe the visible difference in one line (layout, colour, type, copy,
new element).

**Outcome:** no effect on PASS / PARTIAL / FAIL. Changed screens go to
the next phase or release as change requests (the user decides; suggest
`/apple:redesign` when many screens changed and it is installed). Don't
re-pin here; the next `/apple:plan` pins the new export for the next phase.

## Step 3.8: Optional handoff — run the app and screenshot

Before relying on the user's memory in the manual UAT below, try to **show the
Expand Down Expand Up @@ -302,6 +342,16 @@ Create `.planning/VERIFICATION.md`:
|---------------|------|--------|--------|------|------|----------|-----|--------|
| [ProfileView.swift] | ✅ | ✅ | ❌ ad-hoc ProgressView | ✅ | ✅ 212 | ⚠️ no error preview | ✅ | — |

## Design Changes Since Pin

[No pin | Unchanged (Figma version history) | Not checked | n added, n removed, n changed]

| Screen | Change | Pinned | New export | What changed |
|--------|--------|--------|------------|--------------|
| [Profile Edit.png] | changed | .planning/design/phase-N/pinned/… | [export]/… | [one line] |

Change requests, not defects: [next phase | next release | /apple:redesign]

## Manual Checks (UAT)

| Feature | Status | Notes |
Expand Down Expand Up @@ -367,6 +417,7 @@ Results:
- Automated: X/Y passed
- Manual: X/Y passed
- Issues: X found
- Design since pin: [unchanged | n changed (change requests) | — ]

Created: .planning/VERIFICATION.md

Expand Down
7 changes: 7 additions & 0 deletions templates/PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,13 @@ Copy this file to your project's `.planning/PLAN.md`.
</flow>
</flows>

<!-- Optional, UI phases with exported design frames (/apple:plan "Design
Pin"): the design version this phase is built against. Frames + pin.tsv
hashes live in .planning/design/phase-N/; /apple:verify reports later
design changes as change requests, not defects. -->
<design-pin source="[Figma|Sketch|Penpot|XD|other]" version="[name or export date]"
link="[optional]" scale="[1x|2x]" frames=".planning/design/phase-N/pinned/"/>

<!-- Optional on type="auto" tasks: model="opus" — set by /apple:plan on at
most 1–2 foundation tasks per phase (architecture, data model,
concurrency, migration). /apple:build passes it through as the agent
Expand Down
15 changes: 15 additions & 0 deletions templates/VERIFICATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,21 @@ system yet for Lint/Shared/States/Case; no design frame for Design).

---

### Design Changes Since Pin (UI phases with a pin)

`—` when PLAN.md has no `<design-pin>`. Change requests, not defects: they
never fail the phase.

**Result:** [Unchanged | Not checked | n added, n removed, n changed] · Pinned: [source] [version]

| Screen | Change | Pinned frame | New export | What changed |
|--------|--------|--------------|------------|--------------|
| [Screen.png] | added/removed/changed | `.planning/design/phase-N/pinned/[Screen.png]` | `[path]` | [layout / colour / type / copy] |

**Goes to:** [next phase | next release | /apple:redesign]

---

## Manual Checks (UAT)

### UI/UX Verification
Expand Down
Loading