create-yss-spec 2.1.8 → 2.1.10

package/template/.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml

@@ -35,8 +35,18 @@ entry_routing:
   invalid_manifest:
     action: migration-check
   direct_matt_entry:
+    skill: ask-matt
     delegate_to: yss-product-lifecycle
     requires_valid_manifest: true
+    action: navigate-only
+    lifecycle_state_mutation: forbidden
+    lifecycle_artifact_write: forbidden
+    return_to_orchestrator: required
+  formal_user_entry:
+    skills: [setup-matt-pocock-skills, grill-with-docs, to-spec, to-tickets, implement]
+    action: lifecycle-validate-and-accept
+    lifecycle_artifact_write: conditional-explicit-user-entry
+    return_to_orchestrator: required
   template_source:
     route: template-maintenance
     forbidden_artifacts: [product-spec, prototype, openapi, vertical-slice-tickets]
@@ -44,8 +54,11 @@ entry_routing:
     on_forbidden_flow: blocked
     block_reason: template-source-product-artifact-forbidden
 
-# Matt skill 的自然语言输出必须先归一化，再由生命周期编排器决定是否推进。
+# 旧 Matt Skill Result 只用于兼容读取；所有生命周期新输出使用 Workflow Execution Result。
 matt_skill_result:
+  status: compatibility-read-only
+  may_influence_routing: false
+  normalize_to: workflow-execution-result-v1
   schema_version: 1
   result_values: [completed, blocked, needs-human, failed]
   required: [result, skill, evidence_refs, changed_artifacts, new_impacts, stale_candidates, next_route, blocking_signals]
@@ -60,7 +73,98 @@ matt_skill_result:
     blocked: blocked
     ready-for-lifecycle-review: needs-human
 
-flow_preconditions:
+workflow_execution_result:
+  canonical_output_schema: workflow-execution-result-v1
+  accepted_input_schemas: [workflow-execution-result-v1]
+  legacy:
+    matt-skill-result-v1:
+      status: compatibility-read-only
+      may_influence_routing: false
+      normalize_to: workflow-execution-result-v1
+      removal_target: schema_version_2
+  result_values: [completed, blocked, needs-human, failed]
+  required: [result_schema, work_unit, workflow_reference, result, evidence_refs, changed_artifacts, new_impacts, stale_candidates, next_route, blocking_signals]
+  blocking_signals: [drift, new_impacts, violation, missing_evidence, stale_candidates]
+  completed_requires_empty: [new_impacts, stale_candidates]
+  completed_requires_non_empty: [evidence_refs]
+  completed_requires_readable_evidence_refs: true
+  evidence_ref_validation: readable-or-resolvable
+  completed_requires_no_blocking_signals: true
+  workflow_reference:
+    required: [source, skill, invocation_mode]
+    allowed_sources: [yss-product-lifecycle, mattpocock/skills]
+
+# Matt user-invoked skills remain explicit user entry points. Lifecycle work units
+# may prepare, validate and accept their results, but cannot invoke them or create
+# their formal artifacts on their behalf.
+matt_invocation_boundary:
+  user_invoked_skills: [ask-matt, grill-me, grill-with-docs, handoff, implement, improve-codebase-architecture, loop-me, setup-matt-pocock-skills, setup-ts-deep-modules, teach, to-questionnaire, to-spec, to-tickets, triage, wait-what, wayfinder, writing-beats, writing-fragments, writing-shape]
+  lifecycle_managed_user_entries: [setup-matt-pocock-skills, grill-with-docs, to-spec, to-tickets, implement]
+  model_invoked_skills: [code-review, codebase-design, diagnosing-bugs, domain-modeling, grilling, migrate-to-shoehorn, prototype, research, resolving-merge-conflicts, scaffold-exercises, setup-pre-commit, tdd, writing-for-agents]
+  lifecycle_allowed_model_invoked_skills: [code-review, codebase-design, diagnosing-bugs, domain-modeling, grilling, prototype, research, tdd]
+  lifecycle_may_invoke_user_invoked: false
+  formal_artifact_owner: explicit-user-entry
+  continuous_orchestration: compatibility-prepare-and-validate-only
+  direct_user_entry: lifecycle-validate-and-accept
+
+skill_source_contract:
+  lock_version: 3
+  source_revisions_required: [mattpocock/skills]
+  adaptation_ref_required_when_effective_diff: true
+  retired_shared_skills: [batch-grill-me]
+
+# 生命周期默认走原生工作单元；Matt user-invoked skill 仅保留为兼容入口。
+lifecycle_native_entries:
+  default_entry: yss-product-lifecycle
+  formal_artifact_owner: yss-product-lifecycle
+  user_confirmation_required_at: [spec-baseline, prototype-confirmation, openapi-freeze, merge-or-release]
+  compatibility_entries:
+    to-spec: lifecycle-validate-and-accept
+    to-tickets: lifecycle-validate-and-accept
+    implement: lifecycle-validate-and-accept
+
+work_unit_routes:
+  work-unit.discovery-opportunity:
+    native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    skills: [competitive-intelligence, research]
+    route_by: {market_or_competitor_fact: competitive-intelligence, technical_or_standard_fact: research, no_external_fact: yss-product-lifecycle}
+  work-unit.discovery-requirements:
+    native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    skills: [grilling, domain-modeling]
+  work-unit.spec-synthesis:
+    native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    compatibility: {source: mattpocock/skills, skill: to-spec, invocation_mode: reference, formal_artifact_owner: explicit-user-entry}
+    skills: [domain-modeling]
+    human_gate: spec-baseline
+  work-unit.prototype-design:
+    native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    skills: [yss-design-system, yss-prototype-stage, product-design:index]
+    human_gate: prototype-confirmation
+  work-unit.technical-analysis:
+    native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    skills: [yss-openapi-governance, yss-openapi-draft-review, codebase-design, implementation-repo-onboarding, yss-router]
+    human_gate: openapi-freeze_if_api_impact
+  work-unit.ticket-decomposition:
+    native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    compatibility: {source: mattpocock/skills, skill: to-tickets, invocation_mode: reference, formal_artifact_owner: explicit-user-entry}
+    skills: [yss-router]
+  work-unit.slice-implementation:
+    native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    compatibility: {source: mattpocock/skills, skill: implement, invocation_mode: reference, formal_artifact_owner: explicit-user-entry}
+    skills: [tdd, yss-router, yss-ui, yss-page-module-development]
+  work-unit.frontend-implementation-verification:
+    native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    skills: [yss-ui, yss-design-system, code-review]
+    applies_when: ui_impact
+  work-unit.code-review:
+    native: {source: yss-product-lifecycle, skill: code-review, invocation_mode: model-invoked}
+    skills: [code-review]
+  work-unit.release-and-retrospective:
+    native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    skills: [yss-product-lifecycle]
+    human_gate: merge_or_release
+
+compatibility_flow_preconditions:
   to-spec:
     required: [grill_exit, no_unresolved_runnable_blocker]
     evidence: [user_problem, mvp_and_non_goals, success_criteria, test_seam, terminology_review]
@@ -70,9 +174,18 @@ flow_preconditions:
     output: vertical-slice-tickets
     output_role: ready-for-human
   implement:
-    required: [ready_for_agent, slice_contract_approved, slice_contract_persisted, slice_contract_current_version, build_architecture_checklist, implementation_repo, implementation_branch, ci, verification_commands, rollback_point, backend_slice_contract_if_applicable, backend_scaffold_policy_satisfied]
+    required: [ready_for_agent, slice_contract_approved, slice_contract_persisted, slice_contract_current_version, build_architecture_checklist, implementation_repo, implementation_branch, ci, verification_commands, rollback_point, backend_slice_contract_if_applicable, backend_scaffold_policy_satisfied, frontend_implementation_plan_if_ui_impact]
     applies_to_single_session: true
 
+grill_exit:
+  required: [frontier_empty, facts_resolved_or_routed, decisions_confirmed, shared_understanding_confirmed, no_unresolved_runnable_blocker]
+  facts_resolved_or_routed:
+    technical_fact: research
+    runnable_question: handoff-prototype-handoff
+    external_decision: external-input-required
+  user_confirmation_required: true
+  output: discovery-evidence
+
 ticket_role_transition:
   yss_active:
     to_tickets_initial_role: ready-for-human
@@ -84,6 +197,9 @@ review_input:
   schema_version: 1
   required: [review_mode, review_base_ref, implementation_candidate_ref, candidate_snapshot_ref, candidate_digest, spec_ref, ticket_ref, slice_contract_ref, build_architecture_checklist_ref, yss_execution_result_refs]
   nullable: [spec_ref]
+  axes: [standards, spec, ui_fidelity_if_ui_impact]
+  repair_invalidates_candidate: true
+  repair_action: recapture_candidate_and_rerun_all_axes
   modes: [committed, worktree]
   committed:
     candidate_ref: HEAD
@@ -131,6 +247,7 @@ review_input:
     completion_requires_current_digest: true
 
 git_authorization:
+  natural_language_intent_is_authorization: false
   commit:
     requires_explicit_user_authorization: true
     required: [commit_authorized, commit_scope, commit_authorization_ref]
@@ -230,6 +347,15 @@ tracker:
 setup_readiness:
   evaluation: once_per_task
   recheck_when: [tracker_changed, remote_changed, labels_changed, configuration_changed]
+  missing_action: needs-human
+  requested_skill: setup-matt-pocock-skills
+  resume_route: setup-readiness
+  preserves: [lifecycle.status, gate.status, ticket.role]
+  lifecycle_may_invoke_setup: false
+  legacy_artifacts_detected:
+    action: migration-check
+    setup: forbidden
+    write: paused
   states: [ready, missing, conflict, degraded, not-applicable]
   evidence: [platform, label_check, domain_layout, artifact_root, migration_ref]
   semantics:
@@ -243,14 +369,39 @@ setup_readiness:
 
 lifecycle_owned_work_units: [release, retrospective]
 lifecycle_work_unit_requirements:
-  release: [fresh_verification, release_or_rollback_evidence, independent_review]
+  release: [fresh_verification, release_or_rollback_evidence, independent_review, all_triggered_gates_approved_or_not_applicable]
   retrospective: [fresh_verification, retrospective_record, governance_reflow_decision]
 
+release_readiness:
+  required: [fresh_verification, release_or_rollback_evidence, independent_review, all_triggered_gates_approved_or_not_applicable]
+  conditional:
+    ui_impact: [gate.frontend-implementation-verified, evidence.frontend-implementation-verification]
+  blocked_when: [triggered_gate_blocked, triggered_gate_stale, triggered_gate_not_evaluated, missing_evidence]
+
 wayfinder_completion:
   required: [no_open_children, no_open_blocked_or_claimed_children, no_fog, destination_clear]
 
 ready_for_agent:
-  required: [gates_satisfied, no_stale_artifacts, blockers_closed, implementation_context_ready, implementation_repo, implementation_branch, ci, verification_commands, rollback_point, slice_contract_approved, slice_contract_persisted, slice_contract_current_version, build_architecture_checklist, backend_slice_contract_if_applicable, backend_scaffold_policy_satisfied]
+  required: [gates_satisfied, no_stale_artifacts, blockers_closed, implementation_context_ready, implementation_repo, implementation_branch, ci, verification_commands, rollback_point, slice_contract_approved, slice_contract_persisted, slice_contract_current_version, build_architecture_checklist, backend_slice_contract_if_applicable, backend_scaffold_policy_satisfied, frontend_implementation_plan_if_ui_impact]
+
+frontend_implementation_plan:
+  applies_when: [ui_impact]
+  required_before: [ready_for_agent]
+  required: [prototype_ref, spec_ref, route_and_page_inventory, visual_acceptance_cases, desktop_viewport, narrow_viewport, state_cases, pnpm_commands]
+  schema: docs/process/schemas/frontend-implementation-evidence.schema.json
+  validator: scripts/verify-frontend-implementation-evidence
+  acceptance: [kind_plan, template_false, status_approved, no_template_placeholders, readable_baseline_refs, non_empty_acceptance_cases]
+
+frontend_implementation_verification:
+  applies_when: [ui_impact]
+  required_before: [release]
+  required: [prototype_ref, spec_ref, route_and_page_inventory, desktop_visual_evidence, narrow_view_visual_evidence, loading_empty_error_permission_interaction_results, console_warning_check, pnpm_commands, uncovered_differences, difference_owner]
+  verification: [actual_command, exit_code, executed_at, evidence_ref]
+  schema: docs/process/schemas/frontend-implementation-evidence.schema.json
+  validator: scripts/verify-frontend-implementation-evidence
+  acceptance: [kind_verification, template_false, status_approved, no_template_placeholders, console_warning_pass, independent_review_approved]
+  blocked_when: [unexplained_visual_difference, missing_visual_evidence, typecheck_only, claimed_alignment_without_evidence]
+  on_new_impact: [new_impacts, drift, reroute]
 
 unknown_impact:
   action: pause
@@ -366,5 +517,5 @@ prototype_modes:
 
 behavioral_invariants:
   wait_what_preserves_state: true
-  wizard_human_only: true
+  human_checkpoint_required_for_manual_steps: true
   diagnostics_redact_secrets: true

package/template/.agents/skills/yss-product-lifecycle/references/orchestration.md

@@ -6,7 +6,7 @@
 2. `setup readiness`：每个任务只执行一次，核对 tracker、五态标签和领域文档布局，并在本轮缓存结果；仅在 tracker、主远端、真实标签或配置变化时重查。
 3. 加载父 Ticket/checkpoint 与真实资产，计算最近可信阶段。
 4. 评估资产、门禁和 `stale`，选择第一个未阻塞工作单元。
-5. 调用一个最小 Matt/YSS 专项 skill，将结果归一化为 `Matt Skill Result`，验收输出并回写状态与证据。
+5. 执行最小生命周期工作单元：只实际调用允许的 model-invoked skill；原生工作单元可直接持有正式资产，Matt 兼容 user-invoked skill 仅作为 workflow reference，仍由用户显式启动。将结果归一化为 `Workflow Execution Result`，验收输出并回写状态与证据。
 6. 若仍在授权和自动推进边界内，回到第 3 步；否则暂停。
 
 不要仅输出下一个提示词后结束 `orchestrate`/`resume`。不要因进入业务代码阶段而退出主控；应把实现交给专项 skill，并在返回后继续核验。
@@ -40,7 +40,7 @@ Readiness 结果在同一任务内复用。只有 tracker、主远端、真实
 | 状态 | 判定 | 动作 |
 |---|---|---|
 | `ready` | tracker、Local `Status:` 或远程标签和领域布局兼容 | 继续 |
-| `missing` | 必要配置缺失 | 路由 `setup-matt-pocock-skills` |
+| `missing` | 必要配置缺失 | `needs-human`；说明缺失项并请用户显式运行 `setup-matt-pocock-skills`，随后回到 readiness |
 | `conflict` | 多个持久配置或真实标签/Local 状态互相矛盾 | 暂停并提出迁移方案，不覆盖 |
 | `degraded` | 已选择的 GitHub/GitLab 不可用 | 建 `docs/.scratch/<feature>/` 待发布草案，不改投平台 |
 | `not-applicable` | `template-source` | 只验证模板契约 |
@@ -51,11 +51,11 @@ tracker 选择和冲突按 `docs/agents/issue-tracker.md` 裁决：已持久化
 
 ## Matt flow 进入条件
 
-- `to-spec` 只能在 `grill-with-docs` 退出条件满足且没有未回流 runnable blocker 时进入；产物默认为 `ready-for-human`。
-- `to-tickets` 只能在 OpenAPI Freeze 或无 API 影响记录完成后进入，并且只能生成垂直切片 Ticket；YSS active 下初始角色统一为 `ready-for-human`，不得沿用 Matt 的通用 `ready-for-agent` 默认值。
-- `implement` 无论是多会话还是单会话，都必须满足 `ready-for-agent` 公式、批准并持久化的 Slice Implementation Contract 和 Build Architecture Checklist。
+- `work-unit.discovery-requirements` 实际调用 `grilling` 和 `domain-modeling`；`work-unit.discovery-opportunity` 按事实类型路由 `competitive-intelligence` 或 `research`。生命周期原生工作单元默认负责 Spec、Ticket 和实现资产；`to-spec`、`to-tickets`、`implement` 仅保留为显式兼容入口，结果必须回交生命周期验收。
+- 原生 `work-unit.ticket-decomposition` 只能在 OpenAPI Freeze 或无 API 影响记录后创建垂直切片，初始角色统一为 `ready-for-human`；生命周期复算完整公式后才能提升 `ready-for-agent`。
+- 原生 `work-unit.slice-implementation` 必须在生命周期批准并持久化 Slice Implementation Contract 和 Build Architecture Checklist 后执行；用户显式 `implement` 仍走兼容入口，不得绕过生命周期。
 - `implement` 遇到 backend `scaffold_status=required` 时，还必须满足原型确认后的脚手架策略：脚手架 Execution Result、`yss-backend-scaffold-parent` 基线、Wrapper 验证和 Router 合同重编译均已回写；否则停在工程基线，不得写业务代码。
-- Matt Result 出现 `drift`、`new_impacts`、`stale_candidates`、`violation`、`missing_evidence`、空 `evidence_refs` 或缺少必需字段时暂停当前工作单元。
+- `Workflow Execution Result` 出现 `drift`、`new_impacts`、`stale_candidates`、`violation`、`missing_evidence`、空 `evidence_refs` 或缺少必需字段时暂停当前工作单元；旧结果只能先经只读兼容 adapter 归一化。
 
 ## 审查与验证
 
@@ -63,6 +63,7 @@ tracker 选择和冲突按 `docs/agents/issue-tracker.md` 裁决：已持久化
 - 小改动和中等变更可由同一独立执行者完成 `code-review` 与 fresh verification，并在同一报告中分别记录 findings、命令、结果和残余风险。
 - 该执行者必须独立于实现者；新模块、高风险变更、职责冲突或需双人控制时，Reviewer 与 Verifier 分开。
 - `code-review` 是唯一默认代码审查 skill。GitLab、CI、Sonar、Alibaba Java 等治理事实作为仓库规则或专项检查输入，不再叠加第二个通用审查 skill。
+- UI 影响切片将 `UI fidelity` 作为 `code-review` 的条件第三轴；任何修复都会使候选摘要失效，必须重新捕获候选并重跑 Standards、Spec、UI fidelity 和 fresh verification。
 
 ## Git 授权
 

package/template/.agents/skills/yss-product-lifecycle/references/state-model.md

@@ -46,11 +46,14 @@ AND 当前工作单元消费的 contract_id/version 与最新批准版本一致
 AND Backend Slice Implementation Contract（后端适用）和 Build Architecture Checklist 已完成
 AND backend 影响且 scaffold_status=required 时，原型确认后的脚手架策略、`yss-backend-scaffold-parent` 基线、Wrapper 验证和 Router 重编译均已完成
 AND 所有后续生成代码均绑定主 YSS skill、依赖闭包、允许写路径、预期证据和 YSS Skill Execution Result
+AND UI 影响切片的前端实现还原计划已通过 schema 校验、`template=false`、`status=approved`，且基线引用可读取
 ```
 
 父 Ticket、Spec、设计、原型、OpenAPI Draft、wayfinder map 和 decision ticket 不得使用 `ready-for-agent`。
 
-YSS active 调用 `to-tickets` 时，垂直切片初始角色固定为 `ready-for-human`。只有 `yss-product-lifecycle` 复算上述公式全部为真后，才能把它提升为 `ready-for-agent`；Matt `to-tickets` 的独立默认值不参与该裁决。
+发布前还必须满足所有已触发门禁均为 `approved` 或 `not-applicable`；UI 影响切片必须额外通过 `gate.frontend-implementation-verified`，不能只凭 fresh verification 和回滚点放行。
+
+用户显式运行 `to-tickets` 后，垂直切片初始角色固定为 `ready-for-human`。只有 `yss-product-lifecycle` 复算上述公式全部为真后，才能把它提升为 `ready-for-agent`；生命周期不会自动调用 `to-tickets`，其默认标签也不参与该裁决。
 
 ## Review 与 Git 授权状态
 
@@ -60,7 +63,7 @@ Git 动作分别保存 `commit_authorized`、`commit_scope`、`commit_authorizat
 
 ## 状态块
 
-状态块位于主 tracker 的功能父 Ticket；Local Markdown 使用 `docs/.scratch/<feature>/parent-ticket.md`，远程 tracker 使用 Issue 并在本地功能包保留引用。平台不可用时才位于 stage checkpoint。只保存索引、状态、引用和因果关系：
+状态块位于主 tracker 的功能父 Ticket，并使用 `docs/process/templates/lifecycle-checkpoint-template.yaml` 的结构化形状和 `lifecycle-checkpoint.schema.json` 校验；Local Markdown 使用 `docs/.scratch/<feature>/parent-ticket.md`，可将完整 checkpoint 保存在 `docs/.scratch/<feature>/gates/lifecycle-checkpoint.yaml` 后由父 Ticket 引用，远程 tracker 使用 Issue 并在本地功能包保留引用。平台不可用时才位于 stage checkpoint。只保存索引、状态、引用和因果关系：
 
 ```yaml
 lifecycle:

package/template/.agents/skills/yss-prototype-stage/SKILL.md

@@ -11,7 +11,7 @@ description: Use when a YSS feature has product-design impact on a primary flow,
 
 - 先由 `yss-product-lifecycle` 判断产品设计影响；无行为变化的孤立视觉修复记录 `not-applicable`，不创建空资产。
 - Codex 的产出主入口是 `product-design:index`；其他 Agent 使用等价的产品设计能力，但必须产出本技能规定的相同资产和证据。能力或证据不能等价时，暂停并回到人工确认。
-- 旧 `product-design-prototype`、`wireframe-prototype`、`high-fidelity-html-prototype` 仅为兼容入口；从它们进入时立即回到本合同。
+- `product-design-prototype`、`high-fidelity-html-prototype` 仅为兼容入口；从它们进入时立即回到本合同。已退休的原型技能不得继续路由。
 
 ## 资产与门禁顺序
 

package/template/.claude/skills/ask-matt/SKILL.md

@@ -80,7 +80,6 @@ Off the main flow entirely.
 - **`/prototype`** — a small, throwaway program that answers one design question: does this state model feel right, or what should this UI look like. Throwaway is a constraint on how the code is written, not a promise to destroy it: the answer folds into the real code, and the prototype itself is kept as a **primary source** on a `prototype/<name>` branch out of main, pointed at from the implementation issue. It's the detour in step 2 of the main flow, but reach for it any time a design question is hard to settle on paper.
 - **`/research`** — delegate reading legwork to a **background agent**: it investigates a question against **primary sources**, then leaves a cited Markdown file in the repo. Keep working while it reads. The file it produces is something to take *into* the main flow at `/grill-with-docs` — research feeds the thinking, it doesn't replace it.
 - **`/to-questionnaire`** — when the thing blocking you isn't in your head or the codebase but in **someone else's**, this writes them a questionnaire to fill in. It's the inverse of `/grill-me`: instead of interviewing you about the subject, it interviews you about the **send** — who it's going to, what you need back — and aims the questions at the gap. What comes back is material for `/grill-with-docs` or `/to-spec`.
-- **`/wizard`** — for the steps only a **human** can take: provisioning infrastructure, setting up credentials or CI secrets, clicking through an unfamiliar third-party dashboard, running a one-off migration or cutover. It generates an interactive bash script that opens each URL, captures each value, and writes it into `.env` and GitHub secrets — so the procedure stops being something you re-explain to an agent every time. Model-invoked, so the agent reaches for it the moment it hits a wall only you can pass. If the agent could just do it itself, it should; this is for where a human is genuinely in the loop.
 - **`/wait-what`** — the corrective for a message that didn't land. Use it mid-conversation, inside any other skill, and the agent re-pitches what it just said with the context you were missing, in plain English, using the `CONTEXT.md` vocabulary. It works after the fact; `/grill-with-docs` is the upfront cure, because a shared language agreed early is what stops the jargon arriving at all.
 - **`/teach`** — learn a concept over multiple sessions, using the current directory as a stateful workspace.
 - **`/writing-for-agents`** — reference for writing documents agents consume: skills, AGENTS.md, pointed-at docs.

package/template/.claude/skills/code-review/SKILL.md

@@ -10,7 +10,7 @@ Two-axis review of a pinned candidate against a fixed point:
 
 Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
 
-The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if `docs/agents/issue-tracker.md` is missing.
+If `docs/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
 ## Process
 

package/template/.claude/skills/diagnosing-bugs/SKILL.md

@@ -127,7 +127,7 @@ If a correct seam exists:
 4. Watch it pass.
 5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
 
-## Phase 6 — Cleanup + post-mortem
+## Phase 6 — Cleanup
 
 Required before declaring done:
 
@@ -135,6 +135,4 @@ Required before declaring done:
 - [ ] Regression test passes (or absence of seam is documented)
 - [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
 - [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
-- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
-
-**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.
+- [ ] The hypothesis that turned out correct is stated in the commit / PR message, so the next debugger learns

package/template/.claude/skills/domain-modeling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: domain-modeling
-description: Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.
+description: Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a CONTEXT.md, or recording or editing an ADR.
 ---
 
 # Domain Modeling

package/template/.claude/skills/grill-me/SKILL.md

@@ -4,4 +4,4 @@ description: A relentless interview to sharpen a plan or design.
 disable-model-invocation: true
 ---
 
-Run a `/grilling` session.
+Call the Skill tool with `grilling`.

package/template/.claude/skills/grill-with-docs/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: grill-with-docs
 description: Use when the user explicitly requests a relentless design interview that must preserve resolved glossary terms, ADR-worthy decisions, and factual research evidence.
+disable-model-invocation: true
 ---
 
-Run a `grilling` session with `domain-modeling` active.
+Call the Skill tool with `grilling`, then call it separately with `domain-modeling`.
 
 ## Output Contract
 

package/template/.claude/skills/grilling/SKILL.md

@@ -7,11 +7,17 @@ Interview the user relentlessly until you reach a shared understanding. Map this
 
 Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled — the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.
 
-Each question should be formatted like so:
+Format a round like so:
 
 ```
 ❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
 
+➡️ <your recommended answer>
+
+---
+
+❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
 ➡️ <your recommended answer>
 ```
 

package/template/.claude/skills/maintaining-skills/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: maintaining-skills
+description: Use when creating, modifying, validating, or retiring reusable Agent skills.
+---
+
+# Maintaining Skills
+
+Create skills that add useful, non-obvious guidance without constraining unrelated work.
+
+## Working Contract
+
+1. Inspect the skill's callers, ownership, projections, and validation policy before editing. Preserve user intent, authorization boundaries, supported runtimes, and existing metadata unless the requested change requires otherwise.
+2. Assume the Agent already has general reasoning and tool competence. Record only domain knowledge, decision criteria, fragile invariants, or repeatable operations that materially improve outcomes. Do not turn one example or past failure into a universal rule.
+3. Keep discovery precise: use a lowercase hyphenated name and a concise description that states the capability and when it applies. Avoid catchalls that attract unrelated requests.
+4. Keep `SKILL.md` as short as the task permits. Put conditional detail in `references/`, deterministic repeated operations in `scripts/`, and files intended for generated output in `assets/`. Create only resources with a concrete use.
+5. Match specificity and validation to risk. Prefer outcome and decision criteria when several approaches are valid; use fixed steps or absolute rules only for correctness, safety, permissions, or genuinely fragile workflows.
+6. Follow the repository's declared maintenance and review policy. If none exists, run structural validation plus focused checks of the behavior or invariant changed. Use independent forward testing only when complexity or risk makes it meaningful; do not require a failing baseline for every ordinary edit.
+7. After changes, validate frontmatter, naming, references, scripts, projections, locks, and affected callers. Retire obsolete names and resources unless the repository explicitly requires compatibility.
+
+## Boundaries
+
+- Project rules belong in the project's authoritative instructions, not duplicated inside a generic skill.
+- Platform-private skills or absolute local paths are not portable shared dependencies.
+- A validation command proves only what it checks; structural validation alone does not prove good Agent decisions.
+- Do not create README files, changelogs, examples, routers, or placeholder directories without a concrete requirement.

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

@@ -36,7 +36,7 @@ If no Spec baseline exists, route back to `yss-product-lifecycle` / `grill-with-
 
 | Need | Add skill/tool |
 |---|---|
-| Low-fidelity page or flow sketch | `wireframe-prototype` |
+| Low-fidelity page or flow sketch | `product-design:index` |
 | Figma work or existing Figma file | `figma` / `figma-use` |
 | YSS implementation constraints | `yss-router`, then `yss-ui`, `yss-formily`, `yss-page-module-development` as needed |
 

package/template/.claude/skills/to-spec/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 This skill takes the current conversation context and codebase understanding and produces a spec. Do NOT interview the user — just synthesize what you already know.
 
-The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not.
+If the issue tracker or triage label vocabulary is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
 ## Process
 

package/template/.claude/skills/to-tickets/SKILL.md

@@ -8,7 +8,7 @@ disable-model-invocation: true
 
 Break a plan, spec, or conversation into a set of **tickets** — tracer-bullet vertical slices, each declaring the tickets that **block** it.
 
-The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not.
+If the issue tracker or triage label vocabulary is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
 ## Process
 

package/template/.claude/skills/triage/SKILL.md

@@ -40,7 +40,7 @@ For a PR, the same states read against the attached code: `ready-for-agent` mean
 
 Every triaged issue should carry exactly one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything else.
 
-These are canonical role names — the actual label strings used in the issue tracker may differ. The mapping should have been provided to you - run `/setup-matt-pocock-skills` if not.
+These are canonical role names. The actual label strings used in the issue tracker may differ. The mapping should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`.
 
 State transitions: an unlabeled issue normally goes to `needs-triage` first; from there it moves to `needs-info`, `ready-for-agent`, `ready-for-human`, or `wontfix`. `needs-info` returns to `needs-triage` once the reporter replies. The maintainer can override at any time — flag transitions that look unusual and ask before proceeding.
 
@@ -73,7 +73,7 @@ Show counts and a one-line summary per item. Let the maintainer pick.
 
 3. **Verify the claim.** Before any grilling, check that the claim holds up. For a bug, reproduce it from the reporter's steps. For a PR, confirm the diff does what it claims — check it out, run the relevant tests or commands. Report what happened: confirmed (with code path), failed, or insufficient detail (a strong `needs-info` signal). A confirmed verification makes a much stronger agent brief.
 
-4. **Grill (if needed).** If the request needs fleshing out, run the `/grilling` and `/domain-modeling` skills together — grill it into shape a round of questions at a time, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land.
+4. **Grill (if needed).** If the request needs fleshing out, call the Skill tool twice, for "grilling" and "domain-modeling", and grill it into shape a round of questions at a time, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land.
 
 5. **Apply the outcome:**
    - `ready-for-agent` — post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)).

package/template/.claude/skills/wait-what/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: wait-what
-description: Stop. That last message did not land — re-pitch it.
+description: "Stop. That last message did not land: re-pitch it."
 disable-model-invocation: true
 ---
 
-Wait — I don't understand where you've got to here. Re-pitch that: give me a little bit of context, talk in ASD-STE100 Simplified Technical English, and use the ubiquitous language from `CONTEXT.md`.
+Wait, I don't understand where you've got to here. Re-pitch that: give me a little bit of context, talk in ASD-STE100 Simplified Technical English, and use the ubiquitous language from `CONTEXT.md` (follow `CONTEXT-MAP.md` to the right one if the repo has more than one).

package/template/.claude/skills/wayfinder/SKILL.md

@@ -22,7 +22,7 @@ The map is a single issue on this repo's issue tracker, labelled `wayfinder:map`
 
 The map is an **index**, not a store. It lists the decisions made and points at the tickets that hold their detail; a decision lives in exactly one place — its ticket — so the map never restates it, only gists it and links.
 
-**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if not. Consult the tracker doc's "Wayfinding operations" section for how _this_ repo expresses them. If no tracker has been provided, default to the local-markdown tracker.
+**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** The issue tracker should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`. Consult the tracker doc's "Wayfinding operations" section for how _this_ repo expresses them. If no tracker has been provided, default to the local-markdown tracker.
 
 ### The map body