@plainconceptsplatform/agent-harness 2.0.0

package/src/fragments/ops-evidence/az.md

@@ -0,0 +1,41 @@
+**Browser MCP tools are FORBIDDEN for all Azure DevOps operations. Use `az boards` CLI only. If `az` is unavailable, skip publishing (report it) — do not fail the pipeline unless the caller declared publishing a ship gate.**
+
+Publish one status comment for every manifest. A `blocked` or `failed` manifest must include its status and reason, never a success claim.
+
+### Step 1 — Image hosting caveat
+
+Azure DevOps discussion comments do not render an image from a repo blob URL the way GitHub does, and `az boards` cannot upload an attachment inline. Use text evidence and derive a commit-pinned repository URL from `git remote get-url origin` when possible. Otherwise include the committed asset path, branch, and SHA.
+
+```
+Screenshot committed at: {asset-path} (branch {branch}, commit {sha})
+```
+
+### Step 2 — Build the comment with a stable marker (idempotent)
+
+```
+<!-- pc-visual-evidence:{change-id} -->
+
+Status: `{status}`
+
+{reason?}
+
+Manifest and assets: {commit-pinned links when available, otherwise committed paths and SHA}
+
+{prMarkdown}
+
+{image-line?}
+```
+
+### Step 3 — Upsert the discussion comment on the work item (and the PR when provided)
+
+`az boards work-item update --discussion` appends a comment; to stay idempotent, first read existing discussion comments and skip if one already carries the marker for this change id, otherwise post:
+
+```bash
+# best-effort existing-comment check via the work-item comments API
+az boards work-item show --id {work-item-id} --query 'fields."System.History"' -o tsv 2>/dev/null | grep -q "pc-visual-evidence:{change-id}" \
+  || az boards work-item update --id {work-item-id} --discussion "$BODY"
+```
+
+When a PR number is provided, also add the same body as a PR thread comment (`az repos pr` thread APIs) if available.
+
+- If a comment call fails: report it. Fail the run ONLY when publishing was declared a ship gate; otherwise continue.

package/src/fragments/ops-evidence/gh.md

@@ -0,0 +1,53 @@
+**ALL GitHub data MUST come from `gh` CLI. NEVER use webfetch, HTTP requests, or browser MCP tools for GitHub. If `gh` is unavailable, skip publishing (report it) — do not fail the pipeline over it unless the caller declared publishing a ship gate.**
+Always pass `--repo {owner}/{repo}` (or `repos/{owner}/{repo}` for `gh api`) explicitly.
+
+Publish one status comment for every manifest. A `blocked` or `failed` manifest must include its status and reason, never a success claim.
+
+### Step 1 — Build commit-pinned repository links
+
+An embedded image must be a raw URL pinned to the commit that actually contains it, and that commit must be pushed. For each asset in `evidence.json`:
+
+```bash
+SHA="$(git log -n 1 --format=%H -- '{asset-path}')"          # the commit that added this asset
+[ -z "$SHA" ] && echo "asset not committed: {asset-path}" && exit-skip
+gh api "repos/{owner}/{repo}/contents/{asset-path}?ref=$SHA" --silent   # 404 → not pushed yet → skip embedding
+```
+
+Build a blob link for every committed manifest and asset: `https://github.com/{owner}/{repo}/blob/{SHA}/{asset-path}`. Use the raw URL only for a verified embeddable image: `https://raw.githubusercontent.com/{owner}/{repo}/{SHA}/{asset-path}`. If verification fails, include the asset path and SHA as text; never post a dead link.
+
+### Step 2 — Build the comment body with a stable marker (idempotent)
+
+Prefix the body with a hidden marker so re-runs update the same comment instead of piling on:
+
+```
+<!-- pc-visual-evidence:{change-id} -->
+
+Status: `{status}`
+
+{reason?}
+
+Manifest: {commit-pinned evidence.json link}
+
+Assets: {commit-pinned asset links}
+
+{prMarkdown}
+```
+
+### Step 3 — Upsert the comment on BOTH the issue and the PR
+
+For each target number (the originating issue, and the PR number when provided), find an existing marked comment and PATCH it, else POST a new one:
+
+```bash
+# find existing
+ID="$(gh api "repos/{owner}/{repo}/issues/{number}/comments" --paginate --jq \
+  '.[] | select(.body | contains("<!-- pc-visual-evidence:{change-id} -->")) | .id' | head -1)"
+
+if [ -n "$ID" ]; then
+  gh api --method PATCH "repos/{owner}/{repo}/issues/comments/$ID" -f body="$BODY" --silent
+else
+  gh api --method POST  "repos/{owner}/{repo}/issues/{number}/comments" -f body="$BODY" --silent
+fi
+```
+
+- Text-only (no verified image, or `default` mode / nothing pushed): drop the image lines, keep the summary (tasks N/N, verification result, commits).
+- If a comment call fails: report it. Fail the run ONLY when the caller declared publishing a ship gate; otherwise continue.

package/src/fragments/ops-evidence/jira.md

@@ -0,0 +1,38 @@
+**NEVER use browser tools to navigate to atlassian.net: use `acli` CLI only. If `acli` is unavailable, skip publishing (report it) — do not fail the pipeline unless the caller declared publishing a ship gate.**
+
+Publish one status comment for every manifest. A `blocked` or `failed` manifest must include its status and reason, never a success claim.
+
+### Step 1 — Image hosting caveat
+
+Jira comments cannot embed an image from a repo blob URL, and `acli` does not upload attachments inline. Use text evidence and derive a commit-pinned repository URL from `git remote get-url origin` when possible. Otherwise include the committed asset path, branch, and SHA:
+
+```
+Screenshot committed at: {asset-path} (branch {branch}, commit {sha})
+```
+
+### Step 2 — Build the comment with a stable marker (idempotent)
+
+```
+<!-- pc-visual-evidence:{change-id} -->
+
+Status: `{status}`
+
+{reason?}
+
+Manifest and assets: {commit-pinned links when available, otherwise committed paths and SHA}
+
+{prMarkdown}
+
+{image-line?}
+```
+
+### Step 3 — Upsert the comment on the issue
+
+Keep it idempotent: list existing comments and skip if one already carries the marker for this change id, otherwise add:
+
+```bash
+acli jira issue comment list --key {issue-key} 2>/dev/null | grep -q "pc-visual-evidence:{change-id}" \
+  || acli jira issue comment --key {issue-key} --body "$BODY"
+```
+
+- If the comment command fails: report it. Fail the run ONLY when publishing was declared a ship gate; otherwise continue.

package/src/fragments/ops-review/az.md

@@ -0,0 +1,63 @@
+**Browser MCP tools are FORBIDDEN for all Azure DevOps operations.**
+
+---
+
+### Step 1: Find PRs
+
+If PR link provided, extract ID from URL. Otherwise:
+
+```bash
+az repos pr list --repository {repo} --status active --top 1
+```
+
+### Step 2: Read comment threads
+
+```bash
+az devops invoke \
+  --area git --resource pullRequestThreads \
+  --route-parameters project={project} repositoryId={repo} pullRequestId={id} \
+  --http-method GET --api-version 7.1
+```
+
+### Step 3: Categorize feedback
+
+| Category      | Description                         | Action                              |
+| ------------- | ----------------------------------- | ----------------------------------- |
+| `code-change` | Reviewer requests code modification | Return to lead to spawn specialists |
+| `spec-update` | Affects proposal, design, or tasks  | Update openspec artifacts           |
+| `question`    | Reviewer asks a question            | Reply with answer                   |
+| `resolved`    | Thread already resolved             | Skip                                |
+
+### Step 4: Update openspec (if spec-update)
+
+```bash
+git branch --show-current
+# feature/193208-roles-crud → change: us-193208-roles-crud
+```
+
+Update: `openspec/changes/{change}/proposal.md`, `design.md`, or `tasks.md` as appropriate.
+
+### Step 5: Reply to each thread
+
+```bash
+az devops invoke \
+  --area git --resource pullRequestThreadComments \
+  --route-parameters project={project} repositoryId={repo} pullRequestId={id} threadId={tid} \
+  --http-method POST --api-version 7.1 --in-file reply.json
+```
+
+`reply.json`:
+
+```json
+{
+  "comments": [
+    {
+      "parentCommentId": 1,
+      "content": "Acknowledged, applying this change now.",
+      "commentType": 1
+    }
+  ]
+}
+```
+
+---

package/src/fragments/ops-review/gh.md

@@ -0,0 +1,53 @@
+**ALL GitHub data MUST come from `gh` CLI. NEVER use webfetch, HTTP requests, or browser MCP tools for GitHub operations, even if gh CLI fails. If `gh` is unavailable, report as a blocker.**
+Always pass `--repo {owner}/{repo}` explicitly, never rely on git context to resolve the repo.
+
+---
+
+### Step 1: Find PRs
+
+If PR link provided, extract number from URL. Otherwise:
+
+```bash
+gh pr list --repo {owner}/{repo} --state open --limit 1
+```
+
+### Step 2: Read comment threads
+
+```bash
+gh pr view {pr-number} --repo {owner}/{repo} --comments
+# Or structured output:
+gh api repos/{owner}/{repo}/pulls/{pr-number}/comments
+gh api repos/{owner}/{repo}/pulls/{pr-number}/reviews
+```
+
+### Step 3: Categorize feedback
+
+| Category      | Description                         | Action                              |
+| ------------- | ----------------------------------- | ----------------------------------- |
+| `code-change` | Reviewer requests code modification | Return to lead to spawn specialists |
+| `spec-update` | Affects proposal, design, or tasks  | Update openspec artifacts           |
+| `question`    | Reviewer asks a question            | Reply with answer                   |
+| `resolved`    | Thread already resolved             | Skip                                |
+
+### Step 4: Update openspec (if spec-update)
+
+```bash
+git branch --show-current
+# feature/add-user-auth → change: add-user-auth
+```
+
+Update: `openspec/changes/{change}/proposal.md`, `design.md`, or `tasks.md` as appropriate.
+
+### Step 5: Reply to each comment thread
+
+```bash
+# Reply to a review comment
+gh api repos/{owner}/{repo}/pulls/{pr-number}/comments/{comment-id}/replies \
+  --method POST \
+  --field body="Acknowledged, applying this change now."
+
+# Or post a general PR comment
+gh pr comment {pr-number} --body "Updated design.md to reflect feedback."
+```
+
+---

package/src/fragments/ops-review/gl.md

@@ -0,0 +1,57 @@
+**ALL GitLab data MUST come from `glab` CLI. NEVER use webfetch, HTTP requests, or browser MCP tools for GitLab operations, even if glab CLI fails. If `glab` is unavailable, report as a blocker.**
+Always pass `--repo {owner}/{repo}` explicitly, never rely on git context to resolve the repo.
+
+---
+
+### Step 1: Parse MR URL or number
+
+- `https://gitlab.com/{owner}/{repo}/-/merge_requests/123` → MR !123, repo: `{owner}/{repo}`
+- `https://gitlab.com/{owner}/{repo}/-/merge_requests/123#note_456` → MR !123, note: 456
+- `!123` → MR !123
+
+### Step 2: Fetch MR details and comments
+
+```bash
+glab mr view {number} --repo {owner}/{repo}
+glab mr note list {number} --repo {owner}/{repo}
+```
+
+Also fetch MR threads (inline code comments):
+
+```bash
+glab api "projects/:id/merge_requests/{number}/discussions"
+```
+
+### Step 3: Classify comments
+
+Categorize each comment as:
+- **BLOCKER**: must fix before merge (test failures, security issues, broken logic)
+- **IMPORTANT**: should fix (missing edge case, code quality, performance)
+- **SUGGESTION**: nice to have (style, refactor, docs)
+- **QUESTION**: needs clarification (respond or discuss)
+- **RESOLVED**: already addressed or invalid
+
+### Step 4: Report
+
+Display a structured summary:
+
+```text
+MR Feedback Summary: !{number}
+
+  Blockers: {count}
+    [B1] {comment-author}: {comment-summary}
+  Important: {count}
+    [I1] {comment-author}: {comment-summary}
+  Suggestions: {count}
+    [S1] {comment-author}: {comment-summary}
+  Questions: {count}
+    [Q1] {comment-author}: {comment-summary}
+
+Next: Run /plan-apply to fix blockers and important items.
+```
+
+### Step 5: Do NOT implement fixes
+
+This mode only triages. Fixing is done via `/plan-apply`. Tell the user what needs fixing, then stop.
+
+---

package/src/fragments/ops-ship/az.md

@@ -0,0 +1,81 @@
+**Browser MCP tools are FORBIDDEN for all Azure DevOps operations.**
+Browser tools are ONLY permitted for screenshots of the LOCAL running app on `localhost` URLs.
+
+---
+
+### Step 1: Verify feature branch
+
+```bash
+git branch --show-current
+```
+
+Branch must be `feature/{id}-{slug}`. NEVER push to `main`.
+
+### Step 2: Capture screenshots (if UI changes exist)
+
+```bash
+browser_navigate url="http://localhost:{port}/{route}"
+browser_wait ms=2000
+browser_screenshot
+```
+
+Save to: `openspec/changes/{change-name}/images/{feature}.png`
+
+### Step 3: Commit and push
+
+```bash
+git add .
+git commit -m "feat({scope}): {description} (#{id})"
+git push origin feature/{id}-{slug}
+```
+
+### Step 4: Create PR
+
+```bash
+az repos pr create \
+  --repository {repo} \
+  --source-branch feature/{id}-{slug} \
+  --target-branch main \
+  --title "feat({scope}): {title} (#{id})" \
+  --description "{description}"
+```
+
+### Step 5: Link work item (MANDATORY, run sequentially, not in parallel)
+
+```bash
+az repos pr work-item add --id {pr-id} --work-items {workitem-id}
+```
+
+### Step 6: Post screenshot comment
+
+Build raw URL for each image:
+
+```
+https://dev.azure.com/{org}/{project}/_apis/git/repositories/{repo}/items?path=openspec/changes/{change}/images/{file}.png&versionType=branch&version={branch}&api-version=7.1
+```
+
+Post via:
+
+```bash
+az devops invoke \
+  --area git --resource pullRequestThreads \
+  --route-parameters project={project} repositoryId={repo} pullRequestId={pr-id} \
+  --http-method POST --api-version 7.1 --in-file body.json
+```
+
+`body.json`:
+
+```json
+{
+  "comments": [
+    {
+      "parentCommentId": 0,
+      "content": "## Screenshots\n\n![{feature}]({raw-url})",
+      "commentType": 1
+    }
+  ],
+  "status": "active"
+}
+```
+
+---

package/src/fragments/ops-ship/gh.md

@@ -0,0 +1,69 @@
+**ALL GitHub data MUST come from `gh` CLI. NEVER use webfetch, HTTP requests, or browser MCP tools for GitHub operations, even if gh CLI fails. If `gh` is unavailable, report as a blocker.**
+Always pass `--repo {owner}/{repo}` explicitly, never rely on git context to resolve the repo.
+
+---
+
+### Step 1: Verify feature branch
+
+```bash
+BRANCH="$(git branch --show-current)"
+DEFAULT_BRANCH="$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')"
+[ -z "$DEFAULT_BRANCH" ] && DEFAULT_BRANCH="main"
+```
+
+`$BRANCH` must be a work branch (`feature/*` or `bugfix/*`: the `pc-plan-apply` skill creates `feature/{change-slug}`). NEVER push the default branch.
+
+### Step 2: Capture screenshots (if UI changes exist)
+
+```bash
+browser_navigate url="http://localhost:{port}/{route}"
+browser_wait ms=2000
+browser_screenshot
+```
+
+Save to: `openspec/changes/{change-name}/images/{feature}.png`
+
+### Step 3: Commit and push
+
+The `pc-plan-apply` skill already committed each task group: usually only screenshots or small residuals remain. Stage **specific paths only** (never `git add .`, it sweeps unrelated files into the ship commit):
+
+```bash
+git add openspec/changes/{change-name}/images/  # plus any other paths you actually changed
+git commit -m "feat({scope}): {description} (#{id})"   # only if there is something to commit
+git push -u origin "$BRANCH"
+```
+
+### Step 4: Create PR
+
+```bash
+gh pr create \
+  --repo {owner}/{repo} \
+  --base "$DEFAULT_BRANCH" \
+  --head "$BRANCH" \
+  --title "feat({scope}): {title} (#{id})" \
+  --body "{description}"
+```
+
+### Step 5: Post screenshot comment
+
+Resolve commit SHA (the commit that includes screenshots):
+
+```bash
+git rev-parse HEAD
+```
+
+Build blob URL for each image with `?raw=true` (a plain blob URL renders the GitHub HTML page, not the image, inside `![...]()`):
+
+```
+https://github.com/{owner}/{repo}/blob/{sha}/openspec/changes/{change}/images/{file}.png?raw=true
+```
+
+Note: on private repos the embedded image is only visible to users with repo access.
+
+Post comment:
+
+```bash
+gh pr comment {pr-number} --repo {owner}/{repo} --body $'## Screenshots\n\n![{feature}]({blob-url})'
+```
+
+---

package/src/fragments/ops-ship/gl.md

@@ -0,0 +1,86 @@
+**ALL GitLab data MUST come from `glab` CLI. NEVER use webfetch, HTTP requests, or browser MCP tools for GitLab operations, even if glab CLI fails. If `glab` is unavailable, report as a blocker.**
+Always pass `--repo {owner}/{repo}` explicitly, never rely on git context to resolve the repo.
+
+---
+
+### Step 1: Verify feature branch
+
+```bash
+BRANCH="$(git branch --show-current)"
+DEFAULT_BRANCH="$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')"
+[ -z "$DEFAULT_BRANCH" ] && DEFAULT_BRANCH="main"
+```
+
+`$BRANCH` must be a work branch (`feature/*` or `bugfix/*`: the `pc-plan-apply` skill creates `feature/{change-slug}`). NEVER push the default branch.
+
+### Step 2: Capture screenshots (if UI changes exist)
+
+```bash
+browser_navigate url="http://localhost:{port}/{route}"
+browser_wait ms=2000
+browser_screenshot
+```
+
+Save to: `openspec/changes/{change-name}/images/{feature}.png`
+
+### Step 3: Commit and push
+
+The `pc-plan-apply` skill already committed each task group: usually only screenshots or small residuals remain. Stage **specific paths only** (never `git add -A`, it sweeps unrelated files into the ship commit):
+
+```bash
+git add openspec/changes/{change-name}/images/  # plus any other paths you actually changed
+git commit -m "{change}: {summary}"   # only if there is something to commit
+git push -u origin "$BRANCH"
+```
+
+### Step 4: Upload screenshots (if any)
+
+If screenshots exist, upload them so they can be referenced in the MR description:
+
+```bash
+glab api --method POST "projects/:id/uploads" -f "file=@openspec/changes/{change-name}/images/{feature}.png"
+```
+
+(`:id` is glab's placeholder for the current project: this is the one sanctioned use of git context in this skill.)
+
+Parse the returned `markdown` field: use it to embed the image in the MR description. If the upload fails (the endpoint needs multipart form data and `-f` support varies by glab version), fall back to referencing the image committed on the branch instead.
+
+If no UI changes, skip this step.
+
+### Step 5: Create Merge Request
+
+```bash
+glab mr create \
+  --source-branch "$BRANCH" \
+  --target-branch "$DEFAULT_BRANCH" \
+  --title "{title}" \
+  --description "Closes {issue-link}
+
+## Summary
+{summary from proposal.md}
+
+## Changes
+{key changes from tasks.md}
+
+## Test plan
+- [ ] {checklist of manual verification steps}
+{screenshots if available}" \
+  --remove-source-branch \
+  --squash-before-merge
+```
+
+Do NOT use `--yes` unless running in autopilot/non-interactive mode.
+
+### Step 6: Report
+
+Display:
+
+```text
+Merge Request created
+  MR: {mr-url}
+  Title: {title}
+  Source: {branch}
+  Target: {default-branch}
+```
+
+---

package/src/index.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import chalk from 'chalk'
+import { createRequire } from 'node:module'
+import { runJoin } from './commands/join.js'
+import { runUpdate } from './commands/update.js'
+import { runSingleCommand } from './commands/single.js'
+import { runWizard } from './commands/wizard.js'
+import { exit } from './utils/process.js'
+import { findLegacyInstall } from './utils/legacy-check.js'
+
+function printHelp(version) {
+  console.log(`agent-harness v${version}`)
+  console.log()
+  console.log('Usage:')
+  console.log('  npx @plainconceptsplatform/agent-harness             Install the harness (full wizard)')
+  console.log('  npx @plainconceptsplatform/agent-harness <command>   Run a single step command')
+  console.log()
+  console.log('Commands:')
+  console.log('  update          Bring the harness up to date from saved config (no prompts)')
+  console.log('  join            Set up a teammate\'s machine (checks & local installs only)')
+  console.log('  clean           Run AI files cleanup step')
+  console.log('  platform        Run platform selection step')
+  console.log('  copy            Run content copy step')
+  console.log('  openspec        Run OpenSpec initialization step')
+  console.log('  models          Run models selection step')
+  console.log('  optimization    Run token optimization tools step')
+  console.log('  browser         Run opencode-browser installer step')
+  console.log('  metadata        Write onboarding metadata step')
+  console.log()
+  console.log('Options:')
+  console.log('  -h, --help      Show this help message')
+}
+
+if (process.stdout.isTTY) console.clear()
+console.log()
+const require = createRequire(import.meta.url)
+const { version } = require('../package.json')
+const args = process.argv.slice(2)
+
+if (args.includes('-h') || args.includes('--help')) {
+  printHelp(version)
+  exit()
+}
+
+async function refuseLegacyInstall() {
+  const legacy = await findLegacyInstall()
+  if (!legacy) return false
+
+  console.log(chalk.red('This project was set up by opencode-onboard v1.'))
+  console.log()
+  if (legacy.files.length > 0) console.log(chalk.dim(`  config:  ${legacy.files.join(', ')}`))
+  if (legacy.skills.length > 0) {
+    const shown = legacy.skills.slice(0, 3).join(', ')
+    const rest = legacy.skills.length > 3 ? `, +${legacy.skills.length - 3} more` : ''
+    console.log(chalk.dim(`  skills:  ${shown}${rest}`))
+  }
+  console.log()
+  console.log('agent-harness v2 renamed both the config files and the skill prefix,')
+  console.log('and it does not migrate v1 projects. Continuing would leave the harness')
+  console.log('half-patched without reporting an error.')
+  console.log()
+  console.log('Re-onboard on a clean branch instead:')
+  console.log(chalk.dim('  git switch -c chore/agent-harness'))
+  console.log(chalk.dim('  rm -rf .opencode .agents/skills/ob-*'))
+  console.log(chalk.dim('  npx @plainconceptsplatform/agent-harness'))
+  return true
+}
+
+// Ctrl-C out of an @inquirer prompt throws ExitPromptError; that is a normal
+// cancellation, not a crash, so it must not exit non-zero.
+async function main() {
+  if (await refuseLegacyInstall()) {
+    exit(1)
+    return
+  }
+  if (args.length === 0) {
+    await runWizard(version)
+    return
+  }
+  if (args[0] === 'join') {
+    await runJoin()
+    return
+  }
+  if (args[0] === 'update') {
+    await runUpdate()
+    return
+  }
+  if (!await runSingleCommand(args[0])) {
+    console.log(chalk.red(`Unknown command: ${args[0]}`))
+    console.log()
+    printHelp(version)
+    exit(1)
+  }
+}
+
+try {
+  await main()
+} catch (err) {
+  if (err.name === 'ExitPromptError') {
+    console.log()
+    console.log(chalk.yellow('Cancelled.'))
+  } else {
+    console.error(chalk.red('\nUnexpected error:'), err.message)
+    exit(1)
+  }
+}
+exit()