@plainconceptsplatform/agent-harness 3.10.0 → 3.11.0

package/README.md

@@ -133,6 +133,8 @@ Commands that other commands (or agents) need to execute are thin wrappers aroun
 | `/repo-audit` | Read-only audit of every configured source root against fullstack abilities and guardrails. Reports prioritized architecture, quality, dependency, lockfile, tooling, and CI findings. |
 | `/repo-initialize` | Initialize the project. Asks greenfield versus brownfield, then activates the agent team. |
 | `/plan-explore` | Think through an idea or investigate a problem before committing to a plan. |
+| `/plan-mockup <screen or flow>` | Draw a self-contained HTML mockup of a UI change from this repository's own design tokens and components, with every region mapped to the real component to build it with. States UX intent, not a spec. Can publish it to an issue, where the refine and implement workflows pick it up. |
+| `/plan-story <feature or need>` | Write a repo-aware user story from a feature idea: Gherkin acceptance criteria and an implementation plan, wrapped in the repository's issue form. Writes no files. |
 | `/plan-propose <url or idea>` | Parse a GitHub Issue, Azure DevOps, Jira, or browser URL, or a direct idea, into a structured plan (proposal, specs, tasks). Enriches each task with agent and model assignments. |
 | `/plan-quick <task>` | Quick plan for focused changes. Reads the codebase, creates a task checklist in the Todo pane, and stops. No OpenSpec, no proposals, no specs. |
 | `/plan-apply` | Implement tasks from the current plan. Detects format automatically: OpenSpec-annotated tasks run as parallel subagent waves; plain checkboxes run sequentially in-session. |
@@ -204,6 +206,8 @@ Built-in skills (`pc-` prefix) shipped with agent-harness:
 | `pc-userstory-browser` | Parse work item from any URL via browser automation (Linear, Trello, and so on) |
 | `browser-automation` | Browser control via `browse` (user's real browser, localhost + external sites with handoffs) |
 | `pc-plan-explore` | Read-only exploration procedure behind `/plan-explore`; autonomous mode used by `/plan-goal` |
+| `pc-plan-mockup` | HTML mockup procedure behind `/plan-mockup`; autonomous mode used by the refine workflow |
+| `pc-plan-story` | User story procedure behind `/plan-story`; used by the refine workflow |
 | `pc-plan-propose` | Proposal + task-enrichment procedure behind `/plan-propose`; autonomous mode used by `/plan-goal` |
 | `pc-plan-apply` | Wave-implementation procedure behind `/plan-apply`; autonomous mode used by `/plan-goal` |
 | `pc-plan-archive` | Archive procedure behind `/plan-archive` (platform flow injected at onboarding); autonomous mode used by `/plan-goal` |

package/cli/steps/copy/skills.js

@@ -1,7 +1,8 @@
+import { execa } from 'execa'
 import fse from 'fs-extra'
 import path from 'path'
 import { fileURLToPath } from 'url'
-import { info, success } from '../../utils/exec.js'
+import { info, success, warn } from '../../utils/exec.js'
 import { canUpdateManagedFile, readUpdateManifest, recordManagedFile, writeUpdateManifest } from '../../utils/update-manifest.js'
 import { RETIRED_PATHS } from '../../utils/paths.js'
 
@@ -294,7 +295,9 @@ export async function installSkills(backlogPlatform = 'github', repoPlatform, op
   if (await fse.pathExists(CONTENT_SKILLS_LOCK)) {
     const destLock = path.join(process.cwd(), 'skills-lock.json')
     if (await fse.pathExists(destLock) && (opts.updateMode || !opts.forceOverwrite)) {
-      info('skills-lock.json already exists, skipping')
+      const added = opts.updateMode ? await mergeShippedSkillsLock(destLock) : []
+      if (added.length > 0) await installLockedSkills(added)
+      else info('skills-lock.json already exists, skipping')
     } else {
       await fse.copy(CONTENT_SKILLS_LOCK, destLock, { overwrite: true })
       success(`${opts.forceOverwrite ? 'Updated' : 'Installed'} skills-lock.json`)
@@ -306,6 +309,40 @@ export async function installSkills(backlogPlatform = 'github', repoPlatform, op
   // This avoids multiple npx skills add calls during onboarding.
 }
 
+// A project's skills-lock.json is its own: it holds the skills the wizard and
+// /make-engineer added. Replacing it on update would drop those, and skipping it
+// meant a third-party skill the harness starts shipping never reached a project
+// installed before that release. So update adds only the entries it lacks.
+export async function mergeShippedSkillsLock(destLock) {
+  const shipped = await fse.readJson(CONTENT_SKILLS_LOCK)
+  let lock
+  try {
+    lock = await fse.readJson(destLock)
+  } catch {
+    warn('Could not parse skills-lock.json, leaving it as it is')
+    return []
+  }
+  lock.skills ??= {}
+  const added = Object.keys(shipped.skills ?? {}).filter(name => !lock.skills[name])
+  if (added.length === 0) return []
+  for (const name of added) lock.skills[name] = shipped.skills[name]
+  await fse.writeJson(destLock, lock, { spaces: 2 })
+  success(`Added to skills-lock.json: ${added.join(', ')}`)
+  return added
+}
+
+async function installLockedSkills(added) {
+  const result = await execa('npx', ['skills', 'experimental_install', '--yes'], {
+    cwd: process.cwd(),
+    reject: false,
+    stdio: 'pipe',
+    timeout: 600000,
+  })
+  if (result.exitCode !== 0) {
+    warn(`${added.join(', ')} added to skills-lock.json but not installed. Run npx skills experimental_install --yes.`)
+  }
+}
+
 export async function removeRetiredFiles(cwd = process.cwd()) {
   for (const relative of RETIRED_PATHS) {
     const target = path.join(cwd, relative)

package/harness/.opencode/commands/plan-mockup.md

@@ -0,0 +1,11 @@
+---
+description: Draw a self-contained HTML mockup of a UI change from this repository's own tokens and components.
+agent: planner
+subagent: false
+---
+
+Load the `pc-plan-mockup` skill and execute it in **interactive mode**.
+
+Input:
+
+$ARGUMENTS

package/harness/skills-lock.json

@@ -7,11 +7,17 @@
       "skillPath": "skills/find-skills/SKILL.md",
       "computedHash": "781bd6d3f9b19f8c9af6b53d8d0e4876d0183841b565db34ca7092ffa412d111"
     },
+    "html-prototype": {
+      "source": "plannotator/effective-html",
+      "sourceType": "github",
+      "skillPath": "skills/html-prototype/SKILL.md",
+      "computedHash": "7f82fd83b81f853e3b3f973073be4e82f93875b190f4a3f4a35b9801ace825cd"
+    },
     "user-story": {
       "source": "deanpeters/product-manager-skills",
       "sourceType": "github",
       "skillPath": "skills/user-story/SKILL.md",
-      "computedHash": "user-story-placeholder"
+      "computedHash": "d2f39a6b17e9635da6c93003029c6ade7a20c17a44b0a17bf871bb0faabb33ed"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/agent-harness",
-  "version": "3.10.0",
+  "version": "3.11.0",
   "description": "Installs the Plain Concepts Platform Harness into any codebase, and keeps it up to date. Wires OpenCode, OpenSpec, codegraph, and agentmemory into a multi-agent workflow that runs on native parallel subagents.",
   "keywords": [
     "opencode",

package/skills/pc-plan-apply/SKILL.md

@@ -41,6 +41,8 @@ Core rule: push, don't pull. A worker is born with its work: every `task()` spaw
 
 When `.platform/contract.yml` declares `reuse` and the change's `proposal.md` has no `## What is reused` section, stop the APPLY stage and report it: the plan never checked what the template already ships. Otherwise every spawn prompt in step 7 carries that section.
 
+When the change comes from an issue that carries a mockup (a section reading `UX mockup: intent, not a spec`, or a `mockups` branch folder for it), every spawn prompt for UI work in step 7 carries its component table and this line: the mockup states UX intent only; build with the components the table names, `DESIGN.md` and the repository's conventions, and never copy its markup, styles or `data-mockup-section` and `data-component` attributes. A `new:<Name>` entry is a component this change builds.
+
 Before hydrating the Todo board, resolve every task's annotated worker. If any task has a blank agent annotation, its base template is missing, its tier variant is unavailable, or the manifest has no effective model for its tier, stop the APPLY stage and report the task ID, expected worker, and missing file. Do not replace the worker with `fullstack-engineer`, `general`, or the lead session.
 
 **3. Hydrate the Todo board.** `todowrite` one item per task: `pending`. The Todo pane is the visible subagent board (opencode plugins cannot draw a custom pane, so the native Todo widget is the live UI). While a task is in flight, its label must carry the worker: `<agent> · <model>`, with the model read from `.opencode/harness-models.json`, so the pane shows which agent on which model is doing what. The Todo list is a projection only: never read it for recovery; rebuild it from `tasks.md` and git and `.opencode/harness-run.json`.

package/skills/pc-plan-explore/SKILL.md

@@ -10,6 +10,7 @@ Explore, then hand back what you learned. `@openspec-explore` supplies the stanc
 
 - Never write, edit, or create a file while this skill is loaded, OpenSpec artifacts included. This overrides `@openspec-explore`, which says creating them is "fine". Reading, searching, and discussing are the whole job.
 - If the conversation turns toward implementation, say explore mode is active and point at `/plan-apply`.
+- When the idea changes what someone sees on screen, point at `/plan-mockup` once the direction is settled: a picture settles layout questions faster than prose.
 
 Load `@openspec-explore` for the approach.
 

package/skills/pc-plan-mockup/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: pc-plan-mockup
+description: Build a self-contained HTML mockup of a UI change from this repository's own design tokens and components, so a person and the implementing agent agree on the experience before any code is written. The mockup states UX intent, not a spec. Use when a feature touches the frontend and the layout, flow or states are worth seeing. Invoked by the /plan-mockup command (interactive) and by the refine workflow (autonomous).
+license: MIT
+---
+
+Draw the change before building it. The mockup answers one question: is this the experience we mean? It is never the implementation. The real components, `DESIGN.md` and `ARCHITECTURE.md` decide how it is built, and the mockup tells the implementer which of those components each part of the screen should be.
+
+[The contract](mockup-contract.md) defines the files, the HTML rules and `mockup.json`. Read it before writing anything.
+
+## Input
+
+A feature idea, an exploration brief from `/plan-explore`, a story from `/plan-story`, or an issue. Ask what screen or flow to draw only when none of those says.
+
+## Modes
+
+- `interactive` (default): the person is here. Show the mockup, ask what to change, iterate until they are happy.
+- `autonomous`: a workflow called this skill and gave an output directory. Ask nothing. Write `index.html` and `mockup.json` there and stop.
+
+<!-- PC-OPTIMIZATION-MEMORY-START -->
+<!-- PC-OPTIMIZATION-MEMORY-END -->
+
+## Rules
+
+- Never use a component, colour or font the repository does not have. When the screen needs something that does not exist, mark it `new:<Name>` so the implementer knows it is new work.
+- Never load anything from outside the file, and never use a utility framework runtime. Plain CSS from the tokens keeps it approximate, and approximate is the point.
+- Never touch the source tree. The mockup lives in `.mockups/` locally and on the `mockups` branch once published.
+- Data is invented. No real names, customers or email addresses, even ones the conversation used.
+
+## Flow
+
+1. **Tokens.** Find `DESIGN.md` at the root, or in `ai/` or `docs/`. Read its frontmatter by meaning, not by exact key: `color.primitives.brand-blue` and `color.primitive.brand_blue` are the same token. If it is missing or still the placeholder, in interactive mode run `/make-design` first; in autonomous mode read the theme stylesheet the web app imports and set `designSource` to `theme-css`.
+
+2. **Components.** List the UI components the area uses: the shared UI folder (often `src/shared/ui/` or `src/components/ui/`), the feature's own components, and the packages they import from. Read the few the screen needs, enough to draw them with the right anatomy (a table's header and pagination, a sheet's footer actions), never to copy their code.
+
+3. **States.** Decide which states the scenario can reach: empty, loading, error, success, disabled, mobile, or one the issue names. Draw only those.
+
+4. **Method.** If `@html-prototype` is installed, load it and use it in mockup mode for how to scope the flow, model states and check widths. This skill stays the authority on look and components.
+
+5. **Write.** `index.html` and `mockup.json`, as the contract says. Tag every region with `data-mockup-section` and every component stand-in with `data-component`. Interactive mode writes to `.mockups/<slug>/` and adds `.mockups/` to `.gitignore` when it is missing; autonomous mode writes to the directory it was given.
+
+6. **Check.** Open the file at 1440 and 390 pixels wide, with `@browser-automation` when it is available, and save `desktop.png` and `mobile.png` beside it. Look for overflow, unreadable contrast and empty regions. Without a browser, say which checks did not run.
+
+7. **Hand off.** In interactive mode, show the screenshots and the component table (section, element, component, path), then ask what next.
+
+## Publish
+
+When the person picks Publish, or names an issue, put the folder on the `mockups` branch so the refine and implement workflows find it:
+
+```bash
+issue=<number>
+dir=$(mktemp -d)
+git fetch origin mockups 2>/dev/null || true
+if git rev-parse --verify -q origin/mockups >/dev/null; then
+  git worktree add "$dir" origin/mockups --detach
+else
+  git worktree add --detach "$dir" && git -C "$dir" checkout --orphan mockups && git -C "$dir" rm -rfq .
+fi
+rm -rf "$dir/issue-$issue" && mkdir -p "$dir/issue-$issue"
+cp .mockups/<slug>/* "$dir/issue-$issue/"
+git -C "$dir" add "issue-$issue"
+git -C "$dir" commit -m "mockup: issue #$issue [skip ci]"
+git -C "$dir" push origin HEAD:refs/heads/mockups
+git worktree remove --force "$dir"
+```
+
+Set `issue` in `mockup.json` before copying. Then comment on the issue with a link to `issue-<number>/index.html` on that branch, the desktop screenshot when there is one, the component table and the line `UX mockup: intent, not a spec. Build with the components listed.` Use the repository's platform CLI for the comment; when there is none, give the person the text to paste.
+
+## Contracts
+
+```json
+{
+  "questions": [
+    {
+      "header": "What next",
+      "question": "What next?",
+      "options": [
+        { "label": "Change the mockup", "description": "Say what to move, add or remove." },
+        { "label": "/plan-story", "description": "Write the user story, with this mockup in its UX section." },
+        { "label": "Publish", "description": "Put the mockup on the mockups branch and link it from an issue." }
+      ]
+    }
+  ]
+}
+```

package/skills/pc-plan-mockup/mockup-contract.md

@@ -0,0 +1,65 @@
+# Mockup contract
+
+What a mockup folder holds, so the people and the workflows that read it can rely on it. The agentic workflows validate a mockup against this file before they render or publish it; a mockup that breaks it is dropped, never fixed up.
+
+## Files
+
+| File | Required | What it is |
+|---|---|---|
+| `index.html` | yes | The mockup. One file, opens offline in any browser. |
+| `mockup.json` | yes | What the mockup claims, in a form a workflow can read without parsing HTML. |
+| `desktop.png`, `mobile.png` | no | Screenshots at 1440 and 390 pixels wide. The refine workflow renders them itself when they are missing. |
+
+## `index.html`
+
+- One self-contained file under 400 KB. Styles sit in one inline `<style>`; a small inline `<script>` is allowed for toggling states.
+- Nothing is loaded from anywhere: no `http://` or `https://` URL, no `<script src>`, no `<link href>` to a stylesheet, no web font, no image file. Icons are inline SVG or text.
+- Colours, radii, spacing and type come from the repository's design tokens, declared once as CSS custom properties on `:root` (and `.dark` when the repository has a dark mode). No utility framework runtime, Tailwind included: the mockup is approximate on purpose, and a runtime would make it look more authoritative than it is.
+- The first element in `<body>` is a banner reading `UX mockup: intent, not a spec`.
+- Every screen region carries `data-mockup-section="<id>"`, a kebab-case id unique in the file.
+- Every element that stands for a real component carries `data-component="<reference>"`:
+  - a path relative to the repository root for a component the repository owns, such as `apps/web/src/shared/ui/button.tsx`;
+  - a package export for a component it imports, such as `@plainconceptsplatform/ui-components/data-table`;
+  - `new:<Name>` for a component that does not exist yet and the change has to build.
+- Data is fictional and internally consistent. No real person, customer, email address or identifier.
+
+## `mockup.json`
+
+```json
+{
+  "version": 1,
+  "title": "Claim timeline panel",
+  "issue": 42,
+  "designSource": "DESIGN.md",
+  "sections": [
+    { "id": "timeline", "purpose": "Every status change of the claim, newest first" }
+  ],
+  "components": [
+    { "section": "timeline", "element": "Status chip", "component": "Badge", "path": "apps/web/src/shared/ui/badge.tsx" },
+    { "section": "timeline", "element": "Timeline row", "component": "new:TimelineItem", "path": "new" }
+  ],
+  "states": ["empty", "loading", "mobile"],
+  "notes": "The approver's comment is collapsed past three lines."
+}
+```
+
+| Field | Rule |
+|---|---|
+| `version` | `1`. |
+| `title` | Short name of the screen or flow. |
+| `issue` | The issue number, or `null` before there is one. |
+| `designSource` | `DESIGN.md`, `theme-css` (tokens read from the theme stylesheet because `DESIGN.md` was missing) or `none`. |
+| `sections` | One entry per `data-mockup-section` in the HTML, same ids, same order. |
+| `components` | One entry per distinct `data-component` reference. `component` is the name the code uses; `path` is the reference from the HTML, or `new`. |
+| `states` | The states the mockup draws, from `default`, `empty`, `loading`, `error`, `success`, `disabled`, `mobile`, or a domain state named in the issue. |
+| `notes` | Optional. Behaviour the picture cannot show. |
+
+## When the work is split
+
+Each smaller issue covers some sections of the one mockup. Its body says which, on a line of its own: `Mockup sections: timeline, filters`, using the section ids. The refine workflow reads that line and links the issue to those sections.
+
+## Where a published mockup lives
+
+On the repository's `mockups` branch, an orphan branch that never merges into anything, at `issue-<number>/`. Every publish replaces that folder. Nothing on that branch is source code, and nothing in the source tree may import or copy from it.
+
+The issue links it from a section the workflow writes between `<!-- agent-mockup:start -->` and `<!-- agent-mockup:end -->`, which opens with `<!-- agent-mockup: issue-<number> -->` naming the folder. A split child names its parent's folder there.

package/skills/pc-plan-story/SKILL.md

@@ -49,7 +49,9 @@ The caller may pass exploration findings from a prior `/plan-explore` session. T
 
    *Fill:* Draw every field's content from your exploration findings. Required fields always get real content; optional fields only when you genuinely have something for them. The story narrative lands in the field that asks for it — proposal, description, or what-happened, depending on the form. The Given/When/Then scenarios go into the form's acceptance-criteria field when it has one; otherwise they stay a section of their own. The Mermaid diagram goes where it reads best inside the filled form.
 
-9. **Plan section.** Using the codebase investigation from step 3, produce a structured implementation plan that goes after the story inside the issue form body. Format it as follows:
+9. **UX section.** When this conversation produced a mockup with `/plan-mockup` (its `.mockups/<slug>/mockup.json`), or the issue already links one, add a short UX section inside the filled form: the mockup's title, where it lives, its component table (section, element, component, path) and the line `UX mockup: intent, not a spec. Build with the components listed.` Acceptance scenarios describe behaviour, never pixels, so none of them may say "matches the mockup". When the story touches the UI and there is no mockup, offer `/plan-mockup` in step 11.
+
+10. **Plan section.** Using the codebase investigation from step 3, produce a structured implementation plan that goes after the story inside the issue form body. Format it as follows:
 
    Start with a one-line scope summary, then a context paragraph describing what areas the plan touches, how many changes it breaks into, and whether the changes are independent.
 
@@ -72,7 +74,7 @@ The caller may pass exploration findings from a prior `/plan-explore` session. T
 
    Do not write any files. The plan is part of the story output, read-only. It tells the implementer what to touch and why, so they can start without re-investigating.
 
-10. Show the story with the issue form wrapping, the plan, and the artefacts it is grounded in, then ask what is next. If the plan has an open clarification — a wording choice, a missing constraint, an unknown API — ask it before the contracts question.
+11. Show the story with the issue form wrapping, the plan, and the artefacts it is grounded in, then ask what is next. If the plan has an open clarification — a wording choice, a missing constraint, an unknown API — ask it before the contracts question.
 
 ## Contracts
 
@@ -85,6 +87,7 @@ The caller may pass exploration findings from a prior `/plan-explore` session. T
       "options": [
         { "label": "/plan-propose", "description": "Turn this user story into a full OpenSpec proposal with design, specs, and tasks." },
         { "label": "/plan-quick", "description": "Create a lightweight task checklist from this story." },
+        { "label": "/plan-mockup", "description": "Draw the UI this story describes before planning it. Offered when the story touches the UI and has no mockup yet." },
         { "label": "Refine the story", "description": "Iterate on the story with feedback." }
       ]
     }

package/skills/pc-repo-help/SKILL.md

@@ -22,6 +22,8 @@ Display the following reference to the user exactly as written. Do not summarize
 
 **`/plan-story <feature or need>`**: Write a detailed, repo-aware user story from a feature idea. Loads the `@user-story` skill (Mike Cohn format + Gherkin acceptance criteria), analyzes your codebase for concrete context, and produces a development-ready story with specific personas, real outcomes, and testable criteria grounded in your actual file paths, component names, and data models. No files written — just the story.
 
+**`/plan-mockup <screen or flow>`**: Draw the UI change before building it: a self-contained HTML mockup built from this repository's own design tokens and components, with every region mapped to the real component the implementer should use. It states UX intent, not a spec. Writes to `.mockups/` and can publish to an issue, where the refine and implement workflows pick it up.
+
 **`/plan-propose <url or idea>`**: You have a work item URL, or a clear idea and you want to turn it into a structured plan (proposal, specs, tasks). Enriches each task with the best matching agent and model before showing you the plan. Nothing is implemented until you confirm.
 
 ---
@@ -69,6 +71,7 @@ Display the following reference to the user exactly as written. Do not summarize
 **Complex change:**
 ```
 /plan-explore   ← optional: think it through first
+/plan-mockup    ← optional: see the UI before planning it
 /plan-propose   ← create the plan
 /plan-apply     ← implement with the team
 /ops-ship        ← ship

package/skills/pc-repo-onboard/SKILL.md

@@ -19,7 +19,7 @@ A guided tour of this repository and the harness installed in it, for somebody w
 
    | Group | Commands |
    |---|---|
-   | Planning | `/plan-explore`, `/plan-story`, `/plan-propose`, `/plan-quick`, `/plan-goal` |
+   | Planning | `/plan-explore`, `/plan-mockup`, `/plan-story`, `/plan-propose`, `/plan-quick`, `/plan-goal` |
    | Implementation | `/plan-apply`, `/plan-archive` |
    | Maintenance | `/make-architecture`, `/make-design`, `/make-engineer`, `/make-guardrails` |
    | Shipping | `/ops-ship`, `/ops-review`, `/ops-backlog` |