@plainconceptsplatform/agent-harness 3.3.1 → 3.4.1

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

@@ -1,63 +1,63 @@
-Azure DevOps data comes from the `az` CLI; a page fetch of dev.azure.com is denied (pc-system-reminders). If `az` is unavailable, report it as a blocker.
-
----
-
-### 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
-    }
-  ]
-}
-```
-
+Azure DevOps data comes from the `az` CLI; a page fetch of dev.azure.com is denied (pc-system-reminders). If `az` is unavailable, report it as a blocker.
+
+---
+
+### 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/cli/fragments/ops-review/gh.md

@@ -1,52 +1,52 @@
-GitHub data comes from the `gh` CLI; a page fetch of github.com is denied (pc-system-reminders). If `gh` is unavailable, report it 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."
-```
-
+GitHub data comes from the `gh` CLI; a page fetch of github.com is denied (pc-system-reminders). If `gh` is unavailable, report it 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/cli/fragments/ops-review/gl.md

@@ -1,56 +1,56 @@
-GitLab data comes from the `glab` CLI; a page fetch of gitlab.com is denied (pc-system-reminders). If `glab` is unavailable, report it 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.
-
+GitLab data comes from the `glab` CLI; a page fetch of gitlab.com is denied (pc-system-reminders). If `glab` is unavailable, report it 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/cli/fragments/ops-ship/gh.md

@@ -1,68 +1,68 @@
-GitHub data comes from the `gh` CLI; a page fetch of github.com is denied (pc-system-reminders). If `gh` is unavailable, report it 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 the paths you actually changed; unscoped staging is denied (`pc-system-reminders`):
-
-```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})'
-```
-
+GitHub data comes from the `gh` CLI; a page fetch of github.com is denied (pc-system-reminders). If `gh` is unavailable, report it 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 the paths you actually changed; unscoped staging is denied (`pc-system-reminders`):
+
+```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/cli/fragments/ops-ship/gl.md

@@ -1,85 +1,85 @@
-GitLab data comes from the `glab` CLI; a page fetch of gitlab.com is denied (pc-system-reminders). If `glab` is unavailable, report it 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 the paths you actually changed; unscoped staging is denied (`pc-system-reminders`):
-
-```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}
-```
-
+GitLab data comes from the `glab` CLI; a page fetch of gitlab.com is denied (pc-system-reminders). If `glab` is unavailable, report it 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 the paths you actually changed; unscoped staging is denied (`pc-system-reminders`):
+
+```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}
+```
+
 ---