@plainconceptsplatform/agent-harness 2.5.2 → 2.7.0

package/harness/.agents/skills/pc-ops-evidence/SKILL.md

@@ -1,133 +1,131 @@
----
-name: pc-ops-evidence
-description: Writes a capturePlan in evidence.json for the Visual Evidence CI workflow to execute on a runner with Docker and Chrome access. Load after a change is implemented. Invoked by /ops-evidence.
-license: MIT
----
-
-# Ops Evidence
-
-Write a capture plan so the Visual Evidence CI workflow can capture screenshots on a runner with full Docker and Chrome access.
-
-The agent runs inside the awf sandbox where Docker-in-Docker is unsupported and headless Chromium's sandbox is blocked by the container security policy. The agent cannot capture screenshots itself. Instead, it analyzes the diff and writes a `capturePlan` in `evidence.json`. A separate CI workflow executes the plan.
-
-## Convention
-
-Every platform project has `pnpm run dev` at root that starts the **full stack** (database + API + web). The app runs with mock auth in development mode (no real authentication needed). This is the only contract — no per-project evidence harness, fixture apps, or scenario registries.
-
-## Input
-
-The caller provides (all optional):
-- change id: locates `openspec/changes/{change-id}/` (or the archived `archive/*{change-id}/`).
-- issue / work-item ref and PR number: where to publish.
-- output mode (`default` / `push` / `pr`): whether the branch was pushed.
-- operation: `capture` (default), `publish`, or `both`.
-
-## Part 1: Capture (operation: capture / both)
-
-**Step 1: Decide whether evidence is required.** Inspect the change's diff:
-- Required when changed files include user-visible UI: `*.tsx/jsx/vue/svelte`, `*.css/scss/less`, pages, layouts, components, navigation.
-- Skipped when docs-only, internal refactor, dependency-only, test-only, backend-only.
-- Mixed or unknown: required (be safe).
-
-If skipped: write `evidence.json` with `status: "skipped"` and reason. Done.
-
-**Step 2: Discover routes from git diff.** Parse changed files to determine which routes to screenshot:
-- `pages/**/*.tsx` or `app/**/page.tsx` → extract the route path
-- `features/**/*.tsx` or `components/**/*.tsx` → screenshot the homepage and any routes that import the changed component
-- If no routes found → screenshot `/` only
-- Always include `/` (homepage) as a baseline
-
-**Step 3: Write `evidence.json` with `capturePlan`.** The agent never attempts to start the app stack or launch a browser — those always fail inside the awf sandbox. Instead, write a `capturePlan` immediately.
-
-### The `capturePlan` schema
-
-```
-capturePlan:
-  routes:           # Array of route objects to screenshot (at minimum [{ path: "/" }])
-    - path: string  # URL path, e.g. "/items/:id"
-      sampleId:     # string | "first" | "any" — how to resolve dynamic segments
-      caption:      # string — human-readable description of what this screenshot shows
-  viewports:        # Array of viewport objects
-    - width: number
-      height: number
-      label: string # "desktop" | "mobile" | custom
-  requireApi:       # boolean — true when the route needs the backend API running
-  requireLogin:     # boolean — true when the route needs authentication
-  loginMethod:      # string — "mock-sso" | "none" | custom method identifier
-  reason:           # string — why evidence was blocked and what the screenshots should show
-```
-
-### Rules for writing capturePlan
-
-1. `routes` MUST always include `{ path: "/", caption: "Homepage" }` as the first entry.
-2. Every additional route discovered from the diff goes after the homepage entry.
-3. `sampleId: "first"` means the CI workflow should use the first record returned by the API. `sampleId: "any"` means any valid ID.
-4. `requireApi` is `true` when any route needs the backend to return data. It is `false` only for purely static pages (login, not-found).
-5. `requireLogin` is `true` when any route needs authentication. For dev mode with mock auth, `loginMethod` is `"mock-sso"`.
-6. `reason` should explain both WHY capture was blocked and WHAT the screenshots should show once captured.
-
-### Example `evidence.json`
-
-Adapt the routes and captions to this repository. Edits between the
-`PC-PROJECT-EXAMPLE` markers are carried over when the harness updates;
-anything outside them is replaced by the shipped version.
-
-<!-- PC-PROJECT-EXAMPLE-START -->
-```json
-{
-  "version": 1,
-  "changeId": "status-badge-in-detail-panel",
-  "required": true,
-  "status": "blocked",
-  "assets": [],
-  "capturePlan": {
-    "routes": [
-      { "path": "/", "sampleId": "any", "caption": "Homepage" },
-      { "path": "/items/:id", "sampleId": "first", "caption": "Item detail with the new status badge" }
-    ],
-    "viewports": [
-      { "width": 1280, "height": 720, "label": "desktop" },
-      { "width": 375, "height": 667, "label": "mobile" }
-    ],
-    "requireApi": true,
-    "requireLogin": true,
-    "loginMethod": "mock-sso",
-    "reason": "Status badge added to the item detail panel; visual change on the detail page."
-  },
-  "reason": "Visual evidence cannot be captured inside the awf sandbox (Docker-in-Docker unsupported, headless Chromium sandbox blocked). A capturePlan has been written for the Visual Evidence CI workflow.",
-  "prMarkdown": "## Evidence\n\nVisual evidence for this change is **blocked** in this agent run. A `capturePlan` has been written to `evidence.json` — the Visual Evidence CI workflow will execute it on a runner with full Docker and Chrome access.\n\nAutomated verification that did run:\n- Lint: clean\n- Tests: all pass\n- Build: success"
-}
-```
-<!-- PC-PROJECT-EXAMPLE-END -->
-
-### When evidence is not required
-
-If evidence is skipped (no UI files changed), write without a `capturePlan`:
-
-```json
-{
-  "version": 1,
-  "changeId": "{change-id}",
-  "required": false,
-  "status": "skipped",
-  "assets": [],
-  "reason": "No user-visible UI files changed in this PR.",
-  "prMarkdown": "## Evidence\n\nSkipped: no user-visible UI changes."
-}
-```
-
-Capture never commits, stages, or pushes. The caller owns git.
-
-## Part 2: Publish (operation: publish / both)
-
-Preconditions:
-- An issue/PR number was provided. Else skip.
-- Image URLs resolve only if the branch was pushed (`pr`/`push` modes).
-- Backlog platform from `.opencode/harness.json`; `none` means skip.
-
-<!-- PC-PLATFORM-EVIDENCE-START -->
-<!-- PC-PLATFORM-EVIDENCE-END -->
-
-## Report
-
-One block: the `status` (passed/skipped/failed/blocked) and why; capturePlan written or why not. Never present a blocked capture as passed.
+---
+name: pc-ops-evidence
+description: Writes a capturePlan in evidence.json for the Visual Evidence CI workflow to execute on a runner with Docker and Chrome access. Load after a change is implemented. Invoked by /ops-evidence.
+license: MIT
+---
+
+# Ops Evidence
+
+Write a capture plan so the Visual Evidence CI workflow can capture screenshots on a runner with full Docker and Chrome access.
+
+The agent runs inside the awf sandbox where Docker-in-Docker is unsupported and headless Chromium's sandbox is blocked by the container security policy. The agent cannot capture screenshots itself. Instead, it analyzes the diff and writes a `capturePlan` in `evidence.json`. A separate CI workflow executes the plan.
+
+## Convention
+
+Every platform project has `pnpm run dev` at root that starts the **full stack** (database + API + web). The app runs with mock auth in development mode (no real authentication needed). This is the only contract — no per-project evidence harness, fixture apps, or scenario registries.
+
+## Input
+
+The caller provides (all optional):
+- change id: locates `openspec/changes/{change-id}/` (or the archived `archive/*{change-id}/`).
+- issue / work-item ref and PR number: where to publish.
+- output mode (`default` / `push` / `pr`): whether the branch was pushed.
+- operation: `capture` (default), `publish`, or `both`.
+
+## Part 1: Capture (operation: capture / both)
+
+**Step 1: Decide whether evidence is required.** Inspect the change's diff:
+- Required when changed files include user-visible UI: `*.tsx/jsx/vue/svelte`, `*.css/scss/less`, pages, layouts, components, navigation.
+- Skipped when docs-only, internal refactor, dependency-only, test-only, backend-only.
+- Mixed or unknown: required (be safe).
+
+If skipped: write `evidence.json` with `status: "skipped"` and reason. Done.
+
+**Step 2: Discover routes from git diff.** Parse changed files to determine which routes to screenshot:
+- `pages/**/*.tsx` or `app/**/page.tsx` → extract the route path
+- `features/**/*.tsx` or `components/**/*.tsx` → screenshot the homepage and any routes that import the changed component
+- If no routes found → screenshot `/` only
+- Always include `/` (homepage) as a baseline
+
+**Step 3: Write `evidence.json` with `capturePlan`.** The agent never attempts to start the app stack or launch a browser — those always fail inside the awf sandbox. Instead, write a `capturePlan` immediately.
+
+### The `capturePlan` schema
+
+```
+capturePlan:
+  routes:           # Array of route objects to screenshot (at minimum [{ path: "/" }])
+    - path: string  # URL path, e.g. "/items/:id"
+      sampleId:     # string | "first" | "any" — how to resolve dynamic segments
+      caption:      # string — human-readable description of what this screenshot shows
+  viewports:        # Array of viewport objects
+    - width: number
+      height: number
+      label: string # "desktop" | "mobile" | custom
+  requireApi:       # boolean — true when the route needs the backend API running
+  requireLogin:     # boolean — true when the route needs authentication
+  loginMethod:      # string — "mock-sso" | "none" | custom method identifier
+  reason:           # string — why evidence was blocked and what the screenshots should show
+```
+
+### Rules for writing capturePlan
+
+1. `routes` MUST always include `{ path: "/", caption: "Homepage" }` as the first entry.
+2. Every additional route discovered from the diff goes after the homepage entry.
+3. `sampleId: "first"` means the CI workflow should use the first record returned by the API. `sampleId: "any"` means any valid ID.
+4. `requireApi` is `true` when any route needs the backend to return data. It is `false` only for purely static pages (login, not-found).
+5. `requireLogin` is `true` when any route needs authentication. For dev mode with mock auth, `loginMethod` is `"mock-sso"`.
+6. `reason` should explain both WHY capture was blocked and WHAT the screenshots should show once captured.
+
+### Example `evidence.json`
+
+Adapt the routes and captions to this repository. Edits between the `PC-PROJECT-EXAMPLE` markers are carried over when the harness updates; anything outside them is replaced by the shipped version.
+
+<!-- PC-PROJECT-EXAMPLE-START -->
+```json
+{
+  "version": 1,
+  "changeId": "status-badge-in-detail-panel",
+  "required": true,
+  "status": "blocked",
+  "assets": [],
+  "capturePlan": {
+    "routes": [
+      { "path": "/", "sampleId": "any", "caption": "Homepage" },
+      { "path": "/items/:id", "sampleId": "first", "caption": "Item detail with the new status badge" }
+    ],
+    "viewports": [
+      { "width": 1280, "height": 720, "label": "desktop" },
+      { "width": 375, "height": 667, "label": "mobile" }
+    ],
+    "requireApi": true,
+    "requireLogin": true,
+    "loginMethod": "mock-sso",
+    "reason": "Status badge added to the item detail panel; visual change on the detail page."
+  },
+  "reason": "Visual evidence cannot be captured inside the awf sandbox (Docker-in-Docker unsupported, headless Chromium sandbox blocked). A capturePlan has been written for the Visual Evidence CI workflow.",
+  "prMarkdown": "## Evidence\n\nVisual evidence for this change is **blocked** in this agent run. A `capturePlan` has been written to `evidence.json` — the Visual Evidence CI workflow will execute it on a runner with full Docker and Chrome access.\n\nAutomated verification that did run:\n- Lint: clean\n- Tests: all pass\n- Build: success"
+}
+```
+<!-- PC-PROJECT-EXAMPLE-END -->
+
+### When evidence is not required
+
+If evidence is skipped (no UI files changed), write without a `capturePlan`:
+
+```json
+{
+  "version": 1,
+  "changeId": "{change-id}",
+  "required": false,
+  "status": "skipped",
+  "assets": [],
+  "reason": "No user-visible UI files changed in this PR.",
+  "prMarkdown": "## Evidence\n\nSkipped: no user-visible UI changes."
+}
+```
+
+Capture never commits, stages, or pushes. The caller owns git.
+
+## Part 2: Publish (operation: publish / both)
+
+Preconditions:
+- An issue/PR number was provided. Else skip.
+- Image URLs resolve only if the branch was pushed (`pr`/`push` modes).
+- Backlog platform from `.opencode/harness.json`; `none` means skip.
+
+<!-- PC-PLATFORM-EVIDENCE-START -->
+<!-- PC-PLATFORM-EVIDENCE-END -->
+
+## Report
+
+One block: the `status` (passed/skipped/failed/blocked) and why; capturePlan written or why not. Never present a blocked capture as passed.

package/harness/.agents/skills/pc-plan-apply/SKILL.md

@@ -25,15 +25,9 @@ The caller provides (all optional):
 
 ## OpenSpec mode: parallel subagent waves
 
-Load `@openspec-apply-change` for change selection, status, and closing. Its
-own implement step does not apply here: annotated tasks are implemented only by
-spawning the annotated tier worker, and the lead never implements. Take that
-step from the protocol below instead.
-
-Referring to it by number would break silently. `@openspec-apply-change` is
-installed by `openspec init --force` with no version pinned, so an inserted step
-upstream renumbers the one being replaced, and the sequential default would then
-run alongside these waves.
+Load `@openspec-apply-change` for change selection, status, and closing. Its own implement step does not apply here: annotated tasks are implemented only by spawning the annotated tier worker, and the lead never implements. Take that step from the protocol below instead.
+
+Referring to it by number would break silently. `@openspec-apply-change` is installed by `openspec init --force` with no version pinned, so an inserted step upstream renumbers the one being replaced, and the sequential default would then run alongside these waves.
 
 **Implement via native subagent waves.**
 

package/harness/.agents/skills/pc-plan-explore/SKILL.md

@@ -4,26 +4,18 @@ description: Explore an idea or requirement before planning. Invoked by the /pla
 license: MIT
 ---
 
-Explore, then hand back what you learned. `@openspec-explore` supplies the
-stance; this skill adds one prohibition and one handoff.
+Explore, then hand back what you learned. `@openspec-explore` supplies the stance; this skill adds one prohibition and one handoff.
 
 ## Rules
 
-- Never write, edit, or create a file while this skill is loaded, OpenSpec
-  artifacts included. This overrides `@openspec-explore`, which says creating
-  them is "fine". Reading, searching, and discussing are the whole job.
-- If the conversation turns toward implementation, say explore mode is active
-  and point at `/plan-apply`.
+- Never write, edit, or create a file while this skill is loaded, OpenSpec artifacts included. This overrides `@openspec-explore`, which says creating them is "fine". Reading, searching, and discussing are the whole job.
+- If the conversation turns toward implementation, say explore mode is active and point at `/plan-apply`.
 
 Load `@openspec-explore` for the approach.
 
 ## Autonomous handoff
 
-When a caller loads this skill in autonomous mode, return `EXPLORATION_BRIEF`
-in memory rather than writing a file. It holds: the problem in one or two
-sentences, the affected paths, the approach chosen, the risks worth knowing,
-and anything deliberately out of scope. `pc-plan-goal` requires it before its
-propose phase.
+When a caller loads this skill in autonomous mode, return `EXPLORATION_BRIEF` in memory rather than writing a file. It holds: the problem in one or two sentences, the affected paths, the approach chosen, the risks worth knowing, and anything deliberately out of scope. `pc-plan-goal` requires it before its propose phase.
 
 <!-- PC-OPTIMIZATION-MEMORY-START -->
 <!-- PC-OPTIMIZATION-MEMORY-END -->

package/harness/.agents/skills/pc-plan-goal/SKILL.md

@@ -64,7 +64,7 @@ Tick `propose` when the proposal commit exists.
 
 Load `pc-plan-apply` in autonomous mode with `start_from: load-plan`. It owns worker resolution, subagent waves, commits, verification, and re-waves.
 
-Require it to return every task complete and `VERIFIED`, then load `pc-repo-verify`. Tick `apply` and `verify` only when both phases return `VERIFIED`.
+Require it to return every task complete and `VERIFIED`, then load `pc-repo-verify`. Tick `apply` when apply returns `VERIFIED`; tick `verify` when `pc-repo-verify` returns `PLAN_WRITTEN` or `STUB_WRITTEN`.
 
 ## Phase 5: Archive
 

package/harness/.agents/skills/pc-plan-propose/SKILL.md

@@ -21,8 +21,7 @@ The caller provides:
 
 ## Step 0.a: Check for unarchived changes (stop)
 
-Before proposing a new change, inspect `openspec/changes/` (ignore `openspec/changes/archive`).
-If any change folder exists in `openspec/changes/` (names vary by platform: `gh-*`, `us-*`, or a plain slug), list them in the question text, then call the `question` tool:
+Before proposing a new change, inspect `openspec/changes/` (ignore `openspec/changes/archive`). If any change folder exists in `openspec/changes/` (names vary by platform: `gh-*`, `us-*`, or a plain slug), list them in the question text, then call the `question` tool:
 
 ```json
 {
@@ -57,6 +56,7 @@ Load `@openspec-propose` skill and follow its instructions to generate proposal.
 1. List every `*-engineer.md` file in `.opencode/agents/`. For each file read:
    - `description:` from the YAML frontmatter: the engineer's specialization summary
    - `## Abilities` section: the skills listed under Development, Testing, Infrastructure (e.g. `@nodejs-backend`, `@secure-nextjs-api-routes`)
+
    Build a map of `agent-name -> { description, abilities }`.
 2. For each task, compare the task text and domain against every engineer's description AND abilities. Pick the engineer whose combined profile most closely matches. `fullstack-engineer` is the fallback worker and the body behind `build` and `plan`; prefer a real specialist over it, and never annotate a task with `build` or `plan`, which are the user's own primaries. If no specialist matches a task, leave the agent field blank and record the missing specialization in the proposal. An annotated OpenSpec task needs a real subagent; never substitute the lead or an obsolete generic agent name.
 3. Pick a tier, derive `depends_on`, derive `touches`, and annotate each task line. Follow the [task annotation](task-annotation.md) reference for the full tier selection guide, dependency derivation, touches derivation, and annotation format with examples.

package/harness/.agents/skills/pc-plan-story/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pc-plan-story
-description: Write a detailed, repo-aware user story from a feature idea or need. Loads the @user-story skill for Mike Cohn format + Gherkin acceptance criteria, analyzes the codebase for concrete context, and produces a development-ready story. Use when the user wants to write a user story, create a story from a feature idea, or turn a need into a structured story with acceptance criteria. Invoked by the /plan-story command.
+description: Write a detailed, repo-aware user story from a feature idea or need, then wrap it in the repository's issue form and append a structured implementation plan. Loads the @user-story skill for Mike Cohn format + Gherkin acceptance criteria, analyzes the codebase for concrete context, and produces a development-ready story with a plan. Use when the user wants to write a user story, create a story from a feature idea, or turn a need into a structured story with acceptance criteria. Invoked by the /plan-story command.
 license: MIT
 ---
 
@@ -10,24 +10,69 @@ Write a user story grounded in this repository. `@user-story` owns the format an
 
 A feature description, need, or rough idea, possibly with exploration findings and diagrams to align the scope with. If `$ARGUMENTS` is empty, ask what the user wants to capture.
 
+The caller may pass exploration findings from a prior `/plan-explore` session. Treat them as the primary source for the codebase inventory; read files only to fill gaps the findings do not cover.
+
 <!-- PC-OPTIMIZATION-MEMORY-START -->
 <!-- PC-OPTIMIZATION-MEMORY-END -->
 
 ## Rules
 
-- Never write, edit, or create a file, and never start the work or invoke `/plan-propose` or `/plan-quick`. The only artefacts are the story and one question.
+- Never write, edit, or create a file, and never start the work or invoke `/plan-propose` or `/plan-quick`. The only artefacts are the story (with its issue form and plan), and one question.
 - Never write `As a user`. The persona comes from the repo's own roles: auth middleware, route guards, user models. A story that could have been written without opening the repo is not worth reviewing.
 - Never show the user a story that fails the `@user-story` checks. Fix it first.
 - Every `Given`, `When` and `Then` names something real, and every `Then` is testable: a file, endpoint, model or field somebody can point at.
+- Never read outside this repository root. The entire inventory and plan must come from files inside this repo.
+- Adhere to `${{ env.REPO_RULES }}` and repository documentation (AGENTS.md, ARCHITECTURE.md, DESIGN.md, existing patterns) before finalizing the story.
+- Reserve the very top of the body — above the form's first heading — for machine-readable lines that later workflow steps add (split markers, estimate lines). Never place story or plan content there; the workflow reads those lines regardless of the form's shape.
 
 ## Flow
 
 1. Load `@user-story`.
-2. Read the codebase for what the feature touches: who the users are (auth, roles, user models, guards), what exists now (components, endpoints, models, types), where the change lands (paths, module boundaries), and what rules already govern it (validation, existing flows). Incorporate any exploration findings, including their out-of-scope decisions.
-3. Draft the story against that inventory, with two or three edge cases taken from what the code does today: a violated constraint, an empty or half-migrated state, a permission boundary.
-4. Load `@humanizer` and run it over the prose. It cleans prose, not structure: paths, component names and Gherkin stay exact.
-5. Add a Mermaid diagram only for a multi-step flow, a state transition, or a component interaction, and only the happy path. A single-resource CRUD story does not need one. If the input carried an exploration diagram, extend it rather than redrawing.
-6. Show the story with the artefacts it is grounded in, then ask what is next.
+
+2. **Coverage gate.** List every work unit from the input. For each, confirm it has exploration findings concrete enough to write an acceptance scenario: the files it touches, the models or endpoints it changes, the constraints it must respect. If any work unit is missing findings, go back and explore it now by reading the codebase. Do not draft the story until every work unit is covered. This skill's own requirement is coverage: several work units become one story that covers all of them, with at least one acceptance scenario per unit.
+
+3. Read the codebase for what the feature touches: who the users are (auth, roles, user models, guards), what exists now (components, endpoints, models, types), where the change lands (paths, module boundaries), and what rules already govern it (validation, existing flows). Incorporate any exploration findings, including their out-of-scope decisions.
+
+4. Draft the story against that inventory. Each work unit gets at least one acceptance scenario. Pull two or three edge cases from what the code does today: a violated constraint, an empty or half-migrated state, a permission boundary.
+
+5. Apply repository documentation and established conventions. Read AGENTS.md, ARCHITECTURE.md, DESIGN.md and any existing patterns that govern the area being changed. Adjust the story to respect them.
+
+6. Load `@humanizer` and run it over the prose. It cleans prose, not structure: paths, component names and Gherkin stay exact.
+
+7. Add a Mermaid diagram only for a multi-step flow, a state transition, or a component interaction, and only the happy path. A single-resource CRUD story does not need one. If the input carried an exploration diagram, extend it rather than redrawing.
+
+8. **Issue form: discover, select, fill.**
+
+   *Discover:* List the YAML and Markdown forms under `.github/ISSUE_TEMPLATE/`, plus a legacy `.github/issue_template.md` or a root `template.yml`. `config.yml` there only declares contact links, which are not forms: ignore it.
+
+   *Select:* When a form filters by labels and the issue carries one of those labels, that form wins. Otherwise use the repository's default form. When the repository has no form at all, keep the free-form story shape from step 4: there is nothing to wrap around.
+
+   *Fill:* Draw every field's content from your exploration findings. Required fields always get real content; optional fields only when you genuinely have something for them. The story narrative lands in the field that asks for it — proposal, description, or what-happened, depending on the form. The Given/When/Then scenarios go into the form's acceptance-criteria field when it has one; otherwise they stay a section of their own. The Mermaid diagram goes where it reads best inside the filled form.
+
+9. **Plan section.** Using the codebase investigation from step 3, produce a structured implementation plan that goes after the story inside the issue form body. Format it as follows:
+
+   Start with a one-line scope summary, then a context paragraph describing what areas the plan touches, how many changes it breaks into, and whether the changes are independent.
+
+   Then break the feature into numbered changes. Each change:
+
+   - **Title** — what the change does.
+   - **Problem** — what is wrong or what needs to change and why. Name the file, method, or endpoint.
+   - **Fix** — bullet steps describing the implementation approach. Each step names a concrete file, method, or field.
+   - **Affected files** — a bullet list of paths with a short note on what changes in each.
+
+   After all changes, add a summary table:
+
+   ```markdown
+   | Change | Files | Layer |
+   |---|---|---|
+   | 1. <title> | <file list> | <Backend | Frontend | Fullstack | Infra | Tests> |
+   ```
+
+   Then list exclusions — what is explicitly out of scope and why.
+
+   Do not write any files. The plan is part of the story output, read-only. It tells the implementer what to touch and why, so they can start without re-investigating.
+
+10. Show the story with the issue form wrapping, the plan, and the artefacts it is grounded in, then ask what is next. If the plan has an open clarification — a wording choice, a missing constraint, an unknown API — ask it before the contracts question.
 
 ## Contracts
 

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

@@ -1,89 +1,89 @@
----
-name: pc-repo-help
-description: The full command reference for this project - every /command with when to use it and the typical workflows. Load when the user asks for help, the command list, or at the end of repo initialization. Invoked by the /repo-help command and the repo-initialize flow.
-license: MIT
----
-
-# Repo Help
-
-Display the following reference to the user exactly as written. Do not summarize.
-
-## Commands
-
-### Not sure where to start?
-
-**`/init`** (alias: `/repo-initialize`): Initialize the project. Presents a single form with all setup questions (project type, history, architecture, design, evidence), then executes the selected steps.
-
-**`/repo-onboard`**: Guided tour of the project and its agentic infrastructure. Explains agents, commands, skills, OpenSpec workflow, and configuration. Read-only: no files modified.
-
-**`/repo-audit`**: Read-only health audit of every configured source root. Loads the fullstack engineer's abilities, checks guardrails, architecture, tooling, dependencies, lockfiles, tests, and CI, then reports prioritized findings.
-
-**`/plan-explore`**: Your backlog is unclear, you have a half-formed idea, or you need to think through a problem before committing to a plan. This is a thinking partner, not an executor.
-
-**`/plan-story <feature or need>`**: Write a detailed, repo-aware user story from a feature idea. Loads the `@user-story` skill (Mike Cohn format + Gherkin acceptance criteria), analyzes your codebase for concrete context, and produces a development-ready story with specific personas, real outcomes, and testable criteria grounded in your actual file paths, component names, and data models. No files written — just the story.
-
-**`/plan-propose <url or idea>`**: You have a work item URL, or a clear idea and you want to turn it into a structured plan (proposal, specs, tasks). Enriches each task with the best matching agent and model before showing you the plan. Nothing is implemented until you confirm.
-
----
-
-### Ready to implement?
-
-**`/plan-quick <task>`**: Quick plan for focused changes. Reads the codebase, creates a task checklist in the Todo pane. No files, no OpenSpec. Then you decide: `/plan-apply` to implement, or `/plan-propose` for a full OpenSpec plan.
-
-**`/plan-apply`**: Implement a plan. Detects the source automatically: OpenSpec-annotated tasks (from `/plan-propose`) run as parallel subagent waves; Todo pane tasks (from `/plan-quick`) run sequentially in-session.
-
-**`/plan-goal <feature or URL>`**: Fully autonomous, no confirmations. Branches off `main`, then runs propose → apply → archive on that branch (each phase its own commit). Default: merges to `main` and deletes the branch. Add `push` keyword to push the branch only. Add `pr` keyword to push + create a PR. Built for loop-engineering / unattended runs. Stops only on a hard failure, leaving the branch unmerged.
-
----
-
-### Done implementing?
-
-**`/ops-ship`**: Create a PR for the current feature branch with screenshots if UI changed.
-
-**`/ops-review`**: Read and triage PR review feedback. If you share a PR URL or say "I've added comments to the PR", it reads and classifies the review comments so you know what to fix. Fixing is done via `/plan-apply`.
-
-**`/ops-backlog`**: Create an issue in the backlog platform (GitHub, Azure DevOps, Jira) from a description.
-
-**`/ops-evidence`**: Produce evidence a completed change works and publish it to the originating issue/PR. Uses `playwright-cli` (headless) and `pnpm run dev` to capture screenshots at desktop and mobile viewports, writes `evidence/evidence.json` (passed/skipped/failed/blocked), and upserts an idempotent verified comment. Best-effort. Run it yourself after a change lands; `/plan-goal` does not run it. Works inside CI containers.
-
-**`/plan-archive`**: Mark a completed change as archived in OpenSpec. Run this after the PR is merged.
-
----
-
-### Maintaining the project?
-
-**`/make-engineer`**: Add a custom specialist engineer to the team. Interactive persona-driven form: pick a persona, then confirm an inspected-and-recommended set of skills (architecture/patterns like FSD or design patterns, framework, testing, infra) before anything installs. Future `/plan-apply` runs will prefer it when its domain matches.
-
-**`/make-architecture`**: Regenerate `ARCHITECTURE.md` from the current codebase. Safe to rerun any time the architecture evolves.
-
-**`/make-design`**: Regenerate `DESIGN.md` from the design system (Tailwind, CSS vars, tokens, etc.).
-
-**`/make-guardrails`**: Generate a `pc-guardrails-project` skill from `ARCHITECTURE.md` and project config files. Extracts concrete rules (architecture boundaries, naming, code style, testing, git workflow) that all agents must follow. Updates every `*-engineer.md` to load the skill.
-
-**`/repo-verify`**: Verify the current branch against applicable guardrails and project checks. Runs immutable dependency installs/restores, configured builds, and tests for every discovered project, repairs relevant failures, checks dependency/lockfile consistency, and reports `VERIFIED` only when every required check passes. It runs automatically in `/plan-goal`.
-
-**`/make-user-model <tier> <model>`**: Set the model for a tier (`plan`, `build`, or `fast`). Writes to `.opencode/harness.json` (`models`). Use `user` prefix for a personal override: `/make-user-model user fast opencode/big-pickle`. Use a model id or `current` for the active session model. Restart opencode for the `pc-subagent-tiers` plugin to rebuild tier agents.
-
----
-
-### Typical workflows
-
-**Complex change:**
-```
-/plan-explore   ← optional: think it through first
-/plan-propose   ← create the plan
-/plan-apply     ← implement with the team
-/ops-ship        ← ship
-/plan-archive   ← close out
-```
-
-**Quick change:**
-```
-/plan-quick     ← create a focused task list
-/plan-apply     ← implement
-```
-
-**Unattended / loop-engineering:**
-```
-/plan-goal <description>  ← full pipeline, no interaction
-```
+---
+name: pc-repo-help
+description: The full command reference for this project - every /command with when to use it and the typical workflows. Load when the user asks for help, the command list, or at the end of repo initialization. Invoked by the /repo-help command and the repo-initialize flow.
+license: MIT
+---
+
+# Repo Help
+
+Display the following reference to the user exactly as written. Do not summarize.
+
+## Commands
+
+### Not sure where to start?
+
+**`/init`** (alias: `/repo-initialize`): Initialize the project. Presents a single form with all setup questions (project type, history, architecture, design, evidence), then executes the selected steps.
+
+**`/repo-onboard`**: Guided tour of the project and its agentic infrastructure. Explains agents, commands, skills, OpenSpec workflow, and configuration. Read-only: no files modified.
+
+**`/repo-audit`**: Read-only health audit of every configured source root. Loads the fullstack engineer's abilities, checks guardrails, architecture, tooling, dependencies, lockfiles, tests, and CI, then reports prioritized findings.
+
+**`/plan-explore`**: Your backlog is unclear, you have a half-formed idea, or you need to think through a problem before committing to a plan. This is a thinking partner, not an executor.
+
+**`/plan-story <feature or need>`**: Write a detailed, repo-aware user story from a feature idea. Loads the `@user-story` skill (Mike Cohn format + Gherkin acceptance criteria), analyzes your codebase for concrete context, and produces a development-ready story with specific personas, real outcomes, and testable criteria grounded in your actual file paths, component names, and data models. No files written — just the story.
+
+**`/plan-propose <url or idea>`**: You have a work item URL, or a clear idea and you want to turn it into a structured plan (proposal, specs, tasks). Enriches each task with the best matching agent and model before showing you the plan. Nothing is implemented until you confirm.
+
+---
+
+### Ready to implement?
+
+**`/plan-quick <task>`**: Quick plan for focused changes. Reads the codebase, creates a task checklist in the Todo pane. No files, no OpenSpec. Then you decide: `/plan-apply` to implement, or `/plan-propose` for a full OpenSpec plan.
+
+**`/plan-apply`**: Implement a plan. Detects the source automatically: OpenSpec-annotated tasks (from `/plan-propose`) run as parallel subagent waves; Todo pane tasks (from `/plan-quick`) run sequentially in-session.
+
+**`/plan-goal <feature or URL>`**: Fully autonomous, no confirmations. Branches off `main`, then runs propose → apply → archive on that branch (each phase its own commit). Default: merges to `main` and deletes the branch. Add `push` keyword to push the branch only. Add `pr` keyword to push + create a PR. Built for loop-engineering / unattended runs. Stops only on a hard failure, leaving the branch unmerged.
+
+---
+
+### Done implementing?
+
+**`/ops-ship`**: Create a PR for the current feature branch with screenshots if UI changed.
+
+**`/ops-review`**: Read and triage PR review feedback. If you share a PR URL or say "I've added comments to the PR", it reads and classifies the review comments so you know what to fix. Fixing is done via `/plan-apply`.
+
+**`/ops-backlog`**: Create an issue in the backlog platform (GitHub, Azure DevOps, Jira) from a description.
+
+**`/ops-evidence`**: Produce evidence a completed change works and publish it to the originating issue/PR. Uses `playwright-cli` (headless) and `pnpm run dev` to capture screenshots at desktop and mobile viewports, writes `evidence/evidence.json` (passed/skipped/failed/blocked), and upserts an idempotent verified comment. Best-effort. Run it yourself after a change lands; `/plan-goal` does not run it. Works inside CI containers.
+
+**`/plan-archive`**: Mark a completed change as archived in OpenSpec. Run this after the PR is merged.
+
+---
+
+### Maintaining the project?
+
+**`/make-engineer`**: Add a custom specialist engineer to the team. Interactive persona-driven form: pick a persona, then confirm an inspected-and-recommended set of skills (architecture/patterns like FSD or design patterns, framework, testing, infra) before anything installs. Future `/plan-apply` runs will prefer it when its domain matches.
+
+**`/make-architecture`**: Regenerate `ARCHITECTURE.md` from the current codebase. Safe to rerun any time the architecture evolves.
+
+**`/make-design`**: Regenerate `DESIGN.md` from the design system (Tailwind, CSS vars, tokens, etc.).
+
+**`/make-guardrails`**: Generate a `pc-guardrails-project` skill from `ARCHITECTURE.md` and project config files. Extracts concrete rules (architecture boundaries, naming, code style, testing, git workflow) that all agents must follow. Updates every `*-engineer.md` to load the skill.
+
+**`/repo-verify`**: Write a reproduction plan for the current branch's change as a journey of agent-browser waypoints stored with the change in `verification-plan.md`. Traces backend-only changes through to the frontend when the changed contract is consumed there; writes a `not-applicable` stub when no UI surface is reachable. Does not run checks, launch a browser, or take screenshots — the checks gate lives in `pc-plan-apply` step 10, and the plan is executed later by a separate agent-browser skill. It runs automatically in `/plan-goal`.
+
+**`/make-user-model <tier> <model>`**: Set the model for a tier (`plan`, `build`, or `fast`). Writes to `.opencode/harness.json` (`models`). Use `user` prefix for a personal override: `/make-user-model user fast opencode/big-pickle`. Use a model id or `current` for the active session model. Restart opencode for the `pc-subagent-tiers` plugin to rebuild tier agents.
+
+---
+
+### Typical workflows
+
+**Complex change:**
+```
+/plan-explore   ← optional: think it through first
+/plan-propose   ← create the plan
+/plan-apply     ← implement with the team
+/ops-ship        ← ship
+/plan-archive   ← close out
+```
+
+**Quick change:**
+```
+/plan-quick     ← create a focused task list
+/plan-apply     ← implement
+```
+
+**Unattended / loop-engineering:**
+```
+/plan-goal <description>  ← full pipeline, no interaction
+```