@plainconceptsplatform/agent-harness 3.1.0 → 3.2.0

package/harness/.opencode/scripts/code-rules.mjs

@@ -0,0 +1,280 @@
+// The same rules Project-Health uses to score a repository (collector/src/metrics/code-rules.ts).
+// Keep the two in step: a rule that differs makes the gate and the dashboard disagree.
+
+const SOURCE = /\.(?:[cm]?[jt]sx?|cs)$/
+const SKIP =
+  /(?:^|\/)(?:node_modules|dist|build|out|\.next|bin|obj|coverage|Migrations|migrations|wwwroot|vendor|generated|__generated__|\.github|\.opencode|\.agents|\.claude|openspec)(?:\/|$)|(?:^|\/)components\/ui\/|\.d\.ts$|\.g\.cs$|\.Designer\.cs$|\.min\.js$|AssemblyInfo\.cs$/
+const TEST =
+  /(?:^|\/)(?:tests?|__tests__|e2e|specs?)\/|\.(?:test|spec)\.[cm]?[jt]sx?$|(?:^|\/)[\w.]+\.(?:Unit|Integration|E2E|Acceptance|Architecture)?Tests?\/|Tests?\.cs$/
+const GENERATED_HEADER =
+  /Managed by @plainconceptsplatform|<auto-generated|@generated|This file was (?:auto-)?generated/i
+
+export function kindOf(path) {
+  if (!SOURCE.test(path) || SKIP.test(path)) return null
+  return TEST.test(path) ? 'test' : 'source'
+}
+
+export function isGenerated(text) {
+  return GENERATED_HEADER.test(text.split('\n', 4).join('\n'))
+}
+
+export function lineKinds(text) {
+  const kinds = []
+  let inBlock = false
+  for (const raw of text.split('\n')) {
+    const t = raw.trim()
+    if (!t) kinds.push('blank')
+    else if (inBlock) {
+      kinds.push('comment')
+      if (t.includes('*/')) inBlock = false
+    } else if (t.startsWith('/*')) {
+      kinds.push('comment')
+      inBlock = !t.includes('*/')
+    } else if (t.startsWith('//')) kinds.push('comment')
+    else kinds.push('code')
+  }
+  return kinds
+}
+
+export function countLines(text) {
+  let codeLines = 0
+  let commentLines = 0
+  for (const kind of lineKinds(text)) {
+    if (kind === 'code') codeLines += 1
+    else if (kind === 'comment') commentLines += 1
+  }
+  return { codeLines, commentLines }
+}
+
+const FILLER = new Set(
+  'a an the this that of for to in on is are be or and with by from its it get gets set sets getting setting value values instance class record struct interface enum new initializes initialises creates constructor property field method current specified given provided object function component hook type props'.split(' '),
+)
+const RETURNS_FILLER = new Set([
+  ...FILLER,
+  'result', 'results', 'task', 'representing', 'asynchronous', 'async', 'operation', 'returns', 'returned', 'which', 'that',
+])
+
+const words = text =>
+  text
+    .replace(/<see\s+cref="([^"]+)"\s*\/>/g, ' $1 ')
+    .replace(/<paramref\s+name="([^"]+)"\s*\/>/g, ' $1 ')
+    .replace(/\{@link\s+([^}\s]+)[^}]*\}/g, ' $1 ')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z])([A-Z][a-z])/g, '$1 $2')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean)
+
+const stem = w => (w.length > 3 && w.endsWith('s') && !w.endsWith('ss') ? w.slice(0, -1) : w)
+
+export function restates(text, identifier, filler = FILLER) {
+  const name = new Set(words(identifier.replace(/^I(?=[A-Z])/, '')).map(stem))
+  const said = words(text).filter(w => !filler.has(w) && !filler.has(stem(w))).map(stem)
+  return said.every(w => name.has(w))
+}
+
+const DECL_KEYWORD = /\b(?:class|record|struct|interface|enum|namespace|type|function)\s+([A-Za-z_$][\w$]*)/
+const DECL_VAR = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)/
+const DECL_CALL = /([A-Za-z_$][\w$]*)\s*(?:<[^()]*>)?\s*\(/
+const DECL_PROP = /([A-Za-z_$][\w$]*)\s*[?!]?\s*(?:\{|=>|=|;|:|$)/
+
+export function declaredName(line) {
+  const l = line.trim()
+  if (!l || l.startsWith('[') || l.startsWith('@')) return null
+  return (l.match(DECL_KEYWORD) ?? l.match(DECL_VAR) ?? l.match(DECL_CALL) ?? l.match(DECL_PROP))?.[1] ?? null
+}
+
+const BANNER = /^\/\/+\s*(?:([=\-*#~_+])\1{2,}.*|.*([=\-*#~_+])\2{2,})\s*$/
+const REGION = /^#(?:region|endregion)\b/
+const TODO = /\/\/.*\b(?:TODO|FIXME|HACK|XXX)\b/
+const TRACKED = /#\d+|https?:\/\/|\b[A-Z][A-Z0-9]+-\d+\b|\(\s*issue\s/i
+const APOLOGETIC =
+  /\b(?:not sure (?:if|whether|this|why)|hope this works|might not work|probably wrong|no idea why|i think this (?:works|is right)|quick and dirty)\b/i
+const CODE_BODY =
+  /^(?:(?:var|let|const|await|return|using|import|export|if|else|for|foreach|while|switch|throw|new|public|private|protected|internal|static|async)\b.*[;{(]\s*$|[\w.$[\]]+\s*(?:\+\+|--|[+\-*/]?=)\s*[^=].*;\s*$|[\w.$]+(?:<[^>]*>)?\([^)]*\)\s*;\s*$|[{}]\s*;?\s*$|\}\s*else\b.*$)/
+const TOOL_PRAGMA =
+  /^(?:nosemgrep|eslint|biome|jscpd|@ts-|prettier|istanbul|c8|v8|webpack|vite|ReSharper|resharper|language=|<auto-generated|#pragma)/
+
+const bodyOf = trimmed => trimmed.replace(/^\/\/+\s?/, '')
+
+export function trailingComment(line) {
+  let quote = null
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i]
+    if (quote) {
+      if (c === '\\') i += 1
+      else if (c === quote) quote = null
+    } else if (c === "'" || c === '"' || c === '`') quote = c
+    else if (c === '/' && line[i + 1] === '/' && line[i - 1] !== ':') return line.slice(i)
+  }
+  return null
+}
+
+export function slopFindings(text) {
+  const lines = text.split('\n')
+  const out = []
+  const add = (rule, line) => out.push({ rule, line })
+  const nameAfter = from => {
+    for (let k = from; k < lines.length && k < from + 6; k++) {
+      const name = declaredName(lines[k])
+      if (name) return name
+    }
+    return null
+  }
+  let codeRun = false
+  for (let i = 0; i < lines.length; i++) {
+    const t = lines[i].trim()
+    const isLineComment = t.startsWith('//') && !t.startsWith('///')
+    const body = isLineComment ? bodyOf(t).trim() : ''
+    const isCode =
+      isLineComment && body !== '' && !TOOL_PRAGMA.test(body) && CODE_BODY.test(body) && !/\s(?:https?:)?\/\//.test(body)
+    if (isCode && !codeRun) add('commented-out-code', i + 1)
+    codeRun = isCode || (codeRun && isLineComment && !body)
+
+    if (isLineComment && BANNER.test(t)) add('banner', i + 1)
+    if (REGION.test(t)) add('region', i + 1)
+    const comment = trailingComment(t)
+    if (comment && TODO.test(comment) && !TRACKED.test(comment)) add('untracked-todo', i + 1)
+    if ((t.startsWith('//') || t.startsWith('*') || t.startsWith('/*')) && APOLOGETIC.test(t)) add('apologetic', i + 1)
+
+    if (t.startsWith('///') && t.includes('<summary>')) {
+      const start = i
+      let doc = ''
+      let j = i
+      for (; j < lines.length && lines[j].trim().startsWith('///'); j++) {
+        doc += ` ${lines[j].trim().replace(/^\/\/\/\s?/, '')}`
+      }
+      const name = nameAfter(j)
+      const summary = doc.match(/<summary>([\s\S]*?)<\/summary>/)?.[1] ?? ''
+      if (name && summary.trim() && restates(summary, name)) add('restating-summary', start + 1)
+      for (const m of doc.matchAll(/<param\s+name="([^"]+)"\s*>([\s\S]*?)<\/param>/g)) {
+        if (m[2].trim() && restates(m[2], m[1])) add('restating-param', start + 1)
+      }
+      for (const m of doc.matchAll(/<returns>([\s\S]*?)<\/returns>/g)) {
+        if (m[1].trim() && restates(m[1], '', RETURNS_FILLER)) add('filler-returns', start + 1)
+      }
+      i = j - 1
+    } else if (t.startsWith('/**') && !t.startsWith('/***')) {
+      const start = i
+      let j = i
+      let doc = ''
+      for (; j < lines.length; j++) {
+        doc += ` ${lines[j].trim()}`
+        if (lines[j].includes('*/')) break
+      }
+      const text = doc.replace(/^\s*\/\*\*|\*\/\s*$/g, ' ').replace(/\s\*\s?/g, ' ').trim()
+      const summary = text.split(/\s@\w+/)[0]?.trim() ?? ''
+      const name = nameAfter(j + 1)
+      if (name && summary && restates(summary, name)) add('restating-jsdoc', start + 1)
+      for (const m of text.matchAll(/@param\s+(?:\{[^}]*\}\s*)?\[?([\w$.]+)\]?\s*(?:-\s*)?([^@]*)/g)) {
+        if (m[2].trim() && restates(m[2], m[1])) add('restating-param', start + 1)
+      }
+      for (const m of text.matchAll(/@returns?\s+(?:\{[^}]*\}\s*)?([^@]*)/g)) {
+        if (m[1].trim() && restates(m[1], '', RETURNS_FILLER)) add('filler-returns', start + 1)
+      }
+      i = j
+    }
+  }
+  return out
+}
+
+const ISSUE_REF = /(?:\b[A-Z][\w-]*\s)?#\d+\b|\b[A-Z][A-Z0-9]+-\d+\b/
+const PAST =
+  /\b(?:was|were|used to|previously|before|had|broke|regressed|ended up|turned out|once|anymore|no longer|caused)\b/i
+const TS_INTERNAL = /^(?:async\s+)?(?:function|const|let|var|class|interface|type|enum)\b/
+const CS_INTERNAL = /^(?:private|internal|private\s+protected)\b/
+
+export function commentBlocks(text) {
+  const lines = text.split('\n')
+  const blocks = []
+  const firstCode = lines.findIndex(l => {
+    const t = l.trim()
+    return t !== '' && !t.startsWith('//') && !t.startsWith('/*') && !t.startsWith('*')
+  })
+  let i = 0
+  while (i < lines.length) {
+    const t = lines[i].trim()
+    if (!(t.startsWith('//') || t.startsWith('/*'))) {
+      i += 1
+      continue
+    }
+    const start = i
+    let inBlock = false
+    let body = ''
+    for (; i < lines.length; i++) {
+      const s = lines[i].trim()
+      if (inBlock) {
+        body += ` ${s}`
+        if (s.includes('*/')) inBlock = false
+        continue
+      }
+      if (s.startsWith('/*')) {
+        body += ` ${s}`
+        inBlock = !s.includes('*/')
+        continue
+      }
+      if (s.startsWith('//')) {
+        body += ` ${s}`
+        continue
+      }
+      break
+    }
+    const rules = []
+    if (ISSUE_REF.test(body) && PAST.test(body)) rules.push('history')
+    if (i - start >= 5 && start > firstCode) rules.push('essay')
+    if (body.trimStart().startsWith('/**') || body.trimStart().startsWith('///')) {
+      const next = lines.slice(i, i + 4).find(l => {
+        const s = l.trim()
+        return s !== '' && !s.startsWith('[') && !s.startsWith('@')
+      })
+      const decl = next?.trim() ?? ''
+      if (TS_INTERNAL.test(decl) || CS_INTERNAL.test(decl)) rules.push('internal-doc')
+    }
+    blocks.push({ start: start + 1, end: i, rules })
+  }
+  return blocks
+}
+
+const TS_CASE =
+  /(?:^|[^\w.$])(x|f)?(?:it|test)(\.only|\.skip|\.todo|\.concurrent|\.each\s*(?:\([^)]*\)|`[^`]*`))?\s*\(\s*['"`]/g
+const CS_CASE = /\[(?:Fact|Theory|SkippableFact|SkippableTheory|Test|TestMethod)\b([^\]]*)\]/g
+const TS_ASSERT = /\b(?:expect|assert)\w*(?:\.\w+)?\s*\(|\.should\b/g
+const TS_CALL_ASSERT = /\.(?:not\.)?(?:toHaveBeenCalled\w*|toBeCalled\w*|toHaveBeenNthCalledWith)\s*\(/g
+const CS_ASSERT = /\bAssert\w*\.\w+|\.Should\w*\(|\bVerify\w*\(|\bThrows\w*(?:Async)?\s*[<(]|\.Received\(/g
+const CS_CALL_ASSERT = /\.Received\(|\.DidNotReceive\(|\.Verify\(\s*\w+\s*=>/g
+const SNAPSHOT = /\.toMatch(?:Inline|File)?Snapshot\s*\(|\bawait\s+Verify(?:Json|Xml)?\s*\(/
+
+const count = (text, re) => (text.match(re) ?? []).length
+
+export function testStats(path, text) {
+  const cs = path.endsWith('.cs')
+  const starts = []
+  for (const m of text.matchAll(cs ? CS_CASE : TS_CASE)) {
+    if (cs) {
+      starts.push({ index: m.index, skipped: /\bSkip\s*=/.test(m[1] ?? ''), focused: false })
+    } else {
+      const modifier = m[2] ?? ''
+      if (modifier === '.todo') continue
+      starts.push({ index: m.index, skipped: m[1] === 'x' || modifier === '.skip', focused: m[1] === 'f' || modifier === '.only' })
+    }
+  }
+  const stats = { cases: starts.length, skipped: 0, focused: 0, snapshot: 0, noAssertion: 0, mockOnly: 0 }
+  if (cs) stats.skipped += count(text, /\[Ignore\b/g)
+  else {
+    stats.skipped += count(text, /\b(?:describe\.skip|xdescribe)\s*\(/g)
+    stats.focused += count(text, /\b(?:describe\.only|fdescribe)\s*\(/g)
+  }
+  for (let k = 0; k < starts.length; k++) {
+    const s = starts[k]
+    const segment = text.slice(s.index, starts[k + 1]?.index ?? text.length)
+    if (s.skipped) stats.skipped += 1
+    if (s.focused) stats.focused += 1
+    if (SNAPSHOT.test(segment)) stats.snapshot += 1
+    const asserts = count(segment, cs ? CS_ASSERT : TS_ASSERT)
+    const callAsserts = count(segment, cs ? CS_CALL_ASSERT : TS_CALL_ASSERT)
+    if (asserts === 0) stats.noAssertion += 1
+    else if (callAsserts > 0 && callAsserts >= asserts) stats.mockOnly += 1
+  }
+  return stats
+}

package/harness/AGENTS.md

@@ -1,49 +1,49 @@
-# 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`. 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`. 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/agent-harness",
-  "version": "3.1.0",
+  "version": "3.2.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,7 +42,6 @@
   "engines": {
     "node": ">=18"
   },
-  "packageManager": "pnpm@11.10.0",
   "dependencies": {
     "@inquirer/prompts": "^7.0.0",
     "chalk": "^5.0.0",
@@ -51,17 +50,6 @@
     "jsonc-parser": "^3.3.1",
     "ora": "^8.0.0"
   },
-  "scripts": {
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "lint:md": "markdownlint-cli2 \"**/*.md\"",
-    "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",
@@ -71,5 +59,15 @@
   },
   "vitest": {
     "environment": "node"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "lint:md": "markdownlint-cli2 \"**/*.md\"",
+    "lint:md:fix": "markdownlint-cli2 --fix \"**/*.md\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "release:dry": "pnpm publish --dry-run --no-git-checks --access public",
+    "release": "pnpm publish --no-git-checks --access public"
   }
-}
+}

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/browser-automation/SKILL.md

@@ -1,72 +1,72 @@
----
-name: browser-automation
-description: Reliable, composable browser automation using agent-browser. Use when capturing screenshots of a locally running app, clicking UI elements, reading page content, or automating browser interactions on localhost.
-license: MIT
-compatibility: Requires agent-browser CLI installed (Rust binary) and running.
-metadata:
-  author: copilots
-  version: "2.0"
----
-
-This skill operates on `localhost` URLs only. Screenshots, clicks, typing, scrolling, and reads on locally running apps are in scope. External services (github.com, dev.azure.com, npmjs.com, etc.) are out of scope for browser tools.
-
-The only exception: when the user selects "Others (Browser)" as their backlog platform during onboarding, the `pc-userstory` skill may navigate to work item URLs the user explicitly provides. That is the sole case where external navigation is permitted, and only to URLs the user explicitly gives you.
-
-## Best-practice workflow
-
-1. Open the page: `agent-browser open <url>` (launches its own Chrome; reuses the running daemon)
-2. Take a snapshot: `agent-browser snapshot` to get the accessibility tree with `@ref` handles
-3. Interact by ref: `agent-browser click @e2`, `agent-browser fill @e3 "text"`
-4. Wait when needed: `agent-browser wait --load networkidle` or `agent-browser wait <selector>`
-5. Confirm the result with a fresh `snapshot`, `get text`, or `screenshot`
-
-Refs like `@e2` come from the last snapshot and go stale after page changes: retake the snapshot after navigation or dynamic updates before reusing them. When a click fails because another element covers the target (consent banner, modal), dismiss or interact with the covering element, then take a fresh snapshot before retrying.
-
-## Tool access
-
-- MCP tools (inside OpenCode): `agent_browser_open`, `agent_browser_snapshot`, `agent_browser_click`, `agent_browser_fill`, `agent_browser_type`, `agent_browser_wait_for_selector`, `agent_browser_screenshot`, `agent_browser_eval`, `agent_browser_close` — configured in `opencode.jsonc` with `--tools core`
-- CLI (any agent, any host): every command below works identically via bash
-- Diagnose the install: `agent-browser doctor`
-
-## Selecting elements
-
-- Prefer refs from `snapshot` (`@e1`, `@e2`, ...) over CSS selectors
-- CSS selectors also work: `agent-browser click "#submit"`, `agent-browser fill "#email" "text"`
-- Semantic locators: `agent-browser find role button click --name "Submit"`, `find text "Sign In" click`, `find label "Email" fill "value"`, `find testid <id> click`
-- Native selects: `agent-browser select <sel> <value>`
-
-## Reading state
-
-- `agent-browser get text <sel>` — text content of an element
-- `agent-browser get value <sel>` — input value
-- `agent-browser snapshot` — structured accessibility tree (preferred for parsing)
-- `agent-browser screenshot [path]` — `--full` for full page, `--annotate` for numbered labels
-- `agent-browser read` — agent-readable markdown of the active tab (no Chrome launch for URL reads)
-
-## Tabs and sessions
-
-- `agent-browser tab` lists tabs with stable `t1`, `t2` ids; `tab new --label <name>` and `tab <label>` switch
-- `agent-browser close` closes the browser; `close --all` closes every session
-
-## CLI-first debugging
-
-- `agent-browser doctor` — diagnose install, Chrome, and daemon state
-- `agent-browser console` — view console messages; `agent-browser errors` — uncaught exceptions
-- `agent-browser eval "<js>"` — run JavaScript in the page
-- `agent-browser network requests --filter api` — inspect tracked requests
-
-## Troubleshooting
-
-- Stale ref: take a fresh `snapshot` after any navigation or DOM change
-- Covered click: the error names the covering element; dismiss it, re-snapshot, retry
-- Selector fails: confirm the content exists with `agent-browser get text` or a snapshot before retrying
-- Daemon or Chrome issues: run `agent-browser doctor`
-
-## Scope
-
-- Screenshots of locally running app on `localhost` URLs: in scope
-- Click, type, scroll, read on `localhost` pages: in scope
-- Navigate to work item URLs the user explicitly provides (when backlog platform is "Others (Browser)"): in scope
-- Navigate to external services for non-work-item purposes: out of scope
-- DevOps or GitHub CLI operations via browser tools: out of scope
-- Reading or modifying production systems via browser tools: out of scope
+---
+name: browser-automation
+description: Reliable, composable browser automation using agent-browser. Use when capturing screenshots of a locally running app, clicking UI elements, reading page content, or automating browser interactions on localhost.
+license: MIT
+compatibility: Requires agent-browser CLI installed (Rust binary) and running.
+metadata:
+  author: copilots
+  version: "2.0"
+---
+
+This skill operates on `localhost` URLs only. Screenshots, clicks, typing, scrolling, and reads on locally running apps are in scope. External services (github.com, dev.azure.com, npmjs.com, etc.) are out of scope for browser tools.
+
+The only exception: when the user selects "Others (Browser)" as their backlog platform during onboarding, the `pc-userstory` skill may navigate to work item URLs the user explicitly provides. That is the sole case where external navigation is permitted, and only to URLs the user explicitly gives you.
+
+## Best-practice workflow
+
+1. Open the page: `agent-browser open <url>` (launches its own Chrome; reuses the running daemon)
+2. Take a snapshot: `agent-browser snapshot` to get the accessibility tree with `@ref` handles
+3. Interact by ref: `agent-browser click @e2`, `agent-browser fill @e3 "text"`
+4. Wait when needed: `agent-browser wait --load networkidle` or `agent-browser wait <selector>`
+5. Confirm the result with a fresh `snapshot`, `get text`, or `screenshot`
+
+Refs like `@e2` come from the last snapshot and go stale after page changes: retake the snapshot after navigation or dynamic updates before reusing them. When a click fails because another element covers the target (consent banner, modal), dismiss or interact with the covering element, then take a fresh snapshot before retrying.
+
+## Tool access
+
+- MCP tools (inside OpenCode): `agent_browser_open`, `agent_browser_snapshot`, `agent_browser_click`, `agent_browser_fill`, `agent_browser_type`, `agent_browser_wait_for_selector`, `agent_browser_screenshot`, `agent_browser_eval`, `agent_browser_close` — configured in `opencode.jsonc` with `--tools core`
+- CLI (any agent, any host): every command below works identically via bash
+- Diagnose the install: `agent-browser doctor`
+
+## Selecting elements
+
+- Prefer refs from `snapshot` (`@e1`, `@e2`, ...) over CSS selectors
+- CSS selectors also work: `agent-browser click "#submit"`, `agent-browser fill "#email" "text"`
+- Semantic locators: `agent-browser find role button click --name "Submit"`, `find text "Sign In" click`, `find label "Email" fill "value"`, `find testid <id> click`
+- Native selects: `agent-browser select <sel> <value>`
+
+## Reading state
+
+- `agent-browser get text <sel>` — text content of an element
+- `agent-browser get value <sel>` — input value
+- `agent-browser snapshot` — structured accessibility tree (preferred for parsing)
+- `agent-browser screenshot [path]` — `--full` for full page, `--annotate` for numbered labels
+- `agent-browser read` — agent-readable markdown of the active tab (no Chrome launch for URL reads)
+
+## Tabs and sessions
+
+- `agent-browser tab` lists tabs with stable `t1`, `t2` ids; `tab new --label <name>` and `tab <label>` switch
+- `agent-browser close` closes the browser; `close --all` closes every session
+
+## CLI-first debugging
+
+- `agent-browser doctor` — diagnose install, Chrome, and daemon state
+- `agent-browser console` — view console messages; `agent-browser errors` — uncaught exceptions
+- `agent-browser eval "<js>"` — run JavaScript in the page
+- `agent-browser network requests --filter api` — inspect tracked requests
+
+## Troubleshooting
+
+- Stale ref: take a fresh `snapshot` after any navigation or DOM change
+- Covered click: the error names the covering element; dismiss it, re-snapshot, retry
+- Selector fails: confirm the content exists with `agent-browser get text` or a snapshot before retrying
+- Daemon or Chrome issues: run `agent-browser doctor`
+
+## Scope
+
+- Screenshots of locally running app on `localhost` URLs: in scope
+- Click, type, scroll, read on `localhost` pages: in scope
+- Navigate to work item URLs the user explicitly provides (when backlog platform is "Others (Browser)"): in scope
+- Navigate to external services for non-work-item purposes: out of scope
+- DevOps or GitHub CLI operations via browser tools: out of scope
+- Reading or modifying production systems via browser tools: out of scope

package/skills/pc-guardrails-generic/SKILL.md

@@ -15,7 +15,7 @@ The marker sections below name the optimization skills this project selected. Lo
 
 ## Code
 
-- The default is zero comments. Add one only where the code is genuinely non-obvious. Past 10% comment-to-code ratio, refactor for clarity. Never add comments that restate the code, label variables, TODOs without a linked issue, commented-out code, separator banners, or auto-generated docstrings/JSDoc/XML docs unless explicitly asked.
+- Zero comments by default. Write one only for what the code cannot show and we do not control: a vendor bug, an external contract, a legal rule. Leave every file you touch with no comment slop, old or new.
 - Never add a file that collects unrelated things — `constants.js`, `types.ts`, `utils.ts`. One responsibility per file, split by domain. A file importing from many unrelated modules is already the symptom.
 
 ## Temporary files
@@ -28,6 +28,7 @@ The marker sections below name the optimization skills this project selected. Lo
 - Never write more tests than the change requires. A bug fix gets one regression test. A new function gets tests for its public contract, not every internal branch. Never aim for a coverage number.
 - Never test framework or library internals. Test your code's contract, not that EF Core saves a tracked entity.
 - Never generate integration, e2e, or snapshot tests unless explicitly asked. Mock nothing you do not own — use a fake that records state. Never add a test that duplicates a type-check or linter rule.
+- `node .opencode/scripts/check-diff.mjs` enforces the comment and test rules on the diff and must exit 0.
 
 <!-- PC-GUARDRAILS-RTK-START -->
 <!-- PC-GUARDRAILS-RTK-END -->