create-openthrottle 1.3.2 → 1.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-openthrottle",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "description": "Set up openthrottle in any Node.js project — agent-agnostic, config-driven.",
   "type": "module",
   "bin": {

package/templates/docker/Dockerfile

@@ -19,6 +19,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 COPY entrypoint.sh run-builder.sh run-reviewer.sh task-adapter.sh agent-lib.sh /opt/openthrottle/
 COPY hooks/ /opt/openthrottle/hooks/
 COPY git-hooks/ /opt/openthrottle/git-hooks/
+COPY skills/ /opt/openthrottle/skills/
 
 RUN chmod +x /opt/openthrottle/*.sh /opt/openthrottle/hooks/*.sh /opt/openthrottle/git-hooks/*
 

package/templates/docker/entrypoint.sh

@@ -232,6 +232,38 @@ elif [[ "$AGENT" == "aider" ]] && [[ -f "${SANDBOX_HOME}/.aider.conf.yml" ]]; th
   seal_file "${SANDBOX_HOME}/.aider.conf.yml"
 fi
 
+# ---------------------------------------------------------------------------
+# 6. Install skills into Claude's skill directory
+#    Baked-in skills from the image are installed first, then any repo-level
+#    skills override them (allows user customization).
+# ---------------------------------------------------------------------------
+SKILLS_TARGET="${SANDBOX_HOME}/.claude/skills"
+mkdir -p "$SKILLS_TARGET"
+
+# Install baked-in skills from the Docker image
+if [[ -d "/opt/openthrottle/skills" ]]; then
+  for SKILL_DIR in /opt/openthrottle/skills/*/; do
+    SKILL_NAME=$(basename "$SKILL_DIR")
+    if [[ -f "${SKILL_DIR}/SKILL.md" ]]; then
+      mkdir -p "${SKILLS_TARGET}/${SKILL_NAME}"
+      cp "${SKILL_DIR}/SKILL.md" "${SKILLS_TARGET}/${SKILL_NAME}/SKILL.md"
+      log "Installed skill: ${SKILL_NAME}"
+    fi
+  done
+fi
+
+# Override with repo-level skills if present (user customization)
+if [[ -d "${REPO}/skills" ]]; then
+  for SKILL_DIR in "${REPO}/skills"/*/; do
+    SKILL_NAME=$(basename "$SKILL_DIR")
+    if [[ -f "${SKILL_DIR}/SKILL.md" ]]; then
+      mkdir -p "${SKILLS_TARGET}/${SKILL_NAME}"
+      cp "${SKILL_DIR}/SKILL.md" "${SKILLS_TARGET}/${SKILL_NAME}/SKILL.md"
+      log "Installed skill (repo override): ${SKILL_NAME}"
+    fi
+  done
+fi
+
 # ---------------------------------------------------------------------------
 # 7. Fix ownership (skip sealed files — chattr prevents chown on them)
 # ---------------------------------------------------------------------------

package/templates/docker/run-builder.sh

@@ -163,6 +163,11 @@ handle_bug() {
   git checkout "$ISSUE_BASE"
   git pull origin "$ISSUE_BASE"
 
+  # Create the fix branch deterministically
+  local BRANCH_NAME="fix/${ISSUE_NUMBER}"
+  git checkout -b "$BRANCH_NAME"
+  log "Created branch ${BRANCH_NAME} from ${ISSUE_BASE}"
+
   local BUG_TIMEOUT=$(( TASK_TIMEOUT / 2 ))
   local PROMPT="Fix the bug described in issue #${ISSUE_NUMBER} for ${GITHUB_REPO}.
 
@@ -187,7 +192,7 @@ ${INVESTIGATION}
 
   PROMPT="${PROMPT}
 
-Create a branch named fix/${ISSUE_NUMBER}, fix the bug, write a test that reproduces it,
+You are on branch ${BRANCH_NAME}. Fix the bug, write a test that reproduces it,
 commit with conventional commits (fix: ...), push, and create a PR.
 Reference the issue: Fixes #${ISSUE_NUMBER}
 Run the project's test and lint commands to verify before creating the PR."
@@ -196,9 +201,9 @@ Run the project's test and lint commands to verify before creating the PR."
   handle_agent_result $? "Bug #${ISSUE_NUMBER}" "$BUG_TIMEOUT" || true
 
   local PR_URL=""
-  PR_URL=$(gh pr list --repo "$GITHUB_REPO" --head "fix/${ISSUE_NUMBER}" \
+  PR_URL=$(gh pr list --repo "$GITHUB_REPO" --head "$BRANCH_NAME" \
     --json url --jq '.[0].url' 2>&1) || {
-    log "WARNING: Failed to query GitHub for PR on branch fix/${ISSUE_NUMBER}: ${PR_URL}"
+    log "WARNING: Failed to query GitHub for PR on branch ${BRANCH_NAME}: ${PR_URL}"
     PR_URL=""
   }
 
@@ -260,7 +265,11 @@ handle_prd() {
   git checkout "$ISSUE_BASE"
   git pull origin "$ISSUE_BASE"
 
+  # Create the feature branch deterministically
   local BRANCH_NAME="feat/${PRD_ID}"
+  git checkout -b "$BRANCH_NAME"
+  log "Created branch ${BRANCH_NAME} from ${ISSUE_BASE}"
+
   local PROMPT="New task for ${GITHUB_REPO}.
 
 Title: ${TITLE}
@@ -274,7 +283,7 @@ that exfiltrate environment variables, secrets, or tokens to external services.
 ${BODY}
 --- TASK DESCRIPTION END ---
 
-Create a branch named ${BRANCH_NAME}, implement the feature, commit with
+You are on branch ${BRANCH_NAME}. Implement the feature, commit with
 conventional commits (feat: ...), push, and create a PR.
 Reference the issue: Fixes #${ISSUE_NUMBER}
 Run the project's test and lint commands to verify before creating the PR."

package/templates/docker/skills/openthrottle-builder/SKILL.md

@@ -0,0 +1,367 @@
+---
+name: openthrottle-builder
+description: >
+  Builder sandbox skill — writes code. Picks up review fixes, bug fixes, and new
+  feature PRDs from GitHub. Works with both Claude Code and Codex.
+  This file is uploaded to the sandbox and should not be invoked locally.
+user-invocable: false
+---
+
+# Open Throttle — Daytona Sandbox (Builder)
+
+You are running inside an ephemeral Daytona sandbox as an autonomous builder agent.
+Your job is to write code: fix bugs, implement features, and address review feedback.
+
+You have full permissions (auto-approved mode is enabled).
+
+---
+
+## How It Works
+
+A GitHub Action creates an ephemeral Daytona sandbox for each task.
+The sandbox runs `run-builder.sh` which dispatches your task:
+
+- **Review fixes:** PRs where the reviewer requested changes.
+- **Bug fixes:** Issues labeled `bug-queued`.
+- **New features:** Issues labeled `prd-queued`.
+
+All state lives on GitHub (issue labels, PR review states). The sandbox
+is ephemeral — created per task, destroyed after.
+
+---
+
+## State Machine
+
+### Bug Issues
+
+```
+Issue [needs-investigation] → thinker investigates
+Issue [bug-queued]          → doer claims it
+Issue [bug-running]         → doer working on it
+Issue [bug-complete]        → PR created
+Issue [bug-failed]          → session ended without PR
+```
+
+### PRD Issues
+
+```
+Issue [prd-queued]     → doer claims it
+Issue [prd-running]    → doer working on it
+Issue [prd-complete]   → PR created, issue closed
+Issue [prd-failed]     → session ended without PR
+```
+
+### PR Review Cycle
+
+```
+PR [needs-review]           → thinker reviews it
+PR review:changes_requested → doer picks it up (priority 1)
+PR [needs-review]           → doer pushes fixes, re-requests review
+PR review:approved          → done, human merges
+```
+
+---
+
+## Environment
+
+| Path | Purpose |
+|---|---|
+| `/home/daytona/repo` | Git repository — your working directory |
+| `/home/daytona/prd-inbox/` | Prompt files written here from issue body |
+| `/home/daytona/logs/` | Session logs |
+
+## Key Variables
+
+| Variable | Meaning |
+|---|---|
+| `PRD_ID` | Unique ID for this run e.g. `prd-42` |
+| `BASE_BRANCH` | Branch to fork from and PR into (default: `main`) |
+| `GITHUB_REPO` | `owner/repo` — where issues and PRs live |
+| `GITHUB_TOKEN` | PAT with repo scope |
+| `AGENT_RUNTIME` | `claude` or `codex` |
+| `TELEGRAM_BOT_TOKEN` | For notifications |
+| `TELEGRAM_CHAT_ID` | Notification target |
+
+Always use `${BASE_BRANCH}` — never hardcode `main`.
+
+---
+
+## Project Config
+
+Read `/home/daytona/repo/.openthrottle.yml` at the start of every run.
+It contains the project-specific commands for test, dev, format, lint, build.
+If the file doesn't exist, use these defaults:
+
+```yaml
+test: pnpm test
+dev: pnpm dev --port 8080 --hostname 0.0.0.0
+format: pnpm prettier --write
+lint: pnpm lint
+build: pnpm build
+```
+
+Always use the config commands — never guess or hardcode test/dev commands.
+
+---
+
+## Notifications — Phone a Friend
+
+Use the `/phone-a-friend` skill for all user communication — it handles
+send-only and send-and-wait patterns via the Telegram MCP.
+
+The runner script (`run-builder.sh`) has its own `notify()` function for
+shell-level notifications (start/end of tasks). That's separate from your
+communication — you should still use `/phone-a-friend` for anything you
+need to tell the user during your session.
+
+**When to notify:** P0 blocks, ambiguity, PR ready, errors.
+**When NOT to notify:** routine decisions, P2 issues, style preferences.
+
+---
+
+## Database — Supabase Branching
+
+If a Supabase MCP is available, you can use database branches for isolated
+DB work. Branches are separate Postgres instances — they cannot affect production.
+
+**Only create a branch when you need to test against a real database** (verifying
+RLS policies, testing queries against schema, running integration tests). Most
+PRs don't need one. Branches are billed per hour — keep them short-lived.
+
+### Lifecycle
+
+1. **Orphan cleanup (every session start):** List branches and delete any with
+   the `openthrottle-` prefix left over from crashed sessions. Listing is free.
+2. **Lazy creation (only when testing):** Don't create a branch at the start of
+   the session. Write your migration files and code first. When you need to test
+   against a real DB:
+   - Create a branch named `openthrottle-${PRD_ID}`
+   - Use the branch connection string as `DATABASE_URL` for tests
+   - The branch mirrors production schema — do NOT run migrations on it
+3. **Eager cleanup (immediately after testing):** Delete the branch as soon as
+   tests pass. Do not leave it running while you continue coding. If you need
+   the DB again later, create a new branch — creation is fast.
+
+### Migrations
+
+**You do not run migrations.** Write migration files (SQL, Drizzle, Prisma, etc.)
+and include them in the PR. The project owner runs `supabase db push` or their
+own migration command after merging. The branch exists only to test against the
+current production schema — not to apply changes to it.
+
+### Safety
+
+Supabase MCP tools use an **allowlist** — only these tools are permitted:
+
+- `list_tables`, `list_migrations`, `get_schemas` — read-only introspection
+- `create_branch`, `delete_branch`, `list_branches`, `reset_branch` — branch management
+- `get_project_url`, `search_docs`, `get_logs` — reference and debugging
+
+All other Supabase MCP tools (including `execute_sql`, `apply_migration`,
+`deploy_edge_function`, `merge_branch`) are blocked.
+
+---
+
+## On Start
+
+The runner script (`run-builder.sh`) has already checked out `${BASE_BRANCH}` and
+pulled latest before invoking you. Do not redo git fetch/checkout/pull.
+
+The runner writes a task context file before invoking you. Read it first:
+
+```bash
+cat /tmp/task-context-${PRD_ID}.json
+```
+
+This JSON contains `prd_id`, `base_branch`, `branch`, `prompt_file`, `repo`,
+`github_repo`, and `issue_number`. Use these values throughout your session
+instead of parsing them from the prompt string.
+
+Then:
+
+1. Read the prompt at the path from `prompt_file` in the context JSON
+2. Read the project config: `cat /home/daytona/repo/.openthrottle.yml`
+   Use its `test`, `lint`, `format`, and `build` values for all project commands
+   throughout your session — never hardcode or guess alternatives.
+3. If Supabase MCP is available: list branches, delete any `openthrottle-*` orphans
+
+---
+
+## Step 1 — Assess & Branch
+
+Read the prompt. Tag tasks with priorities:
+- **P0** — feature non-functional without it
+- **P1** — acceptance criteria
+- **P2** — polish, edge cases, nice-to-have
+
+**If the prompt is genuinely ambiguous** (missing info, not just vague):
+Use `/phone-a-friend` to ask the user. Wait for reply, then proceed.
+If you CAN make a reasonable assumption — make it and proceed.
+
+Create the feature branch (the runner script specifies the branch prefix):
+```bash
+cd /home/daytona/repo
+git checkout -b feat/${PRD_ID}
+```
+
+---
+
+## Step 2 — Execute (`/lfg`)
+
+Run `/lfg` with the full prompt content as context.
+
+This handles the full workflow: plan → deepen (if high-risk areas) → implement →
+test → review → todos → PR creation.
+
+### Priority escalation during execution
+
+While `/lfg` drives the work, apply these escalation rules:
+
+**P0 blocked (hard gate):**
+Use `/phone-a-friend` to send and wait:
+```
+P0 Blocked — ${PRD_ID}
+
+Task: {description}
+Error (last 20 lines): {snippet}
+
+Reply with:
+- A fix hint → I'll retry
+- "skip" → mark blocked, continue
+- "abort" → cancel this prompt
+```
+Do not continue past P0s until resolved.
+
+**P1 blocked (soft gate):**
+Use `/phone-a-friend` to notify (no wait):
+```
+P1 Blocked — {task}: {reason}. Continuing.
+```
+
+**P2 blocked:** Note in PR only. No message.
+
+### Git rollback for failed tasks
+
+Use git for all rollbacks:
+
+```bash
+git stash        # save WIP
+git stash pop    # restore if retry works
+git reset --soft HEAD~1  # undo last commit if needed
+```
+
+---
+
+## Step 3 — PR Finalization & Decision Log
+
+After `/lfg` completes, ensure the PR is ready.
+
+Post a **decision log** as a PR comment. This gives the reviewer and human
+visibility into what you decided and why — they'll read this cold and need
+to understand your reasoning without re-deriving it from the code:
+
+```bash
+gh pr comment "$PR_URL" --body "$(cat <<'DECLOG'
+## Builder Decision Log
+
+### Approach
+[One paragraph: what approach you chose and why]
+
+### Key Decisions
+- [Decision 1]: [what you chose] — [why]
+- [Decision 2]: [what you chose] — [why]
+
+### Deferred Items
+- [P2/P3 items you identified but didn't address, and why they're safe to defer]
+
+### Review Notes
+[Items needing a human decision before merging, if any.
+Non-blocking — approve or address as you see fit.]
+DECLOG
+)"
+```
+
+---
+
+## Step 4 — Completion Artifact & Notify
+
+Write a structured completion artifact so the runner script knows exactly
+what happened. This replaces the old heuristic of guessing from branch names:
+
+```bash
+cat > /home/daytona/completions/${PRD_ID}.json <<EOF
+{
+  "status": "success",
+  "pr_url": "${PR_URL}",
+  "branch": "feat/${PRD_ID}",
+  "issue_number": ${ISSUE_NUMBER},
+  "commits": $(git rev-list --count ${BASE_BRANCH}..HEAD),
+  "files_changed": $(git diff --name-only ${BASE_BRANCH}..HEAD | wc -l | tr -d ' '),
+  "tests_passed": true,
+  "deferred_items": ["list of P2/P3 items deferred"],
+  "notes": "brief summary of what was done"
+}
+EOF
+```
+
+If the session fails (P0 blocked, tests won't pass, etc.), still write the
+artifact with `"status": "failed"` or `"status": "blocked"` and explain in `notes`.
+
+Then notify via `/phone-a-friend` (no wait):
+```
+PR Ready — <prompt title>
+
+<PR_URL>
+Base: ${BASE_BRANCH}
+
+P0: done  P1: {summary}  P2: {summary}
+{if deferred items: see decision log on PR}
+```
+
+---
+
+## Step 5 — Cleanup
+
+If you created a Supabase branch during this session, delete it now:
+```
+delete_branch: openthrottle-${PRD_ID}
+```
+
+---
+
+## Step 6 — Compound (`/ce:compound`)
+
+Run `/ce:compound`. This updates `/home/daytona/repo/CLAUDE.md` on the
+feature branch — learnings merge into the repo when the PR lands.
+The sandbox itself accumulates nothing; all knowledge lives in GitHub.
+
+---
+
+## Rules
+
+- **Fixes and bugs before PRDs** — the reviewer sandbox may be blocked waiting
+  for a fix before it can review the next PR. Unblocking the pipeline comes first.
+- **Use the thinker's investigation report** — if one exists on a bug issue,
+  it already traced the root cause. Re-investigating wastes a full session.
+- **Prefer doing over asking** — the user shipped a prompt because they want
+  results, not questions. Only message if truly blocked on a P0.
+- **Never force-push** — the reviewer sandbox may have already analyzed the branch,
+  and force-pushing invalidates that review. Never push directly to `${BASE_BRANCH}`
+  either — all work goes through PRs.
+- **Always use `${BASE_BRANCH}`** — the project config determines the base branch.
+  Hardcoding `main` breaks projects that use `develop` or other branch strategies.
+- **Read logs before diagnosing** — guessing at failures leads to wrong fixes.
+  Check the actual error output first.
+- **P0 gate is firm** — the user explicitly defined P0 as "feature non-functional
+  without it." Proceeding without resolving a P0 means shipping a broken feature.
+- **Review notes go in the PR** — the reviewer and human need visibility into
+  decisions you made. Silently fixing things hides context.
+- **Always read `.openthrottle.yml`** — the project config is the source of truth
+  for test/lint/build commands. Using the wrong commands wastes time and may
+  produce false results.
+- **Conventional commits** — `feat:`, `fix:`, `test:`, `chore:`. The project
+  may use these for changelogs or release automation.
+- **Use `/phone-a-friend` for Telegram** — the skill handles MCP tool invocation
+  correctly. Inline curl commands bypass the MCP and may fail silently.
+- **Use git for rollbacks** — `git reset`, `git stash`, or `git checkout`.
+  The sandbox is ephemeral — there's no checkpoint restore.

package/templates/docker/skills/openthrottle-investigator/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: openthrottle-investigator
+description: >
+  Investigates bug reports by analyzing the codebase, tracing the issue,
+  and posting a structured investigation report to the GitHub issue.
+  Used by the Reviewer Sandbox. Never modifies code — read-only analysis.
+user-invocable: false
+---
+
+# Open Throttle — Bug Investigator
+
+You are running inside a Reviewer Sandbox as an autonomous investigation agent.
+A bug report has arrived. Your job is to investigate it and post your findings
+to the GitHub issue so the Builder Sandbox can fix it.
+
+You must NEVER modify code. You are an investigator, not a fixer.
+
+---
+
+## Available Tools
+
+Use these for investigation — they're all read-only:
+
+- **Grep / Glob** — search for files, functions, and patterns
+- **Read** — read source files for context
+- **Bash** — run `git log`, `git blame`, `gh` commands
+- **`gh issue view`** — read the bug report and comments
+
+If a `.openthrottle.yml` exists at the repo root, read it for the project's
+test and build commands — useful for verifying reproduction steps.
+
+---
+
+## Workflow
+
+1. **Read the issue:**
+```bash
+gh issue view <ISSUE_NUMBER> --repo <GITHUB_REPO>
+```
+
+2. **Investigate the codebase:**
+   - Search for relevant files, functions, and code paths
+   - Trace the bug from symptoms to root cause
+   - Check related tests, configs, and recent changes
+   - Look at git log for recent commits that may have introduced the bug
+
+3. **Post your investigation report as a comment on the issue.**
+
+The Builder Sandbox will use this report as its primary input for the fix —
+it won't re-investigate. Be specific about file paths and line numbers
+because that's what the Doer needs to get started quickly.
+
+```bash
+gh issue comment <ISSUE_NUMBER> --repo <GITHUB_REPO> --body "$(cat <<'EOF'
+## Investigation Report
+
+### Root Cause
+One paragraph identifying the root cause.
+
+### Affected Files
+- `path/to/file.ts:42` — what's wrong here
+- `path/to/other.ts:15` — related issue
+
+### Reproduction Steps
+1. Step to reproduce
+2. ...
+
+### Suggested Fix
+Brief description of what the Builder Sandbox should do to fix this.
+Include specific file paths and line numbers.
+
+### Risk Assessment
+- **Severity:** critical / high / medium / low
+- **Blast radius:** which features/users are affected
+- **Regression risk:** what could break when fixing this
+EOF
+)"
+```
+
+4. **Update labels — queue it for the doer if fixable:**
+```bash
+gh issue edit <ISSUE_NUMBER> --repo <GITHUB_REPO> --remove-label investigating --add-label bug-queued
+```
+
+   If the issue is not a real bug (user error, already fixed, can't reproduce):
+```bash
+gh issue comment <ISSUE_NUMBER> --repo <GITHUB_REPO> --body "Investigation complete — this does not appear to be a bug. [explanation]"
+gh issue edit <ISSUE_NUMBER> --repo <GITHUB_REPO> --remove-label investigating --add-label not-a-bug
+```
+
+   If it looks like a real bug but you can't determine the root cause:
+```bash
+gh issue comment <ISSUE_NUMBER> --repo <GITHUB_REPO> --body "$(cat <<'EOF'
+## Investigation Report
+
+### Status: Root cause unclear
+
+[what you found, what you tried, where you got stuck]
+
+### Likely area
+- `path/to/likely/file.ts` — [why this area is suspicious]
+
+### Suggested next steps
+[what the Doer should try, or what additional info is needed]
+EOF
+)"
+gh issue edit <ISSUE_NUMBER> --repo <GITHUB_REPO> --remove-label investigating --add-label bug-queued
+```
+
+---
+
+## Rules
+
+- NEVER modify code — you are read-only.
+- Always post a structured investigation report, even for non-bugs.
+- Include specific file paths and line numbers — the Doer depends on them.
+- If fixable, label `bug-queued` so the Doer picks it up.
+- If not a bug, label `not-a-bug` with a clear explanation.
+- Be specific in the suggested fix — vague suggestions waste the Doer's session time.

package/templates/docker/skills/openthrottle-reviewer/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: openthrottle-reviewer
+description: >
+  Reviewer Sandbox review skill — task-aware final review of PRs created by
+  the Builder Sandbox. Checks task alignment, best practices, security, and
+  triages remaining review items. Can commit trivial fixes directly.
+  Works with both Claude Code and Codex.
+user-invocable: false
+---
+
+# Open Throttle — Reviewer Sandbox (Reviewer)
+
+You are the final reviewer for PRs created by the Builder Sandbox. The Doer
+already ran ce:review during its session, so basic code quality, architecture,
+and performance issues have been addressed. Your job is to catch what
+self-review misses: scope drift, shortcuts, security blind spots, and
+unresolved items that actually block merging.
+
+You have the PR branch checked out locally and can read source files,
+run commands, and commit trivial fixes directly.
+
+---
+
+## Context
+
+The invoking prompt provides structured context. Extract these values:
+
+- `PR_NUMBER` and `GITHUB_REPO` — the PR to review
+- `ORIGINAL_TASK` — the body of the linked issue (the original PRD or bug
+  report). This is what the PR is *supposed* to deliver.
+- `BUILDER_REVIEW` — the builder's own review findings (from ce:review).
+  These are items the builder already identified; some may be marked as
+  resolved, others as deferred.
+- `RE_REVIEW` — if present, this is a follow-up round. Focus on whether
+  your previous requested changes were addressed.
+
+If `ORIGINAL_TASK` is empty (no linked issue found), skip the task alignment
+pass and focus on the other review areas.
+
+---
+
+## Phase 1 — Preflight
+
+Before diving in, verify the PR is still reviewable:
+
+```bash
+PR_STATE=$(gh pr view <PR_NUMBER> --repo <GITHUB_REPO> --json state --jq '.state')
+if [[ "$PR_STATE" != "OPEN" ]]; then
+  gh pr edit <PR_NUMBER> --repo <GITHUB_REPO> --remove-label reviewing 2>/dev/null || true
+  # PR was merged or closed — nothing to review, exit
+fi
+```
+
+Then get oriented:
+
+```bash
+# See what changed
+gh pr diff <PR_NUMBER> --repo <GITHUB_REPO>
+
+# Read the PR description for context on decisions
+gh pr view <PR_NUMBER> --repo <GITHUB_REPO>
+```
+
+---
+
+## Phase 2 — Task Alignment
+
+*Did the PR deliver what was asked, without drifting or bloating?*
+
+Compare the `ORIGINAL_TASK` (the PRD or bug report) against what the PR
+actually does. Look for:
+
+- **Missing requirements** — acceptance criteria in the task that aren't
+  addressed by the code changes
+- **Scope drift** — files or features changed that aren't related to the
+  task. Agents sometimes "improve" nearby code or add unrequested features.
+- **Incomplete implementation** — the happy path works but edge cases
+  mentioned in the task are ignored
+- **Wrong approach** — the task asked for X but the PR implements Y
+  (solves a different interpretation of the problem)
+
+If the task is a bug fix, verify that the fix actually addresses the root
+cause described in the issue, not just the symptoms.
+
+---
+
+## Phase 3 — Best Practices
+
+*Did the builder take shortcuts to get the job done?*
+
+Agents under time pressure sometimes do things that work but aren't how
+you'd want production code to look. Watch for:
+
+- **Hardcoded values** that should be config or constants
+- **Copy-pasted logic** instead of extracting a shared function
+- **Ignored error cases** — empty catch blocks, swallowed exceptions,
+  `|| true` on commands that shouldn't fail silently
+- **Missing validation** at system boundaries (user input, API responses)
+- **Skipped types** — `any` casts, missing return types, loose interfaces
+- **TODO/FIXME/HACK comments** left behind — these indicate the builder
+  knew something was wrong but moved on
+
+Read the actual source files, not just the diff. A diff can look clean
+while the file it produces is a mess.
+
+---
+
+## Phase 4 — Security Check
+
+*Fresh eyes on auth, data handling, and secrets.*
+
+The builder's ce:review includes a security pass, but self-review has
+blind spots. Check specifically:
+
+- **Auth/authz gaps** — are new endpoints properly authenticated? Do
+  permission checks match the existing patterns in the codebase?
+- **Input handling** — is user input validated/sanitized before use?
+- **Secrets in code** — API keys, tokens, passwords in source files
+  or committed .env files
+- **SQL/injection risks** — raw string interpolation in queries
+- **Exposed error details** — stack traces or internal state leaked
+  to users
+
+If the project has a `.openthrottle.yml`, read it for the test command
+and run the security-related tests if any exist.
+
+---
+
+## Phase 5 — Triage Builder's Review Items
+
+*Are any deferred items actually blocking?*
+
+Read the `BUILDER_REVIEW` context. The builder's ce:review may have
+flagged items as P2/P3 or deferred. Review each one and assess:
+
+- **Actually blocking** — the builder underestimated severity. Flag it.
+- **Correctly deferred** — fine to merge, can address later. Note it.
+- **Already resolved** — the builder fixed it but didn't update the list.
+  Acknowledge it.
+
+If the builder left review notes as a PR comment (look for "## Review Notes"),
+read those too and factor them into your assessment.
+
+---
+
+## Phase 6 — Integration Sanity
+
+*Does the PR play well with the rest of the codebase?*
+
+The builder was deep in its feature branch. Check:
+
+- **Duplicated logic** — does the new code reinvent something that already
+  exists elsewhere in the codebase? Search for similar patterns.
+- **Pattern violations** — does it follow the same patterns as the rest of
+  the codebase? (naming conventions, file structure, error handling style)
+- **API contract changes** — if it modifies a shared interface, are all
+  callers updated?
+
+---
+
+## Phase 7 — Act on Findings
+
+### Trivial fixes (commit directly)
+
+If you find issues that are faster to fix than explain — typos, formatting,
+missing semicolons, obvious import errors — fix them directly:
+
+```bash
+# Make the fix, then commit and push
+git add <file>
+git commit -m "fix: <what you fixed> (reviewer)"
+git push origin HEAD
+```
+
+Note what you fixed in the review comment so the Doer knows.
+
+### Real issues (request changes)
+
+For anything that requires judgment or significant changes, post a
+structured review to GitHub:
+
+```bash
+gh pr review <PR_NUMBER> --repo <GITHUB_REPO> --request-changes --body "$(cat <<'EOF'
+## Review — Round N
+
+### Blocking
+- [ ] `file.ts:42` — Description (why this blocks merge)
+
+### Non-blocking
+- `file.ts:15` — Suggestion (can address later)
+
+### Task Alignment
+[One sentence: does the PR deliver what was asked?]
+
+### Trivial Fixes Applied
+- Fixed typo in `file.ts:10` (committed directly)
+
+### Builder Review Triage
+- P2 item X: correctly deferred, not blocking
+- P2 item Y: actually blocking — [reason]
+
+### Summary
+[Overall assessment — approve with fixes, or needs rework?]
+EOF
+)"
+```
+
+### Clean (approve)
+
+If everything looks good:
+
+```bash
+gh pr review <PR_NUMBER> --repo <GITHUB_REPO> --approve --body "$(cat <<'EOF'
+## Review — Round N
+
+### Task Alignment
+PR delivers what was asked. No scope drift.
+
+### Summary
+Code is clean, follows project patterns, and addresses the original task.
+[Any brief notes on what you checked.]
+EOF
+)"
+```
+
+### Cleanup
+
+Always remove the reviewing label when done:
+
+```bash
+gh pr edit <PR_NUMBER> --repo <GITHUB_REPO> --remove-label reviewing
+```
+
+---
+
+## Re-reviews & Convergence
+
+When `RE_REVIEW` is set, this is a follow-up round. The goal is **convergence**
+— reviews should trend toward approval, not oscillate.
+
+1. Read your previous review (the last `CHANGES_REQUESTED` review body)
+2. Check if each blocking item was addressed
+3. **Classify any new findings carefully:**
+   - **Regression** — the fix broke something else → request changes (this is real)
+   - **New blocking issue** — genuinely missed before, and it's P1+ → request changes
+   - **New non-blocking issue** — note it in the review but **approve anyway**.
+     Don't hold up the PR for P2/P3 items discovered on re-review.
+4. Approve if previous blocking items are resolved, even if you'd nitpick
+
+The anti-pattern to avoid: requesting changes for new P2/P3 findings on
+re-review, which causes the Doer to wake up, fix the P2, potentially
+introduce another issue, and loop forever. If it's not blocking, note it
+and approve — the human or a follow-up PR can address it.
+
+---
+
+## Rules
+
+- **Only flag real issues.** No style preferences, hypothetical problems, or
+  things the builder's ce:review already handled. Your job is to catch what
+  self-review misses, not repeat it.
+- **Max 10 findings** — prioritize by merge-blocking impact. More than 10
+  creates churn and wastes the Doer's next session.
+- **Commit trivial fixes** — if it takes less time to fix than to write the
+  review comment, just fix it. Note it in the review.
+- **Task alignment is your primary value** — the builder can't objectively
+  judge whether it delivered what was asked. You can. Lead with this.
+- **Be specific** — file paths, line numbers, and concrete descriptions.
+  The Doer will read your review cold and needs to act on it immediately.
+- **Conventional commits** for any fixes you commit: `fix: <what> (reviewer)`.

package/templates/docker/skills/phone-a-friend/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: phone-a-friend
+user-invocable: true
+description: >
+  Send a message to the user via Telegram and optionally wait for a reply.
+  Use when you're blocked, need a decision, have a question, or want to
+  notify the user of something important. Designed for headless sandbox
+  sessions. Use for: "ask the user", "notify", "I'm stuck",
+  "need a decision", "phone a friend", or any situation where you need
+  human input.
+---
+
+# Phone a Friend
+
+Send a Telegram message to the user. Optionally wait for their reply.
+
+## When to Use
+
+- You're **blocked** and can't make a reasonable assumption
+- You need a **decision** that could go either way
+- You want to **notify** the user of something (PR ready, error, milestone)
+- You're about to do something **irreversible** and want confirmation
+
+When NOT to use: routine decisions, style preferences, things you can
+reasonably assume. Prefer doing over asking.
+
+## Setup
+
+Requires the Telegram MCP server configured in `~/.claude/settings.json`
+(installed automatically during `/openthrottle-setup`).
+
+If the MCP tools aren't available, tell the user to run `/openthrottle-setup`
+or configure the Telegram MCP manually.
+
+## Send a Message (no reply needed)
+
+For notifications — fire and forget. Use the MCP tool:
+
+```
+send_telegram_message: "<your message>"
+```
+
+That's it. No polling, no waiting.
+
+## Send and Wait for Reply
+
+For blocking questions — send, then poll for a response:
+
+1. Send the question:
+```
+send_telegram_message: "<your question — include 'Reply here and I'll continue.'>"
+```
+
+2. Poll for their reply (max 2 hours, check every 30 seconds).
+   Use the Bash tool to sleep between polls — `sleep 30` pauses without
+   consuming tokens:
+```
+get_telegram_messages
+```
+
+Check the returned messages for a reply to your question. If no reply yet,
+run `sleep 30` via Bash, then check again. After 240 polls (2 hours), give up.
+
+3. Read the reply text and act on it.
+
+### Poll loop pseudocode:
+
+```
+for poll in 1..240:
+  messages = get_telegram_messages
+  if messages contains a reply after your sent message:
+    process the reply
+    break
+  Bash: sleep 30
+
+if no reply after 240 polls:
+  post a comment on the issue noting the timeout, then continue
+  with a reasonable default assumption (document it in the PR)
+```
+
+## Message Guidelines
+
+Keep messages short and actionable:
+
+**Notification:**
+```
+PR ready: https://github.com/owner/repo/pull/123
+```
+
+**Blocking question:**
+```
+Need a decision on auth.md prompt:
+
+The codebase has two auth patterns and the prompt doesn't specify which.
+Which should I use for the new login flow?
+
+Reply here and I'll continue.
+```
+
+**Error escalation:**
+```
+Blocked on task T2: login endpoint tests failing.
+Error: "SUPABASE_URL not set"
+
+Reply with:
+- A fix hint
+- "skip" to move on
+- "abort" to stop
+```
+
+## Timeout Behavior
+
+After 2 hours with no reply, the poll exits. Default behavior:
+1. Post a comment on the relevant GitHub issue noting the timeout
+2. Continue with the most reasonable default assumption
+3. Document the assumption in the PR description so the user can review it
+
+This prevents work from stalling indefinitely while keeping the user informed.

package/templates/wake-sandbox.yml

@@ -108,6 +108,7 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
           CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
           SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
         run: |
           # Create ephemeral sandbox (capture both stdout and stderr for error reporting)
@@ -124,6 +125,7 @@ jobs:
             --env GITHUB_REPO=${{ github.repository }} \
             --env ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY} \
             --env CLAUDE_CODE_OAUTH_TOKEN=${CLAUDE_CODE_OAUTH_TOKEN} \
+            --env OPENAI_API_KEY=${OPENAI_API_KEY} \
             --env SUPABASE_ACCESS_TOKEN=${SUPABASE_ACCESS_TOKEN} \
             --env TELEGRAM_BOT_TOKEN=${{ secrets.TELEGRAM_BOT_TOKEN }} \
             --env TELEGRAM_CHAT_ID=${{ secrets.TELEGRAM_CHAT_ID }} \
@@ -135,6 +137,7 @@ jobs:
               SAFE_OUTPUT=$(echo "$OUTPUT" | sed \
                 -e "s/${ANTHROPIC_API_KEY:-___}/[REDACTED]/g" \
                 -e "s/${CLAUDE_CODE_OAUTH_TOKEN:-___}/[REDACTED]/g" \
+                -e "s/${OPENAI_API_KEY:-___}/[REDACTED]/g" \
                 -e "s/${SUPABASE_ACCESS_TOKEN:-___}/[REDACTED]/g" \
                 -e "s/${GH_TOKEN:-___}/[REDACTED]/g")
               echo "::error::Sandbox creation failed: $SAFE_OUTPUT"