diff --git a/.paseo/playbooks/defaults/main.yaml b/.paseo/playbooks/defaults/main.yaml
new file mode 100644
index 000000000..698a94329
--- /dev/null
+++ b/.paseo/playbooks/defaults/main.yaml
@@ -0,0 +1,12 @@
+agent:
+ provider: omp
+ model: anthropic/claude-haiku-5-5
+ mode: full
+manager:
+ provider: omp
+ model: anthropic/claude-haiku-5-5
+ mode: full
+timeout: 2h
+role:
+ silence: 30m
+ archive_agents: true
diff --git a/.paseo/playbooks/defaults/manager.md b/.paseo/playbooks/defaults/manager.md
new file mode 100644
index 000000000..643f83f4e
--- /dev/null
+++ b/.paseo/playbooks/defaults/manager.md
@@ -0,0 +1,14 @@
+# Playbook Manager Instructions
+
+You are the Playbook Manager supervising execution of Devsy playbooks.
+Follow the playbook protocol strictly.
+
+## Manager Responsibilities
+
+1. Read inputs and start ready steps using start_step.
+2. Provide concise and focused briefs to step agents.
+3. Validate step outputs upon step completion.
+4. Open gates for human decisions using request_gate.
+5. Relay feedback to target steps when loops trigger.
+6. Enforce zero tracker references across all commits and pull requests.
+7. Ensure all subagents run in standard normal mode with fast mode disabled.
diff --git a/.paseo/playbooks/devsy-fix.yaml b/.paseo/playbooks/devsy-fix.yaml
new file mode 100644
index 000000000..103fe9bc0
--- /dev/null
+++ b/.paseo/playbooks/devsy-fix.yaml
@@ -0,0 +1,95 @@
+title: Devsy Fix and PR Pipeline
+description: Investigate, implement, validate, review, and merge a verified bug fix in Devsy.
+concurrency: 1
+
+inputs:
+ fingerprint:
+ type: string
+ required: true
+ description: Normalized failure fingerprint
+ description:
+ type: string
+ required: true
+ description: Description of the failure or issue
+ failing_step:
+ type: string
+ default: unspecified
+ description: Failing CI step or component
+
+outputs:
+ pr_url:
+ type: string
+ value: "{{ steps.implement.outputs.pr_url }}"
+ commit_sha:
+ type: string
+ value: "{{ steps.implement.outputs.commit_sha }}"
+
+steps:
+ - id: investigate
+ role:
+ name: ci-investigator
+ prompt: "Investigate failure: {{ inputs.description }}.\nFingerprint: {{ inputs.fingerprint }}.\nFailing step: {{ inputs.failing_step }}."
+ inputs: [fingerprint, description, failing_step]
+ outputs:
+ root_cause: { type: string }
+ repro_command: { type: string }
+ fix_hypothesis: { type: string }
+ outcomes: [success, failure, already_resolved]
+ on:
+ already_resolved: end
+ - id: approve_plan
+ needs: [investigate]
+ gate:
+ question: "Root cause identified. Approve fix hypothesis to begin implementation, or request changes."
+ choices:
+ approved: { label: Approve and Implement, color: success }
+ rejected: { label: Request Changes, comment: required, color: danger }
+ on:
+ rejected: { goto: investigate }
+
+ - id: implement
+ needs: [approve_plan]
+ role:
+ name: fix-worker
+ prompt: "Implement approved fix for {{ inputs.fingerprint }}. Loop {{ loop }}.\nHypothesis: {{ inputs.fix_hypothesis }}.\nRoot cause: {{ inputs.root_cause }}.\nRepro: {{ inputs.repro_command }}.\nIf loop is greater than 0, apply changes to the existing open pull request branch and push with force-with-lease instead of opening a duplicate PR."
+ inputs:
+ fingerprint: "{{ playbook.inputs.fingerprint }}"
+ fix_hypothesis: "{{ steps.investigate.outputs.fix_hypothesis }}"
+ root_cause: "{{ steps.investigate.outputs.root_cause }}"
+ repro_command: "{{ steps.investigate.outputs.repro_command }}"
+ outputs:
+ pr_url: { type: string }
+ commit_sha: { type: string }
+ outcomes: [success, failure, already_resolved]
+ on:
+ already_resolved: end
+ - id: wait_ci
+ needs: [implement]
+ script:
+ run: wait_ci.sh
+ poll: 30s
+ timeout: 45m
+ inputs:
+ pr_url: "{{ steps.implement.outputs.pr_url }}"
+ outcomes: [success, failure]
+ on:
+ failure: { goto: implement }
+
+ - id: approve_pr
+ needs: [wait_ci]
+ gate:
+ question: "All CI status checks have passed and PR is green. Review and approve to merge, or request changes."
+ choices:
+ approved: { label: Approve and Merge, color: success }
+ changes_requested: { label: Request Changes, comment: required, color: danger }
+ on:
+ changes_requested: { goto: implement }
+ - id: merge
+ needs: [approve_pr]
+ role:
+ name: fix-worker
+ prompt: "Run gh pr ready {{ inputs.pr_url }} to mark the draft pull request ready for review. Then merge pull request {{ inputs.pr_url }}. Retrieve PR title and number using gh pr view {{ inputs.pr_url }} --json title,number. Run squash merge with one-line subject and empty body: gh pr merge {{ inputs.pr_url }} --squash --delete-branch --subject \"
(#)\" --body \"\". Verify commit message is single line."
+ inputs:
+ pr_url: "{{ steps.implement.outputs.pr_url }}"
+ outputs:
+ merge_status: { type: string }
diff --git a/.paseo/playbooks/roles/ci-investigator/instructions.md b/.paseo/playbooks/roles/ci-investigator/instructions.md
new file mode 100644
index 000000000..a77357cc1
--- /dev/null
+++ b/.paseo/playbooks/roles/ci-investigator/instructions.md
@@ -0,0 +1,28 @@
+You are a read-only investigation agent for devsy-org/devsy.
+Your task is performing root cause analysis on a reported bug or CI failure.
+
+## Guidelines
+
+1. Check for existing open pull requests targeting this failure:
+ gh pr list -R devsy-org/devsy --state open --search ""
+ If an open pull request already exists, report outcome: already_resolved with the active PR URL in summary.
+2. Locate the failing signature and inspect relevant logs, workflows, and source files.
+3. Identify the root cause with exact file paths and line numbers.
+4. Formulate a minimal reproduction command or test case.
+5. Formulate a minimal fix hypothesis adhering to devsy-pr-ready.
+6. Never edit files, create commits, push branches, or open pull requests.
+7. Populate required outputs: root_cause, repro_command, and fix_hypothesis.
+8. If the failure has already been resolved on origin/main, report outcome: already_resolved.
+
+## Output Template
+
+Structure your final summary using this template:
+
+### Root Cause
+Exact file paths and line numbers causing the failure.
+
+### Reproduction Command
+Deterministic command or test demonstrating the issue.
+
+### Proposed Fix Hypothesis
+Minimal behavior-preserving change adhering to devsy-pr-ready.
diff --git a/.paseo/playbooks/roles/ci-investigator/role.yaml b/.paseo/playbooks/roles/ci-investigator/role.yaml
new file mode 100644
index 000000000..08c5d2603
--- /dev/null
+++ b/.paseo/playbooks/roles/ci-investigator/role.yaml
@@ -0,0 +1,6 @@
+title: CI Investigator
+readonly: true
+agent:
+ provider: omp
+ model: openai-codex/gpt-6.1-terra
+ mode: full
diff --git a/.paseo/playbooks/roles/fix-worker/instructions.md b/.paseo/playbooks/roles/fix-worker/instructions.md
new file mode 100644
index 000000000..37d61fe69
--- /dev/null
+++ b/.paseo/playbooks/roles/fix-worker/instructions.md
@@ -0,0 +1,36 @@
+You are the fix implementation worker for devsy-org/devsy.
+Your task is implementing verified bug fixes and opening pull requests adhering strictly to devsy-pr-ready.
+When the prompt asks you to merge a pull request, perform only the merge instructions in the prompt and skip the guidelines below.
+
+## Implementation Guidelines
+
+1. When the prompt reports loop 0, check for open pull requests targeting this failure:
+ gh pr list -R devsy-org/devsy --state open --search ""
+ If an open pull request already exists, report outcome: already_resolved and exit without opening a duplicate pull request.
+ When the prompt reports a loop greater than 0, skip this check. Apply the changes to the existing open pull request branch, push with force-with-lease, and report that pull request as pr_url.
+2. Minimal behavior-preserving changes and targeted regression tests.
+3. Self-documenting code with plain ASCII text. Do not add redundant comments.
+4. Run local validation:
+ mkdir -p dist
+ mise run cli:format
+ mise run cli:lint:ci
+ mise run cli:test
+5. Create signed conventional commit using the host configured git identity:
+ git commit -S -m "fix(scope): concise subject"
+6. Run CodeRabbit review on committed changes:
+ coderabbit review --agent --committed --base-commit $(git merge-base HEAD origin/main)
+ If CodeRabbit reports actionable findings, fix them, revalidate, and amend:
+ git commit -S --amend --no-edit
+7. Open draft pull request strictly under 100 words in three sections using this template:
+ ## Cause
+ Concise cause description under 30 words.
+
+ ## Fix
+ Concise fix description under 30 words.
+
+ ## Test evidence
+ Validation commands run and test output summary.
+ devsy-fingerprint:
+8. Zero tracker references: no issue numbers, tracker URLs, or tracker labels in commit messages, branch names, PR titles, or PR descriptions.
+9. Populate required step outputs: pr_url and commit_sha.
+10. If the fix has already been merged into origin/main, report outcome: already_resolved without opening a duplicate pull request.
diff --git a/.paseo/playbooks/roles/fix-worker/role.yaml b/.paseo/playbooks/roles/fix-worker/role.yaml
new file mode 100644
index 000000000..f73fb3f13
--- /dev/null
+++ b/.paseo/playbooks/roles/fix-worker/role.yaml
@@ -0,0 +1,6 @@
+title: Fix Worker
+readonly: false
+agent:
+ provider: omp
+ model: openai-codex/gpt-6.1-terra
+ mode: full
diff --git a/.paseo/playbooks/scripts/wait_ci.sh b/.paseo/playbooks/scripts/wait_ci.sh
new file mode 100755
index 000000000..0d3806431
--- /dev/null
+++ b/.paseo/playbooks/scripts/wait_ci.sh
@@ -0,0 +1,3 @@
+#!/bin/sh
+set -eu
+exec mise run playbooks:wait-ci -- "$@"
diff --git a/mise.toml b/mise.toml
index 94780afa6..9fa7da137 100644
--- a/mise.toml
+++ b/mise.toml
@@ -317,3 +317,40 @@ cp dist/devsy-dev_linux_amd64_v1/devsy-linux-amd64 "$TMP_DIR/devsy-linux-amd64"
gh release upload v0.0.0-10 dist/devsy-dev_linux_amd64_v1/devsy-linux-amd64 --repo devsy-org/devsy --clobber
rm -rf "$TMP_DIR"
'''
+
+[tasks."playbooks:wait-ci"]
+description = "poll GitHub PR status checks for a playbook run; exits 75 while checks are pending"
+shell = "bash -c"
+run = '''
+set -eu
+
+PR="${PLAYBOOK_INPUT_PR_URL:-${1:-}}"
+if [ -z "$PR" ]; then
+ echo '{"outcome":"failure","summary":"Missing PR URL in PLAYBOOK_INPUT_PR_URL"}'
+ exit 0
+fi
+
+CHECKS_JSON=$(gh pr checks "$PR" --json name,bucket,state 2>/dev/null || echo "")
+
+if [ -z "$CHECKS_JSON" ] || [ "$CHECKS_JSON" = "[]" ]; then
+ exit 75
+fi
+
+PENDING=$(echo "$CHECKS_JSON" | jq '[.[] | select(.bucket == "pending")] | length')
+if [ "$PENDING" -gt 0 ]; then
+ exit 75
+fi
+
+FAILURES=$(echo "$CHECKS_JSON" | jq -r '[.[] | select(.bucket == "fail" or .bucket == "cancel")] | .[].name' | tr '\n' ', ' | sed 's/,[[:space:]]*$//')
+if [ -n "$FAILURES" ]; then
+ jq -nc --arg f "$FAILURES" '{outcome:"failure",summary:("CI status checks failed: "+$f)}'
+ exit 0
+fi
+
+PASSING=$(echo "$CHECKS_JSON" | jq '[.[] | select(.bucket == "pass")] | length')
+if [ "$PASSING" -eq 0 ]; then
+ exit 75
+fi
+
+jq -nc --arg count "$PASSING" '{outcome:"success",summary:("All "+$count+" necessary CI status checks have passed.")}'
+'''