@plainconceptsplatform/agent-harness 2.0.0

package/src/content/.agents/skills/pc-userstory-az/SKILL.md

@@ -0,0 +1,157 @@
+---
+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}
+```

package/src/content/.agents/skills/pc-userstory-browser/SKILL.md

@@ -0,0 +1,132 @@
+---
+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 opencode-browser extension and openspec CLI.
+metadata:
+  author: copilots
+  version: "1.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 the opencode-browser plugin.
+
+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
+
+- opencode-browser extension installed and running (installed during onboarding)
+- The user must be authenticated to the backlog system in their browser (e.g. logged into Azure DevOps, Jira, Trello, Linear, etc.)
+
+## 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. **Navigate to the URL**
+   ```bash
+   browser_open_tab url="https://the-url-the-user-provided"
+   ```
+
+3. **Wait for the page to load**
+   ```bash
+   browser_wait ms=3000
+   ```
+
+4. **Read the work item content**
+   ```bash
+   browser_query mode="page_text"
+   ```
+
+   Also try to get structured content:
+   ```bash
+   browser_snapshot
+   ```
+   The accessibility snapshot often reveals the work item title, description, and fields more precisely than raw page text.
+
+5. **Parse work item fields**
+
+   From the page text and/or snapshot, 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 longer (`browser_wait ms=5000`)
+   - Use `browser_query` with `mode=page_text` after the wait
+   - Try `browser_snapshot` which may capture more structured content
+
+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 `browser_snapshot` to get structured accessibility tree data
+
+## Rules
+
+- Navigate only to URLs the user explicitly provides. Never guess or browse randomly.
+- The user must already be authenticated in their browser to the backlog system.
+- If the page requires login and the user isn't authenticated, tell them to log in via their browser 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.

package/src/content/.agents/skills/pc-userstory-gh/SKILL.md

@@ -0,0 +1,120 @@
+---
+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}
+```

package/src/content/.agents/skills/pc-userstory-jira/SKILL.md

@@ -0,0 +1,131 @@
+---
+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"
+---
+
+Use `acli` CLI for all Jira operations.
+
+## Atlassian CLI Setup (One-Time)
+
+Install from: https://developer.atlassian.com/cloud/acli/guides/install-acli/
+
+Authenticate:
+```bash
+# Option 1: API token (recommended for CI)
+echo <token> | acli jira auth login --site "<yoursite>.atlassian.net" --email "<email>" --token
+
+# Option 2: OAuth (interactive)
+acli jira auth login --web
+```
+
+Generate API token at: https://id.atlassian.com/manage-profile/security/api-tokens
+
+## Steps
+
+1. **Extract Issue Key** from URL
+   - `https://yoursite.atlassian.net/browse/PROJ-123` -> Key: PROJ-123
+   - `https://yoursite.atlassian.net/jira/core/projects/PROJ/issues/PROJ-123` -> Key: PROJ-123
+   - `https://yoursite.atlassian.net/browse/PROJ-123?filter=123` -> Key: PROJ-123
+   - If the user provides just `PROJ-123` without a URL, use it directly as the key.
+
+2. **Fetch Work Item**
+   ```bash
+   acli jira workitem view --key "PROJ-123"
+   ```
+
+   Parse the output for:
+   - Summary -> title
+   - Description -> proposal context
+   - Acceptance Criteria (if present in description or custom fields) -> spec requirements
+   - Labels -> tags for the OpenSpec change
+   - Status -> current state (e.g. To Do, In Progress, Done)
+   - Assignee -> who requested it
+   - Priority -> complexity hint
+
+3. **Offer to transition the Work Item to In Progress**
+
+   This writes to Jira, so ask first using the `question` tool:
+
+   ```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." }
+         ]
+       }
+     ]
+   }
+   ```
+
+   Only if the user answers `yes` AND the status is currently "To Do" or "Backlog":
+   ```bash
+   acli jira workitem transition --key "PROJ-123" --status "In Progress"
+   ```
+   In unattended runs (`/plan-goal`), skip the question and the transition entirely.
+
+4. **Create OpenSpec Change**
+   ```bash
+   openspec new change "{slug-from-summary}"
+   ```
+
+   Write `proposal.md` with:
+   - Title: the Jira issue summary
+   - Context: mention this is Jira issue `{KEY}`, link back to the URL
+   - Requirements: extracted from description and acceptance criteria
+   - Scope: what's in/out based on the issue
+
+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`.
+
+## Jira URL Patterns
+
+| URL format | Example |
+|------------|---------|
+| Browse URL | `https://yoursite.atlassian.net/browse/PROJ-123` |
+| Issue URL  | `https://yoursite.atlassian.net/jira/core/projects/PROJ/issues/PROJ-123` |
+| Board URL  | `https://yoursite.atlassian.net/jira/software/c/projects/PROJ/boards/1?selectedIssue=PROJ-123` |
+| Direct key | `PROJ-123` |
+
+## Useful Commands
+
+```bash
+# View work item
+acli jira workitem view --key "PROJ-123"
+
+# Transition work item
+acli jira workitem transition --key "PROJ-123" --status "In Progress"
+acli jira workitem transition --key "PROJ-123" --status "Done"
+
+# Search with JQL
+acli jira workitem search --jql "project = PROJ AND status = 'To Do' ORDER BY priority DESC"
+
+# Add a comment
+acli jira workitem comment create --key "PROJ-123" --body "Implementation started"
+```
+
+Jira is a backlog-only platform: it has no code repos or PRs. PR creation and code review use the repo platform (GitHub or Azure DevOps) configured separately.

package/src/content/.opencode/_gitignore

@@ -0,0 +1,7 @@
+node_modules
+harness-run.json
+harness.user.json
+harness-managed.json
+source-roots.json
+tmp/
+*-engineer.*.md

package/src/content/.opencode/commands/init.md

@@ -0,0 +1,5 @@
+---
+description: Initialize the project. Presents a single form with all setup questions, then executes selected steps.
+---
+
+Load the `pc-repo-initialize` skill and follow every step defined in it.

package/src/content/.opencode/commands/make-architecture.md

@@ -0,0 +1,5 @@
+---
+description: Generate or update ARCHITECTURE.md by analyzing the codebase structure. Safe to run at any time.
+---
+
+Load the `pc-make-architecture` skill and follow every step defined in it.

package/src/content/.opencode/commands/make-design.md

@@ -0,0 +1,5 @@
+---
+description: Generate or update DESIGN.md by analyzing the codebase design system. Safe to run at any time.
+---
+
+Load the `pc-make-design` skill and follow every step defined in it.

package/src/content/.opencode/commands/make-engineer.md

@@ -0,0 +1,5 @@
+---
+description: Create a custom engineer agent via persona-driven interactive design
+---
+
+Load the `pc-make-engineer` skill and follow every step defined in it.

package/src/content/.opencode/commands/make-evidence-scaffold.md

@@ -0,0 +1,5 @@
+---
+description: One-time scaffold of a project-specific visual-evidence harness (deterministic capture + assertions + manifest + publisher) that /ops-evidence and /plan-goal delegate to.
+---
+
+Load the `pc-make-evidence-scaffold` skill and follow every step defined in it.

package/src/content/.opencode/commands/make-guardrails.md

@@ -0,0 +1,5 @@
+---
+description: Generate or update a pc-guardrails-project skill from ARCHITECTURE.md and relevant project files.
+---
+
+Load the `pc-make-guardrails` skill and follow every step defined in it.

package/src/content/.opencode/commands/make-user-model.md

@@ -0,0 +1,5 @@
+---
+description: Set the model for a tier (plan, build, or fast). Team-wide or user-local override.
+---
+
+Load the `pc-make-user-model` skill and follow every step defined in it.

package/src/content/.opencode/commands/ops-backlog.md

@@ -0,0 +1,10 @@
+---
+description: Create an issue in the backlog platform (GitHub, Azure DevOps, Jira) from a description.
+---
+
+Backlog platform is set in `.opencode/harness.json` → `platform.backlog`. The platform-specific content below is injected by the CLI during onboarding.
+
+Input: `$ARGUMENTS` (the issue title/description)
+
+<!-- PC-PLATFORM-BACKLOG-START -->
+<!-- PC-PLATFORM-BACKLOG-END -->

package/src/content/.opencode/commands/ops-evidence.md

@@ -0,0 +1,9 @@
+---
+description: Capture a screenshot (or text summary) of a completed change and post it as a comment on the originating issue or work item.
+---
+
+Load the `pc-ops-evidence` skill and execute it.
+
+Input:
+
+$ARGUMENTS

package/src/content/.opencode/commands/ops-review.md

@@ -0,0 +1,8 @@
+---
+description: Read and triage PR review feedback. Reports what needs fixing, does not implement fixes.
+---
+
+Repo platform is set in `.opencode/harness.json` → `platform.repo`. The platform-specific content below is injected by the CLI during onboarding.
+
+<!-- PC-PLATFORM-REVIEW-START -->
+<!-- PC-PLATFORM-REVIEW-END -->

package/src/content/.opencode/commands/ops-ship.md

@@ -0,0 +1,9 @@
+---
+description: Create a pull request for the current feature branch with screenshots if UI changed.
+---
+
+Load the `pc-ops-ship` skill and execute it.
+
+Input:
+
+$ARGUMENTS

package/src/content/.opencode/commands/plan-apply.md

@@ -0,0 +1,9 @@
+---
+description: Implement tasks from a plan: works with OpenSpec proposals and in-conversation plans.
+---
+
+Load the `pc-plan-apply` skill and execute it in **interactive mode** with `start_from: branch` (the full protocol, including branch creation).
+
+Input:
+
+$ARGUMENTS

package/src/content/.opencode/commands/plan-archive.md

@@ -0,0 +1,5 @@
+---
+description: Archive the oldest merged unarchived OpenSpec change and update documentation.
+---
+
+Load the `pc-plan-archive` skill and execute it in **interactive mode**. No input required.

package/src/content/.opencode/commands/plan-explore.md

@@ -0,0 +1,9 @@
+---
+description: Think through an idea, investigate a problem, or clarify requirements before creating a change.
+---
+
+Load the `pc-plan-explore` skill and execute it in **interactive mode**.
+
+Input:
+
+$ARGUMENTS

package/src/content/.opencode/commands/plan-goal.md

@@ -0,0 +1,5 @@
+---
+description: Autonomous pipeline: explore, propose, apply, archive, then merge/PR/push. For loop-engineering.
+---
+
+Load the `pc-plan-goal` skill and follow every step defined in it.

package/src/content/.opencode/commands/plan-propose.md

@@ -0,0 +1,9 @@
+---
+description: Parse a work item or idea and propose a change plan with enriched task assignments.
+---
+
+Load the `pc-plan-propose` skill and execute it in **interactive mode**.
+
+Input:
+
+$ARGUMENTS