@plainconceptsplatform/agent-harness 3.0.3 → 3.1.0

package/cli/steps/optimization/index.js

@@ -4,7 +4,6 @@ import fse from 'fs-extra'
 import path from 'path'
 import { fileURLToPath } from 'url'
 import { code, commandExists, header, info, loading, success, warn } from '../../utils/exec.js'
-import { installQuota } from './quota.js'
 import { installSimpleEnglish } from './simple-english.js'
 import { installCodegraph } from './codegraph.js'
 import { installMemory } from './memory.js'
@@ -92,10 +91,6 @@ export async function tokenOptimizationStep(options = {}) {
     ? await checkRtk({ skipHeader: true, skipPrompt: true })
     : { optedIn: false, checked: false, available: false }
 
-  const quota = has('quota')
-    ? await installQuota({ skipHeader: true, skipPrompt: true })
-    : { optedIn: false, installed: false }
-
   const simpleEnglish = has('simpleEnglish')
     ? await installSimpleEnglish({
       skipHeader: true,
@@ -132,7 +127,7 @@ export async function tokenOptimizationStep(options = {}) {
   if (selected.length === 0) warn('No token optimization tools selected')
   else success('Token optimization step completed')
 
-  return { rtk, quota, simpleEnglish, codegraph, memory, humanizer }
+  return { rtk, simpleEnglish, codegraph, memory, humanizer }
 }
 
 async function syncSkillsLock() {

package/cli/utils/paths.js

@@ -1,67 +1,80 @@
-import os from 'node:os'
-import path from 'node:path'
-
-/**
- * Every harness path that lands in a consumer repo, in one place.
- *
- * These filenames are a contract with every repo the harness has been
- * installed into: the CLI writes them, and the opencode plugins shipped in
- * harness/.opencode/plugins/ read them back at runtime. Changing a name
- * here means changing it in that payload too, or the plugins go blind.
- *
- * They are deliberately named for the harness rather than for the CLI, so a
- * future rename of the package does not become a rename of the on-disk state.
- */
-export const OPENCODE_DIR = '.opencode'
-
-/** Project config written by the metadata step. */
-export const CONFIG_FILE = 'harness.json'
-
-/** Per-developer model override, gitignored, never committed. */
-export const USER_CONFIG_FILE = 'harness.user.json'
-
-/** Hashes of every managed file, so `update` can detect local edits. */
-export const MANIFEST_FILE = 'harness-managed.json'
-
-/** Live subagent wave state, owned by the pc-subagent-monitor plugin. */
-export const RUN_STATE_FILE = 'harness-run.json'
-
-/** Names `.opencode/.gitignore` must cover. Mirrored in content/.opencode/_gitignore. */
-export const IGNORED_ENTRIES = [
-  'node_modules',
-  RUN_STATE_FILE,
-  USER_CONFIG_FILE,
-  MANIFEST_FILE,
-  'source-roots.json',
-  '*-engineer.*.md',
-  // Regenerated from fullstack-engineer.md by pc-subagent-tiers every startup.
-  'agents/build.md',
-  'agents/plan.md',
-]
-
-export function configPath(cwd = process.cwd()) {
-  return path.join(cwd, OPENCODE_DIR, CONFIG_FILE)
-}
-
-export function userConfigPath(cwd = process.cwd()) {
-  return path.join(cwd, OPENCODE_DIR, USER_CONFIG_FILE)
-}
-
-export function manifestPath(cwd = process.cwd()) {
-  return path.join(cwd, OPENCODE_DIR, MANIFEST_FILE)
-}
-
-/** Cross-run models cache, keyed to the CLI rather than to any one repo. */
-export function modelsCacheDir() {
-  return path.join(os.homedir(), '.config', 'agent-harness')
-}
-
-/**
- * Filenames written by opencode-onboard v1.x. Only used to detect a v1 repo
- * and refuse to half-patch it: nothing reads their contents.
- */
-export const LEGACY_CONFIG_FILES = [
-  'opencode-onboard.json',
-  'opencode-onboard.user.json',
-  'opencode-onboard-managed.json',
-]
+import os from 'node:os'
+import path from 'node:path'
+
+/**
+ * Every harness path that lands in a consumer repo, in one place.
+ *
+ * These filenames are a contract with every repo the harness has been
+ * installed into: the CLI writes them, and the opencode plugins shipped in
+ * harness/.opencode/plugins/ read them back at runtime. Changing a name
+ * here means changing it in that payload too, or the plugins go blind.
+ *
+ * They are deliberately named for the harness rather than for the CLI, so a
+ * future rename of the package does not become a rename of the on-disk state.
+ */
+export const OPENCODE_DIR = '.opencode'
+
+/** Project config written by the metadata step. */
+export const CONFIG_FILE = 'harness.json'
+
+/** Per-developer model override, gitignored, never committed. */
+export const USER_CONFIG_FILE = 'harness.user.json'
+
+/** Hashes of every managed file, so `update` can detect local edits. */
+export const MANIFEST_FILE = 'harness-managed.json'
+
+/** Live subagent wave state, owned by the pc-subagent-monitor plugin. */
+export const RUN_STATE_FILE = 'harness-run.json'
+
+/** Names `.opencode/.gitignore` must cover. Mirrored in content/.opencode/_gitignore. */
+export const IGNORED_ENTRIES = [
+  'node_modules',
+  RUN_STATE_FILE,
+  USER_CONFIG_FILE,
+  MANIFEST_FILE,
+  'source-roots.json',
+  '*-engineer.*.md',
+  // Regenerated from fullstack-engineer.md by pc-subagent-tiers every startup.
+  'agents/build.md',
+  'agents/plan.md',
+]
+
+/**
+ * Files the harness shipped and has since retired. `update` deletes them, because a skill or
+ * command left behind keeps being offered to agents long after the procedure it describes is
+ * gone. pc-ops-evidence wrote a capturePlan for a CI workflow that no longer exists; the
+ * verification plan from pc-repo-verify is what the evidence workflow replays now.
+ */
+export const RETIRED_PATHS = [
+  '.agents/skills/pc-ops-evidence',
+  '.agents/skills/pc-make-evidence-scaffold',
+  '.opencode/commands/ops-evidence.md',
+  '.opencode/commands/make-evidence-scaffold.md',
+]
+
+export function configPath(cwd = process.cwd()) {
+  return path.join(cwd, OPENCODE_DIR, CONFIG_FILE)
+}
+
+export function userConfigPath(cwd = process.cwd()) {
+  return path.join(cwd, OPENCODE_DIR, USER_CONFIG_FILE)
+}
+
+export function manifestPath(cwd = process.cwd()) {
+  return path.join(cwd, OPENCODE_DIR, MANIFEST_FILE)
+}
+
+/** Cross-run models cache, keyed to the CLI rather than to any one repo. */
+export function modelsCacheDir() {
+  return path.join(os.homedir(), '.config', 'agent-harness')
+}
+
+/**
+ * Filenames written by opencode-onboard v1.x. Only used to detect a v1 repo
+ * and refuse to half-patch it: nothing reads their contents.
+ */
+export const LEGACY_CONFIG_FILES = [
+  'opencode-onboard.json',
+  'opencode-onboard.user.json',
+  'opencode-onboard-managed.json',
+]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/agent-harness",
-  "version": "3.0.3",
+  "version": "3.1.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",
@@ -42,6 +42,7 @@
   "engines": {
     "node": ">=18"
   },
+  "packageManager": "pnpm@11.10.0",
   "dependencies": {
     "@inquirer/prompts": "^7.0.0",
     "chalk": "^5.0.0",
@@ -50,16 +51,6 @@
     "jsonc-parser": "^3.3.1",
     "ora": "^8.0.0"
   },
-  "devDependencies": {
-    "@eslint/js": "^9.0.0",
-    "eslint": "^9.0.0",
-    "globals": "^15.0.0",
-    "markdownlint-cli2": "0.23.2",
-    "vitest": "^4.1.5"
-  },
-  "vitest": {
-    "environment": "node"
-  },
   "scripts": {
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
@@ -67,7 +58,18 @@
     "lint:md:fix": "markdownlint-cli2 --fix \"**/*.md\"",
     "test": "vitest run",
     "test:watch": "vitest",
+    "prepublishOnly": "npm run lint && npm run lint:md && npm run test",
     "release:dry": "pnpm publish --dry-run --no-git-checks --access public",
     "release": "pnpm publish --no-git-checks --access public"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "eslint": "^9.0.0",
+    "globals": "^15.0.0",
+    "markdownlint-cli2": "0.23.2",
+    "vitest": "^4.1.5"
+  },
+  "vitest": {
+    "environment": "node"
   }
-}
+}

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

@@ -64,7 +64,11 @@ 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` when apply returns `VERIFIED`; tick `verify` when `pc-repo-verify` returns `PLAN_WRITTEN` or `STUB_WRITTEN`.
+Require it to return every task complete and `VERIFIED`, then load `pc-repo-verify`. Tick `apply` when apply returns `VERIFIED`. When `pc-repo-verify` returns `PLAN_WRITTEN` or `STUB_WRITTEN`, commit the plan, which the evidence workflow replays once the pull request merges, then tick `verify`:
+
+```bash
+git add openspec/changes/{change-id}/verification-plan.md && git commit -m "verify: {title} ({change-id})"
+```
 
 ## Phase 5: Archive
 

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

@@ -1,89 +1,87 @@
----
-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
-```
+---
+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.
+
+**`/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 the verification plan for the current branch's change: a journey through the new functionality as a fenced YAML block in `verification-plan.md`, stored with the change. The evidence workflow from `@plainconceptsplatform/workflows` replays it in headless Chromium when the pull request merges and archives one screenshot per waypoint on it. Backend-only changes are traced through to the frontend when their contract is consumed there; a `not-applicable` stub is written when no UI surface is reachable. Does not run checks or take screenshots. 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/skills/pc-repo-initialize/SKILL.md

@@ -51,10 +51,10 @@ First read `AGENTS.md`. Without the `<!-- PC-NOT-INITIALIZED -->` marker the pro
     },
     {
       "header": "Evidence",
-      "question": "Enable visual evidence capture for this project? (playwright-cli + pnpm run dev; no per-project scaffold needed)",
+      "question": "Record how the app starts and how a person signs in locally, so merged changes get screenshots?",
       "options": [
-        { "label": "Yes", "description": "Evidence will be captured automatically by /plan-goal using playwright-cli + pnpm run dev." },
-        { "label": "No", "description": "Skip evidence capture." }
+        { "label": "Yes", "description": "Fill the project environment in pc-repo-verify: start command, URL, local sign-in, seeded data." },
+        { "label": "No", "description": "Skip; the verification plans will look for the sign-in themselves." }
       ]
     }
   ]
@@ -93,7 +93,14 @@ Always. Load `pc-make-guardrails`.
 
 ## Step 7, Visual evidence
 
-If Yes, there is nothing to scaffold: `pc-ops-evidence` drives `playwright-cli` against the project's root `pnpm run dev`, which has to start the full stack with mock auth. CI installs `playwright-cli` itself.
+If Yes. Every change's verification plan (`pc-repo-verify`) is replayed in headless Chromium by the evidence workflow when its pull request merges, from a freshly started app with nothing in the browser. Find in the source, and confirm by reading the root `package.json`, `.env.example` and the local auth setup:
+
+- the command that starts the whole stack with mock authentication (normally `pnpm run dev` at the root),
+- the URL the web app answers on,
+- the local sign-in: the exact steps and visible labels of the mock account picker or dev login,
+- the data a fresh start seeds (accounts, records) that a journey can rely on.
+
+Write them as the bullet list between `<!-- PC-PROJECT-ENVIRONMENT-START -->` and `<!-- PC-PROJECT-ENVIRONMENT-END -->` in `.agents/skills/pc-repo-verify/SKILL.md`, replacing the placeholder bullets. Only that slot: the rest of the file is the harness's, and an update keeps only the slot.
 
 ## Step 8, Show help
 

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

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