@plainconceptsplatform/agent-harness 2.5.2 → 2.6.0

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

@@ -1,36 +1,123 @@
 ---
 name: pc-repo-verify
-description: Verify and repair current-branch changes using applicable fullstack engineer abilities, project checks, and dependency rules. Invoked by /repo-verify and the plan-goal pipeline.
+description: Write a reproduction plan for the completed change as a journey of agent-browser waypoints stored with the change. Does not run checks, launch a browser, or take screenshots. Invoked by /repo-verify and the plan-goal pipeline.
 license: MIT
 ---
 
 # Repo Verify
 
-Verify the current branch before it is archived, shipped, or handed to an external automation gate. Work only on the current branch: do not switch branches, push, create pull requests or backlog items, or contact external platforms.
+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 observation waypoints, written so a later agent-browser executor skill can follow it verbatim.
 
-## Step 1: Load verification rules
+This skill never launches a browser, never takes a screenshot, never starts a server. It only reads the change and writes a plan file. It is the agent-executed counterpart to `pc-ops-evidence`, whose `capturePlan` stays the CI-side screenshot workflow.
 
-1. Read `.opencode/agents/fullstack-engineer.md`.
-2. Parse every `@skill-name` in its `## Abilities` section.
-3. Load every listed skill, guardrails first. A missing referenced skill is a verification failure; report it and do not claim `VERIFIED`.
+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`.
 
-## Step 2: Determine changed scope
+## Step 1: Read the change
 
-1. Read `.opencode/source-roots.json` when it exists. Use its non-empty `roots` array; otherwise use the repository root.
-2. Inspect `git diff` against the branch base and the working tree. Map every changed path to a configured root and discovered project.
-3. Discover every project in every configured source root. Read each project's manifest, scripts, test configuration, CI configuration, and applicable guardrail instructions.
-4. Build a check matrix. Include every discovered project's repository-defined immutable dependency install or restore command, build command, and test command, even when that project is untouched. Add changed-scope lint, typecheck, migration, generated-artifact, documentation, evidence, and required repository-wide checks from loaded guardrails.
+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 3: Verify and repair
+## Step 2: Determine UI impact
 
-Run every discovered project's repository-defined immutable dependency install or restore command, build command, and test command. Run the changed-scope lint, typecheck, migration, generated-artifact, documentation, and evidence checks. A project without one of those commands is the only allowed skip, and the report must name the missing command.
+Decide whether the change is reachable from something a user sees or does in the browser.
 
-When a dependency manifest changes, require its ecosystem lockfile to change when the package manager uses one. The dependency install or restore command must validate that lockfile without mutating it.
+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, treating the API change as an indirect UI change.
+3. **None** — no path reaches the frontend. Write the stub plan (Step 3, `status: not-applicable`) and stop. Do not fabricate a journey.
 
-When a check fails, repair only the current branch's relevant files and rerun the failed check. Continue until every applicable check passes or a hard blocker prevents progress. Never hide a failure by deleting tests, weakening checks, or reverting requested work.
+Mixed or unknown counts as affected: be safe.
 
-Once every check passes, run the project's lint fix command over the files you changed (`pnpm lint:fix`, `pnpm exec biome check --write <changed-files>`, or its equivalent). Formatting is not a review comment worth anybody's turn, and a branch that fails lint on arrival gets sent back for it. Where no fix command exists, run lint and correct what it reports.
+## Step 3: Write the plan
+
+Write `verification-plan.md` into the change directory:
+
+```
+openspec/changes/<change-id>/verification-plan.md
+```
+
+The plan is written in agent-browser idiom so a future executor skill can follow it verbatim. Format:
+
+```markdown
+# verification-plan.md — <change-id>
+
+environment:
+  start: pnpm run dev
+  url: http://localhost:3000
+  login: mock-sso
+  data: |
+    <seed/data preconditions, or "none">
+
+journey:
+  - id: 1
+    arrive:
+      - agent-browser open http://localhost:3000/
+      - agent-browser wait --load networkidle
+    waypoint: wp-1-home
+    capture: home
+    expect: homepage renders; nav is visible
+
+  - id: 2
+    arrive:
+      - agent-browser find text "Items" click
+    waypoint: wp-2-items-list
+    capture: items-list
+    expect: the items list shows the seeded rows
+
+  - id: 3
+    arrive:
+      - agent-browser find first ".item-row" click
+      - agent-browser wait --load networkidle
+    waypoint: wp-3-detail-before
+    capture: detail-before
+    expect: the item detail panel is open and shows the record
+
+  - id: 4
+    arrive:
+      - agent-browser find role button click --name "Status"
+    waypoint: wp-4-detail-active
+    capture: detail-active
+    expect: the status badge now reads "Active"
+```
+
+Replace the example routes, captions, locators, and expectations with the actual change. Locators must be agent-browser-native and stable: prefer `find role`, `find text`, `find label`, `find testid`; use CSS selectors only when no semantic locator exists. Use `wait --load networkidle` (or `wait <selector>` / `wait --text "<known>"`) so the executor reaches the state before observing.
+
+### Waypoint rules
+
+1. The first waypoint is always the baseline at `/`: `wp-1-home`, `capture: home`.
+2. Place waypoints as a pre/post pair around the changed behavior — the state immediately before and immediately after the core change is exercised.
+3. Every waypoint has a `waypoint:` id (`wp-<n>-<slug>`), a `capture:` id (kebab-case, unique), and an `expect:` line stating what must be observable there.
+4. Dynamic data uses `sampleId: first` or `sampleId: any` in the `data:` block; locators that target a record resolve through it.
+5. The number of waypoints is the minimum that reproduces and proves the behavior — not every screenshottable moment, just the meaningful observation points.
+
+### When the change is not UI-reachable
+
+Write the stub and stop:
+
+```markdown
+# verification-plan.md — <change-id>
+
+status: not-applicable
+reason: |
+  Change is backend-only and no frontend code references the changed contract
+  (<names>). No user-visible journey exists; the executor skill should skip.
+```
+
+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 verifications. The caller owns git.
+- The plan file is the only artifact written. Do not modify the change's specs, tasks, or proposal.
+- Keep locators stable and observable: prefer semantic locators over brittle CSS paths.
 
 ## Step 4: Result
 
-Report a check matrix with command, affected project, result, and skip reason where applicable. Report `VERIFIED` only when every applicable check passed, every dependency change has consistent lockfiles, and no required ability is missing. Otherwise report `NOT VERIFIED`, the blockers, and the exact next command.
+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.

package/harness/ARCHITECTURE.md

@@ -2,8 +2,7 @@
 >
 > This file has not been populated yet. It is intentionally empty.
 >
-> **If this is a greenfield project** (no codebase exists yet): skip this for now.
-> Come back and run `/make-architecture` once you have meaningful code, structure, or infrastructure in place.
+> **If this is a greenfield project** (no codebase exists yet): skip this for now. Come back and run `/make-architecture` once you have meaningful code, structure, or infrastructure in place.
 >
 > **If this is a brownfield project** (existing codebase): run this command now to generate the architecture documentation:
 >
@@ -11,6 +10,4 @@
 > /make-architecture
 > ```
 >
-> This command analyzes your folder structure, config files, routes, data models, integrations, and build setup,
-> then writes a complete ARCHITECTURE.md covering components, data flow, tech stack, deployment, and more.
-> It is safe to rerun any time the architecture changes significantly.
+> This command analyzes your folder structure, config files, routes, data models, integrations, and build setup, then writes a complete ARCHITECTURE.md covering components, data flow, tech stack, deployment, and more. It is safe to rerun any time the architecture changes significantly.

package/harness/DESIGN.md

@@ -2,8 +2,7 @@
 >
 > This file has not been populated yet. It is intentionally empty.
 >
-> **If this is a greenfield project** (no UI exists yet): skip this for now.
-> Come back and run `/make-design` once you have a design system, UI components, or styles in place.
+> **If this is a greenfield project** (no UI exists yet): skip this for now. Come back and run `/make-design` once you have a design system, UI components, or styles in place.
 >
 > **If this is a brownfield project** (existing UI/styles): run this command now to generate the design documentation:
 >
@@ -11,6 +10,4 @@
 > /make-design
 > ```
 >
-> This command analyzes your CSS, Tailwind config, component files, and design tokens,
-> then writes a complete DESIGN.md with structured YAML tokens and written design intent.
-> It is safe to rerun any time your design system changes.
+> This command analyzes your CSS, Tailwind config, component files, and design tokens, then writes a complete DESIGN.md with structured YAML tokens and written design intent. It is safe to rerun any time your design system changes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/agent-harness",
-  "version": "2.5.2",
+  "version": "2.6.0",
   "description": "Installs the Plain Concepts Platform Harness into any codebase, and keeps it up to date. Wires OpenCode, OpenSpec, codegraph, and agentmemory into a multi-agent workflow that runs on native parallel subagents.",
   "keywords": [
     "opencode",
@@ -52,6 +52,7 @@
     "@eslint/js": "^9.0.0",
     "eslint": "^9.0.0",
     "globals": "^15.0.0",
+    "markdownlint-cli2": "0.23.2",
     "vitest": "^4.1.5"
   },
   "vitest": {
@@ -60,6 +61,8 @@
   "scripts": {
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
+    "lint:md": "markdownlint-cli2 \"**/*.md\"",
+    "lint:md:fix": "markdownlint-cli2 --fix \"**/*.md\"",
     "test": "vitest run",
     "test:watch": "vitest",
     "release:dry": "pnpm publish --dry-run --no-git-checks --access public",