@plainconceptsplatform/agent-harness 3.3.1 → 3.5.0

package/skills/pc-repo-initialize/SKILL.md

@@ -1,119 +1,119 @@
----
-name: pc-repo-initialize
-description: "Initialize the project. Presents a single form with all setup questions, then executes selected steps. Invoked by the /init command (alias: /repo-initialize)."
-license: MIT
----
-
-First read `AGENTS.md`. Without the `<!-- PC-NOT-INITIALIZED -->` marker the project is already initialized: say so, and point at `/make-architecture` or `/make-design` for a refresh. With it, run the sequence below.
-
-## Rules
-
-- Write only to `ARCHITECTURE.md`, `DESIGN.md`, `AGENTS.md`, `openspec/` and `.agents/skills/`. Source files are read for analysis, never edited: init sets a project up, it does not implement anything, and it creates no branches or pull requests.
-- Ask the five questions in one `question` call. Five separate prompts is five chances for the user to walk away from a setup that does nothing until it finishes.
-- A step whose answer was No is skipped, not approximated.
-
-## Step 1, Ask everything at once
-
-```json
-{
-  "questions": [
-    {
-      "header": "Type",
-      "question": "What type of project is this?",
-      "options": [
-        { "label": "brownfield", "description": "Existing codebase. Generate docs from your code." },
-        { "label": "greenfield", "description": "Starting from scratch, little or no existing code." }
-      ]
-    },
-    {
-      "header": "History",
-      "question": "Archive project history into OpenSpec?",
-      "options": [
-        { "label": "Yes", "description": "Scan codebase for existing docs, changelogs, decisions and archive them." },
-        { "label": "No", "description": "Skip history archival." }
-      ]
-    },
-    {
-      "header": "Architecture",
-      "question": "Generate ARCHITECTURE.md from the codebase?",
-      "options": [
-        { "label": "Yes", "description": "Analyze project structure and generate architecture documentation." },
-        { "label": "No", "description": "Skip, leave as placeholder." }
-      ]
-    },
-    {
-      "header": "Design",
-      "question": "Generate DESIGN.md from the design system?",
-      "options": [
-        { "label": "Yes", "description": "Analyze Tailwind, CSS vars, tokens and generate design documentation." },
-        { "label": "No", "description": "Skip, leave as placeholder." }
-      ]
-    },
-    {
-      "header": "Evidence",
-      "question": "Record how the app starts and how a person signs in locally, so merged changes get screenshots?",
-      "options": [
-        { "label": "Yes", "description": "Fill the project environment in pc-repo-verify: start command, URL, local sign-in, seeded data." },
-        { "label": "No", "description": "Skip; the verification plans will look for the sign-in themselves." }
-      ]
-    }
-  ]
-}
-```
-
-## Step 2, Sync skills
-
-Always. `npx skills experimental_install --yes` in the project root installs what onboarding queued in `skills-lock.json`. A failure here is a warning, not a stop: the optional ones can be added later.
-
-## Step 3, Archive project history
-
-If Yes. Scan the roots in `.opencode/source-roots.json` (plus this repo's own docs and config) for documentation, changelogs, ADRs, READMEs and anything else that records how the project got here. Then:
-
-```bash
-openspec new change "project-history"
-```
-
-Write a `proposal.md` in it covering what the project is, the decisions already taken, the tech debt and constraints the code shows, and where things stand. Archive it immediately, with `-y` so it cannot block:
-
-```bash
-openspec archive "project-history" -y
-```
-
-## Step 4, Generate ARCHITECTURE.md
-
-If Yes. Load `pc-make-architecture`.
-
-## Step 5, Generate DESIGN.md
-
-If Yes. Load `pc-make-design`.
-
-## Step 6, Generate guardrails
-
-Always. Load `pc-make-guardrails`.
-
-## Step 7, Visual evidence
-
-If Yes. Every change's verification plan (`pc-repo-verify`) is replayed in headless Chromium by the evidence workflow when its pull request merges, from a freshly started app with nothing in the browser. Find in the source, and confirm by reading the root `package.json`, `.env.example` and the local auth setup:
-
-- the command that starts the whole stack with mock authentication (normally `pnpm run dev` at the root),
-- the URL the web app answers on,
-- the local sign-in: the exact steps and visible labels of the mock account picker or dev login,
-- the data a fresh start seeds (accounts, records) that a journey can rely on.
-
-Write them as the bullet list between `<!-- PC-PROJECT-ENVIRONMENT-START -->` and `<!-- PC-PROJECT-ENVIRONMENT-END -->` in `.agents/skills/pc-repo-verify/SKILL.md`, replacing the placeholder bullets. Only that slot: the rest of the file is the harness's, and an update keeps only the slot.
-
-## Step 8, Show help
-
-Load `pc-repo-help` and display the command reference as written.
-
-## Step 9, Confirm
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Initialization complete.
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Restart OpenCode now.
-Nothing will work correctly until you do.
-After restarting you are ready to work.
-```
+---
+name: pc-repo-initialize
+description: "Initialize the project. Presents a single form with all setup questions, then executes selected steps. Invoked by the /init command (alias: /repo-initialize)."
+license: MIT
+---
+
+First read `AGENTS.md`. Without the `<!-- PC-NOT-INITIALIZED -->` marker the project is already initialized: say so, and point at `/make-architecture` or `/make-design` for a refresh. With it, run the sequence below.
+
+## Rules
+
+- Write only to `ARCHITECTURE.md`, `DESIGN.md`, `AGENTS.md`, `openspec/` and `.agents/skills/`. Source files are read for analysis, never edited: init sets a project up, it does not implement anything, and it creates no branches or pull requests.
+- Ask the five questions in one `question` call. Five separate prompts is five chances for the user to walk away from a setup that does nothing until it finishes.
+- A step whose answer was No is skipped, not approximated.
+
+## Step 1, Ask everything at once
+
+```json
+{
+  "questions": [
+    {
+      "header": "Type",
+      "question": "What type of project is this?",
+      "options": [
+        { "label": "brownfield", "description": "Existing codebase. Generate docs from your code." },
+        { "label": "greenfield", "description": "Starting from scratch, little or no existing code." }
+      ]
+    },
+    {
+      "header": "History",
+      "question": "Archive project history into OpenSpec?",
+      "options": [
+        { "label": "Yes", "description": "Scan codebase for existing docs, changelogs, decisions and archive them." },
+        { "label": "No", "description": "Skip history archival." }
+      ]
+    },
+    {
+      "header": "Architecture",
+      "question": "Generate ARCHITECTURE.md from the codebase?",
+      "options": [
+        { "label": "Yes", "description": "Analyze project structure and generate architecture documentation." },
+        { "label": "No", "description": "Skip, leave as placeholder." }
+      ]
+    },
+    {
+      "header": "Design",
+      "question": "Generate DESIGN.md from the design system?",
+      "options": [
+        { "label": "Yes", "description": "Analyze Tailwind, CSS vars, tokens and generate design documentation." },
+        { "label": "No", "description": "Skip, leave as placeholder." }
+      ]
+    },
+    {
+      "header": "Evidence",
+      "question": "Record how the app starts and how a person signs in locally, so merged changes get screenshots?",
+      "options": [
+        { "label": "Yes", "description": "Fill the project environment in pc-repo-verify: start command, URL, local sign-in, seeded data." },
+        { "label": "No", "description": "Skip; the verification plans will look for the sign-in themselves." }
+      ]
+    }
+  ]
+}
+```
+
+## Step 2, Sync skills
+
+Always. `npx skills experimental_install --yes` in the project root installs what onboarding queued in `skills-lock.json`. A failure here is a warning, not a stop: the optional ones can be added later.
+
+## Step 3, Archive project history
+
+If Yes. Scan the roots in `.opencode/source-roots.json` (plus this repo's own docs and config) for documentation, changelogs, ADRs, READMEs and anything else that records how the project got here. Then:
+
+```bash
+openspec new change "project-history"
+```
+
+Write a `proposal.md` in it covering what the project is, the decisions already taken, the tech debt and constraints the code shows, and where things stand. Archive it immediately, with `-y` so it cannot block:
+
+```bash
+openspec archive "project-history" -y
+```
+
+## Step 4, Generate ARCHITECTURE.md
+
+If Yes. Load `pc-make-architecture`.
+
+## Step 5, Generate DESIGN.md
+
+If Yes. Load `pc-make-design`.
+
+## Step 6, Generate guardrails
+
+Always. Load `pc-make-guardrails`.
+
+## Step 7, Visual evidence
+
+If Yes. Every change's verification plan (`pc-repo-verify`) is replayed in headless Chromium by the evidence workflow when its pull request merges, from a freshly started app with nothing in the browser. Find in the source, and confirm by reading the root `package.json`, `.env.example` and the local auth setup:
+
+- the command that starts the whole stack with mock authentication (normally `pnpm run dev` at the root),
+- the URL the web app answers on,
+- the local sign-in: the exact steps and visible labels of the mock account picker or dev login,
+- the data a fresh start seeds (accounts, records) that a journey can rely on.
+
+Write them as the bullet list between `<!-- PC-PROJECT-ENVIRONMENT-START -->` and `<!-- PC-PROJECT-ENVIRONMENT-END -->` in `.agents/skills/pc-repo-verify/SKILL.md`, replacing the placeholder bullets. Only that slot: the rest of the file is the harness's, and an update keeps only the slot.
+
+## Step 8, Show help
+
+Load `pc-repo-help` and display the command reference as written.
+
+## Step 9, Confirm
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Initialization complete.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Restart OpenCode now.
+Nothing will work correctly until you do.
+After restarting you are ready to work.
+```

package/skills/pc-repo-onboard/SKILL.md

@@ -1,32 +1,32 @@
----
-name: pc-repo-onboard
-description: Walk the user through the project and its agentic infrastructure. Explains what exists, how agents work, and how to use the system. Invoked by the /repo-onboard command.
-license: MIT
----
-
-A guided tour of this repository and the harness installed in it, for somebody who has just arrived. Read and explain; change nothing.
-
-## Rules
-
-- Never write, edit, or create a file, and never run a command from the tour to demonstrate it. The output is the explanation.
-- Never describe an agent, command, skill or setting that is not in this repository. The tour is worth having because it is specific: read `.opencode/agents/`, `.opencode/commands/`, `.agents/skills/`, `.opencode/harness.json`, `AGENTS.md`, `ARCHITECTURE.md` and `DESIGN.md` and report what is actually there.
-
-## Cover, in this order
-
-1. **The project.** Three to five bullets: what it is, the stack, the directories that matter.
-2. **The agents.** One table row per file in `.opencode/agents/`, with its tier and purpose. Then the selection model: `build` and `plan` are the only two a human picks and both run the `fullstack-engineer` body, `plan` can neither edit nor spawn, everything else is `mode: subagent` and reached through `task()`, and a missing specialist is made with `/make-engineer`.
-3. **The commands**, grouped by what they are for:
-
-   | Group | Commands |
-   |---|---|
-   | Planning | `/plan-explore`, `/plan-story`, `/plan-propose`, `/plan-quick`, `/plan-goal` |
-   | Implementation | `/plan-apply`, `/plan-archive` |
-   | Maintenance | `/make-architecture`, `/make-design`, `/make-engineer`, `/make-guardrails` |
-   | Shipping | `/ops-ship`, `/ops-review`, `/ops-backlog` |
-   | Quality | `/repo-audit` (read-only), `/repo-verify` (writes the verification plan) |
-   | Setup | `/init`, `/make-user-model`, `/repo-help` |
-
-4. **The skills** installed in `.agents/skills/`, one line each, marking which are platform-specific.
-5. **The OpenSpec lifecycle**: explore, propose, apply, archive, and what `openspec/config.yaml` controls.
-6. **The configuration** in `.opencode/harness.json`: what each section governs, that `/make-user-model` changes a tier's model, and what `agents.maxConcurrent` caps.
-7. **Where to start.** `/plan-goal` with a description of the work, `/repo-help` for everything else, and `npx @plainconceptsplatform/agent-harness` to refresh the harness after changing config.
+---
+name: pc-repo-onboard
+description: Walk the user through the project and its agentic infrastructure. Explains what exists, how agents work, and how to use the system. Invoked by the /repo-onboard command.
+license: MIT
+---
+
+A guided tour of this repository and the harness installed in it, for somebody who has just arrived. Read and explain; change nothing.
+
+## Rules
+
+- Never write, edit, or create a file, and never run a command from the tour to demonstrate it. The output is the explanation.
+- Never describe an agent, command, skill or setting that is not in this repository. The tour is worth having because it is specific: read `.opencode/agents/`, `.opencode/commands/`, `.agents/skills/`, `.opencode/harness.json`, `AGENTS.md`, `ARCHITECTURE.md` and `DESIGN.md` and report what is actually there.
+
+## Cover, in this order
+
+1. **The project.** Three to five bullets: what it is, the stack, the directories that matter.
+2. **The agents.** One table row per file in `.opencode/agents/`, with its tier and purpose. Then the selection model: `build` and `plan` are the only two a human picks and both run the `fullstack-engineer` body, `plan` can neither edit nor spawn, everything else is `mode: subagent` and reached through `task()`, and a missing specialist is made with `/make-engineer`.
+3. **The commands**, grouped by what they are for:
+
+   | Group | Commands |
+   |---|---|
+   | Planning | `/plan-explore`, `/plan-story`, `/plan-propose`, `/plan-quick`, `/plan-goal` |
+   | Implementation | `/plan-apply`, `/plan-archive` |
+   | Maintenance | `/make-architecture`, `/make-design`, `/make-engineer`, `/make-guardrails` |
+   | Shipping | `/ops-ship`, `/ops-review`, `/ops-backlog` |
+   | Quality | `/repo-audit` (read-only), `/repo-verify` (writes the verification plan) |
+   | Setup | `/init`, `/make-user-model`, `/repo-help` |
+
+4. **The skills** installed in `.agents/skills/`, one line each, marking which are platform-specific.
+5. **The OpenSpec lifecycle**: explore, propose, apply, archive, and what `openspec/config.yaml` controls.
+6. **The configuration** in `.opencode/harness.json`: what each section governs, that `/make-user-model` changes a tier's model, and what `agents.maxConcurrent` caps.
+7. **Where to start.** `/plan-goal` with a description of the work, `/repo-help` for everything else, and `npx @plainconceptsplatform/agent-harness` to refresh the harness after changing config.

package/skills/pc-repo-verify/SKILL.md

@@ -1,150 +1,150 @@
----
-name: pc-repo-verify
-description: Write the verification plan for the completed change, a journey through the new functionality as a fenced YAML block that the evidence workflow replays in headless Chromium after the pull request merges. Does not run checks, launch a browser, or take screenshots. Invoked by /repo-verify and the plan-goal pipeline.
-license: MIT
----
-
-# Repo Verify
-
-Write the verification plan for the current branch's change. The checks gate lives in `pc-plan-apply` step 10 (lint, typecheck, test, build). This skill produces the reproduction plan instead: a journey through the new functionality with one screenshot per waypoint.
-
-The plan is executed by a machine, not read by one. When the pull request merges, the evidence workflow (`evidence.yml` from `@plainconceptsplatform/workflows`) checks out the pull request head, starts the app, replays every step below in headless Chromium with no model in the loop, and archives one screenshot per waypoint in an `evidence/` folder beside this plan on the default branch, shown in one comment on the pull request. A step it cannot follow is a screenshot of the wrong screen. Write every step so it can be followed literally from a freshly started app.
-
-This skill never launches a browser, never takes a screenshot, never starts a server. It only reads the change and writes a plan file.
-
-Work only on the current branch: do not switch branches, push, create pull requests, or contact external platforms. Write the plan into the change directory; it is carried into the archive by `pc-plan-archive`. Never create or edit an `evidence/` folder: the workflow writes it beside the archived plan after the merge.
-
-## Project environment
-
-How this project's app starts, where it answers, how a person signs in locally, and what data a fresh start already has. Read it before writing a journey; it is the project's, and an update keeps it.
-
-<!-- PC-PROJECT-ENVIRONMENT-START -->
-- Start: `pnpm run dev` at the repository root brings up the whole stack with mock authentication.
-- URL: `http://localhost:3000`.
-- Sign-in: none recorded yet. Find the local sign-in (a mock account picker, a dev login button) in the source and write its steps into the first waypoint.
-- Seeded data: none recorded yet. Create what the journey needs through the UI.
-<!-- PC-PROJECT-ENVIRONMENT-END -->
-
-## Step 1: Read the change
-
-1. Resolve the change id from the caller (autonomous mode) or from the current branch's unarchived change under `openspec/changes/<change-id>/`. Read `proposal.md`, `tasks.md`, and `design.md` when present.
-2. Read `.opencode/source-roots.json` when it exists; use its non-empty `roots` array to scope frontend source, otherwise use the repository root.
-3. Inspect `git diff` against the branch base and the working tree for context on what changed.
-
-## Step 2: Determine UI impact
-
-Decide whether the change is reachable from something a user sees or does in the browser.
-
-1. **Direct**: changed files include user-visible UI: `*.tsx`/`jsx`/`vue`/`svelte`, `*.css`/`scss`/`less`, pages, layouts, components, navigation, routes. The affected surfaces are the routes/components the diff touches.
-2. **Indirect (backend-only diff, frontend-affected)**: the diff touches only API/backend code, but the changed contract is consumed by the frontend. Trace it: for every changed endpoint, route, handler, query, or exported function, search the frontend source roots for references to that name or path. If any reference exists, the frontend **is** affected. Map the surfaces (the routes/components that import or call the changed contract) and build the journey through them.
-3. **None**: no path reaches the frontend. Write the stub plan (Step 3, `status: not-applicable`) and stop. Do not fabricate a journey.
-
-Mixed or unknown counts as affected: be safe.
-
-## Step 3: Write the plan
-
-Write `verification-plan.md` into the change directory:
-
-```
-openspec/changes/<change-id>/verification-plan.md
-```
-
-Prose around the block is for people and is ignored by the replay. The replay reads the first fenced `yaml` block that holds a `journey`:
-
-````markdown
-# Verification plan: <change-id>
-
-One or two sentences on what the journey proves.
-
-```yaml
-url: http://localhost:3000
-journey:
-  - capture: home
-    expect: signed in, the item list is the home page
-    steps:
-      - open: /
-      - click: { role: button, name: Alice Admin }
-      - wait: { role: heading, name: Items }
-
-  - capture: detail-before
-    expect: the detail panel shows the item without a status badge
-    steps:
-      - click: { text: Seeded item }
-      - wait: { load: networkidle }
-
-  - capture: detail-active
-    expect: the status badge reads Active
-    steps:
-      - click: { role: button, name: Activate }
-      - wait: { text: Active }
-```
-````
-
-### Keys
-
-- `url`: where the app answers once started, from the project environment above. Relative `open:` paths resolve against it.
-- `start` (optional): the command that starts the app, only when it is not the project's default.
-- `viewport` (optional): `1280x800` unless the change is about another size.
-- `journey`: the waypoints, in order, in one browser tab. Each has a `capture` (kebab-case, unique), an `expect` (what is visible in the screenshot), and the `steps` that get there from the previous waypoint.
-
-### Steps
-
-Each step is a map with exactly one action:
-
-| Step | Does |
-|---|---|
-| `open: /path` | navigate (relative to `url`, or a full URL) |
-| `click: <locator>` | click; add `button: right` inside the locator for a context menu |
-| `dblclick: <locator>`, `hover: <locator>`, `check: <locator>`, `uncheck: <locator>` | as named |
-| `fill: { <locator>, value: text }` | replace the field's text |
-| `select: { <locator>, value: option }` | choose an option |
-| `press: Enter` or `press: { <locator>, key: Enter }` | press a key |
-| `wait: <locator>` | until the element is visible |
-| `wait: { text: Saved }` | until the text is visible |
-| `wait: { load: networkidle }` | until the page settles; never a failure on its own |
-| `wait: { url: /items/ }` | until the address contains it |
-| `wait: { ms: 500 }` | a fixed pause, only for an animation with nothing to wait on |
-
-A locator is one of `{ role: button, name: Save }`, `{ text: Save }`, `{ label: Name }`, `{ placeholder: Search }`, `{ testid: save }`, `{ alt: Logo }`, `{ title: Close }`, or `{ css: ".row" }`, optionally with `nth: 1` or `last: true`. The first match is used.
-
-### Rules
-
-1. The first waypoint starts with `open` and signs in, using the sign-in from the project environment. The replay starts from a freshly started app with nothing in the browser.
-2. Everything the journey needs that a fresh start does not have, create through the UI in the steps (a record to open, a setting to change). Never assume data from a developer's machine.
-3. Place waypoints as a pre/post pair around the changed behavior: the state immediately before and immediately after the core change is exercised.
-4. Use the minimum number of waypoints that reproduces and proves the behavior, normally three to six.
-5. Locators name what a person sees: prefer `role` with `name`, then `label`, `text`, `testid`. Copy visible text from the source's default-language strings exactly, not from memory. Use `css` only when nothing semantic exists.
-6. Wait for the state before each capture: end every waypoint's steps with a `wait` on something the screenshot is meant to show.
-7. Only the steps above replay. Network inspection, console reads, and API calls do not; prove those in tests, not here.
-
-### When the change is not UI-reachable
-
-Write the stub and stop:
-
-````markdown
-# Verification plan: <change-id>
-
-```yaml
-status: not-applicable
-reason: Backend-only change; no frontend code references the changed contract (<names>).
-```
-````
-
-Adapt the reason to the actual change. Do not invent a journey when Step 2 concluded `None`.
-
-### Rules for writing
-
-- This skill MUST NOT launch a browser, start the app, take screenshots, or run build/test/lint. Those belong elsewhere.
-- Never commit, stage, or push. The caller owns git.
-- The plan file is the only artifact written. Do not modify the change's specs, tasks, or proposal.
-- When the project environment above says `none recorded yet` and you found the real sign-in or start command in the source, say so in the result so a person can record it there.
-
-## Step 4: Result
-
-Report one of:
-
-- `PLAN_WRITTEN <change-id>`: a journey with waypoints was written to `verification-plan.md`.
-- `STUB_WRITTEN <change-id>`: `status: not-applicable` stub written with a reason.
-- `NOT WRITTEN`: hard blocker (unreadable change, missing change directory). Report the blocker and the exact next step.
-
-A correct plan file written to the change directory is the success condition. Write a stub for non-UI changes; never skip writing the file.
+---
+name: pc-repo-verify
+description: Write the verification plan for the completed change, a journey through the new functionality as a fenced YAML block that the evidence workflow replays in headless Chromium after the pull request merges. Does not run checks, launch a browser, or take screenshots. Invoked by /repo-verify and the plan-goal pipeline.
+license: MIT
+---
+
+# Repo Verify
+
+Write the verification plan for the current branch's change. The checks gate lives in `pc-plan-apply` step 10 (lint, typecheck, test, build). This skill produces the reproduction plan instead: a journey through the new functionality with one screenshot per waypoint.
+
+The plan is executed by a machine, not read by one. When the pull request merges, the evidence workflow (`evidence.yml` from `@plainconceptsplatform/workflows`) checks out the pull request head, starts the app, replays every step below in headless Chromium with no model in the loop, and archives one screenshot per waypoint in an `evidence/` folder beside this plan on the default branch, shown in one comment on the pull request. A step it cannot follow is a screenshot of the wrong screen. Write every step so it can be followed literally from a freshly started app.
+
+This skill never launches a browser, never takes a screenshot, never starts a server. It only reads the change and writes a plan file.
+
+Work only on the current branch: do not switch branches, push, create pull requests, or contact external platforms. Write the plan into the change directory; it is carried into the archive by `pc-plan-archive`. Never create or edit an `evidence/` folder: the workflow writes it beside the archived plan after the merge.
+
+## Project environment
+
+How this project's app starts, where it answers, how a person signs in locally, and what data a fresh start already has. Read it before writing a journey; it is the project's, and an update keeps it.
+
+<!-- PC-PROJECT-ENVIRONMENT-START -->
+- Start: `pnpm run dev` at the repository root brings up the whole stack with mock authentication.
+- URL: `http://localhost:3000`.
+- Sign-in: none recorded yet. Find the local sign-in (a mock account picker, a dev login button) in the source and write its steps into the first waypoint.
+- Seeded data: none recorded yet. Create what the journey needs through the UI.
+<!-- PC-PROJECT-ENVIRONMENT-END -->
+
+## Step 1: Read the change
+
+1. Resolve the change id from the caller (autonomous mode) or from the current branch's unarchived change under `openspec/changes/<change-id>/`. Read `proposal.md`, `tasks.md`, and `design.md` when present.
+2. Read `.opencode/source-roots.json` when it exists; use its non-empty `roots` array to scope frontend source, otherwise use the repository root.
+3. Inspect `git diff` against the branch base and the working tree for context on what changed.
+
+## Step 2: Determine UI impact
+
+Decide whether the change is reachable from something a user sees or does in the browser.
+
+1. **Direct**: changed files include user-visible UI: `*.tsx`/`jsx`/`vue`/`svelte`, `*.css`/`scss`/`less`, pages, layouts, components, navigation, routes. The affected surfaces are the routes/components the diff touches.
+2. **Indirect (backend-only diff, frontend-affected)**: the diff touches only API/backend code, but the changed contract is consumed by the frontend. Trace it: for every changed endpoint, route, handler, query, or exported function, search the frontend source roots for references to that name or path. If any reference exists, the frontend **is** affected. Map the surfaces (the routes/components that import or call the changed contract) and build the journey through them.
+3. **None**: no path reaches the frontend. Write the stub plan (Step 3, `status: not-applicable`) and stop. Do not fabricate a journey.
+
+Mixed or unknown counts as affected: be safe.
+
+## Step 3: Write the plan
+
+Write `verification-plan.md` into the change directory:
+
+```
+openspec/changes/<change-id>/verification-plan.md
+```
+
+Prose around the block is for people and is ignored by the replay. The replay reads the first fenced `yaml` block that holds a `journey`:
+
+````markdown
+# Verification plan: <change-id>
+
+One or two sentences on what the journey proves.
+
+```yaml
+url: http://localhost:3000
+journey:
+  - capture: home
+    expect: signed in, the item list is the home page
+    steps:
+      - open: /
+      - click: { role: button, name: Alice Admin }
+      - wait: { role: heading, name: Items }
+
+  - capture: detail-before
+    expect: the detail panel shows the item without a status badge
+    steps:
+      - click: { text: Seeded item }
+      - wait: { load: networkidle }
+
+  - capture: detail-active
+    expect: the status badge reads Active
+    steps:
+      - click: { role: button, name: Activate }
+      - wait: { text: Active }
+```
+````
+
+### Keys
+
+- `url`: where the app answers once started, from the project environment above. Relative `open:` paths resolve against it.
+- `start` (optional): the command that starts the app, only when it is not the project's default.
+- `viewport` (optional): `1280x800` unless the change is about another size.
+- `journey`: the waypoints, in order, in one browser tab. Each has a `capture` (kebab-case, unique), an `expect` (what is visible in the screenshot), and the `steps` that get there from the previous waypoint.
+
+### Steps
+
+Each step is a map with exactly one action:
+
+| Step | Does |
+|---|---|
+| `open: /path` | navigate (relative to `url`, or a full URL) |
+| `click: <locator>` | click; add `button: right` inside the locator for a context menu |
+| `dblclick: <locator>`, `hover: <locator>`, `check: <locator>`, `uncheck: <locator>` | as named |
+| `fill: { <locator>, value: text }` | replace the field's text |
+| `select: { <locator>, value: option }` | choose an option |
+| `press: Enter` or `press: { <locator>, key: Enter }` | press a key |
+| `wait: <locator>` | until the element is visible |
+| `wait: { text: Saved }` | until the text is visible |
+| `wait: { load: networkidle }` | until the page settles; never a failure on its own |
+| `wait: { url: /items/ }` | until the address contains it |
+| `wait: { ms: 500 }` | a fixed pause, only for an animation with nothing to wait on |
+
+A locator is one of `{ role: button, name: Save }`, `{ text: Save }`, `{ label: Name }`, `{ placeholder: Search }`, `{ testid: save }`, `{ alt: Logo }`, `{ title: Close }`, or `{ css: ".row" }`, optionally with `nth: 1` or `last: true`. The first match is used.
+
+### Rules
+
+1. The first waypoint starts with `open` and signs in, using the sign-in from the project environment. The replay starts from a freshly started app with nothing in the browser.
+2. Everything the journey needs that a fresh start does not have, create through the UI in the steps (a record to open, a setting to change). Never assume data from a developer's machine.
+3. Place waypoints as a pre/post pair around the changed behavior: the state immediately before and immediately after the core change is exercised.
+4. Use the minimum number of waypoints that reproduces and proves the behavior, normally three to six.
+5. Locators name what a person sees: prefer `role` with `name`, then `label`, `text`, `testid`. Copy visible text from the source's default-language strings exactly, not from memory. Use `css` only when nothing semantic exists.
+6. Wait for the state before each capture: end every waypoint's steps with a `wait` on something the screenshot is meant to show.
+7. Only the steps above replay. Network inspection, console reads, and API calls do not; prove those in tests, not here.
+
+### When the change is not UI-reachable
+
+Write the stub and stop:
+
+````markdown
+# Verification plan: <change-id>
+
+```yaml
+status: not-applicable
+reason: Backend-only change; no frontend code references the changed contract (<names>).
+```
+````
+
+Adapt the reason to the actual change. Do not invent a journey when Step 2 concluded `None`.
+
+### Rules for writing
+
+- This skill MUST NOT launch a browser, start the app, take screenshots, or run build/test/lint. Those belong elsewhere.
+- Never commit, stage, or push. The caller owns git.
+- The plan file is the only artifact written. Do not modify the change's specs, tasks, or proposal.
+- When the project environment above says `none recorded yet` and you found the real sign-in or start command in the source, say so in the result so a person can record it there.
+
+## Step 4: Result
+
+Report one of:
+
+- `PLAN_WRITTEN <change-id>`: a journey with waypoints was written to `verification-plan.md`.
+- `STUB_WRITTEN <change-id>`: `status: not-applicable` stub written with a reason.
+- `NOT WRITTEN`: hard blocker (unreadable change, missing change directory). Report the blocker and the exact next step.
+
+A correct plan file written to the change directory is the success condition. Write a stub for non-UI changes; never skip writing the file.