@hybridlabor-api/aos 4.12.0 → 4.13.0

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. 

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

@@ -0,0 +1,57 @@
+---
+name: <skill-name>
+description: <leading verb> <task> when <trigger>; use <source of truth> instead of <wrong source>
+---
+
+# <Skill Title>
+
+Use this skill when <the user or workflow asks for the repeatable agent task>.
+
+The goal is to <one-sentence invariant the agent should preserve>.
+
+## Core Requirements
+
+- <Rule that identifies the live source of truth.>
+- <Rule that names inputs that must not drive the decision.>
+- <Rule that keeps the change reviewable.>
+- <Rule that defines the validation bar.>
+
+## Workflow
+
+### 1. Find the target
+
+<How to identify candidate files/components/issues.>
+
+Completion criterion: <observable condition that proves the target was selected correctly>.
+
+### 2. Inspect the source of truth
+
+<What to read before editing.>
+
+Completion criterion: <observable condition that proves the agent did enough legwork>.
+
+### 3. Make the smallest safe change
+
+<How to edit without broadening scope. Include multiple steps / workflow if necessary.>
+
+Completion criterion: <observable condition that proves the change matches the source of truth>.
+
+### 4. Validate
+
+Run the narrowest relevant validation first, then the repo-required quality gate.
+
+Completion criterion: validation passes or the final report names the exact blocker.
+
+### 5. Format the response
+
+When running as a CI agent, format your final response according to `references/response-template.md`. This response becomes the PR body.
+
+Completion criterion: the response follows the template structure and includes all required information for reviewers.
+
+## Review Checklist
+
+- The source of truth was inspected before editing.
+- The change does not encode support-code-only states as real behavior.
+- The diff is small enough to review.
+- The validation command passed or the blocker is documented.
+- The final response follows the response template.

package/skills/global_config/design-control-loop/references/workflow-template.yml

@@ -0,0 +1,273 @@
+# Agent <Task Title> - iterated control loop
+#
+# This workflow has two modes:
+# 1. scheduled/manual mode: run one sense -> control -> actuate iteration on a fresh agent
+#    branch and open a PR. When sensor/controller/actuator are fused, collapse them to one step.
+# 2. /iterate mode: when a maintainer comments on an agent-created PR, update that PR
+#    and optionally update .github/agent-memory/<task-slug>.md for future runs.
+#
+# The /iterate path intentionally checks the PR body marker BEFORE checkout/setup so
+# every agent workflow can listen for /iterate while non-matching workflows no-op cheaply.
+
+name: "Agent: <Task Title>"
+
+on:
+  schedule:
+    - cron: "0 13 * * *" # Update me based on user preferences
+  workflow_dispatch:
+  issue_comment:
+    types: [created] # for iteration!
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+
+concurrency:
+  group: agent-<task-slug>
+  cancel-in-progress: true
+
+jobs:
+  agent-task:
+    # Run all non-comment events. For issue comments, only authorized PR comments
+    # starting with /iterate are allowed to reach the marker preflight below.
+    if: |
+      github.event_name != 'issue_comment' ||
+      (
+        github.event.issue.pull_request &&
+        startsWith(github.event.comment.body, '/iterate') &&
+        (github.event.comment.author_association == 'OWNER' ||
+         github.event.comment.author_association == 'MEMBER' ||
+         github.event.comment.author_association == 'COLLABORATOR')
+      )
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check iterate marker to bound work-in-progress
+        id: agent_gate
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          EVENT_NAME: ${{ github.event_name }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          PR_URL: ${{ github.event.issue.pull_request.url }}
+          WORKFLOW_ID: agent-<task-slug>
+          AGENT_LABEL: agent-<task-slug>
+        run: |
+          # Scheduled runs no-op when an open PR already exists for this agent (flow control).
+          if [ "$EVENT_NAME" = "schedule" ] || [ "$EVENT_NAME" = "workflow_call" ]; then
+            EXISTING_PR=$(gh pr list --repo "$GITHUB_REPOSITORY" --state open --label "$AGENT_LABEL" --json number,url --limit 1)
+            if [ "$(echo "$EXISTING_PR" | jq 'length')" -gt 0 ]; then
+              echo "run_agent=false" >> "$GITHUB_OUTPUT"
+              echo "Open PR already exists for $AGENT_LABEL; no-op."
+              exit 0
+            fi
+          fi
+
+          # Manual runs are normal agent runs, so allow the rest of the job.
+          if [ "$EVENT_NAME" != "issue_comment" ]; then
+            echo "run_agent=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # /iterate comments are shared by all recurring agent workflows. The hidden
+          # PR body marker deterministically routes the comment to the workflow that
+          # originally opened the PR. Non-matching workflows exit before checkout/setup.
+          PR_DATA=$(gh api "$PR_URL")
+          BODY=$(echo "$PR_DATA" | jq -r '.body // ""')
+          if grep -Fq "<!-- codelayer-agent:workflow=$WORKFLOW_ID;" <<< "$BODY"; then
+            echo "run_agent=true" >> "$GITHUB_OUTPUT"
+            echo "number=$(echo "$PR_DATA" | jq -r '.number')" >> "$GITHUB_OUTPUT"
+            echo "head_ref=$(echo "$PR_DATA" | jq -r '.head.ref')" >> "$GITHUB_OUTPUT"
+            echo "head_sha=$(echo "$PR_DATA" | jq -r '.head.sha')" >> "$GITHUB_OUTPUT"
+          else
+            echo "run_agent=false" >> "$GITHUB_OUTPUT"
+            echo "PR was not created by $WORKFLOW_ID; no-op."
+          fi
+
+      - uses: actions/checkout@v5
+        if: steps.agent_gate.outputs.run_agent == 'true' && github.event_name != 'issue_comment'
+        with:
+          fetch-depth: 0
+
+      - uses: actions/checkout@v5
+        if: steps.agent_gate.outputs.run_agent == 'true' && github.event_name == 'issue_comment'
+        with:
+          # Iteration updates the existing agent PR branch rather than creating a new one.
+          ref: ${{ steps.agent_gate.outputs.head_ref }}
+          fetch-depth: 0
+
+      - name: Configure git user & branch
+        if: steps.agent_gate.outputs.run_agent == 'true'
+        shell: bash
+        run: |
+          if [ "${{ github.event_name }}" != "issue_comment" ]; then
+            BRANCH="<branch-prefix>/$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
+            echo "BRANCH=$BRANCH" >> "$GITHUB_ENV"
+            git checkout -b "$BRANCH"
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      # NOTE: setup below assumes a bun/Node repo. Replace with this repo's runtime + install.
+      - name: Install bun
+        if: steps.agent_gate.outputs.run_agent == 'true'
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.14
+
+      - name: Install Node.js
+        if: steps.agent_gate.outputs.run_agent == 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: Cache bun dependencies
+        if: steps.agent_gate.outputs.run_agent == 'true'
+        uses: actions/cache@v4
+        with:
+          path: ~/.bun/install/cache
+          key: bun-${{ runner.os }}-${{ hashFiles('**/bun.lock') }}
+          restore-keys: |
+            bun-${{ runner.os }}-
+
+      - name: Install dependencies
+        if: steps.agent_gate.outputs.run_agent == 'true'
+        run: bun install --frozen-lockfile
+
+      # --- Iteration path: a /iterate comment refines the existing PR ---
+      # Iteration is one actuator pass over reviewer feedback, not a fresh sense->control->actuate cycle.
+      - name: Actuator — iterate on feedback
+        if: steps.agent_gate.outputs.run_agent == 'true' && github.event_name == 'issue_comment'
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          FORCE_COLOR: "3"
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          PR_NUMBER: ${{ steps.agent_gate.outputs.number }}
+          COMMENT_BODY: ${{ github.event.comment.body }}
+        run: |
+          set -o pipefail
+          # Build an iteration prompt from the PR body, comments, the /iterate feedback, and memory.
+          # NOTE: update the agent-iteration.ts path to where you installed it (.github/scripts/, ci-scripts/, scripts/).
+          bun .github/scripts/agent-iteration.ts \
+            --command prompt \
+            --workflow agent-<task-slug> \
+            --memory .github/agent-memory/<task-slug>.md \
+            --repo "$GITHUB_REPOSITORY" \
+            --pr-number "$PR_NUMBER" \
+            --comment-body "$COMMENT_BODY" > /tmp/agent-prompt.md
+
+          # NOTE: replace with your agent runner from references/agent-runner-templates.md
+          bunx @humanlayer/cli@latest codelayer \
+            --provider anthropic --model claude-sonnet-4-6 --thinking high \
+            --prompt "$(cat /tmp/agent-prompt.md)" \
+            2>&1 | tee /tmp/agent-output.txt
+
+          # NOTE: replace with agent-specific extraction from references/agent-runner-templates.md
+          cat /tmp/agent-output.txt | sed 's/\x1b\[[0-9;]*m//g' > /tmp/pr-body.md
+
+      # --- Scheduled / manual path: one sense -> control -> actuate iteration ---
+      # If your sensor and controller are fused into the agent (or into one tool), collapse
+      # the next three steps into a single Actuator step — do not invent separation you don't have.
+
+      - name: Sensor — measure current state
+        if: steps.agent_gate.outputs.run_agent == 'true' && github.event_name != 'issue_comment'
+        run: |
+          # Run the sensor you designed and write a stable, normalized measurement.
+          # Replace with your sensor (lint / AST search / type-check / tests / telemetry / script / agent).
+          # Example shape:
+          #   <sensor command> > /tmp/sensor-output.json
+          echo "TODO: run the sensor and write /tmp/sensor-output.json"
+
+      - name: Controller — select the next increment
+        if: steps.agent_gate.outputs.run_agent == 'true' && github.event_name != 'issue_comment'
+        run: |
+          # Consume /tmp/sensor-output.json and choose what to change this run, within scope
+          # and batch size. Deterministic example: sort findings and take the top N.
+          # If the agent itself is the controller, delete this step.
+          # Example shape:
+          #   <controller command> /tmp/sensor-output.json > /tmp/controller-output.md
+          echo "TODO: select target(s) and write /tmp/controller-output.md"
+
+      - name: Actuator — run the coding agent
+        if: steps.agent_gate.outputs.run_agent == 'true' && github.event_name != 'issue_comment'
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          FORCE_COLOR: "3"
+        run: |
+          set -o pipefail
+          MEMORY_CONTENT="$(cat .github/agent-memory/<task-slug>.md)"
+          CONTROLLER_OUTPUT="$(cat /tmp/controller-output.md 2>/dev/null || true)"
+
+          PROMPT="$(cat <<EOF
+          <paste prompt-template.md here and replace placeholders>
+
+          ## Selected work (controller output)
+
+          $CONTROLLER_OUTPUT
+
+          ## Agent Memory
+
+          $MEMORY_CONTENT
+          EOF
+          )"
+
+          # NOTE: replace this block with your agent runner from references/agent-runner-templates.md.
+          # Each agent has different output formats — see that file for extraction steps.
+          bunx @humanlayer/cli@latest codelayer \
+            --provider anthropic --model claude-opus-4-8 --thinking high \
+            --prompt "$PROMPT" \
+            2>&1 | tee /tmp/agent-output.txt
+
+      # NOTE: response extraction is agent-specific — see references/agent-runner-templates.md.
+      - name: Extract PR body
+        if: steps.agent_gate.outputs.run_agent == 'true' && github.event_name != 'issue_comment'
+        run: |
+          # CodeLayer example — strip ANSI codes. Replace with your agent's extraction.
+          cat /tmp/agent-output.txt | sed 's/\x1b\[[0-9;]*m//g' > /tmp/pr-body.md
+
+      - name: Push and create PR
+        if: steps.agent_gate.outputs.run_agent == 'true' && github.event_name != 'issue_comment'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          AGENT_LABEL: agent-<task-slug>
+          WORKFLOW_ID: agent-<task-slug>
+        run: |
+          if git diff --quiet origin/main...HEAD; then
+            echo "No commits were created by the agent; skipping PR creation."
+            exit 0
+          fi
+
+          git push --set-upstream origin "${{ env.BRANCH }}"
+
+          # Add the hidden workflow marker to the PR body for /iterate routing.
+          # NOTE: Update the path to agent-iteration.ts based on where you installed it
+          bun .github/scripts/agent-iteration.ts \
+            --command footer \
+            --workflow "$WORKFLOW_ID" \
+            --memory .github/agent-memory/<task-slug>.md >> /tmp/pr-body.md
+
+          gh label create "$AGENT_LABEL" --description "Recurring <Task Title> agent PR" --color "0E8A16" || true
+          PR_URL=$(gh pr create --title "[$(date +%m/%d)] <Task Title>" --body-file /tmp/pr-body.md)
+          gh pr edit "$PR_URL" --add-label "$AGENT_LABEL"
+
+      - name: Push iteration changes and comment
+        if: steps.agent_gate.outputs.run_agent == 'true' && github.event_name == 'issue_comment'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          if ! git diff --quiet HEAD; then
+            git add -A
+            git commit -m "chore: iterate <task-slug> agent feedback"
+            git push origin HEAD:${{ steps.agent_gate.outputs.head_ref }}
+          fi
+
+          gh pr comment ${{ steps.agent_gate.outputs.number }} --body-file /tmp/pr-body.md
+
+      - name: Upload agent output
+        if: always() && steps.agent_gate.outputs.run_agent == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: agent-output
+          path: /tmp/agent-output.txt