AGENT SKILL

verify-with-prototype

Prototype-before-production workflow for risky host integrations (sudo, privileges, system config). Use when a feature touches the real OS, when behavior must be proven with a small script before full implementation, or when the user mentions prototype verification, POC script, or verify-with-prototype. Run after investigate/followup and before doctest-TDD integration.

License 许可
MIT
所属仓库
xhd2015/agent-pro
最近更新
2026-11-12
Stars
★ 1
Forks
0

01 前言 Front Matter

name
verify-with-prototype
description
Prototype-before-production workflow for risky host integrations (sudo, privileges, system config). Use when a feature touches the real OS, when behavior must be proven with a small script before full implementation, or when the user mentions prototype verification, POC script, or verify-with-prototype. Run after investigate/followup and before doctest-TDD integration.

02 资源文件 1

03 SKILL.md 正文

You guide the agent through prototype verification before full implementation and integration. The goal is to learn failure modes cheaply (false positives, session caches, TTY requirements) in a throwaway script, then encode lessons in a real package with fakes-based tests.

When to use

  • Host or privilege integration: sudo, /etc/sudoers.d, TUN, networksetup, etc.
  • Persistent state vs session cache can be confused (sudo -n, timestamp cache)
  • Production mistakes are hard to undo or dangerous to test in CI
  • User wants "setup once, then never password again" or similar UX proofs

When not to use

  • Pure documentation or config-only changes
  • Behavior already covered by isolated unit tests with no OS side effects
  • User only wants root-cause explanation → use investigate instead

Required workflow

Phase 0 — Understand (often already done)

  • Symptom, expected behavior, and constraints from investigate / followup
  • Identify the stand-in for the expensive dependency (e.g. hello.sh instead of sing-box)

Phase 1 — POC script

Create script/<feature>-poc/ (Go preferred) with small command surface:

Command Purpose
detect Report persistent state vs cache vs "works right now" separately
auto-setup One-time install path (may prompt on TTY)
remove-* Tear down + invalidate session cache if relevant

Document a manual test matrix in the script header:

remove → auto-setup (password once) → auto-setup (no password) → remove → auto-setup (password again)

POC rules

  • Do not infer persistent install from sudo -n alone — use drop-in file + local manifest (or equivalent)
  • On remove, flush sudo timestamp cache (sudo -k) when testing "prompt again" behavior
  • Distinguish stdin vs stdout TTY when password is required

Phase 2 — Manual verification

User (or agent with user) runs the matrix in a real terminal. Capture lessons:

  • False positives (e.g. warm cache after remove-sudo)
  • Missing non-TTY guard
  • Wrong detection signal

Fix the POC until the matrix passes. Do not proceed to production until manual proof succeeds.

Phase 3 — Requirement doc

Write REQUIREMENT-DESIGN-<slug>.md with:

  • Data model (Config, Rule, manifest paths, sudoers drop-in name)
  • Approved scope (package only vs integration)
  • Test tree outline (doctests with injectable FS + Runner, no real /etc or sudo)

Get explicit user approval before TDD implementation.

Phase 4 — Extract package + TDD

  • Extract core logic to pkgs/<name>/ with injectable FS and Runner
  • Doctest tree with fakes only — no real system modification in CI
  • Thin CLIs: POC script + production caller(s) share the package
  • Guards:
    • Under go test, panic if FS/Runner nil (production deps would touch the OS)
    • Before interactive sudo, error if stdin is not a TTY (already-installed path may skip)

Phase 5 — Integration

  • Wire production entrypoints (flags like --no-setup-sudo for opt-out of auto-setup)
  • Hook layer in existing packages for test injection
  • Bump / replace module deps as needed

Response shape

  1. Risk summary — what can go wrong on the real system
  2. POC plan — commands, stand-in, manual matrix
  3. Detection model — persistent vs cache vs live probe (table)
  4. After manual proof — package API sketch + test groups
  5. Stop — do not implement production code until POC matrix passes and user approves REQUIREMENT-DESIGN

Case study (this repo)

VPN passwordless sudo (master-2026-07-06-vpn-no-password work):

  • POC: script/sudo-nopasswd-poc (detect, auto-setup, remove-sudo)
  • Lesson: sudo -n after remove-sudo succeeded via timestamp cache, not NOPASSWD
  • Fix: manifest + /etc/sudoers.d stat for IsInstalled; sudo -k on remove
  • Package: pkgs/sudosetup with fake FS/Runner doctests
  • Integration: ws-proxy vpn auto-setup + --no-setup-sudo
  • Guards: test-time production-deps panic; stdin-TTY check before first setup

Related commands

agent-pro skill investigate --show
agent-pro skill followup --show
agent-pro skill verify-with-prototype --show

Install locally:

agent-pro skill verify-with-prototype install

04 同仓库更多 Skills

xhd2015
xhd2015/agent-pro

verify-on-behalf-of-user

Run human-style scenario verification after an agent claims work is done: git status, build into ~/.sandbox/bin (default sandbox mode) or opt-in host mode (outside sandbox: wrk --reinstall-local / change-scoped install), real integration/E2E scenarios (start servers, browser-agent for UI), always-labeled depth, markdown transcript written and inlined for review. Use for "verify on my behalf", before commit. Complements doctests; does not replace them. Load a sub-topic with: agent-pro skill --show verify-on-behalf-of-user/<topic>

★ 1
xhd2015
xhd2015/agent-pro

test-case-tree-design-expert

Use when the user wants a decision-tree style test case design with inherited setup and per-leaf assertions.

★ 1
xhd2015
xhd2015/agent-pro

test-case-design-expert

Use when the user wants comprehensive user-facing end-to-end test scenarios for a feature description.

★ 1
xhd2015
xhd2015/agent-pro

tdd-expert

Use when the user has a test-case-tree output and wants runnable Go tests plus stub implementation following Test-Driven Development.

★ 1
xhd2015
xhd2015/agent-pro

summarize-a-skill

Meta-skill: distill durable high-signal guidance (worked vs failed, wrong → correct, and anything else that quickens future similar tasks) into a brief reusable skill document with YAML frontmatter. When the user does not explicitly ask for a new skill/file, prefer updating an existing skill over creating one. Writes skills/<name>/SKILL.md (or docs|doc/skills/…). Use for /summarize-a-skill, "summarize what worked", "lessons learned into a skill", or "write a skill from this session".

★ 1
xhd2015
xhd2015/agent-pro

split-phases

Break a large implementation plan into dependency-ordered phases that are independently implementable and verifiable. Use when the user runs /split-phases, or says "split into phases", "phase this plan", "break into units of work", "dependency-ordered milestones", or wants a giant plan split for phase-by-phase work.

★ 1