AGENT SKILL

verify-green

Select and run the smallest risk-based verification lane that proves a mono-agent change. Use before claiming a change works, before committing or opening a PR, or when asked to verify, run the gate, make it green, or check architecture.

License 许可
GPL-3.0
最近更新
2026-11-15
Stars
★ 2
Forks
1

01 前言 Front Matter

name
verify-green
description
Select and run the smallest risk-based verification lane that proves a mono-agent change. Use before claiming a change works, before committing or opening a PR, or when asked to verify, run the gate, make it green, or check architecture.

02 资源文件 1

03 SKILL.md 正文

Verify green

Verification is selected from the diff, not accumulated from every available workflow. Run focused checks while iterating, then execute the chosen lane once before shipping. Do not repeat a passing broad gate at the same SHA.

1. Classify the change

Choose the highest applicable lane:

Lane Typical diff Required proof
Process AGENTS.md, skills/, agent metadata, internal docs Relevant contract tests, discoverability, OSS hygiene, whitespace
Package Ordinary implementation within existing package boundaries Dependency-closure build, focused tests, package typecheck, one broad CI gate
High risk Security/sandbox, storage or migration, lifecycle, provider routing, delivery, public package boundaries Focused checks, one local verify:all, CI, one matching live smoke
Release Mechanical lockstep version/publish work Use release-lockstep; do not add deployment or consumer checks here

A mixed diff uses the highest lane. Explain the classification in the final evidence so reviewers can challenge it.

1a. Cross-process contract changes

A wire contract is any value this repo emits that a different process parses later: callback_data protocols, event and tool names, on-disk state shapes, notification payloads, CLI JSON. Renaming or retiring one is always high risk, however small the diff, because in-repo tests cannot observe the other side. Green tests are the expected result of this break, not evidence against it.

Before merging such a diff:

# in-repo consumers
grep -rn "<old protocol literal>" packages/*/src extras/*/src --include="*.ts"
# out-of-repo consumers — the fleet parses these contracts too
grep -rn "<old protocol literal>" <instance-dir> <other-instance-dirs> \
  --include="*.mjs" --include="*.ts" --include="*.md" 2>/dev/null \
  | grep -v node_modules | grep -v "/dist/"

Then require the matching live-smoke round-trip: emit the new contract and confirm the far side acts on it. A unit test asserting a literal (["ask:0", "ask:1"]) proves only that the literal is unchanged — derive the expectation from the exported builder instead, so retiring the protocol fails the test that pins it.

PR #527 renamed the Telegram button protocol ask:<index> → reply:v1:<0-7> with every gate green. Personal Agent heartbeat cards kept emitting the old payload for a week; taps did nothing, and a test pinning the literal stayed green throughout.

2. Process lane

Do not build packages, run live smoke, inspect the fleet, or run release checks for a docs/skills/process-only diff. Select tests that cover the edited contract. For the engineering-skill surface, use:

pnpm exec vitest run \
  scripts/__tests__/check-codex-discoverability.test.mjs \
  scripts/__tests__/repo-hygiene-skills.test.mjs \
  scripts/release/__tests__/package-count-drift.test.mjs
pnpm run check:codex-discoverability
pnpm run check:oss-hygiene
git diff --check

Run the website build only when docs/, website/, or published-site inputs changed; use docs-sync to choose that surface.

3. Package lane

While iterating on package X:

pnpm --filter @mono-agent/<X>... run build
pnpm --filter @mono-agent/<X> test
pnpm --filter @mono-agent/<X> run typecheck

Add focused dependent-package checks when the changed public behavior crosses a package boundary. Before merge, rely on one successful hosted CI run for the exact head SHA. If Actions is unavailable, run pnpm run verify:all once under a supported Node runtime and record why CI could not provide the broad gate.

4. High-risk lane

Run the focused package checks above, then:

pnpm run verify:all

Require hosted CI for the exact head SHA and select exactly one scenario from live-smoke that exercises the risky boundary. Add a second scenario only when the diff independently changes a second live surface.

Provider-backed smoke is reserved for provider behavior. UI, worker transport, and lifecycle changes should use their narrower local scenarios instead of paid model calls.

Worktree dist rule

Cross-package imports resolve through built dist/. After editing package A, rebuild A before testing or typechecking a dependent package. A process-only change does not exercise package resolution and needs no dist baseline. See worktree-feature for diff-aware worktree setup.

Failure handling

  • Diagnose the first stable failure; do not rerun an unchanged failing broad gate.
  • When a failure may pre-exist, compare against the exact base SHA in a detached worktree.
  • A failure that passes on rerun at the same SHA is a flake: route it with flaky-tests (fix in scope, issue otherwise) instead of only rerunning.
  • If hosted CI fails immediately for an account or billing condition, stop polling and report that external blocker.
  • Never replace a failed stated check with a different check without naming the substitution.

Report format

State the lane, exact commands, SHA, and pass/fail result. For failures, name the failing test or gate. A green claim without command evidence is not complete.

04 同仓库更多 Skills

robertsreberski
robertsreberski/mono-agent

worktree-feature

Start isolated mono-agent work with diff-aware setup, keep only required dist fresh, and ship through a PR with safe cleanup. Use for tracked repository changes, multi-commit work, or before executing an implementation plan.

★ 2
robertsreberski
robertsreberski/mono-agent

repo-hygiene-gc

Explicit bulk branch/worktree garbage collection using API-bound deletion proof. Use when asked to clean up the repository or run a deliberate maintenance sweep; ordinary PR cleanup belongs to worktree-feature.

★ 2
robertsreberski
robertsreberski/mono-agent

release-lockstep

Cut and registry-verify a lockstep npm release of all @mono-agent packages. Use when asked to release, publish to npm, cut vX.Y.Z, or bump the version. A release never implies consumer deployment.

★ 2
robertsreberski
robertsreberski/mono-agent

pi-upstream-recon

Investigate the vendored pi packages' real API surface (pi-ai and pi-agent-core) before hand-rolling anything, and run pi version bumps safely. Use before implementing runtime/provider/session behavior, when pi behavior is surprising, or when asked to "bump pi".

★ 2
robertsreberski
robertsreberski/mono-agent

ops-log-hygiene

Check bounded logs for explicitly restarted services, or run a full log-health audit when requested or when symptoms justify it. Use for crash-loop diagnosis, oversized logs, restart churn, or an explicit live-fleet log audit.

★ 2
robertsreberski
robertsreberski/mono-agent

new-package

Add a new @mono-agent package/adapter that passes the architecture gate on the first try (catalog entry, README sections, dependency categories, lockstep version). Use when creating any new package, or when check:architecture fails on catalog/README/boundary errors.

★ 2