@plainconceptsplatform/agent-harness 2.4.1 → 2.5.0

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

@@ -1,157 +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"
----
-
-Use `az` CLI for all Azure DevOps operations. Browser MCP tools are out of scope for this skill.
-
-## Azure CLI Setup (One-Time)
-
-```bash
-az config set extension.dynamic_install_allow_preview=true
-az extension add --name azure-devops
-az login
-az devops login --organization https://dev.azure.com/{org}
-az devops configure --defaults organization=https://dev.azure.com/{org} project={project}
-```
-
-The `configure --defaults` line is required: every command below relies on the default org/project instead of passing `--organization`.
-
-PAT Token: go to `https://dev.azure.com/{org}/_usersSettings/tokens`. Create with scopes: Work Items (Read and Write) and Code (Read and Write).
-
-## Steps
-
-1. **Extract Work Item ID** from URL
-   - `?workitem=193208` -> ID: 193208
-   - `/workitems/edit/193208` -> ID: 193208
-
-2. **Fetch Work Item**
-   ```bash
-   az boards work-item show --id 193208
-   ```
-   Uses the default org, no `--organization` flag needed.
-
-3. **Extract Key Fields** from JSON response:
-   - `fields.System.Title` -> Title
-   - `fields.System.Description` -> Description (may be HTML, strip tags)
-   - `fields.System.WorkItemType` -> Type
-   - `fields.System.IterationPath` -> Sprint
-   - `fields.System.State` -> State
-   - `fields.System.AcceptanceCriteria` -> AC (if present)
-
-4. **Create OpenSpec Change**
-   ```bash
-   openspec new change "us-{id}-{slug}"
-   ```
-
-5. **Hand off to proposal.** Load the `pc-plan-propose` skill (interactive mode) to generate the proposal, specs, and tasks. After it completes, call the `question` tool:
-
-   ```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." }
-         ]
-       }
-     ]
-   }
-   ```
-
-   Wait for confirmation before loading `pc-plan-apply`.
-
-## Full Azure DevOps CLI Reference
-
-### Work Items
-```bash
-# Read work item
-az boards work-item show --id <id>
-
-# Update work item state
-az boards work-item update --id <id> --state "Active"
-```
-
-### PR Threads (Comments)
-```bash
-# Read all threads
-az devops invoke \
-  --area git --resource pullRequestThreads \
-  --route-parameters project={project} repositoryId=<repo> pullRequestId=<id> \
-  --http-method GET --api-version 7.1
-
-# Post new comment thread (requires body.json)
-az devops invoke \
-  --area git --resource pullRequestThreads \
-  --route-parameters project={project} repositoryId=<repo> pullRequestId=<id> \
-  --http-method POST --api-version 7.1 --in-file body.json
-
-# Reply to existing thread
-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
-```
-
-### Comment Body JSON format
-```json
-{
-  "comments": [
-    {
-      "parentCommentId": 0,
-      "content": "Your markdown comment here.",
-      "commentType": 1
-    }
-  ],
-  "status": "active"
-}
-```
-
-For replies, `parentCommentId` should be the ID of the first comment in the thread (usually 1).
-
-## Screenshot / Image Strategy
-
-Save to openspec change folder and reference via raw URL. Use `_apis/git/repositories` URLs (not `_git/`, which return HTML):
-
-```
-openspec/changes/{change-name}/images/{screenshot}.png
-```
-
-Raw URL format (renders inline in PR comments):
-```
-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
-```
-
-## URL Formats Reference
-
-```
-# Sprint board with work item
-https://dev.azure.com/{org}/{project}/_sprints/backlog/{team}/{project}/Sprint%20110?workitem=193208
-
-# Direct work item
-https://dev.azure.com/{org}/{project}/_workitems/edit/193208
-
-# PR
-https://dev.azure.com/{org}/{project}/_git/{repo}/pullrequest/{pr-id}
-```
-
-## Output Format
-
-```
-## User Story Parsed
-
-Work Item: #{id}
-Title: {title}
-Type: User Story
-Iteration: {sprint}
-State: {state}
-
-Change Created: us-{id}-{slug}
-```
+---
+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/harness/.agents/skills/pc-userstory-browser/SKILL.md

@@ -8,129 +8,57 @@ metadata:
   version: "2.0"
 ---
 
-This skill is used when the backlog platform is set to "Others (Browser)": when there is no CLI integration for the backlog system, or the user doesn't have API tokens. Work items are read directly from the web page using agent-browser.
+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.
 
-This skill overrides the `browser-automation` skill's external navigation restriction, but only for URLs the user explicitly provides as work items. Navigate only to URLs the user gives you.
-
-## Prerequisites
-
-- agent-browser installed (installed during onboarding) — verify with `agent-browser doctor`
-- An authenticated session for the backlog system:
-  - agent-browser runs its own Chrome, not the user's daily browser. Login state persists per session via `--session <slug> --restore`: log in once, and later runs restore cookies automatically.
-  - On first use, the user logs in manually in the opened window; state is saved on close and auto-restored afterwards.
-
-## Steps
-
-1. **Extract the URL** from the user's message
-   - The user provides a direct URL to a work item, issue, ticket, or PBI
-   - Examples: `https://dev.azure.com/org/project/_workitems/edit/123`, `https://linear.app/team/issue/ENG-123`, `https://trello.com/c/abc123`, `https://your-tool.com/ticket/456`
-
-2. **Open the URL in a persistent session**
-   ```bash
-   agent-browser --session backlog --restore open "https://the-url-the-user-provided"
-   ```
-
-3. **Wait for the page to load**
-   ```bash
-   agent-browser wait --load networkidle
-   ```
-   Prefer load-state waits over fixed sleeps; for SPAs that render after idle, add `agent-browser wait --text "<known heading>"` when a stable string is known.
-
-4. **Read the work item content**
-   ```bash
-   agent-browser snapshot
-   ```
-   The accessibility tree with `@ref` handles usually reveals the work item title, description, and fields more precisely than raw page text. Also useful:
-   ```bash
-   agent-browser read           # agent-readable text of the active tab
-   agent-browser get text "h1"  # the heading, when present
-   ```
-
-5. **Parse work item fields**
-
-   From the snapshot and/or text, extract:
-   - Title/Summary: usually the main heading or the `<h1>` / page title
-   - Description: the body text, acceptance criteria, or "Definition of Done" section
-   - ID/Key: the work item ID from the URL or page (e.g. `123`, `ENG-123`)
-   - Status: if visible (e.g. "To Do", "In Progress", "Active")
-   - Assignee: if visible
-   - Priority: if visible
-   - Labels/Tags: if visible
-
-   If the page is a SPA that loads content dynamically:
-   - Wait for load state again (`agent-browser wait --load networkidle`)
-   - Take a fresh `snapshot` after the wait
-   - `agent-browser get url` confirms you are still on the work item
-
-   If a login page appears instead, the session is not authenticated: tell the user to log in manually in the opened browser window, then retry from step 2 with the same `--session backlog --restore` (the login is saved for future runs).
-
-6. **Create OpenSpec Change**
-   ```bash
-   openspec new change "{slug-from-title}"
-   ```
-
-   Write `proposal.md` with:
-   - Title: the work item title from the page
-   - Context: mention the source URL and the work item ID
-   - Requirements: extracted from description and acceptance criteria
-   - Scope: what's in/out based on the ticket
-
-7. **Hand off to proposal.** Load the `pc-plan-propose` skill (interactive mode) to generate the proposal, specs, and tasks. After it completes, call the `question` tool:
-
-   ```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." }
-         ]
-       }
-     ]
-   }
-   ```
-
-   Wait for confirmation before loading `pc-plan-apply`.
-
-## Working with common backlog tools
-
-### Azure DevOps (browser fallback)
-- URL: `https://dev.azure.com/{org}/{project}/_workitems/edit/{id}`
-- Title: visible in the work item header
-- Description: "Description" field section
-- Acceptance Criteria: "Acceptance Criteria" field section
-- State: visible in the top-right area
-
-### Linear
-- URL: `https://linear.app/{team}/issue/{key}`
-- Title: the issue title
-- Description: the issue body
-- Status: visible as a dropdown
-
-### Jira (browser fallback)
-- URL: `https://yoursite.atlassian.net/browse/{key}`
-- Title: the issue summary
-- Description: the description field
-- Status: visible in the status badge
-
-### Trello
-- URL: `https://trello.com/c/{short-id}`
-- Title: the card title
-- Description: the card description
-- Labels: visible as colored badges
-
-### Other tools (generic)
-- Look for `<h1>` or page title for the work item title
-- Look for the main content area for description
-- Use `agent-browser snapshot` to get structured accessibility tree data
+Browser is a backlog-only platform. Shipping runs on whichever repo platform the project configured.
 
 ## Rules
 
-- Navigate only to URLs the user explicitly provide. Never guess or browse randomly.
-- Reuse the `backlog` session (`--session backlog --restore`) so login state persists across runs.
-- If the page requires login and the session is not authenticated, tell them to log in via the opened browser window and retry.
-- For GitHub/Azure/Jira URLs when the CLI is configured for those platforms, use the CLI-based skill instead (faster, more reliable, no browser needed).
-- This skill is read-only: no clicking buttons, no changing status.
-- Browser is a backlog-only platform: it has no PR or repo integration. PR creation uses the repo platform configured separately.
+- 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/harness/.agents/skills/pc-userstory-gh/SKILL.md

@@ -1,120 +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"
----
-
-Use `gh` CLI for all GitHub operations. If `gh` is unavailable, report it as a blocker.
-
-## GitHub CLI Setup (One-Time)
-
-```bash
-gh auth login
-# Follow prompts, authenticate via browser or token
-```
-
-Verify:
-```bash
-gh auth status
-```
-
-## Steps
-
-1. **Extract owner, repo, and issue number** from URL
-   - `https://github.com/{owner}/{repo}/issues/42` -> owner: `{owner}`, repo: `{repo}`, number: `42`
-
-2. **Fetch Issue**, always pass `--repo` explicitly:
-   ```bash
-   gh issue view 42 --repo {owner}/{repo} --json number,title,body,labels,milestone,state
-   ```
-   If this returns an auth error or 404, report as a blocker.
-
-3. **Extract Key Fields** from JSON response:
-   - `number` -> Issue number
-   - `title` -> Title
-   - `body` -> Description / acceptance criteria
-   - `labels` -> Labels
-   - `milestone` -> Milestone / sprint equivalent
-   - `state` -> State (open/closed)
-
-4. **Create OpenSpec Change**
-   ```bash
-   openspec new change "gh-{number}-{slug}"
-   ```
-
-5. **Hand off to proposal.** Load the `pc-plan-propose` skill (interactive mode) to generate the proposal, specs, and tasks. After it completes, call the `question` tool:
-
-   ```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." }
-         ]
-       }
-     ]
-   }
-   ```
-
-   Wait for confirmation before loading `pc-plan-apply`.
-
-## Full GitHub CLI Reference
-
-Always pass `--repo {owner}/{repo}`, relying on git context is unreliable.
-
-### Issues
-```bash
-# Read issue
-gh issue view <number> --repo {owner}/{repo}
-
-# List open issues
-gh issue list --repo {owner}/{repo} --state open --limit 10
-
-# Update issue
-gh issue edit <number> --repo {owner}/{repo} --add-label "in-progress"
-```
-
-## Screenshot / Image Strategy
-
-Save to openspec change folder and reference via GitHub blob URL pinned to commit SHA. Keep `?raw=true` when embedding in markdown:
-
-```
-openspec/changes/{change-name}/images/{screenshot}.png
-```
-
-```
-https://github.com/{owner}/{repo}/blob/{sha}/openspec/changes/{change}/images/{file}.png?raw=true
-```
-
-## URL Formats Reference
-
-```
-# Issue
-https://github.com/{owner}/{repo}/issues/{number}
-
-# PR
-https://github.com/{owner}/{repo}/pull/{number}
-
-# Blob file
-https://github.com/{owner}/{repo}/blob/{sha}/{path}
-```
-
-## Output Format
-
-```
-## Issue Parsed
-
-Issue: #{number}
-Title: {title}
-State: {state}
-Milestone: {milestone}
-
-Change Created: gh-{number}-{slug}
-```
+---
+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." }
+      ]
+    }
+  ]
+}
+```