create-yss-spec 1.1.3 → 2.0.0

package/template/.codex/skills/codebase-design/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Codebase Design"
+  short_description: "Vocabulary for deep-module design"

package/template/.codex/skills/competitive-intelligence/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: competitive-intelligence
-description: Use when researching competitors, market positioning, pricing, feature gaps, customer sentiment, or category trends before Discovery, PRD, product strategy, or roadmap decisions.
+description: Use when researching competitors, market positioning, pricing, feature gaps, customer sentiment, or category trends before Discovery, Spec, product strategy, or roadmap decisions.
 ---
 
 # Competitive Intelligence
 
 Source requested for this project: `anthropics/knowledge-work-plugins`, `sales/skills/competitive-intelligence`.
 
-Use this skill when competitive or market facts are needed to shape product Discovery, PRD scope, positioning, differentiation, pricing assumptions, or roadmap tradeoffs.
+Use this skill when competitive or market facts are needed to shape product Discovery, Spec scope, positioning, differentiation, pricing assumptions, or roadmap tradeoffs.
 
 ## Core Rules
 
@@ -43,11 +43,11 @@ Use this skill when competitive or market facts are needed to shape product Disc
    - Differentiators and defensibility.
    - Gaps and underserved jobs-to-be-done.
    - Risks if we copy the competitor too closely.
-   - Product opportunities for PRD or roadmap.
+   - Product opportunities for Spec or roadmap.
 5. Hand off to lifecycle assets:
    - Update Discovery findings in `docs/discovery/`.
    - Create or update a competitor matrix in `docs/discovery/reports/`.
-   - Feed stable user, pain, MVP, non-goal, and success criteria into `grill-with-docs` and `to-prd`.
+   - Feed stable user, pain, MVP, non-goal, and success criteria into `grill-with-docs` and `to-spec`.
    - Record uncertain claims as assumptions, not requirements.
 
 ## Output Shape
@@ -76,7 +76,7 @@ For a quick brief:
 | 维度 | 竞品 A | 竞品 B | 我们的机会 |
 |---|---|---|---|
 
-### PRD 输入
+### Spec 输入
 - 用户 / 痛点：
 - MVP 建议：
 - 非目标范围：

package/template/.codex/skills/cross-repo-implementation-routing/SKILL.md

@@ -9,8 +9,8 @@ description: Use when a Harness change or vertical slice may require work across
 
 ## Inputs
 
-- Harness change / OpenSpec / Comet change。
-- 垂直切片 Issue 或实施计划。
+- Harness change / Spec Delta change。
+- 垂直切片 Ticket 或实施计划。
 - OpenAPI Freeze 或无 API 影响记录。
 - 已登记的实现仓库记录；没有登记时先使用 `implementation-repo-onboarding`。
 

package/template/.codex/skills/diagnosing-bugs/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Diagnosing Bugs"
+  short_description: "Diagnose hard bugs and regressions"

package/template/.codex/skills/domain-modeling/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Domain Modeling"
+  short_description: "Build and sharpen a domain model"

package/template/.codex/skills/grill-with-docs/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Grill with Docs"
+  short_description: "Grill a design and write its docs"
+policy:
+  allow_implicit_invocation: false

package/template/.codex/skills/handoff/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: handoff
+description: Compact the current conversation into a handoff document for another agent to pick up.
+argument-hint: "What will the next session be used for?"
+disable-model-invocation: true
+---
+
+Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.
+
+Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
+
+Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+
+Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
+
+If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.

package/template/.codex/skills/handoff/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Handoff"
+  short_description: "Compact a conversation into a handoff"
+policy:
+  allow_implicit_invocation: false

package/template/.codex/skills/high-fidelity-html-prototype/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: high-fidelity-html-prototype
-description: Use after low-fidelity prototype review is approved and before PRD calibration, requirement freeze, OpenAPI Draft, or UI implementation when a user-facing YSS feature needs a high-fidelity interactive HTML prototype using Ant Design v6.
+description: Use after low-fidelity prototype review is approved and before Spec calibration, requirement freeze, OpenAPI Draft, or UI implementation when a user-facing YSS feature needs a high-fidelity interactive HTML prototype using Ant Design v6.
 ---
 
 # High Fidelity HTML Prototype
@@ -9,7 +9,7 @@ Use this skill only after `prototype-review` approves the low-fidelity prototype
 
 ## Required Inputs
 
-- PRD baseline: `docs/requirements/<feature>-prd.md`.
+- Spec baseline: `docs/requirements/<feature>-spec.md`.
 - Product overview design / functional architecture: `docs/design/<feature>-product-overview-design.md`.
 - Interaction spec: `docs/design/<feature>-interaction-spec.md`.
 - State matrix: `docs/design/<feature>-state-matrix.md`.
@@ -47,7 +47,7 @@ Use the latest verified v6.x version instead of `6.5.0` when npm reports a newer
 - Prefer Ant Design components and tokens over hand-built controls: `Layout`, `Menu`, `Breadcrumb`, `Button`, `Input`, `Select`, `Table`, `Form`, `Tabs`, `Steps`, `Drawer`, `Modal`, `Alert`, `Tooltip`, `Tag`, `Badge`, `DatePicker`, `Upload`, `Pagination`, `Empty`, `Spin`, `Result`.
 - Do not create extra data-service or fixture artifacts. Use embedded sample data inside the HTML/JS for visual and interaction demonstration only.
 - Mark the file clearly as `PROTOTYPE ONLY - NOT PRODUCTION CODE`.
-- Do not treat the HTML prototype as a stable frontend implementation, generated-client contract, or OpenAPI source of truth. It informs PRD calibration and OpenAPI Draft.
+- Do not treat the HTML prototype as a stable frontend implementation, generated-client contract, or OpenAPI source of truth. It informs Spec calibration and OpenAPI Draft.
 
 ## Interaction Coverage
 
@@ -80,7 +80,7 @@ Run a local browser verification before calling the artifact ready:
 High-fidelity HTML prototype
 
 ### 输入资产
-- <PRD / product overview / interaction spec / state matrix / prototype review>
+- <Spec / product overview / interaction spec / state matrix / prototype review>
 
 ### 高保真产物
 - `docs/design/prototypes/<feature>/index.html`
@@ -94,9 +94,9 @@ High-fidelity HTML prototype
 ### 验证证据
 - <render command or file open path, viewport checks, interaction checks>
 
-### 是否可进入 PRD 校准 / API 影响分析
+### 是否可进入 Spec 校准 / API 影响分析
 - <yes/no; list blocking gaps>
 
 ### 下一步
-- <PRD calibration / return to high-fidelity prototype / return to product-design-prototype>
+- <Spec calibration / return to high-fidelity prototype / return to product-design-prototype>
 ```

package/template/.codex/skills/implement/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: implement
-description: "Implement a piece of work based on a PRD or set of issues."
+description: "Implement a piece of work based on a spec or set of tickets."
 disable-model-invocation: true
 ---
 
-Implement the work described by the user in the PRD or issues.
+Implement the work described by the user in the spec or tickets.
 
 Use /tdd where possible, at pre-agreed seams.
 

package/template/.codex/skills/implement/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Implement"
+  short_description: "Build work from a spec or tickets"
+policy:
+  allow_implicit_invocation: false

package/template/.codex/skills/improve-codebase-architecture/SKILL.md

@@ -17,6 +17,11 @@ This command is _informed_ by the project's domain model and built on a shared d
 
 ### 1. Explore
 
+**Scope before you scan — YAGNI.** Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide *where* to look before you look:
+
+- If the user named a direction — a module, a subsystem, a pain point — take it, and skip the inference below.
+- Otherwise, walk back a good stretch of the commit history (`git log --oneline`) to find the codebase's hot spots — the files and areas that keep coming up — and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net.
+
 Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first.
 
 Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
@@ -56,7 +61,7 @@ Do NOT propose interfaces yet. After the file is written, ask the user: "Which o
 
 ### 3. Grilling loop
 
-Once the user picks a candidate, run the `/grilling` skill to walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
+Once the user picks a candidate, run the `/grilling` skill to walk the decision tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
 
 Side effects happen inline as decisions crystallize — run the `/domain-modeling` skill to keep the domain model current as you go:
 

package/template/.codex/skills/improve-codebase-architecture/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Improve Codebase Architecture"
+  short_description: "Find and grill architecture improvements"
+policy:
+  allow_implicit_invocation: false

package/template/.codex/skills/product-design-prototype/SKILL.md

@@ -1,31 +1,32 @@
 ---
 name: product-design-prototype
-description: Use when a PRD baseline or user story has UI impact and needs page maps, user flows, wireframes, interaction states, or API implications before PRD calibration, OpenAPI Draft, or implementation.
+description: Use when a Spec baseline or user story has UI impact and needs page maps, user flows, wireframes, interaction states, or API implications before Spec calibration, OpenAPI Draft, or implementation.
 ---
 
 # Product Design Prototype
 
-Use this skill after PRD baseline and before PRD calibration / OpenAPI Draft for features with user interfaces. Its job is to turn requirements into design assets that can drive calibrated PRD, API, frontend acceptance, and vertical slices.
+Use this skill after Spec baseline and before Spec calibration / OpenAPI Draft for features with user interfaces. Its job is to turn requirements into design assets that can drive a calibrated Spec, API, frontend acceptance, and vertical slices.
 
 ## Required Inputs
 
-- PRD baseline or confirmed user stories.
+- Spec baseline or confirmed user stories.
 - `CONTEXT.md` terms when domain language matters.
 - Existing `docs/design/` assets or prototype links.
 - Known component/page constraints, such as YSS UI, Formily, tables, trees, drawers, modals, permissions, or generated API clients.
 
-If no PRD baseline exists, route back to `yss-product-lifecycle` / `grill-with-docs` / `to-prd`. If the change has no UI impact, record the no-UI decision and continue to PRD calibration, OpenAPI, or engineering baseline.
+If no Spec baseline exists, route back to `yss-product-lifecycle` / `grill-with-docs` / `to-spec`. If the change has no UI impact, record the no-UI decision and continue to Spec calibration, OpenAPI, or engineering baseline.
 
 ## Core Flow
 
-1. Inspect current assets: PRD, `docs/design/`, `docs/api/specs/`, `docs/architecture/`, and active OpenSpec/Comet changes.
+1. Inspect current assets: Spec, `docs/design/`, `docs/api/specs/`, `docs/architecture/`, and active Spec Delta changes.
 2. Create or update a design artifact under `docs/design/<feature>-interaction-spec.md` using `docs/design/templates/interaction-spec-template.md`.
 3. Capture page map, primary user flow, exception flow, and low-fidelity prototype or wireframe link.
 4. Fill the state matrix using `docs/design/templates/state-matrix-template.md`.
 5. Write the OpenAPI implication list: fields, filters, actions, errors, permissions, pagination, optimistic/concurrency states, and audit/version data.
 6. For every primary page action, add an action-to-contract row: page/component, action label, `actionKey`, endpoint or explicit non-goal, request fields, response shape, permission behavior, state transition, idempotency/concurrency rule, and error codes.
 7. For every P0 requirement containing verbs such as manage, maintain, configure, create, update, archive, retry, cancel, publish, export, or create draft, confirm the interaction spec either names the API implication or records that the capability is intentionally out of scope.
-8. Hand off to `prototype-review`. After low-fidelity review is approved, hand off to `high-fidelity-html-prototype`. Do not freeze/calibrate the PRD or enter OpenAPI Draft for UI work until the Ant Design v6 high-fidelity HTML prototype exists and has no blocking findings.
+8. Hand off to `prototype-review`. After low-fidelity review is approved, hand off to `high-fidelity-html-prototype`. Do not freeze/calibrate the Spec or enter OpenAPI Draft for UI work until the Ant Design v6 high-fidelity HTML prototype exists and has no blocking findings.
+9. 交互原型应标注 semantic token 角色、single primary action、interaction feedback 和不可逆操作确认；若页面使用 Ant Design，主题密度或暗色策略必须使用 theme algorithm，并在关键文本上复核 accessibility contrast。
 
 ## Tool Routing
 
@@ -44,7 +45,7 @@ Return:
 Product design / prototype / interaction design
 
 ### 输入资产
-- <PRD / discovery / CONTEXT / existing design paths>
+- <Spec / discovery / CONTEXT / existing design paths>
 
 ### 设计产物
 - <docs/design/... or prototype link>
@@ -61,11 +62,14 @@ Product design / prototype / interaction design
 ### 页面动作到契约映射
 - <page/component action -> actionKey -> endpoint/non-goal -> permission -> state transition -> error codes>
 
-### 是否可进入 PRD 校准 / OpenAPI Draft
-- <yes/no; include whether PRD calibration is needed first>
+### Ant Design v6 体验检查
+- <semantic token / theme algorithm / single primary action / interaction feedback / accessibility contrast>
+
+### 是否可进入 Spec 校准 / OpenAPI Draft
+- <yes/no; include whether Spec calibration is needed first>
 
 ### 下一步
-- <prototype-review / high-fidelity-html-prototype / routing back to PRD/design>
+- <prototype-review / high-fidelity-html-prototype / routing back to Spec/design>
 ```
 
 ## Data Modeling Example

package/template/.codex/skills/product-design-prototype/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Product Design Prototype"
   short_description: "UI flow and state design before API draft"
-  default_prompt: "Use $product-design-prototype to turn a PRD baseline into interaction design assets before PRD calibration."
+  default_prompt: "Use $product-design-prototype to turn a Spec baseline into interaction design assets before Spec calibration."

package/template/.codex/skills/prototype/LOGIC.md

@@ -36,7 +36,7 @@ The right shape depends on the question:
 
 Pick whichever shape best fits the question being asked, *not* whichever is easiest to wire to a TUI. Keep it pure: no I/O, no terminal code, no `console.log` for control flow. The TUI imports it and calls into it; nothing flows the other direction.
 
-This is what makes the prototype useful past its own lifetime. When the question's been answered, the validated reducer / machine / function set can be lifted into the real module — the TUI shell gets deleted.
+This is what makes the prototype useful past its own lifetime: when the question's been answered, the validated reducer / machine / function set can be lifted into the real module on its own.
 
 ### 4. Build the smallest TUI that exposes the state
 
@@ -66,9 +66,9 @@ If the host project has no task runner, just put the command at the top of the p
 
 Give the user the run command. They'll drive it themselves; the interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different" — those are the bugs in the _idea_, which is the whole point. If they want new actions added, add them. Prototypes evolve.
 
-### 7. Capture the answer
+### 7. Capture the answer and the prototype
 
-When the prototype has done its job, the answer to the question is the only thing worth keeping. If the user is around, ask what it taught them. If not, leave a `NOTES.md` next to the prototype so the answer can be filled in (or filled in by you, if you've watched the session) before the prototype gets deleted.
+Once the prototype has answered its question, capture the answer, then capture the prototype the way the [SKILL](SKILL.md) describes. The logic-specific mapping: the validated reducer / machine / function set lifts into the real module (the decision, absorbed); the TUI shell rides along to the throwaway branch that keeps the prototype as a primary source.
 
 ## Anti-patterns
 

package/template/.codex/skills/prototype/SKILL.md

@@ -21,10 +21,6 @@ The two branches produce very different artifacts — getting this wrong wastes
 1. **Throwaway from day one, and clearly marked as such.** Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so context is obvious — but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure.
 2. **One command to run.** Whatever the project's existing task runner supports — `pnpm <name>`, `python <path>`, `bun <path>`, etc. The user must be able to start it without thinking.
 3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is _checking_, not something it should depend on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE — wipe me" name.
-4. **Skip the polish.** No tests, no error handling beyond what makes the prototype _runnable_, no abstractions. The point is to learn something fast and then delete it.
+4. **Skip the polish.** No tests, no error handling beyond what makes the prototype _runnable_, no abstractions. The point is to learn something fast.
 5. **Surface the state.** After every action (logic) or on every variant switch (UI), print or render the full relevant state so the user can see what changed.
-6. **Delete or absorb when done.** When the prototype has answered its question, either delete it or fold the validated decision into the real code — don't leave it rotting in the repo.
-
-## When done
-
-The _answer_ is the only thing worth keeping from a prototype. Capture it somewhere durable (commit message, ADR, issue, or a `NOTES.md` next to the prototype) along with the question it was answering. If the user is around, that capture is a quick conversation; if not, leave the placeholder so they (or you, on the next pass) can fill in the verdict before deleting the prototype.
+6. **Capture it when done.** Fold any validated decision into the real code, then capture the prototype itself as a **primary source**: commit it to a throwaway branch, out of main, and leave a context pointer to that branch on the implementation issue. Capture the answer too — the verdict and the question it settled — in the issue or a commit. The main branch keeps only the validated decision.

package/template/.codex/skills/prototype/UI.md

@@ -97,12 +97,12 @@ Surface the URL (and the `?variant=` keys). The user will flip through whenever
 
 ### 6. Capture the answer and clean up
 
-Once a variant has won, write down which one and why (commit message, ADR, issue, or a `NOTES.md` next to the prototype if running AFK and the user hasn't responded yet). Then:
+Once a variant has won, capture the answer — which variant and why — then capture the prototype the way the [SKILL](SKILL.md) describes. Fold the winner into the real code and move the rest onto the throwaway branch, not into main:
 
-- **Sub-shape A** — delete the losing variants and the switcher; fold the winner into the existing page.
-- **Sub-shape B** — promote the winning variant to a real route, delete the throwaway route and the switcher.
+- **Sub-shape A** — fold the winner into the existing page; drop the losing variants and the switcher from main.
+- **Sub-shape B** — promote the winning variant to a real route; drop the throwaway route and the switcher from main.
 
-Don't leave variant components or the switcher lying around. They rot fast and confuse the next reader.
+The full set of variants is the primary source, so it lands on the throwaway branch, not the bin — variant components and the switcher left in the main branch rot fast and confuse the next reader.
 
 ## Anti-patterns
 

package/template/.codex/skills/prototype/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Prototype"
+  short_description: "Prototype to answer a design question"

package/template/.codex/skills/prototype-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: prototype-review
-description: Use when reviewing low-fidelity UI design, wireframes, prototype links, interaction specs, or state matrices before high-fidelity HTML prototype work, PRD calibration, OpenAPI Draft, vertical slicing, or implementation.
+description: Use when reviewing low-fidelity UI design, wireframes, prototype links, interaction specs, or state matrices before high-fidelity HTML prototype work, Spec calibration, OpenAPI Draft, vertical slicing, or implementation.
 ---
 
 # Prototype Review
@@ -9,7 +9,7 @@ Use this skill as the low-fidelity gate between product design/prototype work an
 
 ## Required Inputs
 
-- PRD baseline or confirmed user stories.
+- Spec baseline or confirmed user stories.
 - `docs/design/<feature>-interaction-spec.md` or prototype link.
 - State matrix, preferably based on `docs/design/templates/state-matrix-template.md`.
 - Existing OpenAPI Draft only if the review is checking alignment; do not require OpenAPI before product design.
@@ -31,10 +31,10 @@ Use this skill as the low-fidelity gate between product design/prototype work an
 
 ## Decision Rules
 
-- If a feature has UI impact and lacks page map, user flow, prototype/wireframe, or state matrix, block high-fidelity HTML prototype work, PRD calibration, and OpenAPI Draft.
+- If a feature has UI impact and lacks page map, user flow, prototype/wireframe, or state matrix, block high-fidelity HTML prototype work, Spec calibration, and OpenAPI Draft.
 - If the prototype hides business rules behind generic text such as "校验失败", require field-level errors and recovery behavior.
-- If a page shows a user action but the OpenAPI implication list lacks endpoint/non-goal mapping, block high-fidelity HTML prototype work, PRD calibration, or OpenAPI Draft.
-- If PRD P0 scope says a user can manage or configure an object but the design only shows read-only data, block until the write path or scope downgrade is explicit.
+- If a page shows a user action but the OpenAPI implication list lacks endpoint/non-goal mapping, block high-fidelity HTML prototype work, Spec calibration, or OpenAPI Draft.
+- If Spec P0 scope says a user can manage or configure an object but the design only shows read-only data, block until the write path or scope downgrade is explicit.
 - If a state is intentionally out of scope, record why and who owns the decision.
 - If implementation dependencies are unclear, route to `yss-router` only after the prototype passes this review.
 
@@ -53,7 +53,7 @@ Use this skill as the low-fidelity gate between product design/prototype work an
 ### OpenAPI Draft Readiness
 - <paths, fields, errors, permissions, pagination/YSS wrappers, action mappings, rule sources, concurrency notes>
 
-### PRD Calibration Readiness
+### Spec Calibration Readiness
 - <requirements gaps, acceptance criteria updates, non-goals, pending decisions>
 
 ### Frontend Prototype Readiness

package/template/.codex/skills/prototype-review/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Prototype Review"
-  short_description: "Gate UI prototypes before PRD calibration"
-  default_prompt: "Use $prototype-review to review prototype readiness before PRD calibration and OpenAPI Draft."
+  short_description: "Gate UI prototypes before Spec calibration"
+  default_prompt: "Use $prototype-review to review prototype readiness before Spec calibration and OpenAPI Draft."

package/template/.codex/skills/research/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Research"
+  short_description: "Research from high-trust sources"

package/template/.codex/skills/resolving-merge-conflicts/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Resolving Merge Conflicts"
+  short_description: "Resolve merge and rebase conflicts"

package/template/.codex/skills/setup-matt-pocock-skills/SKILL.md

@@ -8,7 +8,7 @@ disable-model-invocation: true
 
 Scaffold the per-repo configuration that the engineering skills assume:
 
-- **Issue tracker** — where issues live (GitHub by default; local markdown is also supported out of the box)
+- **Ticket tracker** — where Tickets live (GitHub by default; local markdown is also supported out of the box)
 - **Triage labels** — the strings used for the five canonical triage roles
 - **Domain docs** — where `CONTEXT.md` and ADRs live, and the consumer rules for reading them
 
@@ -26,16 +26,18 @@ Look at the current repo to understand its starting state. Read whatever exists;
 - `docs/adr/` and any `src/*/docs/adr/` directories
 - `docs/agents/` — does this skill's prior output already exist?
 - `.scratch/` — sign that a local-markdown issue tracker convention is already in use
+- Is the `triage` skill installed? (a `triage` skill folder alongside this one, or `triage` in your available skills.) This decides whether Section B runs at all.
+- Monorepo signals — a `pnpm-workspace.yaml`, a `workspaces` field in `package.json`, or a populated `packages/*` with its own `src/`. Present only in a genuinely large multi-package repo; their absence means single-context, which is almost every repo.
 
 ### 2. Present findings and ask
 
-Summarise what's present and what's missing. Then walk the user through the three decisions **one at a time** — present a section, get the user's answer, then move to the next. Don't dump all three at once.
+Summarise what's present and what's missing. Then take the sections in order — one section, one answer, then the next.
 
-Assume the user does not know what these terms mean. Each section starts with a short explainer (what it is, why these skills need it, what changes if they pick differently). Then show the choices and the default.
+Lead each section with the recommended answer so the user can accept it in a word. Give a one-line explainer only when the choice genuinely branches; skip the section entirely when exploration already settled it (Section B when `triage` isn't installed, Section C when there's no monorepo).
 
-**Section A — Issue tracker.**
+**Section A — Ticket tracker.**
 
-> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-issues`, `triage`, `to-prd`, and `qa` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.
+> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-tickets`, `triage`, `to-spec`, and `qa` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.
 
 Default posture: these skills were designed for GitHub. If a `git remote` points at GitHub, propose that. If a `git remote` points at GitLab (`gitlab.com` or a self-hosted host), propose GitLab. Otherwise (or if the user prefers), offer:
 
@@ -44,41 +46,26 @@ Default posture: these skills were designed for GitHub. If a `git remote` points
 - **Local markdown** — issues live as files under `.scratch/<feature>/` in this repo (good for solo projects or repos without a remote)
 - **Other** (Jira, Linear, etc.) — ask the user to describe the workflow in one paragraph; the skill will record it as freeform prose
 
-If — and only if — the user picked **GitHub** or **GitLab**, ask one follow-up:
+Record the choice in `docs/agents/issue-tracker.md`. The GitHub and GitLab templates carry a "PRs as a request surface" flag, defaulted **off** — leave it off and don't raise it; a user who wants external PRs in the triage queue can flip the flag in the file later.
 
-> Explainer: Open-source repos often receive feature requests as pull requests, not just issues — a PR is an issue with attached code. If you turn this on, `/triage` pulls *external* PRs into the same queue and runs them through the same labels and states as issues (collaborators' in-flight PRs are left alone). Leave it off if PRs aren't a request surface for you.
+**Section B — Triage label vocabulary.** Skip this section entirely if the `triage` skill isn't installed (exploration told you) — an uninstalled skill needs no labels.
 
-- **PRs as a request surface** — yes / no (default: no). Record the answer in `docs/agents/issue-tracker.md`. For local-markdown and other trackers, skip this question — there are no PRs.
+If it is installed, ask exactly one question:
 
-**Section B — Triage label vocabulary.**
+> Do you want to keep the default triage labels? (recommended: **yes**)
 
-> Explainer: When the `triage` skill processes an incoming issue, it moves it through a state machine — needs evaluation, waiting on reporter, ready for an AFK agent to pick up, ready for a human, or won't fix. To do that, it needs to apply labels (or the equivalent in your issue tracker) that match strings *you've actually configured*. If your repo already uses different label names (e.g. `bug:triage` instead of `needs-triage`), map them here so the skill applies the right ones instead of creating duplicates.
+The defaults are the five canonical roles, each label string equal to its name: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. On **yes**, write them as-is. Only if the user says no — usually because their tracker already uses other names (e.g. `bug:triage` for `needs-triage`) — collect the overrides so `triage` applies existing labels instead of creating duplicates.
 
-The five canonical roles:
+**Section C — Domain docs.** Default to **single-context** — one `CONTEXT.md` + `docs/adr/` at the repo root. This fits almost every repo; write it without asking.
 
-- `needs-triage` — maintainer needs to evaluate
-- `needs-info` — waiting on reporter
-- `ready-for-agent` — fully specified, AFK-ready (an agent can pick it up with no human context)
-- `ready-for-human` — needs human implementation
-- `wontfix` — will not be actioned
-
-Default: each role's string equals its name. Ask the user if they want to override any. If their issue tracker has no existing labels, the defaults are fine.
-
-**Section C — Domain docs.**
-
-> Explainer: Some skills (`improve-codebase-architecture`, `diagnosing-bugs`, `tdd`) read a `CONTEXT.md` file to learn the project's domain language, and `docs/adr/` for past architectural decisions. They need to know whether the repo has one global context or multiple (e.g. a monorepo with separate frontend/backend contexts) so they look in the right place.
-
-Confirm the layout:
-
-- **Single-context** — one `CONTEXT.md` + `docs/adr/` at the repo root. Most repos are this.
-- **Multi-context** — `CONTEXT-MAP.md` at the root pointing to per-context `CONTEXT.md` files (typically a monorepo).
+Offer **multi-context** — a root `CONTEXT-MAP.md` pointing to per-context `CONTEXT.md` files — only when exploration found monorepo signals. Then confirm which layout they want.
 
 ### 3. Confirm and edit
 
 Show the user a draft of:
 
 - The `## Agent skills` block to add to whichever of `CLAUDE.md` / `AGENTS.md` is being edited (see step 4 for selection rules)
-- The contents of `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md`, `docs/agents/domain.md`
+- The contents of `docs/agents/issue-tracker.md`, `docs/agents/domain.md`, and `docs/agents/triage-labels.md` (the last only when `triage` is installed)
 
 Let them edit before writing.
 
@@ -99,9 +86,9 @@ The block:
 ```markdown
 ## Agent skills
 
-### Issue tracker
+### Ticket tracker
 
-[one-line summary of where issues are tracked, plus whether external PRs are a triage surface]. See `docs/agents/issue-tracker.md`.
+[one-line summary of where issues are tracked]. See `docs/agents/issue-tracker.md`.
 
 ### Triage labels
 
@@ -112,12 +99,14 @@ The block:
 [one-line summary of layout — "single-context" or "multi-context"]. See `docs/agents/domain.md`.
 ```
 
-Then write the three docs files using the seed templates in this skill folder as a starting point:
+Include the `### Triage labels` sub-block, and write `docs/agents/triage-labels.md`, only when `triage` is installed and Section B ran. When it isn't, both are omitted.
+
+Then write the docs files using the seed templates in this skill folder as a starting point:
 
 - [issue-tracker-github.md](./issue-tracker-github.md) — GitHub issue tracker
 - [issue-tracker-gitlab.md](./issue-tracker-gitlab.md) — GitLab issue tracker
 - [issue-tracker-local.md](./issue-tracker-local.md) — local-markdown issue tracker
-- [triage-labels.md](./triage-labels.md) — label mapping
+- [triage-labels.md](./triage-labels.md) — label mapping (only if `triage` is installed)
 - [domain.md](./domain.md) — domain doc consumer rules + layout
 
 For "other" issue trackers, write `docs/agents/issue-tracker.md` from scratch using the user's description.

package/template/.codex/skills/setup-matt-pocock-skills/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Setup Matt Pocock Skills"
+  short_description: "Configure a repo for the skills"
+policy:
+  allow_implicit_invocation: false

package/template/.codex/skills/setup-matt-pocock-skills/issue-tracker-github.md

@@ -1,6 +1,6 @@
-# Issue tracker: GitHub
+# Ticket tracker: GitHub
 
-Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+Tickets and Specs for this repo live as GitHub Issues. Use the `gh` CLI for all operations.
 
 ## Conventions
 

package/template/.codex/skills/setup-matt-pocock-skills/issue-tracker-gitlab.md

@@ -1,6 +1,6 @@
-# Issue tracker: GitLab
+# Ticket tracker: GitLab
 
-Issues and PRDs for this repo live as GitLab issues. Use the [`glab`](https://gitlab.com/gitlab-org/cli) CLI for all operations.
+Tickets and Specs for this repo live as GitLab Issues. Use the [`glab`](https://gitlab.com/gitlab-org/cli) CLI for all operations.
 
 ## Conventions
 

package/template/.codex/skills/setup-matt-pocock-skills/issue-tracker-local.md

@@ -1,12 +1,12 @@
-# Issue tracker: Local Markdown
+# Ticket tracker: Local Markdown
 
-Issues and PRDs for this repo live as markdown files in `.scratch/`.
+Tickets and Specs for this repo live as markdown files in `.scratch/`.
 
 ## Conventions
 
 - One feature per directory: `.scratch/<feature-slug>/`
-- The PRD is `.scratch/<feature-slug>/PRD.md`
-- Implementation issues are `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01`
+- The spec is `.scratch/<feature-slug>/spec.md`
+- Implementation tickets are one file per ticket at `.scratch/<feature-slug>/tickets/<NN>-<slug>.md`, numbered from `01` — never a single combined tickets file
 - Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
 - Comments and conversation history append to the bottom of the file under a `## Comments` heading
 
@@ -23,8 +23,8 @@ Read the file at the referenced path. The user will normally pass the path or th
 Used by `/wayfinder`. The **map** is a file with one **child** file per ticket.
 
 - **Map**: `.scratch/<effort>/map.md` — the Notes / Decisions-so-far / Fog body.
-- **Child ticket**: `.scratch/<effort>/issues/NN-<slug>.md`, numbered from `01`, with the question in the body. A `Type:` line records the ticket type (`research`/`prototype`/`grilling`/`task`); a `Status:` line records `claimed`/`resolved`.
+- **Child ticket**: `.scratch/<effort>/tickets/NN-<slug>.md`, numbered from `01`, with the question in the body. A `Type:` line records the ticket type (`research`/`prototype`/`grilling`/`task`); a `Status:` line records `claimed`/`resolved`.
 - **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked when every file it lists is `resolved`.
-- **Frontier**: scan `.scratch/<effort>/issues/` for files that are open, unblocked, and unclaimed; first by number wins.
+- **Frontier**: scan `.scratch/<effort>/tickets/` for files that are open, unblocked, and unclaimed; first by number wins.
 - **Claim**: set `Status: claimed` and save before any work.
 - **Resolve**: append the answer under an `## Answer` heading, set `Status: resolved`, then append a context pointer (gist + link) to the map's Decisions-so-far in `map.md`.

package/template/.codex/skills/setup-matt-pocock-skills/triage-labels.md

@@ -6,8 +6,8 @@ The skills speak in terms of five canonical triage roles. This file maps those r
 | -------------------------- | -------------------- | ---------------------------------------- |
 | `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
 | `needs-info`               | `needs-info`         | Waiting on reporter for more information |
-| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
-| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `ready-for-agent`          | `ready-for-agent`    | Unblocked vertical-slice ticket whose required gates passed |
+| `ready-for-human`          | `ready-for-human`    | Spec, design, draft contract, or other item needing human judgment or access |
 | `wontfix`                  | `wontfix`            | Will not be actioned                     |
 
 When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.

package/template/.codex/skills/tdd/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "TDD"
+  short_description: "Test-driven red-green-refactor"