fleet-agents 0.1.0

package/review/prompts/fix.md

@@ -0,0 +1,190 @@
+You are finishing PR #__PR__ on `__REPO__`.
+
+The branch `pr/__PR__` is already checked out locally with the base branch merged in and
+upstream tracking set — skip any fetch / checkout / merge phases.
+
+`pushRemote` is already wired to the contributor's fork — `git push` from this branch lands
+directly on the PR's head branch (`__HEAD_REPO__:__HEAD_BRANCH__`), updating the actual PR. Do
+not push to `origin` explicitly; plain `git push` is correct.
+
+__CONFLICT_BLOCK__
+
+# Your job
+
+Two phases, both required:
+
+1. **Review and apply fixes**: do a CodeRabbit-style review of the diff, identify real issues
+   (blockers, major, suggestions), and apply the fixes directly to the working tree. Also
+   address every existing reviewer/bot comment on the PR (CodeRabbit, maintainers, inline
+   threads) — apply each actionable item rather than describing it.
+2. **Quality suite, commit, push**: run the repo's formatters / typecheck / lint / tests,
+   commit everything in focused commits, and push back to the PR branch.
+
+**Your job is to finish the PR, not to report on it.** A response that only lists what *should*
+be done is a failure mode.
+
+# Workflow
+
+## 0. Sanity check the working state
+
+```bash
+git status --short                  # should be empty or only your own staged work
+git branch --show-current           # should be pr/__PR__
+git rev-parse --abbrev-ref @{u}     # upstream must be set
+git log --oneline -5
+```
+
+If the working tree is dirty in a way you didn't expect, stop and ask — never stash/discard.
+
+## 1. Fetch PR metadata and existing review comments
+
+```bash
+gh pr view __PR__ -R __REPO__ --json number,title,headRefName,headRepositoryOwner,headRepository,baseRefName,isCrossRepository,state,author,url,body,mergeable,statusCheckRollup
+gh pr diff __PR__ -R __REPO__
+gh pr view __PR__ -R __REPO__ --json reviews --jq '.reviews[] | {author: .author.login, state: .state, body: .body, submittedAt: .submittedAt}'
+gh api repos/__REPO__/pulls/__PR__/comments --paginate
+gh api repos/__REPO__/issues/__PR__/comments --paginate
+```
+
+Confirm the PR is **open**. Abort on closed/merged unless the user says otherwise.
+
+For cross-repo forks where local `pr/__PR__` was pushed to your own `origin` (not the
+contributor's fork), pushes update your origin copy — **not the actual PR**. Flag this clearly.
+
+## 2. Read every changed file in full
+
+Read the **whole file** (not just the hunk). Read siblings for new files; check both paths for
+moves/renames. Skipping this produces shallow fixes.
+
+## 3. Analyze + classify each existing comment and your own findings
+
+Run a CodeRabbit-style review against these axes:
+
+**Correctness** — logic bugs, off-by-one, null/undefined, async/await misuse, race conditions,
+error propagation and handling.
+
+**Project standards** — read the repo's own `CLAUDE.md` / `AGENTS.md` / `CONTRIBUTING` and
+linter/formatter config, and hold the change to *those* conventions (module layout, error
+handling, logging style, file-size limits). Don't impose rules the project doesn't follow.
+
+**Testing** — new behavior ships with tests using the repo's framework; cover branches and
+error paths.
+
+**Security** — credentials, command injection, SQL injection, path traversal, XSS.
+
+Classify each existing comment and new finding:
+- `actionable-trivial` — typo, rename, formatting, missing import: fix directly.
+- `actionable-non-trivial` — logic/architecture/test gap: fix if direction is unambiguous;
+  otherwise defer.
+- `already-addressed` — current code satisfies it.
+- `stale-outdated` — no longer applies.
+- `disagree` / `defer-human` / `question` — surface in the final report and post back as a PR
+  comment via `gh api`; never silently dismiss.
+
+## 4. Apply fixes (REQUIRED)
+
+Apply every `actionable-trivial` and clearly-directed `actionable-non-trivial` fix. Re-read
+surrounding code before each edit (state may have drifted since the comment was written).
+
+One logical concern per commit:
+
+```text
+fix(<area>): <what changed> (addresses @<reviewer> on <file>:<line>)
+refactor(<area>): <what changed>
+test(<area>): <what added>
+docs(<area>): <what changed>
+chore(pr-fix): apply formatting
+```
+
+Skip anything you choose not to apply (capture the reason for the final report). Don't expand
+scope.
+
+## 5. Run the quality suite
+
+Detect the repo's checks from its manifests (`package.json` / `Cargo.toml` / `Makefile` /
+`pyproject.toml` / etc.) and run them — formatters, typecheck/lint, and tests. Run independent
+suites in parallel; always run the formatter + typecheck when code changed.
+
+If a test fails on apparent flake, rerun once. If it still fails, stop and report.
+
+## 6. Commit any auto-fixes
+
+- Formatter changes → `chore(pr-fix): apply formatting`.
+- Non-trivial lint autofixes → `chore(pr-fix): lint autofix`.
+- `git status --short` must be empty before push.
+- Never `--no-verify` unless a pre-push hook fails on pre-existing breakage unrelated to your
+  changes — in that case, push with `--no-verify` and note it in the report.
+- Never amend published commits. Never force-push without explicit user approval.
+
+## 7. Push (REQUIRED)
+
+```bash
+git status --short    # must be empty
+git push              # pushes to the contributor's fork (__HEAD_REPO__:__HEAD_BRANCH__) — updates the PR
+```
+
+If rejected (non-fast-forward — the contributor pushed while you worked): `git pull --rebase`
+then push. **Never** force-push without explicit user approval.
+
+If the push fails with a permissions error (no write access to the contributor's fork): stop,
+do NOT fall back to `origin`, and report — the user needs access or the contributor must pull
+the changes themselves.
+
+## 8. Post deferred / disagree / question items back to the PR
+
+For every item classified `disagree`, `defer-human`, or `question`, post it as an inline review
+comment via `gh api` so nothing is lost in chat:
+
+```bash
+gh api -X POST repos/__REPO__/pulls/__PR__/comments \
+  -f body="<your reply>" \
+  -f commit_id="$(gh pr view __PR__ -R __REPO__ --json headRefOid --jq .headRefOid)" \
+  -f path="<file path>" \
+  -F line=<line number> \
+  -f side=RIGHT
+```
+
+## 9. Final report (to the user)
+
+```text
+## PR #__PR__ - <title>
+Branch: pr/__PR__  PR head: <headRefName>  Base: <baseRefName>  Author: <login>
+
+### Preconditions
+- Working tree clean at start: yes/no
+- Branch / upstream verified: yes/no
+- Cross-repo fork: yes/no — push target: <origin/<branch> | contributor-fork>
+
+### Review comments processed (<count>)
+- @<reviewer> on <file>:<line> - <one-line> -> fixed / already addressed / deferred / disagree
+
+### New findings raised (<count>)
+- <severity> <file>:<line> - <one-line> -> fixed / deferred
+
+### Checks
+| Check | Result |
+|---|---|
+| typecheck | pass/fail |
+| lint | pass/fail (N autofixes) |
+| format | pass |
+| tests | <passed>/<total> |
+
+### Commits pushed
+- <sha> <subject>
+
+### Outstanding human items
+- <list, or none>
+
+### PR
+<url>
+```
+
+# Guardrails
+
+- **Never** push to `main`, force-push, skip hooks (except the documented pre-existing-breakage
+  case), amend published commits, or run destructive git commands without explicit user approval.
+- **Never** commit secrets (`.env`, `*.key`, credentials).
+- If the working tree is dirty at start in unexpected ways, **stop** — don't stash.
+- If tests flake, rerun once; if still failing, report rather than loop.
+- Stay on the PR branch; never accidentally commit to the base branch.
+- Keep findings honest. If the PR is clean, say so. Don't pad with invented issues.

package/review/prompts/review.md

@@ -0,0 +1,170 @@
+You are doing a CodeRabbit-style review of PR #__PR__ on `__REPO__`.
+
+The branch `pr/__PR__` is already checked out locally with the base branch merged in and
+upstream tracking set — skip any fetch / checkout / merge phases.
+
+__CONFLICT_BLOCK__
+
+# Your job
+
+Produce a thorough CodeRabbit-style review: walkthrough, change summary table, per-file
+analysis, actionable inline comments with concrete code suggestions, and a nitpick section.
+Then **post the review and any inline comments via `gh`**. If the changes look acceptable
+overall, approve with `gh pr review __PR__ -R __REPO__ --approve`. If blocking issues remain,
+request changes instead.
+
+Do NOT apply code changes — this is a review-only task.
+
+# Workflow
+
+## 1. Fetch PR metadata and diff
+
+```bash
+gh pr view __PR__ -R __REPO__ --json number,title,headRefName,baseRefName,isCrossRepository,state,author,url,body,mergeable,additions,deletions,changedFiles
+gh pr diff __PR__ -R __REPO__
+gh pr view __PR__ -R __REPO__ --json files --jq '.files[] | {path, additions, deletions}'
+```
+
+Abort on closed/merged PRs unless the user insists. Note cross-repo/fork status.
+
+## 2. Read every changed file in full
+
+For every file in the diff:
+- Read the **whole file**, not just the hunk. Context matters.
+- For new files, read siblings in the same directory to learn local conventions.
+- For moved/renamed files, check both old and new paths.
+
+Skipping this produces shallow reviews that miss architectural issues.
+
+## 3. Analyze against these axes
+
+**Correctness** — logic bugs, off-by-one, null/undefined, async/await misuse, race
+conditions, resource leaks, error propagation and handling.
+
+**Project standards** — read the repo's own `CLAUDE.md` / `AGENTS.md` / `CONTRIBUTING` and
+its linter/formatter/editorconfig, and hold the change to *those* conventions (module layout,
+error-handling patterns, logging style, file-size limits, naming). Don't impose rules the
+project doesn't follow.
+
+**Testing** — new behavior ships with tests using the repo's framework; cover branches and
+error paths; test behavior over implementation; no real network, no time-based flakes.
+
+**Debug logging** — meaningful logs on new flows (entry/exit, branches, retries, state
+transitions) with grep-friendly prefixes; never log secrets or PII.
+
+**Security** — credentials, command injection, SQL injection, path traversal, XSS, secret
+files (`.env`, `*.key`), validation at trust boundaries.
+
+**Design / code quality** — dead code, commented-out blocks, unexplained TODOs,
+over-abstraction, duplication, backwards-compat cruft, "what" comments instead of "why".
+
+**UX / UI** (frontend changes) — accessibility, keyboard nav, loading/error/empty states,
+responsiveness.
+
+**Documentation** — comments/API docs match new behavior; architecture/usage docs updated for
+behavior or rule changes.
+
+## 4. Classify findings
+
+For each finding, tag:
+- **Severity**: `blocker` (must fix before merge), `major` (should fix), `minor` / `nitpick`
+  (optional polish), `question` (needs discussion).
+- **Confidence**: `high` / `medium` / `low`.
+
+Drop `low`-confidence `minor` items — they're noise. Keep real issues; don't pad the review.
+
+## 5. Emit and post the review
+
+Format the review using the structure below, then post it as a single review on the PR using
+`gh pr review __PR__ -R __REPO__ --body-file -` (or `--body "..."`). For each per-file
+actionable item, also post an inline review comment via `gh api repos/__REPO__/pulls/__PR__/comments`
+so it lands on the right line in the diff:
+
+```bash
+gh api -X POST repos/__REPO__/pulls/__PR__/comments \
+  -f body="<comment body>" \
+  -f commit_id="$(gh pr view __PR__ -R __REPO__ --json headRefOid --jq .headRefOid)" \
+  -f path="<file path>" \
+  -F line=<line number> \
+  -f side=RIGHT
+```
+
+Review body structure:
+
+````markdown
+# PR #__PR__ — <title>
+
+## Walkthrough
+<2–4 sentence prose summary of what the PR does, the approach taken, and overall assessment.>
+
+## Changes
+
+| File | Summary |
+| --- | --- |
+| `path/to/file1` | <1-line summary> |
+| `path/to/file2` | <…> |
+
+## Actionable comments (<count>)
+
+### 🛑 Blockers
+
+#### 1. `path/to/file:42-56` — <short title>
+<2–5 line explanation of the issue, why it's wrong, and the downstream effect.>
+
+**Suggested change:**
+```
+// before
+<snippet>
+
+// after
+<snippet>
+```
+
+### ⚠️ Major
+#### 2. `path/to/other:110-128` — <short title>
+<…same structure…>
+
+### 💡 Refactor / suggestion
+#### 3. `path/to/thing:200-240` — <short title>
+<…>
+
+## Nitpicks (<count>)
+- `path/to/file:15` — prefer `const` over `let`; not reassigned.
+
+## Questions for the author (<count>)
+- `path/to/file:88` — <question>
+
+## Verified / looks good
+- <what you checked that's correct>
+````
+
+Rules:
+- Use **file:line** or **file:line-range** for every actionable item.
+- Every actionable comment must include a **concrete proposed fix** — a code block where
+  plausible. "Consider refactoring" is not a suggestion.
+- Before/after code blocks should be minimal.
+- Do not invent issues. If the PR is clean, say so and keep it short.
+- Do not repeat what the linter/compiler would catch unless CI hasn't caught it.
+
+## 6. Approve or request changes
+
+After posting the review:
+- No blockers, no major issues: `gh pr review __PR__ -R __REPO__ --approve`.
+- Blockers exist: `gh pr review __PR__ -R __REPO__ --request-changes --body "See review above."`.
+- Otherwise: leave it as a plain `--comment`.
+
+## 7. Final report (to the user)
+
+```text
+## PR #__PR__ — Review posted
+### Findings raised: <total>  (blockers <n>, major <n>, suggestions <n>, nitpicks <n>, questions <n>)
+### Action: posted review <yes/no>, inline comments <n>, final state APPROVED / CHANGES_REQUESTED / COMMENTED
+### PR URL: <url>
+```
+
+# Guardrails
+
+- This is review-only. Do NOT edit code, commit, or push.
+- Never approve a PR with unresolved blockers.
+- Keep the review honest. If the PR is good, say so.
+- Never log secrets or full PII in comments.

package/review/review.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# review.sh <pr-number> [--agent <tool>] [extra-prompt]
+# Sync the PR locally, then hand a fully-inlined CodeRabbit-style review prompt
+# to the chosen agent. The prompt is loaded from scripts/shortcuts/review/prompts/review.md
+# so the workflow is agent-agnostic (no reliance on Claude Code's named
+# subagent registry).
+#
+# --agent picks the CLI that drives the work. Default: claude.
+# A trailing positional <extra-prompt> (any free-form text) is appended to the
+# agent's prompt verbatim.
+
+set -euo pipefail
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib.sh
+source "$here/lib.sh"
+
+require git gh jq
+require_pr_number "${1:-}"
+
+pr="$1"
+agent="claude"
+extra_prompt=""
+shift
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --agent) agent="${2:?--agent requires a value}"; shift 2 ;;
+    --agent=*) agent="${1#*=}"; shift ;;
+    *)
+      if [ -n "$extra_prompt" ]; then
+        echo "[review] unexpected extra arg: $1 (extra-prompt already set)" >&2
+        exit 1
+      fi
+      extra_prompt="$1"; shift
+      ;;
+  esac
+done
+
+require "$agent"
+sync_pr "$pr"
+
+template="$here/prompts/review.md"
+if [ ! -f "$template" ]; then
+  echo "[review] missing prompt template: $template" >&2
+  exit 1
+fi
+
+if [ "${REVIEW_HAS_CONFLICTS:-0}" = "1" ]; then
+  conflict_block="# ⚠️ Merge conflicts detected
+
+When the PR branch was merged with current \`main\`, the following files were left with unresolved conflict markers:
+
+$(printf '%s\n' "$REVIEW_CONFLICT_FILES" | sed 's/^/- /')
+
+Since this is a **review-only** run, do NOT resolve them — but you MUST call them out prominently in the review walkthrough as a blocker (with severity 🛑) and request changes on the PR. Tell the author exactly which files need attention before this PR can merge."
+else
+  conflict_block=""
+fi
+
+prompt=$(REVIEW_CONFLICT_BLOCK="$conflict_block" \
+         awk -v pr="$REVIEW_PR" -v repo="$REVIEW_REPO_RESOLVED" '
+  BEGIN { conflict = ENVIRON["REVIEW_CONFLICT_BLOCK"] }
+  { gsub(/__PR__/, pr); gsub(/__REPO__/, repo); gsub(/__CONFLICT_BLOCK__/, conflict); print }
+' "$template")
+
+if [ -n "$extra_prompt" ]; then
+  prompt="${prompt}
+
+# Additional instructions from the user
+${extra_prompt}"
+fi
+
+agent_exec "$agent" "$prompt"

package/review/sync.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# sync.sh <pr-number>
+# Check out the PR as local branch pr/<num>, merge main in, wire upstream
+# tracking + pushRemote to the contributor's fork. No agent invocation.
+
+set -euo pipefail
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib.sh
+source "$here/lib.sh"
+
+require git gh jq
+require_pr_number "${1:-}"
+sync_pr "$1"
+
+echo "[review] done. current branch: $(git branch --show-current)"