From b8c98a9b42b2c3ff81918c8b67e94d0b12c583fe Mon Sep 17 00:00:00 2001 From: ginnoir Date: Fri, 12 Jun 2026 00:58:53 -0500 Subject: [PATCH] docs: document automation queue and recipe format --- docs/architecture.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/docs/architecture.md b/docs/architecture.md index 11f0083..6564181 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -82,6 +82,39 @@ progression is driven by Story-kind actions. The full design lives in `docs/superpowers/specs/2026-06-11-m1-pr3-shell-ui-design.md`. +### Automation + +Automation is universal across action kinds once an action has at least its +configured number of successful completions (`automation.unlockAfterManualCompletions`, +default `1`). The engine stores those counts in +`GameState.manualCompletionCounts` and stores configured automation in +`GameState.automationQueue`. + +`src/engine/automation.ts` owns unlock checks, queue mutation, and the runner. +The runner preserves precedence: manual active/queued actions first, +automation second, loop-idle actions last. `tickGame` can start automation when +the manual queue exhausts, including during offline catch-up; loop actions still +start only from the live runtime path. + +`src/engine/recipe.ts` serializes automation queues as shareable text using +content action ids. The v1 multiline format is: + +```text +idlegame-recipe/v1 +# name: Camp loop +gather_supplies +rest +``` + +The single-line alias is: + +```text +idlegame-recipe/v1:gather_supplies,rest +``` + +Import rejects unknown action ids and actions that are not automation-unlocked +for the current save. + ## Verification Run the full local gate before pushing: