Verify Paperclip Agent Skill

Verify Paperclip

Read the map contract, then use the

feature map to select user verification

recipes. For API/agent access, read the same-named

agent access companion and use the

actual permitted agent identity, target and work mode. Follow existing API/runner/MCP

fixtures for access proof; a board request does not prove agent access. Report

recipe or access drift with evidence; map updates belong to

maintain-verification-skill.

Read development instructions for current commands.

Launch

Run from the repository root with Node 24.11+, Python 3, lsof, and dependencies

installed with pnpm install --frozen-lockfile. Browser driving uses the existing

@playwright/test dependency. If Chromium is unavailable, run

node node_modules/@playwright/test/cli.js install chromium, or select an installed

browser with PAPERCLIP_PLAYWRIGHT_CHANNEL=chrome.

Create separate, unique data and evidence directories. Keep the evidence outside

the data directory:

VERIFY_DATA_DIR=$(mktemp -d "${TMPDIR:-/tmp}/paperclip-verify-XXXXXX")
VERIFY_EVIDENCE_DIR=$(mktemp -d "${TMPDIR:-/tmp}/paperclip-proof-XXXXXX")
python3 .agents/skills/verify-paperclip/scripts/launch.py \
  --data-dir "$VERIFY_DATA_DIR" --evidence-dir "$VERIFY_EVIDENCE_DIR"

Keep this command in a foreground terminal/session. The helper runs the supported

onboard --yes --bind loopback --no-install-service --run command, with isolated

embedded PostgreSQL, a free loopback port, no inherited instance routing or cwd

.env, and no automatic browser opening. It records launch.json in the evidence

directory. Source startup builds its required shared/plugin packages and migrates

the empty database; readiness can take longer on the first run.

This path starts an empty instance without model credentials. Create company and

agent state through the journey being checked. A UI check that stops before model

execution does not prove an agent run. For a preconfigured company/CEO and live

model work, use the documented test-drive

command with an authorized environment-backed credential and --no-browser.

Record its printed data directory, URL, runtime PID and commit before driving;

never use a fake credential to claim provider verification.

For Paperclip-managed reusable services, follow

dev-workspace run/verify/fix

instead of launching a second server. Its cloned-data/login requirements differ

from this empty local instance.

Doctor

After startup, and again after any surprising behavior, run:

python3 .agents/skills/verify-paperclip/scripts/doctor.py \
  --evidence-dir "$VERIFY_EVIDENCE_DIR"

This read-only check compares the recorded launcher, runtime PID, port owner,

process cwd, configuration, served Git commit, health/bootstrap readiness, root

HTML response, and company-list access. It writes doctor.json or exits nonzero.

Do not trust a root 200 or CLI doctor output alone. The CLI doctor checks whether

the port is available before startup; it is not proof of a running server's

ownership. Browser readiness still requires the expected visible page. Reset or

relaunch a wedged browser even when the process health passes.

Drive

Use accessible roles, labels, and placeholders from the latest page state.

Existing Playwright specs in tests/e2e/ supply recipes and selectors; their

configured servers and fixtures are separate from this live instance. Run a named

suite through its own configuration only when that is the evidence needed.

The executable onboarding smoke drives onboarding.md / web-wizard: open

/onboarding in the disposable self-hosted instance,

enter a unique organization name, choose Continue, reach the agent-name field,

reopen /<company-prefix>/onboarding, reload, and corroborate the saved company

through read-only API checks:

node .agents/skills/verify-paperclip/scripts/onboarding-smoke.mjs \
  --evidence-dir "$VERIFY_EVIDENCE_DIR"

This covers company creation and setup resumption, with no mocked responses or

provider calls. Hiring, first task execution, and the alternate CLI entry remain

separate journeys. The script requires an empty instance and refuses a non-owned

or non-loopback target. For other features, reuse the owned URL and follow the

map's entry points. Company routes normally require the selected company's

issuePrefix, for example /<PREFIX>/goals; use current navigation rather than

guessing resource URLs. The unprefixed /onboarding route starts naming; use the

company-prefixed onboarding route to resume its agent setup. Check relevant

experimental gates and actor permissions.

For CLI checks, discover exact flags with

node cli/node_modules/tsx/dist/cli.mjs cli/src/index.ts <command> --help, then

select the disposable data directory/API/company explicitly. API reads can

corroborate UI writes; API-created state does not prove a creation UI.

Evidence

Record feature file, sub-feature and entry-point ID, commit/dirty state, owned URL,

company/user, flags, runtime/harness, live versus simulated dependencies, command,

exit code, expected and observed behavior, and evidence links. Report each entry

as passed, failed, blocked with its prerequisite, or not run.

The smoke saves before/after/reload screenshots, visible-page text, a Playwright

trace, and result.json with company ID and API corroboration. On failure it

retains the trace, visible state, and failure result; rerun doctor before retrying.

Preserve launch output and relevant application logs without secrets. Reopen or

reload changed state and verify persistence/continuation, not just a success toast.

One passing sub-feature does not certify the entire feature family or other

surfaces. A full maintenance pass must exercise every mapped feature or report

incomplete coverage.

For Paperclip-assigned work, attach important proof through

the artifact workflow. Keep runtime results in

the evidence directory or issue, not in the map; coverage.json describes

documentation coverage rather than live test health.

Cleanup

Close the browser context you created (the smoke does this in finally). Stop the owned runtime with:

python3 .agents/skills/verify-paperclip/scripts/stop.py \
  --evidence-dir "$VERIFY_EVIDENCE_DIR"

The helper verifies the runtime's port, cwd, and launch ancestry before sending

SIGTERM to that PID, then waits for runtime exit and checks that its HTTP

listener and embedded database have stopped. Signaling the runtime PID lets the server drain before stopping

PostgreSQL; a terminal group interrupt can reach the database first. Do this after

failed drives as well as successful runs. If startup fails before a runtime record

exists, stop only the foreground session you created and inspect its recorded data

directory for residue. Never kill by process name or stop another checkout's server.

Verify the recorded HTTP port has no listener and the owned runtime PID has

exited. Embedded PostgreSQL should stop with the server; inspect only the recorded

data directory if shutdown is incomplete. Retain the data directory for diagnosis

until no owned process uses it; remove only that exact temporary directory when

it is no longer useful. Never delete the evidence directory during teardown.

Confirm screenshots, trace, result.json, launch.json, and doctor.json still

exist after shutdown. A failed launch leaves its evidence intact.

Helpers

All helper invocations are shown above. launch.py, doctor.py, and stop.py use Python's

standard library and the repo CLI; onboarding-smoke.mjs uses the repo's existing

Playwright dependency. They introduce no new package dependency or test framework.

Helper safety check

Run the standard-library ownership test before changing launch/doctor/stop helpers:

python3 -m unittest discover -s .agents/skills/verify-paperclip/tests -v

It starts an owned fixture in another temporary checkout and confirms that both

doctor and stop reject its claimed port/PID without stopping the server. A second

fixture closes its listener before exiting and proves that cleanup waits for

runtime exit. These checks do

not qualify Paperclip startup, database readiness, or onboarding.