@hybridlabor-api/aos 4.12.1 → 4.13.1

package/skills/global_config/design-control-loop/references/agent-runner-templates.md

@@ -0,0 +1,157 @@
+# Agent Runner Templates
+
+Use one of these inside the workflow's agent run step. Broad permission modes are appropriate only on trusted, isolated runners.
+
+Each agent outputs differently, so response extraction varies. The goal is to get the agent's final formatted response into `/tmp/pr-body.md` for the PR body.
+
+**Run the actuator locally before wiring CI.** Every command below is a headless CLI invocation — export the agent's secret and set `PROMPT`, then run it in your shell against a controller-selected target to confirm the actuator works before it goes into a workflow:
+
+```bash
+export ANTHROPIC_API_KEY=...         # or the agent's secret
+PROMPT="$(cat /tmp/agent-prompt.md)" # your assembled actuator prompt
+# then run the agent command for your chosen agent, below
+```
+
+---
+
+## Claude Code
+
+Secret: `ANTHROPIC_API_KEY`.
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: 24
+- run: npm install -g @anthropic-ai/claude-code
+- name: Run Claude Code
+  env:
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+  run: |
+    claude -p "$PROMPT" \
+      --permission-mode bypassPermissions \
+      --output-format stream-json \
+      --verbose \
+      2>&1 | tee /tmp/agent-output.txt
+```
+
+Use `--max-turns` or `--max-budget-usd` when the repo needs spend guards.
+
+**Response extraction:** Claude Code with `--output-format stream-json` outputs JSON lines. Extract the final assistant message:
+
+```yaml
+- name: Extract PR body
+  run: |
+    # Extract the last assistant text message from stream-json output
+    cat /tmp/agent-output.txt \
+      | grep '^{' \
+      | jq -s '[.[] | select(.type == "assistant" and .message.content)] | last | .message.content[] | select(.type == "text") | .text' -r \
+      > /tmp/pr-body.md
+```
+
+---
+
+## Codex CLI
+
+Secret: `OPENAI_API_KEY`.
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: 24
+- run: npm install -g @openai/codex
+- name: Login Codex
+  env:
+    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+  run: printenv OPENAI_API_KEY | codex login --with-api-key
+- name: Run Codex
+  run: |
+    codex exec "$PROMPT" \
+      --cd "$GITHUB_WORKSPACE" \
+      --ask-for-approval never \
+      --sandbox danger-full-access \
+      --json \
+      --output-last-message /tmp/pr-body.md \
+      2>&1 | tee /tmp/agent-output.txt
+```
+
+**Response extraction:** Codex has built-in support via `--output-last-message /tmp/pr-body.md`. No additional extraction needed.
+
+---
+
+## OpenCode
+
+Secret: provider-specific, commonly `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`.
+
+```yaml
+- uses: oven-sh/setup-bun@v2
+- run: bun install -g opencode-ai
+- name: Run OpenCode
+  env:
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+  run: |
+    opencode run "$PROMPT" \
+      --dir "$GITHUB_WORKSPACE" \
+      --model anthropic/claude-sonnet-4-5 \
+      --format json \
+      --dangerously-skip-permissions \
+      2>&1 | tee /tmp/agent-output.txt
+```
+
+Change `--model` and env secrets together, for example to an `openai/...` model with `OPENAI_API_KEY`.
+
+**Response extraction:** OpenCode with `--format json` outputs structured JSON. Extract the final message:
+
+```yaml
+- name: Extract PR body
+  run: |
+    # Extract the last assistant message from OpenCode JSON output
+    cat /tmp/agent-output.txt \
+      | jq -r '.messages | map(select(.role == "assistant")) | last | .content' \
+      > /tmp/pr-body.md
+```
+
+---
+
+## CodeLayer
+
+Secret: usually `ANTHROPIC_API_KEY` for Anthropic-backed runs.
+
+```yaml
+- uses: oven-sh/setup-bun@v2
+- name: Run CodeLayer
+  env:
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    FORCE_COLOR: "3"
+  run: |
+    bunx @humanlayer/cli@latest codelayer \
+      --provider anthropic \
+      --model claude-opus-4-8 \
+      --thinking high \
+      --prompt "$PROMPT" \
+      2>&1 | tee /tmp/agent-output.txt
+```
+
+Use this when the repo already depends on HumanLayer/CodeLayer conventions or wants CodeLayer's PR-oriented behavior.
+
+**Response extraction:** CodeLayer outputs plain text with ANSI colors. Use a parser script or strip formatting:
+
+```yaml
+- name: Extract PR body
+  run: |
+    # If you have a codelayer-output parser script:
+    # bun ci-scripts/codelayer-output.ts < /tmp/agent-output.txt > /tmp/pr-body.md
+    
+    # Otherwise, strip ANSI codes and use the raw output:
+    cat /tmp/agent-output.txt | sed 's/\x1b\[[0-9;]*m//g' > /tmp/pr-body.md
+```
+
+For cleaner extraction, use a parser script like `ci-scripts/codelayer-output.ts` that extracts just the final response section.
+
+---
+
+## Notes
+
+- All agents should tee output to `/tmp/agent-output.txt` for artifact upload and debugging.
+- The extracted response goes to `/tmp/pr-body.md` which is used by the PR creation step.
+- If extraction fails, the workflow should fall back gracefully (e.g., use raw output or a placeholder message).

package/skills/global_config/design-control-loop/references/control-loop-taxonomy.md

@@ -0,0 +1,75 @@
+# Control Loop Taxonomy
+
+Use this to explain an agent loop as a control system before designing one, so it is observable, bounded, and reviewable instead of "an agent runs sometimes."
+
+Every example below is an **illustration to spark discussion**, not a recommendation. The right sensor, controller, and actuator depend entirely on the user's codebase and the tooling they already use — discover that in the interview, don't assume it.
+
+## The four components
+
+Foreground these four (plus the set point they serve). Keep the rest of the vocabulary in your back pocket.
+
+- **Set point** — the desired end state for some property of the codebase. An invariant ("no module imports across these boundaries"), a threshold ("coverage ≥ 80% in `core`"), or a direction ("fewer occurrences each run").
+
+- **Sensor** — how the loop measures the current state and the gap to the set point. It can be almost anything that reports on the codebase: a static-analysis or lint tool, a structural/AST search, a type checker, a test suite, a telemetry or error query, a code-search query, a custom script — or an agent that inspects the code. Trade-offs to talk through with the user (not rules to impose): how stable and repeatable the measurement is, how much it costs to run, and whether it can be silently disabled. Aim for output a controller can act on repeatably.
+
+- **Controller** — how the loop turns the measurement into the next change, sized to stay low-risk and reviewable. It decides *what to do now versus defer*: which target, how many, in what order. It ranges from fully deterministic (a script that sorts findings and picks one) to fully agentic (an agent choosing from natural-language criteria), with data-driven variants in between (e.g. prioritize by where production errors cluster). This is the part you **tune over time** from loop output — start simple.
+
+- **Actuator** — what applies the change: a coding agent (Claude Code, Codex, OpenCode, CodeLayer, …) plus a repo-local skill, running in CI and opening a PR.
+
+- **Disturbance** — anything that changes the system from outside the loop: teammates' commits, dependency updates, generated code, flaky tests, large refactors. The loop has to make progress *despite* these.
+
+## Components can blur
+
+In practice — especially with agents — the lines blur, and that is fine:
+
+- **Sensor + controller fused:** a tool that both reports problems and ranks them by impact is doing both jobs.
+- **Controller + actuator fused:** a single agent prompt that both picks the next target and changes it.
+
+Design the loop the user actually needs; don't manufacture separation that isn't there.
+
+## The fuller picture
+
+You rarely need to name all of this explicitly, but it helps when reasoning about a loop:
+
+```mermaid
+flowchart LR
+  SetPoint[Set point] --> Compare((Compare))
+  Measured[Measured output] --> Compare
+  Compare --> Error[Measured error]
+  Error --> Controller[Controller]
+  Controller --> Actuator[Actuator]
+  Actuator --> System[System / Repository]
+  Disturbance[Disturbance] --> System
+  System --> Output[System output]
+  Output --> Sensor[Sensor]
+  Sensor --> Measured
+```
+
+- **Measured output** — the signal the sensor produces (e.g. a list of findings, a count, a score).
+- **Measured error** — the delta between set point and measured output (e.g. findings over threshold, or new findings vs a baseline).
+- **Controller output** — the chosen operation for this iteration (e.g. "address these N targets in these packages").
+- **System input / output** — the patch/commit/PR the actuator produces, and the resulting repo state plus validation and review.
+
+## Run each component locally first
+
+Whatever the components turn out to be, make each one runnable by hand and standalone before wiring CI: run the sensor and read its output, run the controller against that output, run the actuator on a selected target. The workflow should only orchestrate pieces the user can already run locally — this keeps the loop debuggable.
+
+## Extra loop parts to consider
+
+- **Flow control (PR bounding)** — stop scheduled runs when an open PR for this loop already exists, so the loop doesn't outrun review.
+- **Dampener (regression gate)** — a check (often on PRs / pushes to main) that compares the sensor's output against a baseline so the problem can't get *worse* while the loop incrementally makes it better. Offer it; not every loop needs one.
+- **Scope gate** — restrict the actuator to safe directories; exclude generated files, vendored code, or high-risk packages unless explicitly selected.
+- **Batch size** — cap each run by finding/file/package count to keep diffs reviewable.
+- **Memory** — durable reviewer feedback and known false positives that steer future runs (not one-off logs).
+
+## Design questions for the interview
+
+1. What property are we driving, and what is the set point?
+2. What in this repo (or its tooling) can measure the gap repeatably? What are the trade-offs of each option?
+3. What counts as an error worth acting on this run, and how big is one reviewable increment?
+4. How should the controller prioritize and select targets — and how will we tune that over time?
+5. Which coding agent is the actuator, what credentials does it need, and what golden patterns should it follow?
+6. What validation proves the actuator improved the system?
+7. What disturbances should the loop ignore, tolerate, or dampen — and do we want a regression gate?
+8. What memory should carry forward between runs?
+9. How do we run each component locally before it goes into CI?

package/skills/global_config/design-control-loop/references/example-control-loop.md

@@ -0,0 +1,57 @@
+# Example Control Loop: React Doctor
+
+One fully worked loop, to make the taxonomy concrete. **This is an illustration, not a template.** A real loop from a production monorepo, it drives React code quality in a single app. Your loop's set point, sensor, controller, and actuator will look different — copy the *shape*, not the specifics.
+
+It is a useful example because the sensor and controller come almost entirely from an existing, configurable tool, so the whole loop is small.
+
+## Set point
+
+`apps/riptide-ui` stays free of high-impact React issues (lint, accessibility, correctness, architecture). A direction more than a fixed threshold: each run leaves the app a little healthier.
+
+## Sensor — `react-doctor` + `doctor.config.ts`
+
+The [`react-doctor`](https://github.com/millionco/react-doctor) CLI scans the app and reports prioritized issues; `doctor.config.ts` configures which rules run and which paths/rules are ignored. It runs locally exactly as it does in CI:
+
+```bash
+bunx react-doctor --project '@codelayer/riptide-ui' --diff false --yes
+```
+
+Chosen because it is repeatable, configurable, and lives outside the editor/lint config so a stray inline comment can't quietly switch it off — a trade-off that mattered *for this team*, not a requirement of all sensors.
+
+## Controller — fused with the sensor
+
+There is no separate controller: `react-doctor` returns "the top 3 rules by impact," and the loop's policy is "fix up to 5 issues from those top 3 rules this run." That selection logic lives in the actuator's prompt. This is the **sensor + controller blur** — one tool plus a small policy does both jobs.
+
+## Actuator — CodeLayer + a repo-local skill
+
+A CodeLayer agent runs with the repo's `react-doctor` skill. Its per-issue loop gives the agent three honest options — **fix**, **ignore** (add to `doctor.config.ts` with a reason), or **skip** (leave for a human) — and validates each change before committing it separately:
+
+```bash
+bun run typecheck
+bun run quality
+bunx react-doctor --project '@codelayer/riptide-ui' --staged   # no new issues in staged files
+```
+
+## Disturbances + dampener
+
+**Disturbance:** teammates ship React code continuously while the loop runs.
+
+**Dampener:** a second workflow (`react-doctor.yml`) runs on every pull request and on pushes to `main`. It diffs against the merge base and comments on only the *newly introduced* issues. It is **advisory by default** (never red-Xes a teammate's PR), with a documented path to graduate to blocking once the team trusts the signal. This keeps the problem from getting worse while the scheduled loop chips away at it.
+
+## The loop — `agent-react-doctor.yml`
+
+A scheduled workflow (daily, plus manual dispatch and `/iterate`) runs the loop and opens a PR whose body is the agent's final message. Because the sensor, controller, and actuator are fused into one agent step here, the workflow does **not** have three separate steps — it collapses them, matching the design. A loop with a deterministic, standalone sensor and controller would instead have discrete steps.
+
+## Human on the loop
+
+- `.github/agent-memory/react-doctor.md` is loaded into the agent every run — standing feedback like "always use the `no-use-effect` skill for `useEffect` fixes" and "don't globally ignore a rule when only specific files need an exemption."
+- Maintainers comment `/iterate` on the PR; a hidden marker in the PR body routes the comment to the workflow that created it, which loads the PR context and feedback and updates the memory file and the PR. Deterministic glue lives in `ci-scripts/` (`agent-iteration.ts`, `codelayer-output.ts`).
+
+## Flow control
+
+Every PR is labeled `agent-react-doctor`. Scheduled runs no-op when an open PR with that label already exists, so there is at most one open PR per loop; manual dispatch bypasses the gate.
+
+## What to take from this
+
+- **Reusable shape:** set point → sensor → controller → actuator under disturbances, plus a dampener, a memory file, `/iterate` steering, and one-PR flow control.
+- **Not reusable:** `react-doctor`, the bun/CodeLayer commands, the "top 3 rules / 5 fixes" policy, the `riptide-ui` scope. Those are tailored to this repo — yours come from your interview.

package/skills/global_config/design-control-loop/references/example-skill.md

@@ -0,0 +1,171 @@
+---
+name: narrow-react-prop-types
+description: narrow React component prop types to match live code paths
+---
+
+# Narrow React Prop Types
+
+Use this skill when a React component's props have been widened for stories, mocks, tests, or demos and now express states the live application does not enter.
+
+The goal is to make component types describe the real live-code-path contract, then require stories/tests/mocks to adapt to that contract instead of weakening it.
+
+## Core Requirements
+
+- Find the actual non-test, non-Storybook call sites before changing types.
+- Treat live code paths as the source of truth for the prop contract.
+- Do not preserve optional props only because they make Storybook, tests, or mock data easier.
+- Keep props optional only when there are non-Storybook, non-test call sites which do not provide them and which have a good reason for not doing so.
+- Types should not enable expressing states which are not observed in non-test, non-Storybook call sites.
+- Types should be as strict as possible so code can be as simple as possible.
+- Prefer deriving and extracting types from existing live-code-path values and APIs where possible.
+
+## Workflow
+
+For an example recurring GitHub Actions workflow that runs this skill through CodeLayer, see `references/agent-narrow-component-props.yml`. Its example agent memory file is `references/narrow-component-props-memory.md`.
+
+### 1. Identify the suspect component
+
+Look for components with these signals:
+
+- Large props interfaces with many optional fields.
+- Optional callback calls such as `onSelect?.(...)` or `onArchive?.(...)`.
+- Fallback state handling such as `items ?? []`, `count ?? 0`, or `handler && ...` around values live code likely always supplies.
+- UI affordances that always render even though their callbacks are optional.
+- Props that look demo-oriented, such as `defaultFoo`, alternate handler shapes, or display toggles not used by live code.
+
+Do not pick a target from a story or test alone. Use stories/tests only as supporting evidence that the type has been widened, not as evidence that a state is real.
+
+### 2. Find every live usage
+
+Search for all imports/usages of the component, exported prop type, and shared child primitives.
+
+Classify call sites by whether they are live code paths or support code:
+
+- Live code paths: app routes, wired components, providers, hooks, production package exports, and shared components used by those paths.
+- Support code: Storybook stories, test files, fixtures, mocks, demo harnesses, and visual-only examples.
+
+Only live code paths should determine what the component API supports.
+
+### 3. Derive the real types from the live code paths
+
+Read the live call sites and classify each prop:
+
+- Required: every non-test, non-Storybook call site supplies it.
+- Optional: at least one non-test, non-Storybook call site omits it and that omission is a meaningful runtime state.
+- Removed: no non-test, non-Storybook call site uses it.
+
+Nullability and optionality are different. If live code always passes a prop but the value can be empty, prefer a required nullable prop such as `focusedItem: FocusedItem | null` over `focusedItem?: FocusedItem | null`.
+
+### 4. Tighten the public prop type
+
+Update exported prop types to match only the states observed in live code paths.
+
+The looser and more optional a type is, the more possible states the component has to reason about. Every optional prop creates another branch the component must handle, test, and keep correct. Prefer strict types that prevent impossible states instead of broad types that require defensive render logic.
+
+If the component always renders an interactive affordance, require the handler that makes it work. Do not allow inert states like a visible menu item that calls `onRename?.(...)`.
+
+### 5. Derive and extract types where possible
+
+Prefer deriving types from the live APIs instead of restating them manually:
+
+- `Parameters<typeof fn>[0]` for function argument types.
+- `ReturnType<typeof fn>` for return types.
+- `Extract<Union, Shape>` for narrowing a union to a real variant.
+- `React.Dispatch<React.SetStateAction<T>>` for React state setters instead of approximating them as `(value: T) => void`.
+
+Prefer explicit state type parameters when inference would widen or obscure the intended state shape:
+
+```ts
+const [dialogState, setDialogState] = useState<DialogState>({
+  id: null,
+  isOpen: false,
+})
+```
+
+Avoid relying on implicit `useState(...)` inference when it produces broad nullable object shapes, string literal widening, or callback types that later need hand-written approximations.
+
+### 6. Tighten internal child props too
+
+Do not stop at the exported component if it passes broad props into child primitives.
+
+If row/menu/button child components receive optional handlers only because the parent props were broad, tighten those internal props too. Replace optional calls like this:
+
+```ts
+onRename?.(id, name)
+```
+
+with required calls:
+
+```ts
+onRename(id, name)
+```
+
+### 7. Remove fallback logic for unsupported states
+
+Once props are required, remove defensive fallbacks that only existed for widened types.
+
+Examples:
+
+```ts
+new Set(expandedIds ?? defaultExpandedIds ?? [])
+```
+
+should become:
+
+```ts
+new Set(expandedIds)
+```
+
+```ts
+items && items.length > 0
+```
+
+should become:
+
+```ts
+items.length > 0
+```
+
+### 8. Update all variants that share the prop type
+
+If multiple components share the broad prop type, update them together so they all enforce the same live-code-path contract.
+
+### 9. Let tests and stories adapt to live code
+
+If a story or test breaks after narrowing props, fix it by providing realistic handlers and state. Do not make live-code-path props optional again to reduce test setup.
+
+If the story/test setup feels verbose, create a test helper or fixture that satisfies the strict live-code-path contract. Keep the helper in support code; do not weaken the component API.
+
+### 10. Validate the change
+
+Run package-level typechecks for the changed package and each live app/package that consumes the changed component.
+
+Use repository-specific validation commands when available. In this monorepo, prefer:
+
+```bash
+bun --bun run typecheck --filter <package>
+```
+
+### 11. Read the response template and format your final asnwer
+Read the response template at `references/final-response-template.md` and format your answer accordingly.
+
+## Review Checklist
+
+- The changed prop type was derived from non-test, non-Storybook call sites.
+- Optional callbacks are removed for always-rendered interactions.
+- Rendered menu items and buttons cannot be inert because of missing handlers.
+- Removed props are not used by live code paths.
+- Nullability is preserved only for real states, such as no current focus.
+- Types are derived or extracted where possible rather than manually duplicated.
+- `useState<T>(...)` is used where inference would otherwise widen or obscure the intended state.
+- Shared variants compile against the same narrowed contract.
+- Typecheck passes for the shared package and consuming live app/package.
+
+## Anti-Patterns to Avoid
+
+- Making callbacks optional so stories can omit them.
+- Rendering a menu item that calls `onAction?.(...)`.
+- Adding `default*` props for Storybook when live code is controlled.
+- Using `?? []` or `?? 0` to hide missing required live state.
+- Accepting multiple API shapes when live code only uses one.
+- Treating pure components as mock components with relaxed contracts.

package/skills/global_config/design-control-loop/references/memory-template.md

@@ -0,0 +1,7 @@
+# Agent Memory: <Task Title>
+
+Standing feedback for future `Agent: <Task Title>` runs. This is the human-on-the-loop steering channel: it is loaded into the actuator on every run (after the controller), so edits here change future behavior, not just one PR. Keep durable guidance only — not one-off instructions or single-run logs.
+
+## Guidance
+
+- <Permanent scope constraint, false-positive area, or reviewer preference that should change future runs.>

package/skills/global_config/design-control-loop/references/prompt-template.md

@@ -0,0 +1,58 @@
+# Context
+
+You are <task summary> in this repository. Begin by using the `<skill-name>` skill.
+
+# Scope
+
+Focus only on `<primary path or package>`.
+
+You may inspect `<secondary path>` only when it is necessary to understand or validate the primary change.
+
+# Instructions
+
+1. <Work the target(s) the controller selected (see "Selected work" if present); otherwise find high-confidence targets yourself.>
+2. <Keep this to one small, reviewable increment.>
+3. <Use the real source of truth, not support-only examples.>
+4. <Avoid adjacent cleanup that belongs to another workflow.>
+5. Validate with the commands below.
+6. Commit and push your changes.
+
+## Validation Commands
+
+```bash
+<validation command 1>
+<validation command 2>
+```
+
+## Important Rules
+
+- <Rule that prevents the most likely wrong change.>
+- <Rule that keeps scope narrow.>
+- Do not run long integration tests unless explicitly requested.
+- You are running in a sandbox or CI runner environment. Do not stop and ask for feedback from the user or request approvals.
+
+## Finishing Up
+
+When you are finished:
+
+1. Make sure the validation commands pass.
+2. Commit and push your changes.
+3. Answer with the output format below.
+
+## Output Format
+
+Format your final answer as GitHub-flavored markdown:
+
+```markdown
+## <Task Title> Complete
+
+### Changes Made
+- [file/component]: [what changed and why]
+
+### Source Of Truth Checked
+- [path]: [why it supports the change]
+
+### Validation
+- [x] <validation command 1> passed
+- [x] <validation command 2> passed
+```

package/skills/global_config/design-control-loop/references/response-template.md

@@ -0,0 +1,103 @@
+# Response Template
+
+This template defines how the CI agent should format its final response, which becomes the body of the GitHub PR.
+
+Customize this template based on the task type and what information reviewers need.
+
+---
+
+## Example: Fix/Migration Task
+
+```markdown
+Finished processing N `<tool-name>` issues:
+  - `resolved`: X
+  - `ignored`: Y
+  - `skipped`: Z
+
+Details below:
+
+---
+
+## Issue 1
+- **File(s)**: `path/to/file.ts`
+- **Summary**: [concise description of the issue]
+- **Resolution**: **FIXED**. [concise description of the fix]
+- **Risk**: [HIGH / medium / low]
+- **Manual verification** (for HIGH/medium risk): [steps to test the changes]
+
+## Issue 2
+- **File(s)**: `path/to/other.ts`
+- **Summary**: [...]
+- **Resolution**: **IGNORED**. [why the rule was added to ignore list]
+
+## Issue 3
+- **File(s)**: `path/to/another.ts`
+- **Summary**: [...]
+- **Resolution**: **SKIPPED**. [why this needs human attention]
+```
+
+---
+
+## Example: Generation Task
+
+```markdown
+Generated N new <artifact type>:
+
+| File | Description | Status |
+|------|-------------|--------|
+| `path/to/new-file.ts` | [what was generated] | Created |
+| `path/to/updated.ts` | [what changed] | Updated |
+
+## Validation
+- Typecheck: PASS
+- Tests: PASS
+- Lint: PASS
+
+## Notes
+[Any context reviewers should know]
+```
+
+---
+
+## Example: Refactor Task
+
+```markdown
+Refactored N components/modules:
+
+## Changes
+
+### `path/to/file.ts`
+- **Before**: [brief description of old pattern]
+- **After**: [brief description of new pattern]
+- **Risk**: low
+
+### `path/to/other.ts`
+- **Before**: [...]
+- **After**: [...]
+- **Risk**: medium
+- **Verify**: [how to test this change]
+
+## Validation
+- Typecheck: PASS
+- Tests: PASS
+- No behavior changes expected
+```
+
+---
+
+## Template Variables
+
+When writing your response template, you can use these placeholders:
+
+- `<tool-name>` - The CLI tool or process that found issues
+- `<artifact-type>` - What the agent creates (tests, types, docs, etc.)
+- `<task-name>` - The name of the agent task
+- `<date>` - Current date (MM/DD format)
+
+## Guidelines
+
+1. **Lead with summary stats** - Reviewers should know scope immediately
+2. **Group by resolution type** - Fixed, ignored, skipped, or created
+3. **Include risk levels and highlight prominently** - Help reviewers prioritize their review
+4. **Provide verification steps** - For medium/high risk changes
+5. **Keep it scannable and concise** - Use tables, headers, and bullet points.