[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M75314TQ4R7RFY6RYKD18YAX":3,"skill-same:01M75314TQ4R7RFY6RYKD18YAX":98},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":16,"sourceHtmlUrl":17,"categories":18,"keywords":19,"publishedAt":20,"linkOnly":21,"markdownContent":22,"markdownBody":23,"frontMatter":24,"refName":25,"commitSha":26,"skillDirectory":27,"forksCount":14,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":6,"updatedAt":31,"install":32,"resources":45},"01M75314TQ4R7RFY6RYKD18YAX","design-control-loop",null,"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 pi coding-agent workflow","kasuboski\u002Fagents.nix","kasuboski","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F2403190?v=4","01M71Q8M5P8MJCB3TZTMMG73S6","Josh Kasuboski","01M7530R0JDN2R3KHRWGJXQAWB",0,"MIT","https:\u002F\u002Fgithub.com\u002Fkasuboski\u002Fagents.nix\u002Fblob\u002Fmain\u002Fpi-extensions\u002Fskills\u002Fdesign-control-loop\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fkasuboski\u002Fagents.nix\u002Fblob\u002Fmain\u002Fpi-extensions\u002Fskills\u002Fdesign-control-loop\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: design-control-loop\ndescription: 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 pi coding-agent workflow\n---\n\n# Design Control Loop\n\nUse 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**.\n\nYour 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.\n\n## The mental model\n\nBorrow 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:\n\n- **Set point** — the desired end state for some property of the codebase.\n- **Sensor** — measures the current state, producing the gap to the set point.\n- **Controller** — decides the next small, low-risk change from that measurement.\n- **Actuator** — a pi coding agent using a repo-local skill that applies the change and opens a PR.\n- The result feeds back into the next run. A human stays *on* the loop to steer it.\n\nRead `references\u002Fcontrol-loop-taxonomy.md` and walk the user through these concepts before designing anything. For one fully worked example, see `references\u002Fexample-control-loop.md` — treat it as an illustration, not a blueprint.\n\n## How to run this skill\n\n- **Read the repo before you ask** (Phase A). Come to the interview with proposals, not a blank form.\n- **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.\n- **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.\n- **Capture the agreed design in writing** before building, so the user can correct it cheaply.\n\n## Outputs\n\nCreate or update these in the target repo, tailored to the agreed design:\n\n- The **sensor** and **controller** as version-controlled commands\u002Fscripts the user can run locally.\n- A project-local actuator skill at the repo's established skill location (`.pi\u002Fskills\u002F\u003Cskill-name>\u002FSKILL.md`, `.agents\u002Fskills\u002F\u003Cskill-name>\u002FSKILL.md`, or another documented `skills\u002F` convention).\n- The recurring **workflow** that runs the loop and opens a PR (GitHub Actions by default; whatever CI the repo uses).\n- A **memory\u002Ffeedback file** that carries standing feedback between runs.\n- Optionally, a **dampener** (regression gate) that keeps the problem from getting worse while the loop improves it.\n\n## Workflow\n\n### Phase A — Understand the system\n\n**Read the following references:** `references\u002Fexample-control-loop.md`.\n\nRead before asking setup questions:\n\n- Existing CI: `.github\u002Fworkflows\u002F*.yml`, `.github\u002Factions\u002F**`, or the repo's non-GitHub CI config — runner, checkout, dependency install, cache, and PR conventions.\n- Package manager files (`package.json`, `bun.lock`, `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, …).\n- Existing validation scripts: typecheck, lint, test, quality, format, and package-scoped commands.\n- Existing project skills (`.pi\u002Fskills`, `.agents\u002Fskills`, `skills\u002F`) and any existing agent loops (workflows, `agent-memory`, where glue scripts live) to mirror conventions instead of inventing new ones.\n- The static-analysis, linting, codegen, and test tooling already in the repo — these are the most likely raw material for a sensor.\n- Discover packages, services, and repo purpose at a high level.\n\nCompletion 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\u002Fservices\u002Fapplications it contains at a high level.\n\n### Phase B — Design the loop with the user\n\n**Read the following references:** `references\u002Fcontrol-loop-taxonomy.md`, `references\u002Fexample-control-loop.md`, `references\u002Fagent-runner-templates.md`.\n\nThis 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.\n\n1. **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\u002Fpackages the loop may change, and which it may only read.\n\n2. **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\u002FAST 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.\n\n3. **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 (a pi 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.\n\n4. **Actuator.** A pi coding agent plus a repo-local skill applies the change.\n   - **Pi setup.** For interactive work in this repository, prefer the `agent` tool when it is available; it already spawns an isolated pi child and returns structured output. For scripts or CI without a parent pi session, use pi's configured provider\u002Fmodel and credentials, or explicit `--provider`, `--model`, and `--api-key` options with `-p`. See `references\u002Fagent-runner-templates.md` for both shapes.\n   - **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).\n   - **Validation.** Decide which commands must pass before the agent commits (propose these from Phase A and confirm).\n\n5. **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.\n\nCompletion criterion: a short written design naming the set point, sensor, controller, actuator (pi command + skill + validation), and disturbances\u002Fdampener — with each component something the user can run locally.\n\n### Phase C — Build the actuator skill\n\n**Read the following references:** `references\u002Fskill-template.md`, `references\u002Fexample-skill.md`, `references\u002Fresponse-template.md`.\n\nWrite 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.\n\n- Put ordered behavior in `SKILL.md` as steps with checkable completion criteria; move long templates and examples into sibling reference files.\n- Encode the golden patterns from Phase B4 so the agent follows established conventions.\n- Keep one source of truth for each rule; do not repeat the same guidance in the skill, the prompt, and the memory file.\n- Include a response template (e.g. `references\u002Fresponse-template.md`) defining how the agent formats its final output, which becomes the PR body. Instruct the skill to read and follow it.\n- Use `references\u002Fskill-template.md` as the skeleton and `references\u002Fexample-skill.md` as a concrete example. See https:\u002F\u002Fagentskills.io\u002Fspecification for the skill spec and ensure the result is discoverable by pi.\n\n**IMPORTANT:** put the skill in the target repo's established project skill location. For pi, `.pi\u002Fskills\u002F\u003Cskill-name>\u002FSKILL.md` or `.agents\u002Fskills\u002F\u003Cskill-name>\u002FSKILL.md` are standard; a repository package may instead use its declared `skills\u002F` directory. Keep the frontmatter name lowercase and hyphenated.\n\nCompletion criterion: the skill explains the job clearly enough that a pi agent can do it unattended, including how to format its final response.\n\n### Phase D — Make each component runnable locally\n\n**Read the following references:** `references\u002Fagent-runner-templates.md`.\n\nBefore 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:\n\n- Run the **sensor** standalone and confirm it produces a stable, usable measurement.\n- Run the **controller** on real sensor output and confirm it selects a sensible next increment.\n- Run the **actuator** locally through the `agent` tool when working inside pi, or through pi's print mode when testing the external\u002FCI path. Confirm it makes the change and passes validation.\n\nOnly 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.\n\nCompletion criterion: the user can run sensor, controller, and actuator locally and independently.\n\n### Phase E — Wire the loop into CI\n\n**Read the following references:** `references\u002Fworkflow-template.yml`, `references\u002Fprompt-template.md`, `references\u002Fagent-runner-templates.md`.\n\nAssemble the components into a recurring job. GitHub Actions is the default because it already has the code, the secrets, version control, and PR conventions — but use whatever CI the repo uses.\n\n- 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 pi agent both selects and changes — collapse them into a single step; do not invent separation the design does not have.)\n- Reusable logic can live in a custom composite action.\n- Decide the **cadence** (daily, weekdays, weekly, monthly, manual-only, or custom cron) based on task risk and review burden.\n- Interpolate the memory file (Phase F) into the actuator's context.\n- Use `references\u002Fworkflow-template.yml` as the base and `references\u002Fprompt-template.md` for the embedded prompt. Use the pi print-mode run and response-capture steps from `references\u002Fagent-runner-templates.md`.\n\nCompletion criterion: the workflow can run from `workflow_dispatch` without relying on files that do not exist.\n\n### Phase F — Put a human on the loop\n\n**Read the following references:** `references\u002Fmemory-template.md`, `references\u002Fagent-iteration.ts`.\n\nA scheduled loop drifts without steering. Give the human two channels, both of which should change future behavior, not just the current PR:\n\n- **Memory\u002Ffeedback file.** A version-controlled markdown file (e.g. `.github\u002Fagent-memory\u002F\u003Ctask-slug>.md`) loaded deterministically into the actuator's context **after the controller** on every run. Use `references\u002Fmemory-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.\n- **`\u002Fiterate` 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 `\u002Fiterate`, the matching workflow loads the PR context (diff, comments) and the feedback, and the pi agent updates its memory and the PR. Install `references\u002Fagent-iteration.ts` (modes: `footer` and `prompt`) where the repo keeps CI scripts.\n\nFrame this for the user as **how you tune the controller and skill over time** — the loop gets better because a human keeps correcting it.\n\nCompletion criterion: standing feedback survives between runs, and `\u002Fiterate` (if enabled) updates the existing PR.\n\n### Phase G — Flow control\n\n**Read the following references:** `references\u002Fworkflow-template.yml`.\n\nBound work-in-progress so the loop never produces PRs faster than they can be reviewed. **Recommended default: one open PR per loop.**\n\n- 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.\n- Decide PR metadata: label name, PR title prefix, branch prefix.\n\nWithout this, a daily loop can stack up duplicate or conflicting PRs while no one is reviewing it. Completion criterion: scheduled runs no-op when the open-PR bound for this loop is already met.\n\n### Phase H — Validate, dry-run, and iterate faster\n\n**Read the following references:** `references\u002Fworkflow-template.yml`.\n\n**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.\n\n**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.\n\n**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.\n\nCompletion criterion: the workflow YAML parses, all referenced files exist, and the loop has produced at least one reviewed PR.\n\n## Reference Files\n\nEach phase above names the references relevant to it — read each one when you reach that phase. Full index:\n\n- `references\u002Fcontrol-loop-taxonomy.md` — the control-loop components and the design questions to ask; read this first and use it to teach the user.\n- `references\u002Fexample-control-loop.md` — one fully worked loop, annotated component-by-component. An illustration, not a template.\n- `references\u002Fagent-runner-templates.md` — local + CI pi print-mode commands and response capture.\n- `references\u002Fworkflow-template.yml` — recurring loop workflow skeleton with discrete sensor\u002Fcontroller\u002Factuator steps.\n- `references\u002Fprompt-template.md` — embedded prompt structure for the actuator step.\n- `references\u002Fmemory-template.md` — memory\u002Ffeedback file skeleton.\n- `references\u002Fskill-template.md` — skeleton for the generated actuator skill.\n- `references\u002Fresponse-template.md` — examples for how the agent should format its final response (the PR body).\n- `references\u002Fexample-skill.md` — a concrete example of a well-formed task skill.\n- `references\u002Fagent-iteration.ts` — helper for `\u002Fiterate` support (PR footer marker + iteration prompt building).\n","# Design Control Loop\n\nUse 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**.\n\nYour 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.\n\n## The mental model\n\nBorrow 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:\n\n- **Set point** — the desired end state for some property of the codebase.\n- **Sensor** — measures the current state, producing the gap to the set point.\n- **Controller** — decides the next small, low-risk change from that measurement.\n- **Actuator** — a pi coding agent using a repo-local skill that applies the change and opens a PR.\n- The result feeds back into the next run. A human stays *on* the loop to steer it.\n\nRead `references\u002Fcontrol-loop-taxonomy.md` and walk the user through these concepts before designing anything. For one fully worked example, see `references\u002Fexample-control-loop.md` — treat it as an illustration, not a blueprint.\n\n## How to run this skill\n\n- **Read the repo before you ask** (Phase A). Come to the interview with proposals, not a blank form.\n- **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.\n- **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.\n- **Capture the agreed design in writing** before building, so the user can correct it cheaply.\n\n## Outputs\n\nCreate or update these in the target repo, tailored to the agreed design:\n\n- The **sensor** and **controller** as version-controlled commands\u002Fscripts the user can run locally.\n- A project-local actuator skill at the repo's established skill location (`.pi\u002Fskills\u002F\u003Cskill-name>\u002FSKILL.md`, `.agents\u002Fskills\u002F\u003Cskill-name>\u002FSKILL.md`, or another documented `skills\u002F` convention).\n- The recurring **workflow** that runs the loop and opens a PR (GitHub Actions by default; whatever CI the repo uses).\n- A **memory\u002Ffeedback file** that carries standing feedback between runs.\n- Optionally, a **dampener** (regression gate) that keeps the problem from getting worse while the loop improves it.\n\n## Workflow\n\n### Phase A — Understand the system\n\n**Read the following references:** `references\u002Fexample-control-loop.md`.\n\nRead before asking setup questions:\n\n- Existing CI: `.github\u002Fworkflows\u002F*.yml`, `.github\u002Factions\u002F**`, or the repo's non-GitHub CI config — runner, checkout, dependency install, cache, and PR conventions.\n- Package manager files (`package.json`, `bun.lock`, `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, …).\n- Existing validation scripts: typecheck, lint, test, quality, format, and package-scoped commands.\n- Existing project skills (`.pi\u002Fskills`, `.agents\u002Fskills`, `skills\u002F`) and any existing agent loops (workflows, `agent-memory`, where glue scripts live) to mirror conventions instead of inventing new ones.\n- The static-analysis, linting, codegen, and test tooling already in the repo — these are the most likely raw material for a sensor.\n- Discover packages, services, and repo purpose at a high level.\n\nCompletion 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\u002Fservices\u002Fapplications it contains at a high level.\n\n### Phase B — Design the loop with the user\n\n**Read the following references:** `references\u002Fcontrol-loop-taxonomy.md`, `references\u002Fexample-control-loop.md`, `references\u002Fagent-runner-templates.md`.\n\nThis 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.\n\n1. **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\u002Fpackages the loop may change, and which it may only read.\n\n2. **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\u002FAST 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.\n\n3. **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 (a pi 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.\n\n4. **Actuator.** A pi coding agent plus a repo-local skill applies the change.\n   - **Pi setup.** For interactive work in this repository, prefer the `agent` tool when it is available; it already spawns an isolated pi child and returns structured output. For scripts or CI without a parent pi session, use pi's configured provider\u002Fmodel and credentials, or explicit `--provider`, `--model`, and `--api-key` options with `-p`. See `references\u002Fagent-runner-templates.md` for both shapes.\n   - **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).\n   - **Validation.** Decide which commands must pass before the agent commits (propose these from Phase A and confirm).\n\n5. **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.\n\nCompletion criterion: a short written design naming the set point, sensor, controller, actuator (pi command + skill + validation), and disturbances\u002Fdampener — with each component something the user can run locally.\n\n### Phase C — Build the actuator skill\n\n**Read the following references:** `references\u002Fskill-template.md`, `references\u002Fexample-skill.md`, `references\u002Fresponse-template.md`.\n\nWrite 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.\n\n- Put ordered behavior in `SKILL.md` as steps with checkable completion criteria; move long templates and examples into sibling reference files.\n- Encode the golden patterns from Phase B4 so the agent follows established conventions.\n- Keep one source of truth for each rule; do not repeat the same guidance in the skill, the prompt, and the memory file.\n- Include a response template (e.g. `references\u002Fresponse-template.md`) defining how the agent formats its final output, which becomes the PR body. Instruct the skill to read and follow it.\n- Use `references\u002Fskill-template.md` as the skeleton and `references\u002Fexample-skill.md` as a concrete example. See https:\u002F\u002Fagentskills.io\u002Fspecification for the skill spec and ensure the result is discoverable by pi.\n\n**IMPORTANT:** put the skill in the target repo's established project skill location. For pi, `.pi\u002Fskills\u002F\u003Cskill-name>\u002FSKILL.md` or `.agents\u002Fskills\u002F\u003Cskill-name>\u002FSKILL.md` are standard; a repository package may instead use its declared `skills\u002F` directory. Keep the frontmatter name lowercase and hyphenated.\n\nCompletion criterion: the skill explains the job clearly enough that a pi agent can do it unattended, including how to format its final response.\n\n### Phase D — Make each component runnable locally\n\n**Read the following references:** `references\u002Fagent-runner-templates.md`.\n\nBefore 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:\n\n- Run the **sensor** standalone and confirm it produces a stable, usable measurement.\n- Run the **controller** on real sensor output and confirm it selects a sensible next increment.\n- Run the **actuator** locally through the `agent` tool when working inside pi, or through pi's print mode when testing the external\u002FCI path. Confirm it makes the change and passes validation.\n\nOnly 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.\n\nCompletion criterion: the user can run sensor, controller, and actuator locally and independently.\n\n### Phase E — Wire the loop into CI\n\n**Read the following references:** `references\u002Fworkflow-template.yml`, `references\u002Fprompt-template.md`, `references\u002Fagent-runner-templates.md`.\n\nAssemble the components into a recurring job. GitHub Actions is the default because it already has the code, the secrets, version control, and PR conventions — but use whatever CI the repo uses.\n\n- 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 pi agent both selects and changes — collapse them into a single step; do not invent separation the design does not have.)\n- Reusable logic can live in a custom composite action.\n- Decide the **cadence** (daily, weekdays, weekly, monthly, manual-only, or custom cron) based on task risk and review burden.\n- Interpolate the memory file (Phase F) into the actuator's context.\n- Use `references\u002Fworkflow-template.yml` as the base and `references\u002Fprompt-template.md` for the embedded prompt. Use the pi print-mode run and response-capture steps from `references\u002Fagent-runner-templates.md`.\n\nCompletion criterion: the workflow can run from `workflow_dispatch` without relying on files that do not exist.\n\n### Phase F — Put a human on the loop\n\n**Read the following references:** `references\u002Fmemory-template.md`, `references\u002Fagent-iteration.ts`.\n\nA scheduled loop drifts without steering. Give the human two channels, both of which should change future behavior, not just the current PR:\n\n- **Memory\u002Ffeedback file.** A version-controlled markdown file (e.g. `.github\u002Fagent-memory\u002F\u003Ctask-slug>.md`) loaded deterministically into the actuator's context **after the controller** on every run. Use `references\u002Fmemory-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.\n- **`\u002Fiterate` 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 `\u002Fiterate`, the matching workflow loads the PR context (diff, comments) and the feedback, and the pi agent updates its memory and the PR. Install `references\u002Fagent-iteration.ts` (modes: `footer` and `prompt`) where the repo keeps CI scripts.\n\nFrame this for the user as **how you tune the controller and skill over time** — the loop gets better because a human keeps correcting it.\n\nCompletion criterion: standing feedback survives between runs, and `\u002Fiterate` (if enabled) updates the existing PR.\n\n### Phase G — Flow control\n\n**Read the following references:** `references\u002Fworkflow-template.yml`.\n\nBound work-in-progress so the loop never produces PRs faster than they can be reviewed. **Recommended default: one open PR per loop.**\n\n- 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.\n- Decide PR metadata: label name, PR title prefix, branch prefix.\n\nWithout this, a daily loop can stack up duplicate or conflicting PRs while no one is reviewing it. Completion criterion: scheduled runs no-op when the open-PR bound for this loop is already met.\n\n### Phase H — Validate, dry-run, and iterate faster\n\n**Read the following references:** `references\u002Fworkflow-template.yml`.\n\n**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.\n\n**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.\n\n**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.\n\nCompletion criterion: the workflow YAML parses, all referenced files exist, and the loop has produced at least one reviewed PR.\n\n## Reference Files\n\nEach phase above names the references relevant to it — read each one when you reach that phase. Full index:\n\n- `references\u002Fcontrol-loop-taxonomy.md` — the control-loop components and the design questions to ask; read this first and use it to teach the user.\n- `references\u002Fexample-control-loop.md` — one fully worked loop, annotated component-by-component. An illustration, not a template.\n- `references\u002Fagent-runner-templates.md` — local + CI pi print-mode commands and response capture.\n- `references\u002Fworkflow-template.yml` — recurring loop workflow skeleton with discrete sensor\u002Fcontroller\u002Factuator steps.\n- `references\u002Fprompt-template.md` — embedded prompt structure for the actuator step.\n- `references\u002Fmemory-template.md` — memory\u002Ffeedback file skeleton.\n- `references\u002Fskill-template.md` — skeleton for the generated actuator skill.\n- `references\u002Fresponse-template.md` — examples for how the agent should format its final response (the PR body).\n- `references\u002Fexample-skill.md` — a concrete example of a well-formed task skill.\n- `references\u002Fagent-iteration.ts` — helper for `\u002Fiterate` support (PR footer marker + iteration prompt building).\n",{"name":5,"description":7},"main","9a4f7fb9aabf902e3b3ff8f4b88c3a8517378d87","pi-extensions\u002Fskills\u002Fdesign-control-loop","https:\u002F\u002Fgithub.com\u002Fkasuboski\u002Fagents.nix","https:\u002F\u002Fgithub.com\u002Fkasuboski","www.joshkasuboski.com","2026-11-13 01:33:20",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add kasuboski\u002Fagents.nix --skill design-control-loop",{"tool":38,"command":39},"bunx","bunx skills add kasuboski\u002Fagents.nix --skill design-control-loop",{"tool":41,"command":42},"pnpm","pnpm dlx skills add kasuboski\u002Fagents.nix --skill design-control-loop","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fkasuboski\u002Fagents.nix\u002Fblob\u002Fmain\u002Fpi-extensions\u002Fskills\u002Fdesign-control-loop\u002FSKILL.md",true,[46,50,56,62,66,70,74,78,82,86,90,94],{"path":47,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":16},"LICENSE","许可证",1067,{"path":51,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":54,"sourceHtmlUrl":55},"README.md","REFERENCE","参考文档",784,"https:\u002F\u002Fgithub.com\u002Fkasuboski\u002Fagents.nix\u002Fblob\u002Fmain\u002Fpi-extensions\u002Fskills\u002Fdesign-control-loop\u002FREADME.md",{"path":57,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":60,"sourceHtmlUrl":61},"references\u002Fagent-iteration.ts","SCRIPT","脚本",5889,"https:\u002F\u002Fgithub.com\u002Fkasuboski\u002Fagents.nix\u002Fblob\u002Fmain\u002Fpi-extensions\u002Fskills\u002Fdesign-control-loop\u002Freferences\u002Fagent-iteration.ts",{"path":63,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":64,"sourceHtmlUrl":65},"references\u002Fagent-runner-templates.md",3749,"https:\u002F\u002Fgithub.com\u002Fkasuboski\u002Fagents.nix\u002Fblob\u002Fmain\u002Fpi-extensions\u002Fskills\u002Fdesign-control-loop\u002Freferences\u002Fagent-runner-templates.md",{"path":67,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":68,"sourceHtmlUrl":69},"references\u002Fcontrol-loop-taxonomy.md",5578,"https:\u002F\u002Fgithub.com\u002Fkasuboski\u002Fagents.nix\u002Fblob\u002Fmain\u002Fpi-extensions\u002Fskills\u002Fdesign-control-loop\u002Freferences\u002Fcontrol-loop-taxonomy.md",{"path":71,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":72,"sourceHtmlUrl":73},"references\u002Fexample-control-loop.md",4224,"https:\u002F\u002Fgithub.com\u002Fkasuboski\u002Fagents.nix\u002Fblob\u002Fmain\u002Fpi-extensions\u002Fskills\u002Fdesign-control-loop\u002Freferences\u002Fexample-control-loop.md",{"path":75,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":76,"sourceHtmlUrl":77},"references\u002Fexample-skill.md",7461,"https:\u002F\u002Fgithub.com\u002Fkasuboski\u002Fagents.nix\u002Fblob\u002Fmain\u002Fpi-extensions\u002Fskills\u002Fdesign-control-loop\u002Freferences\u002Fexample-skill.md",{"path":79,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":80,"sourceHtmlUrl":81},"references\u002Fmemory-template.md",456,"https:\u002F\u002Fgithub.com\u002Fkasuboski\u002Fagents.nix\u002Fblob\u002Fmain\u002Fpi-extensions\u002Fskills\u002Fdesign-control-loop\u002Freferences\u002Fmemory-template.md",{"path":83,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":84,"sourceHtmlUrl":85},"references\u002Fprompt-template.md",1521,"https:\u002F\u002Fgithub.com\u002Fkasuboski\u002Fagents.nix\u002Fblob\u002Fmain\u002Fpi-extensions\u002Fskills\u002Fdesign-control-loop\u002Freferences\u002Fprompt-template.md",{"path":87,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":88,"sourceHtmlUrl":89},"references\u002Fresponse-template.md",2441,"https:\u002F\u002Fgithub.com\u002Fkasuboski\u002Fagents.nix\u002Fblob\u002Fmain\u002Fpi-extensions\u002Fskills\u002Fdesign-control-loop\u002Freferences\u002Fresponse-template.md",{"path":91,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":92,"sourceHtmlUrl":93},"references\u002Fskill-template.md",1847,"https:\u002F\u002Fgithub.com\u002Fkasuboski\u002Fagents.nix\u002Fblob\u002Fmain\u002Fpi-extensions\u002Fskills\u002Fdesign-control-loop\u002Freferences\u002Fskill-template.md",{"path":95,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":96,"sourceHtmlUrl":97},"references\u002Fworkflow-template.yml",10912,"https:\u002F\u002Fgithub.com\u002Fkasuboski\u002Fagents.nix\u002Fblob\u002Fmain\u002Fpi-extensions\u002Fskills\u002Fdesign-control-loop\u002Freferences\u002Fworkflow-template.yml",[99,107,115],{"skillNo":100,"name":101,"nameZh":6,"description":102,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":103,"sourceHtmlUrl":104,"categories":105,"keywords":106,"publishedAt":20},"01M75323XDYF0SQCYR91D29SND","leaving-pr-comments","Use whenever leaving comments on GitHub.","https:\u002F\u002Fgithub.com\u002Fkasuboski\u002Fagents.nix\u002Fblob\u002Fmain\u002Fpi-extensions\u002Fskills\u002Fleaving-pr-comments\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fkasuboski\u002Fagents.nix\u002Fblob\u002Fmain\u002Fpi-extensions\u002Fskills\u002Fleaving-pr-comments\u002FSKILL.md",[],[],{"skillNo":108,"name":109,"nameZh":6,"description":110,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":111,"sourceHtmlUrl":112,"categories":113,"keywords":114,"publishedAt":20},"01M7531CFJES7AE5QPFYZQ50N6","diagram-design","Create branded architecture, architecture delta, IT current-state, flowchart, sequence, state machine, ER\u002Fdata model, timeline, swimlane, quadrant, radar\u002Fspider, polar chart (polar\u002Fradial lollipop), loop\u002Fflywheel, nested, tree, org chart, layer stack, exploded axonometric, axonometric plan, Venn, pyramid\u002Ffunnel, treemap and marimekko, heatmap, bar and dumbbell, waterfall, line (slopegraph, ridgeline, streamgraph, bump), Gantt and scatter charts (bubble, beeswarm), high-level, process, medallion, data flow, DP integration, DP security matrix, Sankey, fishbone, Wardley map, kanban, user journey, deployment, dependency graph, UML class, story map, or database schema diagrams as HTML\u002FSVG\u002FPNG, with .drawio, Mermaid, and .excalidraw import, plus lifecycle phase maps, block decomposition trees, and onboarding guidance.","https:\u002F\u002Fgithub.com\u002Fkasuboski\u002Fagents.nix\u002Fblob\u002Fmain\u002Fpi-extensions\u002Fskills\u002Fdiagram-design\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fkasuboski\u002Fagents.nix\u002Fblob\u002Fmain\u002Fpi-extensions\u002Fskills\u002Fdiagram-design\u002FSKILL.md",[],[],{"skillNo":116,"name":117,"nameZh":6,"description":118,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":119,"sourceHtmlUrl":120,"categories":121,"keywords":122,"publishedAt":20},"01M753105DSWP76GJBJ49SVPTQ","babysit-pr","Monitor a pull request through review and CI. Use when the user asks to monitor, watch, or babysit a PR.","https:\u002F\u002Fgithub.com\u002Fkasuboski\u002Fagents.nix\u002Fblob\u002Fmain\u002Fpi-extensions\u002Fskills\u002Fbabysit-pr\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fkasuboski\u002Fagents.nix\u002Fblob\u002Fmain\u002Fpi-extensions\u002Fskills\u002Fbabysit-pr\u002FSKILL.md",[],[]]