@plainconceptsplatform/agent-harness 3.9.0 → 3.11.0

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

@@ -1,91 +1,91 @@
----
-name: pc-plan-goal
-description: "Autonomous pipeline: explore, propose, apply, archive, then merge/PR/push. For loop-engineering. Invoked by the /plan-goal command."
-license: MIT
----
-
-Run the full OpenSpec lifecycle without human interaction. This skill owns phase order, cross-phase gates, commits, and output. Each phase skill owns its procedure.
-
-Keep this checklist visible:
-
-`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 <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 the paths a phase wrote; unscoped staging is denied (`pc-system-reminders`). A shared tree once put a Teams tool and its tests inside a commit named after a YAML input rename, so unreviewed work reached the default branch under a heading nobody would look twice at.
-
-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.
-
-- For a work-item URL or issue key with a configured backlog platform, load `@pc-userstory` and fetch the work item.
-- Otherwise, use the remaining text as the direct feature description.
-- Preserve title, description, work-item reference, and acceptance criteria as `{resolved_input}`.
-- Derive `{slug}` and classify scope as `focused`, `standard`, or `complex`.
-
-**Refined-issue detection:** set `{refined}` to `true` only when all three hold. The input came from a backlog work item, not free text. It contains at least one `Scenario:` with `Given` / `When` / `Then`. It names affected paths, and at least one of them exists in this repository. Anything less runs Phases 2 and 3 in full: `{refined}` skips a gate, so a near miss must fall back rather than guess.
-
-When it is `true`, the issue content is the proposal. Phase 2 is skipped and Phase 3 runs with `skip_specs: true`.
-
-## Phase 1: Branch
-
-Follow the [branching procedure](branching.md) with `{slug}`. Record `$START_BRANCH`, `$DEFAULT_BRANCH`, `$BRANCH`, and whether the goal stash exists.
-
-## Phase 2: Explore
-
-**Skip if `{refined}` is `true`.** The issue already contains structured acceptance criteria and affected artifacts; re-exploring the codebase would waste tokens re-deriving what the issue already specifies. Set `EXPLORATION_BRIEF` to a one-line summary: `"Pre-refined issue: {title}"`.
-
-Load `pc-plan-explore` with `{resolved_input}` in autonomous mode. Require an in-memory `EXPLORATION_BRIEF` as its findings handoff to Phase 3.
-
-Tick `explore` when `pc-plan-explore` returns its findings handoff.
-
-## Phase 3: Propose
-
-Load `pc-plan-propose` in autonomous mode with `{resolved_input}`, `EXPLORATION_BRIEF`, and `scope_classification`.
-
-**When `{refined}` is `true`,** pass the work item as the proposal body and set `skip_specs: true` in `.openspec.yaml`: the issue already carries the spec content. Propose still runs, because it owns task enrichment. A hand-written `tasks.md` has no `<!-- agent, depends_on, touches -->` annotations, and Phase 4 stops on a task whose worker is unresolved.
-
-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 openspec/changes/{change-id}/ && git commit -m "propose: {title} ({change-id})"
-```
-
-Tick `propose` when the proposal commit exists.
-
-## Phase 4: Apply and verify
-
-Load `pc-plan-apply` in autonomous mode with `start_from: load-plan`. It owns worker resolution, subagent waves, commits, verification, and re-waves.
-
-Require it to return every task complete and `VERIFIED`, then load `pc-repo-verify`. Tick `apply` when apply returns `VERIFIED`. When `pc-repo-verify` returns `PLAN_WRITTEN` or `STUB_WRITTEN`, commit the plan, which the evidence workflow replays once the pull request merges, then tick `verify`:
-
-```bash
-git add openspec/changes/{change-id}/verification-plan.md && git commit -m "verify: {title} ({change-id})"
-```
-
-## Phase 5: Archive
-
-Require `verify` and a clean working tree. Load `pc-plan-archive` in autonomous mode with `{change-id}`. It owns archive verification and retry.
-
-Require `ARCHIVED_OK` and the archive path, then commit:
-
-```bash
-git add openspec/changes/ && git commit -m "archive: {title} ({change-id})"
-```
-
-Tick `archive` when the archive commit exists.
-
-## Phase 6: Output
-
-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
-
-Print the final report from the [output procedure](output.md). Tick `report` only after every checklist item is complete.
+---
+name: pc-plan-goal
+description: "Autonomous pipeline: explore, propose, apply, archive, then merge/PR/push. For loop-engineering. Invoked by the /plan-goal command."
+license: MIT
+---
+
+Run the full OpenSpec lifecycle without human interaction. This skill owns phase order, cross-phase gates, commits, and output. Each phase skill owns its procedure.
+
+Keep this checklist visible:
+
+`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 <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 the paths a phase wrote; unscoped staging is denied (`pc-system-reminders`). A shared tree once put a Teams tool and its tests inside a commit named after a YAML input rename, so unreviewed work reached the default branch under a heading nobody would look twice at.
+
+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.
+
+- For a work-item URL or issue key with a configured backlog platform, load `@pc-userstory` and fetch the work item.
+- Otherwise, use the remaining text as the direct feature description.
+- Preserve title, description, work-item reference, and acceptance criteria as `{resolved_input}`.
+- Derive `{slug}` and classify scope as `focused`, `standard`, or `complex`.
+
+**Refined-issue detection:** set `{refined}` to `true` only when all three hold. The input came from a backlog work item, not free text. It contains at least one `Scenario:` with `Given` / `When` / `Then`. It names affected paths, and at least one of them exists in this repository. Anything less runs Phases 2 and 3 in full: `{refined}` skips a gate, so a near miss must fall back rather than guess.
+
+When it is `true`, the issue content is the proposal. Phase 2 is skipped and Phase 3 runs with `skip_specs: true`.
+
+## Phase 1: Branch
+
+Follow the [branching procedure](branching.md) with `{slug}`. Record `$START_BRANCH`, `$DEFAULT_BRANCH`, `$BRANCH`, and whether the goal stash exists.
+
+## Phase 2: Explore
+
+**Skip if `{refined}` is `true`.** The issue already contains structured acceptance criteria and affected artifacts; re-exploring the codebase would waste tokens re-deriving what the issue already specifies. Set `EXPLORATION_BRIEF` to a one-line summary: `"Pre-refined issue: {title}"`.
+
+Load `pc-plan-explore` with `{resolved_input}` in autonomous mode. Require an in-memory `EXPLORATION_BRIEF` as its findings handoff to Phase 3.
+
+Tick `explore` when `pc-plan-explore` returns its findings handoff.
+
+## Phase 3: Propose
+
+Load `pc-plan-propose` in autonomous mode with `{resolved_input}`, `EXPLORATION_BRIEF`, and `scope_classification`.
+
+**When `{refined}` is `true`,** pass the work item as the proposal body and set `skip_specs: true` in `.openspec.yaml`: the issue already carries the spec content. Propose still runs, because it owns task enrichment. A hand-written `tasks.md` has no `<!-- agent, depends_on, touches -->` annotations, and Phase 4 stops on a task whose worker is unresolved.
+
+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 openspec/changes/{change-id}/ && git commit -m "propose: {title} ({change-id})"
+```
+
+Tick `propose` when the proposal commit exists.
+
+## Phase 4: Apply and verify
+
+Load `pc-plan-apply` in autonomous mode with `start_from: load-plan`. It owns worker resolution, subagent waves, commits, verification, and re-waves.
+
+Require it to return every task complete and `VERIFIED`, then load `pc-repo-verify`. Tick `apply` when apply returns `VERIFIED`. When `pc-repo-verify` returns `PLAN_WRITTEN` or `STUB_WRITTEN`, commit the plan, which the evidence workflow replays once the pull request merges, then tick `verify`:
+
+```bash
+git add openspec/changes/{change-id}/verification-plan.md && git commit -m "verify: {title} ({change-id})"
+```
+
+## Phase 5: Archive
+
+Require `verify` and a clean working tree. Load `pc-plan-archive` in autonomous mode with `{change-id}`. It owns archive verification and retry.
+
+Require `ARCHIVED_OK` and the archive path, then commit:
+
+```bash
+git add openspec/changes/ && git commit -m "archive: {title} ({change-id})"
+```
+
+Tick `archive` when the archive commit exists.
+
+## Phase 6: Output
+
+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
+
+Print the final report from the [output procedure](output.md). Tick `report` only after every checklist item is complete.

package/skills/pc-plan-goal/branching.md

@@ -1,39 +1,39 @@
-# Branching procedure
-
-Resolve and record the branch names. If the invoking workflow already placed you on a feature branch (`feature/*`, `fix/*`, etc.), it owns the branch: do not stash, switch, pull, or rename. The sandbox hosting the workflow has no git credentials, so those commands would either corrupt the tree or hang, and the workflow has already cut the branch from the default branch. Treat its result as given.
-
-```bash
-BRANCH="$(git branch --show-current)"
-case "$BRANCH" in
-  feature/*|fix/*|chore/*|docs/*|refactor/*)
-    START_BRANCH="$BRANCH"
-    DEFAULT_BRANCH="$BRANCH"
-    GOAL_STASH="none"
-    ;;
-  *)
-    START_BRANCH="$BRANCH"
-    DEFAULT_BRANCH="$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')"
-    [ -z "$DEFAULT_BRANCH" ] && DEFAULT_BRANCH="main"
-
-    # Stash uncommitted work when needed and record that the goal stash exists.
-    git stash push -u -m "goal-wip"
-    GOAL_STASH="goal-wip"
-
-    # Create the feature branch from the synchronized default branch.
-    git switch "$DEFAULT_BRANCH"
-
-    if git remote get-url origin >/dev/null 2>&1; then
-      git pull origin "$DEFAULT_BRANCH"
-    fi
-
-    git switch -c "feature/{slug}"
-    BRANCH="$(git branch --show-current)"
-    ;;
-esac
-```
-
-Record the branch name and that `feature/{slug}` was applied unconditionally, so downstream phases can restore if they move off it.
-
-Everything through archive happens on `$BRANCH`.
-
-When a later phase renames `$BRANCH` to match the canonical change slug (Phase 3 of `pc-plan-goal`), skip the rename if the workflow already fixed the name. Renaming would call `git branch -m`, which a credentialless sandbox refuses, and the workflow's `create_pull_request` is told to use the branch as named. Detect this by checking that `$BRANCH` already starts with `feature/`; if it does, keep it.
+# Branching procedure
+
+Resolve and record the branch names. If the invoking workflow already placed you on a feature branch (`feature/*`, `fix/*`, etc.), it owns the branch: do not stash, switch, pull, or rename. The sandbox hosting the workflow has no git credentials, so those commands would either corrupt the tree or hang, and the workflow has already cut the branch from the default branch. Treat its result as given.
+
+```bash
+BRANCH="$(git branch --show-current)"
+case "$BRANCH" in
+  feature/*|fix/*|chore/*|docs/*|refactor/*)
+    START_BRANCH="$BRANCH"
+    DEFAULT_BRANCH="$BRANCH"
+    GOAL_STASH="none"
+    ;;
+  *)
+    START_BRANCH="$BRANCH"
+    DEFAULT_BRANCH="$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')"
+    [ -z "$DEFAULT_BRANCH" ] && DEFAULT_BRANCH="main"
+
+    # Stash uncommitted work when needed and record that the goal stash exists.
+    git stash push -u -m "goal-wip"
+    GOAL_STASH="goal-wip"
+
+    # Create the feature branch from the synchronized default branch.
+    git switch "$DEFAULT_BRANCH"
+
+    if git remote get-url origin >/dev/null 2>&1; then
+      git pull origin "$DEFAULT_BRANCH"
+    fi
+
+    git switch -c "feature/{slug}"
+    BRANCH="$(git branch --show-current)"
+    ;;
+esac
+```
+
+Record the branch name and that `feature/{slug}` was applied unconditionally, so downstream phases can restore if they move off it.
+
+Everything through archive happens on `$BRANCH`.
+
+When a later phase renames `$BRANCH` to match the canonical change slug (Phase 3 of `pc-plan-goal`), skip the rename if the workflow already fixed the name. Renaming would call `git branch -m`, which a credentialless sandbox refuses, and the workflow's `create_pull_request` is told to use the branch as named. Detect this by checking that `$BRANCH` already starts with `feature/`; if it does, keep it.

package/skills/pc-plan-goal/failure-policy.md

@@ -1,30 +1,30 @@
-# Failure policy
-
-`/plan-goal` never asks for input, but must halt instead of shipping broken or incoherent work.
-
-Use the failure policy when:
-
-- exploration cannot produce a safe and coherent functional interpretation after its one retry,
-- exploration determines the goal is infeasible or outside the repository's feasible responsibility,
-- the proposal produces no actionable tasks,
-- the proposal materially contradicts the exploration brief,
-- a task wave stalls because tasks remain but none are eligible,
-- a task exhausts its single retry,
-- tests, lint, build, type checks, or required verification fail and cannot be cleared by re-waving,
-- any verification command (lint, typecheck, test) exits non-zero after the apply phase and re-waving does not clear it,
-- archive verification still prints `ARCHIVE_FAILED` after one retry,
-- required repository state is missing or inconsistent before output,
-- or a merge conflict cannot be resolved cleanly and automatically.
-
-On failure:
-
-1. Stop the pipeline.
-2. Do not merge.
-3. Do not push the default branch.
-4. Leave `$BRANCH` intact whenever it exists.
-5. Abort any incomplete merge.
-6. Restore the Phase 1 goal stash on `$START_BRANCH`.
-7. If stash restoration conflicts, preserve the stash and report its reference.
-8. Report: the failed phase, the exact failed postcondition, commands or verification that failed, retry attempts, current branch, repository state, completed commits, archive state, and the safest manual next step.
-
-For loop-engineering, a clean failure with the feature branch preserved is the correct outcome. Never merge or ship unverified work.
+# Failure policy
+
+`/plan-goal` never asks for input, but must halt instead of shipping broken or incoherent work.
+
+Use the failure policy when:
+
+- exploration cannot produce a safe and coherent functional interpretation after its one retry,
+- exploration determines the goal is infeasible or outside the repository's feasible responsibility,
+- the proposal produces no actionable tasks,
+- the proposal materially contradicts the exploration brief,
+- a task wave stalls because tasks remain but none are eligible,
+- a task exhausts its single retry,
+- tests, lint, build, type checks, or required verification fail and cannot be cleared by re-waving,
+- any verification command (lint, typecheck, test) exits non-zero after the apply phase and re-waving does not clear it,
+- archive verification still prints `ARCHIVE_FAILED` after one retry,
+- required repository state is missing or inconsistent before output,
+- or a merge conflict cannot be resolved cleanly and automatically.
+
+On failure:
+
+1. Stop the pipeline.
+2. Do not merge.
+3. Do not push the default branch.
+4. Leave `$BRANCH` intact whenever it exists.
+5. Abort any incomplete merge.
+6. Restore the Phase 1 goal stash on `$START_BRANCH`.
+7. If stash restoration conflicts, preserve the stash and report its reference.
+8. Report: the failed phase, the exact failed postcondition, commands or verification that failed, retry attempts, current branch, repository state, completed commits, archive state, and the safest manual next step.
+
+For loop-engineering, a clean failure with the feature branch preserved is the correct outcome. Never merge or ship unverified work.

package/skills/pc-plan-goal/output-mode.md

@@ -1,10 +1,10 @@
-# Output mode
-
-Determine the mode only from the first whitespace-delimited token of `$ARGUMENTS`.
-
-- `pr`: remove the token, push the feature branch, and create a PR.
-- `push`: remove the token and push the feature branch.
-- `branch`: remove the token, keep the feature branch, merge nothing and push nothing.
-- Any other first token: keep the full input and merge locally into the default branch.
-
-Words such as "push notifications" or "PR template" inside the feature description are feature data. They do not change output mode.
+# Output mode
+
+Determine the mode only from the first whitespace-delimited token of `$ARGUMENTS`.
+
+- `pr`: remove the token, push the feature branch, and create a PR.
+- `push`: remove the token and push the feature branch.
+- `branch`: remove the token, keep the feature branch, merge nothing and push nothing.
+- Any other first token: keep the full input and merge locally into the default branch.
+
+Words such as "push notifications" or "PR template" inside the feature description are feature data. They do not change output mode.

package/skills/pc-plan-goal/output.md

@@ -1,71 +1,71 @@
-# Output procedure
-
-Before output, require `verify`, `archive`, a clean working tree, no active change directory, and an archive directory for `{change-id}`.
-
-## Restore stash
-
-If the goal created `goal-wip`, restore it after the mode-specific operation. When restoration conflicts, leave the stash intact, report its `git stash list` reference, and do not drop user work.
-
-## Default mode
-
-Synchronize the default branch, merge, delete the feature branch, then restore the stash:
-
-```bash
-git switch "$DEFAULT_BRANCH"
-
-if git remote get-url origin >/dev/null 2>&1; then
-  git pull origin "$DEFAULT_BRANCH"
-fi
-
-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.
-
-## Push mode
-
-Push the feature branch:
-
-```bash
-git push -u origin "$BRANCH"
-```
-
-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, and commits. Do not merge the PR.
-
-Restore the stash.
-
-## Branch mode
-
-Leave `$BRANCH` in place with its commits. Merge nothing, push nothing, delete nothing.
-
-Restore the stash.
-
-## Final report
-
-Print:
-
-```text
-Goal: {title}
-Change ID: {change-id}
-Scope classification: focused | standard | complex
-Functional outcome: {one-sentence result}
-Branch: {branch}
-Tasks: {completed}/{total}
-Acceptance criteria: {passed}/{total}
-Commits: {proposal, apply, archive}
-Verification: passed | failed
-Archived: yes | no
-Archive path: {path or none}
-Output mode: default | push | pr | branch
-Final state: merged locally | pushed branch | PR URL | branch preserved | branch preserved after failure
-Stash restoration: not needed | restored | preserved after conflict
-```
-
-## External gate
-
-An unattended caller must verify `openspec list --json` is empty and run the project's lint and typecheck commands before any later git operation.
+# Output procedure
+
+Before output, require `verify`, `archive`, a clean working tree, no active change directory, and an archive directory for `{change-id}`.
+
+## Restore stash
+
+If the goal created `goal-wip`, restore it after the mode-specific operation. When restoration conflicts, leave the stash intact, report its `git stash list` reference, and do not drop user work.
+
+## Default mode
+
+Synchronize the default branch, merge, delete the feature branch, then restore the stash:
+
+```bash
+git switch "$DEFAULT_BRANCH"
+
+if git remote get-url origin >/dev/null 2>&1; then
+  git pull origin "$DEFAULT_BRANCH"
+fi
+
+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.
+
+## Push mode
+
+Push the feature branch:
+
+```bash
+git push -u origin "$BRANCH"
+```
+
+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, and commits. Do not merge the PR.
+
+Restore the stash.
+
+## Branch mode
+
+Leave `$BRANCH` in place with its commits. Merge nothing, push nothing, delete nothing.
+
+Restore the stash.
+
+## Final report
+
+Print:
+
+```text
+Goal: {title}
+Change ID: {change-id}
+Scope classification: focused | standard | complex
+Functional outcome: {one-sentence result}
+Branch: {branch}
+Tasks: {completed}/{total}
+Acceptance criteria: {passed}/{total}
+Commits: {proposal, apply, archive}
+Verification: passed | failed
+Archived: yes | no
+Archive path: {path or none}
+Output mode: default | push | pr | branch
+Final state: merged locally | pushed branch | PR URL | branch preserved | branch preserved after failure
+Stash restoration: not needed | restored | preserved after conflict
+```
+
+## External gate
+
+An unattended caller must verify `openspec list --json` is empty and run the project's lint and typecheck commands before any later git operation.

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.