@plainconceptsplatform/agent-harness 2.3.0 → 2.4.1

package/{src/content → harness}/.agents/skills/pc-make-engineer/template.md

@@ -1,80 +1,80 @@
-# Agent file template
-
-The agent file is exactly this structure: frontmatter plus one identity paragraph plus the `## Abilities` section. No other sections. No other content.
-
-```markdown
----
-description: <one sentence naming the persona + top 3-5 detected technologies>
-mode: subagent
-permission:
-  edit: allow
-  bash: allow
-  read: allow
-  glob: allow
-  grep: allow
----
-
-<One paragraph: "You are a {persona} engineer specializing in {top technologies}. You own all work in {scope/files}." Keep it to 2-3 sentences max.>
-
-## Abilities
-- Guardrails: @pc-guardrails-generic, @pc-guardrails-project
-- Development: <@installed-skill-1>, <@installed-skill-2>, ...
-- Testing: <@installed-skill-for-testing>, ...
-- Infrastructure: <@installed-skill-for-devops>, ...
-```
-
-That is the entire file: frontmatter, one identity paragraph, and the `## Abilities` section. The always-installed `pc-system-reminders` plugin loads the listed skills for every session. Replace every `<...>` placeholder with real values from your research. Remove any ability category line that has no skills assigned (besides Guardrails which is always present).
-
-## Description quality bar
-
-The `description:` field is the matching key for `/plan-apply`. The lead compares task domain text against agent descriptions to pick the right specialist. A weak description means the wrong engineer gets spawned.
-
-Bad: `"A frontend engineer for React"`
-Good: `"Frontend engineer for Ink 7 + React 19 TUI, FSD architecture, Inversify DI, design tokens, and i18n"`
-
-Rules:
-- Name the persona explicitly
-- List the top 3-5 detected technologies from Step 2
-- One sentence, no padding
-
-## Identity paragraph
-
-The identity paragraph sits between frontmatter and `## Abilities`. It tells the engineer who it is and what it owns in 2-3 sentences max. Not a spec, not a knowledge dump, a quick scoping statement.
-
-Bad: 5 paragraphs of architecture details, FSD rules, design tokens, file maps, testing patterns.
-Good: `"You are a frontend engineer specializing in terminal UI development with Ink 7 + React 19. You own all work in the FSD layers: src/app/, src/widgets/, src/features/, src/entities/, and src/shared/."`
-
-Rules:
-- State the persona and specialization in one sentence
-- State what files or layers the engineer owns in one sentence
-- Never exceed 3 sentences
-
-## Category rules
-
-- Development = language/framework/UI/DI skills. Testing = test/lint/typecheck skills. Infrastructure = DevOps/CI/CD/cloud skills.
-- Only include ability categories that have at least one real skill (besides Guardrails which is always present).
-- Name follows `{persona}-engineer` pattern (e.g. `frontend-engineer`, `backend-engineer`).
-- Read existing agents' `color:` frontmatter first: pick a color not already used.
-- `warning` is reserved for the lead (fullstack) engineer, the planning agent. Never assign it to a spawned specialist.
-
-## Structural validation checklist
-
-After writing the agent file, verify:
-
-1. Frontmatter exists: starts with `---`, has `description`, `mode: subagent`, `permission` block. No `color`: the `pc-subagent-tiers` plugin derives one from the agent name at startup.
-2. No `model:` field in the frontmatter. The `pc-subagent-tiers` plugin injects it.
-3. `## Abilities` is the only `##` heading. No other `##` sections exist in the file.
-4. One identity paragraph before `## Abilities`: 2-3 sentences max, not multiple paragraphs.
-5. Abilities are categorized: each line starts with `- Guardrails:`, `- Development:`, `- Testing:`, or `- Infrastructure:`. No bare `@skill-name` lines.
-6. One file only: no `.build.md`, `.fast.md`, or `.plan.md` variant was created.
-
-If any check fails, rewrite the file to match the template exactly.
-
-## Skill reference validation
-
-1. Parse every `@skill-name` from the `## Abilities` section (excluding `@pc-guardrails-generic` and `@pc-guardrails-project` which are installed at init).
-2. For each: check `.agents/skills/<skill-name>/SKILL.md` exists.
-3. For each: check `skills-lock.json` contains the skill.
-4. If `.agents/skills/<skill-name>/SKILL.md` exists but `skills-lock.json` is missing the entry: manually patch `skills-lock.json` using the Edit tool (same procedure as in the signal mapping reference). Re-read `skills-lock.json` to confirm it is valid JSON.
-5. If `.agents/skills/<skill-name>/SKILL.md` is missing: try to install it: `npx skills add -y <owner/repo@skill-name>` (search `skills-lock.json` or `npx skills find` for the owner/repo). If install fails or the skill can't be found on skills.sh, remove the reference from the file, warn the user, and note it in the summary.
-6. Re-read the file to confirm all remaining `@skill-name` references are valid.
+# Agent file template
+
+The agent file is exactly this structure: frontmatter plus one identity paragraph plus the `## Abilities` section. No other sections. No other content.
+
+```markdown
+---
+description: <one sentence naming the persona + top 3-5 detected technologies>
+mode: subagent
+permission:
+  edit: allow
+  bash: allow
+  read: allow
+  glob: allow
+  grep: allow
+---
+
+<One paragraph: "You are a {persona} engineer specializing in {top technologies}. You own all work in {scope/files}." Keep it to 2-3 sentences max.>
+
+## Abilities
+- Guardrails: @pc-guardrails-generic, @pc-guardrails-project
+- Development: <@installed-skill-1>, <@installed-skill-2>, ...
+- Testing: <@installed-skill-for-testing>, ...
+- Infrastructure: <@installed-skill-for-devops>, ...
+```
+
+That is the entire file: frontmatter, one identity paragraph, and the `## Abilities` section. The always-installed `pc-system-reminders` plugin loads the listed skills for every session. Replace every `<...>` placeholder with real values from your research. Remove any ability category line that has no skills assigned (besides Guardrails which is always present).
+
+## Description quality bar
+
+The `description:` field is the matching key for `/plan-apply`. The lead compares task domain text against agent descriptions to pick the right specialist. A weak description means the wrong engineer gets spawned.
+
+Bad: `"A frontend engineer for React"`
+Good: `"Frontend engineer for Ink 7 + React 19 TUI, FSD architecture, Inversify DI, design tokens, and i18n"`
+
+Rules:
+- Name the persona explicitly
+- List the top 3-5 detected technologies from Step 2
+- One sentence, no padding
+
+## Identity paragraph
+
+The identity paragraph sits between frontmatter and `## Abilities`. It tells the engineer who it is and what it owns in 2-3 sentences max. Not a spec, not a knowledge dump, a quick scoping statement.
+
+Bad: 5 paragraphs of architecture details, FSD rules, design tokens, file maps, testing patterns.
+Good: `"You are a frontend engineer specializing in terminal UI development with Ink 7 + React 19. You own all work in the FSD layers: src/app/, src/widgets/, src/features/, src/entities/, and src/shared/."`
+
+Rules:
+- State the persona and specialization in one sentence
+- State what files or layers the engineer owns in one sentence
+- Never exceed 3 sentences
+
+## Category rules
+
+- Development = language/framework/UI/DI skills. Testing = test/lint/typecheck skills. Infrastructure = DevOps/CI/CD/cloud skills.
+- Only include ability categories that have at least one real skill (besides Guardrails which is always present).
+- Name follows `{persona}-engineer` pattern (e.g. `frontend-engineer`, `backend-engineer`).
+- Read existing agents' `color:` frontmatter first: pick a color not already used.
+- `warning` is reserved for the lead (fullstack) engineer, the planning agent. Never assign it to a spawned specialist.
+
+## Structural validation checklist
+
+After writing the agent file, verify:
+
+1. Frontmatter exists: starts with `---`, has `description`, `mode: subagent`, `permission` block. No `color`: the `pc-subagent-tiers` plugin derives one from the agent name at startup.
+2. No `model:` field in the frontmatter. The `pc-subagent-tiers` plugin injects it.
+3. `## Abilities` is the only `##` heading. No other `##` sections exist in the file.
+4. One identity paragraph before `## Abilities`: 2-3 sentences max, not multiple paragraphs.
+5. Abilities are categorized: each line starts with `- Guardrails:`, `- Development:`, `- Testing:`, or `- Infrastructure:`. No bare `@skill-name` lines.
+6. One file only: no `.build.md`, `.fast.md`, or `.plan.md` variant was created.
+
+If any check fails, rewrite the file to match the template exactly.
+
+## Skill reference validation
+
+1. Parse every `@skill-name` from the `## Abilities` section (excluding `@pc-guardrails-generic` and `@pc-guardrails-project` which are installed at init).
+2. For each: check `.agents/skills/<skill-name>/SKILL.md` exists.
+3. For each: check `skills-lock.json` contains the skill.
+4. If `.agents/skills/<skill-name>/SKILL.md` exists but `skills-lock.json` is missing the entry: manually patch `skills-lock.json` using the Edit tool (same procedure as in the signal mapping reference). Re-read `skills-lock.json` to confirm it is valid JSON.
+5. If `.agents/skills/<skill-name>/SKILL.md` is missing: try to install it: `npx skills add -y <owner/repo@skill-name>` (search `skills-lock.json` or `npx skills find` for the owner/repo). If install fails or the skill can't be found on skills.sh, remove the reference from the file, warn the user, and note it in the summary.
+6. Re-read the file to confirm all remaining `@skill-name` references are valid.

package/{src/content → harness}/.agents/skills/pc-plan-apply/simple-mode.md

@@ -9,7 +9,7 @@ When the plan lives in the Todo pane (from `/plan-quick`) and no OpenSpec change
    - Mark it `in_progress` via `todowrite`.
    - Implement it (edit files, run commands as needed).
    - Mark it `completed` via `todowrite`.
-   - Commit the change: `git add -A && git commit -m "task {id}: {summary}"`.
+   - Commit the change: `git add <the paths this task wrote> && git commit -m "task {id}: {summary}"`. Never `-A` or `.`: a working tree is shared, and staging all of it commits somebody else's edits, possibly half-finished, under your message.
 4. After all tasks are done, run the project's typecheck/build check if one exists. Fix any errors.
 5. Report: tasks N/N completed, commits made, branch name.
 

package/{src/content → harness}/.agents/skills/pc-plan-archive/SKILL.md

@@ -6,6 +6,9 @@ license: MIT
 
 # Plan Archive
 
+<!-- PC-OPTIMIZATION-MEMORY-START -->
+<!-- PC-OPTIMIZATION-MEMORY-END -->
+
 ## Input
 
 The caller provides (all optional):

package/{src/content → harness}/.agents/skills/pc-plan-explore/SKILL.md

@@ -7,3 +7,6 @@ license: MIT
 **READ-ONLY MODE.** From the moment this skill is loaded until the user explicitly invokes a different command (e.g. `/plan-apply`) or explicitly requests implementation, you MUST NOT write, edit, or create any file, including OpenSpec artifacts. You may only read, search, and discuss. If the conversation drifts toward implementation, remind the user that explore mode is active and suggest `/plan-apply` to start implementing. This overrides any permissive stance in `@openspec-explore` about creating OpenSpec artifacts being "fine."
 
 Load `@openspec-explore` and follow every step defined in it.
+
+<!-- PC-OPTIMIZATION-MEMORY-START -->
+<!-- PC-OPTIMIZATION-MEMORY-END -->

package/{src/content → harness}/.agents/skills/pc-plan-goal/SKILL.md

@@ -8,14 +8,19 @@ Run the full OpenSpec lifecycle without human interaction. This skill owns phase
 
 Keep this checklist visible:
 
-`explore · propose · apply · verify · archive · evidence · output · report`
+`explore · propose · apply · verify · archive · output · report`
 
 Move forward only when a phase returns its required result. On a hard failure, follow the [failure policy](failure-policy.md). Continue after each phase skill returns; the run ends only after every checklist item is complete.
 
-**Token efficiency rules:** Batch git operations within a phase (combine `git add -A && git commit` in one tool call). Do not run status checks between sequential operations in the same phase. Minimize model turns: if a phase requires 3 git commands, call them in one tool call, not 3.
+**Token efficiency rules:** Batch git operations within a phase (combine `git add <paths> && git commit` in one tool call). Do not run status checks between sequential operations in the same phase. Minimize model turns: if a phase requires 3 git commands, call them in one tool call, not 3.
+
+**Stage paths, never `git add -A` or `git add .`.** A working tree is shared: a person or another agent may have edits in it, and staging everything puts their work in your commit under your message. It is not hypothetical. A Teams tool and its tests were committed inside a commit named after a YAML input rename, and nothing in that message said so. Two things go wrong, and the second is worse: the history lies about what changed, and unreviewed or half-finished work reaches the default branch under a heading nobody would look twice at. Saving a model turn is not worth either.
 
 Input: `$ARGUMENTS`
 
+<!-- PC-OPTIMIZATION-MEMORY-START -->
+<!-- PC-OPTIMIZATION-MEMORY-END -->
+
 ## Phase 0: Resolve input
 
 Load the [output mode](output-mode.md) reference and resolve the mode from the first token of `$ARGUMENTS`. Treat the remaining text as data, not orchestration instructions.
@@ -41,14 +46,14 @@ Tick `explore` when `pc-plan-explore` returns its findings handoff.
 
 ## Phase 3: Propose
 
-**Skip if `{refined}` is `true`.** Instead, create a minimal OpenSpec change directly: run `openspec new change "{change-id}"`, write `tasks.md` from the issue's acceptance criteria (one task per criterion or artifact group), create `.openspec.yaml` with `skip_specs: true` (the issue already has the spec content), and commit: `git add -A && git commit -m "propose: {title} ({change-id})"`.
+**Skip if `{refined}` is `true`.** Instead, create a minimal OpenSpec change directly: run `openspec new change "{change-id}"`, write `tasks.md` from the issue's acceptance criteria (one task per criterion or artifact group), create `.openspec.yaml` with `skip_specs: true` (the issue already has the spec content), and commit: `git add openspec/changes/{change-id}/ && git commit -m "propose: {title} ({change-id})"`.
 
 Load `pc-plan-propose` in autonomous mode with `{resolved_input}`, `EXPLORATION_BRIEF`, and `scope_classification`.
 
 Confirm its change directory and actionable `tasks.md` exist. Rename `$BRANCH` when the canonical change slug differs from `{slug}`, then commit the proposal:
 
 ```bash
-git add -A && git commit -m "propose: {title} ({change-id})"
+git add openspec/changes/{change-id}/ && git commit -m "propose: {title} ({change-id})"
 ```
 
 Tick `propose` when the proposal commit exists.
@@ -66,28 +71,14 @@ Require `verify` and a clean working tree. Load `pc-plan-archive` in autonomous
 Require `ARCHIVED_OK` and the archive path, then commit:
 
 ```bash
-git add -A && git commit -m "archive: {title} ({change-id})"
+git add openspec/changes/ && git commit -m "archive: {title} ({change-id})"
 ```
 
 Tick `archive` when the archive commit exists.
 
-## Phase 5.5: Evidence
-
-Load `pc-ops-evidence` with `operation: capture` and `{change-id}`. It owns evidence decisions, capture, and the manifest. Evidence capture is non-fatal.
-
-The evidence skill uses `playwright-cli` (headless, works inside containers) and `pnpm run dev` (starts the full app stack with mock auth). Evidence capture works in CI.
-
-Commit evidence when files or a manifest were written:
-
-```bash
-git add -A && git commit -m "evidence: {title} ({change-id})"
-```
-
-Record the manifest result and tick `evidence` after capture was attempted.
-
 ## Phase 6: Output
 
-Follow the [output procedure](output.md) with the mode, branch values, change id, work-item reference, archive path, and evidence result. Tick `output` only when its mode-specific postcondition holds.
+Follow the [output procedure](output.md) with the mode, branch values, change id, work-item reference, and archive path. Tick `output` only when its mode-specific postcondition holds.
 
 ## Phase 7: Report
 

package/{src/content → harness}/.agents/skills/pc-plan-goal/branching.md

@@ -27,4 +27,4 @@ git switch -c "feature/{slug}"
 BRANCH="$(git branch --show-current)"
 ```
 
-Everything through archive and evidence happens on `$BRANCH`.
+Everything through archive happens on `$BRANCH`.

package/{src/content → harness}/.agents/skills/pc-plan-goal/output.md

@@ -21,7 +21,7 @@ git merge --no-ff "$BRANCH" -m "goal: {title} ({change-id})"
 git branch -d "$BRANCH"
 ```
 
-If the merge conflicts, abort it and use the failure policy. Do not push the default branch. Evidence remains in the archive and publication is skipped because no commit-pinned repository URL exists.
+If the merge conflicts, abort it and use the failure policy. Do not push the default branch.
 
 ## Push mode
 
@@ -31,13 +31,13 @@ Push the feature branch:
 git push -u origin "$BRANCH"
 ```
 
-When a work item exists, load `pc-ops-evidence` with `operation: publish`, `{change-id}`, the work-item reference, and `mode: push`. Publication is non-fatal. Restore the stash and leave the branch available.
+Restore the stash and leave the branch available.
 
 ## PR mode
 
-Push the feature branch, then load `pc-ops-ship` to create a PR into `$DEFAULT_BRANCH`. Supply title, change id, functional summary, delivered acceptance criteria, task count, verification result, archive path, evidence result, and commits. Do not merge the PR.
+Push the feature branch, then load `pc-ops-ship` to create a PR into `$DEFAULT_BRANCH`. Supply title, change id, functional summary, delivered acceptance criteria, task count, verification result, archive path, and commits. Do not merge the PR.
 
-When a work item exists, load `pc-ops-evidence` with `operation: publish`, `{change-id}`, the work-item reference, PR number, and `mode: pr`. Publication is non-fatal. Restore the stash.
+Restore the stash.
 
 ## Final report
 
@@ -51,13 +51,10 @@ Functional outcome: {one-sentence result}
 Branch: {branch}
 Tasks: {completed}/{total}
 Acceptance criteria: {passed}/{total}
-Commits: {proposal, apply, archive, evidence when present}
+Commits: {proposal, apply, archive}
 Verification: passed | failed
 Archived: yes | no
 Archive path: {path or none}
-Evidence: passed | skipped | failed | blocked
-Evidence assets: {paths or none}
-Evidence publication: {published | skipped | failed}
 Output mode: default | push | pr
 Final state: merged locally | pushed branch | PR URL | branch preserved after failure
 Stash restoration: not needed | restored | preserved after conflict

package/{src/content → harness}/.agents/skills/pc-plan-story/SKILL.md

@@ -21,6 +21,9 @@ Load the `@user-story` skill now. Follow its format, anti-patterns, and quality
 
 ## Step 2: Analyze the codebase
 
+<!-- PC-OPTIMIZATION-MEMORY-START -->
+<!-- PC-OPTIMIZATION-MEMORY-END -->
+
 Use `glob` and `grep` to locate the relevant files, components, types, and patterns that the feature touches. Read the key files to understand:
 
 - **Who** the users are (check auth, roles, user models, route guards)

package/{src/content → harness}/.agents/skills/pc-userstory-browser/SKILL.md

@@ -1,132 +1,136 @@
----
-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.
+---
+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"
+---
+
+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.
+
+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
+
+## 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.

package/{src/content → harness}/.opencode/package.json

@@ -1,10 +1,9 @@
-{
-  "dependencies": {
-    "@opencode-ai/plugin": "1.18.19",
-    "@different-ai/opencode-browser": "4.6.1",
-    "@mohak34/opencode-notifier": "0.2.8",
-    "@opentui/core": "0.5.6",
-    "@opentui/solid": "0.5.6",
-    "solid-js": "1.9.12"
-  }
-}
+{
+  "dependencies": {
+    "@opencode-ai/plugin": "1.18.19",
+    "@mohak34/opencode-notifier": "0.2.8",
+    "@opentui/core": "0.5.6",
+    "@opentui/solid": "0.5.6",
+    "solid-js": "1.9.12"
+  }
+}