@andorra-labs/code 0.0.0-stage → 0.1.4

package/dist/src/skills/bundled/dynamic-workflows/patterns.md

@@ -0,0 +1,460 @@
+# Dynamic workflow patterns
+
+A catalogue of orchestration shapes. Each entry states when the shape is right, then shows
+it written correctly. Interfaces are elided where they are obvious — your script must
+define every type it names.
+
+The snippets here are **fragments, not runnable scripts**: they name types and subagents that
+the surrounding prose leaves to you. Complete scripts live in `examples.md`.
+
+For the API surface itself, read the `CreateWorkflow` tool description. For the reasoning
+behind these choices, read `SKILL.md`.
+
+---
+
+## 1. Fan-out / fan-in over a glob
+
+**When:** the same independent question about every file in a set, and you want them
+answered at once.
+
+```ts
+phase("Find the files to audit");
+const paths = await files.glob("src/**/*.ts");
+log(`fanning out over ${paths.length} files`);
+
+phase("Security-audit each file independently");
+const verdicts = await Promise.all(
+  paths.map((p) =>
+    agent(`auditor-${p}`).ask<Verdict>(`Security-review ${p}. Report only real issues.`),
+  ),
+);
+
+phase("Report the files that failed");
+return verdicts.filter((v) => !v.approved).map((v) => ({ path: v.path, reason: v.reason }));
+```
+
+A fresh subagent per path is the point: the questions are unrelated, so there is nothing to
+share and everything to parallelize. Do not hoist `agent(...)` above the `map`.
+
+The name carries the path because subagent names must be unique within a run: `agent("auditor")`
+inside the `map` would create one subagent per file all claiming the same name, which is rejected
+at compile time. `` `auditor-${p}` `` is also what lets a revised re-run (`AmendWorkflow`) keep
+the verdicts for files whose question did not change. Anonymous — `agent()` — is legal too,
+and starts every file with an empty context.
+
+**Narrow before you fan out.** A glob over a large repository is a large fan-out. If only
+some files can possibly matter, find them first:
+
+```ts
+const hits = await files.grep("dangerouslySetInnerHTML", "src/**/*.tsx");
+const paths = [...new Set(hits.map((h) => h.path))];
+```
+
+`files.grep` rejects rather than truncating when it overruns its cap, so a pattern that is
+too broad fails loudly instead of handing you a partial file list to fan out over.
+
+---
+
+## 2. Changed-file review sweep
+
+**When:** reviewing work in progress rather than the whole tree.
+
+```ts
+phase("Find the work in progress");
+let paths: string[];
+try {
+  paths = await git.changedFiles("origin/main");
+} catch {
+  paths = await files.glob("src/**/*.ts");
+}
+
+phase("Review each changed file for bugs");
+const reviews = await Promise.all(
+  paths.map((p) => agent(`reviewer-${p}`).ask<Review>(`Review ${p} for correctness bugs.`)),
+);
+```
+
+Every `git` call rejects outside a repository or with no `git` available, so the `try`/`catch`
+with a `files.glob` fallback is the idiom, not defensive padding.
+
+When the reviewer needs the change rather than the file, hand it the diff — but per path, so
+no single prompt carries the whole changeset:
+
+```ts
+const perFile = await Promise.all(
+  paths.map(async (p) => {
+    const patch = await git.diff("origin/main", p);
+    return agent(`reviewer-${p}`).ask<Review>(`Review this change to ${p}:\n\n${patch}`);
+  }),
+);
+```
+
+`git.diff` is capped and rejects rather than truncating, so narrow it to a path when the
+whole-workspace diff would be large.
+
+Then confirm before you report — per file, as each review lands, not after all of them. The
+reviewer that raised a finding does not get to confirm it — a subagent asked to check its own
+work grades generously — so each finding goes to a fresh confirmer that reproduces it from the
+evidence alone and is told not to fix anything. Chaining the confirmers inside the same
+callback means the slowest reviewer holds up only its own file:
+
+```ts
+phase("Review each changed file and confirm its findings as they land");
+const confirmed = (
+  await Promise.all(
+    paths.map(async (p) => {
+      const review = await agent(`reviewer-${p}`).ask<Review>(`Review ${p} for correctness bugs.`);
+      return Promise.all(
+        review.findings.map(async (finding, index) => {
+          const check = await agent(`confirmer-${p}-${index}`).ask<Confirmation>(
+            `Reproduce this finding from its evidence alone. Do not edit any file.\n${JSON.stringify(finding)}`,
+          );
+          const reported = { ...finding, status: check.reproduced ? "verified" : "unconfirmed" };
+          report(reported);
+          return reported;
+        }),
+      );
+    }),
+  )
+).flat();
+```
+
+What fails confirmation is kept and labelled, not dropped. The review fan-out above and this
+one are the same shape written twice for exposition; in a real script write only this one.
+
+---
+
+## 3. Planner ↔ reviewer loop
+
+**When:** the first attempt at something is rarely right, and a critic can say why.
+
+```ts
+const planner = agent("planner", "You write concrete, minimal implementation plans.");
+const reviewer = agent("reviewer", "You find the flaw in a plan. Approve only when you cannot. You never edit files.");
+
+let feedback = "none";
+for (let round = 0; round < 5; round++) {
+  phase("Draft a plan for the change");
+  const plan = await planner.ask<Plan>(`Plan the change. Previous critique: ${feedback}`);
+  phase("Critique the plan until it holds");
+  const review = await reviewer.ask<Review>(`Critique this plan:\n${JSON.stringify(plan)}`);
+  if (review.approved) return plan;
+  log(`round ${round + 1} rejected: ${review.feedback}`);
+  feedback = review.feedback;
+}
+```
+
+Both subagents are created **once, outside the loop**. That is what makes the loop cheap: each
+keeps its accumulated context across rounds, so the planner remembers what it already tried
+and the reviewer remembers what it already objected to. Creating them inside the loop throws
+that away every round and pays full price for it.
+
+The reviewer's persona says it never edits files: that is what keeps it critiquing the plan
+instead of quietly "fixing" it. When critiquing the plan is reading a string, it simply never
+opens a file; when the plan is about code, tell it to read the code — a reviewer that has not
+opened the files can only judge whether the plan is coherent, not whether it is right.
+
+By the last round the persistent reviewer is anchored on its own earlier objections. Put the
+final plan in front of eyes that have seen nothing else, and ask for failures rather than
+approval:
+
+```ts
+phase("Independent review of the final plan");
+const second = await agent("independent-reviewer", "You review plans and never edit files.").ask<Review>(
+  `You have not seen this plan before. Read it against the codebase. What would break it, and what is missing?
+${JSON.stringify(plan)}`,
+);
+if (!second.approved) feedback = second.feedback;
+```
+
+---
+
+## 4. Judge panel: independent, or calibrated
+
+**When:** a finding needs a second opinion. Two shapes, and the difference matters.
+
+**Independent** — N fresh contexts, each blind to the others. Use for a majority vote,
+where correlated judges would defeat the purpose:
+
+```ts
+phase("Judge the finding from three angles");
+const votes = await Promise.all(
+  ["correctness", "security", "does-it-reproduce"].map((lens) =>
+    agent(`judge-${lens}`)
+      .ask<Verdict>(`Judge this finding through the ${lens} lens. Try to refute it:\n${claim}`),
+  ),
+);
+const survives = votes.filter((v) => !v.refuted).length >= 2;
+```
+
+Giving each judge a distinct lens beats three identical refuters: diversity catches failure
+modes that redundancy cannot.
+
+**Calibrated** — one context that sees every item, so its verdicts are consistent with each
+other. Use for ranking and severity, where "high" has to mean the same thing twice:
+
+```ts
+phase("Rank every finding on one scale");
+const triage = agent("triage", "You rank findings on one consistent scale across a whole batch.");
+
+const ranked: Ranked[] = [];
+for (const finding of findings) {
+  ranked.push(await triage.ask<Ranked>(`Rank: ${JSON.stringify(finding)}`));
+}
+```
+
+The `for`/`await` is deliberate here — asks on one subagent queue FIFO anyway, so writing it as
+a `Promise.all` would only hide the serialization, not remove it.
+
+A queue is not a barrier, though. The calibrated subagent does not need the whole batch in
+hand before it starts: feed it each item as the stage before produces it (from inside that
+stage's fan-out callback, SKILL.md §11) and its verdicts stay consistent while the pipeline
+keeps moving.
+
+Either way, a judge's verdict is a judgement, not a reproduction: a finding that survived the
+panel still enters the report as `unconfirmed` unless a confirmer or a `world.run` check
+reproduced it.
+
+---
+
+## 5. Loop until approved, with a real escape
+
+**When:** a bounded loop that must still return something useful when it runs out of rounds.
+
+```ts
+let best: Attempt | undefined;
+for (let round = 0; round < 6; round++) {
+  phase("Attempt the fix");
+  const attempt = await worker.ask<Attempt>(`Attempt the fix. Prior failure: ${lastError ?? "none"}`);
+  phase("Check whether it actually passes");
+  const check = await checker.ask<Check>(`Does this pass? ${JSON.stringify(attempt)}`);
+  if (check.passed) return { attempt, rounds: round + 1, converged: true };
+  best = attempt;
+  lastError = check.reason;
+}
+return { attempt: best, rounds: 6, converged: false };
+```
+
+Return the shape that says **whether it converged**, not just the result. A caller that
+cannot tell "approved on round two" from "gave up after six" will treat the second as the
+first. Never let the loop fall off the end returning nothing.
+
+---
+
+## 6. Staged pipeline with typed handoff
+
+**When:** each stage narrows or transforms what the next one works on.
+
+```ts
+phase("Survey which modules touch auth");
+const survey = await agent("surveyor").ask<Survey>("List the modules that touch auth.");
+log(`${survey.modules.length} modules in scope`);
+
+phase("Analyse each module for auth bypasses");
+const analyses = await Promise.all(
+  survey.modules.map((m) =>
+    agent(`analyst-${m.path}`).ask<Analysis>(
+      `Analyse ${m.path} for auth bypasses. Purpose: ${m.purpose}`,
+    ),
+  ),
+);
+
+phase("Write the findings up for the engineer who fixes them");
+const synth = agent("synthesist", "You write findings up for an engineer who will fix them.");
+return synth.ask<Writeup>(`Write these up, deduplicated:\n${JSON.stringify(analyses)}`);
+```
+
+Each stage's result is the next stage's input, and the type argument is what makes the
+handoff safe — `survey.modules.map` only compiles because `Survey` says what came back.
+
+Note the shape of the last call: a single synthesis subagent gets everything at once, because
+deduplicating across findings is exactly the job that needs to see all of them. Do not
+parallelize a stage whose whole purpose is cross-item comparison.
+
+The converse holds too. The analysis stage maps one to one onto the survey's modules, so if a
+per-module check followed it, that check would belong inside the same callback as the
+analysis — not behind a second `Promise.all` (shape 10). Reserve the barrier for the stage
+that needs everyone.
+
+---
+
+## 7. Bounded discovery
+
+**When:** the work has no natural size — "find the bugs" rather than "check these twelve
+files."
+
+```ts
+const MAX_ROUNDS = 6;
+const found: Bug[] = [];
+const seen = new Set<string>();
+
+for (let round = 1; round <= MAX_ROUNDS; round++) {
+  phase("Hunt for bugs not already found");
+  const batch = await agent("hunter").ask<Bugs>(
+    `Find bugs not already in this list: ${JSON.stringify([...seen])}`,
+  );
+  const fresh = batch.bugs.filter((b) => !seen.has(`${b.path}:${b.line}`));
+  if (fresh.length === 0) break; // dry: stop, the remaining rounds would only repeat
+
+  for (const bug of fresh) {
+    seen.add(`${bug.path}:${bug.line}`);
+    report(bug);
+    found.push(bug);
+  }
+  log(`${found.length} found after round ${round}`);
+}
+return found;
+```
+
+Two guards, and you need both: the round cap keeps the loop from running forever when the
+hunter keeps finding things, and the dry check stops it once the hunter stops finding anything
+new. The cap is a knob you pick and amend in the script — the harness enforces no node limit,
+so a loop without one only ends when the user cancels the run. Deduplicate against everything
+**seen**, not against everything kept — dedup against the kept list makes rejected findings
+reappear every round and the loop never converges.
+
+---
+
+## 8. Salvage by report
+
+**When:** always, in any run long enough to fail partway.
+
+```ts
+// Wrong: forty tasks of work, and a failure on task twelve returns nothing.
+const results: Result[] = [];
+for (const item of items) results.push(await worker.ask<Result>(`Handle ${item.id}`));
+return results;
+
+// Right: each result is published the moment it exists.
+phase("Handle each item and publish as it lands");
+const results: Result[] = [];
+for (const item of items) {
+  const result = await worker.ask<Result>(`Handle ${item.id}`);
+  report(result);
+  results.push(result);
+}
+return results;
+```
+
+Reported items are delivered with the completion notification on errored and stopped runs
+as well as successful ones, and they are recorded, so a resumed run does not re-emit them.
+The return value only survives if the script reaches its `return`; reported items survive
+regardless. Report findings, not chatter — there is a per-run item cap, and overrunning it
+fails the run.
+
+The same call can feed a picture. Tag the item with a preset artifact id —
+`report(result, "progress")` — and it lands both in the run's results and on the chart,
+table, metrics or board of that name, live as the loop goes (SKILL.md §10).
+
+A `try`/`catch` around a single task turns one **logic** failure — a subagent result that
+failed validation, a gate that did not pass, a world read over its cap, an artifact publish
+whose file is missing — into a partial result instead of a dead run. It is not for provider
+errors: model-side errors never reach the script. Transient ones (rate limits, overload,
+network errors, timeouts, unknown provider errors) are retried by the runtime without limit;
+deterministic ones (sign-in expired, model not in the plan, quota cap) stop the whole run as
+`stopped` so the user can fix the cause and resume it. A retry loop around an ask for their
+sake is dead code. The one model-adjacent error a script can catch is `ContextLimit`: the
+ask itself was too large for the model even after compaction, and the fix is a smaller ask.
+
+```ts
+for (const item of items) {
+  try {
+    report(await worker.ask<Result>(`Handle ${item.id}`));
+  } catch (error) {
+    log(`skipped ${item.id}: ${String(error)}`);
+  }
+}
+```
+
+---
+
+## 9. Gated verifier loop (world.run)
+
+**When:** the stopping condition is machine-checkable — a build, a proof checker, a test
+suite — and a subagent's claim of success is not worth trusting.
+
+```ts
+const prover = agent("prover", "You repair the proof. Fix exactly what the checker reports.");
+
+phase("Write the first proof attempt");
+await prover.ask<Attempt>(`Prove the open theorem in ${FILE}.`);
+let clean = false;
+for (let round = 1; round <= 8; round++) {
+  phase("Check the file with the fast checker");
+  const check = await world.run("lake", ["env", "lean", FILE], { timeoutMs: 600_000 });
+  clean = check.exitCode === 0 && !check.stderr.includes("sorry");
+  if (clean) break;
+  log(`round ${round}: checker rejected`);
+  phase("Repair what the checker rejected");
+  await prover.ask<Attempt>(`The checker rejected the file:\n${check.stderr}\nRepair ${FILE}.`);
+}
+if (!clean) return { proved: false };
+
+phase("Build the whole project once before handing over");
+const build = await world.run("lake", ["build"], { timeoutMs: 1_800_000 });
+return { proved: build.exitCode === 0 };
+```
+
+The subagent does the open-ended work; the script does the judging, and the judgment is not
+delegable. `world.run` executes the checker for real, so "verified" is never a claim — only
+an exit code. A nonzero exit is a **value**, which is why the loop reads `check.exitCode`
+and feeds `check.stderr` forward instead of catching anything; rejections are reserved for
+the world failing to answer (spawn failure, timeout, output over the cap), and a
+`try`/`catch` around the call is how a script chooses a fallback for those.
+
+Two tiers, and the difference is the whole point. The per-file checker is the fast tier: it
+answers in seconds, so it drives the rounds. It is not the verdict — `lake env lean` exits
+0 on a proof that still says `sorry` and only warns on stderr, which is why the loop reads
+stderr too. The whole-project build is the strong tier: it is what the request was about,
+and it runs once at the end even though the fast tier already said yes. Pick both tiers by
+reading the repository — the README's "run this to verify" line, the `Makefile`, the
+`package.json` scripts — never from habit; the strongest check the repository offers for
+what the user asked is the one that decides (SKILL.md §5).
+
+The command name is a compile-time literal by rule — the user approves the script's command
+set at confirmation — so interpolate paths, flags and round numbers into the **args**,
+never into the command. Compare shape 5: same loop, but there the checker was a subagent;
+prefer this shape whenever a real command can render the verdict.
+
+---
+
+## 10. Per-item pipeline
+
+**When:** two or more stages map one to one — a hunter per file and a confirmer per finding,
+a migrator per file and a checker per file — and nothing in the later stage needs to see the
+whole earlier stage.
+
+```ts
+phase("Hunt for bugs in each file and confirm them as they are found");
+const confirmed = (
+  await Promise.all(
+    paths.map(async (p) => {
+      const hunt = await agent(`hunter-${p}`).ask<Hunt>(`Hunt for correctness bugs in ${p}.`);
+      return Promise.all(
+        hunt.bugs.map(async (bug, index) => {
+          const check = await agent(`confirmer-${p}-${index}`).ask<Confirmation>(
+            `Reproduce this bug from its evidence alone. Do not edit any file.\n${JSON.stringify(bug)}`,
+          );
+          const reported = { ...bug, status: check.reproduced ? "verified" : "unconfirmed" };
+          report(reported);
+          return reported;
+        }),
+      );
+    }),
+  )
+).flat();
+```
+
+One join, at the end, where the report needs every item. Compare the two-barrier version —
+`Promise.all` over the hunters, then `Promise.all` over the confirmers — which starts no
+confirmer until the slowest hunter is done and leaves the concurrency slots idle in between.
+The cache identity of a revised re-run is unchanged: each subagent is still named and asked in
+the same order.
+
+One phase covers the whole pipeline, named for what it does to each item. Do not put a marker
+per stage inside the callback: the run has one current phase, and concurrent callbacks
+re-entering two markers out of order would stamp each other's steps.
+
+When one item failing should cost one item, catch inside the callback (examples #3) or use
+`Promise.allSettled` and read each outcome; a rejection inside a plain `Promise.all` rejects
+the join and the siblings with it.