diff --git a/skills/committee/SKILL.md b/skills/committee/SKILL.md new file mode 100644 index 000000000..3cfe47942 --- /dev/null +++ b/skills/committee/SKILL.md @@ -0,0 +1,159 @@ +--- +name: committee +description: Form a committee of two high-reasoning agents to step back, do root cause analysis, and produce a plan. Use when stuck, looping, tunnel-visioning, or facing a hard planning problem. +user-invocable: true +--- + +# Committee Skill + +You are forming a committee to step back from the current problem and get fresh perspective. + +**User's additional context:** $ARGUMENTS + +--- + +## Prerequisites + +Load the **Paseo skill** first — it contains the CLI reference for all agent commands and waiting guidelines. + +## What Is a Committee + +Two agents — **Opus 4.6** (`--thinking on`) and **GPT 5.4** (`--thinking medium`) — launched in parallel to plan a solution. Fresh context, no implementation baggage, proper root cause analysis. + +They stay alive after planning for Phase 3 review — they hold only the plan, so they catch implementation drift. + +**The purpose is to step back, not to double down.** The committee may propose a completely different approach. + +## Your Role + +You drive the full lifecycle: plan → implement → review. You are a middleman between the user and the committee. Do not yield back to the user until the cycle is complete. If the user needs to weigh in on a divergence, ask them — but don't stop the process. + +## No Anxiety + +**Once you call `paseo wait`, trust the wait.** Do not poll logs, read output early, send hurry-up messages, interrupt deep analysis, or give up because it's taking long. + +GPT 5.4 can reason for 15–30 minutes. Opus does extended thinking. Long waits mean the agent found something worth thinking about. Let it finish. + +If the CLI has a bug, the user will tell you. + +## No-Edits Suffix + +Every prompt to a committee member — initial, follow-up, or review — **must** end with this suffix. They will start editing code if you don't. + +``` +NO_EDITS="This is analysis only. Do NOT edit, create, or delete any files. Do NOT write code." +``` + +All example prompts below include `$NO_EDITS` — always expand it. + +## Phase 1: Get a Plan + +### Write the prompt + +Describe the **overall problem**, not just the immediate symptom: + +- High-level goal and acceptance criteria +- Constraints +- Symptoms (if a bug) +- What you've tried and why it failed +- Explicitly ask for root cause analysis + +```bash +prompt="We're trying to [high-level goal]. Constraints: [X, Y, Z]. Acceptance criteria: [A, B, C]. + +We've been stuck on this. Here's what we've tried and why it didn't work: +- [approach 1] — failed because [reason] +- [approach 2] — partially worked but [issue] + +Step back from these attempts. Do root cause analysis — the fix might not be for [immediate symptom] at all, it might be structural. + +Use the think-harder approach: state your assumptions, ask why at least 3 levels deep for each, and check whether you're patching a symptom or removing the problem. What's the right approach? + +$NO_EDITS" +``` + +### Launch both members + +Same prompt to both, `[Committee]` prefix for identification: + +```bash +opus_id=$(paseo run -d --mode bypassPermissions --model opus --thinking on --name "[Committee] Task description" "$prompt" -q) +gpt_id=$(paseo run -d --mode full-access --provider codex --model gpt-5.4 --thinking medium --name "[Committee] Task description" "$prompt" -q) +``` + +### Wait for both + +Wait for **both** agents — not just the first one that finishes. + +```bash +paseo wait "$opus_id" +paseo wait "$gpt_id" +``` + +### Read and challenge + +```bash +paseo logs "$opus_id" +paseo logs "$gpt_id" +``` + +**Do not accept output at face value.** Use the **think-harder** framework to challenge their output. Before synthesizing: + +1. **Ask "why" 2–3 levels deep.** "Fix X because Y is broken" — why is Y broken? Is Y a root cause or a consequence? +2. **Challenge assumptions.** If the plan assumes something about the code, make the agent verify it. +3. **Symptom vs cause.** "Are we fixing the consequence or the cause?" +4. **Probe alternatives.** "What did you consider and reject?" + +```bash +paseo send "$opus_id" "You said [X]. Why does [underlying thing] happen in the first place? Are we patching a symptom? $NO_EDITS" +paseo wait "$opus_id" +paseo logs "$opus_id" +``` + +Keep pushing until the plan addresses the root cause. + +### Synthesize and confirm + +- Convergence → merge into unified plan. +- Significant divergence → involve the user. + +Send the merged plan back for confirmation. Multi-turn if needed — keep going until consensus. + +```bash +paseo send "$opus_id" "Merged plan: [plan]. Concerns? $NO_EDITS" +paseo send "$gpt_id" "Merged plan: [plan]. Concerns? $NO_EDITS" +``` + +## Phase 2: Implement + +Implement the plan yourself — unless the user said **"delegate"**, in which case launch an implementer: + +```bash +impl_id=$(paseo run -d --mode full-access --provider codex --name "[Impl] Task description" "Implement the following plan end-to-end. [plan]" -q) +paseo wait "$impl_id" +``` + +Committee agents stay clean — not involved in implementation. + +## Phase 3: Review + +Send the committee the changes for review. They anchor against the plan and catch drift. + +```bash +review_prompt="Implementation is done. Review changes against the plan. Flag drift or missing pieces. $NO_EDITS" + +paseo send "$opus_id" "$review_prompt" +paseo send "$gpt_id" "$review_prompt" + +paseo wait "$opus_id" +paseo wait "$gpt_id" + +paseo logs "$opus_id" +paseo logs "$gpt_id" +``` + +### Iterate + +Send committee feedback to the implementer (or apply yourself). Repeat Phase 2 → 3 until the committee confirms the implementation matches the plan. + +After ~10 iterations without convergence, start a fresh committee with full context of what was tried — the current committee's context may have drifted too far. diff --git a/skills/handoff/SKILL.md b/skills/handoff/SKILL.md new file mode 100644 index 000000000..3aff1147a --- /dev/null +++ b/skills/handoff/SKILL.md @@ -0,0 +1,146 @@ +--- +name: handoff +description: Hand off the current task to another agent with full context. Use when the user says "handoff", "hand off", "hand this to", or wants to pass work to another agent (Codex or Claude). +user-invocable: true +--- + +# Handoff Skill + +You are handing off the current task to another agent. Your job is to write a comprehensive handoff prompt and launch the agent via Paseo CLI. + +**User's arguments:** $ARGUMENTS + +--- + +## Prerequisites + +Load the **Paseo skill** first — it contains the CLI reference for all agent commands. + +## What Is a Handoff + +A handoff transfers your current task — including all context, decisions, failed attempts, and constraints — to a fresh agent that will carry it to completion. The handoff prompt is the most important part: the receiving agent starts with **zero context**, so everything it needs must be in the prompt. + +## Parsing Arguments + +Parse `$ARGUMENTS` to determine: + +1. **Provider and model** — who to hand off to +2. **Worktree** — whether to run in an isolated git worktree +3. **Task description** — any additional context the user provided + +### Provider Resolution + +| User says | Provider | Model | Mode | +|---|---|---|---| +| *(nothing)* | `codex` | `gpt-5.4` | `full-access` | +| `codex` | `codex` | `gpt-5.4` | `full-access` | +| `claude` | `claude` | `opus` | `bypassPermissions` | +| `opus` | `claude` | `opus` | `bypassPermissions` | +| `sonnet` | `claude` | `sonnet` | `bypassPermissions` | + +Default is **Codex** with `gpt-5.4`. + +### Worktree Resolution + +If the user says "in a worktree" or "worktree", add `--worktree` with a short descriptive branch name derived from the task. Worktrees require a `--base` branch — use the current branch in the working directory (run `git branch --show-current` to get it). + +## Writing the Handoff Prompt + +This is the critical step. The receiving agent has **zero context** about your conversation. The handoff prompt must be a self-contained briefing document. + +### Must Include + +1. **Task description** — What needs to be done, in clear imperative language +2. **Task qualifiers** — Preserve the semantics of what the user asked for: + - If the user asked to **investigate without editing**, say "DO NOT edit any files" + - If the user asked to **fix**, say "implement the fix" + - If the user asked to **refactor**, say "refactor" not "rewrite" + - Carry forward the exact intent +3. **Relevant files** — List every file path that matters, with brief descriptions of what each contains +4. **Current state** — What has been done so far, what's working, what's not +5. **What was tried** — Any approaches attempted and why they failed or were abandoned +6. **Decisions made** — Anything you and the user agreed on (design choices, constraints, trade-offs) +7. **Acceptance criteria** — How the agent knows it's done +8. **Constraints** — Anything the agent must NOT do + +### Template + +``` +## Task + +[Clear, imperative description of what to do] + +## Context + +[Why this task exists, background the agent needs] + +## Relevant Files + +- `path/to/file.ts` — [what it does and why it matters] +- `path/to/other.ts` — [what it does and why it matters] + +## Current State + +[What's been done, what works, what doesn't] + +## What Was Tried + +- [Approach 1] — [why it failed/was abandoned] +- [Approach 2] — [partial success, but...] + +## Decisions + +- [Decision 1 — rationale] +- [Decision 2 — rationale] + +## Acceptance Criteria + +- [ ] [Criterion 1] +- [ ] [Criterion 2] + +## Constraints + +- [Do not do X] +- [Must preserve Y] +``` + +## Launching the Agent + +Use `--ui` so that the agent is visible in the UI. + +### Default (Codex, no worktree) + +```bash +paseo run --ui -d --mode full-access --provider codex --name "[Handoff] Task description" "$prompt" +``` + +### Claude (Opus, no worktree) + +```bash +paseo run --ui -d --mode bypassPermissions --model opus --name "[Handoff] Task description" "$prompt" +``` + +### Codex in a worktree + +```bash +base=$(git branch --show-current) +paseo run --ui -d --mode full-access --provider codex --worktree task-branch-name --base "$base" --name "[Handoff] Task description" "$prompt" +``` + +### Claude in a worktree + +```bash +base=$(git branch --show-current) +paseo run --ui -d --mode bypassPermissions --model opus --worktree task-branch-name --base "$base" --name "[Handoff] Task description" "$prompt" +``` + +## After Launch + +1. Print the agent ID and the command to follow along: + ``` + Handed off to [provider] ([model]). Agent ID: + Follow along: paseo logs -f + Wait for completion: paseo wait + ``` +2. Do **not** wait for the agent by default — the user can choose to wait or move on. +3. If the user wants to wait, run `paseo wait ` and then `paseo logs ` when done. diff --git a/skills/loop/SKILL.md b/skills/loop/SKILL.md new file mode 100644 index 000000000..4a32ea776 --- /dev/null +++ b/skills/loop/SKILL.md @@ -0,0 +1,221 @@ +--- +name: 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. +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. + +**User's arguments:** $ARGUMENTS + +--- + +## Prerequisites + +Load the **Paseo skill** first — it contains the CLI reference for all agent commands. + +## What Is a Loop + +A loop is two roles — **worker** and **judge** — running in alternation: + +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 + +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. + +## Live Steering + +Each loop run persists state in: + +```text +~/.paseo/loops// + plan.md + last_reason.md + history.log +``` + +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. + +## 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 + +### Examples + +``` +/loop +→ Agent derives plan from conversation context + +/loop the provider list bug +→ Plan: full context about the bug, steps to fix, acceptance criteria + Name: provider-list-fix + +/loop until tests pass +→ Plan: make the failing tests pass, acceptance criteria: all tests pass + Name: fix-tests + +/loop in a worktree +→ Same as above but all agents run in a shared worktree +``` + +## Using the Script + +The loop is implemented as a bash script at `~/.agents/skills/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 +``` + +### 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 | +| `--thinking` | No | `medium` | Thinking level for worker | + +\* Provide exactly one of `--plan` or `--plan-file`. + +### How the Plan Is Used + +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. + + +[your plan here] + +``` + +If a previous iteration failed, the worker also receives: +``` + +[judge's failure reason from last iteration] + +``` + +**Judge receives:** +``` +Verify that every step of the plan has been implemented to the letter. + + +[your plan here] + +``` + +### Agent Naming + +Agents are named `{name}-work-{N}` and `{name}-verify-{N}` so the caller can track iterations: + +``` +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 +``` + +### 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. + +```bash +~/.agents/skills/loop/bin/loop.sh \ + --plan-file /tmp/my-plan.md \ + --name "feature-x" \ + --worktree "feature-x" +``` + +## 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 + +### Steering Guidance + +- 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. + +### Writing a Good Plan + +The plan is the single source of truth for both the worker and the judge. It must be: + +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. + +**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" + +**Bad plan elements:** +- "The code is clean" (subjective) +- "The implementation is correct" (vague) +- "It works" (unverifiable) + +### Skill Stacking + +You can instruct the worker to use other skills in the plan: + +```bash +~/.agents/skills/loop/bin/loop.sh \ + --plan "Use the /committee skill to plan and then fix the provider list bug. The bug is..." \ + --name "provider-fix" +``` + +### Composing with Handoff + +A handoff can launch a loop in a worktree: + +``` +/handoff a loop in a worktree +``` + +The handoff skill writes a prompt telling the new agent to use `/loop`, and the loop runs inside the worktree. diff --git a/skills/loop/bin/loop.sh b/skills/loop/bin/loop.sh new file mode 100755 index 000000000..00f7d7cbd --- /dev/null +++ b/skills/loop/bin/loop.sh @@ -0,0 +1,255 @@ +#!/usr/bin/env bash +set -euo pipefail + +usage() { + cat <<'EOF' +Usage: loop.sh (--plan PROMPT | --plan-file PATH) --name NAME [options] + +Required: + --plan PROMPT The implementation plan (given to both worker and judge) + --plan-file PATH Read the plan from a file + --name NAME Name prefix for agents (e.g. "fix-bug" → "fix-bug-work-1", "fix-bug-verify-1") + +Options: + --max-iterations N Maximum loop iterations (default: 10) + --worktree NAME Run all agents in this worktree (created on first use, reused after) + --worker-provider P Worker provider: claude or codex (default: codex) + --worker-model M Worker model (default: provider's default) + --judge-provider P Judge provider: claude or codex (default: claude) + --judge-model M Judge model (default: provider's default) + --thinking LEVEL Thinking level for worker (default: medium) +EOF + exit 1 +} + +# Defaults +max_iterations=10 +worker_provider="codex" +worker_model="" +judge_provider="claude" +judge_model="sonnet" +plan="" +plan_file_input="" +name="" +thinking="medium" +worktree="" +state_root="${HOME}/.paseo/loops" + +while [[ $# -gt 0 ]]; do + case "$1" in + --plan) plan="$2"; shift 2 ;; + --plan-file) plan_file_input="$2"; shift 2 ;; + --name) name="$2"; shift 2 ;; + --max-iterations) max_iterations="$2"; shift 2 ;; + --worktree) worktree="$2"; shift 2 ;; + --worker-provider) worker_provider="$2"; shift 2 ;; + --worker-model) worker_model="$2"; shift 2 ;; + --judge-provider) judge_provider="$2"; shift 2 ;; + --judge-model) judge_model="$2"; shift 2 ;; + --thinking) thinking="$2"; shift 2 ;; + --help|-h) usage ;; + *) echo "Unknown option: $1"; usage ;; + esac +done + +load_prompt() { + local inline_value="$1" + local file_value="$2" + local label="$3" + + if [[ -n "$inline_value" && -n "$file_value" ]]; then + echo "Error: use either --${label} or --${label}-file, not both" + usage + fi + + if [[ -n "$file_value" ]]; then + [[ -f "$file_value" ]] || { echo "Error: --${label}-file not found: $file_value"; exit 1; } + local file_content + file_content="$(cat "$file_value")" + [[ -n "$file_content" ]] || { echo "Error: --${label}-file is empty: $file_value"; exit 1; } + printf '%s' "$file_content" + return 0 + fi + + if [[ -n "$inline_value" ]]; then + printf '%s' "$inline_value" + return 0 + fi + + echo "Error: either --${label} or --${label}-file is required" + usage +} + +plan="$(load_prompt "$plan" "$plan_file_input" "plan")" +[[ -z "$name" ]] && { echo "Error: --name is required"; usage; } + +mkdir -p "$state_root" + +generate_loop_id() { + uuidgen | tr '[:upper:]' '[:lower:]' | tr -d '-' | cut -c1-6 +} + +loop_id="$(generate_loop_id)" +state_dir="${state_root}/${loop_id}" +while [[ -e "$state_dir" ]]; do + loop_id="$(generate_loop_id)" + state_dir="${state_root}/${loop_id}" +done + +mkdir -p "$state_dir" + +plan_file="${state_dir}/plan.md" +last_reason_file="${state_dir}/last_reason.md" +history_log="${state_dir}/history.log" + +printf '%s\n' "$plan" > "$plan_file" +printf '' > "$last_reason_file" +printf '' > "$history_log" + +# Build worker flags +worker_flags=() +if [[ "$worker_provider" == "codex" ]]; then + worker_flags+=(--mode full-access --provider codex) +elif [[ "$worker_provider" == "claude" ]]; then + worker_flags+=(--mode bypassPermissions) +fi +[[ -n "$worker_model" ]] && worker_flags+=(--model "$worker_model") +[[ -n "$thinking" ]] && worker_flags+=(--thinking "$thinking") + +# Build judge flags +judge_flags=() +if [[ "$judge_provider" == "codex" ]]; then + judge_flags+=(--mode full-access --provider codex) +elif [[ "$judge_provider" == "claude" ]]; then + judge_flags+=(--mode bypassPermissions) +fi +[[ -n "$judge_model" ]] && judge_flags+=(--model "$judge_model") + +# Worktree flags — passed to every paseo run call +worktree_flags=() +if [[ -n "$worktree" ]]; then + base_branch="$(git branch --show-current 2>/dev/null || echo "main")" + worktree_flags+=(--worktree "$worktree" --base "$base_branch") +fi + +# Judge output schema +judge_schema='{"type":"object","properties":{"criteria_met":{"type":"boolean"},"reason":{"type":"string"}},"required":["criteria_met","reason"],"additionalProperties":false}' + +iteration=0 + +echo "=== Loop started: $name ===" +echo " Loop ID: $loop_id" +echo " State dir: $state_dir" +echo " Plan file: $plan_file" +echo " Last reason file: $last_reason_file" +echo " History log: $history_log" +echo " Steering: edits to plan.md are picked up on the next worker/judge launch." +echo " Worker: $worker_provider ${worker_model:-(default)}" +echo " Judge: $judge_provider ${judge_model:-(default)}" +if [[ -n "$worktree" ]]; then + echo " Worktree: $worktree (base: $base_branch)" +fi +echo " Max iterations: $max_iterations" +echo "" + +while [[ $iteration -lt $max_iterations ]]; do + iteration=$((iteration + 1)) + echo "--- Iteration $iteration/$max_iterations ---" + + if [[ ! -s "$plan_file" ]]; then + echo "Error: plan file is missing or empty: $plan_file" + exit 1 + fi + + current_plan="$(cat "$plan_file")" + last_reason="$(cat "$last_reason_file")" + + # Build worker prompt with plan in XML tags + worker_prompt="Implement the following plan exactly as specified. + + +$current_plan +" + + if [[ -n "$last_reason" ]]; then + worker_prompt="$worker_prompt + + +The previous attempt was verified and did NOT pass. Address the following issues before anything else: + +$last_reason +" + fi + + # Launch worker + worker_name="${name}-work-${iteration}" + echo "Launching worker: $worker_name" + worker_id=$(paseo run -d "${worker_flags[@]}" "${worktree_flags[@]}" --name "$worker_name" "$worker_prompt" -q) + echo "Worker [$worker_name] launched. ID: $worker_id" + echo " Stream logs: paseo logs $worker_id -f" + echo " Inspect: paseo inspect $worker_id" + echo " Wait: paseo wait $worker_id" + + # Wait for worker + echo "" + echo "Waiting for worker to complete..." + paseo wait "$worker_id" + echo "Worker done." + + # Build judge prompt with plan in XML tags + judge_prompt="You are a fact checker. Your ONLY job is to verify whether the plan below was implemented correctly and completely. + +Inspect the codebase independently. Do NOT fix anything. Do NOT suggest fixes. Do NOT provide guidance. + + +$current_plan + + + +Verify that every step of the plan has been implemented to the letter. If the plan contains acceptance criteria, check each one individually. + +Report ONLY facts: +- criteria_met: true if the ENTIRE plan is implemented correctly, false if ANY part is missing or wrong +- reason: for each item in the plan, state whether it was implemented correctly with evidence (file contents, test output, etc.). Be specific about what passed and what failed. +" + + # Launch judge (blocking, structured output) + judge_name="${name}-verify-${iteration}" + echo "" + echo "Launching judge: $judge_name (synchronous, blocks until verdict)" + verdict=$(paseo run "${judge_flags[@]}" "${worktree_flags[@]}" --name "$judge_name" --output-schema "$judge_schema" "$judge_prompt") + echo "Verdict: $verdict" + + # Parse verdict + criteria_met=$(echo "$verdict" | jq -r '.criteria_met') + reason=$(echo "$verdict" | jq -r '.reason') + printf '[%s] iteration=%s worker_id=%s judge=%s criteria_met=%s reason=%s\n' \ + "$(date -u +'%Y-%m-%dT%H:%M:%SZ')" \ + "$iteration" \ + "$worker_id" \ + "$judge_name" \ + "$criteria_met" \ + "$(echo "$reason" | tr '\n' ' ')" >> "$history_log" + + if [[ "$criteria_met" == "true" ]]; then + echo "" + echo "=== Loop complete: criteria met on iteration $iteration ===" + echo "Reason: $reason" + echo "" + echo "Review the final worker's changes:" + echo " paseo logs $worker_id" + echo " paseo inspect $worker_id" + exit 0 + fi + + echo "Criteria not met: $reason" + echo "Starting next iteration..." + + # Keep only the latest judge reason for the next worker iteration. + printf '%s\n' "$reason" > "$last_reason_file" + + echo "" +done + +echo "=== Loop exhausted: $max_iterations iterations without meeting criteria ===" +exit 1 diff --git a/skills/paseo/SKILL.md b/skills/paseo/SKILL.md new file mode 100644 index 000000000..4e372072e --- /dev/null +++ b/skills/paseo/SKILL.md @@ -0,0 +1,222 @@ +--- +name: paseo +description: Use when entering orchestrator mode to manage agents via Paseo CLI +--- + +### Paseo CLI Commands + +Use these CLI commands to manage agents: + +```bash +# List agents (directory-scoped by default) +paseo ls # Only shows agents for current directory +paseo ls -g # All agents across all projects (global) +paseo ls --json # JSON output for parsing + +# Create and run an agent (blocks until completion by default) +paseo run --mode bypassPermissions "" +paseo run --mode bypassPermissions --name "Task Name" "" +paseo run --mode bypassPermissions --model opus "" +paseo run --mode full-access --provider codex "" + +# UI visible agents +paseo run --ui "hello" + +# Detached mode - runs in background, returns agent ID immediately +paseo run --detach "" +paseo run -d "" # Short form + +# Structured output - agent returns only matching JSON +paseo run --output-schema '{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}' "" +paseo run --output-schema schema.json "" # Or from a file +# NOTE: --output-schema blocks until completion (cannot be used with --detach) + +# Worktrees - isolated git worktree for parallel feature development +paseo run --worktree feature-x "" + +# Check agent logs/output +paseo logs +paseo logs -f # Follow (stream) +paseo logs --tail 10 # Last 10 entries +paseo logs --filter tools # Only tool calls + +# Wait for agent to complete or need permission +paseo wait +paseo wait --timeout 60 # 60 second timeout + +# Send follow-up prompt to running agent +paseo send "" +paseo send --image screenshot.png "" # With image +paseo send --no-wait "" # Queue without waiting + +# Inspect agent details +paseo inspect + +# Interrupt an agent's current run +paseo stop + +# Hard-delete an agent (interrupts first if needed) +paseo delete + +# Attach to agent output stream (Ctrl+C to detach without stopping) +paseo attach + +# Permissions management +paseo permit ls # List pending permission requests +paseo permit allow # Allow all pending for agent +paseo permit deny --all # Deny all pending + +# Agent mode switching +paseo agent mode --list # Show available modes +paseo agent mode bypass # Set bypass mode + +# Output formats +paseo ls --json # JSON output +paseo ls -q # IDs only (quiet mode, useful for scripting) +``` + +## UI + +By default agents you run are not visible in the UI, use the `--ui` flags so that they're visible. + +### Available Models + +**Claude (default provider)** - use aliases, CLI resolves to latest version: +- `--model haiku` - Fast/cheap, ONLY for tests (not for real work) +- `--model sonnet` - Default, good for most tasks +- `--model opus` - For harder reasoning, complex debugging + +**Codex** (`--provider codex`): +- `--model gpt-5.4` - Latest frontier agentic coding model (default, preferred for all engineering tasks) +- `--model gpt-5.1-codex-mini` - Cheaper, faster, but less capable + +### Permissions + +Always launch agents fully permissioned. Use `--mode bypassPermissions` for Claude and `--mode full-access` for Codex. Control behavior through **strict prompting**, not permission modes. + +### Agent Use Cases + +You can run agents to: +- **Implement a task** - Spawn an agent to write code and implement features +- **Have a design discussion** - Use Codex for architecture discussions +- **Test some feature** - Run tests and verify functionality +- **Do investigation** - Research and explore the codebase +- **Review changes** - Use Codex for thorough code reviews + +### Clarifying Ambiguous Requests + +**CRITICAL:** When user requests are ambiguous or unclear: + +1. **Research first** - Spawn an investigation agent to understand the current state +2. **Ask clarifying questions** - After research, ask the user specific questions about what they want +3. **Present options** - Offer multiple approaches with trade-offs +4. **Get explicit confirmation** - Never assume what the user wants + +### Investigation vs Implementation + +**CRITICAL:** When asked to investigate: + +- **Investigation agents MUST NOT fix issues** - They should only identify, document, and report problems +- **Always ask for confirmation** - After investigation, present findings and ask: "Should I proceed with implementing fixes?" +- **Only implement if explicitly requested** - Don't auto-fix without user approval + +### Rigorous Agent Interrogation + +**CRITICAL:** Agents start with ZERO context about your task. You must always provide complete context in your initial prompt. + +When working with agents, you must dig deep and challenge them rigorously: + +#### For Implementation Agents + +- **Don't accept surface-level completion**: Check their logs with `paseo logs ` +- **Trace the implementation**: Ask them to walk through the code flow step by step +- **Uncover gaps**: Send follow-up prompts with `paseo send ""` + - "Show me exactly where you handle error case X" + - "What happens if the user does Y before Z?" + - "Walk me through the data flow from input to output" + +#### For Investigation/Debugging Agents + +- **Don't stop at the first answer**: Keep digging deeper +- **Explore different angles**: "What are 3 other possible causes?" +- **Request proof**: "Show me the specific code that proves this hypothesis" +- **Challenge assumptions**: "How do you know that's the root cause?" + +#### For Review Agents (prefer Codex) + +- **Security review**: "What are the security implications? Any OWASP vulnerabilities?" +- **Edge cases**: "What edge cases are not handled?" +- **Performance**: "Where are the performance bottlenecks?" +- **Maintainability**: "How maintainable is this code?" + +### Waiting for Agents + +**CRITICAL:** `paseo wait` blocks until the agent completes. Trust it. + +- Agent tasks can legitimately take 10, 20, or even 30+ minutes. This is normal. +- When `paseo wait` times out, **just re-run `paseo wait `** — don't panic, don't start checking logs, don't inspect status. The agent is still working. +- Do NOT poll with `paseo ls`, `paseo inspect`, or `paseo logs` in a loop to "check on" the agent. This wastes your context window and accomplishes nothing. +- Only check logs/inspect if you have a **specific reason** to believe something is wrong (e.g., you sent a prompt and got an unexpected error back). +- **Never launch a duplicate agent** because a wait timed out. The original is still running. + +```bash +# Correct: just keep waiting +paseo wait # timed out? just run it again: +paseo wait # still going? keep waiting: +paseo wait --timeout 300 # or use a longer timeout + +# Wrong: anxious polling loop +paseo wait # timed out +paseo ls # is it still running?? +paseo inspect # what's it doing?? +paseo logs # let me check the logs!! +# ^ Don't do this. Trust the wait. +``` + +### Agent Management Principles + +- **Keep agents focused** - Each agent should have a clear, specific responsibility +- **You can talk to them** - Use `paseo send ""` to guide them +- **Monitor progress** - Use `paseo logs -f` to stream output +- **Always provide context** - Remember: agents start with zero knowledge of your task +- **Verify work rigorously** - Don't trust, verify. Ask agents to prove their work +- **Commit frequently** - Ensure each agent commits their changes before moving on +- **Plan for quality gates** - Use Codex review agents as checkpoints +- **Run in parallel when possible** - Use `-d` flag to run multiple agents concurrently + +### Common Patterns + +#### Committee + +When stuck or planning something hard, use the `/committee` skill. It launches two high-reasoning agents (Opus 4.6 + GPT 5.4) in parallel to do root cause analysis and produce a plan, then stays alive to review the implementation afterward. + +### Composing Agents in Bash Scripts + +`paseo run` blocks by default and `--output-schema` returns structured JSON, making it easy to compose agents in bash loops and pipelines. + +**Implement-and-verify loop:** +```bash +while true; do + paseo run --provider codex "make the tests pass" >/dev/null + + verdict=$(paseo run --provider claude --output-schema '{"type":"object","properties":{"criteria_met":{"type":"boolean"}},"required":["criteria_met"],"additionalProperties":false}' "ensure tests all pass") + if echo "$verdict" | jq -e '.criteria_met == true' >/dev/null; then + echo "criteria met" + break + fi +done +``` + +**Detach + wait pattern for parallel work:** +```bash +# Kick off parallel agents +api_id=$(paseo run -d --name "API impl" "implement the API" -q) +ui_id=$(paseo run -d --name "UI impl" "implement the UI" -q) + +# Wait for both to finish +paseo wait "$api_id" +paseo wait "$ui_id" + +# Review the combined result +paseo run --provider codex "review the API and UI implementations. DO NOT edit." +```