@plainconceptsplatform/agent-harness 2.5.2 → 2.6.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-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
+```

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.