Getting started
Install the harness, satisfy the prerequisites, and keep it up to date.
Requires Node.js 18 or higher
The wizard runs in the directory you invoke it from, so cd into the repository you want to
prepare before starting.
Run the wizard
npx @plainconceptsplatform/agent-harness@latestTen steps, run once. It keeps the current step visible plus the last two completed, so progress is always clear. See The wizard for what each step does.
Initialize the project
Open OpenCode in your project and run:
/repo-initializeOpenCode asks whether this is a greenfield or brownfield project. See The bootstrap sequence for what each path does.
Start working
Give the lead agent a work item URL or an idea and the
pipeline takes it from proposal to pull request. /repo-help lists every
command if you are unsure where to start.
Prerequisites
| Requirement | Notes |
|---|---|
| Node.js 18 or higher | Required |
| OpenCode | The agent runtime |
| gh CLI | GitHub platform, must be authenticated |
az CLI plus the azure-devops extension | Azure DevOps platform |
| acli | Jira backlog platform, must be authenticated |
| glab | GitLab repository platform, must be authenticated |
CLI checks are skipped for browser-based and None platforms.
Running individual steps
Setup and maintenance steps can run without the full wizard:
npx @plainconceptsplatform/agent-harness clean
npx @plainconceptsplatform/agent-harness platform
npx @plainconceptsplatform/agent-harness copy
npx @plainconceptsplatform/agent-harness openspec
npx @plainconceptsplatform/agent-harness models
npx @plainconceptsplatform/agent-harness optimization
npx @plainconceptsplatform/agent-harness browser
npx @plainconceptsplatform/agent-harness metadata
npx @plainconceptsplatform/agent-harness join
npx @plainconceptsplatform/agent-harness updateShow the CLI help and all commands:
npx @plainconceptsplatform/agent-harness --helpWhen available, step commands reuse context from .opencode/harness.json.
Keeping the harness current
A new release of agent-harness ships new commands, skills and plugins. To pull them into a project that already has the harness:
npx @plainconceptsplatform/agent-harness@latest updateupdate re-runs every file patch from .opencode/harness.json without asking anything. It
tracks a hash of each file it manages in .opencode/harness-managed.json, so anything you have
edited by hand is preserved rather than overwritten.
Upgrading from opencode-onboard v1
v2 renamed the config files and the skill prefix (ob- became pc-), and it does not migrate
v1 projects. The CLI detects one and refuses to run rather than half-patching it. Re-onboard on
a clean branch: remove .opencode/ and .agents/skills/ob-*, then run the wizard again.