From autocraft
Orchestrates a continuous journey-builder → refine → restart loop. Runs journey-builder and refine-journey sequentially, improving the skill each iteration. Loops until all spec requirements are covered by journeys and the score reaches 95%.
How this skill is triggered — by the user, by Claude, or both
Slash command
/autocraft:journey-loopThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are the orchestrator of a self-improving build loop. You manage three concurrent/sequential phases per iteration:
You are the orchestrator of a self-improving build loop. You manage three concurrent/sequential phases per iteration:
screenshot-timing.jsonl in real-time while builder runs; kills the test and reports violations when gaps > 3s are detectedYour job is to keep this loop running, monitor quality in real-time, and decide when to restart, fix, or stop.
Spec file: $ARGUMENTS
If no argument given, use spec.md in the current directory.
| File | Written by | Read by |
|---|---|---|
journeys/*/ | Builder | Refiner, Orchestrator, Watcher |
journeys/*/screenshot-timing.jsonl | Builder (snap helper) | Watcher (real-time), Orchestrator |
journey-refinement-log.md | Refiner | Orchestrator |
AGENTS.md (repo root) | Refiner | Builder (each restart) |
journey-loop-state.md | Orchestrator | Orchestrator (resume) |
journey-state.md | Builder | Builder, Orchestrator |
Create or resume 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 |
|---|--------------|----------|-------|-----------------|----------|
If this file already exists, read it and resume from the correct iteration.
Before ANYTHING else, fetch and read ALL pitfall files from the shared gist:
gh gist view 84a5c108d5742c850704a5088a3f4cbf --files
Then read each file:
gh gist view 84a5c108d5742c850704a5088a3f4cbf -f <filename>
Include the full pitfalls content in the builder agent's prompt so it has them available.
Before each iteration, read the root AGENTS.md fresh (create if missing). The refiner may have changed it.
Also read journey-state.md to determine what to work on:
Priority order for picking the next journey:
in-progress or needs-extension → work on that one firstpolished status but unmeasured/estimated (~) durations need a measurement run, but do NOT block progress on new journeys. The orchestrator can batch-measure these separately.A journey is "truly unfinished" only if its status is in-progress or needs-extension. Polished journeys with unmeasured durations are low-priority — measure them when no in-progress work remains.
2a. Determine the journey being worked on. From Step 1, you know which journey the builder will work on. Identify its folder path: journeys/{NNN}-{name}/.
2b. Clear the timing file before launching the builder:
rm -f journeys/{NNN}-{name}/screenshot-timing.jsonl
2c. Launch the Builder Agent in background. Spawn a new Agent (run_in_background=true) with:
AGENTS.md as instructions (if it exists)journey-state.md content2d. Launch the Timing Watcher immediately after the builder starts. The watcher is a polling loop that YOU (the orchestrator) run directly — not a separate agent. Use Bash to poll:
# Poll screenshot-timing.jsonl every 3 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 3
done
Run this Bash command in the background. When it exits with code 1, a timing violation was caught. SLOW-OK entries (documented unavoidable gaps) are ignored.
2e. Wait for the builder to complete. Two possible outcomes:
Outcome A — Builder completes normally (no violations): The watcher found no SLOW entries. Proceed to Step 3 (Refiner).
Outcome B — Builder completes but evidence review finds gaps: The orchestrator reads the screenshots and timing log. If the snap index sequence has large gaps (e.g., snap names jump from "090-..." to "103-..." skipping the entire recording phase), the journey has silently skipped phases. Re-launch the builder with a directive to investigate and fix the gaps. Include the specific missing phases in the prompt.
Outcome C — Watcher killed the test (violation detected):
screenshot-timing.jsonl to find all SLOW entrieswaitForExistence(timeout:) is set too high// SLOW-OK: 8s gap — simulated model download requires async completion, cannot be reduced. Then go back to 2b.SLOW-OK comments in the test code.Important: When investigating a SLOW entry, think carefully. Common fixable causes:
waitForExistence(timeout: 10) where the element appears in <1s — lower the timeoutCommon unfixable causes (document these):
After the builder completes, spawn a new Agent with the full content of the refine-journey SKILL.md as the task prompt, substituting the spec path.
Wait for the refiner to complete. It will:
journey-refinement-log.mdAGENTS.md with project-specific improvements, or add platform-specific pitfalls to the gistRead journey-refinement-log.md. Extract from the most recent entry:
Score: — the percentageFailures Found: — list of failuresChanges Made to AGENTS.md: — what was changedRead journey-state.md to check:
polished with all tests passing AND all mapped acceptance criteria covered?~)?If score >= 95% AND all journeys are polished AND all spec requirements covered: Stop.
If current journey is not yet polished: Continue working on the same journey next iteration.
If current journey is polished: Move to the next unfinished journey or next uncovered spec path.
If score did NOT improve for 2 consecutive iterations: Log a warning. If the same failure pattern appears 3 times, escalate.
Append to journey-loop-state.md:
| <iteration> | <journey-name> | <duration> | <score>% | <N changes> | <continue/done> |
Increment iteration counter. Go to Step 0.
Stop when all of:
journey-state.md has status polished (all acceptance criteria covered)When stopped, output:
Loop complete after <N> iterations.
Final score: XX%
Journeys built: <list with durations>
Spec coverage: X / N requirements covered
Total test suite duration: Xm
Run all tests with: <exact test command>
AGENTS.md and the pitfalls gist get improved.Provides a checklist for code reviews covering functionality, security, performance, maintainability, tests, and quality. Use for pull requests, audits, team standards, and developer training.
npx claudepluginhub sunfmin/autocraft