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
15 changes: 15 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,21 @@ commands, or moved skill-reference paths.

### Added

- **Checkable acceptance criteria, traced from the spec** (#69). `plan`
gives each task that users or callers can notice a `<criteria>` block:
*Given* a starting situation, *When* an action, *Then* something you can
see or test, plus the proof (a named test, a flow, a lint rule, or a
manual check). Criteria for Swift packages use public functions; for
screens, what's on screen. Vague spec items are asked about before the
build, and answers are kept in `<spec-clarifications>` (under
`autonomous`, the safest reading is recorded as an assumption to
confirm). `verify` now writes its own list from APP.md / RELEASE.md
**before** reading the plan, then traces every promised feature to a
criterion and its proof; a promise nobody checks is an issue even when
every task says completed. VERIFICATION.md gains a Spec Coverage table.
`build` writes the tests criteria name; `autonomous` verifies spec-first.
Older plans without criteria still verify, against their `<done>` lines.

- **Shared command scripts, tested** (#112). The shell programs that were
pasted into command text now live in `templates/_scripts/`, and the
commands call them in one line:
Expand Down
3 changes: 2 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -168,9 +168,10 @@ The body defines expertise, code patterns, best practices, and a verification ch
Templates in `templates/` use XML tags that commands parse. Key tags in PLAN.md tasks:
```xml
<task id="N" type="auto|manual|generator" status="pending|in_progress|completed">
<name>, <files>, <apple-patterns>, <action>, <verify>, <hig-compliance>, <done>
<name>, <files>, <apple-patterns>, <action>, <verify>, <hig-compliance>, <criteria>, <done>
</task>
```
`<criteria>` holds Given/When/Then acceptance criteria (`<criterion id="ACn" feature via="screen|package">` with `<given>`, `<when>`, `<then>`, `<proof type="test|flow|lint|manual">`), and a plan-level `<spec-clarifications>` records answers to spec questions `plan` asked first. `/apple:verify` writes its own list from APP.md/RELEASE.md before reading PLAN.md, then traces each feature → criterion → proof (#69).
Generator tasks add `<generator>` and `<customization>` tags. `type="auto"` tasks may carry an optional `model="opus"` attribute (set by `/apple:plan`, max 1–2 foundation tasks per phase) that `/apple:build` passes through as the spawn's per-call `model` override. Maintain tag consistency — commands match on these exact tag names.

### Adding a New Command
Expand Down
15 changes: 11 additions & 4 deletions commands/autonomous.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,8 @@ command — follow that command's logic exactly.

2. **Plan** — execute the `/apple:plan [N]` logic. Generate `.planning/PLAN.md`
for this phase, applying preferences and the conditional generator selection.
Unclear spec items are not asked mid-run: plan records its safest reading
as `source="assumed"` in `<spec-clarifications>`.

3. **Build** — execute the `/apple:build` logic. Work through every pending task
in order, spawning the matched agents (bare names; retry as `apple:<name>`
Expand Down Expand Up @@ -143,9 +145,13 @@ command — follow that command's logic exactly.

4. **Verify** — execute the `/apple:verify [N]` logic **through an
independent verifier**: spawn a fresh `swift-generalist` (bare name; retry
`apple:swift-generalist`) with the phase's PLAN.md deliverables and have
*it* run the build + test suite and the deliverables checklist, reporting
PASS/FAIL per item with the command output as evidence. The context that
`apple:swift-generalist`). Give it APP.md / RELEASE.md and the phase's
ROADMAP.md entry **first**, and have it write its own list of what the
spec promises before it reads PLAN.md (verify Steps 1–2: spec first,
then trace each promise to a criterion and its proof). Then it runs the
build + test suite and the deliverables checklist, reporting PASS/FAIL
per item with the command output as evidence. Spec gaps count like any
other finding. The context that
just built the phase grading its own output is the same trust gap
`/apple:build` Step 4 closes for tasks — reopened at phase scope. Write
the verifier's findings to `.planning/VERIFICATION.md`. If agents can't
Expand All @@ -160,7 +166,8 @@ command — follow that command's logic exactly.
the phase recap and again at the next checkpoint so a human runs them.

5. **Phase summary** — print a short recap (tasks completed, files changed,
quality-gate counts, verification result) and update `STATE.md` to mark the
quality-gate counts, verification result, and any `source="assumed"` spec
answers for a person to confirm) and update `STATE.md` to mark the
phase completed.

### 3. Between-Phase Checkpoint
Expand Down
5 changes: 4 additions & 1 deletion commands/build.md
Original file line number Diff line number Diff line change
Expand Up @@ -260,7 +260,10 @@ Task({
1. Follow the <apple-patterns> specified
2. Create/modify files listed in <files>
3. Verify all <verify> checks pass
4. Meet all <done> criteria
4. Meet all <done> criteria, and every <criteria> Given/When/Then:
write each test named in a <proof type="test"> in this task, with
that name, testing the behavior from outside (on screen for
via="screen", public functions for via="package")
5. Reuse <existing-helpers> — never reimplement a listed helper. If none
fits, say so in your report before adding a new shared one.
6. If <design-system> is present: tokens and .appText only, the listed
Expand Down
90 changes: 90 additions & 0 deletions commands/plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -267,6 +267,78 @@ no design file (screens designed in SwiftUI previews or `/apple:prototype`).

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

## Acceptance Criteria (every phase)

A `<done>` line like "Profile screen works" can't be proven true or false.
Every task that delivers something a user or caller can notice also gets
**acceptance criteria**: short statements anyone can check, in a fixed
shape:

- **Given** the starting situation
- **When** the user (or the calling code) does something
- **Then** something you can see or test happens

Example: *Given* no internet, *When* the user taps Save, *Then* the note
stays in the list and a "Saved offline" message shows.

**1. List what this phase promises.** Read the features this phase
delivers: the phase's entry in ROADMAP.md, matched to APP.md
`<mvp-features>` (new apps), or to the RELEASE.md `<features>` and `<bugs>`
by id (updates). Each one needs at least one criterion. A bug's criterion
comes from its `<symptom>`: *Given* the conditions that triggered it,
*When* the same action, *Then* the correct behavior.

**2. Ask before writing, not halfway through the build.** If a feature is
too vague to write a criterion (for example "sync works": what happens with
no internet? which copy wins when both changed?), collect those questions
and ask them together with `AskUserQuestion` (up to 4 per call), each with
plain choices and the recommended one first. Record every answer in
PLAN.md's `<spec-clarifications>` block so `/apple:verify` sees it.
Under `/apple:autonomous`, never ask: choose the safest reading (no data
lost, user told what happened), record it with `source="assumed"`, and the
run's next checkpoint lists the assumptions for a person to confirm.

**3. Write the criteria.** Rules:
- **Checkable from outside.** On screen for app screens; through the public
functions for a Swift package (`Packages/*` or a local package in the
project). Never "the cache is updated" or "the view model holds X".
Say which with `via="screen"` or `via="package"`.
- **One behavior each.** Cover the empty, error and edit cases the
`<flows>` already list, not only the happy path.
- **Name the proof**, the thing that will show it's true:
- `test`: the test that checks it (name it; the task writes it)
- `flow`: a `<flows>` id that `/apple:walkthrough` drives
- `lint`: a lint rule
- `manual`: a person checks it during `/apple:verify` (only when nothing
automatic can; most screen behavior can be a UI test or a flow)
- Tasks that deliver nothing a user or caller can notice (project setup,
the Visual QA task) keep only `<done>`.
- Ids run across the whole plan: `AC1`, `AC2`, ….

```xml
<spec-clarifications>
<!-- Answers to questions asked before planning. source="assumed" = chosen under autonomous, not yet confirmed -->
<clarification feature="[feature]" source="asked|assumed">[question] → [answer]</clarification>
</spec-clarifications>

<task id="N" ...>
...
<criteria>
<criterion id="AC1" feature="[feature name or RELEASE id, as in the spec]" via="screen|package">
<given>[starting situation]</given>
<when>[action]</when>
<then>[what you can see or test]</then>
<proof type="test|flow|lint|manual">[test name | flow id | rule | what the person checks]</proof>
</criterion>
</criteria>
<done>...</done>
</task>
```

Place `<spec-clarifications>` after `<flows>` (and `<design-pin>`), before
the tasks. Before writing PLAN.md, check: every feature from step 1 has at
least one criterion; if one doesn't, write it or ask.

## Task Generation

Create `.planning/PLAN.md` with detailed tasks:
Expand Down Expand Up @@ -484,6 +556,14 @@ tasks get zero tags — that is the common case.
<check type="build">App builds with navigation in place</check>
<check type="simulator">Navigation works correctly</check>
</verify>
<criteria>
<criterion id="AC1" feature="[MVP feature this screen serves]" via="screen">
<given>A first launch with no saved data</given>
<when>The app opens</when>
<then>The main screen shows its empty state with one clear first action</then>
<proof type="flow">F1</proof>
</criterion>
</criteria>
<done>
- Navigation structure matches app type
- Programmatic navigation works
Expand Down Expand Up @@ -533,6 +613,14 @@ Generate tasks based on:
<check type="build">Generated code compiles in the app target</check>
<check type="simulator">Settings screen renders and toggles respond</check>
</verify>
<criteria>
<criterion id="AC4" feature="Settings" via="screen">
<given>Appearance is set to Dark</given>
<when>The user quits and reopens the app</when>
<then>The app opens in Dark appearance</then>
<proof type="test">SettingsUITests.testAppearancePersists</proof>
</criterion>
</criteria>
<done>
- Settings accessible from navigation
- All preferences persist
Expand All @@ -555,6 +643,8 @@ Before printing the completion message, append one `"event":"outcome"` line to t
✅ Phase [X] plan created!

Created: .planning/PLAN.md with [N] tasks
Checkable criteria: [n] covering [n of m] features this phase promises
[Questions answered: n | Assumptions to confirm: n (listed in <spec-clarifications>)]

Tasks:
1. [Task 1 name] (type: [auto/manual/generator][; append ", model: opus" if tagged])
Expand Down
91 changes: 75 additions & 16 deletions commands/verify.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,44 +9,88 @@ model: sonnet

You are a quality assurance expert verifying that completed work meets the planned deliverables. Your goal is to ensure everything works before moving to the next phase.

## Step 1: Load Context
## Step 1: Write Your Own List From the Spec (before reading the plan)

Read the relevant planning files:
The plan was written by the same kind of model that did the work. If the
plan forgot something, checking only the plan forgets it too. So first,
**without opening PLAN.md**, read what was promised:

```
Read: .planning/PLAN.md # Current phase tasks and deliverables
Read: .planning/STATE.md # Current state and completed tasks
Read: .planning/APP.md # App specification for context
Read: .planning/APP.md # new apps: <mvp-features>
Read: .planning/RELEASE.md # updates: <features>, <bugs> (optional)
Read: .planning/ROADMAP.md # which of those this phase delivers
```

If a phase number is provided as argument, verify that specific phase.

## Step 2: Extract Deliverables
For each feature or bug this phase delivers, write down in your own words
what a person should be able to see or do when it works: the normal case,
plus the empty, error and edit cases where they apply. Use the same
Given / When / Then shape the plan uses. Keep this list; it goes into the
report unchanged as **Expected from the spec**.

From PLAN.md, extract all **testable deliverables**:
## Step 2: Read the Plan and Compare

1. **Files created** - Do they exist?
2. **Features implemented** - Do they work?
3. **Tests written** - Do they pass?
4. **UI components** - Are they accessible and correct?
```
Read: .planning/PLAN.md # tasks, <criteria>, <spec-clarifications>
Read: .planning/STATE.md # current state and completed tasks
```

Create a verification checklist:
**Trace every promise to its proof.** For each feature on your Step 1 list:

1. Find the plan's `<criterion>` entries for it (matched by `feature`).
Apply `<spec-clarifications>`: an answer there settles what the spec
meant. Note any `source="assumed"` items; a person still has to confirm
them.
2. Compare them with your list. Something you expected that no criterion
covers is a **gap in the plan**, even if every task says completed.
3. Check each criterion's `<proof>` exists: the named test is in the test
target, the flow id is in `<flows>`, the lint rule is in
`.swiftlint.yml`. A criterion whose proof doesn't exist is **unproven**.
4. Criteria with `via="package"` are checked through the package's public
functions (its tests); `via="screen"` through what's on screen (UI test,
walkthrough, screenshot, or a manual check).

How these count:

| Finding | Severity | Effect on the result |
|---------|----------|----------------------|
| A `must` feature (or `crash`/`high` bug) has no criterion | High | FAIL |
| A `should`/`could` feature or lower bug has no criterion | Medium | PARTIAL |
| Something you expected is missing from the criteria | Medium (High if it loses data) | PARTIAL |
| A criterion's proof doesn't exist | Medium | PARTIAL |
| A criterion's proof runs and fails | as the failure | FAIL |
| An assumed clarification is still unconfirmed | Low | ask in Step 4 |

**Older plans with no `<criteria>`:** don't fail them for the format. Trace
the spec list to the `<done>` lines instead, mark each feature "no
checkable criteria (older plan)", and turn your Step 1 statements into
the manual checks in Step 4.

Then build the checklist. Each criterion becomes a check of its proof type:
`test` runs in 3.2 (name the tests), `lint` in 3.5, `flow` through
`/apple:walkthrough` results or Step 4, `manual` in Step 4 (ask it as
written: "Given …, when you …, do you see …?"). Gaps go straight to
Issues Found.

```markdown
## Deliverables to Verify

### Spec coverage
- [ ] [Feature] → AC[n] → [proof]
- [ ] [Feature] → ⚠️ no criterion (gap)

### Automated Checks
- [ ] Project builds without errors
- [ ] All tests pass
- [ ] All tests pass (including every test named in a criterion)
- [ ] No compiler warnings
- [ ] Lint gate passes (if .swiftlint.yml exists)
- [ ] Coverage gate passes (if .coverage-baseline exists)
- [ ] [Feature X] file exists at [path]
- [ ] [Feature Y] file exists at [path]

### Manual Checks
- [ ] [Feature X] works as expected
- [ ] [UI Component] displays correctly
- [ ] AC[n]: Given [..], when [..], then [..]
- [ ] Confirm assumption: [clarification]
- [ ] [User flow] completes successfully
```

Expand Down Expand Up @@ -322,6 +366,7 @@ Create `.planning/VERIFICATION.md`:

## Summary

- **Spec coverage:** X of Y features proven ([n] gaps, [n] unproven)
- **Automated Checks:** X/Y passed
- **Manual Checks:** X/Y passed
- **Issues Found:** X
Expand Down Expand Up @@ -355,6 +400,19 @@ Create `.planning/VERIFICATION.md`:

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

## Spec Coverage

Every promise in the spec, what checks it, and whether it held. Written
from APP.md / RELEASE.md before reading the plan.

| Feature (spec) | Criterion | Proof | Result |
|----------------|-----------|-------|--------|
| [Offline notes] | AC3: Given no internet, when Save is tapped, then the note stays and "Saved offline" shows | test `NotesTests.testOfflineSave` | ✅ Passed |
| [Offline notes] | ⚠️ none: what happens when the same note changed on two devices? | — | ❌ Gap in the plan |
| [Export] | AC5: … | manual | ⚠️ Not run |

**Assumptions to confirm:** [list from `<spec-clarifications source="assumed">` | none]

## Manual Checks (UAT)

| Feature | Status | Notes |
Expand Down Expand Up @@ -421,6 +479,7 @@ Verification complete!
Status: [PASS / FAIL / PARTIAL] ([everything works | works, with gaps listed below | something important is broken])

Results:
- Promised features proven: X of Y [(n not covered by any check)]
- Automated: X/Y passed
- Manual: X/Y passed
- Issues: X found
Expand Down
22 changes: 22 additions & 0 deletions templates/PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,12 @@ Copy this file to your project's `.planning/PLAN.md`.
<design-pin source="[Figma|Sketch|Penpot|XD|other]" version="[name or export date]"
link="[optional]" scale="[1x|2x]" frames=".planning/design/phase-N/pinned/"/>

<!-- Answers to spec questions /apple:plan asked before writing tasks.
source="assumed": chosen under /apple:autonomous, a person still confirms it. -->
<spec-clarifications>
<clarification feature="[feature]" source="asked|assumed">[question] → [answer]</clarification>
</spec-clarifications>

<!-- 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 Expand Up @@ -83,6 +89,22 @@ Copy this file to your project's `.planning/PLAN.md`.
<check>System colors used for Dark Mode support</check>
</hig-compliance>

<criteria>
<!-- Acceptance criteria: Given / When / Then, checkable from outside —
on screen (via="screen") or through a Swift package's public
functions (via="package"). Every feature the phase promises has
at least one. <proof> names what shows it's true: a test, a
<flows> id, a lint rule, or a manual check. /apple:verify traces
each spec feature → criterion → proof. Omit for tasks with nothing
a user or caller can notice (setup, Visual QA). -->
<criterion id="AC1" feature="[feature name or RELEASE id]" via="screen|package">
<given>[starting situation]</given>
<when>[what the user or calling code does]</when>
<then>[what you can see or test]</then>
<proof type="test|flow|lint|manual">[test name | flow id | rule | what a person checks]</proof>
</criterion>
</criteria>

<done>
<!-- Specific completion criteria -->
- [Criterion 1]
Expand Down
Loading
Loading