agentlane 0.0.0 → 0.4.0-rc.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +118 -0
- package/LICENSE +27 -0
- package/README.md +167 -2
- package/dist/agents/claude-plugin.js +79 -0
- package/dist/agents/cli.js +258 -0
- package/dist/agents/detect.js +88 -0
- package/dist/agents/init.js +251 -0
- package/dist/agents/launcher.js +32 -0
- package/dist/agents/package.js +119 -0
- package/dist/agents/skills.js +59 -0
- package/dist/agents/toml.js +325 -0
- package/dist/agents/wiring-check.js +117 -0
- package/dist/agents/wiring.js +374 -0
- package/dist/bench/host.js +104 -0
- package/dist/bench/live.js +511 -0
- package/dist/bench/mcp-client.js +91 -0
- package/dist/bench/model.js +15 -0
- package/dist/bench/report.js +162 -0
- package/dist/bench/run.js +121 -0
- package/dist/bench/schedule.js +140 -0
- package/dist/bench/stats.js +59 -0
- package/dist/bench-cli.js +167 -0
- package/dist/browser/aria.js +184 -0
- package/dist/browser/control.js +203 -0
- package/dist/browser/env.js +118 -0
- package/dist/browser/evidence.js +44 -0
- package/dist/browser/install.js +361 -0
- package/dist/browser/kinds.js +10 -0
- package/dist/browser/lane-browser.js +224 -0
- package/dist/browser/libraries.js +56 -0
- package/dist/browser/paths.js +29 -0
- package/dist/browser/release.js +121 -0
- package/dist/browser/screen.js +19 -0
- package/dist/browser/signin.js +154 -0
- package/dist/browser/stop.js +163 -0
- package/dist/browser/tools.js +25 -0
- package/dist/cache/build.js +154 -0
- package/dist/cache/config.js +186 -0
- package/dist/cache/index.js +4 -0
- package/dist/cache/key.js +196 -0
- package/dist/cache/store.js +303 -0
- package/dist/cli.js +178 -0
- package/dist/clock.js +4 -0
- package/dist/devices/adb.js +160 -0
- package/dist/devices/android.js +214 -0
- package/dist/devices/backend.js +7 -0
- package/dist/devices/bundler.js +46 -0
- package/dist/devices/common.js +51 -0
- package/dist/devices/controls.js +65 -0
- package/dist/devices/dial.js +56 -0
- package/dist/devices/emulator.js +396 -0
- package/dist/devices/hygiene.js +202 -0
- package/dist/devices/index.js +5 -0
- package/dist/devices/launch.js +76 -0
- package/dist/devices/simctl.js +119 -0
- package/dist/devices/tools.js +1 -0
- package/dist/devices/variant.js +99 -0
- package/dist/devices/xcrun.js +265 -0
- package/dist/driver/absence.js +54 -0
- package/dist/driver/caller.js +51 -0
- package/dist/driver/client.js +312 -0
- package/dist/driver/diff.js +180 -0
- package/dist/driver/elements.js +70 -0
- package/dist/driver/engine-main.js +13 -0
- package/dist/driver/engine.js +499 -0
- package/dist/driver/errors.js +11 -0
- package/dist/driver/exec.js +66 -0
- package/dist/driver/failure.js +156 -0
- package/dist/driver/flow.js +94 -0
- package/dist/driver/idle.js +100 -0
- package/dist/driver/images.js +68 -0
- package/dist/driver/install.js +272 -0
- package/dist/driver/lock.js +101 -0
- package/dist/driver/look.js +223 -0
- package/dist/driver/maestro-child.js +194 -0
- package/dist/driver/maestro-runs.js +46 -0
- package/dist/driver/paths.js +105 -0
- package/dist/driver/pixels.js +144 -0
- package/dist/driver/plan.js +108 -0
- package/dist/driver/release.js +7 -0
- package/dist/driver/runner.js +42 -0
- package/dist/driver/selector.js +91 -0
- package/dist/driver/session.js +474 -0
- package/dist/driver/suggest.js +86 -0
- package/dist/driver/supervisor.js +251 -0
- package/dist/driver/tree.js +426 -0
- package/dist/driver-cli.js +865 -0
- package/dist/evidence/device.js +177 -0
- package/dist/evidence/evidence.js +304 -0
- package/dist/evidence/files.js +92 -0
- package/dist/hooks/env.js +81 -0
- package/dist/hooks/run.js +101 -0
- package/dist/mcp/server.js +69 -0
- package/dist/mcp/tools.js +246 -0
- package/dist/name.js +22 -0
- package/dist/plugin/aims.js +465 -0
- package/dist/plugin/conventions.js +73 -0
- package/dist/plugin/guard.js +163 -0
- package/dist/plugin/hook-cli.js +216 -0
- package/dist/plugin/session-name.js +28 -0
- package/dist/plugin/shell.js +254 -0
- package/dist/processes.js +77 -0
- package/dist/project/config.js +316 -0
- package/dist/project/schema.js +335 -0
- package/dist/project/validate.js +224 -0
- package/dist/registry/config.js +142 -0
- package/dist/registry/format.js +22 -0
- package/dist/registry/owner.js +265 -0
- package/dist/registry/paths.js +50 -0
- package/dist/registry/ports.js +26 -0
- package/dist/registry/prune.js +160 -0
- package/dist/registry/refusal.js +53 -0
- package/dist/registry/registry.js +1027 -0
- package/dist/registry/resources.js +117 -0
- package/dist/registry/rows.js +115 -0
- package/dist/registry/status.js +85 -0
- package/dist/registry/store.js +274 -0
- package/dist/registry/types.js +1 -0
- package/dist/registry-cli.js +544 -0
- package/dist/services/services.js +268 -0
- package/dist/services/system.js +189 -0
- package/dist/up/deps.js +1 -0
- package/dist/up/doctor.js +424 -0
- package/dist/up/exec.js +133 -0
- package/dist/up/lane-files.js +75 -0
- package/dist/up/lane-services.js +38 -0
- package/dist/up/maestro-env.js +172 -0
- package/dist/up/preflight.js +232 -0
- package/dist/up/release.js +148 -0
- package/dist/up/resources.js +178 -0
- package/dist/up/restart.js +87 -0
- package/dist/up/setup.js +28 -0
- package/dist/up/up.js +610 -0
- package/dist/up-cli.js +258 -0
- package/dist/usage.js +16 -0
- package/package.json +58 -3
- package/schema/agentlane.schema.json +675 -0
- package/skills/create-verification-skill/LICENSE +21 -0
- package/skills/create-verification-skill/SKILL.md +88 -0
- package/skills/dev-loop/LICENSE +21 -0
- package/skills/dev-loop/SKILL.md +61 -0
- package/skills/device/SKILL.md +8 -0
- package/skills/drive/SKILL.md +64 -0
- package/skills/maintain-verification-skill/LICENSE +21 -0
- package/skills/maintain-verification-skill/SKILL.md +42 -0
- package/skills/setup/SKILL.md +80 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Lauren Tan
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: create-verification-skill
|
|
3
|
+
description: Build or extend a project's run skill so any agent can bring the real app up on its own lane (a simulator or emulator, a browser, its own servers and data), drive it the way a user does and prove what it does - the project's agentlane.json with its services, per-lane resources and sign-in, launch, doctor, drive, evidence and cleanup, the project's Maestro flows and Playwright tests adapted to run in a lane, plus a feature map with one page per user-facing feature - and run it once end to end before calling it done. Any surface - iOS or Android app, web app, CLI, service.
|
|
4
|
+
when_to_use: A project has no agentlane.json or no scripted way to drive its app and prove behavior; its run skill lacks drive or evidence sections or a feature map; the setup skill hands over to it; or dev-loop's bootstrap offer was accepted. Not for keeping an existing map current, which maintain-verification-skill does.
|
|
5
|
+
license: Parts adapted from cursor/plugins (pstack) under the MIT License, Copyright (c) 2026 Lauren Tan; the full notice is in LICENSE beside this skill in the toolkit package
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
<!-- Adapted from cursor/plugins (pstack/skills/create-verification-skill), MIT License, Copyright (c) 2026 Lauren Tan; full notice in ./LICENSE -->
|
|
9
|
+
|
|
10
|
+
# Create a verification skill <!-- upstream: pstack-create-verification-skill -->
|
|
11
|
+
|
|
12
|
+
The output is the project's `agentlane.json`, its committed flows and tests adapted to run in a lane, and its run skill in `.agents/skills/run/` (the toolkit's `init` mirrors it into `.claude/skills/run/` for Claude Code), the skill an agent finds whenever anyone asks to run the app or see a change working. Load the `dev-loop` skill for what the run skill must hold; this is how a project gets there. Write it for the next agent, which will read it cold, mid-task, having never seen the app.
|
|
13
|
+
|
|
14
|
+
Done when step 5 has passed: the run skill's own instructions, followed from a fresh lane, brought each app up to `doctor` ready, drove one mapped feature per app, and left evidence that still exists after `release`.
|
|
15
|
+
|
|
16
|
+
When the `setup` skill sent you here, its survey answers step 1 and its decisions (which apps, data per lane or shared, how sign-in gets a session) settle what step 2 writes; take them as given and do the rest.
|
|
17
|
+
|
|
18
|
+
## 1. Interview the repo, not the user
|
|
19
|
+
|
|
20
|
+
Answer these from the codebase, and ask the user only what you can't observe:
|
|
21
|
+
|
|
22
|
+
- **Surface:** what does a user actually touch: a mobile app, a web app, both? When there are several, note each; the run skill covers every one the project ships.
|
|
23
|
+
- **Run:** how does each app start locally? Prefer the repo's own scripts. Note the long-running servers (Metro, an API, a web dev server, workers), the ports they bind by default, devices, env files, seed data and auth.
|
|
24
|
+
- **Drive:** what can act on it programmatically? For a mobile app, the device tools (load the `drive` skill) on the claimed simulator, plus the project's committed Maestro flows. For a web app, the lane's browser through its driver, plus the project's Playwright suites. Otherwise existing harnesses first (curl-able endpoints, a debug port), then a generic recipe: a PTY for a CLI, HTTP for a service.
|
|
25
|
+
- **Observe:** what evidence can be captured: screenshots, recordings, traces, logs, response bodies, exit codes, database state.
|
|
26
|
+
- **Data:** where the app's data lives, and how the project's tests create and reset it today (migrations, a seed script, a Docker database, a SQLite file, fixtures). That decides whether each lane gets its own copy (a resource, step 2) or shares one.
|
|
27
|
+
- **Sign-in:** how a user signs in, which test accounts exist and where their credentials come from, and whether the project already has a seam (a token endpoint, a deep link, a Playwright setup project that saves a login).
|
|
28
|
+
- **Isolate:** can two instances run side by side? Every port the app or its servers hard-code is a collision between agents. The toolkit claims a port per service and passes it in, so each server has to take its port from the environment, and the mobile app has to take its API address at launch (a launch argument in debug builds) instead of a baked-in one. Shared outside state, such as a hosted dev database or test accounts, stays shared: say so in the skill and name what must be cleaned up after a write.
|
|
29
|
+
- **Worktrees:** agents work in git worktrees, often inside the repo (Claude Code puts them under `.claude/worktrees/`). Check that the project's watchers and test runners (Metro, Jest's haste map, Vite, linters, Playwright's test match) don't scan them, and add excludes where they do.
|
|
30
|
+
|
|
31
|
+
When a run skill already exists, read it and its scripts first. Keep what works and add what's missing; it usually holds traps someone paid for, and a rewrite loses them. If the checkout doesn't build or start, fix that or report it precisely before writing anything. A skill written against a broken base teaches wrong steps.
|
|
32
|
+
|
|
33
|
+
## 2. Write the project config
|
|
34
|
+
|
|
35
|
+
`agentlane.json` at the repo root (`node_modules/.bin/agentlane schema` prints its JSON Schema; point `$schema` at `node_modules/agentlane/schema/agentlane.schema.json` so editors check it) declares what the project has. `node_modules/.bin/agentlane doctor` validates it: its `config` line names any field that breaks the schema, and the bar is `node_modules/.bin/agentlane up` from a clean worktree followed by `doctor` reporting ready on each platform.
|
|
36
|
+
|
|
37
|
+
- **Apps:** `app` for the mobile app, `web` for the web app (`service`, the service that serves it, and `path`, the page to open), or both. `web.browser.driver` picks the browser driver: `playwright` (the default) or `agent-browser` when the project already uses it. `web.browser.headed: true` shows the window for a person to watch, with Playwright only; agent-browser runs headless.
|
|
38
|
+
- **Device:** when committed flows tap by point, or the repo says which device they were measured on, pin that model in `app.device` with `strict: true` (`{"type": "iPhone 17", "strict": true}`, or under `app.ios` or `app.android` when only one platform's flows depend on it). Without `strict`, a full pool hands the lane another model, and the points land elsewhere on its screen.
|
|
39
|
+
- **Services:** each long-running server with its start command, reading its port from `AGENTLANE_<SERVICE>_PORT`, and a readiness check. `platforms` limits a service to the apps that need it, so a web `up` doesn't start Metro. When a server's CLI sends usage telemetry, switch it off in the start command with the variable the CLI documents (`EXPO_NO_TELEMETRY=1`, `NEXT_TELEMETRY_DISABLED=1`), since every lane starts its own copy of the server.
|
|
40
|
+
- **Resources,** for data each lane gets its own copy of: `create`, `exports` and `teardown`. `create` runs once per lane, after setup and before the services, and appends a `NAME=value` line for each declared export to the file at `$AGENTLANE_EXPORTS` (`echo "DATABASE_URL=$url" >> "$AGENTLANE_EXPORTS"`); anything it prints only goes to the log. The values then reach every service, hook and `exec`, and replace whatever the caller's shell had. Name the copy after `$AGENTLANE_LANE` so two lanes never meet. `teardown` runs when the lane ends, also after a crash and possibly after the worktree is deleted, so it needs only the exported values (`dropdb … "$DB_NAME"`, `rm -f -- "${DATABASE_PATH:?}"`), never a script from the worktree. Since create runs once per lane, run migrations where every `up` reaches them too, such as in the API's start command.
|
|
41
|
+
- **Hooks** the project owns: `setup`, `build`, `launch` when the built-in launch modes don't fit, `signin`, `teardown`. Hooks are shell commands that read the lane from the environment (`AGENTLANE_DEVICE`, `AGENTLANE_<SERVICE>_PORT`, `AGENTLANE_WEB_URL`, the resources' values); they are non-interactive and fail with a non-zero exit when they didn't do their job.
|
|
42
|
+
- **Sign-in:** on a device, `signin` signs the launched app in through the project's seam. On the web, `signin` writes the lane's saved login to the file at `$AGENTLANE_STORAGE_STATE`, in Playwright's storage-state format (`{"cookies": [...], "origins": [...]}`), for the web app's origin; the lane's browser starts with it, and the project's tests can load it. Get the session the way a real client does, through the app's own sign-in endpoint with a test account, and write the cookie or token it returns. In a project with both apps, one `signin` hook branches on `$AGENTLANE_PLATFORM`. `up` checks the file and keeps its values out of every log.
|
|
43
|
+
- **First-run sheets:** a lane's simulator or emulator may never have run the app, so `up` can meet the app's first launch: onboarding, a what's-new sheet, a permission prompt, a rating or cookie banner. Each covers the screen an agent came to capture and takes its taps. On a simulator, `up`'s capture hygiene already marks the keyboard's slide-to-type intro as shown; the app's own sheets are the project's to clear, before anything is captured. Clear each through the app's own seam where there is one, the default or launch argument its debug build reads to mark the sheet seen, set from the `signin` or `launch` hook. A permission prompt stays away once `node_modules/.bin/agentlane device permission grant <service> <bundle id>` has granted the permission before the app asks. Dismiss any other sheet in the sign-in flow with an `optional` tap on its id or label. The run skill names each sheet and how it's cleared, and the feature map's baseline is the screen the app shows once they're gone.
|
|
44
|
+
- **Build cache,** for a mobile app: `buildCache.inputs` lists what the native build reads (the app config, the lockfile, native folders, plugins, assets, the build scripts, per platform where they differ), so an unchanged worktree installs a cached build instead of building. The key already covers Xcode, Android's JDK, Gradle and SDK packages and the env file; add a `command` input for every other tool whose version changes the native output, such as `pod --version` for CocoaPods, or a cached build outlives that tool's upgrade.
|
|
45
|
+
- **Preconditions** go in `preconditions` for whatever would otherwise fail a slow step late, each with the fix it names:
|
|
46
|
+
- one per tool a hook or a start command calls that the project doesn't install itself (`command -v pod`, `command -v uv`), one tool to a check, with its install command as the fix;
|
|
47
|
+
- one that the project's dependencies are installed (`test -d node_modules`, `before: build`, with the install command as its fix), so `up --no-setup` in a fresh worktree stops there with that fix instead of failing inside the build;
|
|
48
|
+
- one per env file a hook or the app needs, and, when the repo documents a failure that stays silent without a particular variable (an app that accepts a sign-in link and stays signed out without its seam key, say), one that the variable has a value, not just that the file exists: `grep -q '^SEAM_KEY=.' .env.test`. The check prints nothing, so the value stays out of every log;
|
|
49
|
+
- any other state the repo warns about, such as a dirty native project.
|
|
50
|
+
|
|
51
|
+
## 3. Adapt the flows and tests, then write the run skill
|
|
52
|
+
|
|
53
|
+
The project's committed flows and tests are its proof, and they keep passing where they ran before (CI, a person's machine). Adapt them to run in a lane as well; don't replace them.
|
|
54
|
+
|
|
55
|
+
- **Maestro flows:** a hard-coded port, host or account becomes a flow variable (`${API_PORT}`), passed under exec as `maestro test -e API_PORT="$AGENTLANE_API_PORT" <flow>`. Point `driver.flows` at their folder. A script that collects what a flow wrote (its `takeScreenshot` files, a failure's bundle) reads it from `$AGENTLANE_EVIDENCE` in a lane, at `<stamp>-maestro-test-<pid>/.maestro/tests/<run>/<flow>/`, ending `-failed` when the test failed. The toolkit also links each run into Maestro's own `~/.maestro/tests`, so a script that reads that folder keeps working, but there it can pick up another lane's run.
|
|
56
|
+
- **Waits in a sign-in or setup flow:** a flow a hook runs on every `up` pays the full timeout of each wait or tap that never matches, and the driver only warns about it (Maestro marks an optional step WARNED and moves on), so a broken step costs every lane its timeout without failing anything. Wait on a handle the driver can see in the screen's accessibility tree, an id or a label, rather than on text inside a system sheet, web view or other view the driver doesn't read. A wait that guards readiness is required, with a timeout no longer than the step needs, so a broken step fails at once and says where; keep `optional` for a screen that may or may not appear. A WARNED step in a sign-in or setup flow is a defect to fix, not a pass.
|
|
57
|
+
- **Playwright suites:** the config reads the lane when it's there and keeps its own behaviour when it isn't.
|
|
58
|
+
- Pin `@playwright/test` to the toolkit's Playwright version (`node_modules/.bin/agentlane browser status` names it). Under exec the tests launch the toolkit's pinned browsers, and another Playwright version looks for a browser build that isn't there.
|
|
59
|
+
- Exec sets `PLAYWRIGHT_TEST_BASE_URL` to the lane's web app, which Playwright Test uses as `baseURL` when the config sets none. A config that sets `baseURL` itself uses that variable when it is set. Skip the config's own `webServer` in a lane (when `AGENTLANE_WEB_URL` is set), since the lane's services already run.
|
|
60
|
+
- Give the tests that start signed in `storageState: process.env.AGENTLANE_STORAGE_STATE`.
|
|
61
|
+
- Keep traces on failure (`trace: 'retain-on-failure'`) and, when `AGENTLANE_EVIDENCE` is set, write `outputDir` to a folder of its own per run under it, such as `` `${process.env.AGENTLANE_EVIDENCE}/${stamp}-playwright-test` ``. Playwright empties `outputDir` at the start of every run, and each worker loads the config again, so compute the stamp once and keep it in `process.env` (`process.env.RUN_STAMP ??= new Date().toISOString().replace(/[-:.]/g, '')`). The trace of a failed run then survives the next run and `release`.
|
|
62
|
+
- Run them as `node_modules/.bin/agentlane exec -- npx playwright test` or the project's script.
|
|
63
|
+
|
|
64
|
+
`.agents/skills/run/SKILL.md` needs frontmatter (`name: run`, and a description naming the app, its surfaces and when to reach for it) and the sections `dev-loop` lists, for each app, each grounded in what the interview found, with no placeholders left. Write every toolkit command in it as `node_modules/.bin/agentlane …`, run from the project root: Codex, Cursor, Copilot and Gemini run the skill's commands in a plain shell, where a bare `agentlane` isn't found, and only Claude Code with the toolkit's plugin has one on the PATH. Any helper ships as an executable script whose invocation the skill shows; a helper the reader has to reverse-engineer is not a helper.
|
|
65
|
+
|
|
66
|
+
When agents keep writing throwaway scripts to click through the app, add a command to the project's CLI instead: a few composable commands that each do real work, `--dry-run` on anything destructive, errors that say what to do, and machine-readable output.
|
|
67
|
+
|
|
68
|
+
## 4. Seed the feature map
|
|
69
|
+
|
|
70
|
+
Create `.agents/skills/run/features/README.md` and one page per user-facing feature. When the repo lists its features itself (a `docs/INDEX.md` per app, a features folder, the docs site's navigation), seed a page for every feature it lists, so `maintain-verification-skill` has every page to fill in; otherwise find them from routes, deep links, tabs, menus, pages, commands and docs. Write the three to five that matter most in full. Each other page may be thin: what the feature is, where the repo documents it, how a user reaches it, and a first line saying it hasn't been driven yet. The README holds the baseline every page starts from (launch state, seed data, signed in or not, on which platform) and the index of every page.
|
|
71
|
+
|
|
72
|
+
A full page answers, from the user's side:
|
|
73
|
+
|
|
74
|
+
- what the feature is, and its sub-features;
|
|
75
|
+
- every way a user reaches it, on each platform it ships on;
|
|
76
|
+
- how to drive each way with the harness, pairing each action with its exact command and the result to look for;
|
|
77
|
+
- the end state that proves it works;
|
|
78
|
+
- the traps that can waste or falsify a run.
|
|
79
|
+
|
|
80
|
+
Leave implementation details out. Name user paths, stable handles, required state, commands and visible proof.
|
|
81
|
+
|
|
82
|
+
## 5. Prove it before handing it over
|
|
83
|
+
|
|
84
|
+
Run the skill's own instructions once, end to end, for each app: `up` (with `--platform` for each), `doctor`, drive one mapped feature, run its committed flow or test under `exec`, capture evidence, `release`. Then confirm the evidence still exists where the skill says it lands; a cleanup that eats the proof fails this step. Read the output of the flows the hooks run during `up` as well (`up` prints each hook's log path): a WARNED step there fails this step until it is fixed. Release after every failed attempt too, so broken tries don't strand processes, ports, devices, browsers or databases. A run skill that was never executed is a draft.
|
|
85
|
+
|
|
86
|
+
## 6. Hand over
|
|
87
|
+
|
|
88
|
+
Report what the skill covers, the feature you drove per app and its evidence, the flows and tests you adapted, the pages still thin, and anything the interview couldn't answer. Point at `maintain-verification-skill` for keeping the map true as the app changes.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Lauren Tan
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: dev-loop
|
|
3
|
+
description: The contract for running a project's app as an agent with the toolkit - one lane per session and folder (a simulator or emulator, a browser, the ports for Metro, the API and the web app, and per-lane resources such as a database), `agentlane up` from bare worktree to running app, `doctor` before trusting an instance, `release` when done - plus what a project's run skill holds and what counts as proof and evidence from a running app. Use when about to run, build, launch or capture a project's mobile or web app, start its dev servers, hand an agent work that runs the app, or when an agent loses turns to ports, simulators, browsers, databases or half-started servers.
|
|
4
|
+
when_to_use: Booting a simulator or emulator, opening the web app in a browser, starting Metro or a dev server, running the app for verification, capture, e2e or debugging; dispatching agents that will run the app; a project with no agentlane.json or no run skill. Not for test-only work that never runs the app.
|
|
5
|
+
license: Parts adapted from cursor/plugins (pstack) under the MIT License, Copyright (c) 2026 Lauren Tan; the full notice is in LICENSE beside this skill in the toolkit package
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
<!-- "What a run skill holds" and "What counts as proof" are adapted from cursor/plugins (pstack/skills/create-verification-skill), MIT License, Copyright (c) 2026 Lauren Tan; full notice in ./LICENSE -->
|
|
9
|
+
|
|
10
|
+
# Dev loop: running the app without losing turns to it
|
|
11
|
+
|
|
12
|
+
Every agent session gets its own running copy of the project, mobile app or web app: its own simulator or emulator, its own browser, its own ports for Metro, the API and the web server, its own resources such as a database, and its own processes on them. The toolkit keeps that in one registry per machine, shared by every project and every agent, so two agents never build onto the same simulator, sign in through the same browser profile, bind the same port or write to the same per-lane database. Everything here runs from a shell at the project root, as `node_modules/.bin/agentlane <command>`: that path works in every agent's shell, while a bare `agentlane` is on the PATH only in Claude Code with the toolkit's plugin. In a fresh worktree with no `node_modules` yet, run the project's install command first. The project's specifics live in its `agentlane.json` (`node_modules/.bin/agentlane schema` prints the format) and its run skill.
|
|
13
|
+
|
|
14
|
+
The loop is done when you have run `release` in your folder, and what you claim about the app rests on a replayable run whose evidence is where you say it is.
|
|
15
|
+
|
|
16
|
+
## The loop
|
|
17
|
+
|
|
18
|
+
1. **`node_modules/.bin/agentlane up`** takes the folder you're in from bare to the running app. It checks the toolchain and the project's preconditions before claiming anything, claims what the platform needs and ports, runs the project's setup, creates the lane's resources the first time (a database, say, whose values such as `DATABASE_URL` reach every service, hook and `exec`), starts each service on its claimed port and waits until it answers, then runs `doctor`.
|
|
19
|
+
- For the mobile app (`--platform ios`, the default when the project has one, or `--platform android` for an emulator) it also builds through the build cache, applies capture hygiene, and launches and signs in. When another worktree is already building the same cache key, `up` prints "waiting for <worktree>'s build of <key>" and installs that build when it lands (it builds itself after 45 minutes, or at once if that builder has died), so a quiet `up` there is waiting, not stuck.
|
|
20
|
+
- For the web app (`--platform web`, the default when the project has only a web app) it claims a browser with its own profile, opens the web app in it, signs in through the project's `signin` hook, and prints `the web app is at <url>`. There is no build, and it is ready in seconds.
|
|
21
|
+
- One lane can hold a device and a browser at once: `up` for one platform keeps what an earlier `up` for the other gave the lane.
|
|
22
|
+
|
|
23
|
+
Run it again to reuse the same lane; healthy services are kept, and one that fails its check is replaced, with the line naming the old pid and the failed check. A refusal names its fix; do the fix, not a workaround.
|
|
24
|
+
|
|
25
|
+
2. **`node_modules/.bin/agentlane doctor`** answers "is this instance worth driving?" read-only, and names a fix for each failure. On a device, its `app variant` line says which build is installed and fails when a hand-made build replaced the one `up` installed. On the web, it checks that the browser is up and that each web service's listener runs this worktree's code, not a server another checkout left on the port. `resource <name>` lines say each resource was created. `--platform` checks the other platform of a project that has both. Run it before the first drive and again whenever something looks off.
|
|
26
|
+
3. **Work.** `node_modules/.bin/agentlane exec -- <command>` runs a command with the lane's variables: `AGENTLANE_DEVICE`, `AGENTLANE_<SERVICE>_PORT`, `AGENTLANE_WEB_URL`, the resources' values, the browser driver's session and `AGENTLANE_STORAGE_STATE`, the log folder `AGENTLANE_LOGS` and the evidence folder `AGENTLANE_EVIDENCE`. An agent's shell commands often start with a fresh environment, so prefer `exec` over exporting. Drive the app with the `drive` skill: the device tools on a device, the driver's own CLI under `exec` in the browser, `look` and `screenshot` on both. To change a service's environment, such as a feature switch, an admin toggle or a client gate, run `KEY=value node_modules/.bin/agentlane restart <service>` rather than `release` and `up`, which would cost a re-lane, an install and a sign-in. It restarts only that service, on the same port, and returns once its ready check passes; the lane, the device, the browser, the app and the other services stay as they are. The service gets the lane's variables plus that call's environment, so pass every variable you still want: one given to `up` and not to `restart` is gone.
|
|
27
|
+
4. **`node_modules/.bin/agentlane release`** in the same folder when you're done: it stops exactly the processes `up` started, the browser and its driver's daemons included, runs the project's teardown and each resource's teardown (the lane's database is gone after this), and frees the lane. The evidence folder stays. When the session ends, its remaining lanes are released for it.
|
|
28
|
+
|
|
29
|
+
`node_modules/.bin/agentlane status` lists every lane on the machine with its owner, folder, start, idle time and last action. A lane whose session has exited is freed the next time any session claims one, its resources torn down with it. With the pool full, `claim` and `up` wait in a queue. An idle lane (over 2 hours) can be taken over only when no slot is free, and the taker is told whose it was.
|
|
30
|
+
|
|
31
|
+
`node_modules/.bin/agentlane prune` lists the pool simulators and emulators no lane holds, and `prune --yes` deletes them to free disk. Every project on the machine shares that pool, and the next lane after a prune waits while a new device is created, so run it when the user asks for disk space back; cleaning up after your own work is `release`.
|
|
32
|
+
|
|
33
|
+
## Lanes are per session and folder
|
|
34
|
+
|
|
35
|
+
A lane belongs to the session that made it and the folder it was made in. Subagents of one session share the session, so each one works in its own worktree and claims there; that keeps their devices, browsers, ports and databases apart. Release only your own folder's lane. A refusal names the holder and the exact command that recovers: when it's another session's lane, leave it, take your own, or ask; `release --lane <id> --force` is only for a holder you know is finished. Never reach another lane's device, browser or port by hand: `simctl`, `adb` and the browser drivers aimed at what you don't hold are denied by the toolkit's hook.
|
|
36
|
+
|
|
37
|
+
Orchestrators name the folder each agent works in, and the agent runs `up` there. Ports an app bakes in (a fixed API port, Metro's 8081, a dev server's 3000) are the app's to remove: each server takes its port from the environment, and debug builds take their API address at launch, which `up` passes from the lane.
|
|
38
|
+
|
|
39
|
+
## What a run skill holds <!-- upstream: pstack-create-verification-skill -->
|
|
40
|
+
|
|
41
|
+
A project's run skill (`.agents/skills/run/SKILL.md`, which the toolkit's `init` mirrors into `.claude/skills/run/` for Claude Code) is read cold, mid-task, by an agent that has never seen the app, in whichever agent the reader works. With the repo's real commands and handles, each toolkit command written as `node_modules/.bin/agentlane …` from the project root, for each app the project has, it covers:
|
|
42
|
+
|
|
43
|
+
- **Launch:** in a fresh worktree, the project's install command first, since `node_modules/.bin/agentlane` exists only after it; then `node_modules/.bin/agentlane up` (with `--platform` where there are several apps) and anything the project adds (a sign-in seam, seed data), how to tell it's ready, and `release`.
|
|
44
|
+
- **Doctor:** `node_modules/.bin/agentlane doctor`, plus any check only the project knows (the right account, a feature flag).
|
|
45
|
+
- **Drive:** how to act on the app the way a user does, preferring stable handles (testIDs, accessible names and roles, routes, deep links) over coordinates and refs.
|
|
46
|
+
- **Evidence:** what proves a behavior, how to run that proof, and where its files land.
|
|
47
|
+
- **Cleanup:** stop what you started, never by process name, and leave the evidence in place.
|
|
48
|
+
|
|
49
|
+
Its `features/` folder is the feature map: a README with the baseline every page starts from and an index, then one page per user-facing feature. A page says what the feature is, every way a user reaches it (on each platform it ships on), how to drive each one, the end state that proves it works, and the traps. A proof that drives one convenient entry point is incomplete when the page lists others. An agent that changes how a user reaches a feature, or what proves it, updates the page in the same change. An agent that verifies a feature with no page writes one from what it just drove.
|
|
50
|
+
|
|
51
|
+
## What counts as proof <!-- upstream: pstack-create-verification-skill -->
|
|
52
|
+
|
|
53
|
+
Exercise the real user path. A seam may set up a precondition, such as a signed-in session, but never stands in for the behavior under test. Capture the action and the resulting state, not only the final screen, and read side effects back (rows written, files saved, messages sent) alongside what's visible. Mock only where a production boundary already isolates the outside system. When the safe path is a dry run or test mode, observe what it actually skips instead of trusting its name.
|
|
54
|
+
|
|
55
|
+
Proof is an assertion the next reader can replay: a committed flow, test or script run through the project's own runner (Maestro flows for the mobile app, the project's Playwright tests for the web app), with the artifacts it writes. Interactive probing (`look`, the driver's CLI, a REPL, a one-off request) is how you find the steps, and its output never stands in for that run.
|
|
56
|
+
|
|
57
|
+
Evidence beyond the assertion is your call, by who reads the result: a video when a user-visible change goes to a person, a screenshot when the owner judges how it looks, logs or a trace when a failure needs explaining. `node_modules/.bin/agentlane evidence` records each into `$AGENTLANE_EVIDENCE`, and a failed run keeps its trace there on its own; the `drive` skill has the commands.
|
|
58
|
+
|
|
59
|
+
## Bootstrap and upkeep
|
|
60
|
+
|
|
61
|
+
In a project with no `agentlane.json`, or no agent wiring, `up` and `doctor` say so and name the `setup` skill. Say so in one line with what setting it up involves, and on yes, load the `setup` skill. When only the run skill lacks the sections above or a feature map, load the `create-verification-skill` skill instead. `maintain-verification-skill` is the upkeep pass: it checks every page against the code and drives every feature live. A specific gap noticed mid-work gets a single offer.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: device
|
|
3
|
+
description: The former name of the `drive` skill, kept so run skills that say "load the device skill" still find it. It points to `drive`, which drives the lane's simulator, emulator or browser.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Device is now drive
|
|
7
|
+
|
|
8
|
+
This skill is now `drive`, which covers the lane's browser as well as its simulator or emulator. Load the `drive` skill and follow it. Done when `drive` is loaded; a run skill that still names `device` can say `drive` instead.
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: drive
|
|
3
|
+
description: Drive the app on this session's own lane - its simulator or emulator through the device tools (look, run, screenshot over MCP, or `agentlane look|run|screenshot` from a shell), its browser through the driver's own CLI under `agentlane exec` (playwright-cli or agent-browser) - and turn what works into proof and evidence. Use when seeing what is on a screen or page, clicking or typing in the web app, trying or repairing Maestro steps or a Playwright test, checking what an action did, reading a failed step, recording a video, trace or screenshot, or setting a device's location, permissions, appearance, push, clipboard or URL.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Driving the app on your lane
|
|
7
|
+
|
|
8
|
+
Everything here acts only on what your session claimed for the folder you work in: a simulator or emulator, a browser, or both. The tools never take a device id or a browser session. Run the toolkit's commands from the project root as written here, `node_modules/.bin/agentlane <command>`, which works in every agent's shell. A lane comes from `node_modules/.bin/agentlane up`: `--platform android` for an emulator, `--platform web` for the web app in its own browser (the default when the project has only a web app). `node_modules/.bin/agentlane claim --boot` gives a bare device. A tool called before any lane answers with the command to run.
|
|
9
|
+
|
|
10
|
+
The verbs are the same on both. `look` reads the screen or the page, `screenshot` saves it, and `node_modules/.bin/agentlane evidence` keeps proof. Over MCP, `look` and `screenshot` take `browser: true`. From a shell they take `--browser` or `--device` when the lane holds both, and read the browser when the lane holds no device. The MCP server serves the whole agent session, so when your session holds lanes in several folders (parallel subagents in their own worktrees), use the shell form from your worktree, or pass `--worktree <dir>`.
|
|
11
|
+
|
|
12
|
+
Done when what you set out to show passes as a committed flow or test, run cold through the project's own runner, and the evidence its reader needs is in the lane's evidence folder.
|
|
13
|
+
|
|
14
|
+
## Look before you act
|
|
15
|
+
|
|
16
|
+
Most failed steps come from acting on a screen that isn't the one you pictured: a sheet still animating in, a list still loading, a page that redirected. `look` prints one line per element. Act on what it gives you, and look again after anything that navigates.
|
|
17
|
+
|
|
18
|
+
- **On a device**, each line has the element's role, id (the testID), label and state. `interactiveOnly` keeps what you can tap, toggle or type into, `within` narrows to one element's subtree, and `bounds` adds each frame in points. Act on ids, then labels; fall back to a point only when an element has neither. A read that comes back nearly empty (maps, canvases, some sheets) brings a screenshot with it: tap what it shows by point.
|
|
19
|
+
- **In a browser**, the first line is `Page: "<title>" at <url>`, then one line per element, indented by nesting: `[role] ref=eN "name"`. The ref is what the driver acts on, and it changes after navigation. The two drivers print the page differently (playwright-cli keeps generic wrappers, agent-browser shows text as `StaticText`), so match on roles and names rather than on the exact lines. A browser look has no bounds or raw mode.
|
|
20
|
+
|
|
21
|
+
Take a screenshot when the question is how something looks rather than what is there. A device's is a JPEG and a browser's a PNG.
|
|
22
|
+
|
|
23
|
+
## Drive a device with run
|
|
24
|
+
|
|
25
|
+
`run` takes Maestro YAML (a header with `appId:` and `---` is optional when you pass `appId`) or a flow file, and returns what changed on screen between the reads before and after. Each lane keeps one Maestro session warm, so a look returns in a few tenths of a second and a tap in under a second. Text that ticks on its own, such as clocks and counters, is left out of that diff, so an empty diff after a tap means the tap changed nothing visible: look again before you assume it worked. `quick: true` taps without waiting for the screen to settle; it is for exploring, and its results aren't proof. A `takeScreenshot` in the YAML lands in `$AGENTLANE_LOGS/shots/`, and `run` prints each file's path.
|
|
26
|
+
|
|
27
|
+
A failed step comes back with its kind, the step, whether the action reached the device (yes, no or unknown), the screen as it is now, and selectors that would match. Read it before you retry: "no" means nothing happened and a corrected retry is safe; "unknown" means look first, because the app may have moved. An absence check (`assertNotVisible`) that Maestro passed is checked once more against the screen the step left: it fails when the read fails, and on a nearly empty read it fails only for text that no read in the run held, since that text could be drawn where the tree describes nothing. Select by id when you can: an id lives only in the tree, so its absence holds on any readable screen.
|
|
28
|
+
|
|
29
|
+
## Drive a browser with its driver
|
|
30
|
+
|
|
31
|
+
The lane's browser is driven by the driver the project picked (`web.browser.driver` in `agentlane.json`, Playwright by default), through that driver's own CLI. `node_modules/.bin/agentlane exec` binds it to your lane: it sets the driver's session, the web app's URL (`$AGENTLANE_WEB_URL`, and `PLAYWRIGHT_TEST_BASE_URL` for tests) and the saved login (`$AGENTLANE_STORAGE_STATE`), and puts the toolkit's pinned driver first on the PATH.
|
|
32
|
+
|
|
33
|
+
- Playwright: `node_modules/.bin/agentlane exec -- playwright-cli click e5`, `fill e5 "text"`, `goto <url>` (`playwright-cli --help` lists the rest). Pass a ref as `look` prints it. `playwright-cli find <text>` searches the snapshot `snapshot` prints, ignoring case, as the page is when it runs. It doesn't wait, so right after a `goto` a page that is still rendering gives "No matches": take a `snapshot` or run `find` again before you call the text absent.
|
|
34
|
+
- agent-browser: `node_modules/.bin/agentlane exec -- agent-browser click @e1`, `fill @e1 "text"`, `snapshot -i`. Put an `@` in front of the ref `look` prints.
|
|
35
|
+
|
|
36
|
+
The browser is headless unless the config sets `web.browser.headed`, which only Playwright supports; agent-browser always runs headless. When a person needs to watch the browser, that is the Playwright driver with `headed: true`, or a video.
|
|
37
|
+
|
|
38
|
+
The browser starts signed in when the project has a `signin` hook, so a page that shows a sign-in form means the hook or the account is wrong; fix that rather than signing in by hand. Pass no session flag (`-s=`, `--session`): `exec` already names yours, and a command aimed at another lane's session is denied. The toolkit installs pinned drivers and browsers in its own folder, so `npx playwright install` and the drivers' install commands aren't needed, and the wrappers refuse them because they would delete builds other sessions use.
|
|
39
|
+
|
|
40
|
+
## Probe, then prove
|
|
41
|
+
|
|
42
|
+
A probe shows you the steps; it isn't evidence, because nobody can replay it. A probe is done when the steps it found pass as a committed flow or test, run cold through the project's own runner.
|
|
43
|
+
|
|
44
|
+
- **Device:** `run` records every passing step of this session. `node_modules/.bin/agentlane record save <file>` writes them as a Maestro flow (`record show` lists them, `record clear` starts over). Steps from a flow file keep its `${NAME}` placeholders, so the saved flow needs the same values at replay (`maestro test -e METRO_PORT=<port> -e API_PORT=<port> <file>`, or the project runner's way of passing them). Steps you typed keep what you typed, such as a claimed port: swap those for the flow's variables. Put the flow beside the project's other flows and run it under `node_modules/.bin/agentlane exec`, where `maestro` is the toolkit's build bound to your device.
|
|
45
|
+
- **Browser:** write the steps as a Playwright test beside the project's others, by role and label rather than refs, and run it through the project's runner under exec: `node_modules/.bin/agentlane exec -- npx playwright test <file>`, or the project's script. Playwright Test takes its base URL from `PLAYWRIGHT_TEST_BASE_URL` on its own; the config gives the signed-in tests `storageState` from `AGENTLANE_STORAGE_STATE` and writes each run's output, traces kept on failure, to its own folder under `AGENTLANE_EVIDENCE`. The project's `@playwright/test` has to be the toolkit's Playwright version (`node_modules/.bin/agentlane browser status` names it), or the tests find no browser under exec. A config that doesn't read them yet is the run skill's to fix; the `create-verification-skill` skill says how.
|
|
46
|
+
|
|
47
|
+
## Evidence
|
|
48
|
+
|
|
49
|
+
Prove a behaviour with an assertion: the committed flow or test above, checking the end state, read back where it lands (a row, a file, a message) as well as on screen. Then add what the reader of your result needs, which is your call:
|
|
50
|
+
|
|
51
|
+
- a video when a user-visible change goes to a person: `node_modules/.bin/agentlane evidence video start`, drive it, `node_modules/.bin/agentlane evidence video stop`;
|
|
52
|
+
- a screenshot when the owner judges how it looks: `node_modules/.bin/agentlane evidence screenshot`;
|
|
53
|
+
- a trace when you need the steps in detail: `node_modules/.bin/agentlane evidence trace start`, then `stop`;
|
|
54
|
+
- logs when a server or the console explains a failure: `node_modules/.bin/agentlane evidence logs --since 5m`.
|
|
55
|
+
|
|
56
|
+
Each prints the file it wrote in the lane's evidence folder, `$AGENTLANE_EVIDENCE`, which outlives `release` by seven days; `node_modules/.bin/agentlane evidence list` shows what is there. A failed run, and a failed command under exec on a browser lane, keep their own bundle there (the trace, a screenshot, the page or screen, the console or driver log) without being asked. `maestro test` under exec or in a hook keeps its whole output there, its `takeScreenshot` files included, in a folder per run: `<stamp>-maestro-test-<pid>`, ending `-failed` when the test failed. Read that bundle before you retry, and name the files you cite in your report.
|
|
57
|
+
|
|
58
|
+
## Device controls
|
|
59
|
+
|
|
60
|
+
Settings that aren't taps live in the CLI, on the same claimed device: `node_modules/.bin/agentlane device location <lat>,<lon> | clear`, `device permission grant|revoke|reset <service> [<bundle id>]`, `device appearance light|dark`, `device push <bundle id> <payload.json | ->`, `device clipboard set <text> | get` and `device open <url>`. On an emulator, `location clear`, `push` and `clipboard` have no adb equivalent and refuse with the reason; `permission` takes the package name and grants the Android permissions behind the service that the app declares.
|
|
61
|
+
|
|
62
|
+
## Other sessions' devices and browsers
|
|
63
|
+
|
|
64
|
+
Run `simctl`, `adb` and the browser drivers only against your own lane: `$AGENTLANE_DEVICE` and the session `exec` sets. The toolkit's hook denies those commands when they aim at a simulator, emulator or browser session another lane holds, and also `booted`, `all` and an `adb` with no `-s` while other lanes hold devices; the denial names the holder and the command that recovers. `node_modules/.bin/agentlane status` lists every lane on the machine with its owner, folder and last action.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Lauren Tan
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: maintain-verification-skill
|
|
3
|
+
description: Keep a project's run skill and feature map true as the app changes, for its mobile app, its web app or both. One read-only reader per feature page checks it against the code, then one live pass drives every feature on the session's own lane (a simulator or emulator, a browser), ending in at most one PR of proven corrections. Product bugs it finds are reported, never written around in the map.
|
|
4
|
+
when_to_use: The user asks to audit or refresh a project's run skill or feature map; a run found a page wrong in a way that suggests wider drift; or a scheduled upkeep run. Needs a run skill with a features/ map; without one, use create-verification-skill.
|
|
5
|
+
license: Parts adapted from cursor/plugins (pstack) under the MIT License, Copyright (c) 2026 Lauren Tan; the full notice is in LICENSE beside this skill in the toolkit package
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
<!-- Adapted from cursor/plugins (pstack/skills/maintain-verification-skill), MIT License, Copyright (c) 2026 Lauren Tan; full notice in ./LICENSE -->
|
|
9
|
+
|
|
10
|
+
# Maintain a verification skill <!-- upstream: pstack-maintain-verification-skill -->
|
|
11
|
+
|
|
12
|
+
A feature map goes stale the moment the app changes. This pass keeps a project's run skill folder honest (`.agents/skills/run/`, or `.claude/skills/run/` in a project that keeps it there). The unit of rigor is the feature: every page gets checked against the code and every feature gets driven live on each platform it ships on, without turning each bullet into a terminal command.
|
|
13
|
+
|
|
14
|
+
## Outcomes
|
|
15
|
+
|
|
16
|
+
The pass is done when every page has a source reader's summary and a live drive on each of its platforms (or a verified-unreachable note), and you have named one of these outcomes:
|
|
17
|
+
|
|
18
|
+
- **clean:** every feature had source and live coverage, and nothing needs shipping. No branch, no PR.
|
|
19
|
+
- **changed:** one PR of proven corrections.
|
|
20
|
+
- **blocked:** coverage couldn't finish, or a proven fix couldn't ship safely. Say exactly what blocked it.
|
|
21
|
+
|
|
22
|
+
## Edit scope
|
|
23
|
+
|
|
24
|
+
Edit only the run skill's folder (its SKILL.md and `features/`), the project's `agentlane.json`, the hook scripts it names and the flows they run, and the lane-reading parts of the flow and test configs (a Maestro flow's variables, the Playwright config's base URL, saved login and output folder). Never edit product code during a pass. When the app no longer does what a page says, decide which it is: the page drifted, so fix the page, or the product regressed, so report it and leave the page describing what should happen.
|
|
25
|
+
|
|
26
|
+
## The pass
|
|
27
|
+
|
|
28
|
+
1. **Index.** Read `features/README.md` and list the pages beside it. Fix missing, extra, duplicate and dead entries. A thin page, one that says it hasn't been driven yet, gets its full sections from this pass: its reader's summary and the live drive.
|
|
29
|
+
2. **Source readers.** One read-only subagent per page, all launched at once. Each explains how its feature works from the code, flags likely drift with `file:line` citations, and returns one live recipe. Readers never drive the app or edit files. Each returns: a summary, the source entry points, likely drift or none, and one recipe.
|
|
30
|
+
3. **Reconcile.** Every page has a returned summary. Merge overlapping recipes into as few app states as you can. Spot-check cited drift; don't re-prove clean claims. Look through recent commits for user-facing features the map lacks, and name a concrete source path before calling one missing.
|
|
31
|
+
4. **Live pass.** Required even when the code looks clean. You do all the driving, on your own lane: `node_modules/.bin/agentlane up` in your folder (`--platform web` for the web app, and the mobile platform for the app; one lane holds both), the `drive` skill for driving (the device tools on a device, the driver's CLI under `exec` in the browser), and the project's committed flows and tests for proof (Maestro flows and Playwright tests, run under `exec`). Drive every feature at least once on each platform its page lists, and hold these the whole way:
|
|
32
|
+
- Run `node_modules/.bin/agentlane doctor` (with `--platform` for each platform you drive) before the first drive and after anything surprising. Where the doctor can't see the fault (a stuck screen on a healthy process, a page that won't load), relaunch with `node_modules/.bin/agentlane up` instead of hoping.
|
|
33
|
+
- Check that evidence survives every cleanup, at its named location; the lane's `$AGENTLANE_EVIDENCE` outlives `release`.
|
|
34
|
+
- Clean up whatever a failed drive left behind.
|
|
35
|
+
- Read the logs of the flows the hooks run during `up`, such as a sign-in or setup flow, whose paths `up` prints. A WARNED step there is a wait or tap that never matches, which costs every lane its timeout: fix it as drift in the hook's flow, waiting on a handle the driver can see, required and with a bounded timeout.
|
|
36
|
+
|
|
37
|
+
A doctor failure caused by the skill's own drift is drift: fix it in scope and retry once before calling the pass blocked. A feature you can't reach counts as verified-unreachable only with the missing prerequisite (an account, an entitlement, an OS version, a browser the driver lacks, outside state) and the route you tried; if the page omits that prerequisite, that's drift too. Re-drive anything you fixed before it ships. Run `node_modules/.bin/agentlane release` when the pass is done.
|
|
38
|
+
|
|
39
|
+
5. **Triage.** A wrong or missing user-side description is drift: fix the page. Working behavior the harness can't drive is a harness gap: fix the harness, as an executable helper the skill shows. Behavior that's actually broken is a product bug: record it for the user, outside this PR.
|
|
40
|
+
6. **Ship or stop.** For changed, open one PR through the project's usual gates, after rereading every changed file. For clean or blocked, open nothing and report the outcome and the coverage honestly.
|
|
41
|
+
|
|
42
|
+
Keep short run notes (features covered, unreachable prerequisites, confirmed drift, outcome) in the scratchpad, not the repo.
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: setup
|
|
3
|
+
description: Set a project up with the toolkit from nothing - find how it runs its mobile app, web app, servers, data and sign-in, wire the agents the user works in with `agentlane init`, write and validate `agentlane.json` (services, a device or a browser or both, per-lane resources, sign-in), build or adapt the run skill and its flows through create-verification-skill, then bring each app up until `agentlane doctor` reports ready. Use when a user asks to set up, install, adopt or configure the toolkit in a project, or when `up` or `doctor` names the setup skill because the config is missing or invalid or no agent is wired.
|
|
4
|
+
when_to_use: A project with no agentlane.json, an agentlane.json that fails validation, no agent wiring, or a user asking to set the toolkit up, redo its setup or add a platform to it. Not for a project that already reaches doctor ready and only needs its run skill or feature map, which create-verification-skill and maintain-verification-skill cover.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Set a project up with the toolkit
|
|
8
|
+
|
|
9
|
+
Setup takes a project from no toolkit wiring to every app it ships coming up on its own lane. The agent decides per project from what the repo already does; there are no presets. It asks the user only for real trade-offs and for facts it can't find, and it changes the project's own code only where the toolkit can't work without it (a server that hard-codes its port, say).
|
|
10
|
+
|
|
11
|
+
Setup is done when `node_modules/.bin/agentlane doctor --platform <p>` reports `ready` for every platform `agentlane.json` declares, every committed flow and test suite has a result in the lane (through `node_modules/.bin/agentlane exec`) or is listed with the command that runs it and why it didn't run, none that passed before setup fails now, every lane you claimed is released, and the user has the summary from step 7.
|
|
12
|
+
|
|
13
|
+
Run the toolkit from the project root as `node_modules/.bin/agentlane <command>`, as written here; a bare `agentlane` is on the PATH only in Claude Code with the toolkit's plugin, and the run skill you write has to work in every agent the user names.
|
|
14
|
+
|
|
15
|
+
Its quality depends on the model. If the user didn't say they started it that way, tell them once, in your first message, that setup works best on their agent's strongest model at its highest effort (in Claude Code, `/model opus` and `/effort xhigh`), then carry on.
|
|
16
|
+
|
|
17
|
+
## 1. Survey the project
|
|
18
|
+
|
|
19
|
+
Read the repo before deciding anything; the answers are usually there. For each item, note where you found it, or that the project has none:
|
|
20
|
+
|
|
21
|
+
- **Apps:** a mobile app (Expo or React Native, an Xcode project, a Gradle project), a web app (Next.js, Vite, Remix and the like, an admin panel), or both, and where each lives in a monorepo.
|
|
22
|
+
- **Servers:** every long-running process the apps need (Metro, an API, a web dev server, workers, a local database container), how the repo starts each (package scripts, a justfile or Makefile, Procfile, docker compose, dev scripts), and the port each binds. A hard-coded port is a collision between agents.
|
|
23
|
+
- **Data:** the database and other stateful stores, whether they run locally or are hosted, and how the project's tests create, migrate, seed and reset them.
|
|
24
|
+
- **Sign-in:** how a user signs in, the test accounts, where their credentials come from (variable names in env example files and CI; never print a secret's value), and any seam the tests already use (a token endpoint, a deep link, a Playwright setup project that saves a login).
|
|
25
|
+
- **Proof that exists:** committed Maestro flows, Playwright suites (and the `@playwright/test` version they pin), other end-to-end tests, and how CI runs them.
|
|
26
|
+
- **How agents run it today:** run skills (`.agents/skills/run/`, `.claude/skills/run/`), `AGENTS.md`, `CLAUDE.md`, README and docs pages on running locally, and the agent folders the repo commits (`.claude/`, `.codex/`, `.cursor/`, `.gemini/`, `.github/hooks/`, `.agents/`).
|
|
27
|
+
- **The toolkit itself:** `node_modules/.bin/agentlane --version` at the project root. The hooks and MCP servers that `init` writes look for it there.
|
|
28
|
+
|
|
29
|
+
The survey is done when every item has an answer with its file path, or "none".
|
|
30
|
+
|
|
31
|
+
## 2. Record the baseline
|
|
32
|
+
|
|
33
|
+
Find out which committed flows and suites pass before you change anything, so you can show later that setup broke none of them. Run each the way CI or the docs run it where that works on this machine without installing simulators or browsers; otherwise read its last result on the default branch in CI, or mark it unknown. The baseline is done when each suite is marked pass, fail or unknown, with the command or CI run behind the mark. An unknown mark is settled in step 6, which runs every flow and suite in the lane.
|
|
34
|
+
|
|
35
|
+
## 3. Decide, and ask once
|
|
36
|
+
|
|
37
|
+
Decide each of these from the survey, with a one-line reason you'll repeat in the summary:
|
|
38
|
+
|
|
39
|
+
- **Platforms:** declare each app the project ships: `app` for the mobile app, `web` for the web app, or both. A project with an admin panel beside its site has two web services; declare the one agents most need as `web` and the other as a service the run skill opens by URL.
|
|
40
|
+
- **Data per lane or shared:** when the tests already create a local database (a Docker Postgres, SQLite, a local Supabase stack), give each lane its own copy as a resource: a database named after the lane, created, migrated and seeded the way the tests do, and dropped at teardown. When the project relies on a shared hosted database with no local equivalent, keep it shared, and have the run skill name what a write must clean up. When both are possible but they differ in a way the user cares about (local needs Docker, lacks an extension, or misses data only the hosted copy has), that is a trade-off to ask about.
|
|
41
|
+
- **Sign-in:** which account each lane signs in as, and through which seam. Prefer the app's own sign-in endpoint with a test account, called from the `signin` hook; on the web the hook writes the saved login the lane's browser starts with.
|
|
42
|
+
- **Browser driver:** Playwright, unless the project already drives browsers with agent-browser. When a person wants to watch the browser, Playwright with `web.browser.headed: true`, since agent-browser runs headless only. The project's `@playwright/test` must be the toolkit's Playwright version (`node_modules/.bin/agentlane browser status` names it), or its tests find no browser in a lane; moving the pin to that version is a change setup makes and reports, and a pin the project must keep for another reason is a question for the user.
|
|
43
|
+
- **Agents to wire:** the agent you are running in, and every agent whose folder the repo already commits. Wherever Claude Code loads the toolkit's plugin (the project's settings, the user's, or the session you run in), `init` leaves Claude Code to the plugin rather than writing a second copy of its skills, MCP server and hooks, and says which it found. When only the user's settings or the session load it, someone who opens the project without the plugin gets no Claude Code wiring from the committed files; that goes in the summary with init's note.
|
|
44
|
+
|
|
45
|
+
Collect what only the user can answer as you go: a real trade-off, a credential or account you can't find or create, a hosted database the project must keep. Ask them in one message, after the survey, each with your recommended answer, and keep working on everything that doesn't depend on the answers. When no one can answer, as in a non-interactive run, take your recommendation and list it in the summary as an assumption.
|
|
46
|
+
|
|
47
|
+
This step is done when every decision above has an answer and a reason, and every question has a reply or a recorded assumption.
|
|
48
|
+
|
|
49
|
+
## 4. Install the toolkit and wire the agents
|
|
50
|
+
|
|
51
|
+
Run `node_modules/.bin/agentlane init --agents <list>` (the names it takes: `claude`, `codex`, `cursor`, `copilot`, `gemini`, `antigravity`). When `node_modules/.bin/agentlane` is missing at the project root, run `npx agentlane init --agents <list>` instead: init adds the toolkit to the project's `package.json` as a dev dependency with the project's package manager, creating a private `package.json` when there is none, and prints what it did, which goes in the summary. When it exits 1 because the install failed, run the command it prints and fix what stops it. When the user installs the toolkit from another source than npm (ask if the repo doesn't show one), add it from there before you run init. It writes each agent's skill stubs in `.agents/skills/` (mirrored into `.claude/skills/` for Claude Code), its MCP server entry and its hooks, backs up what it changes, and refuses a file it can't parse with nothing written; fix or report a refusal rather than editing around it. Keep the per-agent notes it prints for the summary: they are the trust prompts the user must accept. `node_modules/.bin/agentlane init --agents <list> --check` exits 0 once the wiring is complete.
|
|
52
|
+
|
|
53
|
+
## 5. Write the config, the run skill and the flows
|
|
54
|
+
|
|
55
|
+
Load the `create-verification-skill` skill and follow it: your survey and decisions answer its interview, and it writes `agentlane.json` (services, apps, resources, sign-in, preconditions), adapts the committed Maestro flows and Playwright suites to run in a lane while keeping them passing where they ran before, and writes or extends the run skill in `.agents/skills/run/` with its feature map. Keep what a project's existing run skill and dev scripts already get right, and make the servers the project starts by hand into services rather than leaving steps for the agent to repeat.
|
|
56
|
+
|
|
57
|
+
Once the run skill exists, run `node_modules/.bin/agentlane init --agents <list>` again, so Claude Code's `.claude/skills/` mirrors it too. This step is done when `node_modules/.bin/agentlane doctor`'s `config` line is `ok` (it validates against the schema `node_modules/.bin/agentlane schema` prints), `init --check` exits 0, and create-verification-skill's own completion criterion holds.
|
|
58
|
+
|
|
59
|
+
## 6. Bring each platform up until doctor is ready
|
|
60
|
+
|
|
61
|
+
For each platform the config declares, run `node_modules/.bin/agentlane up --platform <p>`, and read every `FAIL` line and its fix. Fix the cause where it lives (the config, a hook, a server that ignores its port, a missing precondition), then run `up` again; the lane is reused and healthy services are kept. A first iOS or Android build can take many minutes: start `up` the way your agent runs a long command in the background, and check on it rather than restarting it. You don't need a log file of your own for it. `up` writes each hook's output, the build's included, into the lane's log folder as it runs, and prints the path when the hook starts (`build: <command> (log: <folder>/hooks/build.log)`), so follow the build there. Any log you do write goes in that folder too (`$AGENTLANE_LOGS` under `exec`, and the folder `up` names in `logs in <folder>`), not in the project or a folder beside or above it. Release after a failed attempt you won't continue, so nothing is left running.
|
|
62
|
+
|
|
63
|
+
Then run every committed Maestro flow and every Playwright or other end-to-end suite once in the lane, each the way the project runs it (`node_modules/.bin/agentlane exec -- <command>`, a flow at a time through the project's own runner when it has one), and record each result by name. This run gives the baseline's unknowns their result.
|
|
64
|
+
|
|
65
|
+
- Where you changed code the flows and suites run through (the app, its servers and their start scripts, the project's test tooling), run them once before those changes and once after, so a failure setup caused shows as a change: bring the lane up on the config and hooks first, run everything, then make the code changes and run everything again. When the lane can't come up without a change, the first run comes right after it; say so for those flows.
|
|
66
|
+
- A flow or suite that passed before and fails now is setup's to fix; one that failed before is reported, not fixed.
|
|
67
|
+
- One that needs what `up` doesn't make, such as a Release build for performance flows or data only an exclusive reset writes, may stay unrun, listed with the command that runs it and the reason. Every committed flow and suite appears in the results either way.
|
|
68
|
+
|
|
69
|
+
When every platform reports ready and the results are in, run `node_modules/.bin/agentlane release`.
|
|
70
|
+
|
|
71
|
+
This step is done when the completion criterion at the top holds, apart from the summary.
|
|
72
|
+
|
|
73
|
+
## 7. Summarize for the user
|
|
74
|
+
|
|
75
|
+
End with a short summary, in this order:
|
|
76
|
+
|
|
77
|
+
- **Wrote:** each file created or changed, one line each, with what it is for.
|
|
78
|
+
- **Decided:** each decision from step 3 with its reason, and each assumption you made for an unanswered question.
|
|
79
|
+
- **Checked:** the `doctor` result per platform, and every committed flow and suite by name: its baseline mark, its result in the lane (before and after your code changes, where you made any), or the command that runs it and why it stayed unrun. A table holds many flows best.
|
|
80
|
+
- **You need to:** what only the user can do: the trust prompts `init` named for each agent, secrets or accounts you couldn't create (where each goes), and reviewing and committing the changes. Leave the commit to them unless they asked you to make it.
|