@plainconceptsplatform/agent-harness 3.3.1 → 3.5.0

package/cli/utils/paths.js

@@ -1,80 +1,81 @@
-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',
-]
+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',
+  'agents/planner.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/cli/utils/process.js

@@ -1,3 +1,3 @@
-export function exit(code = 0) {
-  process.exit(code)
-}
+export function exit(code = 0) {
+  process.exit(code)
+}

package/cli/utils/terminal.js

@@ -1,6 +1,6 @@
-export const MARKERS = {
-  EMPTY: "  ",
-  OK_PREFIX: "✓ ",
-  WARN_PREFIX: "⚠ ",
-  ERROR_PREFIX: "✗ ",
-};
+export const MARKERS = {
+  EMPTY: "  ",
+  OK_PREFIX: "✓ ",
+  WARN_PREFIX: "⚠ ",
+  ERROR_PREFIX: "✗ ",
+};

package/cli/utils/update-manifest.js

@@ -1,75 +1,75 @@
-import crypto from 'node:crypto'
-import fse from 'fs-extra'
-import path from 'node:path'
-import { MANIFEST_FILE, OPENCODE_DIR } from './paths.js'
-
-const MANIFEST_RELATIVE_PATH = path.join(OPENCODE_DIR, MANIFEST_FILE)
-
-function normalizeRelativePath(relativePath) {
-  return relativePath.split(path.sep).join('/')
-}
-
-function hashContent(content) {
-  return crypto.createHash('sha256').update(content).digest('hex')
-}
-
-export async function hashFile(filePath) {
-  return hashContent(await fse.readFile(filePath))
-}
-
-// A file counts as untouched when it differs from what we shipped only in ways
-// the harness itself caused. Two of those, and both made the raw-bytes
-// comparison call an untouched file modified — permanently, because the flag is
-// re-derived on every update:
-//
-//   1. Marker pairs. The patchers rewrite them after the copy, so a file with
-//      any PC-* marker never matches its own source again.
-//   2. Line endings. A file that reaches a consumer's tree through git arrives
-//      CRLF on Windows while the shipped source is LF.
-//
-// This is the general form of the bug that left five repos on a stale
-// browser-automation skill through repeated updates.
-const MARKER_PAIR = /(<!-- PC-[A-Z0-9-]+-START -->)[\s\S]*?(<!-- PC-[A-Z0-9-]+-END -->)/g
-
-function comparableContent(buffer) {
-  return buffer.toString('utf-8').replace(/\r\n/g, '\n').replace(MARKER_PAIR, '$1$2')
-}
-
-export async function hashComparableFile(filePath) {
-  return hashContent(comparableContent(await fse.readFile(filePath)))
-}
-
-export async function readUpdateManifest(cwd = process.cwd()) {
-  const manifestPath = path.join(cwd, MANIFEST_RELATIVE_PATH)
-  const manifest = await fse.readJson(manifestPath).catch(() => ({ version: 1, files: {} }))
-  if (!manifest.files || typeof manifest.files !== 'object') manifest.files = {}
-  return manifest
-}
-
-export async function writeUpdateManifest(manifest, cwd = process.cwd()) {
-  const manifestPath = path.join(cwd, MANIFEST_RELATIVE_PATH)
-  await fse.ensureDir(path.dirname(manifestPath))
-  await fse.writeJson(manifestPath, manifest, { spaces: 2 })
-}
-
-export async function canUpdateManagedFile(relativePath, cwd, manifest) {
-  const normalizedPath = normalizeRelativePath(relativePath)
-  const destinationPath = path.join(cwd, relativePath)
-  if (!await fse.pathExists(destinationPath)) return true
-  const previousHash = manifest.files?.[normalizedPath]
-  if (!previousHash) return false
-  // Raw is accepted too: manifests written before this comparison existed hold
-  // raw source hashes, and re-recording them all would need an update to run
-  // first, which is the thing being unblocked.
-  return previousHash === await hashComparableFile(destinationPath)
-    || previousHash === await hashFile(destinationPath)
-}
-
-export async function recordManagedFile(manifest, relativePath, sourcePath) {
-  const files = manifest.files
-  files[normalizeRelativePath(relativePath)] = await hashComparableFile(sourcePath)
-}
-
-export function manifestPath() {
-  return MANIFEST_RELATIVE_PATH
-}
+import crypto from 'node:crypto'
+import fse from 'fs-extra'
+import path from 'node:path'
+import { MANIFEST_FILE, OPENCODE_DIR } from './paths.js'
+
+const MANIFEST_RELATIVE_PATH = path.join(OPENCODE_DIR, MANIFEST_FILE)
+
+function normalizeRelativePath(relativePath) {
+  return relativePath.split(path.sep).join('/')
+}
+
+function hashContent(content) {
+  return crypto.createHash('sha256').update(content).digest('hex')
+}
+
+export async function hashFile(filePath) {
+  return hashContent(await fse.readFile(filePath))
+}
+
+// A file counts as untouched when it differs from what we shipped only in ways
+// the harness itself caused. Two of those, and both made the raw-bytes
+// comparison call an untouched file modified — permanently, because the flag is
+// re-derived on every update:
+//
+//   1. Marker pairs. The patchers rewrite them after the copy, so a file with
+//      any PC-* marker never matches its own source again.
+//   2. Line endings. A file that reaches a consumer's tree through git arrives
+//      CRLF on Windows while the shipped source is LF.
+//
+// This is the general form of the bug that left five repos on a stale
+// browser-automation skill through repeated updates.
+const MARKER_PAIR = /(<!-- PC-[A-Z0-9-]+-START -->)[\s\S]*?(<!-- PC-[A-Z0-9-]+-END -->)/g
+
+function comparableContent(buffer) {
+  return buffer.toString('utf-8').replace(/\r\n/g, '\n').replace(MARKER_PAIR, '$1$2')
+}
+
+export async function hashComparableFile(filePath) {
+  return hashContent(comparableContent(await fse.readFile(filePath)))
+}
+
+export async function readUpdateManifest(cwd = process.cwd()) {
+  const manifestPath = path.join(cwd, MANIFEST_RELATIVE_PATH)
+  const manifest = await fse.readJson(manifestPath).catch(() => ({ version: 1, files: {} }))
+  if (!manifest.files || typeof manifest.files !== 'object') manifest.files = {}
+  return manifest
+}
+
+export async function writeUpdateManifest(manifest, cwd = process.cwd()) {
+  const manifestPath = path.join(cwd, MANIFEST_RELATIVE_PATH)
+  await fse.ensureDir(path.dirname(manifestPath))
+  await fse.writeJson(manifestPath, manifest, { spaces: 2 })
+}
+
+export async function canUpdateManagedFile(relativePath, cwd, manifest) {
+  const normalizedPath = normalizeRelativePath(relativePath)
+  const destinationPath = path.join(cwd, relativePath)
+  if (!await fse.pathExists(destinationPath)) return true
+  const previousHash = manifest.files?.[normalizedPath]
+  if (!previousHash) return false
+  // Raw is accepted too: manifests written before this comparison existed hold
+  // raw source hashes, and re-recording them all would need an update to run
+  // first, which is the thing being unblocked.
+  return previousHash === await hashComparableFile(destinationPath)
+    || previousHash === await hashFile(destinationPath)
+}
+
+export async function recordManagedFile(manifest, relativePath, sourcePath) {
+  const files = manifest.files
+  files[normalizeRelativePath(relativePath)] = await hashComparableFile(sourcePath)
+}
+
+export function manifestPath() {
+  return MANIFEST_RELATIVE_PATH
+}

package/harness/.opencode/_gitignore

@@ -1,9 +1,10 @@
-node_modules
-harness-run.json
-harness.user.json
-harness-managed.json
-source-roots.json
-tmp/
-*-engineer.*.md
-agents/build.md
-agents/plan.md
+node_modules
+harness-run.json
+harness.user.json
+harness-managed.json
+source-roots.json
+tmp/
+*-engineer.*.md
+agents/build.md
+agents/plan.md
+agents/planner.md

package/harness/.opencode/commands/init.md

@@ -1,5 +1,5 @@
----
-description: Initialize the project. Presents a single form with all setup questions, then executes selected steps.
----
-
-Load the `pc-repo-initialize` skill.
+---
+description: Initialize the project. Presents a single form with all setup questions, then executes selected steps.
+---
+
+Load the `pc-repo-initialize` skill.

package/harness/.opencode/commands/make-architecture.md

@@ -1,5 +1,5 @@
----
-description: Generate or update ARCHITECTURE.md by analyzing the codebase structure. Safe to run at any time.
----
-
-Load the `pc-make-architecture` skill.
+---
+description: Generate or update ARCHITECTURE.md by analyzing the codebase structure. Safe to run at any time.
+---
+
+Load the `pc-make-architecture` skill.

package/harness/.opencode/commands/make-design.md

@@ -1,5 +1,5 @@
----
-description: Generate or update DESIGN.md by analyzing the codebase design system. Safe to run at any time.
----
-
-Load the `pc-make-design` skill.
+---
+description: Generate or update DESIGN.md by analyzing the codebase design system. Safe to run at any time.
+---
+
+Load the `pc-make-design` skill.

package/harness/.opencode/commands/make-engineer.md

@@ -1,5 +1,5 @@
----
-description: Create a custom engineer agent via persona-driven interactive design
----
-
-Load the `pc-make-engineer` skill.
+---
+description: Create a custom engineer agent via persona-driven interactive design
+---
+
+Load the `pc-make-engineer` skill.

package/harness/.opencode/commands/make-guardrails.md

@@ -1,5 +1,5 @@
----
-description: Generate or update a pc-guardrails-project skill from ARCHITECTURE.md and relevant project files.
----
-
-Load the `pc-make-guardrails` skill.
+---
+description: Generate or update a pc-guardrails-project skill from ARCHITECTURE.md and relevant project files.
+---
+
+Load the `pc-make-guardrails` skill.

package/harness/.opencode/commands/make-user-model.md

@@ -1,5 +1,5 @@
----
-description: Set the model for a tier (plan, build, or fast). Team-wide or user-local override.
----
-
-Load the `pc-make-user-model` skill.
+---
+description: Set the model for a tier (plan, build, or fast). Team-wide or user-local override.
+---
+
+Load the `pc-make-user-model` skill.

package/harness/.opencode/commands/ops-backlog.md

@@ -1,10 +1,10 @@
----
-description: Create an issue in the backlog platform (GitHub, Azure DevOps, Jira) from a description.
----
-
-Backlog platform is set in `.opencode/harness.json` → `platform.backlog`. The platform-specific content below is injected by the CLI during onboarding.
-
-Input: `$ARGUMENTS` (the issue title/description)
-
-<!-- PC-PLATFORM-BACKLOG-START -->
-<!-- PC-PLATFORM-BACKLOG-END -->
+---
+description: Create an issue in the backlog platform (GitHub, Azure DevOps, Jira) from a description.
+---
+
+Backlog platform is set in `.opencode/harness.json` → `platform.backlog`. The platform-specific content below is injected by the CLI during onboarding.
+
+Input: `$ARGUMENTS` (the issue title/description)
+
+<!-- PC-PLATFORM-BACKLOG-START -->
+<!-- PC-PLATFORM-BACKLOG-END -->

package/harness/.opencode/commands/ops-review.md

@@ -1,8 +1,10 @@
----
-description: Read and triage PR review feedback. Reports what needs fixing, does not implement fixes.
----
-
-Repo platform is set in `.opencode/harness.json` → `platform.repo`. The platform-specific content below is injected by the CLI during onboarding.
-
-<!-- PC-PLATFORM-REVIEW-START -->
-<!-- PC-PLATFORM-REVIEW-END -->
+---
+description: Read and triage PR review feedback. Reports what needs fixing, does not implement fixes.
+agent: planner
+subagent: false
+---
+
+Repo platform is set in `.opencode/harness.json` → `platform.repo`. The platform-specific content below is injected by the CLI during onboarding.
+
+<!-- PC-PLATFORM-REVIEW-START -->
+<!-- PC-PLATFORM-REVIEW-END -->

package/harness/.opencode/commands/ops-ship.md

@@ -1,9 +1,9 @@
----
-description: Create a pull request for the current feature branch with screenshots if UI changed.
----
-
-Load the `pc-ops-ship` skill and execute it.
-
-Input:
-
-$ARGUMENTS
+---
+description: Create a pull request for the current feature branch with screenshots if UI changed.
+---
+
+Load the `pc-ops-ship` skill and execute it.
+
+Input:
+
+$ARGUMENTS

package/harness/.opencode/commands/plan-apply.md

@@ -1,9 +1,9 @@
----
-description: "Implement tasks from a plan: works with OpenSpec proposals and in-conversation plans."
----
-
-Load the `pc-plan-apply` skill and execute it in **interactive mode** with `start_from: branch`.
-
-Input:
-
-$ARGUMENTS
+---
+description: "Implement tasks from a plan: works with OpenSpec proposals and in-conversation plans."
+---
+
+Load the `pc-plan-apply` skill and execute it in **interactive mode** with `start_from: branch`.
+
+Input:
+
+$ARGUMENTS

package/harness/.opencode/commands/plan-archive.md

@@ -1,5 +1,7 @@
----
-description: Archive the oldest merged unarchived OpenSpec change and update documentation.
----
-
-Load the `pc-plan-archive` skill and execute it in **interactive mode**. No input required.
+---
+description: Archive the oldest merged unarchived OpenSpec change and update documentation.
+agent: planner
+subagent: false
+---
+
+Load the `pc-plan-archive` skill and execute it in **interactive mode**. No input required.

package/harness/.opencode/commands/plan-explore.md

@@ -1,9 +1,11 @@
----
-description: Think through an idea, investigate a problem, or clarify requirements before creating a change.
----
-
-Load the `pc-plan-explore` skill and execute it in **interactive mode**.
-
-Input:
-
-$ARGUMENTS
+---
+description: Think through an idea, investigate a problem, or clarify requirements before creating a change.
+agent: planner
+subagent: false
+---
+
+Load the `pc-plan-explore` skill and execute it in **interactive mode**.
+
+Input:
+
+$ARGUMENTS

package/harness/.opencode/commands/plan-goal.md

@@ -1,5 +1,5 @@
----
-description: "Autonomous pipeline: explore, propose, apply, archive, then merge/PR/push. For loop-engineering."
----
-
-Load the `pc-plan-goal` skill.
+---
+description: "Autonomous pipeline: explore, propose, apply, archive, then merge/PR/push. For loop-engineering."
+---
+
+Load the `pc-plan-goal` skill.

package/harness/.opencode/commands/plan-propose.md

@@ -1,9 +1,11 @@
----
-description: Parse a work item or idea and propose a change plan with enriched task assignments.
----
-
-Load the `pc-plan-propose` skill and execute it in **interactive mode**.
-
-Input:
-
-$ARGUMENTS
+---
+description: Parse a work item or idea and propose a change plan with enriched task assignments.
+agent: planner
+subagent: false
+---
+
+Load the `pc-plan-propose` skill and execute it in **interactive mode**.
+
+Input:
+
+$ARGUMENTS

package/harness/.opencode/commands/plan-quick.md

@@ -1,5 +1,7 @@
----
-description: "Quick plan: analyze the codebase and create a task checklist using the Todo pane. No files, no OpenSpec."
----
-
-Load the `pc-plan-quick` skill.
+---
+description: "Quick plan: analyze the codebase and create a task checklist using the Todo pane. No files, no OpenSpec."
+agent: planner
+subagent: false
+---
+
+Load the `pc-plan-quick` skill.

package/harness/.opencode/commands/plan-story.md

@@ -1,9 +1,11 @@
----
-description: Write a detailed, repo-aware user story from a feature idea or need.
----
-
-Load the `pc-plan-story` skill.
-
-Input:
-
-$ARGUMENTS
+---
+description: Write a detailed, repo-aware user story from a feature idea or need.
+agent: planner
+subagent: false
+---
+
+Load the `pc-plan-story` skill.
+
+Input:
+
+$ARGUMENTS

package/harness/.opencode/commands/repo-audit.md

@@ -1,5 +1,7 @@
----
-description: Audit every configured source root against the fullstack engineer's guardrails and abilities. Read-only.
----
-
-Load the `pc-repo-audit` skill.
+---
+description: Audit every configured source root against the fullstack engineer's guardrails and abilities. Read-only.
+agent: planner
+subagent: false
+---
+
+Load the `pc-repo-audit` skill.

package/harness/.opencode/commands/repo-help.md

@@ -1,5 +1,5 @@
----
-description: Show all available commands and when to use each one.
----
-
-Load the `pc-repo-help` skill and display its reference to the user exactly as written. Do not summarize.
+---
+description: Show all available commands and when to use each one.
+---
+
+Load the `pc-repo-help` skill and display its reference to the user exactly as written. Do not summarize.