create-yss-spec 3.5.3 → 3.5.5

package/template/.agents/skills/setup-matt-pocock-skills/references/write-configuration.md

@@ -0,0 +1,42 @@
+# 配置写入与种子模板
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。仓库脚本与 pnpm 命令从当前登记的项目根目录执行。
+
+### 4. Write
+
+**Pick the file to edit:**
+
+- If `AGENTS.md` exists, edit it.
+- If it is missing, ask before creating it.
+
+If an `## Agent skills` block already exists in the chosen file, update its contents in-place rather than appending a duplicate. Don't overwrite user edits to the surrounding sections.
+
+The block:
+
+```markdown
+## Agent skills
+
+### Issue tracker
+
+[one-line summary of where issues are tracked]. See `.template-spec/agents/issue-tracker.md`.
+
+### Triage labels
+
+[one-line summary of the label vocabulary]. See `.template-spec/agents/triage-labels.md`.
+
+### Domain docs
+
+[one-line summary: one root `CONTEXT.md`, with bounded contexts represented inside its business glossary]. See 根 `CONTEXT.md` 的消费规则.
+```
+
+Include the `### Triage labels` sub-block, and write `.template-spec/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 (only if `triage` is installed)
+- 根 `CONTEXT.md` 文首合同与消费规则 — domain doc consumer rules + layout
+
+For an unsupported tracker request, stop and require a YSS tracker-contract extension; do not write an unsupported platform into `.template-spec/agents/issue-tracker.md`.

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

@@ -8,68 +8,15 @@ This explicit compatibility entry synthesizes confirmed context into a Spec draf
 
 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
+## 起草过程
 
-1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the spec, and respect any ADRs in the area you're touching.
+1. 消费根 `CONTEXT.md`、已确认 Plan、当前决定和相关 ADR；复用已确认测试 seam，只对新增或实质变化的决定补充澄清。
+2. 使用仓库权威 `.template-spec/templates/spec-template.md`，与常规生命周期入口共享结构；按 `.template-spec/process/document-writing.md` 写作。故事数量由范围决定。FR/NFR/AC、来源、验收和未决项采用 `.template-spec/process/plan-spec-quality.md` 的表达约定。
+3. Spec 描述可观察行为、边界、例外和非目标。实现决策仅引用已确认上游约束；技术架构、OpenAPI Freeze 和实现任务交由既有下游阶段，不在本入口提前决定。
+4. 同时按 `.template-spec/process/business-tickets.md` 起草业务 Ticket 和 FR/AC 覆盖集合；每票放入 `business-tickets/`，Spec 只引用集合路径。复用已有稳定 ID，不等待工程、OpenAPI 或技术设计。草案未决项保留责任人和解决时点，运行 `scripts/verify-business-tickets <集合> --mode draft` 后一并回交验收。
+5. 将草稿按主控允许路径持久化；主 tracker 按项目配置使用，不从 Git remote 猜测。平台不可用时保留待发布草稿。Spec 使用 `ready-for-human`，起草者不批准、不设置 `ready-for-agent`。Design 校准同一组业务票，下游实现 Slice 仍放入 `issues/` 并保留工程和批准门禁。
+6. 可按需运行只读 `scripts/inspect-plan-spec check --root . --spec <Spec路径>` 辅助审阅；发现和未评估项不能转换为流转许可，原有 Context、决定和批准验证照常执行。
 
-2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one.
+## 来源与适配
 
-Reuse already confirmed seams; ask only when a seam is new or materially changed.
-
-3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-human` triage label. Spec drafts need a human baseline approval before they are `approved`, and before implementation tickets may become `ready-for-agent`. Do not label the Spec itself `ready-for-agent`.
-
-<spec-template>
-
-## Problem Statement
-
-The problem that the user is facing, from the user's perspective.
-
-## Solution
-
-The solution to the problem, from the user's perspective.
-
-## User Stories
-
-A LONG, numbered list of user stories. Each user story should be in the format of:
-
-1. As an <actor>, I want a <feature>, so that <benefit>
-
-<user-story-example>
-1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
-</user-story-example>
-
-This list of user stories should be extremely extensive and cover all aspects of the feature.
-
-## Implementation Decisions
-
-A list of implementation decisions that were made. This can include:
-
-- The modules that will be built/modified
-- The interfaces of those modules that will be modified
-- Technical clarifications from the developer
-- Architectural decisions
-- Schema changes
-- API contracts
-- Specific interactions
-
-Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
-
-Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
-
-## Testing Decisions
-
-A list of testing decisions that were made. Include:
-
-- A description of what makes a good test (only test external behavior, not implementation details)
-- Which modules will be tested
-- Prior art for the tests (i.e. similar types of tests in the codebase)
-
-## Out of Scope
-
-A description of the things that are out of scope for this spec.
-
-## Further Notes
-
-Any further notes about the feature.
-
-</spec-template>
+保留 mattpocock 上游来源与锁定记录。YSS 适配仅统一权威模板、生命周期边界和本地持久化方式；不维护另一份内嵌模板。

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

@@ -1,105 +1,39 @@
 ---
 name: to-tickets
-description: "显式调用时，将已确认的 Plan 或 Spec 拆成带依赖的垂直切片 Ticket，并按配置的 tracker 持久化。"
+description: 显式按当前生命周期拆分 Ticket；Spec/Design 起草业务票，研发侧承接业务票细化实现 Slice。
 disable-model-invocation: true
 ---
 
 # To Tickets
 
-Break an explicitly requested, confirmed plan or Spec into tracer-bullet Ticket drafts. Before any formal write, return to the active lifecycle orchestrator for repository identity, current inputs, allowed paths and applicable gates. Template-source maintenance does not create product Tickets. The explicit entry may write its prepared artifacts only within that preflight contract and returns them to the orchestrator for validation and acceptance; it cannot approve a Slice Contract or decide readiness.
+本兼容入口仅由用户显式调用。写入前回交当前生命周期主控，核验仓库身份、当前输入、允许路径和适用门禁。`template-source` 不生成产品票；起草者不批准 Slice 合同、不设置 `ready-for-agent`。保留 mattpocock 上游来源与锁定记录，采用以下 YSS 阶段适配。
 
-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
+按 `.template-spec/process/business-tickets.md` 和当前工作单元选择一种输出；目录是否存在不决定路线。
 
-### 1. Gather context
+| 当前范围 | 输出与依据 | 工程前置 |
+|---|---|---|
+| Spec / 产品设计 | 业务 Ticket 草案或校准；按用户行为、可验收结果、FR/AC、适用规则和场景拆分 | 不需要实现仓库、OpenAPI Freeze 或构建命令 |
+| 研发 | 消费正式业务集合，细化窄垂直实现 Slice；保留业务 Ticket 和原始 FR/AC 引用 | 技术分析可起草；正式化仍需当前工程契约及仓库准备 |
 
-Work from whatever is already in the conversation context. If the user passes a reference (a spec path, an issue number or URL) as an argument, fetch it and read its full body and comments.
+独立 Design profile 只允许第一种输出，完成业务正式化后进入战略交接。全生命周期使用本地已确认资产，不导出再导入自己的包。
 
-### 2. Explore the codebase (optional)
+## 起草与校准
 
-If you have not already explored the codebase, do so to understand the current state of the code. Ticket titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching.
+1. 读取已有 Spec、根 `CONTEXT.md`、当前决定、集合及相关设计。先复用稳定 ID，再根据真实范围增删或细化；不重新生成一套票。
+2. 业务票用 `.template-spec/templates/business-ticket-template.md`，每票一个 `business-tickets/BT-<id>.md`。集合用 `business-ticket-set-template.yaml`，只保存引用、版本、摘要和覆盖处置。依赖表达业务前后置，禁止按 Controller / Service / Repository 分票，也不机械地一条 FR 一票。
+3. Design 按页面流、状态、失败和恢复路径校准。无产品设计影响时记录依据；不生成空原型。未决项保留责任人、解决时点及是否阻断，延期遵守既有决定协议。
+4. 研发输出用 `.template-spec/templates/vertical-slice-ticket-template.md`，放入 `issues/`；一个业务票可细化为多个 Slice。实现票保留 `kind: vertical-slice-ticket`、业务集合和业务票来源以及原始 AC 引用。
 
-Look for opportunities to prefactor the code to make the implementation easier. "Make the change easy, then make the easy change."
+仅研发细化时按需查看已登记工程及 ADR。每个实现 Slice 贯通本次行为命中的技术层、可独立验证；不因模板枚举 schema / API / UI 就引入未命中的技术层。必要的机械重构按 expand → 分批迁移 → contract 排序；无法独立保持绿色的批次须明确共享集成验证边界，不能声称各批已独立完成。
 
-### 3. Draft vertical slices
+## 审阅与回交
 
-Break the work into **tracer bullet** tickets.
+展示每票的业务结果、范围、验收、依赖与未决项，以及集合覆盖情况。按实际缺口提问；等义细化沿既有授权延续协议核验，范围、规则或验收实质变化返回原决定边界。拆分本身不增加常规人工批准节点。
 
-<vertical-slice-rules>
+业务草案运行 `scripts/verify-business-tickets <集合> --mode draft`；正式化使用 `--mode formal`，并消费已有 Spec / 适用产品设计批准及当前独立专业审查。结构检查不代替语义审查或真实批准。阶段工作项完成、业务正式化和实现就绪分别回报。
 
-- Each slice cuts a narrow but COMPLETE path through every layer (schema, API, UI, tests) — vertical, NOT a horizontal slice of one layer
-- A completed slice is demoable or verifiable on its own
-- Each slice is sized to fit in a single fresh context window
-- Any prefactoring should be done first
+主 tracker 以 `.template-spec/agents/issue-tracker.md` 为准，不从 Git remote 猜测。配置缺失时回交主控处理，不自动调用其他显式 Skill。远程不可用或未获发布授权时保留本地待发布草案；远程发布需用户明确授权。业务票保持 `draft` / `ready-for-human`，实现票只有主控完成正式门禁和当前合同批准后才可 `ready-for-agent`。
 
-</vertical-slice-rules>
-
-Give each ticket its **blocking edges** — the other tickets that must complete before it can start. A ticket with no dependency edges still needs a current approved Slice Contract and all applicable implementation gates before it can start.
-
-**Wide refactors are the exception to vertical slicing.** A **wide refactor** is one mechanical change — rename a column, retype a shared symbol — whose **blast radius** fans across the whole codebase, so a single edit breaks thousands of call sites at once and no vertical slice can land green. Don't force it into a tracer bullet; sequence it as **expand–contract**. First expand: add the new form beside the old so nothing breaks. Then migrate the call sites over in batches sized by blast radius (per package, per directory), each batch its own ticket blocked by the expand, keeping CI green batch to batch because the old form still exists. Finally contract: delete the old form once no caller remains, in a ticket blocked by every migrate batch. When even the batches can't stay green alone, keep the sequence but let them share an integration branch that all block a final integrate-and-verify ticket — green is promised only there.
-
-### 4. Quiz the user
-
-Present the proposed breakdown as a numbered list. For each ticket, show:
-
-- **Title**: short descriptive name
-- **Blocked by**: which other tickets (if any) must complete first
-- **What it delivers**: the end-to-end behaviour this ticket makes work
-
-Ask the user:
-
-- Does the granularity feel right? (too coarse / too fine)
-- Are the blocking edges correct — does each ticket only depend on tickets that genuinely gate it?
-- Should any tickets be merged or split further?
-
-Reuse an existing approval that covers this same breakdown. Ask only about unresolved scope, granularity or dependency decisions; return accepted drafts and evidence to the orchestrator.
-
-### 5. Publish the tickets to the configured tracker
-
-Publish the approved tickets. **How** depends on the tracker `/setup-matt-pocock-skills` configured — the tickets are the same either way, only the shape of the blocking edges changes:
-
-- **Local files** → write one file per ticket under `docs/.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01` in dependency order (blockers first). Each file's "Blocked by" lists the numbers/titles it depends on. Use the per-ticket file template below — one ticket per file, never a single combined file.
-- **A real issue tracker (GitHub, Linear, …)** → publish one issue per ticket in dependency order (blockers first) so each ticket's blocking edges can reference real identifiers. Use the platform's native blocking / sub-issue relationship where it has one; otherwise set each ticket's "Blocked by" to the blocking issues. Keep drafts `ready-for-human`. Only the orchestrator may mark a narrow slice `ready-for-agent` after checking its current approved contract and applicable gates. Publishing to a remote tracker requires explicit authorization for that action.
-
-Work the **frontier**: any ticket whose blockers are all done. For a purely linear chain that means top to bottom.
-
-Do NOT close or modify any parent issue.
-
-<local-ticket-template>
-
-# <NN> — <Ticket title>
-
-**What to build:** the end-to-end behaviour this ticket makes work, from the user's perspective — not a layer-by-layer implementation list.
-
-**Blocked by:** the numbers/titles of the tickets that gate this one, or "None — readiness still requires contract and gate verification".
-
-**Status:** ready-for-human
-
-- [ ] Acceptance criterion 1
-- [ ] Acceptance criterion 2
-
-</local-ticket-template>
-
-<issue-template>
-
-## Parent
-
-A reference to the parent issue on the tracker (if the source was an existing issue, otherwise omit this section).
-
-## What to build
-
-The end-to-end behaviour this ticket makes work, from the user's perspective — not layer-by-layer implementation.
-
-## Acceptance criteria
-
-- [ ] Criterion 1
-- [ ] Criterion 2
-
-## Blocked by
-
-- A reference to each blocking ticket, or "None — readiness still requires contract and gate verification".
-
-</issue-template>
-
-In either form, avoid specific file paths or code snippets — they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
+Spec、map 与父 Ticket 引用同一集合，不复制正文。本入口回交证据及待同步内容，由主控维护父 Ticket 状态；不得自行关闭父票或宣布功能完成。

package/template/.agents/skills/using-git-worktrees/SKILL.md

@@ -58,132 +58,15 @@ Only proceed to Step 1b if you have no native worktree tool available.
 
 ### 1b. Git Worktree Fallback
 
-**Only use this if Step 1a does not apply** — you have no native worktree tool available. Create a worktree manually using git.
+仅无原生工具且创建已获授权时，读取 [手工 Git worktree 创建](references/git-fallback.md)。目录遵循用户偏好，项目内目录先核验忽略规则；创建失败保留当前 checkout 和隔离边界。
 
-#### Directory Selection
+## Steps 2–3: Setup and baseline
 
-Follow this priority order. Explicit user preference always beats observed filesystem state.
+进入新建或已有隔离工作区后，读取 [项目准备与基线验证](references/setup-and-baseline.md)，选择项目声明的依赖与测试命令。已有失败应记录并区分，不得称基线干净。
 
-1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.
+## 排查
 
-2. **Check for an existing project-local worktree directory:**
-   ```bash
-   ls -d .worktrees 2>/dev/null     # Preferred (hidden)
-   ls -d worktrees 2>/dev/null      # Alternative
-   ```
-   If found, use it. If both exist, `.worktrees` wins.
-
-3. **If there is no other guidance available**, default to `.worktrees/` at the project root.
-
-#### Safety Verification (project-local directories only)
-
-**MUST verify directory is ignored before creating worktree:**
-
-```bash
-git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
-```
-
-**If NOT ignored:** Add the chosen directory to .gitignore within the authorized setup scope, verify it is ignored, then proceed. Leave that edit uncommitted unless Git commit authorization already covers it.
-
-**Why critical:** Prevents accidentally committing worktree contents to repository.
-
-#### Create the Worktree
-
-```bash
-# Determine path based on chosen location
-path="$LOCATION/$BRANCH_NAME"
-
-git worktree add "$path" -b "$BRANCH_NAME"
-cd "$path"
-```
-
-**Isolation failure:** If worktree creation is blocked, report the actual error and preserve the current checkout. Use another already authorized isolated location when available; ask only if proceeding would change the requested isolation boundary. Do not silently begin implementation in the original checkout.
-
-## Step 2: Project Setup
-
-Auto-detect and run appropriate setup:
-
-```bash
-# Node.js: inspect packageManager, lockfile and project instructions first.
-# In a pnpm project, use the recorded version and frozen lockfile:
-# pnpm install --frozen-lockfile
-# Use npm/yarn only when the repository actually declares them.
-
-# Rust
-if [ -f Cargo.toml ]; then cargo build; fi
-
-# Python
-if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-if [ -f pyproject.toml ]; then poetry install; fi
-
-# Go
-if [ -f go.mod ]; then go mod download; fi
-```
-
-## Step 3: Verify Clean Baseline
-
-Run tests to ensure workspace starts clean:
-
-```bash
-# Use project-appropriate command
-pnpm test / cargo test / pytest / go test ./... # select the declared project runner
-```
-
-**If tests fail:** Record the existing failure and investigate within the authorized scope. Ask only if a new decision or access is needed; do not label the baseline clean.
-
-**If tests pass:** Report ready.
-
-### Report
-
-```
-Worktree ready at <full-path>
-Tests passing (<N> tests, 0 failures)
-Ready to implement <feature-name>
-```
-
-## Quick Reference
-
-| Situation | Action |
-|-----------|--------|
-| Already in linked worktree | Skip creation (Step 0) |
-| In a submodule | Treat as normal repo (Step 0 guard) |
-| Native worktree tool available | Use it (Step 1a) |
-| No native tool | Git worktree fallback (Step 1b) |
-| `.worktrees/` exists | Use it (verify ignored) |
-| `worktrees/` exists | Use it (verify ignored) |
-| Both exist | Use `.worktrees/` |
-| Neither exists | Check instruction file, then default `.worktrees/` |
-| Directory not ignored | Add to .gitignore; commit only when authorized |
-| Permission error on create | Report failure; preserve the requested isolation boundary |
-| Tests fail during baseline | Record failures; continue authorized diagnosis |
-| No package.json/Cargo.toml | Skip dependency install |
-
-## Common Mistakes
-
-### Fighting the harness
-
-- **Problem:** Using `git worktree add` when the platform already provides isolation
-- **Fix:** Step 0 detects existing isolation. Step 1a defers to native tools.
-
-### Skipping detection
-
-- **Problem:** Creating a nested worktree inside an existing one
-- **Fix:** Always run Step 0 before creating anything
-
-### Skipping ignore verification
-
-- **Problem:** Worktree contents get tracked, pollute git status
-- **Fix:** Always use `git check-ignore` before creating project-local worktree
-
-### Assuming directory location
-
-- **Problem:** Creates inconsistency, violates project conventions
-- **Fix:** Follow priority: explicit instructions > existing project-local directory > default
-
-### Proceeding with failing tests
-
-- **Problem:** Can't distinguish new bugs from pre-existing issues
-- **Fix:** Distinguish baseline failures from new defects; ask only for a missing decision
+遇到目录选择、嵌套工作树、忽略规则或基线失败时，读取 [常见错误速查](references/troubleshooting.md)。
 
 ## Red Flags
 

package/template/.agents/skills/using-git-worktrees/references/git-fallback.md

@@ -0,0 +1,46 @@
+# 手工 Git worktree 创建
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。Git、依赖安装和测试命令从当前仓库或选定的工作树根目录执行。
+
+### 1b. Git Worktree Fallback
+
+**Only use this if Step 1a does not apply** — you have no native worktree tool available. Create a worktree manually using git.
+
+#### Directory Selection
+
+Follow this priority order. Explicit user preference always beats observed filesystem state.
+
+1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.
+
+2. **Check for an existing project-local worktree directory:**
+   ```bash
+   ls -d .worktrees 2>/dev/null     # Preferred (hidden)
+   ls -d worktrees 2>/dev/null      # Alternative
+   ```
+   If found, use it. If both exist, `.worktrees` wins.
+
+3. **If there is no other guidance available**, default to `.worktrees/` at the project root.
+
+#### Safety Verification (project-local directories only)
+
+**MUST verify directory is ignored before creating worktree:**
+
+```bash
+git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+```
+
+**If NOT ignored:** Add the chosen directory to .gitignore within the authorized setup scope, verify it is ignored, then proceed. Leave that edit uncommitted unless Git commit authorization already covers it.
+
+**Why critical:** Prevents accidentally committing worktree contents to repository.
+
+#### Create the Worktree
+
+```bash
+# Determine path based on chosen location
+path="$LOCATION/$BRANCH_NAME"
+
+git worktree add "$path" -b "$BRANCH_NAME"
+cd "$path"
+```
+
+**Isolation failure:** If worktree creation is blocked, report the actual error and preserve the current checkout. Use another already authorized isolated location when available; ask only if proceeding would change the requested isolation boundary. Do not silently begin implementation in the original checkout.

package/template/.agents/skills/using-git-worktrees/references/setup-and-baseline.md

@@ -0,0 +1,45 @@
+# 项目准备与基线验证
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。Git、依赖安装和测试命令从当前仓库或选定的工作树根目录执行。
+
+## Step 2: Project Setup
+
+Auto-detect and run appropriate setup:
+
+```bash
+# Node.js: inspect packageManager, lockfile and project instructions first.
+# In a pnpm project, use the recorded version and frozen lockfile:
+# pnpm install --frozen-lockfile
+# Use npm/yarn only when the repository actually declares them.
+
+# Rust
+if [ -f Cargo.toml ]; then cargo build; fi
+
+# Python
+if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+if [ -f pyproject.toml ]; then poetry install; fi
+
+# Go
+if [ -f go.mod ]; then go mod download; fi
+```
+
+## Step 3: Verify Clean Baseline
+
+Run tests to ensure workspace starts clean:
+
+```bash
+# Use project-appropriate command
+pnpm test / cargo test / pytest / go test ./... # select the declared project runner
+```
+
+**If tests fail:** Record the existing failure and investigate within the authorized scope. Ask only if a new decision or access is needed; do not label the baseline clean.
+
+**If tests pass:** Report ready.
+
+### Report
+
+```
+Worktree ready at <full-path>
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```

package/template/.agents/skills/using-git-worktrees/references/troubleshooting.md

@@ -0,0 +1,47 @@
+# 工作树常见错误
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。Git、依赖安装和测试命令从当前仓库或选定的工作树根目录执行。
+
+## Quick Reference
+
+| Situation | Action |
+|-----------|--------|
+| Already in linked worktree | Skip creation (Step 0) |
+| In a submodule | Treat as normal repo (Step 0 guard) |
+| Native worktree tool available | Use it (Step 1a) |
+| No native tool | Git worktree fallback (Step 1b) |
+| `.worktrees/` exists | Use it (verify ignored) |
+| `worktrees/` exists | Use it (verify ignored) |
+| Both exist | Use `.worktrees/` |
+| Neither exists | Check instruction file, then default `.worktrees/` |
+| Directory not ignored | Add to .gitignore; commit only when authorized |
+| Permission error on create | Report failure; preserve the requested isolation boundary |
+| Tests fail during baseline | Record failures; continue authorized diagnosis |
+| No package.json/Cargo.toml | Skip dependency install |
+
+## Common Mistakes
+
+### Fighting the harness
+
+- **Problem:** Using `git worktree add` when the platform already provides isolation
+- **Fix:** Step 0 detects existing isolation. Step 1a defers to native tools.
+
+### Skipping detection
+
+- **Problem:** Creating a nested worktree inside an existing one
+- **Fix:** Always run Step 0 before creating anything
+
+### Skipping ignore verification
+
+- **Problem:** Worktree contents get tracked, pollute git status
+- **Fix:** Always use `git check-ignore` before creating project-local worktree
+
+### Assuming directory location
+
+- **Problem:** Creates inconsistency, violates project conventions
+- **Fix:** Follow priority: explicit instructions > existing project-local directory > default
+
+### Proceeding with failing tests
+
+- **Problem:** Can't distinguish new bugs from pre-existing issues
+- **Fix:** Distinguish baseline failures from new defects; ask only for a missing decision

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

@@ -26,81 +26,17 @@ The map is an **index**, not a store. It lists the decisions made and points at
 
 **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
+### Map and ticket format
 
-The whole map at low resolution, loaded once per session. Open tickets are **not** listed — they are open child issues, found by query.
-
-```markdown
-## Destination
-
-<what reaching the end of this map looks like — the spec, decision, or change this effort is finding its way to. One or two lines; every session orients to it before choosing a ticket.>
-
-## Notes
-
-<domain; skills every session should consult; standing preferences for this effort>
-
-## Decisions so far
-
-<!-- the index — one line per closed ticket: enough to judge relevance, then zoom the link for the detail the ticket holds -->
-
-- [<closed ticket title>](link) — <one-line gist of the answer>
-
-## Not yet specified
-
-<!-- see "Fog of war": in-scope fog you can't ticket yet; graduates as the frontier advances -->
-
-## Out of scope
-
-<!-- see "Out of scope": work ruled beyond the destination; closed, never graduates -->
-```
-
-### Tickets
-
-Each ticket is a **child issue** of the map; the tracker's issue id is its identity. Its body is the question, bounded by a coherent decision and the current runtime/context capacity:
-
-```markdown
-## Question
-
-<the decision or investigation this ticket resolves>
-```
-
-Each ticket carries a `wayfinder:<type>` label — one of `research`, `prototype`, `grilling`, `task` (see [Ticket Types](#ticket-types)).
-
-A session **claims** a ticket by assigning it to the dev driving the map, **first**, before any work, so concurrent sessions skip it. That assignee _is_ the claim: an open, unassigned ticket is unclaimed.
-
-Blocking uses the tracker's **native** dependency relationship — essential because it renders the frontier _visually_ in the tracker's own UI, so the human sees what's takeable without opening the map. Only a tracker that lacks native blocking falls back to a body convention. A ticket is **unblocked** when every ticket blocking it is closed; the **frontier** is the open, unblocked, unclaimed children — the edge of the known.
-
-The answer isn't part of the body — it's recorded on resolution (see [Work through the map](#work-through-the-map)). Assets created while resolving a ticket are linked from the issue, not pasted in.
+创建或更新地图 / Ticket 时读取 [资产结构](references/map-format.md)。地图只索引决定，详情留在 Ticket；先认领再处理，以原生依赖表示阻塞。
 
 ## Ticket Types
 
-Every ticket is either **HITL** — human in the loop, worked _with_ a human who speaks for themselves — or **AFK**, driven by the agent alone. A HITL ticket only resolves through that live exchange; the agent never stands in for the human's side of it (a grilling agent that answers its own questions has broken this).
-
-- **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases to surface a fact a decision waits on. Resolved by a `/yss-research` **subagent** (`/research` is a deprecated alias). Use when knowledge outside the current working directory is required.
-- **Prototype** (HITL): Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code via the /prototype skill. Links the prototype as an asset. Use when "how should it look" or "how should it behave" is the key question.
-- **Grilling** (HITL): Conversation. The default case. Always invoke the /grilling and /domain-modeling skills.
-- **Task** (HITL or AFK): Manual work that must happen before a _decision_ can be made — nothing to decide, prototype, or research, but the discussion is blocked until it's done. Signing up for a service so its API can be judged, provisioning access, moving data so its shape can be seen. This is the one type that _does_ rather than decides — and it earns its place by unblocking a decision, not by delivering the destination. The agent drives it alone where it can (AFK); otherwise it hands the human a precise checklist (HITL). Resolved when the work is done; the answer records what was done and any resulting facts (credentials location, new URLs, row counts) later tickets depend on.
-
-## Fog of war
-
-The map is _deliberately_ incomplete: don't chart what you can't yet see. Beyond the live tickets lies the **fog of war** — the dim view of decisions and investigations you can tell are coming but can't yet pin down, because they hang on questions still open. Resolving a ticket clears the fog ahead of it, graduating whatever's now specifiable into fresh tickets — one at a time, until the way to the destination is clear and no tickets remain.
-
-The map's **Not yet specified** section is where that dim view is written down: the suspected question, the area to revisit later. It's the undiscovered frontier _toward_ the destination — everything here is in scope, just not sharp enough to ticket. Write as loosely or as fully as the view allows; it doubles as a signpost for collaborators reading where the effort is headed.
-
-**Fog or ticket?** The test is whether you can state the question precisely now — _not_ whether you can answer it now.
+选择或处理 Ticket 类型时，读取 [类型与参与方式](references/ticket-types.md)。Research 为 AFK；Prototype / Grilling 为 HITL，真实用户回复不能由 Agent 代答；Task 只为解除决定阻塞。
 
-- **Ticket when** the question is already sharp — even if it's blocked and you can't act on it yet.
-- **Not yet specified when** you can't yet phrase it that sharply. Don't pre-slice the fog into ticket-sized pieces: it's coarser than a ticket, and one patch may graduate into several tickets, or none, once the frontier reaches it.
+## Scope and frontier
 
-**Not yet specified** excludes what's already decided (Decisions so far), what's already a live ticket, and what's out of scope (the next section).
-
-## Out of scope
-
-Fog only ever gathers _toward_ the destination. The destination fixes the scope, so work beyond it is **out of scope** — it isn't fog, and it doesn't belong in **Not yet specified**. It gets its own **Out of scope** section on the map: work you've consciously ruled out of _this_ effort. Scope, not sharpness, lands it here.
-
-Out-of-scope work never graduates — the frontier stops at the destination — so it returns only if the destination is redrawn, and then as a fresh effort, not a resumption.
-
-Ruling something out of scope is a scoping act, not a step on the route. When a ticket that already exists turns out to sit past the destination — mis-scoped in while charting, or exposed by a resolution — **close it** (a closed ticket is unambiguously off the frontier) and leave one line in the **Out of scope** section: the gist plus why it's out of scope, linking the closed ticket. It stays out of **Decisions so far**, which records the route actually walked — a scope boundary isn't a step on it.
+划分未知范围、生成新 Ticket 或剔除越界工作时，读取 [范围与决策前沿](references/scope-and-frontier.md)。能明确提问的工作可成票；范围外工作不作为待细化事项。
 
 ## Invocation
 
@@ -108,23 +44,8 @@ Two modes. Keep each decision traceable and stop at a real dependency, decision
 
 ### Chart the map
 
-User invokes with a loose idea.
-
-1. **Name the destination.** Run a `/grilling` and `/domain-modeling` session to pin down what this map is finding its way to — the spec, decision, or change. The destination fixes the scope, so it's settled first.
-2. **Map the frontier.** Grill again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. **If this surfaces no fog** — the way to the destination is already clear, the whole journey small enough for one session — you don't need a map. Stop and ask the user how they'd like to proceed.
-3. **Create the map** (label `wayfinder:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into **Not yet specified**.
-4. **Create the tickets you can specify now** as child issues of the map — then wire blocking edges in a **second pass** (issues need ids before they can reference each other). Wiring sorts them into the frontier and the blocked; everything you can't yet specify stays in the fog — the **Not yet specified** section.
-5. **Fire the research subagents.** For each `research` ticket you just created, spin up a `/yss-research` subagent to resolve it in parallel, capturing its findings on a throwaway `research/<name>` branch with a context pointer from the ticket. `/research` remains only as a deprecated compatibility alias.
-6. Stop — charting is one session's work; it hand-resolves nothing.
+用户给出模糊想法、尚无地图时，读取 [建立地图](references/chart-map.md)。先确认目标和范围，再创建可明确提问的 Ticket；建立地图不代替执行。
 
 ### Work through the map
 
-User invokes with a map (URL or number). A ticket is **optional** — without one, you pick the next decision, not the user.
-
-1. Load the **map** — the low-res view, not every ticket body.
-2. Choose the ticket. If the user named one, use it. Otherwise take the first frontier ticket in order. **Claim it**: assign it to yourself before any work.
-3. Resolve it — **zoom as needed**: fetch the full body of any related or closed ticket on demand; invoke the skills the `## Notes` block names. If in doubt, use `/grilling` and `/domain-modeling`.
-4. Record the resolution: post the answer as a **resolution comment**, **close** the issue, and **append a context pointer** to the map's Decisions-so-far.
-5. Add newly-surfaced tickets (create-then-wire); graduate any fog the answer has made specifiable, clearing each graduated patch from **Not yet specified** so it lives only as its new ticket. If the answer reveals a ticket — this one or another — sits beyond the destination, **rule it out of scope** rather than resolving it on the route. If the decision invalidates other parts of the map, update or delete those tickets.
-
-The user may run unblocked tickets in parallel, so expect other sessions to be editing the tracker concurrently.
+用户给出已有地图时，读取 [推进地图](references/work-map.md)。先加载地图再认领一个未阻塞的决定，相关 Ticket 详情按需读取；完成后记录决定并更新前沿。