← All craftbooks

One-Off Automation Script

Build: software and codeevalv1.0.0released 2026-06-05workflow: build-loop

Steps

Entry step: scope. Each step names the specialist role it wants; the full working prompt is expandable.

1. Scope the taskplannerentry

   lock inputs/outputs, side-effects, dry-run, safety

   Show working prompt

   Scope the automation before coding — a script with side-effects deserves a plan. Step 1: State exactly what the script does, its INPUTS (args, files, env) and its OUTPUTS/side-effects (files written, API calls, records changed). Step 2: Decide the safety affordances: a DRY-RUN/preview mode that shows what would happen without doing it, and how the real run is confirmed. Step 3: Decide idempotency — re-running must not double-apply (skip already-done work) — and failure handling (stop vs skip-and-log, exit code). Step 4: Decide the logging: what progress and summary it prints. Step 5: Write a numbered acceptance-criteria checklist of 5-9 items (e.g. 'a dry-run makes no changes and previews the plan', 'a real run performs the task', 're-running is a safe no-op on already-done items', 'errors are logged and exit non-zero'). `write_task_note` the scope + checklist and write the same to the produces path.

2. Build the scriptdeveloper

   implement the runnable script with dry-run

   Show working prompt

   Implement the script to the scope as a single runnable file. Step 1: Parse the arguments (including a `--dry-run` flag) and validate inputs up front, failing fast with a clear message on bad args. Step 2: Implement the core task; in dry-run mode, LOG what each action WOULD do and make zero side-effects, while the real run performs them. Step 3: Make side-effects idempotent — check before writing/calling so a re-run skips already-done items. Step 4: Log progress per item and a final summary (done/skipped/failed counts); on error, log it clearly and exit non-zero. Write the script to the produces path. On a loop-back, fix only the named gap. `write_task_note` the file path and which criteria now pass.

3. Verify the scriptreviewer

   confirm it works, is rerun-safe, fails loudly

   Show working prompt

   Verify the automation is correct and safe. Step 1: Run it with `--dry-run` and confirm it previews actions and makes NO changes. Step 2: Run it for real on sample input and confirm it performs the task and prints a sensible summary. Step 3: Run it AGAIN and confirm the second run is a safe no-op on already-done items (idempotent). Step 4: Feed bad input/args and confirm it fails loudly with a clear message and a non-zero exit. Write a verification note covering the dry-run, real run, re-run, and error handling to the produces path.

4. Evaluatereviewer

   Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.

   Show working prompt

   Run the script in dry-run, real, re-run, and error modes. For EACH acceptance criterion: confirm dry-run makes no changes and previews the plan, confirm a real run performs the task with a summary, confirm a re-run is a safe no-op on done items, and confirm bad input fails loudly with a non-zero exit. Write PASS/FAIL per criterion; a dry-run that mutates state or a non-idempotent re-run is a FAIL.
   
   Then route — this is the whole point of the loop:
   
   - **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`.
   - **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "build" })` to loop back. The builder fixes exactly those gaps.
   
   Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.

5. Finishdeveloper

   All acceptance criteria met. Stamp a short summary and report DONE.

   Show working prompt

   Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.

Triggers

Phrases that suggest this craftbook to a crew.

• write an automation script
• automate a task
• one-off script
• script to process files
• batch automation

Source

View this craftbook on GitHub · MIT license