@plainconceptsplatform/agent-harness 3.9.0 → 3.10.0

package/harness/AGENTS.md

@@ -1,55 +1,55 @@
-# AGENTS.md
-
-<!-- PC-NOT-INITIALIZED -->
-
-# Agent operating guide
-
-The operating contract for AI agents in this repository. Agent-agnostic: OpenCode, Claude Code, Codex, Gemini and others.
-
-## Session context
-
-Before a non-trivial change, read `AGENTS.md` for workflow rules, `ARCHITECTURE.md` for boundaries and component interactions, `DESIGN.md` for UI and design-system work, and the active OpenSpec change or the specification covering the area you are changing.
-
-Command aliases: OpenSpec skills may reference `/opsx-propose`, `/opsx-apply`, `/opsx-archive`, or `/opsx-explore`. Always substitute them with the `pc-plan-propose`, `pc-plan-apply`, `pc-plan-archive`, and `pc-plan-explore` skills respectively. User-facing command names are `/plan-propose`, `/plan-apply`, `/plan-archive`, and `/plan-explore`. Never mention the `opsx-` names to the user.
-
-## Workflow ownership
-
-<!-- PC-PLATFORM-WORKFLOW-START -->
-<!-- PC-PLATFORM-WORKFLOW-END -->
-
-## Planning and execution
-
-- Never combine an unrelated refactor with the work you were asked to do. It arrives under a message that does not mention it, and the reviewer approves both.
-- Never introduce a new convention where the repository already has one, and never guess when requirements, architecture or a security constraint are unclear. Ask.
-
-## Engineer selection
-
-Inspect `.opencode/agents/*.md` before spawning. Prefer the most specialized custom engineer. `build` and `plan` are the only primaries and are never spawned; `fullstack-engineer` is the body they share and the fallback worker, so prefer a specialist over it. If no specialist matches, tell the user to create one with `/make-engineer`. Spawn only engineers present in that directory.
-
-The `pc-plan-apply` skill is authoritative for subagent waves, dependency ordering, retries, and concurrency. A spawn past `agents.maxConcurrent` is denied (`pc-subagent-monitor`); a denied spawn is not a failed task, so re-issue it in the next wave.
-
-## Tool and repository safety
-
-- Never expose or commit secrets, credentials, tokens, or production data.
-- Never overwrite a generated file, or uncommitted changes you did not make. The tree may be shared with a person and another agent.
-- Never bypass a check, weaken a test, or silence a lint rule to reach a green result. A green run that was arranged is worse than a red one, because nobody looks again.
-- Commit, push, open a pull request, change dependencies, or touch deployment configuration only with the user's explicit approval and the repository's stated process.
-
-## Verification and completion
-
-- Never call a bug fixed without a test that would have caught it, where one is practical.
-- Never leave a specification, `ARCHITECTURE.md` or `DESIGN.md` asserting something this change made false.
-- Never end on a blocker without naming it and the decision it needs. An unattended run that stops quietly looks like one that finished.
-
-## Skills
-
-Skills live in `.agents/skills/`. Always installed: `@pc-guardrails-generic`, `@pc-guardrails-project`, and `@browser-automation`.
-
-<!-- PC-PLATFORM-SKILLS-START -->
-Mandatory, before any edit, shell command or subagent spawn: read `.agents/skills/pc-guardrails-generic/SKILL.md`, then `.agents/skills/pc-guardrails-project/SKILL.md` if present. They are instructions, not references: a loaded skill may name further skills, and those load too before the work they cover.
-<!-- PC-PLATFORM-SKILLS-END -->
-
-An entry under `## Abilities` is not a passive reference: call the `skill` tool once per `@skill-name`, guardrails first. Editing, shell and spawning stay blocked until you have (`pc-system-reminders`), and a loaded skill can require further loads.
-
-<!-- PC-PLATFORM-SKILLS-GUIDE-START -->
-<!-- PC-PLATFORM-SKILLS-GUIDE-END -->
+# AGENTS.md
+
+<!-- PC-NOT-INITIALIZED -->
+
+# Agent operating guide
+
+The operating contract for AI agents in this repository. Agent-agnostic: OpenCode, Claude Code, Codex, Gemini and others.
+
+## Session context
+
+Before a non-trivial change, read `AGENTS.md` for workflow rules, `ARCHITECTURE.md` for boundaries and component interactions, `DESIGN.md` for UI and design-system work, and the active OpenSpec change or the specification covering the area you are changing.
+
+Command aliases: OpenSpec skills may reference `/opsx-propose`, `/opsx-apply`, `/opsx-archive`, or `/opsx-explore`. Always substitute them with the `pc-plan-propose`, `pc-plan-apply`, `pc-plan-archive`, and `pc-plan-explore` skills respectively. User-facing command names are `/plan-propose`, `/plan-apply`, `/plan-archive`, and `/plan-explore`. Never mention the `opsx-` names to the user.
+
+## Workflow ownership
+
+<!-- PC-PLATFORM-WORKFLOW-START -->
+<!-- PC-PLATFORM-WORKFLOW-END -->
+
+## Planning and execution
+
+- Never combine an unrelated refactor with the work you were asked to do. It arrives under a message that does not mention it, and the reviewer approves both.
+- Never introduce a new convention where the repository already has one, and never guess when requirements, architecture or a security constraint are unclear. Ask.
+
+## Engineer selection
+
+Inspect `.opencode/agents/*.md` before spawning. Prefer the most specialized custom engineer. `build` and `plan` are the only primaries and are never spawned; `fullstack-engineer` is the body they share and the fallback worker, so prefer a specialist over it. If no specialist matches, tell the user to create one with `/make-engineer`. Spawn only engineers present in that directory.
+
+The `pc-plan-apply` skill is authoritative for subagent waves, dependency ordering, retries, and concurrency. A spawn past `agents.maxConcurrent` is denied (`pc-subagent-monitor`); a denied spawn is not a failed task, so re-issue it in the next wave.
+
+## Tool and repository safety
+
+- Never expose or commit secrets, credentials, tokens, or production data.
+- Never overwrite a generated file, or uncommitted changes you did not make. The tree may be shared with a person and another agent.
+- Never bypass a check, weaken a test, or silence a lint rule to reach a green result. A green run that was arranged is worse than a red one, because nobody looks again.
+- Commit, push, open a pull request, change dependencies, or touch deployment configuration only with the user's explicit approval and the repository's stated process.
+
+## Verification and completion
+
+- Never call a bug fixed without a test that would have caught it, where one is practical.
+- Never leave a specification, `ARCHITECTURE.md` or `DESIGN.md` asserting something this change made false.
+- Never end on a blocker without naming it and the decision it needs. An unattended run that stops quietly looks like one that finished.
+
+## Skills
+
+Skills live in `.agents/skills/`. Always installed: `@pc-guardrails-generic`, `@pc-guardrails-project`, and `@browser-automation`.
+
+<!-- PC-PLATFORM-SKILLS-START -->
+Mandatory, before any edit, shell command or subagent spawn: read `.agents/skills/pc-guardrails-generic/SKILL.md`, then `.agents/skills/pc-guardrails-project/SKILL.md` if present. They are instructions, not references: a loaded skill may name further skills, and those load too before the work they cover.
+<!-- PC-PLATFORM-SKILLS-END -->
+
+An entry under `## Abilities` is not a passive reference: call the `skill` tool once per `@skill-name`, guardrails first. Editing, shell and spawning stay blocked until you have (`pc-system-reminders`), and a loaded skill can require further loads.
+
+<!-- PC-PLATFORM-SKILLS-GUIDE-START -->
+<!-- PC-PLATFORM-SKILLS-GUIDE-END -->

package/harness/ARCHITECTURE.md

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

package/harness/DESIGN.md

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

package/harness/opencode.jsonc

@@ -1,36 +1,37 @@
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "servers": {
-      "agent-browser": {
-        "type": "local",
-        "command": ["agent-browser", "mcp", "--tools", "core"],
-        "disabled": false
-      }
-    },
-    "timeout": {
-      "catalog": 300000,
-      "execution": 300000
-    }
-  },
-  "compaction": {
-    "auto": true,
-    "buffer": 10000
-  },
-  "permissions": [
-    { "action": "question", "resource": "*", "effect": "allow" },
-    { "action": "skill", "resource": "*", "effect": "allow" }
-  ],
-  "skills": [".agents/skills"],
-  "default_agent": "plan",
-  "agents": {
-    "build": { "mode": "primary" },
-    "plan": {
-      "mode": "primary",
-      "permissions": [
-        { "action": "edit", "resource": "*", "effect": "deny" },
-        { "action": "subagent", "resource": "*", "effect": "deny" }
-      ]
-    }
-  }
-}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "servers": {
+      "browse": {
+        "type": "local",
+        "command": ["browse", "mcp"],
+        "environment": { "OPENCODE_BROWSER_RUNTIME": "auto-update" },
+        "disabled": false
+      }
+    },
+    "timeout": {
+      "catalog": 300000,
+      "execution": 300000
+    }
+  },
+  "compaction": {
+    "auto": true,
+    "buffer": 10000
+  },
+  "permissions": [
+    { "action": "question", "resource": "*", "effect": "allow" },
+    { "action": "skill", "resource": "*", "effect": "allow" }
+  ],
+  "skills": [".agents/skills"],
+  "default_agent": "plan",
+  "agents": {
+    "build": { "mode": "primary" },
+    "plan": {
+      "mode": "primary",
+      "permissions": [
+        { "action": "edit", "resource": "*", "effect": "deny" },
+        { "action": "subagent", "resource": "*", "effect": "deny" }
+      ]
+    }
+  }
+}

package/harness/openspec/config.yaml

@@ -1,20 +1,20 @@
-schema: spec-driven
-
-# Project context (optional)
-# This is shown to AI when creating artifacts.
-# Add your tech stack, conventions, style guides, domain knowledge, etc.
-# Example:
-#   context: |
-#     Tech stack: TypeScript, React, Node.js
-#     We use conventional commits
-#     Domain: e-commerce platform
-
-# Per-artifact rules (optional)
-# Add custom rules for specific artifacts.
-# Example:
-#   rules:
-#     proposal:
-#       - Keep proposals under 500 words
-#       - Always include a "Non-goals" section
-#     tasks:
-#       - Break tasks into chunks of max 2 hours
+schema: spec-driven
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours

package/harness/skills-lock.json

@@ -1,17 +1,17 @@
-{
-  "version": 1,
-  "skills": {
-    "find-skills": {
-      "source": "vercel-labs/skills",
-      "sourceType": "github",
-      "skillPath": "skills/find-skills/SKILL.md",
-      "computedHash": "781bd6d3f9b19f8c9af6b53d8d0e4876d0183841b565db34ca7092ffa412d111"
-    },
-    "user-story": {
-      "source": "deanpeters/product-manager-skills",
-      "sourceType": "github",
-      "skillPath": "skills/user-story/SKILL.md",
-      "computedHash": "user-story-placeholder"
-    }
-  }
-}
+{
+  "version": 1,
+  "skills": {
+    "find-skills": {
+      "source": "vercel-labs/skills",
+      "sourceType": "github",
+      "skillPath": "skills/find-skills/SKILL.md",
+      "computedHash": "781bd6d3f9b19f8c9af6b53d8d0e4876d0183841b565db34ca7092ffa412d111"
+    },
+    "user-story": {
+      "source": "deanpeters/product-manager-skills",
+      "sourceType": "github",
+      "skillPath": "skills/user-story/SKILL.md",
+      "computedHash": "user-story-placeholder"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/agent-harness",
-  "version": "3.9.0",
+  "version": "3.10.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/README.md

@@ -1,18 +1,18 @@
-# skills/
-
-Two kinds of skills live here, both discoverable by `npx skills`:
-
-| Kind | Directories | Purpose |
-| --- | --- | --- |
-| Installable `pc-*` + `browser-automation` | `pc-*`, `browser-automation` | What the CLI copies into a target project under `.agents/skills/` during onboarding. Plain Concepts' own skills. |
-| CLI-self | `agent-harness-cli` | Skills for agents working on THIS CLI repo (driving `npx @plainconceptsplatform/agent-harness`). Never copied into target projects. |
-
-Discoverability: any `SKILL.md` in a subdirectory here is auto-discovered by OpenCode, Claude Code, and `npx skills` (which scans `./skills/` as a recognized project-skill location).
-
-## Using one
-
-Point your agent at the directory, or copy a skill into wherever your tool discovers skills:
-
-```bash
-cp -r skills/agent-harness-cli ~/.claude/skills/
-```
+# skills/
+
+Two kinds of skills live here, both discoverable by `npx skills`:
+
+| Kind | Directories | Purpose |
+| --- | --- | --- |
+| Installable `pc-*` + `browser-automation` | `pc-*`, `browser-automation` | What the CLI copies into a target project under `.agents/skills/` during onboarding. Plain Concepts' own skills. |
+| CLI-self | `agent-harness-cli` | Skills for agents working on THIS CLI repo (driving `npx @plainconceptsplatform/agent-harness`). Never copied into target projects. |
+
+Discoverability: any `SKILL.md` in a subdirectory here is auto-discovered by OpenCode, Claude Code, and `npx skills` (which scans `./skills/` as a recognized project-skill location).
+
+## Using one
+
+Point your agent at the directory, or copy a skill into wherever your tool discovers skills:
+
+```bash
+cp -r skills/agent-harness-cli ~/.claude/skills/
+```

package/skills/agent-harness-cli/SKILL.md

@@ -1,86 +1,86 @@
----
-name: agent-harness-cli
-description: Drive the agent-harness CLI - install the Plain Concepts Platform Harness into a repository, bring an existing one up to date, set up a teammate's machine, or rerun a single step. Load when asked to install, update, or repair the Platform Harness, when a repo needs AI/agent scaffolding set up, or when a command like `npx @plainconceptsplatform/agent-harness` fails and needs diagnosing.
-license: MIT
----
-
-# agent-harness CLI
-
-`agent-harness` installs the **Plain Concepts Platform Harness** into a repository and keeps it up to date. The harness is Plain Concepts' own, and it is the set of files agents work from: slash commands, `pc-*` skills (the `pc-` is Plain Concepts), an agent team, OpenCode plugins, an OpenSpec workspace, and generated `ARCHITECTURE.md` and `DESIGN.md`.
-
-Everything runs against the **current working directory**. `cd` into the target repository first; there is no `--path` flag.
-
-## Pick the right verb
-
-Read the repo before running anything. `.opencode/harness.json` is the marker for "harness already installed".
-
-| Situation | Command |
-| --- | --- |
-| No `.opencode/harness.json` | `npx @plainconceptsplatform/agent-harness@latest` (the install wizard) |
-| Harness present, want the latest release's files | `npx @plainconceptsplatform/agent-harness@latest update` |
-| Harness present, new machine or new teammate | `npx @plainconceptsplatform/agent-harness join` |
-| One specific thing needs redoing | a single step command, see below |
-
-Requires Node.js 18+.
-
-## The install wizard is interactive
-
-The wizard asks about source scope, backlog and repository platform, three models, and optional token-optimization tools. **Do not run it in a non-interactive shell.** It will hang or abort. If you cannot present prompts to a human, say so and hand the command to the user rather than trying to drive it.
-
-Everything else (`update`, and the single-step commands other than `platform`, `models`, `optimization`) runs without prompts.
-
-## Single-step commands
-
-Run one step without the full wizard. Each reuses context from `.opencode/harness.json` when it needs to.
-
-```
-clean           Remove pre-existing AI files (AGENTS.md, .cursorrules, CLAUDE.md, ...)
-platform        Choose backlog + repository platform
-copy            Copy agents, skills, commands, docs into the repo
-openspec        Initialize the OpenSpec workspace
-models          Choose plan / build / fast models
-optimization    Configure RTK, quota, Simple English, codegraph, agentmemory, humanizer
-browser         Install agent-browser (npm package + its Chrome for Testing)
-metadata        Rewrite .opencode/harness.json
-```
-
-`metadata` last if you ran several, because it refreshes the config the others read.
-
-## What lands in the repo
-
-```
-.opencode/
-  harness.json            harness config: platform, models, agents.maxConcurrent
-  harness-managed.json    hash per managed file, so update spares your edits
-  harness.user.json       per-developer model override (gitignored)
-  harness-run.json        live subagent wave state (gitignored)
-  commands/               slash commands
-  plugins/                pc-commit-coauthor, pc-subagent-monitor, pc-subagent-tiers, pc-system-reminders
-  agents/                 fullstack-engineer + user-created *-engineer files
-.agents/skills/           pc-* skills
-AGENTS.md ARCHITECTURE.md DESIGN.md
-```
-
-After a fresh install, the next move is `/repo-initialize` inside OpenCode. That is what generates real `ARCHITECTURE.md` and `DESIGN.md` and activates the agent team. Installing the harness alone does not do it.
-
-## `update` is edit-safe
-
-`update` compares each managed file against the hash recorded in `.opencode/harness-managed.json`. Files you changed by hand are left alone and reported as preserved. Generated skills (`pc-guardrails-project`, `pc-merge-risk-assess`) are never overwritten once populated. So `update` is safe to run repeatedly, and a second consecutive run should report no changes.
-
-## Diagnosing failures
-
-**"This project was set up by opencode-onboard v1".** The repo has v1 state files or `ob-*` skills. v2 renamed both and does not migrate. Re-onboard on a clean branch; do not try to rename the files by hand, because the marker comments inside the installed skills changed too.
-
-**"No config found. Run the wizard first."** `update` or a step needs `.opencode/harness.json` and it is absent. Run the wizard.
-
-**A platform step reports nothing and changes nothing.** Platform content is injected into `<!-- PC-PLATFORM-*-START/END -->` marker pairs. If a marker pair is missing from the target file, injection is skipped silently. Check the markers exist before concluding the step worked.
-
-**Skills missing after install.** Skill installation ends with `npx skills experimental_install --yes`, run once at the end of the optimization step. If it failed, rerun it directly in the repo.
-
-**Platform CLI warnings.** The harness expects `gh` (GitHub), `az` + azure-devops extension (Azure DevOps), `acli` (Jira), `glab` (GitLab), each authenticated. These are warnings, not fatal; the harness installs, but the matching `/ops-*` flows will not work until the CLI is present.
-
-## Rules
-
-- Never edit `.opencode/harness.json` by hand to change models. Use `/make-user-model <tier> <model>` inside OpenCode, or the `models` step.
-- Never commit `harness.user.json` or `harness-run.json`. Both belong in `.opencode/.gitignore`, which `join` verifies.
-- `clean` deletes files. Confirm with the user before running it on a repo that already has AI configuration worth keeping.
+---
+name: agent-harness-cli
+description: Drive the agent-harness CLI - install the Plain Concepts Platform Harness into a repository, bring an existing one up to date, set up a teammate's machine, or rerun a single step. Load when asked to install, update, or repair the Platform Harness, when a repo needs AI/agent scaffolding set up, or when a command like `npx @plainconceptsplatform/agent-harness` fails and needs diagnosing.
+license: MIT
+---
+
+# agent-harness CLI
+
+`agent-harness` installs the **Plain Concepts Platform Harness** into a repository and keeps it up to date. The harness is Plain Concepts' own, and it is the set of files agents work from: slash commands, `pc-*` skills (the `pc-` is Plain Concepts), an agent team, OpenCode plugins, an OpenSpec workspace, and generated `ARCHITECTURE.md` and `DESIGN.md`.
+
+Everything runs against the **current working directory**. `cd` into the target repository first; there is no `--path` flag.
+
+## Pick the right verb
+
+Read the repo before running anything. `.opencode/harness.json` is the marker for "harness already installed".
+
+| Situation | Command |
+| --- | --- |
+| No `.opencode/harness.json` | `npx @plainconceptsplatform/agent-harness@latest` (the install wizard) |
+| Harness present, want the latest release's files | `npx @plainconceptsplatform/agent-harness@latest update` |
+| Harness present, new machine or new teammate | `npx @plainconceptsplatform/agent-harness join` |
+| One specific thing needs redoing | a single step command, see below |
+
+Requires Node.js 18+.
+
+## The install wizard is interactive
+
+The wizard asks about source scope, backlog and repository platform, three models, and optional token-optimization tools. **Do not run it in a non-interactive shell.** It will hang or abort. If you cannot present prompts to a human, say so and hand the command to the user rather than trying to drive it.
+
+Everything else (`update`, and the single-step commands other than `platform`, `models`, `optimization`) runs without prompts.
+
+## Single-step commands
+
+Run one step without the full wizard. Each reuses context from `.opencode/harness.json` when it needs to.
+
+```
+clean           Remove pre-existing AI files (AGENTS.md, .cursorrules, CLAUDE.md, ...)
+platform        Choose backlog + repository platform
+copy            Copy agents, skills, commands, docs into the repo
+openspec        Initialize the OpenSpec workspace
+models          Choose plan / build / fast models
+optimization    Configure RTK, quota, Simple English, codegraph, agentmemory, humanizer
+browser         Install browse (npm package + browser extension pairing)
+metadata        Rewrite .opencode/harness.json
+```
+
+`metadata` last if you ran several, because it refreshes the config the others read.
+
+## What lands in the repo
+
+```
+.opencode/
+  harness.json            harness config: platform, models, agents.maxConcurrent
+  harness-managed.json    hash per managed file, so update spares your edits
+  harness.user.json       per-developer model override (gitignored)
+  harness-run.json        live subagent wave state (gitignored)
+  commands/               slash commands
+  plugins/                pc-commit-coauthor, pc-subagent-monitor, pc-subagent-tiers, pc-system-reminders
+  agents/                 fullstack-engineer + user-created *-engineer files
+.agents/skills/           pc-* skills
+AGENTS.md ARCHITECTURE.md DESIGN.md
+```
+
+After a fresh install, the next move is `/repo-initialize` inside OpenCode. That is what generates real `ARCHITECTURE.md` and `DESIGN.md` and activates the agent team. Installing the harness alone does not do it.
+
+## `update` is edit-safe
+
+`update` compares each managed file against the hash recorded in `.opencode/harness-managed.json`. Files you changed by hand are left alone and reported as preserved. Generated skills (`pc-guardrails-project`, `pc-merge-risk-assess`) are never overwritten once populated. So `update` is safe to run repeatedly, and a second consecutive run should report no changes.
+
+## Diagnosing failures
+
+**"This project was set up by opencode-onboard v1".** The repo has v1 state files or `ob-*` skills. v2 renamed both and does not migrate. Re-onboard on a clean branch; do not try to rename the files by hand, because the marker comments inside the installed skills changed too.
+
+**"No config found. Run the wizard first."** `update` or a step needs `.opencode/harness.json` and it is absent. Run the wizard.
+
+**A platform step reports nothing and changes nothing.** Platform content is injected into `<!-- PC-PLATFORM-*-START/END -->` marker pairs. If a marker pair is missing from the target file, injection is skipped silently. Check the markers exist before concluding the step worked.
+
+**Skills missing after install.** Skill installation ends with `npx skills experimental_install --yes`, run once at the end of the optimization step. If it failed, rerun it directly in the repo.
+
+**Platform CLI warnings.** The harness expects `gh` (GitHub), `az` + azure-devops extension (Azure DevOps), `acli` (Jira), `glab` (GitLab), each authenticated. These are warnings, not fatal; the harness installs, but the matching `/ops-*` flows will not work until the CLI is present.
+
+## Rules
+
+- Never edit `.opencode/harness.json` by hand to change models. Use `/make-user-model <tier> <model>` inside OpenCode, or the `models` step.
+- Never commit `harness.user.json` or `harness-run.json`. Both belong in `.opencode/.gitignore`, which `join` verifies.
+- `clean` deletes files. Confirm with the user before running it on a repo that already has AI configuration worth keeping.