@hybridlabor-api/aos 4.12.1 → 4.13.0

package/scripts/build-scenario-store-index.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+// Usage: node scripts/build-scenario-store-index.mjs <path-to-local-clone> <commit>
+// Offline: reads blobs of <commit> from the local clone with git; never touches the network and never runs anything from it.
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const OUTPUT_PATH = join(ROOT, 'lib', 'scenario-store-index.json');
+const CAP = 300 * 1024;
+const SOURCE = {
+  id: 'scenario', label: 'Scenario', upstream: 'https://github.com/scenario-labs/skills',
+  raw_base: 'https://raw.githubusercontent.com/scenario-labs/skills',
+  license: 'MIT', copyright: 'Copyright (c) 2026 Scenario', third_party: true,
+};
+
+// Starter set (production_artifacts/09 section 4, minus skills whose dependencies are outside the set).
+// Excluded: scenario-blender-rigging (bx_rig.mannequin imports scenario-blender-sculpting), scenario-unity-2d (SKILL.md
+// names scenario-sprite-pipeline, which does not exist upstream), scenario-text-overlay (Scenario MCP workflow, chevron + network font fetch).
+const BLENDER = 'scenario-blender-expert';
+const UNITY = 'scenario-unity-expert';
+const SET = {
+  [BLENDER]: { dir: 'skills/dcc/blender', category: 'media-eventtech' },
+  'scenario-blender-retopology': { dir: 'skills/dcc/blender', category: 'media-eventtech', requires: [BLENDER] },
+  'scenario-blender-uv-baking': { dir: 'skills/dcc/blender', category: 'media-eventtech', requires: [BLENDER] },
+  'scenario-blender-texturing-shading': { dir: 'skills/dcc/blender', category: 'media-eventtech', requires: [BLENDER] },
+  'scenario-blender-hard-surface': { dir: 'skills/dcc/blender', category: 'media-eventtech', requires: [BLENDER] },
+  'scenario-blender-lighting-rendering': { dir: 'skills/dcc/blender', category: 'media-eventtech', requires: [BLENDER] },
+  'scenario-blender-animation': { dir: 'skills/dcc/blender', category: 'media-eventtech', requires: [BLENDER] },
+  'scenario-blender-geometry-nodes': { dir: 'skills/dcc/blender', category: 'media-eventtech', requires: [BLENDER] },
+  [UNITY]: { dir: 'skills/game-engines/unity', category: 'media-eventtech' },
+  'scenario-unity-performance': { dir: 'skills/game-engines/unity', category: 'engineering-method', requires: [UNITY] },
+  'scenario-unity-pipeline-automation': { dir: 'skills/game-engines/unity', category: 'engineering-method', requires: [UNITY] },
+  'scenario-unity-shaders': { dir: 'skills/game-engines/unity', category: 'media-eventtech', requires: [UNITY] },
+  'scenario-unity-ui': { dir: 'skills/game-engines/unity', category: 'design-ui-ux', requires: [UNITY] },
+};
+
+const [cloneArg, commit] = process.argv.slice(2);
+if (!cloneArg || !/^[a-f0-9]{40}$/.test(commit || '')) {
+  console.error('Usage: build-scenario-store-index.mjs <clone-path> <40-hex-commit>');
+  process.exit(2);
+}
+const clone = resolve(cloneArg);
+const git = (args, opts = {}) => execFileSync('git', ['-C', clone, ...args], { maxBuffer: 64 << 20, ...opts });
+if (git(['rev-parse', `${commit}^{commit}`], { encoding: 'utf8' }).trim() !== commit) throw new Error('commit not found in clone');
+const hash = (data) => createHash('sha256').update(data).digest('hex');
+
+function frontmatterValue(text, key) {
+  const match = text.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!match) return '';
+  const lines = match[1].split(/\r?\n/);
+  const start = lines.findIndex((line) => new RegExp(`^${key}:`, 'i').test(line));
+  if (start < 0) return '';
+  const first = lines[start].slice(lines[start].indexOf(':') + 1).trim();
+  if (first && !/^[>|][-+]?$/.test(first)) return first.replace(/^['"]|['"]$/g, '');
+  const values = [];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (lines[i] && !/^\s/.test(lines[i])) break;
+    values.push(lines[i].trim());
+  }
+  return values.join(' ').trim();
+}
+
+function skillFiles(dir) {
+  return git(['ls-tree', '-r', '-z', commit, `${dir}/`]).toString('latin1').split('\0').filter(Boolean).map((line) => {
+    const [meta, path] = line.split('\t');
+    const [mode, kind, oid] = meta.split(' ');
+    if (kind !== 'blob' || mode === '120000') throw new Error(`Unsupported entry in ${dir}: ${line}`);
+    const data = git(['cat-file', 'blob', oid]);
+    return { path: path.slice(dir.length + 1), sha256: hash(data), size: data.length, exec: mode === '100755', data };
+  }).sort((a, b) => (a.path < b.path ? -1 : 1));
+}
+
+// Audit detectors run on every script (files under scripts/). execBridge = a file that both executes code it
+// receives (exec/eval/runtime compile/reflective invoke) and has a receive channel (socket, server, inbox).
+const EXEC = [
+  [/(^|[^\w.])(exec|eval)\s*\(/m, 'calls exec()/eval()'],
+  [/\b(CSharpScript|CSharpCodeProvider|CompileAssemblyFromSource)\b/, 'compiles C# at runtime'],
+  [/\.Invoke\(null, null\)/, 'invokes a method named in a request'],
+  [/\bAssembly\.Load\b/, 'loads assemblies at runtime'],
+];
+const CHANNEL = [
+  [/\b(HttpListener|TcpListener|UdpClient)\b/, 'network listener'],
+  [/\.listen\s*\(|\.bind\s*\(|socketserver|http\.server|socket\.socket\(/, 'socket/server'],
+  [/\binbox\b/i, 'file inbox polled for requests'],
+];
+const firstHit = (rules, text) => rules.find(([re]) => re.test(text))?.[1];
+
+function audit(files) {
+  const scripts = files.filter((f) => f.path.startsWith('scripts/'));
+  const bridgeFiles = [];
+  for (const f of scripts) {
+    const text = f.data.toString('utf8');
+    const exec = firstHit(EXEC, text);
+    const channel = firstHit(CHANNEL, text);
+    if (exec && channel) bridgeFiles.push({ path: f.path, reason: `${exec} + ${channel}` });
+  }
+  return { hasScripts: scripts.length > 0, scriptCount: scripts.length, execBridge: bridgeFiles.length > 0, execBridgeFiles: bridgeFiles };
+}
+
+const KNOWN_SOFTWARE = ['Blender', 'Unity'];
+function software(description) {
+  return KNOWN_SOFTWARE.flatMap((name) => {
+    const m = description.match(new RegExp(`\\b${name}\\b(?:\\s(\\d+(?:\\.\\d+)+))?`));
+    return m ? [m[1] ? `${name} ${m[1]}` : name] : [];
+  });
+}
+
+const skills = {};
+for (const [name, cfg] of Object.entries(SET)) {
+  const dir = `${cfg.dir}/${name}`;
+  const files = skillFiles(dir);
+  const skillMd = files.find((f) => f.path === 'SKILL.md');
+  if (!skillMd) throw new Error(`${name}: no SKILL.md in ${dir}`);
+  const text = skillMd.data.toString('utf8');
+  if ((frontmatterValue(text, 'name') || '').trim() !== name) throw new Error(`${name}: SKILL.md name differs from directory`);
+  if (!/^[A-Za-z0-9_-]+$/.test(name)) throw new Error(`Invalid store name: ${name}`);
+  const description = frontmatterValue(text, 'description').replace(/\s+/g, ' ').trim();
+  skills[name] = {
+    description: description.length > 100 ? `${description.slice(0, 99)}…` : description,
+    category: cfg.category,
+    tier: 'free',
+    origin: 'scenario',
+    requires_auth: false,
+    sha256: skillMd.sha256,
+    upstream_path: `${dir}/SKILL.md`,
+    ...(cfg.requires ? { requires: cfg.requires } : {}),
+    software: software(description),
+    ...audit(files),
+    files: files.map(({ data, ...rest }) => rest),
+  };
+}
+for (const [name, item] of Object.entries(skills)) {
+  for (const dep of item.requires || []) if (!skills[dep]) throw new Error(`${name} requires ${dep}, which is not in the set`);
+}
+
+const index = {
+  version: '1.1.0',
+  generated_at: git(['show', '-s', '--format=%cI', commit], { encoding: 'utf8' }).trim(),
+  pinned_commit: commit,
+  source: SOURCE,
+  harness_support: ['claude', 'antigravity', 'codex', 'cursor', 'roo'],
+  skills: Object.fromEntries(Object.entries(skills).sort(([a], [b]) => a.localeCompare(b))),
+  subagents: {},
+};
+const output = JSON.stringify(index) + '\n';
+if (Buffer.byteLength(output) >= CAP) throw new Error(`Store index exceeds 300 KB: ${Buffer.byteLength(output)} bytes`);
+writeFileSync(OUTPUT_PATH, output);
+for (const [name, item] of Object.entries(skills)) {
+  console.log(`${name}\t${item.category}\tfiles=${item.files.length}\tscripts=${item.scriptCount}\texecBridge=${item.execBridge}\t${item.execBridgeFiles.map((f) => `${f.path} (${f.reason})`).join('; ')}`);
+}
+console.log(`Wrote ${OUTPUT_PATH} with ${Object.keys(skills).length} skills (${Buffer.byteLength(output)} bytes).`);

package/skills/bdbrainstorm/SKILL.md

@@ -39,6 +39,7 @@ You are strictly required to enforce the following 6 pillars in your process:
 - **Mandatory — Plan Canvas review.** Write the aligned plan to a file, then run `aos-plan-canvas open <file>` followed by `aos-plan-canvas await <file>` and leave it running. The user reviews and annotates in the browser (Mermaid diagrams render live, click-to-annotate, chat rail); do not write `state.goal` or hand off to `/startcycle-graph` before an `approve` verdict comes back. A `request_changes` verdict means revise the plan file and reopen the session — it live-reloads. This runs identically regardless of which agent harness is executing this skill; it is a plain CLI, not a Claude-Code-specific mechanism. See the `plan-canvas` skill.
 - Write the plan in the agenttrail component convention (`## Name {#id}` components with `needs:` / `files:` lines, tasks as `- [ ] ... {#id}`) and render the architecture with `aos-archify` so the canvas review includes the diagram; after the `approve` verdict, Trigger A starts the live map. See the `agenttrail` and `archify` skills.
 - Present the aligned plan and hand off to `/startcycle-graph` for execution — write `state.goal` from this session's output and let `/startcycle-graph`'s dispatcher take it from there (see `.agents/graph.md`). This skill does not invoke `/startcycle-graph`'s agents itself; it produces the goal they read.
+- For a recurring quality goal, run `/design-control-loop` after shipping (manual, opt-in; not part of the graph).
 
 ## Execution Rules
 1. **Never skip the debate:** Ideas must be contested by subagents and the user before finalization.

package/skills/global_config/agent-pipeline/SKILL.md

@@ -48,6 +48,10 @@ This file exists so anyone (human or agent) asking "what's the BDB software
 lifecycle?" gets the real shape of it, without re-deriving it from `graph.md`
 line by line. It is descriptive, not an alternate entry point.
 
+Optional post-ship step, outside the graph: `/design-control-loop` sets up a
+recurring improvement loop in CI for a quality goal. It is started manually and
+the dispatcher never calls it.
+
 ## 2. When to Use
 - Use when you need the lifecycle framing (define → plan → build → verify →
   ship) to structure a conversation or a manual walkthrough.

package/skills/global_config/aos-store/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: aos-store
-description: Browse, preview, and install AOS Core + ECC skills and agents from a local web UI. Use when exploring or adding new skills to a project.
+description: Browse, preview, and install AOS Core, ECC and Scenario skills and agents from a local web UI. Use when exploring or adding new skills to a project.
 category: bdb-core
 metadata:
   version: "1.0.0"
@@ -13,7 +13,7 @@ A web UI for discovering and installing AOS skills and agents. Lists what is alr
 
 ## When to Use
 
-- You want to explore available AOS Core + ECC skills and agents in a local web UI.
+- You want to explore available AOS Core, ECC and Scenario skills and agents in a local web UI.
 - You need to preview a skill or agent before installing it.
 - You want to install skills or agents globally (all harnesses) or into the current project, with explicit confirmation before each install.
 
@@ -43,7 +43,7 @@ Some harnesses (e.g. OpenCode) cannot open a browser automatically. **Always pri
 
 ## Store Features
 
-- **Browse:** Lists all available AOS Core and ECC skills and agents.
+- **Browse:** Lists all available AOS Core, ECC and Scenario skills and agents. Scenario items are MIT-licensed third-party skills; some contain scripts (the preview warns, and flags bridges that execute received code).
 - **Show Installed:** Marks what is already installed and which items are AOS Core (always included).
 - **Preview:** "+ Add" first shows the exact target paths for the chosen scope (global or project); nothing is written yet.
 - **Confirm:** Every install requires explicit user confirmation — nothing is installed silently.

package/skills/global_config/design-control-loop/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: design-control-loop
+description: interview the user to design an agentic control loop (sensor, controller, actuator under disturbances) tailored to their codebase, then build it as locally-runnable components plus a scheduled coding-agent workflow
+category: bdb-core
+source: humanlayer
+license: MIT (see THIRD_PARTY_NOTICES.md, humanlayer/skills)
+---
+
+# Design Control Loop
+
+<!-- AOS notes: start (local addition, not upstream) -->
+## AOS notes
+
+- **Manual, opt-in.** Start it yourself (`/design-control-loop`) for a recurring improvement loop in CI. It is not a pipeline node and not part of `/startcycle-graph`; the dispatcher never calls it. After shipping, it is an optional follow-up.
+- **Runs outside the GO gate.** The loops it generates run unattended in CI, often with `--dangerously-skip-permissions` and API secrets, so the AOS GO gate does not cover them. That is a deliberate design choice; you decide per loop. When generating workflows, pin CLI versions instead of `@latest` and keep secrets in the CI secret store.
+- **Output lives in the target repo.** The generated actuator skill, scripts and workflow are written to the TARGET repo, not to AOS.
+- **Source.** Vendored from https://github.com/humanlayer/skills at commit `ca7c8088db69e315a8b2deea43820270457f8f3c` (MIT, see `THIRD_PARTY_NOTICES.md`). Everything below this section is upstream text.
+<!-- AOS notes: end -->
+
+Use this skill when a user wants to drive some property of their codebase toward a target with small, low-risk, reviewable changes on a schedule — an **agentic control loop**.
+
+Your job is to **interview the user, design the loop _with_ them, and then build it for them**. The design must be tailored to *their* codebase and the tooling they already use. There is no fixed toolset and no template to reproduce: propose options grounded in what you find in the repo, discuss trade-offs, agree on a design, then implement it.
+
+## The mental model
+
+Borrow from control theory. The codebase is a dynamic system being changed continuously (by teammates, dependencies, and generated code — the **disturbances**). A control loop drives it toward a desired state instead of all at once:
+
+- **Set point** — the desired end state for some property of the codebase.
+- **Sensor** — measures the current state, producing the gap to the set point.
+- **Controller** — decides the next small, low-risk change from that measurement.
+- **Actuator** — a coding agent that applies the change and opens a PR.
+- The result feeds back into the next run. A human stays *on* the loop to steer it.
+
+Read `references/control-loop-taxonomy.md` and walk the user through these concepts before designing anything. For one fully worked example, see `references/example-control-loop.md` — treat it as an illustration, not a blueprint.
+
+## How to run this skill
+
+- **Read the repo before you ask** (Phase A). Come to the interview with proposals, not a blank form.
+- **Tailor every component.** The right sensor, controller, and actuator depend entirely on the user's problem and stack. The lists in the references are examples to spark discussion, never a checklist to push.
+- **Make each component runnable locally and standalone before wiring it into CI** (Phase D). The workflow should only orchestrate pieces the user can already run by hand.
+- **Capture the agreed design in writing** before building, so the user can correct it cheaply.
+
+## Outputs
+
+Create or update these in the target repo, tailored to the agreed design:
+
+- The **sensor** and **controller** as version-controlled commands/scripts the user can run locally.
+- `.claude/skills/<skill-name>/SKILL.md` — the **actuator** skill capturing the agent's judgement (path may be `.agents/skills/...` per repo convention).
+- The recurring **workflow** that runs the loop and opens a PR (GitHub Actions by default; whatever CI the repo uses).
+- A **memory/feedback file** that carries standing feedback between runs.
+- Optionally, a **dampener** (regression gate) that keeps the problem from getting worse while the loop improves it.
+
+## Workflow
+
+### Phase A — Understand the system
+
+**Read the following references:** `references/example-control-loop.md`.
+
+Read before asking setup questions:
+
+- Existing CI: `.github/workflows/*.yml`, `.github/actions/**`, or the repo's non-GitHub CI config — runner, checkout, dependency install, cache, and PR conventions.
+- Package manager files (`package.json`, `bun.lock`, `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, …).
+- Existing validation scripts: typecheck, lint, test, quality, format, and package-scoped commands.
+- Existing `.claude/skills` / `.agents/skills` and any existing agent loops (workflows, `agent-memory`, where glue scripts live) to mirror conventions instead of inventing new ones.
+- The static-analysis, linting, codegen, and test tooling already in the repo — these are the most likely raw material for a sensor.
+- Discover packages, services, and repo purpose at a high level. 
+
+Completion criterion: you can name the repo's package manager, install command, likely validation commands, CI platform, and any existing loop conventions. You understand the packages/services/applications it contains at a high level.
+
+### Phase B — Design the loop with the user
+
+**Read the following references:** `references/control-loop-taxonomy.md`, `references/example-control-loop.md`, `references/agent-runner-templates.md`.
+
+This is an interview. Work through each component below. Start by asking the user questions about the set point. Proposing options grounded in Phase A and surfacing trade-offs rather than mandating any choice. Record the decisions as you go.
+
+1. **Set point.** What property are we driving, and to what target? Examples: an invariant ("no procedures use the old pattern"), a threshold ("test coverage ≥ X in these packages"), or a direction ("reduce occurrences each run"). Also pin the **scope**: which directories/packages the loop may change, and which it may only read.
+
+2. **Sensor.** How will the loop measure the gap to the set point? Inspect the codebase and the user's existing tooling and propose the options that fit *their* stack — a static-analysis or lint tool, a structural/AST search, a test suite, a type checker, a telemetry or error query, a custom script, or even an agent-based check. Discuss the trade-offs that matter to them (stability, cost, repeatability, and whether the measurement can be silently disabled) instead of mandating any property. Aim for a measurement the controller can act on repeatably.
+
+3. **Controller.** How will the loop choose the next increment from the measurement, sized to stay low-risk and reviewable? Design this *with* the user: how to prioritize targets, how big one increment is, and what "one reviewable unit of work" means here. A controller can be anything from fully deterministic (a script that selects the next target) to fully agentic (an agent that decides from natural-language criteria), and it may be **fused** with the sensor or the actuator. The controller is the part you will **tune over time** from loop output — start simple and expect to revise it.
+
+4. **Actuator.** A coding agent plus a repo-local skill applies the change.
+   - **Agent + credentials.** Pick the CLI coding agent (Claude Code, Codex, OpenCode, CodeLayer, …), its secret, and its headless command from `references/agent-runner-templates.md`.
+   - **Golden patterns first.** Before automating, establish what a good change looks like: ask the user whether existing patterns in the codebase should be followed, and inspect the code to find them. Capture these in the actuator skill (Phase C).
+   - **Validation.** Decide which commands must pass before the agent commits (propose these from Phase A and confirm).
+
+5. **Disturbances + dampener (offer).** Name what changes the system outside the loop (teammates shipping concurrently, dependency bumps, generated code). Then **offer** a dampener: a check that keeps the measured problem from getting worse while the scheduled loop chips away at it — for example a PR check that compares the sensor's output against a baseline and surfaces (or eventually blocks) newly introduced deviations. This is optional; some loops do not need one.
+
+Completion criterion: a short written design naming the set point, sensor, controller, actuator (agent + skill + validation), and disturbances/dampener — with each component something the user can run locally.
+
+### Phase C — Build the actuator skill
+
+**Read the following references:** `references/skill-template.md`, `references/example-skill.md`, `references/response-template.md`.
+
+Write a repo-local skill that captures the actuator's judgement for this task. It can use repo-specific paths, package names, and conventions since it lives in the repository.
+
+- Put ordered behavior in `SKILL.md` as steps with checkable completion criteria; move long templates and examples into sibling reference files.
+- Encode the golden patterns from Phase B4 so the agent follows established conventions.
+- Keep one source of truth for each rule; do not repeat the same guidance in the skill, the prompt, and the memory file.
+- Include a response template (e.g. `references/response-template.md`) defining how the agent formats its final output, which becomes the PR body. Instruct the skill to read and follow it.
+- Use `references/skill-template.md` as the skeleton and `references/example-skill.md` as a concrete example. See https://agentskills.io/specification for the skill spec.
+
+**IMPORTANT:** the `name` in the skill's frontmatter must match its directory slug — a skill named `migrate-foo` lives at `.claude/skills/migrate-foo/SKILL.md` (or `.agents/skills/migrate-foo/SKILL.md`).
+
+Completion criterion: the skill explains the job clearly enough that the agent can do it unattended, including how to format its final response.
+
+### Phase D — Make each component runnable locally
+
+**Read the following references:** `references/agent-runner-templates.md`.
+
+Before any CI exists, land the sensor and controller as version-controlled commands or scripts (follow the repo's convention for where such scripts live), and verify the whole loop works by hand:
+
+- Run the **sensor** standalone and confirm it produces a stable, usable measurement.
+- Run the **controller** on real sensor output and confirm it selects a sensible next increment.
+- Run the **actuator** locally via its headless CLI command on a controller-selected target, and confirm it makes the change and passes validation.
+
+Only proceed to CI once each piece runs locally on its own. This keeps the loop debuggable and makes the workflow a thin orchestrator of things the user can already run.
+
+Completion criterion: the user can run sensor, controller, and actuator locally and independently.
+
+### Phase E — Wire the loop into CI
+
+**Read the following references:** `references/workflow-template.yml`, `references/prompt-template.md`, `references/agent-runner-templates.md`.
+
+Assemble the components into a recurring job. GitHub Actions is the default because it already has the code, the secrets, version control, and scheduling/dispatch — but use whatever CI the repo uses.
+
+- Run the loop as **discrete steps: sensor → controller → actuator**, then commit and open a PR using the agent's final message as the body. (When components are fused — e.g. the sensor already prioritizes, or one agent both selects and changes — collapse them into a single step; do not invent separation the design does not have.)
+- Reusable logic can live in a custom composite action.
+- Decide the **cadence** (daily, weekdays, weekly, monthly, manual-only, or custom cron) based on task risk and review burden.
+- Interpolate the memory file (Phase F) into the actuator's context.
+- Use `references/workflow-template.yml` as the base and `references/prompt-template.md` for the embedded prompt. Pull the agent run + response-extraction steps from `references/agent-runner-templates.md` (each agent outputs differently; get the final response into `/tmp/pr-body.md`).
+
+Completion criterion: the workflow can run from `workflow_dispatch` without relying on files that do not exist.
+
+### Phase F — Put a human on the loop
+
+**Read the following references:** `references/memory-template.md`, `references/agent-iteration.ts`.
+
+A scheduled loop drifts without steering. Give the human two channels, both of which should change future behavior, not just the current PR:
+
+- **Memory/feedback file.** A version-controlled markdown file (e.g. `.github/agent-memory/<task-slug>.md`) loaded deterministically into the actuator's context **after the controller** on every run. Use `references/memory-template.md`. Good entries: permanent scope exclusions, known false-positive areas, and reviewer feedback that should change future selections — not one-off instructions or single-run logs.
+- **`/iterate` on the PR.** Label each loop's PRs and embed a hidden marker so each workflow only handles comments on PRs it created. When a maintainer comments `/iterate`, the matching workflow loads the PR context (diff, comments) and the feedback, and the agent updates its memory and the PR. Install `references/agent-iteration.ts` (modes: `footer` and `prompt`) where the repo keeps CI scripts.
+
+Frame this for the user as **how you tune the controller and skill over time** — the loop gets better because a human keeps correcting it.
+
+Completion criterion: standing feedback survives between runs, and `/iterate` (if enabled) updates the existing PR.
+
+### Phase G — Flow control
+
+**Read the following references:** `references/workflow-template.yml`.
+
+Bound work-in-progress so the loop never produces PRs faster than they can be reviewed. **Recommended default: one open PR per loop.**
+
+- The workflow checks for open PRs with this loop's label and no-ops on scheduled runs when the bound is met; manual `workflow_dispatch` runs bypass the check.
+- Decide PR metadata: label name, PR title prefix, branch prefix.
+
+Without this, a daily loop can stack up duplicate or conflicting PRs while no one is reviewing. Completion criterion: scheduled runs no-op when the open-PR bound for this loop is already met.
+
+### Phase H — Validate, dry-run, and iterate faster
+
+**Read the following references:** `references/workflow-template.yml`.
+
+**Validate** the workflow YAML (`bunx js-yaml file.yml`, `python -c "import yaml,sys; yaml.safe_load(open(sys.argv[1]))" file.yml`, or `yq`) and confirm every path named by the skill, workflow, and memory file exists or is created by this task.
+
+**Dry-run.** A workflow cannot be `workflow_dispatch`-ed until it has run once. Temporarily add a `push` trigger for the current branch, push, watch it run, then remove the trigger. Review any PR it opens to confirm the loop's behavior.
+
+**Ready to iterate faster** (once the loop is tuned and producing consistent, high-quality output): increase the schedule frequency; widen the controller's batch (e.g. select N targets per run); run the sense→control→actuate cycle N times per workflow run; or run the workflow multiple times and assign one PR to each teammate.
+
+Completion criterion: the workflow YAML parses, all referenced files exist, and the loop has produced at least one reviewed PR.
+
+## Reference Files
+
+Each phase above names the references relevant to it — read each one when you reach that phase. Full index:
+
+- `references/control-loop-taxonomy.md` — the control-loop components and the design questions to ask; read this first and use it to teach the user.
+- `references/example-control-loop.md` — one fully worked loop, annotated component-by-component. An illustration, not a template.
+- `references/agent-runner-templates.md` — local + CI headless commands and secrets for Claude Code, Codex, OpenCode, and CodeLayer, with response extraction.
+- `references/workflow-template.yml` — recurring loop workflow skeleton with discrete sensor/controller/actuator steps.
+- `references/prompt-template.md` — embedded prompt structure for the actuator step.
+- `references/memory-template.md` — memory/feedback file skeleton.
+- `references/skill-template.md` — skeleton for the generated actuator skill.
+- `references/response-template.md` — examples for how the agent should format its final response (the PR body).
+- `references/example-skill.md` — a concrete example of a well-formed task skill.
+- `references/agent-iteration.ts` — helper for `/iterate` support (PR footer marker + iteration prompt building).

package/skills/global_config/design-control-loop/references/agent-iteration.ts

@@ -0,0 +1,174 @@
+#!/usr/bin/env bun
+
+// Shared helper for recurring coding agent workflows.
+//
+// `footer` mode appends visible /iterate instructions plus a hidden workflow marker
+// to agent-created PR bodies. The marker is what lets many workflows listen for the
+// same /iterate command while only the workflow that opened the PR continues.
+//
+// `prompt` mode builds the iteration prompt after the workflow has passed its cheap
+// pre-check and checked out the PR branch. It intentionally includes raw PR context
+// plus the workflow memory file, then asks the agent to update the PR and distill
+// durable guidance back into that memory file when appropriate.
+//
+// Installation options:
+// 1. Place in `.github/scripts/agent-iteration.ts` (recommended)
+// 2. Place in `ci-scripts/agent-iteration.ts`
+// 3. Place in `scripts/agent-iteration.ts`
+//
+// Usage:
+//   bun .github/scripts/agent-iteration.ts --command footer --workflow <workflow-id> --memory <memory-path>
+//   bun .github/scripts/agent-iteration.ts --command prompt --workflow <workflow-id> --memory <memory-path> --repo <owner/repo> --pr-number <number> --comment-body <body>
+
+interface Args {
+	command: 'footer' | 'prompt'
+	workflow: string
+	memory: string
+	repo?: string
+	prNumber?: string
+	commentBody?: string
+}
+
+const args = parseArgs(Bun.argv.slice(2))
+
+if (args.command === 'footer') {
+	process.stdout.write(renderFooter(args.workflow, args.memory))
+} else {
+	if (!args.repo || !args.prNumber) throw new Error('--repo and --pr-number are required for prompt')
+	process.stdout.write(await renderIterationPrompt(args))
+}
+
+function renderFooter(workflow: string, memory: string): string {
+	return `
+---
+
+### Iterating on this agent run
+
+This PR was opened by a coding agent workflow. Maintainers can comment:
+
+- \`/iterate <feedback>\` to ask the same workflow to update this PR and learn durable guidance for future runs.
+
+The workflow stores durable feedback in its agent memory file and injects that memory into future runs.
+
+<!-- codelayer-agent:workflow=${workflow};memory=${memory};version=1 -->
+`.trim()
+}
+
+async function renderIterationPrompt(args: Args): Promise<string> {
+	const memory = await readTextIfExists(args.memory)
+	const pr = await ghJson(`repos/${args.repo}/pulls/${args.prNumber}`)
+	const [issueComments, reviewComments] = await Promise.all([
+		ghJson(`repos/${args.repo}/issues/${args.prNumber}/comments --paginate`),
+		ghJson(`repos/${args.repo}/pulls/${args.prNumber}/comments --paginate`),
+	])
+
+	return `# Iteration Request
+
+${stripIterateCommand(args.commentBody ?? '')}
+
+# Workflow Identity
+
+- Workflow: ${args.workflow}
+- Agent memory file: ${args.memory}
+
+# Instructions
+
+You are iterating on an open PR that was created by this coding agent workflow.
+
+1. Treat the Iteration Request as the user's current instruction.
+2. Update this PR branch if the feedback asks for a code, workflow, prompt, or documentation change.
+3. Distill durable feedback into ${args.memory} when it should influence future scheduled/manual runs of this workflow.
+4. Keep ${args.memory} concise and human-readable. Do not append raw transcripts or one-off PR details.
+5. If the feedback is only PR-specific, update the PR but do not add it to memory.
+6. Commit and push any changes you make.
+7. Finish with a concise GitHub-flavored markdown summary of what changed and whether memory was updated.
+
+# Current Agent Memory
+
+${memory || '(memory file is empty or missing)'}
+
+# Pull Request
+
+- Number: #${pr.number}
+- Title: ${pr.title}
+- State: ${pr.state}
+- Base: ${pr.base?.ref ?? '(unknown)'}
+- Head: ${pr.head?.ref ?? '(unknown)'}
+
+## PR Body
+
+${pr.body ?? '(empty)'}
+
+# PR Issue Comments
+
+${formatIssueComments(issueComments)}
+
+# PR Review Comments
+
+${formatReviewComments(reviewComments)}
+`
+}
+
+async function readTextIfExists(path: string): Promise<string> {
+	try {
+		const file = Bun.file(path)
+		if (!(await file.exists())) return ''
+		return await file.text()
+	} catch {
+		return ''
+	}
+}
+
+async function ghJson(pathAndArgs: string): Promise<any> {
+	const result = await Bun.$`bash -lc ${`gh api ${pathAndArgs}`}`.text()
+	return JSON.parse(result)
+}
+
+function formatIssueComments(comments: any): string {
+	if (!Array.isArray(comments) || comments.length === 0) return '(no issue comments)'
+	return comments
+		.map((comment) => {
+			return `Comment ${comment.id} by ${comment.user?.login ?? 'unknown'} at ${comment.created_at ?? 'unknown time'}:\n\n${comment.body ?? ''}`
+		})
+		.join('\n\n---\n\n')
+}
+
+function formatReviewComments(comments: any): string {
+	if (!Array.isArray(comments) || comments.length === 0) return '(no review comments)'
+	return comments
+		.map((comment) => {
+			return `Review comment ${comment.id} by ${comment.user?.login ?? 'unknown'} on ${comment.path ?? 'unknown path'}:${comment.line ?? comment.original_line ?? 'unknown line'} at ${comment.created_at ?? 'unknown time'}:\n\n${comment.body ?? ''}`
+		})
+		.join('\n\n---\n\n')
+}
+
+function stripIterateCommand(body: string): string {
+	return body.trim().replace(/^\/iterate\b\s*/i, '').trim() || 'Iterate on this PR using the available feedback.'
+}
+
+function parseArgs(argv: string[]): Args {
+	const parsed: Record<string, string> = {}
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i]
+		if (!arg?.startsWith('--')) continue
+		const key = arg.slice(2)
+		const value = argv[i + 1]
+		if (!value || value.startsWith('--')) throw new Error(`Missing value for ${arg}`)
+		parsed[key] = value
+		i += 1
+	}
+
+	const command = parsed.command
+	if (command !== 'footer' && command !== 'prompt') throw new Error('--command must be footer or prompt')
+	if (!parsed.workflow) throw new Error('--workflow is required')
+	if (!parsed.memory) throw new Error('--memory is required')
+
+	return {
+		command,
+		workflow: parsed.workflow,
+		memory: parsed.memory,
+		repo: parsed.repo,
+		prNumber: parsed['pr-number'],
+		commentBody: parsed['comment-body'],
+	}
+}