jb/paseo
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add agent ID/name resolution and provider/model syntax support

Browse Source
This commit is contained in:
Mohamed Boudra
2026-03-14 22:04:09 +07:00
parent d1632d80e3
commit 3ae1102d13
10 changed files with 533 additions and 257 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/paseo-loop/SKILL.md
+154 -127
View File
@@ -1,12 +1,12 @@
---
name: paseo-loop
description: Run a task in a worker→judge loop until acceptance criteria are met. Use when the user says "loop", "loop this", "keep trying until", or wants iterative autonomous execution.
description: Run a task in a loop until an exit condition is met. Use when the user says "loop", "loop this", "keep trying until", "babysit", "poll", or wants iterative autonomous execution.
user-invocable: true
---
# Loop Skill
You are setting up an autonomous worker→judge loop. A worker agent implements the plan, then a judge agent independently verifies the plan was implemented to the letter.
You are setting up an autonomous loop. An agent runs repeatedly until an exit condition is met.
**User's arguments:** $ARGUMENTS
@@ -18,14 +18,19 @@ Load the **Paseo skill** first — it contains the CLI reference for all agent c
## What Is a Loop
A loop is two roles — **worker** and **judge** — running in alternation:
A loop runs an agent repeatedly until it's done. There are two modes:
1. **Worker** receives the plan and implements it (fresh agent each iteration)
2. **Judge** receives the same plan and independently verifies it was implemented correctly, emitting a structured verdict: `{ criteria_met: boolean, reason: string }`
3. If `criteria_met` is false, a new worker is launched with the latest judge failure reason (latest only, not full history)
4. Loop exits when the judge says `criteria_met: true` or max iterations are reached
### Self-terminating (no verifier)
The judge verifies the **entire plan** — every step, every file change, every acceptance criterion. It does NOT suggest fixes or provide guidance. It only reports facts.
A single worker agent runs each iteration. It returns `{ done: boolean, reason: string }` via structured output. The loop exits when `done` is true.
### Worker + Verifier
A worker agent runs each iteration (detached, no structured output). After the worker finishes, a separate verifier agent evaluates the verification prompt and returns `{ done: boolean, reason: string }`. The loop exits when `done` is true.
### Feedback between iterations
In both modes, the `reason` from the previous iteration is fed back to the next worker as `<previous-iteration-result>`. This gives the worker context about what happened last time.
## Live Steering
@@ -33,128 +38,137 @@ Each loop run persists state in:
```text
~/.paseo/loops/<loop-id>/
plan.md
last_reason.md
history.log
worker-prompt.md # worker prompt (live-editable)
verifier-prompt.md # verifier prompt (live-editable, only when verifier is used)
last_reason.md # latest iteration result
history.log # per-iteration records
```
Behavior:
- `plan.md` is read immediately before launching each worker and each judge.
- `last_reason.md` stores only the latest judge failure reason (not accumulated history).
- `history.log` appends per-iteration operational records.
Edits to `plan.md` are picked up on the next worker/judge launch without restarting the loop.
Edits to prompt files are picked up on the next iteration without restarting the loop.
## Parsing Arguments
Parse `$ARGUMENTS` to determine:
1. **Plan** — the full implementation plan (context, steps, acceptance criteria, constraints — all in one document)
2. **Worker model** — who does the work (default: Codex `gpt-5.4`)
3. **Judge model** — who verifies (default: Claude `sonnet`)
4. **Name** — a short name for tracking iterations
5. **Max iterations** — safety cap (default: 10)
6. **Worktree** — whether to run in an isolated git worktree
1. **Worker prompt** — what the worker does each iteration
2. **Verifier prompt** (optional) — what the verifier checks after each worker iteration
3. **Worker** — which agent does the work (default: Codex)
4. **Verifier** — which agent verifies (default: Claude sonnet)
5. **Sleep** (optional) — delay between iterations
6. **Name** — a short name for tracking
7. **Max iterations** — safety cap (default: unlimited)
8. **Archive** — whether to archive agents after each iteration
9. **Worktree** — whether to run in an isolated git worktree
### Examples
```
/loop
→ Agent derives plan from conversation context
/loop babysit PR #42 until CI is green, check every 5 minutes
→ worker-prompt: "Check the CI status of PR #42 using `gh pr checks 42`. Report done when ALL checks
have passed (no pending, no failures). If any checks are still running or have failed, report not
done and list which checks are pending or failing."
No verifier (self-terminating: the worker inspects CI and reports done when green)
sleep: 5m
archive: yes
name: babysit-pr-42
/loop the provider list bug
→ Plan: full context about the bug, steps to fix, acceptance criteria
Name: provider-list-fix
/loop implement the auth refactor from the plan in /tmp/plan.md
→ worker-prompt-file: /tmp/plan.md
verifier-prompt: "Verify every step of the plan was implemented. Check file changes, types, and
run `npm run typecheck` and `npm test`. Report each criterion individually with evidence."
name: auth-refactor
worktree: auth-refactor
/loop until tests pass
→ Plan: make the failing tests pass, acceptance criteria: all tests pass
Name: fix-tests
/loop run the test suite until it passes
→ worker-prompt: "Run `npm test`. If any tests fail, read the failure output, investigate the root
cause in the source code, and fix it. Report done when `npm test` exits with code 0 and all
tests pass. Report not done if any test still fails, and explain which tests failed and why."
No verifier (self-terminating: worker reports done when tests pass)
name: fix-tests
/loop in a worktree
→ Same as above but all agents run in a shared worktree
/loop watch error rates after deploy, check every 10 minutes
→ worker-prompt: "Check the error rate for the canary deployment by running `./scripts/check-canary.sh`.
Report done when the error rate has been below 0.1% for at least 2 consecutive checks. Report not
done with the current error rate and trend."
No verifier (self-terminating: worker reports done when error rate is stable)
sleep: 10m
max-iterations: 30
archive: yes
name: canary-watch
```
## Using the Script
The loop is implemented as a bash script at `~/.agents/skills/loop/bin/loop.sh`.
The loop is implemented as a bash script at `~/.claude/skills/paseo-loop/bin/loop.sh`.
```bash
~/.agents/skills/loop/bin/loop.sh \
--plan "The full implementation plan" \
--name "short-name" \
--max-iterations 10 \
--worker-provider codex \
--worker-model gpt-5.4 \
--judge-provider claude \
--judge-model sonnet
# Self-terminating: worker checks PR CI and reports done when all checks pass
~/.claude/skills/paseo-loop/bin/loop.sh \
--worker-prompt "Check CI status of PR #42 using gh pr checks 42. Report done when ALL checks pass. Report not done with a list of pending/failing checks." \
--name "babysit-pr" \
--sleep 5m \
--archive
# Worker + verifier: worker implements, verifier independently checks
~/.claude/skills/paseo-loop/bin/loop.sh \
--worker-prompt "Implement the auth refactor: ..." \
--verifier-prompt "Verify the auth refactor is complete. Run npm run typecheck and npm test. Check that all file changes match the plan. Report each criterion with evidence." \
--name "auth-refactor" \
--worktree "auth-refactor"
```
### Arguments
| Flag | Required | Default | Description |
|---|---|---|---|
| `--plan` | Yes* | — | Full implementation plan (given to both worker and judge) |
| `--plan-file` | Yes* | — | Read the plan from a file |
| `--name` | Yes | — | Name prefix for agents (`name-work-N`, `name-verify-N`) |
| `--max-iterations` | No | 10 | Safety cap on iterations |
| `--worktree` | No | — | Worktree name. Created on first use, reused for all subsequent agents. |
| `--worker-provider` | No | `codex` | `codex` or `claude` |
| `--worker-model` | No | provider default | Model for worker |
| `--judge-provider` | No | `claude` | `codex` or `claude` |
| `--judge-model` | No | provider default | Model for judge |
| `--worker-prompt` | Yes* | — | Prompt given to the worker each iteration |
| `--worker-prompt-file` | Yes* | — | Read the worker prompt from a file |
| `--worker` | No | `codex` | Worker agent (`provider/model`, e.g. `codex/gpt-5.4`, `claude/sonnet`) |
| `--verifier-prompt` | No* | — | Verification prompt for a separate verifier agent |
| `--verifier-prompt-file` | No* | — | Read the verifier prompt from a file |
| `--verifier` | No | `claude/sonnet` | Verifier agent (`provider/model`) |
| `--name` | Yes | — | Name prefix for agents |
| `--sleep` | No | — | Delay between iterations (e.g. `30s`, `5m`, `1h`) |
| `--max-iterations` | No | unlimited | Safety cap on iterations |
| `--archive` | No | off | Archive agents after each iteration |
| `--worktree` | No | — | Worktree name. Created on first use, reused after. |
| `--thinking` | No | `medium` | Thinking level for worker |
\* Provide exactly one of `--plan` or `--plan-file`.
\* Provide exactly one of `--worker-prompt` or `--worker-prompt-file`. Provide at most one of `--verifier-prompt` or `--verifier-prompt-file`.
### How the Plan Is Used
### Behavior by parameters
The same plan is given to both the worker and the judge, wrapped in XML tags:
**Worker receives:**
```
Implement the following plan exactly as specified.
<plan>
[your plan here]
</plan>
```
If a previous iteration failed, the worker also receives:
```
<previous-verification-failure>
[judge's failure reason from last iteration]
</previous-verification-failure>
```
**Judge receives:**
```
Verify that every step of the plan has been implemented to the letter.
<plan>
[your plan here]
</plan>
```
| Parameters | Mode | Use case |
|---|---|---|
| `--worker-prompt` only | Self-terminating worker | Worker does work and decides when done |
| `--worker-prompt` + `--verifier-prompt` | Worker + verifier | Worker implements, verifier independently checks |
| `--worker-prompt` + `--sleep` | Polling with self-termination | Periodic check until a condition is met |
| `--worker-prompt` + `--verifier-prompt` + `--sleep` | Periodic work + verifier | Periodic work with independent verification |
### Agent Naming
Agents are named `{name}-work-{N}` and `{name}-verify-{N}` so the caller can track iterations:
Without verifier: agents are named `{name}-{N}`:
```
fix-bug-work-1 # First worker attempt
fix-bug-verify-1 # First judge check
fix-bug-work-2 # Second worker attempt (with failure context)
fix-bug-verify-2 # Second judge check
babysit-1 # First iteration
babysit-2 # Second iteration
```
With verifier: workers are `{name}-{N}`, verifiers are `{name}-verify-{N}`:
```
feat-1 # First worker
feat-verify-1 # First verifier
feat-2 # Second worker (with previous result context)
feat-verify-2 # Second verifier
```
### Worktree Support
When `--worktree` is passed, all workers and judges run in the same git worktree. The worktree is created on the first agent launch and reused for all subsequent agents (the `--worktree` flag on `paseo run` is idempotent — if the worktree exists, the agent runs in it without creating a new one).
No `--base` is needed in the loop script — it automatically uses the current branch as the base.
When `--worktree` is passed, all agents run in the same git worktree. The worktree is created on first launch and reused for all subsequent agents.
```bash
~/.agents/skills/loop/bin/loop.sh \
--plan-file /tmp/my-plan.md \
~/.claude/skills/paseo-loop/bin/loop.sh \
--worker-prompt "Implement the feature..." \
--verifier-prompt "Verify the feature works and typecheck passes" \
--name "feature-x" \
--worktree "feature-x"
```
@@ -162,60 +176,73 @@ No `--base` is needed in the loop script — it automatically uses the current b
## Your Job
1. **Understand the task** from the conversation context and `$ARGUMENTS`
2. **Write the plan** — comprehensive, self-contained (the worker has zero context). The plan should include:
- Task description and context
- Relevant files and what they do
- Implementation steps (ordered, concrete)
- Acceptance criteria (factual, verifiable)
- Constraints (what NOT to do)
3. **Choose models** — default: Codex worker + Claude sonnet judge
4. **Choose a name** — short, descriptive
5. **Run the script** — call `loop.sh` with all the arguments
2. **Decide the mode** — does this need a separate verifier, or can the worker self-terminate?
3. **Write the worker prompt** — what the worker does each iteration. Must be self-contained (the agent has zero prior context).
4. **Write the verifier prompt** (if needed) — what the verifier checks. Should be factual and verifiable.
5. **Choose sleep** — if the task is polling/monitoring, add a sleep duration
6. **Choose archive** — use `--archive` for long-running or polling loops to keep the agent list clean
7. **Choose agents** — default: `codex` worker + `claude/sonnet` verifier
8. **Choose a name** — short, descriptive
9. **Run the script** — call `loop.sh` with all the arguments
### Steering Guidance
### When to use a verifier vs self-terminating
- Prefer tightening or clarifying the plan when important requirements are missing.
- Rework acceptance criteria when they are causing dead loops or are not independently verifiable.
- Avoid weakening user-defined criteria unless the user explicitly asks for that change.
- Keep the plan self-contained so the loop can succeed without relying on iterative reasoning context.
Use a verifier (`--verifier-prompt`) when:
- The worker's job is to implement something and you want independent verification
- You want the verification done by a different agent than the worker
- The worker should focus on doing work, not on judging its own work
### Writing a Good Plan
Use self-terminating (no verifier) when:
- The worker is checking/polling an external condition (CI status, deployment health)
- The worker can objectively determine when it's done (tests pass, file exists)
- You want a single agent doing both the work and the evaluation
The plan is the single source of truth for both the worker and the judge. It must be:
### Writing a Good Worker Prompt
1. **Self-contained** — The worker starts with zero context. Everything needed is in the plan.
2. **Specific** — Name files, functions, types. "Update the handler" is useless. "In `src/handlers/auth.ts`, modify the `handleLogin` function to..." is useful.
3. **Ordered** — Steps should be in implementation order.
4. **Verifiable** — Every step and criterion must be independently checkable by the judge.
The worker prompt is what the agent receives each iteration. It must be:
**Good plan elements:**
- "File `src/utils.ts` exports a function named `formatDate`"
- "Running `npm test` exits with code 0"
- "The component at `src/ProviderList.tsx` renders a list of providers from the API response"
- "Typecheck passes (`npm run typecheck`)"
- "`npm run typecheck` passes"
1. **Self-contained** — The agent starts with zero context. Everything needed is in the prompt.
2. **Specific** — Name files, functions, types, URLs. Be concrete.
3. **Action-oriented** — Tell the agent what to do, not what to think about.
**Bad plan elements:**
- "The code is clean" (subjective)
- "The implementation is correct" (vague)
- "It works" (unverifiable)
### Writing a Good Verifier Prompt
The verifier prompt defines what the verifier checks after each worker iteration. It can range from strict factual checks to qualitative code review:
**Factual / objective checks:**
- "Run `npm test` and `npm run typecheck`. Report done only if both pass with zero failures."
- "Check that PR #42 has all CI checks green and no unresolved review comments."
- "Verify the API responds to `GET /health` with status 200 within 500ms."
**Code quality / style checks:**
- "Review the changes for DRY violations. Report done when there is no duplicated logic across files."
- "Check that the implementation does not over-engineer. No unnecessary abstractions, no premature generalization, no feature flags for single-use code."
- "Verify the code follows the project's conventions: functional style, no classes, explicit types, no `any`."
**Performance / resource checks:**
- "Run the benchmark suite. Report done when p99 latency is under 100ms."
- "Check bundle size. Report done when the production build is under 500KB gzipped."
**Comprehensive verification:**
- "Verify every step of the plan was implemented. Check file changes, types, test output. Run `npm run typecheck` and `npm test`. Report each criterion individually with evidence."
The verifier should report facts with evidence, not suggest fixes.
### Skill Stacking
You can instruct the worker to use other skills in the plan:
You can instruct the worker to use other skills:
```bash
~/.agents/skills/loop/bin/loop.sh \
--plan "Use the /committee skill to plan and then fix the provider list bug. The bug is..." \
~/.claude/skills/paseo-loop/bin/loop.sh \
--worker-prompt "Use /committee to plan, then fix the provider list bug. The bug is..." \
--verifier-prompt "The provider list renders correctly and npm run typecheck passes" \
--name "provider-fix"
```
### Composing with Handoff
A handoff can launch a loop in a worktree:
A handoff can launch a loop:
```
/handoff a loop in a worktree
/handoff a loop in a worktree to babysit PR #42
```
The handoff skill writes a prompt telling the new agent to use `/loop`, and the loop runs inside the worktree.