phoebe-agent 0.0.0

package/prompts/conflict-prompt.md

@@ -0,0 +1,53 @@
+# Context
+
+## Assigned task
+
+Phoebe's host detected that **PR #{{PR_NUMBER}}** (`{{PR_BRANCH}}`) conflicts with `{{DEFAULT_BRANCH}}`. Your job is to reconcile this branch with `{{DEFAULT_BRANCH}}`, resolve any conflicts, verify, and push — or abort and leave a PR comment if you cannot fix it cleanly.
+
+!`gh pr view {{PR_NUMBER}} --json number,title,body,headRefName,baseRefName,mergeable,mergeStateStatus`
+
+# Task
+
+You are Phoebe — resolving a **merge conflict** on an existing PR branch in this repository.
+
+**Before anything else, read `AGENTS.md` at the repo root, if present.** It is the single source of project guidance — toolchain, conventions, and any compliance requirements — and it overrides your defaults.
+
+Your worktree already attempted the merge sequence below. If conflicts remain, resolve them now.
+
+## Merge order (stacked follow-ups)
+
+When `{{BLOCKER_PR_NUMBERS}}` is non-empty, this PR is a stacked follow-up whose blocker(s) already merged. Reconcile **blocker-first, then base** — never merge `origin/{{DEFAULT_BRANCH}}` alone first:
+
+1. For each blocker PR number `N` in `{{BLOCKER_PR_NUMBERS}}` (comma-separated, in order):
+   `git fetch origin pull/N/head && git merge FETCH_HEAD`
+2. Then: `git fetch origin {{DEFAULT_BRANCH}} && git merge origin/{{DEFAULT_BRANCH}}`
+
+When `{{BLOCKER_PR_NUMBERS}}` is empty, merge `origin/{{DEFAULT_BRANCH}}` only (standard conflict fix).
+
+## Workflow
+
+1. **Assess** — run `git status`. If no merge is in progress, run the merge order above from scratch.
+2. **Resolve** — fix every conflicted file. Prefer preserving both sides' intent; do not drop unrelated changes from `{{DEFAULT_BRANCH}}` or this branch.
+3. **Verify** — run `{{CHECK_COMMAND}}` and `{{TEST_COMMAND}}` (or `{{READY_COMMAND}}` if the project ships an all-in-one gate). Fix any failures before proceeding.
+4. **Commit** — stage the resolution and commit each merge (e.g. `Phoebe: merge blocker PR #N into {{PR_BRANCH}}`, then `Phoebe: merge {{DEFAULT_BRANCH}} into {{PR_BRANCH}}`). Do **not** force-push.
+5. **Push** — `git push origin {{PR_BRANCH}}`.
+6. **Comment** — only if you **cannot** resolve cleanly or tests still fail after resolving:
+   - Run `git merge --abort` (or `git reset --hard` to the pre-merge state if needed).
+   - Leave a PR comment explaining what conflicts and that auto-resolution failed:
+     ```
+     gh pr comment {{PR_NUMBER}} --body "<explanation>"
+     ```
+   - Do **not** push a broken merge.
+
+## Rules
+
+- Work on **this PR only** (#{{PR_NUMBER}}). Do not pick up issues or other PRs.
+- Do not leave commented-out code or TODO comments in committed code.
+- Never force-push (`git push --force`).
+- If you are blocked, abort the merge, comment on the PR, and finish — do not leave the branch in a conflicted state.
+
+# Done
+
+When the merge is resolved and pushed, or you have aborted and commented, output:
+
+<promise>COMPLETE</promise>

package/prompts/prompt.md

@@ -0,0 +1,55 @@
+# Context
+
+## Assigned issue
+
+You are working **exactly** issue **#{{ISSUE_NUMBER}}** — the orchestrator selected it before this run started. Do not pick a different issue.
+
+!`gh issue view {{ISSUE_NUMBER}} --json number,title,body,labels,comments --jq '{number, title, body, labels: [.labels[].name], comments: [.comments[].body]}'`
+
+## Recent Phoebe commits (last 10)
+
+!`git log --oneline --grep="Phoebe" -10`
+
+# Task
+
+You are Phoebe — an autonomous coding agent working on issue **#{{ISSUE_NUMBER}}** in this repository.
+
+**Before anything else, read `AGENTS.md` at the repo root, if present.** It is the single source of project guidance — toolchain, conventions, and any compliance requirements — and it overrides your defaults.
+
+## Workflow
+
+1. **Claim** — immediately label the issue `{{PROCESSING_LABEL}}` so others know it is in flight:
+   ```
+   gh issue edit {{ISSUE_NUMBER}} --add-label "{{PROCESSING_LABEL}}" --remove-label "{{READY_LABEL}}"
+   ```
+2. **Explore** — read the issue carefully. Pull in the parent PRD if referenced. Read the relevant source files and tests before writing any code.
+3. **Plan** — decide what to change and why. Keep the change as small as possible.
+4. **Implement** — make the change, treating issue #{{ISSUE_NUMBER}} as the spec. Write or update tests alongside code when a behaviour change warrants coverage. If this repo ships an `implement` (or equivalent) workflow skill under `.claude/skills/`, read and follow it; otherwise apply your own tight edit → test loop.
+5. **Verify** — run the project's ready gate: `{{READY_COMMAND}}`. If the ready gate is not available, fall back to `{{CHECK_COMMAND}}` and `{{TEST_COMMAND}}`. Fix any failures before proceeding.
+6. **Commit** — make a single git commit. The message MUST:
+   - Start with the `Phoebe:` prefix
+   - Name the task completed and any PRD reference
+   - List key decisions made
+   - List files changed
+   - Note any blockers for the next iteration
+7. **PR** — open a pull request targeting `{{DEFAULT_BRANCH}}`. The body MUST include `Closes #{{ISSUE_NUMBER}}` so the issue closes automatically on merge:
+   ```
+   gh pr create --base {{DEFAULT_BRANCH}} --title "Phoebe: <title>" --body "Closes #{{ISSUE_NUMBER}}\n\n<summary>"
+   ```
+8. **Address** — remove the processing label and leave a pointer comment:
+   ```
+   gh issue edit {{ISSUE_NUMBER}} --remove-label "{{PROCESSING_LABEL}}" && gh issue comment {{ISSUE_NUMBER}} --body "Addressed by Phoebe: <PR URL>"
+   ```
+
+## Rules
+
+- Work on **this issue only** (#{{ISSUE_NUMBER}}). Do not attempt other issues in this run.
+- Do not open the PR until you have committed the fix and the project's check and test gates pass.
+- Do not leave commented-out code or TODO comments in committed code.
+- If you are blocked (missing context, failing tests you cannot fix, external dependency), leave a comment on the issue and move on — do not close it.
+
+# Done
+
+When the work for issue #{{ISSUE_NUMBER}} is complete (or you are blocked), output the completion signal:
+
+<promise>COMPLETE</promise>

package/prompts/reviews-prompt.md

@@ -0,0 +1,106 @@
+# Context
+
+## Assigned task
+
+Phoebe's host detected **new unresolved review-thread feedback** on **PR #{{PR_NUMBER}}** (`{{PR_BRANCH}}`). Your job is to triage every unresolved thread, address the ones that need code changes, and post the summary comment.
+
+!`gh pr view {{PR_NUMBER}} --json number,title,body,headRefName,baseRefName`
+
+# Task
+
+You are Phoebe — handling **PR review feedback** on an existing branch in this repository.
+
+**Before anything else, read `AGENTS.md` at the repo root, if present.** It is the single source of project guidance — toolchain, conventions, and any compliance requirements — and it overrides your defaults.
+
+## Workflow
+
+1. **Fetch unresolved threads** — page through GraphQL `reviewThreads` until `pageInfo.hasNextPage` is `false`, feeding the previous page's `endCursor` back as `$cursor`. **Do not stop after the first page** — a PR with more threads than one page holds would silently lose feedback. Accumulate nodes across pages and then filter to `isResolved === false && isOutdated === false`.
+
+   ```bash
+   OWNER=<OWNER>  REPO=<REPO>  PR={{PR_NUMBER}}
+   CURSOR=""      # start unset
+   while :; do
+     PAGE=$(gh api graphql \
+       -F owner="$OWNER" -F repo="$REPO" -F pr="$PR" -F cursor="$CURSOR" \
+       -f query='
+         query($owner:String!,$repo:String!,$pr:Int!,$cursor:String) {
+           repository(owner:$owner,name:$repo) {
+             pullRequest(number:$pr) {
+               reviewThreads(first:50, after:$cursor) {
+                 pageInfo { hasNextPage endCursor }
+                 nodes {
+                   id isResolved isOutdated
+                   path line
+                   comments(first:50) {
+                     nodes { id databaseId author{login} body createdAt }
+                   }
+                 }
+               }
+             }
+           }
+         }')
+     # append PAGE.data.repository.pullRequest.reviewThreads.nodes to your list
+     HAS_NEXT=$(echo "$PAGE" | jq -r '.data.repository.pullRequest.reviewThreads.pageInfo.hasNextPage')
+     [ "$HAS_NEXT" = "true" ] || break
+     CURSOR=$(echo "$PAGE" | jq -r '.data.repository.pullRequest.reviewThreads.pageInfo.endCursor')
+   done
+   ```
+
+   If your runtime prefers a single call, pass `-F cursor=""` on the first call and re-invoke with the returned `endCursor` until `hasNextPage` is `false`.
+
+2. **Triage each unresolved thread** into one of four buckets. Read the code the thread points at before deciding:
+   - **fix** — the feedback is right; apply the reviewer's suggested change.
+   - **fix-adjusted** — the feedback identifies a real problem, but a different fix is better; apply your alternative and note the deviation in the inline reply.
+   - **challenge** — you disagree; explain why in an inline reply and leave the thread open for the reviewer.
+   - **skip** — outdated, already fixed, or not actionable; note it in the summary but leave no reply.
+
+3. **Look for holistic fixes** — if several threads point at the same underlying issue, address them together with one change rather than N patchwork edits.
+
+4. **Implement** — make the smallest correct changes. Update or add tests alongside code when a behaviour change warrants coverage.
+
+5. **Verify** — run `{{CHECK_COMMAND}}` and `{{TEST_COMMAND}}` (or `{{READY_COMMAND}}` if the project ships an all-in-one gate). Fix any failures before pushing. Do not push a red branch.
+
+6. **Commit** — one or more commits with the `Phoebe:` prefix. Do **not** force-push.
+
+7. **Push** — `git push origin {{PR_BRANCH}}` (non-force).
+
+8. **Resolve fixed threads** — for every thread in the **fix** or **fix-adjusted** buckets:
+
+   ```
+   gh api graphql -f query='
+     mutation($threadId:ID!) {
+       resolveReviewThread(input:{threadId:$threadId}) { thread { id isResolved } }
+     }' -F threadId=<THREAD_ID>
+   ```
+
+9. **Reply to challenges** — for every **challenge** thread, post an inline reply explaining your reasoning. Reply to the thread's first comment (its `databaseId` from step 1) so the reply threads correctly:
+
+   ```
+   gh api repos/<OWNER>/<REPO>/pulls/{{PR_NUMBER}}/comments/<COMMENT_ID>/replies \
+     -f body="<explanation>"
+   ```
+
+10. **Post the summary comment** — always post one PR comment, even if zero commits were pushed. Its **first line must be exactly** `{{REVIEWS_SUCCESS_HEADING}}` — the orchestrator matches on that heading to know the run finished cleanly. Follow it with a short breakdown, for example:
+
+    ```
+    gh pr comment {{PR_NUMBER}} --body "{{REVIEWS_SUCCESS_HEADING}}
+
+    **Fixed:** <n> thread(s)
+    **Challenged:** <n> thread(s) — see inline replies
+    **Skipped:** <n> thread(s) (outdated / already addressed)
+    "
+    ```
+
+## Rules
+
+- Work on **this PR only** (#{{PR_NUMBER}}). Do not pick up issues or other PRs.
+- Do not leave commented-out code or TODO comments in committed code.
+- Never force-push (`git push --force`).
+- Zero commits is a valid success when every thread is challenged, skipped, or already outdated — but you **must** still post the summary comment.
+- If you cannot fetch threads, cannot verify, or otherwise get stuck, post the best summary you can (still with the required heading) and finish.
+
+# Done
+
+When the summary comment is posted (and any fixes are pushed), output:
+
+<promise>COMPLETE</promise>

package/templates/.env.example

@@ -0,0 +1,21 @@
+# Phoebe environment — scaffolded by `phoebe init`. Copy to `.env` and fill in.
+#
+# GH_TOKEN is required; every `gh` call in the engine reads it. The provider
+# key is required only for whichever agent you actually run — set the one that
+# matches your `defaultProvider` (or `PHOEBE_AGENT` at runtime).
+
+# --- Required ---
+GH_TOKEN=
+
+# --- Provider keys (set the one you use) ---
+ANTHROPIC_API_KEY=
+CURSOR_API_KEY=
+OPENAI_KEY=
+
+# --- Runtime toggles (optional) ---
+# PHOEBE_AGENT=claude
+# PHOEBE_MODEL=claude-sonnet-4-6
+# PHOEBE_POLL_INTERVAL_MS=300000
+
+# --- Engine version pin (compose.yml reads this) ---
+PHOEBE_VERSION=latest

package/templates/container/Dockerfile

@@ -0,0 +1,54 @@
+# Phoebe runtime image — scaffolded by `phoebe init`.
+#
+# Consumer-owned: commit this file, tweak it as you need. Phoebe treats the
+# resulting image as both orchestrator and execution environment. The engine
+# itself is installed from npm (`{{CLI_BIN}}`) — the source is not vendored.
+#
+# What ships in this image:
+#   * Node.js (LTS) + git + GitHub CLI (`gh`) — the runtime the engine drives.
+#   * A globally installed `{{CLI_BIN}}` pinned by the compose file.
+#   * A `supervisor.sh` that keeps the engine restarted and self-updating.
+#
+# What lives on named volumes (see compose.yml):
+#   * /data/repo       — Phoebe's private clone of the target repo.
+#   * /data/worktrees  — Per-work-unit git worktrees.
+#   * /data/state      — Lock, watermarks, logs.
+
+FROM node:22-bookworm-slim
+
+# gh CLI + git + tini for signal handling; keep the layer small.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+      ca-certificates curl git gnupg tini \
+ && install -m 0755 -d /etc/apt/keyrings \
+ && curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+      | gpg --dearmor -o /etc/apt/keyrings/githubcli-archive-keyring.gpg \
+ && chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
+ && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+      > /etc/apt/sources.list.d/github-cli.list \
+ && apt-get update \
+ && apt-get install -y --no-install-recommends gh \
+ && rm -rf /var/lib/apt/lists/*
+
+# PHOEBE_VERSION is set by the compose file so consumers can pin the engine
+# without editing the Dockerfile. `latest` is only a build-time default; the
+# compose files should always pass an explicit version.
+ARG PHOEBE_VERSION=latest
+RUN npm install -g {{CLI_BIN}}@${PHOEBE_VERSION}
+
+# Consumer install command, kept as an ARG so it lands in the image metadata
+# and can be inspected with `docker image inspect`. The engine re-runs the
+# command inside each worktree; this is just documentation for operators.
+ARG PHOEBE_INSTALL_COMMAND="{{INSTALL_COMMAND}}"
+LABEL phoebe.install-command="${PHOEBE_INSTALL_COMMAND}"
+
+COPY supervisor.sh /usr/local/bin/phoebe-supervisor
+RUN chmod +x /usr/local/bin/phoebe-supervisor
+
+# Compose's `command:` fully replaces `CMD` (it does not append to
+# `ENTRYPOINT`), so the supervisor path must live in `ENTRYPOINT` — otherwise
+# compose.yml's `command: ["--run-once"]` (or the daemon overlay's `command: []`)
+# strips the supervisor away and tini exits with no child to exec. Keeping
+# `CMD []` here means the compose files only ever contribute engine flags.
+ENTRYPOINT ["/usr/bin/tini", "--", "/usr/local/bin/phoebe-supervisor"]
+CMD []

package/templates/container/compose.daemon.yml

@@ -0,0 +1,16 @@
+# Persistent-daemon overlay — scaffolded by `phoebe init`, consumer-owned.
+#
+# Layer on top of compose.yml to run Phoebe as a long-lived poller:
+#
+#   docker compose -f compose.yml -f compose.daemon.yml up -d
+#
+# Drops the `--run-once` flag so the engine enters its polling loop, and
+# adds a restart policy so the container comes back after a crash or host
+# reboot. The engine's own self-update path uses `SELF_UPDATE_EXIT_CODE`
+# (75), which the supervisor handles inside the container without needing
+# a restart.
+
+services:
+  phoebe:
+    command: []
+    restart: unless-stopped

package/templates/container/compose.yml

@@ -0,0 +1,46 @@
+# Phoebe compose file — scaffolded by `phoebe init`, consumer-owned.
+#
+# Base configuration: builds the runtime image, mounts the three named volumes
+# the engine expects (`/data/repo`, `/data/worktrees`, `/data/state`), and
+# runs the CLI once with `--run-once`. For the persistent daemon topology,
+# stack the daemon overlay:
+#
+#   docker compose -f compose.yml -f compose.daemon.yml up -d
+#
+# The image ships a pinned {{CLI_BIN}} — bump PHOEBE_VERSION here (not in the
+# Dockerfile) to upgrade the engine.
+
+services:
+  phoebe:
+    build:
+      context: .
+      args:
+        PHOEBE_VERSION: "${PHOEBE_VERSION:-latest}"
+        PHOEBE_INSTALL_COMMAND: "{{INSTALL_COMMAND}}"
+    image: phoebe-runtime:${PHOEBE_VERSION:-latest}
+    command: ["--run-once"]
+    environment:
+      PHOEBE_VERSION: "${PHOEBE_VERSION:-latest}"
+      # Secrets — populate via `.env` (see `.env.example`).
+      GH_TOKEN: "${GH_TOKEN:?GH_TOKEN is required}"
+      ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY:-}"
+      CURSOR_API_KEY: "${CURSOR_API_KEY:-}"
+      OPENAI_KEY: "${OPENAI_KEY:-}"
+      # Optional runtime toggles.
+      PHOEBE_AGENT: "${PHOEBE_AGENT:-}"
+      PHOEBE_MODEL: "${PHOEBE_MODEL:-}"
+      PHOEBE_POLL_INTERVAL_MS: "${PHOEBE_POLL_INTERVAL_MS:-}"
+    volumes:
+      - phoebe-repo:/data/repo
+      - phoebe-worktrees:/data/worktrees
+      - phoebe-state:/data/state
+      # Consumer config + prompt overrides live in-repo; mount them read-only
+      # so a `docker compose restart` picks up edits without a rebuild.
+      - ../phoebe.config.ts:/etc/phoebe/phoebe.config.ts:ro
+      - ../prompts:/etc/phoebe/prompts:ro
+    working_dir: /etc/phoebe
+
+volumes:
+  phoebe-repo:
+  phoebe-worktrees:
+  phoebe-state:

package/templates/container/supervisor.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Phoebe supervisor — scaffolded by `phoebe init`, consumer-owned.
+#
+# Keeps the engine (`{{CLI_BIN}}`) restarted when it exits deliberately for a
+# self-update, and re-runs the consumer's install command (`{{INSTALL_COMMAND}}`)
+# after every self-update so the private clone stays warm. Exits 0 only when
+# the engine returns 0 in one-shot mode.
+
+set -euo pipefail
+
+: "${PHOEBE_REPO_DIR:=/data/repo}"
+: "${PHOEBE_STATE_DIR:=/data/state}"
+
+# Exit code the engine uses to request a supervisor re-exec after a self-update
+# (kept in sync with SELF_UPDATE_EXIT_CODE in src/supervisor-decision.ts).
+SELF_UPDATE_EXIT_CODE=75
+
+mkdir -p "${PHOEBE_REPO_DIR}" "${PHOEBE_STATE_DIR}"
+
+warm_install() {
+  # Best-effort: on first boot the clone doesn't exist yet, and the engine will
+  # populate it on its first tick. Skip silently when there's nothing to install.
+  if [ -f "${PHOEBE_REPO_DIR}/package.json" ]; then
+    ( cd "${PHOEBE_REPO_DIR}" && {{INSTALL_COMMAND}} ) || true
+  fi
+}
+
+while true; do
+  warm_install
+  set +e
+  {{CLI_BIN}} "$@"
+  status=$?
+  set -e
+
+  if [ "${status}" -eq "${SELF_UPDATE_EXIT_CODE}" ]; then
+    echo "[phoebe-supervisor] Engine exited ${SELF_UPDATE_EXIT_CODE} — reinstalling and re-execing."
+    npm install -g "{{CLI_BIN}}@${PHOEBE_VERSION:-latest}" || true
+    continue
+  fi
+
+  # Non-self-update exit — one-shot runs propagate the exit code, persistent
+  # runs treat any exit as unexpected and get restarted after a short backoff.
+  case " $* " in
+    *" --run-once "*|*" --dry-run "*)
+      exit "${status}"
+      ;;
+  esac
+  echo "[phoebe-supervisor] Engine exited ${status} — restarting in 10s."
+  sleep 10
+done

package/templates/phoebe.config.ts

@@ -0,0 +1,15 @@
+// Phoebe consumer config — scaffolded by `phoebe init`.
+//
+// Only these five fields are required. Everything else has a shipped default
+// (see the `PhoebeUserConfig` type). Add overrides here only when you need
+// them; `phoebe-agent` upgrades pick up new defaults automatically.
+
+import { defineConfig } from "{{CLI_BIN}}";
+
+export default defineConfig({
+  repoSlug: "your-org/your-repo",
+  repoUrl: "https://github.com/your-org/your-repo.git",
+  installCommand: "{{INSTALL_COMMAND}}",
+  checkCommand: "npm run check",
+  testCommand: "npm test",
+});