Skip to content

akunzai/agent-skills / skills/setup-agent-ready-repo

setup-agent-ready-repo

Unverified

Set up a repository so agents can file tickets, open pull or merge requests, and verify their own changes.

assets/templates/verification.md

View on GitHub
<!-- Template. Replace every <angle placeholder>, every inline `placeholder`
     span, and every ```placeholder fence; delete sections that do not
     apply. -->

# Verification

How an agent exercises a change in this repo before it reaches review.
Human setup narrative lives in `<README.md | CONTRIBUTING.md>`; this file
holds only what an agent needs.

## Starting the environment

```placeholder
the one non-interactive command
```

<!-- Service: the command that brings the stack up. Library, CLI or TUI:
     the project's own gate command. Nothing to start, no ports. -->

<!-- drift:forge <github|gitlab|other|none> -->
<!-- A script entrypoint is recorded as a path, a task-runner one as a
     command. Keep the line that applies and delete the other; repeat
     either marker where the gate is genuinely more than one command. -->
<!-- drift:entrypoint <scripts/dev-up.sh> -->
<!-- drift:entrypoint-cmd <mise run check> -->

It never prompts. A step needing a human aborts non-zero naming the
prerequisite — see Human prerequisites below.

**Proof it ran**: `placeholder:health endpoint, port check, or a subcommand
that exits zero`. For a library or CLI this is the built artifact
answering `--version` or `--check`, not a process that stays up.

<!-- Service only; delete for a library, CLI or TUI: -->
Entry point: `placeholder:url`. Test account: `placeholder:account` /
`placeholder:where the password comes from`.

## Checks

Record what the lookup cannot give. A task runner already names and
describes its own tasks, so copy none of them here; say where they live
and which command lists them.

| What | Command |
| --- | --- |
| `placeholder:the gate` | `placeholder:command` |
| `placeholder:one stage of it` | `placeholder:the command that lists them` |
| `placeholder:what no task file holds` | `placeholder:command` |

## Human prerequisites

Run once, by a person. The start command fails until they are done.

- [ ] `placeholder:install tool`
- [ ] `placeholder:trust certificate`
- [ ] `placeholder:obtain credentials`

<!-- If the wizard skill is available, suggest turning this list into an
interactive script that finishes by running the check above. Do not have
an agent run that script. -->

## Ports

<!-- Reached by port: -->
Ports come from `placeholder:runtime file`, derived from the worktree path
so two agents can run the stack at once. Compose reads `${<VAR>:-<default>}`.

<!-- drift:port <8080> -->

<!-- No listening service (library, CLI, TUI) — delete the rest of this
     section and the deployed-environment section below: -->
Not applicable. `placeholder:project` has no listening service, so several agents
can run the gate in the same clone at once.

<!-- Reached by hostname or TLS: -->
This stack is reached by hostname, so ports cannot be offset. **Only one
agent runs the environment at a time**; the lock is `placeholder:path`.

## Changes that need a deployed environment

These cannot be verified locally. Open the request as a draft, let the
pipeline deploy, then verify against `placeholder:environment url`:

- `placeholder:area`: `placeholder:why local cannot cover it`

Evidence from that environment cites the pipeline or deployment id and
the commit SHA, and is treated as containing real data: mask, crop, or
use a dedicated test account.

Agent may deploy to it: **<no | yes>**.
Credentials come from `placeholder:vault or variable name`.

## Capturing evidence

- Recording: `<record-walkthrough | tcut | tool>` — `placeholder:fallback if absent`
- Screenshots: `placeholder:tool`
- UI locale: **`placeholder:the locale of the language requests are written in when the UI ships it (check locales/, i18n), else the UI default; e.g. zh-TW`**. The app picks it from
  `placeholder:what it reads, in order`; `placeholder:anything that overrides the browser, such as a cookie or query parameter`.
  Browser automation defaults to `en-US`, so set it on every capture:
  `"locale"` in a `record-walkthrough` scenario, `locale` on the
  Playwright browser context for screenshots. Captions and narration
  follow the language requests are written in (`"captionLocale"`).

<!-- A UI with one language keeps the UI locale line as "UI locale: not
     applicable, the UI has one language" and drops the rest of it. -->

**This document is where the capture rules live**, and the request
document points here rather than restating them. A capture taken on the
developer's own machine carries their account's data, username, and home
paths as readily as a shared environment does. Assert on the frame, a
marker, or fixture data, and crop or mask what the tool happened to be
showing.

For a change behind a mode switch or feature flag, confirm the far end
received the call. A healthy container and a green build are not
evidence that an integration is wired up.

## Not verified

- `placeholder:path or behaviour`: `placeholder:reason it could not be verified locally`

A gap you could have closed is not a gap. Run the check whose dependency
you have already seen running, and report a check you skipped as untried,
rather than recording it here as one this repo cannot run.

<!-- Machine-checkable facts for scripts/check-drift.sh. Add one
     drift:file marker per mock scenario or fixture this file relies on. -->
<!-- drift:file <.devcontainer/mock/mappings/tenant.json> -->
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall