diff --git a/CHANGELOG.md b/CHANGELOG.md index ea9095e..fa16169 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 `` 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: diff --git a/commands/help.md b/commands/help.md index 1150ae1..358958b 100644 --- a/commands/help.md +++ b/commands/help.md @@ -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` | diff --git a/commands/plan.md b/commands/plan.md index a71b907..61638b4 100644 --- a/commands/plan.md +++ b/commands/plan.md @@ -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 @@ -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 ""/*.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 ``: + ```xml + + ``` + Name each UI task's frame in its `` ("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//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: diff --git a/commands/verify.md b/commands/verify.md index 4d2be8a..14cccf5 100644 --- a/commands/verify.md +++ b/commands/verify.md @@ -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 ``) 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 @@ -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 `` (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="" + 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 @@ -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 | @@ -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 diff --git a/templates/PLAN.md b/templates/PLAN.md index 88e15d8..7ba8509 100644 --- a/templates/PLAN.md +++ b/templates/PLAN.md @@ -24,6 +24,13 @@ Copy this file to your project's `.planning/PLAN.md`. + + +