@plainconceptsplatform/agent-harness 2.5.2 → 2.7.0

package/harness/.agents/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`, `/ops-evidence` |
-   | Quality | `/repo-audit` (read-only), `/repo-verify` (the branch gate) |
-   | 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`, `/ops-evidence` |
+   | 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/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.7.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",