A usable brief specifies state transitions, data lifetime and exclusions. Ten different app ideas can share that structure without receiving the same implementation.

User goal → Observable behavior → Data and failure states → Acceptance criteria
  1. 1User goal
  2. 2Observable behavior
  3. 3Data and failure states
  4. 4Acceptance criteria

Work through the example

For each brief, write one success check and one failure check. Keep optional polish out of the first implementation slice.

Start with a disposable branch and synthetic data. Write the expected outcome before changing the implementation, then keep the first failing result. This prevents a later repair from quietly redefining the task. The procedure below is grounded in the repository reference; its examples must still be checked against your project and installed toolchain.

Implementation reference

The following focused section is adapted from the maintained project guide. It preserves the source’s examples and limitations.

Input Contract

Accept short, messy descriptions. Do not require the user to fill a long form.

Example:

Create a fitness app for beginners. It should track workouts, show progress,
feel energetic, and use blue and green.

If details are missing, infer reasonable defaults and label them as assumptions. Ask a question only when the missing detail blocks implementation, such as whether the app needs authentication, payments, health data, or backend sync.

Acceptance and failure review

Checkpoint What to inspect If it does not match
User goal Confirm the input and environment Preserve the failure and return to this step
Observable behavior Inspect the intermediate artifact Preserve the failure and return to this step
Data and failure states Run the focused check Preserve the failure and return to this step
Acceptance criteria Record the observed result Preserve the failure and return to this step

Ask the agent to explain the smallest change that resolves the observed mismatch. Keep unrelated refactors out of the repair. A change that makes a warning disappear is not enough if the behavior or ownership contract has changed. Re-run the same acceptance check so the before and after results are comparable.

Ten briefs to practice with

These are authored exercises, not claimed outputs from ten model runs. Keep the first release local and small.

Idea Core behavior Acceptance check
Task list Add and complete a task Completion survives reopening
Reading list Save and search books Clearing search restores all books
Water log Record a drink Daily total changes once per entry
Pantry list Mark an item used Used item is excluded from available stock
Study cards Reveal an answer Navigation never changes the card data
Habit tracker Mark a day complete Repeated taps do not duplicate the day
Expense notes Save an amount and note Invalid numeric input cannot be saved
Travel checklist Group packing items Completion is independent in each trip
Workout journal Record a set A cancelled edit preserves the old value
Plant diary Record watering A new event appears with the chosen date

For each idea, add an empty state, an error recovery path and one explicit exclusion. For example, the reading list does not need accounts or a cloud backend in its first slice. That exclusion is a useful constraint, not missing ambition.

Evidence and limits

The example briefs are editorial exercises; they are not ten recorded model-generated plans.

This is an educational guide. Its presence in the series does not certify a completed client-specific lab. The series evidence record separates executed checks from exercises and blocked environments.

Inspect the source used in this lesson.

What to do next

Next: Generating an Xcode project the agent can edit: XcodeGen vs opening .xcodeproj by hand