journey-loop

• Builder — runs the journey-builder skill to build and test the next user journey (runs in background)
• Timing Watcher — monitors

  screenshot-timing.jsonl

  in real-time while builder runs; kills the test and reports violations when gaps > 5s are detected
• Refiner — runs the refine-journey skill to evaluate output and improve the skill

Inputs

spec.md

Shared State Files

journeys/*/

journeys/*/screenshot-timing.jsonl

journey-refinement-log.md

AGENTS.md

journey-loop-state.md

journey-state.md

Orchestrator State File

journey-loop-state.md

# Journey Loop State

**Spec:** <path>
**Started:** <timestamp>
**Current Iteration:** 1
**Status:** running

## Iteration History
| # | Journey Built | Duration | Score | AGENTS.md Changes | Decision |
|---|--------------|----------|-------|-----------------|----------|

Loop Protocol

Step 0: Load Pitfalls (MANDATORY — every iteration)

gh gist view 84a5c108d5742c850704a5088a3f4cbf --files

gh gist view 84a5c108d5742c850704a5088a3f4cbf -f <filename>

Step 1: Read Current AGENTS.md + Journey State

AGENTS.md

journey-state.md

spec.md

journey-loop-state.md

## Acceptance Criteria Master List

## Acceptance Criteria Master List
Total requirements: N
Total acceptance criteria: M

| ID | Requirement | Criterion # | Criterion Text |
|----|-------------|-------------|----------------|
| P0-0 | First Launch Setup | 1 | User sees consent dialog on first launch |
| P0-0 | First Launch Setup | 2 | User can accept consent |
...

1. Any journey with status

   in-progress

   or

   needs-extension

   → work on that one first
2. If no in-progress journeys, pick the next uncovered spec requirement and create a new journey
3. Journeys with

   polished

   status but unmeasured/estimated (

   ~

   ) durations need a measurement run, but do NOT block progress on new journeys. The orchestrator can batch-measure these separately.

in-progress

needs-extension

Step 2: Launch Builder + Timing Watcher

journeys/{NNN}-{name}/

rm -f journeys/{NNN}-{name}/screenshot-timing.jsonl

1. The full content of

   AGENTS.md

   as instructions (if it exists)
2. The full content of all pitfall files from the gist
3. The current

   journey-state.md

   content
4. Clear directive: work on the first in-progress/needs-extension journey, or create the next new journey for uncovered spec requirements

# Poll screenshot-timing.jsonl every 5 seconds
TIMING_FILE="journeys/{NNN}-{name}/screenshot-timing.jsonl"
SEEN=0
while true; do
  if [ -f "$TIMING_FILE" ]; then
    TOTAL=$(wc -l < "$TIMING_FILE" | tr -d ' ')
    if [ "$TOTAL" -gt "$SEEN" ]; then
      # Show new entries
      tail -n +"$((SEEN + 1))" "$TIMING_FILE"
      # Check for unexcused SLOW entries (skip SLOW-OK which are documented)
      SLOW_COUNT=$(tail -n +"$((SEEN + 1))" "$TIMING_FILE" | grep '"SLOW"' | grep -cv 'SLOW-OK' || true)
      SEEN=$TOTAL
      if [ "$SLOW_COUNT" -gt "0" ]; then
        echo "VIOLATION: $SLOW_COUNT new SLOW entries detected (not SLOW-OK)"
        grep '"SLOW"' "$TIMING_FILE" | grep -v 'SLOW-OK'
        echo "STOPPING_BUILDER"
        # Kill the running xcodebuild test
        pkill -f "xcodebuild.*test.*-only-testing" 2>/dev/null || true
        exit 1
      fi
    fi
  fi
  sleep 5
done

SLOW-OK

1. Read

   screenshot-timing.jsonl

   to find all SLOW entries
2. For each SLOW entry, read the test code to find what happens between the previous screenshot and the slow one
3. Research: Is it possible to make this step <= 5 seconds?
   • Read the app code that the test is exercising
   • Check if a

     waitForExistence(timeout:)

     is set too high
   • Check if the app itself is doing unnecessary work
   • Check if intermediate screenshots could break a long operation into visible chunks
4. If fixable (can be <= 5s): Fix the test code or app code. Go back to 2b (clear timing, re-launch builder).
5. If NOT fixable (genuine async like a real download): Add a comment in the test code on the line BEFORE the slow snap explaining exactly why:

   // SLOW-OK: 8s gap — simulated model download requires async completion, cannot be reduced

   . Then go back to 2b.
6. The watcher will now skip entries with matching names that have

   SLOW-OK

   comments in the test code.

• waitForExistence(timeout: 10)

  where the element appears in <1s — lower the timeout
• Missing accessibility identifier causing XCUITest to do a slow tree search — add the identifier
• App performing synchronous work on main thread — move to background
• Test waiting for an element that doesn't exist yet because app code hasn't been written — write the app code

• Real network/download simulation that must complete asynchronously
• App launch time (first screenshot always has overhead)
• System permission dialogs that appear unpredictably

Step 3: Launch Refiner Agent

autocraft:refine-journey

• Evaluate the builder's output
• Write a score to

  journey-refinement-log.md

• Edit

  AGENTS.md

  with project-specific improvements, or add platform-specific pitfalls to the gist

Step 4: See What the Builder Produced

1. Read 3-5 screenshots from the journey the builder just worked on. Do they show real features working? Or empty states, error messages, "No Results"? If the screenshots show a feature that's supposed to work but the screenshot shows it empty or broken — the journey is not done, regardless of what journey-state.md claims.
2. Check the journey folder for review files. Are there actual review notes? Or did the builder skip them?
   bash

   ls -la journeys/{NNN}-{name}/*.md

   If the builder claims "polished" but there are fewer than 3 review files — it's not polished.
3. Read the refinement log for the score and findings. Extract:

   • Score:

     — the percentage

   • Failures Found:

     — list of failures

   • Changes Made to AGENTS.md:

     — what was changed
4. Read

   journey-state.md

   — but treat it as the builder's CLAIM, not the truth. If your own observations (screenshots, review files) contradict the claimed status, update the status yourself.

needs-extension

Step 5: Decide Next Action

polished

1. Read the Acceptance Criteria Master List from

   journey-loop-state.md

   . M total rows.
2. For each criterion row: (a) confirm a journey maps it by number in its

   ## Spec Coverage

   , (b) confirm the journey's test file contains a step exercising it (search for keywords from the criterion text), (c) confirm a screenshot file exists in

   journeys/{NNN}-{name}/screenshots/

   for that step.
3. Build a final audit table:

   ## Pre-Stop Criterion Audit
   | Req ID | Crit # | Journey | Mapped? | Test Step? | Screenshot? | VERDICT |

4. Count uncovered = rows with any NO.
5. If uncovered > 0: do NOT stop. For each uncovered criterion — if it belongs to a journey currently marked

   polished

   , update that journey to

   needs-extension

   in

   journey-state.md

   ; if no journey owns it, create a new journey targeting those criteria. Continue the loop.
6. Only proceed to stop if uncovered == 0 AND score >= 95%.

polished

polished

polished

needs-extension

Step 6: Update Loop State

journey-loop-state.md

| <iteration> | <journey-name> | <duration> | <score>% | <N changes> | <continue/done> |

Stop Condition

• Overall score >= 95%
• Build passes
• All journey tests pass
• Every journey in

  journey-state.md

  has status

  polished

• Pre-stop criterion audit in Step 5a shows 0 uncovered criteria (every acceptance criterion in

  spec.md

  has: a journey mapping it by number, a test step exercising it, and a screenshot proving the outcome)
• Total criteria covered == M (from the Acceptance Criteria Master List)

Loop complete after <N> iterations.
Final score: XX%
Journeys built: <list with durations>
Spec coverage: X / N requirements fully covered (all criteria)
Criteria coverage: X / M acceptance criteria covered (impl + test + screenshot)
Uncovered criteria: (should be 0)
Total test suite duration: Xm
Run all tests with: <exact test command>

Safety Limits

• No iteration limit. The loop runs indefinitely until the user stops it or the stop condition is met.
• Stall detection: If the builder produces no changes for 2 consecutive iterations, log the stall and proceed to the refiner — it can diagnose why the builder stalled.
• Never modify the spec — the spec is read-only. Only

  AGENTS.md

  and the pitfalls gist get improved.
• Pitfall gist is append-only — add new pitfalls, never delete existing ones.