Support multiple independent loops per repository

mrjf · claude · mrjf · commit e1b60611d33c · 2026-03-11T20:52:24.000-07:00
- Programs now live in .github/autoloop/programs/ (one .md file per loop)
- Each program gets its own namespace: metrics, memory, branches, PRs, experiment log
- Programs can specify per-program schedule and timeout via YAML frontmatter
- Slash command supports program targeting: /autoloop training: try X
- Template moved to programs/example.md with instructions to rename

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/docs/autoloop.md b/docs/autoloop.md
@@ -4,7 +4,7 @@
 
 **Iterative optimization agent inspired by [Autoresearch](https://github.com/karpathy/autoresearch) and Claude Code's `/loop`**
 
-The [Autoloop workflow](../workflows/autoloop.md?plain=1) runs on a schedule to autonomously improve a target artifact toward a measurable goal. Each iteration proposes a change, evaluates it against a metric, and keeps only improvements.
+The [Autoloop workflow](../workflows/autoloop.md?plain=1) runs on a schedule to autonomously improve target artifacts toward measurable goals. Each iteration proposes a change, evaluates it against a metric, and keeps only improvements. Supports **multiple independent loops** in the same repository.
 
 ## Installation
 
@@ -22,43 +22,58 @@ This walks you through adding the workflow to your repository.
 
 ```mermaid
 graph LR
-    A[Scheduled Run] --> B[Read program.md]
-    B --> C[Review History]
-    C --> D[Propose Change]
-    D --> E[Implement on Branch]
-    E --> F[Run Evaluation]
-    F --> G{Metric Improved?}
-    G -->|Yes| H[Create Draft PR]
-    G -->|No| I[Record & Reject]
-    H --> J[Update Experiment Log]
-    I --> J
+    A[Scheduled Run] --> B[Discover Programs]
+    B --> C[For Each Program]
+    C --> D[Review History]
+    D --> E[Propose Change]
+    E --> F[Implement on Branch]
+    F --> G[Run Evaluation]
+    G --> H{Metric Improved?}
+    H -->|Yes| I[Create Draft PR]
+    H -->|No| J[Record & Reject]
+    I --> K[Update Experiment Log]
+    J --> K
 ```
 
 ## Getting Started
 
-When you install Autoloop, a **template `program.md`** is added to your repo at `.github/autoloop/program.md`. This template has placeholder sections you must fill in — the workflow **will not run** until you do.
+When you install Autoloop, a **template program file** is added at `.github/autoloop/programs/example.md`. This template has placeholder sections you must fill in — the workflow **will not run** until you do.
 
 ### Setup flow
 
 ```mermaid
 graph LR
-    A[Install Workflow] --> B[Edit program.md]
+    A[Install Workflow] --> B[Rename & Edit Program]
     B --> C[Define Goal, Targets, Evaluation]
     C --> D[Remove UNCONFIGURED sentinel]
     D --> E[Commit & Push]
     E --> F[Loop Begins]
 ```
 
 1. **Install** — `gh aw add-wizard githubnext/agentics/autoloop`
-2. **Edit** — Open `.github/autoloop/program.md` and replace the placeholders with your project's goal, target files, and evaluation command. The template includes three complete examples (ML training, test coverage, build performance) for inspiration.
-3. **Activate** — Remove the `<!-- AUTOLOOP:UNCONFIGURED -->` line at the top of the file.
-4. **Compile & push** — `gh aw compile && git add . && git commit -m "Configure autoloop" && git push`
+2. **Rename** — Rename `.github/autoloop/programs/example.md` to something meaningful (e.g., `training.md`, `coverage.md`). The filename becomes the program name.
+3. **Edit** — Replace the placeholders with your project's goal, target files, and evaluation command. The template includes three complete examples for inspiration.
+4. **Activate** — Remove the `<!-- AUTOLOOP:UNCONFIGURED -->` line at the top.
+5. **Compile & push** — `gh aw compile && git add . && git commit -m "Configure autoloop" && git push`
 
 If you forget to edit the template, the first scheduled run will create a GitHub issue reminding you, with a direct link to edit the file.
 
+### Adding more loops
+
+To run multiple optimization loops in parallel, just add more `.md` files to `.github/autoloop/programs/`:
+
+```
+.github/autoloop/programs/
+├── training.md      ← optimize model training loss
+├── coverage.md      ← maximize test coverage
+└── build-perf.md    ← minimize build time
+```
+
+Each program runs independently with its own metric tracking, experiment log issue, and PR namespace. Copy the template, fill it in, and push — the next scheduled run picks it up automatically.
+
 ## Configuration
 
-The `program.md` file (at `.github/autoloop/program.md` or repo root) has three sections:
+Each program file in `.github/autoloop/programs/` has three sections:
 
 ### 1. Goal — What to optimize
 
@@ -72,7 +87,7 @@ List the files the agent is allowed to modify. Everything else is off-limits.
 
 Provide a command to run and a metric to extract. Specify whether higher or lower is better.
 
-### Example program.md
+### Example program file
 
 ````markdown
 # Autoloop Program
@@ -107,11 +122,13 @@ Edit the workflow's `schedule` field. Examples:
 
 After editing, run `gh aw compile` to update the workflow.
 
+Note: The schedule applies to the workflow as a whole — all programs iterate on the same schedule. To run programs at different frequencies, you can install the workflow multiple times with different schedules, each pointing to a subset of programs.
+
 ## Usage
 
 ### Automatic mode
 
-Once `program.md` exists and the workflow is installed, iterations run automatically on schedule. Each run:
+Once at least one configured program exists, iterations run automatically on schedule. Each run processes every configured program:
 
 1. Reads the program definition and past history
 2. Proposes a single targeted change
@@ -121,23 +138,26 @@ Once `program.md` exists and the workflow is installed, iterations run automatic
 ### Manual trigger
 
 ```bash
-# Run an iteration now
+# Run all programs now
 gh aw run autoloop
 
-# Give specific instructions
-gh aw run autoloop -- "try using cosine annealing for the learning rate schedule"
+# Target a specific program
+gh aw run autoloop -- "training: try using cosine annealing"
+
+# If only one program exists, no prefix needed
+gh aw run autoloop -- "try batch size 64 instead of 32"
 ```
 
 ### Slash command
 
 Comment on any issue or PR:
 ```
-/autoloop try batch size 64 instead of 32
+/autoloop training: try batch size 64 instead of 32
 ```
 
 ## Experiment Tracking
 
-All iterations are logged in a monthly GitHub issue titled `[Autoloop] Experiment Log {YYYY-MM}`. The issue tracks:
+Each program gets its own monthly experiment log issue titled `[Autoloop: {program-name}] Experiment Log {YYYY-MM}`. The issue tracks:
 
 - Current best metric value
 - Full iteration history with accept/reject status
@@ -148,14 +168,15 @@ All iterations are logged in a monthly GitHub issue titled `[Autoloop] Experimen
 
 - **Review draft PRs** — accepted improvements appear as draft PRs for human review
 - **Merge or close** — you decide which optimizations to keep
-- **Adjust the program** — update `program.md` to change the goal, targets, or evaluation
-- **Steer via slash command** — use `/autoloop <instructions>` to direct specific experiments
-- **Pause** — disable the workflow schedule to stop iterations
+- **Adjust programs** — edit any program file to change the goal, targets, or evaluation
+- **Add/remove loops** — add or delete files in `.github/autoloop/programs/`
+- **Steer via slash command** — use `/autoloop {program}: {instructions}` to direct experiments
+- **Pause** — disable the workflow schedule to stop all loops, or add the sentinel back to a single program file to pause just that loop
 
 ## Security
 
 - Runs with read-only GitHub permissions
-- Only modifies files listed in `program.md`'s Target section
+- Only modifies files listed in each program's Target section
 - Never modifies evaluation scripts
 - All changes go through draft PRs requiring human approval
 - Uses "safe outputs" to constrain what the agent can create
diff --git a/workflows/autoloop.md b/workflows/autoloop.md
@@ -74,58 +74,102 @@ An iterative optimization agent that proposes changes, evaluates them against a
 Take heed of **instructions**: "${{ steps.sanitized.outputs.text }}"
 
 If these are non-empty (not ""), then you have been triggered via `/autoloop <instructions>`. The instructions may be:
-- **A one-off directive**: e.g., `/autoloop try a different approach to the loss function`. Execute it as a single iteration using the program.md context, then report results.
-- **A configuration change**: e.g., `/autoloop set metric to accuracy instead of loss`. Update the relevant program.md section and confirm.
+- **A one-off directive targeting a specific program**: e.g., `/autoloop training: try a different approach to the loss function`. The text before the colon is the program name (matching a file in `.github/autoloop/programs/`). Execute it as a single iteration for that program, then report results.
+- **A general directive**: e.g., `/autoloop try cosine annealing`. If no program name prefix is given and only one program exists, use that one. If multiple exist, ask which program to target.
+- **A configuration change**: e.g., `/autoloop training: set metric to accuracy instead of loss`. Update the relevant program file and confirm.
 
 Then exit — do not run the normal loop after completing the instructions.
 
+## Multiple Programs
+
+Autoloop supports **multiple independent optimization loops** in the same repository. Each loop is defined by a separate markdown file in `.github/autoloop/programs/`. For example:
+
+```
+.github/autoloop/programs/
+├── training.md      ← optimize model training
+├── coverage.md      ← maximize test coverage
+└── build-perf.md    ← minimize build time
+```
+
+Each program runs independently with its own:
+- Goal, target files, and evaluation command
+- Metric tracking and best-metric history
+- Experiment log issue: `[Autoloop: {program-name}] Experiment Log {YYYY-MM}`
+- Branch namespace: `autoloop/{program-name}/iteration-<N>-<desc>`
+- PR title prefix: `[Autoloop: {program-name}]`
+- Repo memory namespace: keyed by program name
+
+On each scheduled run, the workflow iterates through **all configured programs** and runs one iteration per program. Programs with the `<!-- AUTOLOOP:UNCONFIGURED -->` sentinel are skipped.
+
+### Per-Program Schedule and Timeout
+
+Programs can optionally specify their own schedule and timeout in a YAML frontmatter block at the top of the file (after the sentinel, if present):
+
+```markdown
+---
+schedule: every 1h
+timeout-minutes: 30
+---
+
+# Autoloop Program
+...
+```
+
+- **`schedule`**: Controls how often this program runs. On each workflow trigger, check if the program is due based on its schedule and the `last_run` timestamp in memory. If the program's schedule hasn't elapsed since its last run, skip it. If omitted, the program runs on every workflow trigger.
+- **`timeout-minutes`**: Maximum time for this program's iteration. If omitted, the program shares the workflow's overall timeout.
+
+This lets you run a fast coverage check every hour while running a slow training loop once a day — all from the same workflow.
+
 ## Program Definition
 
-The user configures the optimization loop by editing **`.github/autoloop/program.md`** — a template file installed alongside this workflow. This file defines three things:
+Each program file in `.github/autoloop/programs/` defines three things:
 
 1. **Goal**: What the agent is trying to optimize (natural language description)
 2. **Target**: Which files the agent is allowed to modify
 3. **Evaluation**: How to measure whether a change is an improvement
 
+The **program name** is the filename without the `.md` extension (e.g., `training.md` → program name is `training`).
+
 ### Setup Guard
 
-**The workflow will not run until the user has edited the template.** The installed template contains a sentinel line:
+A template program file is installed at `.github/autoloop/programs/example.md`. **Programs will not run until the user has edited them.** Each template contains a sentinel line:
 
 ```
 <!-- AUTOLOOP:UNCONFIGURED -->
 ```
 
-At the start of every run, check for this sentinel. If it is present:
+At the start of every run, check each program file for this sentinel. For any program where it is present:
 
-1. **Do not run any iterations.**
-2. Create a single GitHub issue (if one doesn't already exist) titled `[Autoloop] Action required: configure your program.md` with:
-   - A clear explanation that the workflow is installed but paused until `program.md` is configured.
-   - A direct link to the file: `${{ github.server_url }}/${{ github.repository }}/edit/${{ github.ref_name }}/.github/autoloop/program.md`
+1. **Skip that program — do not run any iterations for it.**
+2. If no setup issue exists for that program, create one titled `[Autoloop: {program-name}] Action required: configure your program` with:
+   - A clear explanation that this program is installed but paused until configured.
+   - A direct link to the file: `${{ github.server_url }}/${{ github.repository }}/edit/${{ github.ref_name }}/.github/autoloop/programs/{program-name}.md`
    - A brief guide: "Open the file, replace the placeholder sections with your project's goal, target files, and evaluation command, then remove the `<!-- AUTOLOOP:UNCONFIGURED -->` line."
    - Two or three example programs for inspiration (ML training, test coverage, build performance).
-3. Exit.
 
-If the sentinel is absent, proceed with the iteration loop.
+If **all** programs are unconfigured, exit after creating the setup issues. Otherwise, proceed with the configured programs.
 
-### Reading the Program
+### Reading Programs
 
 At the start of every run:
 
-1. Read `.github/autoloop/program.md` (or `program.md` in the repo root as a fallback).
-2. Check for the `<!-- AUTOLOOP:UNCONFIGURED -->` sentinel — if present, run the **Setup Guard** flow above.
-3. Parse the three sections: Goal, Target, Evaluation.
-4. Validate that all three sections have non-placeholder content. If any section still contains `TODO` or `REPLACE` markers, treat it as unconfigured — create/update the setup issue and exit.
-5. Read the current state of all target files.
-6. Read repo memory for the current best metric value and iteration history.
+1. List all `.md` files in `.github/autoloop/programs/`.
+2. If the directory is empty or doesn't exist, also check for a single `.github/autoloop/program.md` or `program.md` in the repo root as a fallback (for single-program setups).
+3. For each program file:
+   a. Check for the `<!-- AUTOLOOP:UNCONFIGURED -->` sentinel — if present, run the **Setup Guard** for that program and skip it.
+   b. Parse the three sections: Goal, Target, Evaluation.
+   c. Validate that all three sections have non-placeholder content. If any section still contains `TODO` or `REPLACE` markers, treat it as unconfigured — create/update the setup issue for that program and skip it.
+   d. Read the current state of all target files.
+   e. Read repo memory for that program's metric history (keyed by program name).
 
 ## Iteration Loop
 
-Each run executes **one iteration** of the optimization loop:
+Each run executes **one iteration per configured program**. For each program:
 
 ### Step 1: Read State
 
-1. Read `program.md` to understand the goal, targets, and evaluation method.
-2. Read repo memory to get:
+1. Read the program file to understand the goal, targets, and evaluation method.
+2. Read repo memory (keyed by program name) to get:
    - `best_metric`: The current best metric value (null if first run).
    - `iteration_count`: How many iterations have been completed.
    - `history`: Summary of recent iterations (last 20).
@@ -145,7 +189,7 @@ Each run executes **one iteration** of the optimization loop:
 
 ### Step 3: Implement
 
-1. Create a fresh branch: `autoloop/iteration-<N>-<short-desc>` from the default branch.
+1. Create a fresh branch: `autoloop/{program-name}/iteration-<N>-<short-desc>` from the default branch.
 2. Make the proposed changes to the target files only.
 3. **Respect the program constraints**: do not modify files outside the target list.
 
@@ -160,7 +204,7 @@ Each run executes **one iteration** of the optimization loop:
 **If the metric improved** (or this is the first run establishing a baseline):
 1. Record the new `best_metric` in repo memory.
 2. Create a draft PR with:
-   - Title: `[Autoloop] Iteration <N>: <short description of change>`
+   - Title: `[Autoloop: {program-name}] Iteration <N>: <short description of change>`
    - Body includes: what was changed, why, the old metric, the new metric, and the improvement delta.
    - AI disclosure: `🤖 *This change was proposed and validated by Autoloop.*`
 3. Add an entry to the experiment log issue.
@@ -180,7 +224,7 @@ Each run executes **one iteration** of the optimization loop:
 
 ## Experiment Log Issue
 
-Maintain a single open issue titled `[Autoloop] Experiment Log {YYYY}-{MM}` as a rolling record of all iterations.
+Maintain a single open issue **per program** titled `[Autoloop: {program-name}] Experiment Log {YYYY}-{MM}` as a rolling record of that program's iterations.
 
 ### Issue Body Format
 
@@ -219,10 +263,11 @@ Maintain a single open issue titled `[Autoloop] Experiment Log {YYYY}-{MM}` as a
 
 ## Memory Schema
 
-Store the following in repo memory:
+Store state in repo memory **keyed by program name**. Each program gets its own memory namespace (e.g., `autoloop/training`, `autoloop/coverage`):
 
 ```json
 {
+  "program_name": "training",
   "best_metric": 0.0234,
   "metric_name": "validation_loss",
   "metric_direction": "lower",
diff --git a/workflows/autoloop/programs/example.md b/workflows/autoloop/programs/example.md
@@ -2,6 +2,18 @@
 <!-- ⚠️  REMOVE the line above once you've filled in your program. -->
 <!-- Autoloop will NOT run until you do. -->
 
+<!--
+  Optional: control how often THIS program runs and its timeout.
+  Remove the comment markers to activate. If omitted, the program
+  runs on every workflow trigger with no per-program timeout.
+
+---
+schedule: every 6h
+timeout-minutes: 30
+---
+
+-->
+
 # Autoloop Program
 
 <!--
@@ -10,6 +22,11 @@
   sentinel at the top. Commit and push — the loop will start on the next
   scheduled run.
 
+  Rename this file to something meaningful — the filename (minus .md) becomes
+  the program name used in issues, PRs, and slash commands.
+
+  Want multiple loops? Just add more .md files to this directory.
+
   Need inspiration? See the examples at the bottom of this file.
 -->
 
