Skip to content

oliver-kriska/claude-elixir-phoenix / scripts/port_lib/amp_overlay/watch-pr

watch-pr

Verified

Watch an Elixir/Phoenix PR with an Amp Orb keep-alive lease until required non-deployment CI is green and review threads are resolved. Use after opening or updating a PR.

FileKindSize
SKILL.mdskill md4.2 KB
references/watcher-mechanics.mdmarkdown6.1 KB

references/watcher-mechanics.md

View on GitHub
# Amp Watcher Mechanics

## Lifecycle

The generated plugin owns the lifecycle rather than a shell process:

```text
start → validate PR → acquire keep-alive → persist snapshot → poll quietly
  ├─ required CI/reviews pending ───────────────────────────────┐
  ├─ actionable failure/feedback → deduplicated event/fix turn ──┤
  ├─ routine progress/activity → reset quiet, no model turn ─────┤
  ├─ ready → 15-minute activity quiet window → release → success│
  ├─ timeout/API error/closed/manual stop → release → incomplete│
  └─ plugin reload → release old lease → recover state/lease ───┘
```

Amp's normal inactivity pause is about five minutes. The default 15-minute
quiet period covers delayed check-backed and account-level reviews while the
lease—not an active model turn—keeps the Orb awake. A 60-second poll is
responsive without paying for model inference on unchanged state. The 2-hour
cap covers normal CI/review latency while limiting one HIGH worker to two
Orb-hours; raise it only when a known slow pipeline justifies the added cost.

All three values are configurable per watch within bounded ranges:

| Setting | Default | Range | Tradeoff |
| --- | ---: | ---: | --- |
| Poll interval | 60 seconds | 30–300 seconds | Faster response versus more GitHub API traffic |
| Quiet period | 15 minutes | 5–60 minutes | Catch delayed reviews versus extra Orb runtime after readiness |
| Active duration | 2 hours | 0.5–24 hours | Slow-pipeline reliability versus a hard billing ceiling |

## Durable and Idempotent Processing

Workspace Amp configuration stores watch identity, bound thread ID, options,
deadline, latest head SHA, normalized check/thread snapshot hashes, pending fix
event hash, and recent webhook IDs. Reload recovery reacquires a lease only for
an active, unexpired watch. Amp dispose releases all process-owned leases;
process exit also ends them server-side.

Snapshot and fix markers are written into appended user messages. Before an
append, the plugin scans recent full-thread messages for the marker. This makes
the append idempotent across a crash between the thread side effect and the
configuration update. `--fix` has one in-memory turn runner per PR, while its
pending and in-flight hashes remain durable. Failed or cancelled required CI
and unresolved threads share one actionable hash, so unchanged failures do not
queue duplicate turns and new evidence waits for the current turn to finish.

## Readiness Contract

`gh pr checks --required --json` is the source of required checks. Older GitHub
CLI versions fall back to its non-interactive tabular output. Buckets `pass`
and `skipping` are green; `pending`, `fail`, and `cancel` are not.

Names and workflows matching deployment, deployments, deploy, release,
preview, production, or prod are removed from readiness and retained in a
separate excluded list. Optional non-deployment checks are not promoted to
required checks. A draft PR is not ready. Every unresolved GitHub review
thread—including outdated but unresolved threads—is actionable until the
`phx-pr-review` turn validates and resolves or rejects it.

Do not treat the first green snapshot as ready. For example, Enaia starts
`Static checks`, `Design-system lifecycle`, `check_gettext`,
`migration_check`, `check_dialyzer`, `test`, `Integration tests`,
`Playwright E2E tests`, `Codex PR Review`, and aggregate `All checks`, while an
account-level Codex review may arrive later without its own check. Each current
head SHA change, required-check transition, review-thread change, top-level PR
comment, and submitted review resets the 15-minute quiet clock. Jobs such as
`deploy_branch`, `deploy_staging`, `draft_release`, and `tag_version` remain
excluded and do not reset it.

Polling and stabilization do not imply a model turn. Pending/passing required
check transitions, head pushes, submitted reviews without an unresolved
thread, and top-level comments reset the quiet clock but remain
inference-silent. Deployment-like transitions are even quieter: they are
persisted and reported by explicit status and terminal summaries, but neither
reset the clock nor append a message. Only failed/cancelled required checks,
unresolved threads, and terminal outcomes wake the model.

With `--fix`, actionable evidence is appended to the same serialized worker
thread with check names/links and unresolved-thread details. The turn may
inspect logs, fix branch-owned causes, verify, and push the authorized branch;
it must not blindly rerun shared CI, merge, or deploy. Without `--fix`, the
same evidence is reported once for inspection rather than repaired.

Review-thread GraphQL pagination is bounded at 1,000 threads. Exceeding that
bound or receiving malformed/incomplete API data is a polling error, never a
false green result. Five consecutive polling errors terminate incomplete and
release the lease.

## Durable Webhook Reactivation

`amp.createWebhook` registers a stable capability URL for the Orb thread and
plugin. The URL is a bearer secret: it is written under
`~/.config/amp/phx-watch-pr/` with owner-only permissions, never logged or put
in a normal thread message. Payloads only select a repository plus an exact
watched PR number or current watched head SHA; events that identify neither and
unrelated status/check events are ignored. All evidence is re-fetched through
authenticated `gh` calls and payload text is never used as agent instructions.

Webhook delivery is at least once, so Amp event IDs are retained and snapshot
markers deduplicate effects. A successful dormant watch reacts only to GitHub
check/status/PR/review events. It acquires a lease and probes for two minutes to
allow GitHub eventual consistency. No relevant change returns immediately to
dormant success; changed CI, head, or review state starts a fresh bounded
active window.

Creating the GitHub repository webhook requires shared administration
permission, so the plugin never does it automatically. Without external
configuration, the 15-minute quiet window is the final opportunity to catch a
comment before the Orb becomes eligible to pause.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall