@plainconceptsplatform/agent-harness 3.8.2 → 3.9.0

package/skills/pc-userstory-az/SKILL.md

@@ -1,71 +1,71 @@
----
-name: pc-userstory
-description: Parse Azure DevOps user story URL and create OpenSpec change. Use when user provides an Azure DevOps URL.
-license: MIT
-compatibility: Requires openspec CLI and Azure CLI.
-metadata:
-  author: copilots
-  version: "3.1"
----
-
-Turn an Azure DevOps work item URL into an OpenSpec change, then hand the change to `pc-plan-propose`.
-
-## Rules
-
-- Work item data comes from `az`, never from a page fetch or a browser (denied by `pc-system-reminders`). An `az` that cannot reach the org is a blocker to report.
-- Never load `pc-plan-apply` until the user has said yes.
-
-## Contracts
-
-The ID is in the URL: `?workitem=193208` or `/workitems/edit/193208` both give `193208`.
-
-```bash
-az boards work-item show --id 193208
-```
-
-That relies on the configured defaults, which is the one piece of setup this skill needs:
-
-```bash
-az devops configure --defaults organization=https://dev.azure.com/{org} project={project}
-```
-
-Without them every command needs `--organization`. A PAT with Work Items (Read and Write) and Code (Read and Write) comes from `https://dev.azure.com/{org}/_usersSettings/tokens`.
-
-From the JSON take `fields.System.Title`, `fields.System.Description` (often HTML, strip the tags), `fields.System.WorkItemType`, `fields.System.IterationPath`, `fields.System.State` and `fields.System.AcceptanceCriteria` when it is there.
-
-```bash
-openspec new change "us-{id}-{slug}"
-```
-
-Screenshots live in the change folder, `openspec/changes/{change-name}/images/{name}.png`. Embedding one uses the `_apis/git/repositories` URL, since `_git/` returns HTML: `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`
-
-Report:
-
-```
-## User Story Parsed
-
-Work Item: #{id}
-Title: {title}
-Type: User Story
-Iteration: {sprint}
-State: {state}
-
-Change Created: us-{id}-{slug}
-```
-
-Then load `pc-plan-propose` (interactive) and, once it returns, ask:
-
-```json
-{
-  "questions": [
-    {
-      "header": "Ready to implement",
-      "question": "Ready to implement?",
-      "options": [
-        { "label": "yes", "description": "Load the pc-plan-apply skill to start implementation." },
-        { "label": "no", "description": "Stop here. You can run /plan-apply later." }
-      ]
-    }
-  ]
-}
-```
+---
+name: pc-userstory
+description: Parse Azure DevOps user story URL and create OpenSpec change. Use when user provides an Azure DevOps URL.
+license: MIT
+compatibility: Requires openspec CLI and Azure CLI.
+metadata:
+  author: copilots
+  version: "3.1"
+---
+
+Turn an Azure DevOps work item URL into an OpenSpec change, then hand the change to `pc-plan-propose`.
+
+## Rules
+
+- Work item data comes from `az`, never from a page fetch or a browser (denied by `pc-system-reminders`). An `az` that cannot reach the org is a blocker to report.
+- Never load `pc-plan-apply` until the user has said yes.
+
+## Contracts
+
+The ID is in the URL: `?workitem=193208` or `/workitems/edit/193208` both give `193208`.
+
+```bash
+az boards work-item show --id 193208
+```
+
+That relies on the configured defaults, which is the one piece of setup this skill needs:
+
+```bash
+az devops configure --defaults organization=https://dev.azure.com/{org} project={project}
+```
+
+Without them every command needs `--organization`. A PAT with Work Items (Read and Write) and Code (Read and Write) comes from `https://dev.azure.com/{org}/_usersSettings/tokens`.
+
+From the JSON take `fields.System.Title`, `fields.System.Description` (often HTML, strip the tags), `fields.System.WorkItemType`, `fields.System.IterationPath`, `fields.System.State` and `fields.System.AcceptanceCriteria` when it is there.
+
+```bash
+openspec new change "us-{id}-{slug}"
+```
+
+Screenshots live in the change folder, `openspec/changes/{change-name}/images/{name}.png`. Embedding one uses the `_apis/git/repositories` URL, since `_git/` returns HTML: `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`
+
+Report:
+
+```
+## User Story Parsed
+
+Work Item: #{id}
+Title: {title}
+Type: User Story
+Iteration: {sprint}
+State: {state}
+
+Change Created: us-{id}-{slug}
+```
+
+Then load `pc-plan-propose` (interactive) and, once it returns, ask:
+
+```json
+{
+  "questions": [
+    {
+      "header": "Ready to implement",
+      "question": "Ready to implement?",
+      "options": [
+        { "label": "yes", "description": "Load the pc-plan-apply skill to start implementation." },
+        { "label": "no", "description": "Stop here. You can run /plan-apply later." }
+      ]
+    }
+  ]
+}
+```

package/skills/pc-userstory-browser/SKILL.md

@@ -1,64 +1,64 @@
----
-name: pc-userstory
-description: Parse work item from any URL using browser automation. Use when user provides a URL that doesn't match GitHub/Azure/Jira CLI platforms, or when backlog platform is 'browser'.
-license: MIT
-compatibility: Requires agent-browser CLI installed and openspec CLI.
-metadata:
-  author: copilots
-  version: "2.0"
----
-
-Read a work item off its own web page, for a backlog with no CLI, then hand the change to `pc-plan-propose`. This is the fallback: a GitHub, Azure DevOps or Jira URL belongs to the CLI skill for that platform, which is faster and cannot misread a page.
-
-Browser is a backlog-only platform. Shipping runs on whichever repo platform the project configured.
-
-## Rules
-
-- Navigate only to a URL the user gave you. This skill is the one exception to `browser-automation`'s ban on leaving localhost, and it is that narrow on purpose: a work-item page is behind the user's own login, and anything else reachable from it is too.
-- Read only. No clicking, no status changes, nothing written back to the tracker.
-- Always reuse the `backlog` session so the login survives; a login page instead of the work item means the session is not authenticated, and the user has to log in manually in the opened window before a retry.
-
-## Contracts
-
-`agent-browser` runs its own Chrome, not the user's daily browser, and keeps state per session:
-
-```bash
-agent-browser --session backlog --restore open "https://the-url-the-user-provided"
-agent-browser wait --load networkidle
-agent-browser snapshot
-```
-
-`agent-browser doctor` verifies the install. The accessibility tree from `snapshot` locates fields more reliably than page text; `agent-browser read` and `agent-browser get text "h1"` fill the gaps, and `agent-browser get url` confirms the page did not navigate away. A single-page app that renders after idle needs a second wait (`--text "<known heading>"` when a stable string exists) and a fresh snapshot, not a sleep.
-
-Take the title, description with its acceptance criteria or definition of done, the ID from the URL or the page, and status, assignee, priority and labels when they are visible. Where to look, by tool:
-
-| Tool | Work item URL | Title | Description |
-|---|---|---|---|
-| Azure DevOps | `/_workitems/edit/{id}` | header | "Description" and "Acceptance Criteria" sections |
-| Linear | `/{team}/issue/{key}` | issue title | issue body |
-| Jira | `/browse/{key}` | summary | description field |
-| Trello | `/c/{short-id}` | card title | card description |
-| Anything else | as given | `<h1>` or page title | main content area |
-
-Then create the change, whose `proposal.md` names the source URL and the work item ID:
-
-```bash
-openspec new change "{slug-from-title}"
-```
-
-Load `pc-plan-propose` (interactive) and, once it returns, ask:
-
-```json
-{
-  "questions": [
-    {
-      "header": "Ready to implement",
-      "question": "Ready to implement?",
-      "options": [
-        { "label": "yes", "description": "Load the pc-plan-apply skill to start implementation." },
-        { "label": "no", "description": "Stop here. You can run /plan-apply later." }
-      ]
-    }
-  ]
-}
-```
+---
+name: pc-userstory
+description: Parse work item from any URL using browser automation. Use when user provides a URL that doesn't match GitHub/Azure/Jira CLI platforms, or when backlog platform is 'browser'.
+license: MIT
+compatibility: Requires agent-browser CLI installed and openspec CLI.
+metadata:
+  author: copilots
+  version: "2.0"
+---
+
+Read a work item off its own web page, for a backlog with no CLI, then hand the change to `pc-plan-propose`. This is the fallback: a GitHub, Azure DevOps or Jira URL belongs to the CLI skill for that platform, which is faster and cannot misread a page.
+
+Browser is a backlog-only platform. Shipping runs on whichever repo platform the project configured.
+
+## Rules
+
+- Navigate only to a URL the user gave you. This skill is the one exception to `browser-automation`'s ban on leaving localhost, and it is that narrow on purpose: a work-item page is behind the user's own login, and anything else reachable from it is too.
+- Read only. No clicking, no status changes, nothing written back to the tracker.
+- Always reuse the `backlog` session so the login survives; a login page instead of the work item means the session is not authenticated, and the user has to log in manually in the opened window before a retry.
+
+## Contracts
+
+`agent-browser` runs its own Chrome, not the user's daily browser, and keeps state per session:
+
+```bash
+agent-browser --session backlog --restore open "https://the-url-the-user-provided"
+agent-browser wait --load networkidle
+agent-browser snapshot
+```
+
+`agent-browser doctor` verifies the install. The accessibility tree from `snapshot` locates fields more reliably than page text; `agent-browser read` and `agent-browser get text "h1"` fill the gaps, and `agent-browser get url` confirms the page did not navigate away. A single-page app that renders after idle needs a second wait (`--text "<known heading>"` when a stable string exists) and a fresh snapshot, not a sleep.
+
+Take the title, description with its acceptance criteria or definition of done, the ID from the URL or the page, and status, assignee, priority and labels when they are visible. Where to look, by tool:
+
+| Tool | Work item URL | Title | Description |
+|---|---|---|---|
+| Azure DevOps | `/_workitems/edit/{id}` | header | "Description" and "Acceptance Criteria" sections |
+| Linear | `/{team}/issue/{key}` | issue title | issue body |
+| Jira | `/browse/{key}` | summary | description field |
+| Trello | `/c/{short-id}` | card title | card description |
+| Anything else | as given | `<h1>` or page title | main content area |
+
+Then create the change, whose `proposal.md` names the source URL and the work item ID:
+
+```bash
+openspec new change "{slug-from-title}"
+```
+
+Load `pc-plan-propose` (interactive) and, once it returns, ask:
+
+```json
+{
+  "questions": [
+    {
+      "header": "Ready to implement",
+      "question": "Ready to implement?",
+      "options": [
+        { "label": "yes", "description": "Load the pc-plan-apply skill to start implementation." },
+        { "label": "no", "description": "Stop here. You can run /plan-apply later." }
+      ]
+    }
+  ]
+}
+```

package/skills/pc-userstory-gh/SKILL.md

@@ -1,63 +1,63 @@
----
-name: pc-userstory
-description: Parse GitHub Issue URL and create OpenSpec change. Use when user provides a GitHub Issue URL.
-license: MIT
-compatibility: Requires openspec CLI and gh CLI.
-metadata:
-  author: copilots
-  version: "1.1"
----
-
-Turn a GitHub Issue URL into an OpenSpec change, then hand the change to `pc-plan-propose`.
-
-## Rules
-
-- Issue data comes from `gh`, never from a page fetch (denied by `pc-system-reminders`). An unavailable or unauthenticated `gh` is a blocker to report: `gh auth status` says which.
-- Always pass `--repo {owner}/{repo}`. Git context resolves to the wrong repository in a fork or a worktree, and the failure looks like a missing issue.
-- Never load `pc-plan-apply` until the user has said yes.
-
-## Contracts
-
-`https://github.com/{owner}/{repo}/issues/42` gives owner, repo and number `42`.
-
-```bash
-gh issue view 42 --repo {owner}/{repo} --json number,title,body,labels,milestone,state
-```
-
-An auth error or a 404 here is the blocker; do not work around it. From the JSON take `number`, `title`, `body` (description and acceptance criteria), `labels`, `milestone` and `state`.
-
-```bash
-openspec new change "gh-{number}-{slug}"
-```
-
-Screenshots live in the change folder, `openspec/changes/{change-name}/images/{name}.png`, and embed as a blob URL pinned to a commit SHA with `?raw=true`: `https://github.com/{owner}/{repo}/blob/{sha}/openspec/changes/{change}/images/{file}.png?raw=true`.
-
-Report:
-
-```
-## Issue Parsed
-
-Issue: #{number}
-Title: {title}
-State: {state}
-Milestone: {milestone}
-
-Change Created: gh-{number}-{slug}
-```
-
-Then load `pc-plan-propose` (interactive) and, once it returns, ask:
-
-```json
-{
-  "questions": [
-    {
-      "header": "Ready to implement",
-      "question": "Ready to implement?",
-      "options": [
-        { "label": "yes", "description": "Load the pc-plan-apply skill to start implementation." },
-        { "label": "no", "description": "Stop here. You can run /plan-apply later." }
-      ]
-    }
-  ]
-}
-```
+---
+name: pc-userstory
+description: Parse GitHub Issue URL and create OpenSpec change. Use when user provides a GitHub Issue URL.
+license: MIT
+compatibility: Requires openspec CLI and gh CLI.
+metadata:
+  author: copilots
+  version: "1.1"
+---
+
+Turn a GitHub Issue URL into an OpenSpec change, then hand the change to `pc-plan-propose`.
+
+## Rules
+
+- Issue data comes from `gh`, never from a page fetch (denied by `pc-system-reminders`). An unavailable or unauthenticated `gh` is a blocker to report: `gh auth status` says which.
+- Always pass `--repo {owner}/{repo}`. Git context resolves to the wrong repository in a fork or a worktree, and the failure looks like a missing issue.
+- Never load `pc-plan-apply` until the user has said yes.
+
+## Contracts
+
+`https://github.com/{owner}/{repo}/issues/42` gives owner, repo and number `42`.
+
+```bash
+gh issue view 42 --repo {owner}/{repo} --json number,title,body,labels,milestone,state
+```
+
+An auth error or a 404 here is the blocker; do not work around it. From the JSON take `number`, `title`, `body` (description and acceptance criteria), `labels`, `milestone` and `state`.
+
+```bash
+openspec new change "gh-{number}-{slug}"
+```
+
+Screenshots live in the change folder, `openspec/changes/{change-name}/images/{name}.png`, and embed as a blob URL pinned to a commit SHA with `?raw=true`: `https://github.com/{owner}/{repo}/blob/{sha}/openspec/changes/{change}/images/{file}.png?raw=true`.
+
+Report:
+
+```
+## Issue Parsed
+
+Issue: #{number}
+Title: {title}
+State: {state}
+Milestone: {milestone}
+
+Change Created: gh-{number}-{slug}
+```
+
+Then load `pc-plan-propose` (interactive) and, once it returns, ask:
+
+```json
+{
+  "questions": [
+    {
+      "header": "Ready to implement",
+      "question": "Ready to implement?",
+      "options": [
+        { "label": "yes", "description": "Load the pc-plan-apply skill to start implementation." },
+        { "label": "no", "description": "Stop here. You can run /plan-apply later." }
+      ]
+    }
+  ]
+}
+```

package/skills/pc-userstory-jira/SKILL.md

@@ -1,74 +1,74 @@
----
-name: pc-userstory
-description: Parse a Jira work item and create an OpenSpec change. Use when the user provides a Jira URL or a bare issue key (e.g. PROJ-123).
-license: MIT
-compatibility: Requires openspec CLI and Atlassian CLI (acli).
-metadata:
-  author: copilots
-  version: "1.0"
----
-
-Turn a Jira issue into an OpenSpec change, then hand the change to `pc-plan-propose`. Jira is backlog-only: it has no repositories and no pull requests, so shipping runs on whichever repo platform the project configured.
-
-## Rules
-
-- Issue data comes from `acli`, never from a page fetch or a browser (denied by `pc-system-reminders`). An `acli` that cannot authenticate is a blocker to report; install and login are documented at https://developer.atlassian.com/cloud/acli/guides/install-acli/.
-- Never transition the work item without asking, and never transition one that is not in `To Do` or `Backlog`. Moving somebody's ticket is visible to their whole team.
-- In an unattended run, skip the question and the transition rather than resolving it yes.
-- Never load `pc-plan-apply` until the user has said yes.
-
-## Contracts
-
-The key is `PROJ-123`, taken from `/browse/PROJ-123`, `/jira/core/projects/PROJ/issues/PROJ-123`, `?selectedIssue=PROJ-123`, or given bare.
-
-```bash
-acli jira workitem view --key "PROJ-123"
-```
-
-From the output take the summary (title), the description (context), acceptance criteria wherever they live (spec requirements), labels, status, assignee and priority.
-
-```bash
-acli jira workitem transition --key "PROJ-123" --status "In Progress"
-```
-
-Ask before that one:
-
-```json
-{
-  "questions": [
-    {
-      "header": "Transition work item",
-      "question": "Move {KEY} to In Progress?",
-      "options": [
-        { "label": "yes", "description": "Transition the work item to In Progress." },
-        { "label": "no", "description": "Skip the transition." }
-      ]
-    }
-  ]
-}
-```
-
-Then create the change, whose `proposal.md` names the Jira key and links back to it:
-
-```bash
-openspec new change "{slug-from-summary}"
-```
-
-Load `pc-plan-propose` (interactive) and, once it returns, ask:
-
-```json
-{
-  "questions": [
-    {
-      "header": "Ready to implement",
-      "question": "Ready to implement?",
-      "options": [
-        { "label": "yes", "description": "Load the pc-plan-apply skill to start implementation." },
-        { "label": "no", "description": "Stop here. You can run /plan-apply later." }
-      ]
-    }
-  ]
-}
-```
-
-Also available: `acli jira workitem search --jql "..."` and `acli jira workitem comment create --key "PROJ-123" --body "..."`.
+---
+name: pc-userstory
+description: Parse a Jira work item and create an OpenSpec change. Use when the user provides a Jira URL or a bare issue key (e.g. PROJ-123).
+license: MIT
+compatibility: Requires openspec CLI and Atlassian CLI (acli).
+metadata:
+  author: copilots
+  version: "1.0"
+---
+
+Turn a Jira issue into an OpenSpec change, then hand the change to `pc-plan-propose`. Jira is backlog-only: it has no repositories and no pull requests, so shipping runs on whichever repo platform the project configured.
+
+## Rules
+
+- Issue data comes from `acli`, never from a page fetch or a browser (denied by `pc-system-reminders`). An `acli` that cannot authenticate is a blocker to report; install and login are documented at https://developer.atlassian.com/cloud/acli/guides/install-acli/.
+- Never transition the work item without asking, and never transition one that is not in `To Do` or `Backlog`. Moving somebody's ticket is visible to their whole team.
+- In an unattended run, skip the question and the transition rather than resolving it yes.
+- Never load `pc-plan-apply` until the user has said yes.
+
+## Contracts
+
+The key is `PROJ-123`, taken from `/browse/PROJ-123`, `/jira/core/projects/PROJ/issues/PROJ-123`, `?selectedIssue=PROJ-123`, or given bare.
+
+```bash
+acli jira workitem view --key "PROJ-123"
+```
+
+From the output take the summary (title), the description (context), acceptance criteria wherever they live (spec requirements), labels, status, assignee and priority.
+
+```bash
+acli jira workitem transition --key "PROJ-123" --status "In Progress"
+```
+
+Ask before that one:
+
+```json
+{
+  "questions": [
+    {
+      "header": "Transition work item",
+      "question": "Move {KEY} to In Progress?",
+      "options": [
+        { "label": "yes", "description": "Transition the work item to In Progress." },
+        { "label": "no", "description": "Skip the transition." }
+      ]
+    }
+  ]
+}
+```
+
+Then create the change, whose `proposal.md` names the Jira key and links back to it:
+
+```bash
+openspec new change "{slug-from-summary}"
+```
+
+Load `pc-plan-propose` (interactive) and, once it returns, ask:
+
+```json
+{
+  "questions": [
+    {
+      "header": "Ready to implement",
+      "question": "Ready to implement?",
+      "options": [
+        { "label": "yes", "description": "Load the pc-plan-apply skill to start implementation." },
+        { "label": "no", "description": "Stop here. You can run /plan-apply later." }
+      ]
+    }
+  ]
+}
+```
+
+Also available: `acli jira workitem search --jql "..."` and `acli jira workitem comment create --key "PROJ-123" --body "..."`.