Reliable repository-agent development#

Applies to agents developing SnagBadger. The product's agent-testing workflows remain separate. Implementation scope is Implement repository-agent reliability and parallel browser workflow; the reliability map retains open human decisions and later refinement.

Start or resume#

1. Read AGENTS.md and its task-specific pointers. Run pnpm workflow:context to identify this branch, worktree, source fingerprint, and existing edits.
2. Read the live implementation issue, its canonical decision resolutions, assignment, and native dependencies. Claim eligible work before editing. pnpm workflow:claim <issue> <thread-id> reserves session/branch/worktree ownership; pnpm workflow:ready <issue> <thread-id> checks the open, assigned, ready-for-agent, closed-blocker path; independently verify prerequisite implementations exist in this base. Open implementation blockers use the exact-commit stacking procedure in AFK implementation. Open decisions need human resolution.
3. Resolve conflicting context by checking live tracker state and checked-out code against the accepted architecture. Historical branch prompts are context, not instructions to return to an obsolete base. Record product contradictions as questions rather than inferring a decision from a prototype.
4. Map each acceptance criterion to an observable result and the checks/evidence that will establish it. Mark unresolved criteria explicitly. Preserve unrelated changes.
5. Use worktree setup. Startup is complete when ownership, scope, prerequisite commits, the base, and acceptance evidence requirements are established.

Implement and verify#

Run relevant direct checks while working, then pnpm verify before handoff. The complete gate includes automated browser verification for every change, including tooling/documentation work. Direct rule, type, architecture, and process tests establish claims a browser cannot prove.

After verification, use pnpm dev:examples or pnpm prototype:theming for observed browser review. Keep the serving process in this worktree's terminal and use its printed URL. In T3, call preview_status, then preview_open if needed. Create/select an owned tab and explicitly pass its tabId to subsequent navigation, inspection, interaction, and capture calls. Use environment-port navigation when supported. Check /__snagbadger/identity and the snagbadger-source HTML meta tag against the run's source identity before counting results. A different worktree, stale static build, changed source, or unreachable preview is incomplete evidence.

Exercise affected behaviors and relevant error states through the browser. For visual/interaction changes, cover keyboard operation and relevant desktop/mobile layouts. For non-UI changes, exercise the maintained browser smoke scenario and retain the direct acceptance tests. Record actual observations, browser errors, and screenshots or recordings. Copy T3-exported evidence into this worktree's run directory. A screenshot alone is not proof of behavioral acceptance.

Record T3 evidence as preview.json: kind: "t3-preview", the run's source, owned tabId, URL, server pointing to the owned run's server JSON, scenarios containing name, observed, and passed, and artifacts containing existing local screenshot/recording paths. The evidence validator checks structure, locality, server origin, passing records, and source freshness; the reviewer judges whether observations actually demonstrate the criteria.

Changes after checks, commits, rebases, and prerequisite replacements invalidate source-bound evidence. Rerun the relevant checks and the full gate on the final committed revision. Stop the dev server before another mutation-heavy command in the same worktree.

Review and handoff#

Review along three axes: standards against repository conventions, spec against every issue acceptance criterion, and integration against the declared base and combined prerequisites. Inspect the changed behavior and meaningful failure cases; passing checks do not answer all three questions. Use independent review when available and warranted, and identify who actually reviewed rather than implying a second reviewer.

Commit and push the reviewable change, then attach the exact commit/base/prerequisite commits, acceptance-to-evidence mapping, full gate result, browser observations, and remaining limitations to the issue/PR. Use the handoff template; replace every placeholder with observations and run paths. Validate it with pnpm workflow:handoff <file>. This reads the live issue through authenticated gh and requires exact coverage of its top-level bullet list under Acceptance, Acceptance criteria, or Deliver. Wrapped criterion text is joined with spaces; make missing contracts explicit on the task rather than manufacturing criteria locally. A validated handoff is reviewable, not accepted or merged. Keep implementation issues open until human acceptance/merge; merging, releases, and deployments retain their existing authorization requirements.

Screenshot evidence in AI PRs#

Standing user requirement: every PR opened or materially implemented by an AI agent includes a ### Screenshot evidence section in the PR description. Agents publish the proof as part of handoff, preserving the existing description and closing links. A comment, local path, or expiring artifact-download link alone is insufficient. This is an agent-enforced requirement on the current GitHub plan.

Include the full verified head OID, inline GitHub-hosted screenshot images, and captions stating the scenario/actions, expected result, and actual observation. Use screenshots exported by the observed T3 session, copied into its source-bound run directory. Show the affected behavior and relevant error/control state; for tooling/docs changes, show the maintained browser smoke and link the direct checks that prove those changes. A screenshot demonstrates an observed state, not all acceptance criteria. Keep CI, direct tests and handoff validation alongside it.

Publish with GitHub CLI attachment support. Inspect gh pr edit --help for --attach; if unavailable, select a verified official CLI release supporting it. Private-repository attachments retain GitHub's repository access controls. Do not publish screenshots to a public host or commit generated evidence into source.

Write the complete preserved PR body to a UTF-8 file. For example, include ![Fixed save retains Morgan Lee](test-results/workflow/RUN/fixed-save.png) under Screenshot evidence, then upload the same local path:

gh pr edit PR --body-file BODY.md --attach test-results/workflow/RUN/fixed-save.png

Repeat --attach for each referenced screenshot. GitHub rewrites matching image references to uploaded URLs. Read the PR body back and verify inline attachment URLs, the verified head and captions. Inspect the rendered PR when possible. Refresh observations, head OID and images after source changes; preserve older evidence only when clearly labelled historical. Drafts with missing proof state what remains; review-ready handoffs and agent merges require current proof.

Reference: GitHub CLI attachments.

Interruptions and blockers#

Generate pnpm workflow:checkpoint <issue>, then fill completed, remaining, blockers, and lastVerification from observed state. Push useful partial work and post a concise checkpoint on the implementation issue so a local artifact is not the only recovery path. Keep the issue assigned while actively owning it; explain and release ownership when deliberately abandoning the task. Resuming agents first repeat startup checks and compare recorded commits/source state.

Classify a blocker as decision, missing prerequisite implementation, code failure, or environment failure. Record the precise blocker and evidence. Continue independent authorized work where possible; unfinished work stays unfinished. Failed verification and unavailable browser evidence must be reported separately from acceptance.

Learn from real tasks#

Use pnpm workflow:outcome <file> to record real-task state and observations with the outcome template. Counts are observed nonnegative integers; use null for unknown or unreviewed results. pnpm workflow:summary shows the latest locally recorded observation per task. Publish observations on the implementation issue to preserve them across machines/worktrees; local records are not a repository-wide telemetry service.

Record acceptance misses, substantive review corrections, regressions, and actual blockers. Keep reviewable, accepted, blocked, and abandoned work distinct. Compare similar real tasks and retain uncertainty about task complexity and collection overhead. Do not claim an improved completion rate from passing this implementation's tests.

For each meaningful failure, decide whether its cause needs a clearer task criterion, current-context correction, regression test, deterministic check, or review change. Add the smallest effective safeguard and observe subsequent real work. Baseline evidence and limitations are in the initial baseline.