Extend planner scope with replaceable checklist and presentation

Reviewed-on: #12

.gitea/ISSUE_TEMPLATE.md

@@ -0,0 +1,15 @@
+## Problem
+
+What is broken or missing, and the evidence for it.
+
+## Scope
+
+The intended change, bounded to what one reviewed pull request can carry.
+
+## Acceptance Criteria
+
+- Observable completion criteria, each checkable on the candidate revision.
+
+## Dependencies
+
+Issues that must complete first, if any.

.gitea/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,57 @@
+## Summary
+
+<!-- Keep prose brief. Add the smallest useful diagram, diff-sketch, tree,
+pseudocode, or code block when it makes the change faster to understand. Use
+the project's domain language. -->
+
+## Evidence
+
+- **Before:** the screenshot, output, symptom, or failing test run.
+- **After:** the screenshot, output, corrected behavior, or passing test run.
+
+<!-- For a bug fix, name the confirmed root cause or successful hypothesis.
+Merge evidence stays here; it is not a docs/evidence/ record (see
+docs/agents/standards.md). -->
+
+### Checks run
+
+- `the exact command already run` — observed result.
+
+## Documentation disposition
+
+updated / not_required / deferred / blocked — which one, and why in one line.
+
+<!-- Definitions and the recording rule live in docs/agents/standards.md;
+/cleanup blocks the merge without one. -->
+
+## Merge Danger
+
+**Door:** one-way or two-way — why the change is or is not cheap to reverse.
+
+**Blast Radius:** the affected subsystem, consumers, or behavior.
+
+**Rollback:** the exact rollback path, including any state it cannot restore.
+
+## Reviewer prerequisites
+
+- Required runtime, services, credentials or profiles, operating system,
+  fixtures, clean-state conditions, duration, and meaningful cost; or `None`.
+
+## Manual Test Plan
+
+<!-- Include only behavior that automated evidence cannot prove. -->
+
+1. [ ] **Action:** the exact reviewer action, command, route, control label,
+   field value, or UI interaction. Put every command in a copyable fenced block.
+
+   **Expected:** the observable evidence that the step passed, and any
+   condition that requires the reviewer to stop.
+
+## Post-Merge Cleanup
+
+```sh
+git switch main
+git pull --ff-only origin main
+git branch -d ISSUE-<number>
+git push origin --delete ISSUE-<number>
+```

.gitea/workflows/check.yml

@@ -12,9 +12,7 @@ jobs:
           github-server-url: https://tea.kyle-merritt.com
       - run: python3 --version
       - run: python3 -m unittest discover -s tests -v
-      - run: python3 -m tools.packages check packages/planner-scope
-      - run: python3 -m tools.packages check packages/implementer-handoff
+      - run: for package in packages/*; do python3 -m tools.packages check "$package"; done
       - run: python3 -m tools.packages check examples/starter-planner
-      - run: python3 -m tools.packages pack packages/planner-scope dist/planner-scope.zip
-      - run: python3 -m tools.packages pack packages/implementer-handoff dist/implementer-handoff.zip
+      - run: for package in packages/*; do python3 -m tools.packages pack "$package" "dist/${package##*/}.zip"; done
       - run: python3 -m tools.packages pack examples/starter-planner dist/starter-planner.zip

AGENTS.md

@@ -0,0 +1,37 @@
+## Agent skills
+
+### Issue tracker
+
+Gitea issues, driven by the `gitea-issues` helpers.
+See `docs/agents/issue-tracker.md`.
+
+### Domain docs
+
+single layout: CONTEXT.md and ADRs live per `docs/agents/domain.md`.
+
+### Work queue
+
+Priority lives in the `type/roadmap` issue's ordered queue; see `docs/agents/queue.md`.
+
+### Working standards
+
+Docs and tests are first-class artifacts; the tracker is the queue, repository
+documents the durable memory. Read the issue's epic and related issues
+before planning; build test-first at the spec's pre-agreed seams; record each
+change's documentation disposition and the evidence behind its merge; commands
+presented as runnable must be ready to run as written. See
+`docs/agents/standards.md`.
+
+### Focused checks
+
+`python3 -m unittest discover -s tests -v`
+
+Run on the exact current head during implementation and review follow-ups;
+any later change makes this evidence stale.
+
+### Epic gate
+
+`python3 -m unittest discover -s tests -v`
+
+The complete gate, reserved for final epic acceptance — run once on the exact
+integrated commit.

NOTICE.md

@@ -2,6 +2,60 @@
 
 The instruction packages and authoring tools in this repository are licensed under the MIT License in [LICENSE](LICENSE). Include that license and copyright notice when redistributing a package or fork.
 
-This release has no third-party runtime dependencies, vendored assets, or third-party package notices. Python's standard library runs the authoring checks and is not bundled into a skill package.
-
 The RelayView owner, its private prompts, and its separate open trust modules are outside this repository and its MIT grant.
+
+The optional role guidance is written for RelayView from the owner's personal skill collection. Several source skills trace to Matt Pocock's skills at revision `c55ee46073ed923f86ce59a5eb3b6d895095d1b7`; the `c4-diff` source skill traces to Jo Van Eyck's skills at revision `f2de8f7042a5125116ed27627fc7320b73048469`. Their MIT copyright and permission notices are preserved below. No plugin text, code, or assets are redistributed. This release has no third-party runtime dependencies or vendored executable assets. Python's standard library runs the authoring checks and is not bundled into a skill package.
+
+The three investigation packages are original RelayView guidance released under
+this repository’s MIT license. They express the role-local investigation method;
+no private owner implementation, protocol, or other private prompt is included.
+Their identical investigation.md resources share one method across separately
+scoped packages.
+
+## Matt Pocock source-skill notice
+
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## Jo Van Eyck source-skill notice
+
+MIT License
+
+Copyright (c) 2026 Jo Van Eyck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -6,11 +6,55 @@ Public source for RelayView-maintained instruction-only role skills and an illus
 
 | Directory | Status | Role / step | Version |
 | --- | --- | --- | --- |
-| `packages/planner-scope` | Maintained default | Planner / planning | 0.2.0 |
+| `packages/{planner,implementer,reviewer}-investigation` | Maintained automatic guidance | One matching role / step each | 0.7.0 |
+| `packages/planner-scope` | Maintained default | Planner / planning | 0.8.0 |
 | `packages/implementer-handoff` | Maintained default | Implementer / implementation | 0.2.0 |
+| `packages/issue-designer-default` | Maintained default | Designer / design | 0.6.1 |
+| `packages/designer-wayfinder`, `designer-grilling` | Optional manual guidance | Designer / design | 0.6.0 |
+| `packages/designer-prototype` | Optional manual guidance | Designer / design | 0.6.2 |
+| `packages/designer-research`, `designer-domain-modeling`, `designer-triage` | Optional manual guidance | Designer / design | 0.6.0 |
+| `packages/designer-to-spec`, `designer-to-tickets` | Optional manual guidance | Designer / design | 0.6.0 |
+| `packages/codebase-design` | Optional guidance | Planner / planning | 0.3.0 |
+| `packages/grill-me` | Optional guidance | Planner / planning | 0.3.0 |
+| `packages/grilling` | Optional guidance | Planner / planning | 0.3.0 |
+| `packages/to-questionnaire` | Optional guidance | Planner / planning | 0.3.0 |
+| `packages/research` | Optional guidance | Planner / planning | 0.3.0 |
+| `packages/improve-codebase-architecture` | Optional guidance | Planner / planning | 0.3.0 |
+| `packages/diagnosing-bugs` | Optional guidance | Implementer / implementation | 0.3.0 |
+| `packages/domain-modeling` | Optional guidance | Implementer / implementation | 0.3.0 |
+| `packages/migrate-to-shoehorn` | Optional guidance | Implementer / implementation | 0.3.0 |
+| `packages/pr` | Optional guidance | Implementer / implementation | 0.3.0 |
+| `packages/prototype` | Optional guidance | Implementer / implementation | 0.3.0 |
+| `packages/scaffold-exercises` | Optional guidance | Implementer / implementation | 0.3.0 |
+| `packages/shared-abstraction-refactor` | Optional guidance | Implementer / implementation | 0.3.0 |
+| `packages/split-large-files` | Optional guidance | Implementer / implementation | 0.3.0 |
+| `packages/tdd` | Optional manual guidance | Implementer / implementation | 0.3.0 |
+| `packages/tdd-auto` | Optional automatic guidance | Implementer / implementation | 0.3.1 |
+| `packages/writing-for-agents` | Optional guidance | Implementer / implementation | 0.3.0 |
+| `packages/code-review` | Optional guidance | Reviewer / review | 0.3.0 |
+| `packages/c4-diff` | Optional guidance | Reviewer / review | 0.3.0 |
 | `examples/starter-planner` | Illustrative starter; not a production default | Planner / planning | 0.1.0 |
 
-Only named releases of maintained defaults receive RelayView compatibility testing and maintenance. User forks are maintained by their publishers. This release uses the instruction package schema version 1 admitted by RelayView's Community MVP. It contains only `SKILL.md`, declared `.md`/`.txt` resources, and `relayview-skill.json` within each package. Scripts, executable files, undeclared files, and requested permissions fail checks and owner admission. There is no fixed release calendar: maintained packages are versioned when their content or compatibility changes. A breaking owner contract requires a new compatible maintained release before the product depends on it.
+Only named releases of maintained packages receive RelayView compatibility testing and maintenance. Optional guidance requires explicit role assignment; the Planner and Implementer defaults remain available alongside the pinned Issue Designer default. User forks are maintained by their publishers. This release uses the instruction package schema version 1 admitted by RelayView's Community MVP. It contains only `SKILL.md`, declared `.md`/`.txt` resources, and `relayview-skill.json` within each package. Scripts, executable files, undeclared files, and requested permissions fail checks and owner admission. There is no fixed release calendar: maintained packages are versioned when their content or compatibility changes. A breaking owner contract requires a new compatible maintained release before the product depends on it.
+
+## A named set in RelayView
+
+A named set groups admitted packages for one role and workflow step. In **Settings → Skills**, the Reviewer has **Reviewer inspection on request** selected as its manual set. Its saved and effective choices match, so future Reviewer sessions capture these two skills for manual invocation. The automatic selector remains at its configured default, which is empty in this example.
+
+![RelayView Settings Skills Reviewer card with the manual set Reviewer inspection on request saved and effective, containing Code review followed by Component diff](docs/images/reviewer-manual-skill-set.png)
+
+The screenshot's ordered manual members come from this excerpt under `trustedSkills.sets` in the owner configuration. Both member IDs must also be admitted in `trustedSkills.catalog`; defining a set makes it available, while selecting and saving it makes it effective for future sessions.
+
+```yaml
+- id: reviewer-inspection
+  name: Reviewer inspection on request
+  role: reviewer
+  step: review
+  invocationMode: manual
+  members: [code-review, c4-diff]
+```
+
+The maintained defaults are original RelayView packages. Some optional guidance adapts earlier MIT-licensed skills; see the [third-party notices](NOTICE.md).
 
 ## Fork the starter
 
@@ -24,9 +68,19 @@ python -m tools.packages pack examples/starter-planner dist/starter-planner.zip
 
 Replace `examples/starter-planner` in the last two commands with your package directory. The `pack` command writes a reproducible ZIP containing the package, `LICENSE`, and `NOTICE.md`, then prints its SHA-256. The check returns the owner's package identity digest. Both use only Python 3's standard library and this repository's source. Preserve the license and notice when redistributing the package or fork.
 
-To import a user fork, place its closed package directory under the owner's configured trusted root, use Settings → Skills to import the relative `SKILL.md` path under a new unique ID, and assign it to the matching future role step. Saving a new assignment takes effect after owner restart; existing sessions retain their captured bytes. The Settings catalog displays source, version, digest, role, step, and pending versus effective assignment. The owner's admission remains authoritative even when these local checks pass.
+To use a user fork, place its closed package directory under the owner's configured trusted root. For Planner, Implementer, or Reviewer guidance, use Settings → Skills to import the relative `SKILL.md` path under a new unique ID. Import validates and records the package; it does not assign it. Add that ID to a role-compatible named set in the owner configuration and restart the owner to load the set. Then select the set for the matching role in Settings → Skills and save. For an optional Designer method, declare its ID and relative `SKILL.md` path in `trustedSkills.catalog`, list the ID in `workflowPresets.designerSkills`, and restart the owner. Designer has no Settings import or set selector for this assignment. These assignments affect future sessions; existing sessions retain their captured bytes. The owner's admission remains authoritative even when these local checks pass.
 
-To use a maintained default, copy its release package under the same trusted root, admit its `SKILL.md` through the owner catalog, then select it for its declared role in Settings. Settings import accepts user-source packages; configure first-party packages in the owner catalog. Select a fork with `source.kind: user` and a distinct ID to replace that role's future assignment. Planner guidance uses existing read and planning tools; Implementer guidance uses existing implementation and reporting tools. Neither selection changes a role's tools, credentials, lifecycle stages, validation requirements, Gitea effects, review, merge, or Human acceptance. The owner keeps the existing Gitea task workflow.
+To use a maintained Planner or Implementer default, copy its release package under the same trusted root, admit its `SKILL.md` through the owner catalog, then select it for its declared role in Settings. Settings import accepts user-source packages; configure first-party packages in the owner catalog. Select a fork with `source.kind: user` and a distinct ID to replace a Planner or Implementer future assignment. RelayView pins and assigns the Issue Designer default automatically; its optional methods use `workflowPresets.designerSkills`. Planner guidance uses existing read and planning tools; Implementer guidance uses existing implementation and reporting tools. Guidance selection does not change a role's tools, credentials, lifecycle stages, validation requirements, Gitea effects, review, merge, or Human acceptance. The owner keeps the existing Gitea task workflow.
+
+## Write the guidance
+
+A package's instructions are read by a model, so write them for one. Before adding an instruction, especially in response to behavior seen in a run, ask:
+
+- Can RelayView's owner determine the result from facts it holds? Then the owner should produce it, and the guidance should use it.
+- Does the text state the action to take and a check the agent can run on the result, rather than what to avoid?
+- Does the environment the agent works in differ from the familiar one it expects? Name each difference and the action that handles it.
+
+Judge a change over several runs, using the tool calls each run made, not one successful conversation. RelayView's `docs/authoritative/architecture-heuristics.md`, under "Model-Facing Work", records these defaults in full.
 
 ## Release identity
 

docs/agents/domain.md

@@ -0,0 +1,56 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists: it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/authoritative/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/authoritative/adr/` for context-scoped decisions. The rest of `docs/authoritative/` holds current product design, contracts, and constraints.
+- **`docs/evidence/`**: curated observations that inform a foundational design decision. Read a record when you need to understand or challenge the decision it supports; it informs that decision but never overrides the authoritative document. Its `README.md` sets what qualifies.
+- **`docs/historical/`**: superseded designs, archived handoffs, and development records, including one issue's retained work under `docs/historical/issue-notes/<issue-number>/`. Read these to understand how the project arrived at its current state — never as current behavior.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved; `/cleanup`-bound work moves superseded context into `docs/historical/` per `docs/agents/standards.md`.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   ├── authoritative/adr/
+│   │   ├── 0001-event-sourced-orders.md
+│   │   └── 0002-postgres-for-write-model.md
+│   ├── evidence/                      ← foundational design evidence
+│   └── historical/issue-notes/186/    ← one issue's retained records
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/authoritative/adr/            ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/authoritative/adr/    ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/authoritative/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_

docs/agents/issue-board.toml

@@ -0,0 +1,2 @@
+[status_board]
+project_id = 12

docs/agents/issue-tracker.md

@@ -0,0 +1,135 @@
+# Issue tracker: Gitea
+
+Issues, specs, and pull requests for this repo live on its Gitea host. Use the
+deterministic helpers from the `gitea-issues` skill for every operation — never
+hand-write API calls. Resolve `<gitea-issues>` from the installed skill path.
+
+## Conventions
+
+- **Read an issue**: `python <gitea-issues>/scripts/gitea.py issue read --issue <number> --comments`
+- **Rename an issue**: `issue update-title --issue <number> --title "New title"` (optionally `--expected-title "Old title"` or `--expected-content-version <version>`)
+- **List issues**: `python <gitea-issues>/scripts/gitea.py issue list --state open` (add `--label` / `--exclude-label` filters, `--output json` for structure)
+- **Create an issue**: `issue create --title "..." --body-file - --label status/ready-for-agent` with the body on standard input, using the `## Problem` / `## Scope` / `## Acceptance Criteria` structure
+- **Comment**: `issue comment --issue <number> --body "..."`
+- **Change status**: `issue set-status --issue <number> --status status/<role>`
+- **Edit classification**: `issue edit-labels --issue <number> --add <label> --remove <label>` (repeat either flag; omit either when unused)
+- **Start implementation**: `issue start --issue <number>` — creates the `ISSUE-<number>` branch in a dedicated worktree and prints the path every later command must use
+- **Close reviewed work**: `pr cleanup` merges the reviewed pull request and reconciles the issue; `issue close --status status/done` closes an explicitly authorized resolved decision, and `--status status/wontfix` closes declined non-implementation work with a short marker-backed explanation
+- **Clean up a merged worktree**: `issue remove-worktree --issue <number> --pull <number>` — fast-forwards local `main` to the fetched remote tip (stopping with resolution commands before any deletion when it cannot) and removes the worktree and its branch
+
+Repository identity comes from the `origin` remote or the resolved credentials;
+the helpers never need a token pasted into chat.
+
+`issue update-title` sends a title-only edit with Gitea's preflight
+`content_version` check and verifies a fresh readback. Gitea does not provide
+an atomic title compare-and-swap, so a concurrent edit can still race. The
+command directs a check of the actual owning roadmap or epic entry and reports
+child `Parent:` lines that need separate guarded repair. Its own `Parent:` line
+is only a hint; preserve entry order and checkboxes.
+
+Read-only commands (`issue list`, `queue roadmap|inspect|next`, `epic
+next-ready`/`start-next` selection) reuse unchanged reads through a
+conditional cache that never touches mutation preflights or read-after-write
+verification. Disable it with `GITEA_READ_CACHE=off`, inspect it with
+`read-cache status`, and clear it with `read-cache clear`; see the skill's
+`references/read-cache.md` for the freshness contract.
+
+## Label vocabulary
+
+Status labels are the agent-writeable source of truth. When a status Project is
+configured in `docs/agents/issue-board.toml`, successful lifecycle commands
+request card reconciliation through `issue-project-board`. The board displays
+status and prerequisites; the roadmap remains the priority source:
+
+`status/needs-triage`, `status/needs-info`, `status/ready-for-agent`,
+`status/ready-for-human`, `status/in-progress`, `status/review`,
+`status/done`, `status/wontfix`, plus `priority/P0` as an exceptional interrupt
+indicator. Type labels (`type/epic`, `type/feature`, `type/bug`, …) and area
+labels classify work. Install missing names idempotently with
+`labels setup --dry-run` then `labels setup`; existing labels are preserved.
+`board/archived` is a non-status label for a closed `status/done` or
+`status/wontfix` issue kept searchable outside the status board. Initial board
+migration and later selected archival require reviewed previews in
+`issue-project-board`; ordinary closure still adds a Done or Won't Fix card.
+`board/finalizing` marks an in-progress epic whose listed children are closed
+`status/done` while final gates are checked. Other in-progress epics appear in
+Active Epics; individual work stays in In Progress. Existing eight-column
+boards use the reviewed `issue-project-board` migration.
+See `docs/agents/triage-labels.md` for the triage-role mapping and
+`docs/agents/queue.md` for the roadmap contract.
+
+`issue edit-labels` changes only named existing non-status labels, preserving
+unrelated labels. It validates every requested name before writing, adds before
+removing, and verifies the requested result with a fresh read. A satisfied
+replay writes nothing. Use `issue set-status` for `status/*` transitions.
+Writes are incremental: after a write or verification failure, reconcile with
+`issue read` before retrying. Changing `type/epic` does not create child order,
+blocking edges, or roadmap placement; use their separate helper operations.
+
+## The repository work queue
+
+Exactly one open issue labelled `type/roadmap` holds the
+`## Work Queue In Priority Order` section that defines repository priority;
+epics order children the same way. Each list entry uses `- [ ] #123 Title` or
+`- [x] #123 Title`; checkboxes display closed `status/done` progress and do
+not change workflow state. `queue inspect` reports disagreements. Convert
+numbered lists only through reviewed `checklist preview` and guarded
+`checklist apply`. Dependencies gate execution; they never define priority.
+
+- **Inspect**: `queue inspect` (health, skipped entries, tree-invariant violations, selected leaf)
+- **Read placement state**: `queue roadmap` (top-level order and content version)
+- **Select read-only**: `queue next`
+- **Maintain**: `queue init` (idempotent), `queue insert --issue <n> --position <p> --expected-content-version <v>`, `queue reorder`, `queue link-children preview` / `apply --confirm` (direct-child blocking edges)
+- **Move to `independent` mode**: the reviewed edge migration — `migration preview --history --write-plan <file>`, `migration freeze`, `migration apply --plan <file>`, `migration readiness`, then a reviewed configuration commit (see the gitea-issues `references/repository-queue.md`)
+
+Only top-level delivery epics and explicitly standalone issues
+(`--allow-standalone`) enter the roadmap. When the user has not stated a
+priority, new work enters at the default position from the gitea-issues
+queue-placement contract — the highest its dependencies allow — and an
+explicit statement always wins. The queue tree carries one
+invariant — every open issue except the roadmap itself sits on exactly one
+priority list and blocks that parent — specified in full in the gitea-issues
+`references/repository-queue.md` reference. Inserting an open entry — epic or
+standalone — links it as blocking the roadmap, so the Gitea UI **Blocks**
+section links each level to the root; the roadmap never takes dependency
+edges beyond its direct children (its queue entries). `queue link-children`
+repairs missing direct-child edges.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external
+PRs as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, external PRs run through the same status labels as issues:
+read them with `issue read --issue <number> --comments`, label with
+`issue set-status`, and triage contributor PRs (not owner/maintainer work)
+through `/triage`.
+
+## When a skill says "publish to the issue tracker"
+
+Create a Gitea issue with `issue create`, then place it explicitly: group
+implementation work under a delivery epic (children linked with
+`epic add-dependency --parent <epic> --child <child>`, the legacy alias of
+`prerequisite add --issue <epic> --requires <child>`, and ordered in the epic's
+`## Child Issues In Priority Order` section) and insert only the epic — or an
+explicitly standalone issue — into the roadmap with `queue insert`. Creation
+and placement stay two separate, reconcilable operations; when the user gave
+no priority, apply the default-placement rule from that contract and say so
+with the proposal, and publish unqueued only when placement is genuinely
+unresolved.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `issue read --issue <number> --comments`.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue labelled `wayfinder:map`;
+its **child tickets** are plain issues that block the map.
+
+- **Map**: `issue create --title "..." --label wayfinder:map` holding the Notes / Decisions-so-far / Fog body.
+- **Child ticket**: an issue labelled `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`) with `Part of #<map>` at the top of its body, linked to the map with `prerequisite add --issue <map> --requires <n>` (the map waits for each ticket).
+- **Blocking**: Gitea dependency links — the map is blocked by every child. `issue read` reports open blockers, which are the live gate.
+- **Frontier query**: `issue list --state open --label wayfinder:map`-scoped children (list open issues, keep those mentioning `Part of #<map>`), drop any with an open blocker or `status/in-progress`; first in map order wins.
+- **Claim**: move the ticket to `status/in-progress` with `issue set-status`.
+- **Resolve**: `issue comment --issue <n> --body "<answer>"`, then use `issue close --issue <n> --status status/done --comment "Decision accepted; see the resolution comment."` for an explicitly authorized accepted decision; use `status/wontfix` for declined work and `pr cleanup` for PR-backed implementation. Gist the decision into the map's Decisions-so-far.

docs/agents/issue-workflow.toml

@@ -0,0 +1,8 @@
+# The relationship mode and the one authoritative priority source, read by the
+# gitea-issues helpers from the default branch. Change it only through a
+# reviewed commit: activation, rollback, and source changes are migrations.
+relationship_mode = "legacy"
+
+[priority_source]
+kind = "roadmap"
+issue = 2

docs/agents/queue.md

@@ -0,0 +1,104 @@
+# Work Queue
+
+How this repository decides what is next. The contract in one paragraph: exactly
+one open issue labelled `type/roadmap` carries a `## Work Queue In Priority
+Order` section; that order — with epic `## Child Issues In Priority Order`
+sections beneath it — is repository priority. Dependency links gate execution;
+status labels gate readiness. Neither ever overrides the written order. The
+queue tree carries one invariant — every open issue except the roadmap itself
+sits on exactly one priority list and blocks that parent — specified in full
+in the gitea-issues `references/repository-queue.md` reference. Every open
+direct child of the roadmap — epic or standalone entry — blocks the roadmap,
+one edge per direct child and never edges to the whole backlog, so the Gitea
+UI **Blocks** section links each level of the tree to the root.
+
+Priority lists use `- [ ] #123 Title` and `- [x] #123 Title`. Physical order
+sets priority; the checkbox is a progress display. A checked entry represents
+a closed issue with `status/done`, including an epic accepted and closed
+separately. `status/wontfix` and historical closed issues without
+`status/done` stay unchecked. `queue inspect` reports disagreements; clicks
+never change readiness, closure, or prerequisites. Convert numbered lists
+through reviewed `checklist preview` and guarded `checklist apply`.
+
+## Reading the queue
+
+- **Health and explanations**: `queue inspect` — status counts, skipped
+  entries, unqueued ready work, tree-invariant violations, structural
+  anomalies.
+- **Placement and reconciliation**: `queue roadmap` — targeted top-level order
+  and current `content_version`, without dependency scans.
+- **What is next**: `queue next` — read-only selection of the highest-priority
+  executable leaf, with every higher-ranked skip explained.
+
+Both are read-only. Inspecting never claims anything; claim separately with
+`issue start --issue <number>`, which creates the `ISSUE-<number>` worktree and
+moves the issue to `status/in-progress`.
+
+## Changing the queue
+
+Queue edits are explicit mutations, never side effects of other work:
+
+- `queue init` — create the canonical roadmap if absent (idempotent).
+- `queue insert --issue <n> --position <p> --expected-content-version <v>` —
+  add a top-level epic, or a standalone issue with `--allow-standalone`.
+  Inserting an open entry — epic or standalone — also links it as blocking
+  the roadmap (reported separately from the body write).
+- `queue reorder --issue <n> ... --expected-content-version <v>` — rewrite the
+  top-level order, naming every current entry exactly once.
+- `queue link-children preview` / `apply --confirm` — classify and repair the
+  direct-child blocking edges to the roadmap (read-only preview; confirmed
+  apply creates exactly the missing edges, streaming `[queue]` progress
+  milestones with the terminal summary and exit status authoritative).
+
+Mutations send the optimistic-locking `content_version` printed by `queue roadmap`.
+On any ambiguous result, re-run `queue roadmap` and reconcile before retrying;
+never blindly re-run a mutation.
+
+## Adopting existing epics
+
+Epics created before this contract may carry legacy child-order sections.
+`epic migrate-children preview` inventories them read-only and classifies each
+open epic; the owner confirms each proposed migration, and
+`epic migrate-children apply --epic <n> --expected-content-version <v>`
+rewrites one epic at a time under the queue contract's rules. Ambiguous epics
+go back to the owner with their diagnostics. The gitea-issues
+`references/repository-queue.md` reference documents the full contract.
+
+## Moving to independent mode
+
+In `legacy` mode, which this document describes, a native edge may mean
+containment, navigation, or a prerequisite. A repository moves to
+`independent` mode — edges mean prerequisites only — through a reviewed
+migration, never a setup rerun: `migration preview --history --write-plan <file>` classifies every
+edge read-only, the owner reviews the plan, `migration freeze` makes every
+roadmap-driven helper fail closed, `migration apply --plan <file>` removes
+only the projection edges the evidence proves and writes each placed
+issue's `Parent:` line, `migration readiness` confirms nothing blocks, and a
+reviewed commit of `relationship_mode = "independent"` activates it. The
+gitea-issues `references/repository-queue.md` reference documents recovery
+and rollback.
+
+## Who enters the roadmap
+
+Only two kinds of issue: a top-level delivery epic, and an explicitly
+standalone actionable issue. Epic children never enter the roadmap — they stay
+in the epic's child-priority list plus dependency links, under the
+queue-tree invariant stated above.
+
+## Default placement for new issues
+
+Newly published work with no priority statement from the user enters at the
+default position — the highest its dependencies allow, per the default rule
+in the gitea-issues `references/create-and-organize.md` queue-placement
+contract; an explicit statement from the user always wins. Creation and
+placement remain two explicit, reconcilable operations either way, and
+genuinely unresolved placement still publishes unqueued and stays visible
+under "Unqueued ready work".
+
+## After reviewed work merges
+
+`pr cleanup` merges reviewed work and reconciles its issue. Continuation then
+recommends exactly one follow-up, in order: newly unblocked dependents, the
+current epic's next executable child, the roadmap's next executable leaf, or an
+explicit blocked/empty result. Recommendations only — starting the next issue
+needs its own authorization.

docs/agents/standards.md

@@ -0,0 +1,146 @@
+# Working Standards
+
+The philosophies every session in this repository works under. The
+`## Agent skills` block in the agent instructions carries the one-line rules;
+this document is the authority behind them and is safe to extend per repo.
+
+## Documentation and tests are first-class artifacts
+
+Code may be replaced, but durable decisions, behavior, and lessons must remain
+recoverable from focused documentation and verification artifacts. A future
+agent with no conversation history should be able to determine:
+
+- what the system currently does;
+- which behavior is only proposed, not implemented;
+- why important architectural decisions were made, and which observations
+  informed the foundational ones (`docs/evidence/`);
+- how to verify implemented behavior;
+- which earlier approaches are retained only for context (`docs/historical/`).
+
+## Documents versus the issue tracker
+
+The issue tracker is the queue for actionable work and holds the transient
+working context of one change; repository documents are the durable memory. A
+closed issue thread is not a supported reference for current behavior. When an
+issue resolves a term or a decision, record it in `CONTEXT.md` or an ADR
+rather than leaving it only in the thread; an idea too valuable to lose and
+not actionable enough to be an issue belongs in the domain documents, not in
+an issue comment.
+
+Before addressing an issue, read the issue with its comments, every other
+issue in its epic, and the issues in related epics. Confirm scope, boundaries,
+and dependencies before planning.
+
+## Writing current-truth documents
+
+`CONTEXT.md` and the ADRs describe what the system does, in present tense, as
+a contract — not a narrative of the change that produced them.
+
+- Test every sentence carrying an issue reference by deleting the number: if
+  the sentence stays true, the reference was decoration and goes; if it stops
+  making sense, rewrite it as a statement of current behavior. ADRs keep
+  their references — they are decision records.
+- ADRs are immutable. Never rewrite a decided ADR; mark it superseded and
+  record the replacement decision in a new ADR that links back.
+- State uncertainty explicitly, and label proposed behavior as proposed.
+- When verified behavior lands, reconcile `CONTEXT.md` and the ADRs in the
+  same iteration. Never document behavior that does not exist yet.
+
+## Historical records
+
+`docs/historical/` holds superseded designs, archived handoffs, and
+development records. Use it to understand how the project arrived at its
+current state; never treat it as current behavior. When reconciling
+documents after verified behavior lands, move superseded context that still
+explains decisions or discarded alternatives to `docs/historical/` rather
+than deleting it. Decisions themselves supersede through the ADR mechanism,
+not by moving.
+
+## Design evidence and issue history
+
+Choose a record's destination by its purpose, not its format, rigor, or size:
+
+- `docs/evidence/` holds only curated observations that materially inform a
+  named foundational product-design decision and stay useful after the
+  implementation issue is forgotten. Its `README.md` carries the admission
+  rule, examples, and a lightweight record shape.
+- `docs/historical/issue-notes/<issue-number>/` holds durable records of one
+  issue's work — test runs, review findings, debugging chronology, shakedown
+  or replay reports, handoffs — created only when worth retaining.
+- The pull request or issue holds issue-specific verification that needs no
+  repository archive.
+
+The ADR or authoritative document keeps the decision and its concise
+rationale and may link supporting evidence. Evidence never declares current
+behavior, and issue notes are history, never current truth. A routine change
+needs no new document, directory, or evidence record; an ADR link alone does
+not make verification qualify as evidence.
+
+## Documentation disposition
+
+The implementing session records one documentation disposition on the issue
+or pull request before completion — in an issue comment on trackers without a
+pull-request template. On Gitea, `/cleanup` blocks the merge without one.
+
+`CONTEXT.md` and ADRs are created lazily (see `docs/agents/domain.md`): a
+change that resolves no new term or decision records `not_required` rather
+than forcing a document into existence.
+
+- **updated** — verified behavior was reconciled into `CONTEXT.md` and the
+  ADRs as present-tense contracts;
+- **not_required** — the change made no durable behavioral or architectural
+  difference; say why in one line;
+- **deferred** — documentation work remains; normal completion waits unless
+  the owner explicitly accepts the deferral;
+- **blocked** — documentation cannot be reconciled because implementation or
+  verification evidence is insufficient.
+
+## Build discipline
+
+Tests are part of the specification. Write the failing test first at the
+spec's pre-agreed seams and make it green with the minimal change — red
+before green, one seam, one test per cycle. Test-after is reserved for glue
+and wiring, UI verified by a manual test plan, and throwaway prototypes.
+
+## Verification cadence
+
+During implementation and review follow-ups, run the focused checks for the
+changed areas and their immediate contracts or consumers, on the exact
+current head. A later code, test, configuration, or documentation change
+invalidates the affected evidence and requires those checks again.
+
+Reserve the complete gate declared as the epic gate for the final integrated
+epic commit, before epic acceptance and closure. Existing successful CI
+satisfies it only when bound to that exact commit. Run a repository-wide
+suite earlier only when explicitly requested, when a failure cannot be
+localized, or when a change to shared test infrastructure, root
+configuration, or a foundational contract has an unbounded blast radius — and
+state the reason before starting it.
+
+Do not delete, weaken, skip, or consolidate tests solely to reduce runtime.
+Pruning is legitimate only with evidence that the coverage is obsolete or
+redundant, the behavior preserved at the lowest faithful layer, and the
+verification documentation updated.
+When automated coverage is not practical for an enduring contract, record a
+repeatable manual procedure and its expected result beside that contract.
+
+## Merge evidence
+
+Every pull request carries the evidence that caused it to be merged, recorded
+before the merge: screenshots for a visible interface, brief command output
+for command-line behavior, the focused checks that passed and the exact head
+they ran against when the effect is not observable through any interface.
+Attribute a reported observation to whoever made it rather than presenting it
+as independently verified, and never attach evidence that was not examined.
+An unrecorded verification did not happen. Merge evidence lives on the pull
+request (or under `docs/historical/issue-notes/<issue-number>/` when worth
+retaining); it is not a `docs/evidence/` record.
+
+## Commands given to the user
+
+A command presented as runnable must be ready to run as written — no
+unresolved placeholder such as `/absolute/path/to/...`, `<your-token>`, or an
+unassigned `$VALUE`. When a value cannot be known while drafting, give the
+exact command that discovers it, then the command that consumes it, and say
+how to substitute the result. Use the repository's documented shell where it
+declares one; otherwise prefer POSIX-compatible syntax.

docs/evidence/README.md

@@ -0,0 +1,104 @@
+# Design Evidence
+
+This directory holds curated observations and analyses that materially inform
+a named, **foundational** product-design decision: a durable choice about
+product behavior, architecture, boundaries, core methodology, or a constraint
+that shapes the product across individual implementation issues.
+
+It is not an archive. Most changes add nothing here, and completing an issue
+never requires an entry.
+
+## Admission
+
+Ask: **would a future maintainer need this record to understand, challenge, or
+revisit a foundational product choice after forgetting the implementation
+issue?** If the record's value is only establishing that one change passed its
+checks, or describing how work proceeded, it belongs with the issue instead.
+
+A qualifying record explains:
+
+- which foundational decision or documented design question it informs;
+- what observations bear on the alternatives or constraints, and how;
+- why those observations stay useful beyond the issue that produced them.
+
+Purpose decides, not format, rigor, or size. A rigorous measurement, a passing
+test suite, or a link to an ADR does not qualify a record on its own, and an
+ADR is never created just to give routine verification somewhere to point.
+
+## Where material goes
+
+| Material | Destination |
+| --- | --- |
+| Current product design, contracts, and constraints | `docs/authoritative/`, per `docs/agents/domain.md` |
+| A decision and its concise rationale, including meaningful trade-offs | `docs/authoritative/adr/` |
+| Curated observations materially informing a foundational design choice | `docs/evidence/` |
+| Durable records of one issue's work: test runs, review findings, debugging chronology, shakedown or replay reports, handoffs | `docs/historical/issue-notes/<issue-number>/` |
+| Issue-specific verification that needs no repository archive | the pull request or issue body and comments |
+
+`<issue-number>` is the tracker's issue number: issue 186's retained records
+live below `docs/historical/issue-notes/186/`. Create that directory only when
+something is worth retaining.
+
+The ADR or authoritative document keeps the "why"; it links here when a
+supporting record helps. Evidence informs a decision — it never declares
+current behavior or silently overrides the authoritative document. Issue notes
+are history, never current truth.
+
+## Examples
+
+Qualifies:
+
+- An evaluation of methodology alternatives behind the product's durable
+  grading contract or experimental design.
+- A data-quality study that establishes a foundational dataset-selection or
+  exclusion policy.
+- Accuracy, latency, and resource measurements that explain a core
+  model-serving architecture choice.
+- A failed experiment or contradictory observation that materially informs such
+  a decision, or explains why a serious alternative was rejected.
+
+Does not qualify:
+
+- "Issue 186 passed 260 tests", CI output, coverage summaries, or merge receipts.
+- One patch's replay results, admission or qualification receipts, debugging
+  logs, an implementation chronology, or an agent handoff.
+- A benchmark run, literature collection, or research note with no demonstrated
+  connection to a foundational product-design decision.
+
+Mixed purpose: when issue work reveals a foundational insight, leave the
+original verification and history where they are, and write a focused
+synthesis here that states the design implication and links to those sources.
+Do not promote the whole issue diary or duplicate its raw artifacts.
+
+## Record shape
+
+Keep only the provenance that helps someone assess the design implication.
+Name files by topic or decision (`serving-latency-trade-offs.md`), not by issue
+or test run. There is no required schema; a record usually covers:
+
+```md
+# Serving latency trade-offs
+
+Informs: the model-serving architecture (link the ADR or design document).
+Date and identities: 2026-03-02; code a1b2c3d, dataset v4, model m-7.
+
+## Observations
+
+What was measured or seen, how, and from which source. Keep large raw
+artifacts in their artifact store and reference them by stable location and
+hash.
+
+## Interpretation
+
+What the observations suggest for the alternatives, kept separate from the
+observations themselves. Include counterevidence.
+
+## Limitations and implications
+
+What the evidence cannot show, and what it means for the design.
+```
+
+When a later decision changes the picture, add a linked correction or
+superseding analysis rather than rewriting the old result, so its historical
+qualifications stay visible. Records need not endorse the currently accepted
+choice, but each must stay meaningfully connected to a foundational decision.

packages/c4-diff/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: c4-diff
+description: Explain structural changes in an owner-pinned code diff with traceable before and after component maps.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Component diff
+  relayview-version: 0.3.0
+---
+
+# Component diff review
+
+Use only when the assigned review calls for architectural change analysis. Inspect the exact base and candidate commits pinned by the owner. Map changed source components and their immediate neighbors at both versions; treat a rename as a changed component when identity is preserved. Include a node or edge only when a source path and symbol support it. Classify added, removed, changed, and unchanged relationships, and distinguish structural change from call-order or formatting changes.
+
+Return a compact before/after/diff description or Mermaid component diagrams within the review response, with an evidence path for each changed node and edge. If there is no structural change, say so. Do not fetch refs, write diagram artifacts, run the original diagram script, or alter review state. Ask the owner to resolve a missing or ambiguous commit identity.

packages/c4-diff/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.3.0"
+  },
+  "role": "reviewer",
+  "step": "review",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "f1746262e65a8a3de9223a8c42a30b354a6718fea3819079cd13597a258da567"
+    }
+  ]
+}

packages/code-review/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: code-review
+description: Review the owner-pinned candidate against repository standards and the admitted Plan on separate evidence axes.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Code review
+  relayview-version: 0.3.0
+---
+
+# Two-axis code review
+
+Review only the candidate and commit identity supplied by the owner. Keep standards and Plan fidelity separate. For standards, cite the exact repository rule and changed hunk; identify possible design smells as judgment calls, never as rule violations. A documented local standard takes precedence over a general heuristic. For Plan fidelity, identify missing or partial requirements, unrequested behavior, and behavior whose implementation contradicts the accepted Plan. Cite the Plan clause and code evidence for each finding.
+
+Report both axes even if one has no findings. Distinguish evidence, inference, and uncertainty; skip issues already enforced by tooling unless the enforcement itself failed. Do not edit the candidate, create subagents, choose a new base, change the acceptance state, or request a new review run. The owner controls review scheduling, exact-head binding, and the response to findings.

packages/code-review/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.3.0"
+  },
+  "role": "reviewer",
+  "step": "review",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "c2b05163e738e59573b96f723d5340f56304299bcdf251e38b2d2afb4eda2b5a"
+    }
+  ]
+}

packages/codebase-design/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: codebase-design
+description: Examine module interfaces and seams while drafting a repository Plan.
+metadata:
+  relayview-display-name: Codebase design
+  relayview-version: 0.3.0
+---
+
+# Codebase design for Planner
+
+Use this guidance while deciding the implementation boundary of an assigned Plan. Read the repository's current architecture, relevant code and tests before proposing a module change. Use the [module guide](module-guide.md) to compare interfaces and identify the smallest seam that can carry the requested behavior.
+
+Describe the existing interface, the behavior hidden behind it, and the caller obligations that a change would add or remove. Compare at least two plausible designs in the Plan when the seam is consequential. Record a recommendation with the trade-off and a testable observation, rather than treating a preferred abstraction as verified behavior.
+
+Submit the result through the assigned planning interface. Keep code edits, branch operations, subagent scheduling, and workflow transitions with their existing owner-controlled roles and stages.

packages/codebase-design/module-guide.md

@@ -0,0 +1,8 @@
+# Module guide
+
+- A module is a unit with an interface and an implementation; its interface includes invariants, ordering, errors, configuration, and performance obligations as well as types.
+- Prefer depth: useful behavior behind a small interface. Assess what callers must learn and where future changes will concentrate.
+- A seam is where the interface lives. Name the dependency that varies there and the concrete adapters that justify it; do not add a speculative port for one fixed implementation.
+- Test proposed behavior through the interface visible to callers. Identify the existing tests that would stay meaningful after an internal refactor.
+- Classify dependencies as in-process, locally substitutable, owned remote, or external before recommending an adapter or verification seam.
+- State what each candidate hides, what it exposes, and how an implementer can prove the selected behavior. A diagram or example may clarify a design, but it is not verification evidence.

packages/codebase-design/relayview-skill.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.3.0"
+  },
+  "role": "planner",
+  "step": "planning",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "8633b139187c3ba62e75338f3792ef6d7a445559b792cfb4926cb722609c161a"
+    },
+    {
+      "path": "module-guide.md",
+      "sha256": "7bb0fa0d1a54dce4469e0ceedade86e2efe1e4cd11cac6f1276ed7fb6dca06f5"
+    }
+  ]
+}

packages/designer-domain-modeling/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: designer-domain-modeling
+description: Sharpen project terms, invariants, and boundaries for an issue draft.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Designer domain modeling
+  relayview-version: 0.6.0
+---
+
+# Domain modeling
+
+Read the assigned project's current context and relevant authoritative contracts. Name concepts in the project's own vocabulary; identify identities, state transitions, invariants, and boundaries that the proposed work touches. Ask the Human when a term or invariant changes acceptance. Put the resulting definitions and open choices in the draft without claiming a repository document was edited.

packages/designer-domain-modeling/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.6.0"
+  },
+  "role": "designer",
+  "step": "design",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "cfb72adc02cf0a488c341d965c16e22d22e90c52ab0540a9072b09c592d1abd7"
+    }
+  ]
+}

packages/designer-grilling/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: designer-grilling
+description: Stress test one proposed issue design through focused Human questions.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Designer grilling
+  relayview-version: 0.6.0
+---
+
+# Grilling
+
+State the design and scope to be challenged and seek the Human's agreement before entering this method. Probe one consequential assumption at a time: behavior, boundary, dependency, failure, or verification. Use each answer to choose the next question. Stop when the important branches are resolved or explicitly left open; summarize the agreed design and open decisions in the draft.

packages/designer-grilling/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.6.0"
+  },
+  "role": "designer",
+  "step": "design",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "431da86a21da7b74fa55bce36c1e0fc806d066cd8b1ace7a784e1eb4a2db4a89"
+    }
+  ]
+}

packages/designer-prototype/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: designer-prototype
+description: Plan a bounded throwaway prototype to answer a design question.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Designer prototype
+  relayview-version: 0.6.2
+---
+
+# Prototype
+
+Propose the exact question, bounded code or data scope, expected preview or data effects, and limits to the Human before entering this method. Use only owner-admitted prototype controls after agreement. Treat observations as evidence about the question, not production behavior. Record what was tried, observed, and still uncertain; keep throwaway changes out of the issue's implementation claim.
+
+## Let the Human try it as a user
+
+The Human answers the question by using the prototype the way the software's user will. The commands they type are part of the design under review: the command name, its arguments and options, and the directory it runs from.
+
+- Prepare the scenario yourself before handing over. Create the sample data, repositories, and earlier history the question needs, and run any setup steps, so the scenario is ready when the Human arrives.
+- Put the scenario's data where the app finds it by default, such as its default config or source directory under HOME, so the user's command needs no extra options.
+- Make the Human's first command one the software's user will type: the real command name, the syntax this change proposes, and the arguments a user would pass, run from the directory where a user would be.
+- Give each command to try exactly as that user types it, and say what it shows.
+- Give the Human only the commands needed to answer the design question. Add a reset command only when one of those commands changes the scenario; then put it in `/scratch/bin` and give it by its name alone, followed by the command to try again.
+- Ask the Human about what they saw as a user of the software, in terms of the design question.
+
+## Before handing over
+
+Work through this checklist, then give the Human the shell command and the first command to try:
+
+1. The app's command runs by its own name from `/scratch/bin`: a configured command the owner listed, or a launcher you wrote. Run `cd` to the command directory, then the command with an unknown option, and confirm its usage message names the command as the user types it.
+2. The scenario's data is where the app finds it by default under the workspace's HOME.
+3. Helper commands are in `/scratch/bin`, so the Human runs each by its name.
+4. The command directory is set with `configure` to where the app's user runs the app.
+5. You ran the first command to try yourself, exactly as the Human will type it, from that directory, and it showed what the question is about.

packages/designer-prototype/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.6.2"
+  },
+  "role": "designer",
+  "step": "design",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "b72f085f33c10ea48f69fbe55c4f364f6a873a8ae2e6baeb8eaf2aaf71df5045"
+    }
+  ]
+}

packages/designer-research/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: designer-research
+description: Research a design question using admitted repository, tracker, and public sources.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Designer research
+  relayview-version: 0.6.0
+---
+
+# Research
+
+Frame the question and the decision it informs. Prefer current primary sources and the assigned repository's authoritative documents. Use only the owner's assigned repository, tracker, and brokered public research tools and active request budget. For each conclusion, keep source, observation time, and completeness visible. Distinguish a source statement from your inference and record material gaps in the draft.

packages/designer-research/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.6.0"
+  },
+  "role": "designer",
+  "step": "design",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "676c4291d4bab19c76c0d945eefe21aa6787783e4e2d2285e0d6e270303d1e94"
+    }
+  ]
+}

packages/designer-to-spec/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: designer-to-spec
+description: Turn an agreed problem into a complete reviewable issue specification.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Designer to spec
+  relayview-version: 0.6.0
+---
+
+# To spec
+
+Use the agreed problem and observed project contracts to draft an outcome, scope boundaries, acceptance observations, failure and recovery behavior, and open decisions. Check prerequisites against the assigned tracker and mark uncertain links as proposed. Save the complete text through the owner-stored draft. The Human decides readiness and publication.

packages/designer-to-spec/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.6.0"
+  },
+  "role": "designer",
+  "step": "design",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "c4b8707f88faf1b9f3e04bb707b45bbb3d89848a8a3b2ac807dc819e8dd29f91"
+    }
+  ]
+}

packages/designer-to-tickets/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: designer-to-tickets
+description: Decompose an agreed specification into ordered issue proposals.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Designer to tickets
+  relayview-version: 0.6.0
+---
+
+# To tickets
+
+Choose independently reviewable slices with observable outcomes and prerequisite edges only where one slice truly requires another. For each proposed issue, state scope, acceptance, verification, and context a cold-start agent needs. Present the ordered set and relationship rationale to the Human. Keep proposals private until Human review and owner publication.

packages/designer-to-tickets/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.6.0"
+  },
+  "role": "designer",
+  "step": "design",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "561db3543cfdffe55b8002954d7debcf9d0fc1125d51c688a74cf2469d3d73a1"
+    }
+  ]
+}

packages/designer-triage/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: designer-triage
+description: Classify and route an observed issue before drafting work.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Designer triage
+  relayview-version: 0.6.0
+---
+
+# Triage
+
+Observe the current report and related tracker state. Separate verified symptoms, missing information, proposed behavior, and duplicate or prerequisite work. Suggest the smallest useful next state and explain the evidence for it. Draft an issue or question for Human review; only owner controls can change tracker status or placement.

packages/designer-triage/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.6.0"
+  },
+  "role": "designer",
+  "step": "design",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "fa62a0806921d87ddd27e494cfc379513cc147ad658eb5a2981970ccb25babf5"
+    }
+  ]
+}

packages/designer-wayfinder/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: designer-wayfinder
+description: Map an uncertain design decision into options and a Human choice.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Designer Wayfinder
+  relayview-version: 0.6.0
+---
+
+# Wayfinder
+
+Use this method for a decision whose alternatives materially change the work. First describe the decision, why it matters, and the bounded scope to the Human; enter the method only after the Human agrees. Observe current facts, list viable options with consequences and reversibility, and ask the smallest question that separates them. Record the Human's decision and remaining uncertainty in the owner-stored draft when relevant. This is decision work, not a ready implementation claim.

packages/designer-wayfinder/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.6.0"
+  },
+  "role": "designer",
+  "step": "design",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "c5b5db0755af497cfe9be9fee9912f1406fb3b8546d7f389998516ba298f27b0"
+    }
+  ]
+}

packages/diagnosing-bugs/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: diagnosing-bugs
+description: Build a reproducible feedback loop before fixing an assigned defect.
+metadata:
+  relayview-display-name: Diagnose bugs
+  relayview-version: 0.3.0
+---
+
+# Diagnose within implementation
+
+Begin with the user's exact symptom and the assigned candidate. Build the smallest runnable check that can fail on that symptom using the Implementer's existing tools and workspace. Run it and preserve the observed red result. If the environment cannot reproduce it, report what was tried and request the missing evidence rather than inventing a cause.
+
+Minimize the reproducer. Rank several falsifiable hypotheses, then vary one cause at a time using bounded instrumentation. Redact credentials and private data from every quoted log. For a performance regression, measure the baseline and the changed path with the same fixture.
+
+At the repository's agreed test seam, turn the reproducer into a regression check, observe failure, apply the smallest fix, and observe success. Rerun the original symptom check, remove temporary instrumentation, and report the confirmed cause and exact checks. Validation and review status remain owner-observed facts; this guidance does not mark a gate complete.

packages/diagnosing-bugs/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.3.0"
+  },
+  "role": "implementer",
+  "step": "implementation",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "41c5d0ccb48b19aef95e19103f3c7721b9c3ddf2e8bdf3ff2c429a26853b18ae"
+    }
+  ]
+}

packages/domain-modeling/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: domain-modeling
+description: Reconcile verified domain vocabulary and accepted decisions during implementation.
+metadata:
+  relayview-display-name: Domain modeling
+  relayview-version: 0.3.0
+---
+
+# Domain documentation in implementation
+
+Read the repository's domain glossary and documentation rules before changing a model. When the assigned implementation reveals ambiguous or conflicting terms, compare the proposed meaning with current code, tests, and the accepted Plan. Raise an unresolved decision through the assigned Human communication path; do not turn a guess into an authoritative term.
+
+After a term or consequential design decision is accepted and verified, update the repository's existing glossary or decision record within the assigned worktree. Keep glossary entries about domain meaning rather than implementation mechanics. Record an ADR only for a hard-to-reverse, surprising trade-off whose decision authority and alternatives are known. Keep run-specific test evidence with the issue or review handoff.
+
+This skill changes repository documentation as part of the Implementer's assigned candidate. It does not revise the immutable Plan, create a new workflow checkpoint, or declare review and validation complete.

packages/domain-modeling/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.3.0"
+  },
+  "role": "implementer",
+  "step": "implementation",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "8a4d491493655b19feeb799af625ccef1f9064f203f3e38f57ccd7e547c28be6"
+    }
+  ]
+}

packages/grill-me/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: grill-me
+description: Ask one deliberate question at a time to clarify an assigned Plan.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Grill me
+  relayview-version: 0.3.0
+---
+
+# One-question planning interview
+
+When the Human explicitly invokes this skill during planning, map the unresolved decisions affecting the assigned task. Check the repository and current Plan context for facts before asking. Ask one consequential question at a time, with a recommended answer and its consequence. Wait for the Human's answer before advancing to a dependent question.
+
+Keep a visible list of settled decisions and remaining branches. Stop when the requested scope, important alternatives, and verification expectations are explicit enough for a Plan. Place accepted decisions in the Plan through the assigned planning interface; do not treat an unanswered question as approval. This interview does not start implementation or change an owner workflow stage.

packages/grill-me/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.3.0"
+  },
+  "role": "planner",
+  "step": "planning",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "36895ad26a065b073d3d823557d83b62bd7bb771e74e65e4f246f4e08b52bb16"
+    }
+  ]
+}

packages/grilling/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: grilling
+description: Interview a Planner's Human about independent decision branches in rounds.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Grilling
+  relayview-version: 0.3.0
+---
+
+# Planning decision rounds
+
+When the Human explicitly invokes this skill, draw the decision tree for the assigned Plan. Resolve repository facts with the Planner's assigned read tools. Identify the current frontier: questions whose prerequisites are already settled. Ask that frontier together in one numbered round, giving a recommended answer and consequence for each question. Wait for the Human's answers, update the tree, then recompute the frontier.
+
+Keep dependent questions for later rounds. State when a branch remains unresolved; silence is not a decision. Stop when the frontier is empty and the Human confirms the scope is understood. Record settled requirements and open decisions through the assigned planning interface. Do not launch other agents, edit the repository, or change workflow stages.

packages/grilling/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.3.0"
+  },
+  "role": "planner",
+  "step": "planning",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "1c88593633482d44022eac49de217fc16c8f102067549ba819f1b1ca1728307e"
+    }
+  ]
+}

packages/implementer-investigation/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: implementer-investigation
+description: Investigate source, generated configuration, load order and negative search results within the assigned implementer boundary.
+metadata:
+  relayview-display-name: Implementer investigation
+  relayview-version: 0.7.0
+---
+
+Use the admitted command/filesystem boundary. Inspect relevant package defaults,
+system configuration, runtime state, reference repositories and symlink targets
+read-only when that boundary admits them. Use absolute paths and line numbers
+when reporting external findings. If access is denied, use the owner-provided
+recovery contract and identify the missing evidence.
+
+The included investigation resource supplies the search method.

packages/implementer-investigation/investigation.md

@@ -0,0 +1,14 @@
+# Search and investigation
+
+Trace load order before treating a negative search as evidence of absence. Follow
+includes, imports, sources, require/dofile calls, symlinks and generated outputs
+within the assigned boundary. Identify which file is actually loaded and whether
+a generator or package default supplies its value.
+
+Search interpreted configuration for literal values and expression pieces:
+modifier variables (mainMod, modKey, mod, leader), key or path fragments, function
+and dispatcher names, modes, section names and visible outcomes. For example,
+a binding may join mainMod with " + S" rather than contain "SUPER + S".
+Combine alternatives in one broad search where the assigned search tool supports
+it. When results are empty, check the search method, load order and admitted scope
+before concluding the behavior is missing.

packages/implementer-investigation/relayview-skill.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.7.0"
+  },
+  "role": "implementer",
+  "step": "implementation",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "7775acb6525cf134d33321c3f4d79c074903086dc948138ef747af53f88e8ef5"
+    },
+    {
+      "path": "investigation.md",
+      "sha256": "714f05eb6cd6f68fe7a44ed352fffcc6309a348d9184edb03b4724c16af9228c"
+    }
+  ]
+}

packages/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: improve-codebase-architecture
+description: Assess assigned module-deepening opportunities as read-only planning options with evidence and tradeoffs.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Architecture opportunities
+  relayview-version: 0.3.0
+---
+
+# Architecture opportunity assessment
+
+Use when the planning assignment asks for a bounded architecture assessment. Read the target's domain vocabulary, applicable decisions, and relevant source. Identify where an interface exposes too much complexity, where behavior that changes together has been scattered, or where a module seam makes verification difficult. Apply the deletion test: would removing an apparent abstraction concentrate complexity rather than merely move it?
+
+For each candidate, cite the affected files, current friction, proposed responsibility boundary, effect on locality and test seams, conflict with any existing decision, and a confidence level. Prefer recently active or explicitly named areas. Present options in the planning response and leave unresolved interface choices explicit. Do not spawn exploration agents, generate or open an HTML report, edit domain documents, or initiate a follow-up interview; the owner governs those activities.

packages/improve-codebase-architecture/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.3.0"
+  },
+  "role": "planner",
+  "step": "planning",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "07b2c9f88207a541c493c85fe7faa6d4b3d04eadbcf7ab592f9e5a4187692ee9"
+    }
+  ]
+}

packages/issue-designer-default/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: issue-designer-default
+description: Guide ordinary Issue Designer Chats from observed facts to a reviewable draft.
+metadata:
+  relayview-display-name: Issue Designer default
+  relayview-version: 0.6.1
+---
+
+# Issue Designer default
+
+Check current facts before drafting. Read the assigned repository's relevant authoritative documentation, code, tests, and tracker observations; state the source, observation time, and any incomplete read. Keep proposed behavior separate from verified current behavior.
+
+Choose the scale with the Human: one issue for bounded work, an ordered issue set for dependent work, or a narrower question when the outcome is unclear. Ask only for decisions that change scope, acceptance, or authority. A useful draft states the problem, observable outcome, boundaries, prerequisites, and verification including failure behavior. Preserve unresolved choices explicitly.
+
+Use the owner-stored draft for one issue and the ordered set for dependent work. Give each item a complete body, an explicit readiness basis, and the relationships needed to read it independently. Keep known facts and proposed behavior distinct.
+
+At readiness marking, recheck the current issue and comments when an issue exists, cited authoritative documentation, source and tests, and the target and installed environment facts available through assigned tools or attributed Human observations. Record when and how completely each input was observed. Include non-secret retrieval instructions for a test target, host or service setup, and verification when a future agent will need them. If a material input is stale or unavailable, mark the affected item `needs-info` and name its specific unresolved question and available evidence. Propose `ready-for-agent` only when a new Planner can start from the item and its references without this Chat. The Human reviews the exact set and publishes through owner controls.

packages/issue-designer-default/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.6.1"
+  },
+  "role": "designer",
+  "step": "design",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "d2d4b743cc9bab550910b95a49f9e7c97805510dcb49d66d7a2f79f9c859bf4f"
+    }
+  ]
+}

packages/migrate-to-shoehorn/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: migrate-to-shoehorn
+description: Replace suitable TypeScript test assertions with an admitted partial-fixture helper.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Migrate to shoehorn
+  relayview-version: 0.3.0
+---
+
+# TypeScript test fixture migration
+
+Use this procedure only for an assigned change to TypeScript tests. Inspect the affected assertions and the project's dependency policy before editing. If `@total-typescript/shoehorn` is not installed, use the Implementer's admitted dependency-acquisition path; if that path is unavailable, report the missing prerequisite. Do not install through an unapproved network command.
+
+Replace a partial object assertion with `fromPartial` when the supplied properties should still type-check. Use `fromAny` only for an intentional invalid-input test, and make that purpose visible in the test. Preserve complete fixtures when they express the behavior better. Keep production code free of the helper.
+
+Run focused tests and type checking on the changed test area. State which assertions changed and whether the tests still exercise the intended failure and success paths. This migration does not weaken a behavior contract or count as owner-verified validation by itself.

packages/migrate-to-shoehorn/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.3.0"
+  },
+  "role": "implementer",
+  "step": "implementation",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "56b0d3f5ea1cbf8603201d4f5563e6f582561fe58c5679ed428dc7c29d31e461"
+    }
+  ]
+}

packages/planner-investigation/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: planner-investigation
+description: Investigate source, generated configuration, load order and negative search results within the assigned planner boundary.
+metadata:
+  relayview-display-name: Planner investigation
+  relayview-version: 0.7.0
+---
+
+Use only assigned read roots and the assigned read/search tools. Investigate
+package defaults, generated configuration, runtime state or reference repositories
+only when they are in those roots. If relevant evidence lies elsewhere, identify
+the missing evidence and use the owner-provided supporting-evidence recovery
+contract. Check that each cited file belongs to an assigned root.
+
+The included investigation resource supplies the search method.

packages/planner-investigation/investigation.md

@@ -0,0 +1,14 @@
+# Search and investigation
+
+Trace load order before treating a negative search as evidence of absence. Follow
+includes, imports, sources, require/dofile calls, symlinks and generated outputs
+within the assigned boundary. Identify which file is actually loaded and whether
+a generator or package default supplies its value.
+
+Search interpreted configuration for literal values and expression pieces:
+modifier variables (mainMod, modKey, mod, leader), key or path fragments, function
+and dispatcher names, modes, section names and visible outcomes. For example,
+a binding may join mainMod with " + S" rather than contain "SUPER + S".
+Combine alternatives in one broad search where the assigned search tool supports
+it. When results are empty, check the search method, load order and admitted scope
+before concluding the behavior is missing.

packages/planner-investigation/relayview-skill.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.7.0"
+  },
+  "role": "planner",
+  "step": "planning",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "e1410558c392100d9557d118a9d82e1068ed7a42142bcfe076f09ceed0dac966"
+    },
+    {
+      "path": "investigation.md",
+      "sha256": "714f05eb6cd6f68fe7a44ed352fffcc6309a348d9184edb03b4724c16af9228c"
+    }
+  ]
+}

packages/planner-scope/SKILL.md

@@ -3,7 +3,7 @@ name: planner-scope
 description: Check assigned issue scope, neighboring work, and verification before drafting a Plan.
 metadata:
   relayview-display-name: Planner scope
-  relayview-version: 0.2.0
+  relayview-version: 0.8.0
 ---
 
 # Planner scope
@@ -13,3 +13,5 @@ When drafting the assigned Plan, identify the requested behavior, its boundary,
 If the owner supplies an admitted work-item identity, use the assigned read tools to inspect it. Preserve source attribution; an issue description is a request, not evidence that its proposed behavior exists. Where tracker access is unavailable, state the missing context instead of guessing a work-item identity.
 
 Write the Plan through the owner's assigned planning interface. The Plan is ready when each requested outcome has an implementation boundary and a checkable success or recovery observation. Owner-controlled workflow stages and checks determine execution authority.
+
+For a linked Gitea issue, this package declares the owner's transition from `status/ready-for-agent` to `status/in-progress` after it proves that the exact Plan reached the Implementer. Finalize the Plan through the assigned interface, then use owner-reported handoff and issue-claim outcomes when explaining progress to the Operator. An accepted Plan alone does not establish that claim. A user may replace this skill with a Planner fork whose package declares a different target status or disables the claim; follow the selected package's policy recorded for the task.

packages/planner-scope/relayview-skill.json

@@ -1,19 +1,22 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "source": {
     "kind": "first-party",
-    "reference": "v0.2.0"
+    "reference": "v0.8.0"
   },
   "role": "planner",
   "step": "planning",
+  "issueClaim": {
+    "statusLabel": "status/in-progress"
+  },
   "files": [
     {
       "path": "SKILL.md",
-      "sha256": "31399ba322d8a4d3ed9814e7fd5d54883b4773c5b7dc3a241b8e14f8f7c16072"
+      "sha256": "7dbd2ace7472a75c69b70ea118333429dfc7d56e5374454724805aa783cc0112"
     },
     {
       "path": "scope.md",
-      "sha256": "fc365d5f5c90f878992204235f32b1148aa4934a31f8c10eb063292fb64cf248"
+      "sha256": "abed1a1590273b5f62f1e1f47ba8c92d00693de72c0d5e9b014ed1c911ac0a8e"
     }
   ]
 }

packages/planner-scope/scope.md

@@ -6,3 +6,38 @@
 - Distinguish verified current behavior from a proposal.
 - Identify one observable success path and one meaningful failure or recovery path.
 - Record uncertainty as an open decision; do not turn silence into approval.
+
+Focus on:
+- affected files and symbols
+- existing patterns and architecture
+- invariants and edge cases
+- ordering and dependencies between changes
+- tests, validation, and likely failure modes
+- any assumptions that the implementer must know
+- explicitly authorized supporting context that influences behavior
+
+Return a compact structured plan. Prefer YAML-compatible Markdown:
+
+```yaml
+objective: ...
+constraints:
+  - ...
+steps:
+  - id: ...
+    files:
+      - ...
+    symbols:
+      - ...
+    change: ...
+    requirements:
+      - ...
+    depends_on:
+      - ...
+edge_cases:
+  - ...
+validation:
+  - ...
+open_questions:
+  - ...
+```
+

packages/pr/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: pr
+description: Prepare a reviewable pull-request description for an implemented candidate.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: PR content
+  relayview-version: 0.3.0
+---
+
+# Prepare review content
+
+When the assigned implementation needs a pull-request description, draft text from the current candidate and evidence actually observed. Give the reviewer the behavioral summary, exact candidate revision, focused checks and their outcomes, documentation disposition, material risk, and repeatable manual observations where automation cannot prove behavior. Link to source files or artifacts whose identity you verified.
+
+State failures, limitations, and stale checks plainly. Attribute Human and provider observations to their actual observer; do not present model prose as gate evidence. Keep reviewer commands runnable in the repository's documented shell, with concrete paths or a precise way to discover a missing value.
+
+Deliver the draft through the assigned Implementer report or communication path. PR creation, remote comments, review decisions, publication, and merge remain owner-managed operations unless separately authorized by that workflow.

packages/pr/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.3.0"
+  },
+  "role": "implementer",
+  "step": "implementation",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "86f5c76f96b1f7a4258d21ecd0aeb9ee39cf95fb45eb90e2ee6b172ca460e47a"
+    }
+  ]
+}

packages/prototype/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: prototype
+description: Build a disposable local prototype to answer one implementation question.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Prototype
+  relayview-version: 0.3.0
+---
+
+# Bounded implementation prototype
+
+Name one question the assigned implementation cannot settle by inspection alone: a state transition, algorithm, or visual interaction. Make a small disposable prototype inside the owner-assigned worktree using tools already admitted to the Implementer. Use local fixtures and avoid external services unless the task's existing environment admits them. Make the relevant state or variant visible so the answer can be observed.
+
+Run a small set of cases that could disprove the idea. Record the question, setup, observations, and resulting choice in the implementation handoff. Move only validated behavior into the real candidate and remove disposable scaffolding before reporting a clean candidate. If the prototype itself needs to remain as evidence, request an owner-managed artifact path; do not create or switch Git branches or publish a separate worktree from this skill.

packages/prototype/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.3.0"
+  },
+  "role": "implementer",
+  "step": "implementation",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "319fe249629788f51b3c8738ded5a1c88336534ad96fa43e7c80a554f09ef586"
+    }
+  ]
+}

packages/research/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: research
+description: Ground assigned planning questions in traceable primary sources using only admitted read tools.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Primary-source research
+  relayview-version: 0.3.0
+---
+
+# Primary-source research
+
+Use for a research question assigned within the planning step. Start with the repository's authoritative documents and source. For external facts, use only read or research tools that the owner has admitted to this session and respect their budget and egress policy. Prefer the official specification, documentation, or source repository that owns a claim. Record a source location and the observed version or date when behavior may change; label inferences and unresolved facts.
+
+Put concise findings and citations in the planning response so the Plan can use them. Do not spawn a background agent, save a research file, fetch through an unassigned channel, or treat research as an owner-approved design decision. If evidence cannot be obtained within the assigned access, state the gap.

packages/research/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.3.0"
+  },
+  "role": "planner",
+  "step": "planning",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "78a832c0bae3d3829afcf78c5cee19a08f0a624e0775b29db5e33c038b725d53"
+    }
+  ]
+}

packages/reviewer-investigation/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: reviewer-investigation
+description: Investigate source, generated configuration, load order and negative search results within the assigned reviewer boundary.
+metadata:
+  relayview-display-name: Reviewer investigation
+  relayview-version: 0.7.0
+---
+
+Use only assigned read roots and the assigned read/search tools. Investigate
+package defaults, generated configuration, runtime state or reference repositories
+only when they are in those roots. If relevant evidence lies elsewhere, identify
+the missing evidence and use the owner-provided supporting-evidence recovery
+contract. Check that each cited file belongs to an assigned root.
+
+The included investigation resource supplies the search method.

packages/reviewer-investigation/investigation.md

@@ -0,0 +1,14 @@
+# Search and investigation
+
+Trace load order before treating a negative search as evidence of absence. Follow
+includes, imports, sources, require/dofile calls, symlinks and generated outputs
+within the assigned boundary. Identify which file is actually loaded and whether
+a generator or package default supplies its value.
+
+Search interpreted configuration for literal values and expression pieces:
+modifier variables (mainMod, modKey, mod, leader), key or path fragments, function
+and dispatcher names, modes, section names and visible outcomes. For example,
+a binding may join mainMod with " + S" rather than contain "SUPER + S".
+Combine alternatives in one broad search where the assigned search tool supports
+it. When results are empty, check the search method, load order and admitted scope
+before concluding the behavior is missing.

packages/reviewer-investigation/relayview-skill.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.7.0"
+  },
+  "role": "reviewer",
+  "step": "review",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "f3c6395f3d077ad1a7901cf31ec7656df032292d0181be9dc8a18e36b92769c9"
+    },
+    {
+      "path": "investigation.md",
+      "sha256": "714f05eb6cd6f68fe7a44ed352fffcc6309a348d9184edb03b4724c16af9228c"
+    }
+  ]
+}

packages/scaffold-exercises/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: scaffold-exercises
+description: Build exercise stubs in an assigned course repository using its local structure.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Scaffold exercises
+  relayview-version: 0.3.0
+---
+
+# Exercise scaffolding
+
+Use this skill only when the assigned repository is an exercise course and the Plan calls for new sections or exercises. Read that repository's naming, variant, and lint rules before creating files. Map each requested exercise to its numbered section and variant folders, such as problem, solution, or explainer, using the existing convention. Give every created variant a meaningful nonempty readme; add code files only when the variant needs them.
+
+Create or rename files within the owner-assigned implementation worktree. Run the repository's focused exercise linter and any checks named by the Plan, then correct failures. Report the created structure and observed checks. Do not assume the example `ai-hero-cli` command applies to another repository, and do not publish, merge, or change issue state through this skill.

packages/scaffold-exercises/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.3.0"
+  },
+  "role": "implementer",
+  "step": "implementation",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "a2714d0a09f737b48e8f581f21a5cd7f9ab946e8dca072cfc813ef61c3f1dc18"
+    }
+  ]
+}

packages/shared-abstraction-refactor/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: shared-abstraction-refactor
+description: Find stable repeated patterns in the assigned implementation scope and promote only justified shared abstractions.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Shared abstraction refactor
+  relayview-version: 0.3.0
+---
+
+# Shared abstraction refactor
+
+Use when the assigned Plan calls for a bounded duplication scan or refactor. Read the relevant repository guidance and existing shared surfaces. Search the target paths first, then compare representative uses to determine whether they carry the same meaning. Classify each candidate as reuse an existing abstraction, promote a new one, leave local, or defer.
+
+For an implementation assignment, move only a stable shared concept with a specific name and clear ownership. Update its callers and focused tests, then run the checks required by the Plan. For a scan assignment, return candidates and evidence without editing. Do not widen the assigned scope or create a generic `utils`, `common`, or `misc` bucket merely to remove repeated lines.

packages/shared-abstraction-refactor/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.3.0"
+  },
+  "role": "implementer",
+  "step": "implementation",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "a7906eb68c07ac53cf74525ba02984056c78f205fc6815049959c150c0b1a188"
+    }
+  ]
+}

packages/split-large-files/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: split-large-files
+description: Split assigned oversized files along cohesive responsibilities while preserving their public interface.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Split large files
+  relayview-version: 0.3.0
+---
+
+# Split large files
+
+Use only for the file or subsystem named by the Plan. Map its responsibilities, public interface, related tests, and the symbols that are commonly changed together. Propose a split only when descriptive file names would help a human locate those responsibilities more than the extra imports and cross-file hops would hurt locality. A line count alone is insufficient.
+
+For each proposed extraction, identify its responsibility, new path, moved symbols, import direction, circular-dependency risk, and the existing caller path. Keep cohesive behavior together. Avoid arbitrary line cuts, equal-size partitions, one-file-per-function layouts, and vague utility buckets.
+
+When the Plan authorizes implementation, preserve the existing public interface and import paths unless it explicitly calls for an interface change. Move the approved responsibilities, adjust callers and tests, and run focused verification. If the requested boundary is ambiguous, report the proposed map to the owner rather than expanding the assignment.

packages/split-large-files/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.3.0"
+  },
+  "role": "implementer",
+  "step": "implementation",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "6cca9cdf43e97778b9ea763d0f7f9faed575583150cdbe88796072c78f8c685b"
+    }
+  ]
+}

packages/tdd-auto/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: tdd-auto
+description: Test-driven development for an assigned implementation Plan; use red, green, and focused verification at its agreed test seams.
+metadata:
+  relayview-display-name: Test-driven development
+  relayview-version: 0.3.1
+---
+
+# Test-driven development
+
+Use the test seams and behavior specified by the immutable Plan. Read the target repository's domain language and test conventions. If the Plan leaves a consequential seam unclear, report that gap to the owner; do not create a new acceptance boundary by silently choosing one.
+
+At each seam, write one test that fails for the missing behavior and observe the failure. Implement the smallest production slice that makes it pass. Repeat for the next behavior, then run the focused checks required by the Plan. Assert observable behavior through public interfaces, using expected values independent of the implementation. Avoid private-method assertions, tautological expectations, and a batch of tests for behavior not yet explored. Record the red and green evidence in the implementation handoff.

packages/tdd-auto/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.3.1"
+  },
+  "role": "implementer",
+  "step": "implementation",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "cf4f0cd039dc283caabc3238e3d084c2d59a3f8c8ba030595e9ea80e2b1338e6"
+    }
+  ]
+}

packages/tdd/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: tdd
+description: Implement an assigned behavior at the Plan's agreed test seam using red, green, and focused verification.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Test-driven development
+  relayview-version: 0.3.0
+---
+
+# Test-driven development
+
+Use the test seams and behavior specified by the immutable Plan. Read the target repository's domain language and test conventions. If the Plan leaves a consequential seam unclear, report that gap to the owner; do not create a new acceptance boundary by silently choosing one.
+
+At each seam, write one test that fails for the missing behavior and observe the failure. Implement the smallest production slice that makes it pass. Repeat for the next behavior, then run the focused checks required by the Plan. Assert observable behavior through public interfaces, using expected values independent of the implementation. Avoid private-method assertions, tautological expectations, and a batch of tests for behavior not yet explored. Record the red and green evidence in the implementation handoff.

packages/tdd/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.3.0"
+  },
+  "role": "implementer",
+  "step": "implementation",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "ab633f2670c8d9027301fa985b048ad469b086ed74b1659df8955f2eab9b3a9c"
+    }
+  ]
+}

packages/to-questionnaire/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: to-questionnaire
+description: Draft questions for an outside expert when the assigned Plan needs missing facts.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Planning questionnaire
+  relayview-version: 0.3.0
+---
+
+# Planning questionnaire
+
+When the Human explicitly invokes this skill, identify the facts or decisions the assigned Plan cannot resolve from the repository or admitted sources. Ask who can supply the missing knowledge and what decision their answer will support. Draft a concise questionnaire in the Planner conversation for the Human to send through their chosen channel.
+
+Put the highest-value questions first. Give each question one topic and enough context for an outside recipient to answer without seeing the task history. Include a place to state uncertainty or partial answers. Record the unanswered items as open Plan decisions; incorporate answers only after the Human provides them. Drafting the text neither sends it nor advances the workflow.

packages/to-questionnaire/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.3.0"
+  },
+  "role": "planner",
+  "step": "planning",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "1ccb2b78ffade9faec27b83427a0e3d8fa7f54109b436578f1d79e0ac22d4fe5"
+    }
+  ]
+}

packages/writing-for-agents/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: writing-for-agents
+description: Write assigned agent-facing repository guidance with precise triggers, scope, and verification.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Writing for agents
+  relayview-version: 0.3.0
+---
+
+# Writing for agents
+
+Use when the Plan assigns an edit to a repository skill, `AGENTS.md`, or another agent-facing document. Inspect the existing instruction hierarchy and the target document's readers before editing. Keep each pointer short: state what document it leads to and the distinct conditions that require reading it. Put detailed instructions in the target document rather than repeating them in every pointer.
+
+State the agent's allowed decision, required inputs, observable output, and escalation condition. Use concrete paths and examples only when they are stable in the assigned repository. Keep rules at the narrowest scope that reaches every intended reader; avoid contradictory duplicates. Check that each imperative can be followed with the role's actual tools and permissions. For RelayView skill packages, keep the package instruction-only and single-role; never use text to grant tools, credentials, workflow transitions, or another role's authority. Run the relevant validation and report any instruction conflict to the owner.

packages/writing-for-agents/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.3.0"
+  },
+  "role": "implementer",
+  "step": "implementation",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "3a2fd1e3253a7373648f333456d1383c161203467ed89526a8129639806f377e"
+    }
+  ]
+}

tests/test_packages.py

@@ -12,8 +12,91 @@ ROOT = Path(__file__).resolve().parents[1]
 
 
 class PackageTests(unittest.TestCase):
+    def test_planner_scope_presentation_and_claim(self):
+        package = ROOT / "packages/planner-scope"
+        check_package(package)
+        text = (package / "scope.md").read_text()
+        for phrase in ("affected files and symbols", "invariants and edge cases", "YAML-compatible Markdown", "open_questions:"):
+            self.assertIn(phrase, text)
+        self.assertNotIn("follow-up monitor", text)
+        manifest = json.loads((package / "relayview-skill.json").read_text())
+        self.assertEqual(manifest["issueClaim"], {"statusLabel": "status/in-progress"})
+
+    def test_role_investigation_packages(self):
+        for role, step in (("planner", "planning"), ("implementer", "implementation"), ("reviewer", "review")):
+            package = ROOT / "packages" / f"{role}-investigation"
+            check_package(package)
+            manifest = json.loads((package / "relayview-skill.json").read_text())
+            self.assertEqual((manifest["role"], manifest["step"]), (role, step))
+            text = (package / "SKILL.md").read_text() + (package / "investigation.md").read_text()
+            self.assertIn("Trace load order", text)
+            self.assertIn("expression pieces", text)
+            self.assertNotIn("disable-model-invocation: true", text)
+            if role != "implementer":
+                self.assertIn("assigned read roots", text)
+                for host in ("/etc/", "/usr/share/", "$HOME", "rg -n"):
+                    self.assertNotIn(host, text)
+
+    def test_designer_release_modes_and_source(self):
+        automatic = "issue-designer-default"
+        manual = (
+            "designer-wayfinder", "designer-grilling", "designer-prototype",
+            "designer-research", "designer-domain-modeling", "designer-triage",
+            "designer-to-spec", "designer-to-tickets",
+        )
+        for name in (automatic, *manual):
+            with self.subTest(name=name):
+                package = ROOT / "packages" / name
+                skill = (package / "SKILL.md").read_text()
+                frontmatter = skill.split("---", 2)[1]
+                self.assertEqual("disable-model-invocation: true" in frontmatter, name in manual)
+                version = {automatic: "0.6.1", "designer-prototype": "0.6.2"}.get(name, "0.6.0")
+                self.assertIn(f"relayview-version: {version}", frontmatter)
+                manifest = json.loads((package / "relayview-skill.json").read_text())
+                self.assertEqual(manifest["source"], {"kind": "first-party", "reference": f"v{version}"})
+                check_package(package)
+
+    def test_tdd_is_available_to_owner_started_implementers(self):
+        package = ROOT / "packages/tdd-auto"
+        skill = (package / "SKILL.md").read_text()
+        frontmatter = skill.split("---", 2)[1]
+        self.assertIn("name: tdd-auto", frontmatter)
+        self.assertNotIn("disable-model-invocation: true", frontmatter)
+        self.assertIn("relayview-version: 0.3.1", frontmatter)
+        manifest = json.loads((package / "relayview-skill.json").read_text())
+        self.assertEqual(manifest["source"], {"kind": "first-party", "reference": "v0.3.1"})
+        check_package(package)
+        self.assertIn("disable-model-invocation: true", (ROOT / "packages/tdd/SKILL.md").read_text())
+
+    def test_migrated_role_guidance_has_one_declared_role_step(self):
+        expected = {"codebase-design": ("planner", "planning"), "grill-me": ("planner", "planning"),
+                    "grilling": ("planner", "planning"), "to-questionnaire": ("planner", "planning"),
+                    "diagnosing-bugs": ("implementer", "implementation"),
+                    "domain-modeling": ("implementer", "implementation"),
+                    "migrate-to-shoehorn": ("implementer", "implementation"),
+                    "pr": ("implementer", "implementation"), "prototype": ("implementer", "implementation"),
+                    "scaffold-exercises": ("implementer", "implementation"),
+                    "shared-abstraction-refactor": ("implementer", "implementation"),
+                    "split-large-files": ("implementer", "implementation"),
+                    "tdd": ("implementer", "implementation"),
+                    "writing-for-agents": ("implementer", "implementation"),
+                    "code-review": ("reviewer", "review"),
+                    "c4-diff": ("reviewer", "review"),
+                    "research": ("planner", "planning"),
+                    "improve-codebase-architecture": ("planner", "planning"),
+                    **{name: ("designer", "design") for name in (
+                        "issue-designer-default", "designer-wayfinder", "designer-grilling", "designer-prototype",
+                        "designer-research", "designer-domain-modeling", "designer-triage",
+                        "designer-to-spec", "designer-to-tickets")}}
+        for name, role_step in expected.items():
+            with self.subTest(name=name):
+                package = ROOT / "packages" / name
+                manifest = json.loads((package / "relayview-skill.json").read_text())
+                self.assertEqual((manifest["role"], manifest["step"]), role_step)
+                check_package(package)
+
     def test_release_package_and_starter_are_valid(self):
-        for path in (ROOT / "packages/planner-scope", ROOT / "packages/implementer-handoff", ROOT / "examples/starter-planner"):
+        for path in sorted((ROOT / "packages").iterdir()) + [ROOT / "examples/starter-planner"]:
             check_package(path)
             with tempfile.TemporaryDirectory() as directory:
                 first = package_archive(path, Path(directory) / "one.zip")

tools/packages.py

@@ -44,15 +44,26 @@ def check_package(path):
         manifest = json.loads(_text(raw_manifest, str(sidecar)))
     except (ValueError, TypeError) as error:
         _fail(f"{sidecar}: invalid JSON: {error}")
-    if not isinstance(manifest, dict) or set(manifest) != {"schemaVersion", "source", "role", "step", "files"}:
+    if not isinstance(manifest, dict) or (
+        (manifest.get("schemaVersion") == 1 and set(manifest) != {"schemaVersion", "source", "role", "step", "files"}) or
+        (manifest.get("schemaVersion") == 2 and set(manifest) != {"schemaVersion", "source", "role", "step", "files", "issueClaim"}) or
+        manifest.get("schemaVersion") not in (1, 2)
+    ):
         _fail(f"{path}: unsupported manifest fields")
     source = manifest["source"]
     if not isinstance(source, dict) or set(source) != {"kind", "reference"}:
         _fail(f"{path}: invalid source")
     if source["kind"] not in ("first-party", "user") or not isinstance(source["reference"], str) or not re.fullmatch(r"[A-Za-z0-9._:-]{1,128}", source["reference"]):
         _fail(f"{path}: invalid source identity")
-    if manifest["schemaVersion"] != 1 or (manifest["role"], manifest["step"]) not in (("planner", "planning"), ("implementer", "implementation"), ("reviewer", "review")):
+    if (manifest["role"], manifest["step"]) not in (("planner", "planning"), ("implementer", "implementation"), ("reviewer", "review"), ("designer", "design")):
         _fail(f"{path}: incompatible role or step")
+    if manifest["schemaVersion"] == 2:
+        claim = manifest["issueClaim"]
+        label = claim.get("statusLabel") if isinstance(claim, dict) else None
+        if (manifest["role"], manifest["step"]) != ("planner", "planning") or not isinstance(claim, dict) or set(claim) != {"statusLabel"} or (
+            label is not None and (not isinstance(label, str) or not re.fullmatch(r"status/[a-z][a-z0-9-]{0,63}", label) or label == "status/ready-for-agent")
+        ):
+            _fail(f"{path}: invalid issue claim policy")
     files = manifest["files"]
     if not isinstance(files, list) or not 1 <= len(files) <= 16:
         _fail(f"{path}: invalid file list")