@llman-sdd/core 0.1.0 → 0.1.1

package/templates/zh-Hans/skills/llman-sdd-continue.md

@@ -0,0 +1,41 @@
+---
+name: "llman-sdd-continue"
+description: "继续已有 llman SDD 变更，创建下一个缺失工件。"
+metadata:
+  version: "{{ llman_version }}"
+---
+
+# LLMAN SDD Continue
+
+使用此 skill 继续已有变更，创建下一个缺失的 artifact。
+
+## 步骤
+1. 确定 change id：
+   - 若用户已提供，直接使用。
+   - 否则运行 `llman sdd list --json` 并询问要继续哪个 change。
+   - 始终说明："使用变更：<id>"。
+2. 阅读变更目录：`llmanspec/changes/<id>/`。
+> 阶段判定：用 `llman sdd show <id> --json --type change` 的 `stage` / `readyToImplement` 字段；完整判定表见 llman-sdd-apply。
+3. 确定下一个要创建的 artifact（按顺序）：
+   1) `proposal.md`
+   2) `design.md`（仅当涉及设计权衡时）
+   3) `tasks.md`
+   4) `llman sdd change start <id>`（或分支已存在时用 `change attach <id>`）——Branch binding
+   5) 在**绑定分支**上编辑 live `llmanspec/specs/<capability>.feature`（扁平，或目录主文件）并 commit——Specs landing（无合约变更可设 `needs_specs_change: false`）
+4. 只创建**一个**缺失 artifact（或在绑定分支上做一次 live spec/feature 编辑）。
+   - continue 模式**不要**实现应用代码。
+   - **不要**创建 `*.feature.delta.toon` 或 `changes/<id>/specs/` 下的文件。
+   - **不要**在未 start/attach 前改公共 `llmanspec/specs/**`。
+5. 若所有 artifact 已齐全，按 `llman sdd show <id> --json` 建议下一步：
+   - `readyToImplement=false` → 先完成 Specs landing（或 `needs_specs_change: false`）；**不要**建议 apply
+   - `readyToImplement=true` → 实施：`llman-sdd-apply`
+   - verify 之后 → 归档：`llman-sdd-archive`
+   - 校验：`llman sdd validate <id> --strict --no-interactive`
+   - 审查：`llman sdd change diff <id>`（只读）
+
+{{ unit("skills/git-native-flow") }}
+> 命令细节用 `llman sdd <cmd> --help` 查看；命令参考以 CLI 为准，skill 不内嵌命令表。
+> 文中「规约」= 本项目 `llmanspec/specs/` 下的 `.feature` 文件；用 `llman sdd list --specs` / `llman sdd show <capability>` 查全文。
+{{ unit("skills/validation-hints") }}
+
+{{ unit("skills/structured-protocol") }}

package/templates/zh-Hans/skills/llman-sdd-draft.md

@@ -0,0 +1,64 @@
+---
+name: "llman-sdd-draft"
+description: "快速把一个 change 想法记成草案提案（仅 proposal.md，经 `change new --from`）。不强制 tasks/design/specs/attach。用于随手记 idea 或未来需求；准备好后用 propose 正式化。"
+metadata:
+  version: "{{ llman_version }}"
+---
+
+# LLMAN SDD 草案（Draft）
+
+把一个 change 想法记成**草案提案**（仅 `proposal.md` skeleton）。这是「先把 idea / 未来需求记下来」的轻量入口——不做 triage、不写 tasks、不编辑 live specs、不 attach。等想法准备好落实时，用 `llman-sdd-propose` 正式化。
+
+## Pipeline 位置
+
+```mermaid
+flowchart LR
+    draft["★ llman-sdd-draft ★<br/>草案（你现在在这里）"] -.->|"正式化"| propose["llman-sdd-propose<br/>提案"]
+    propose --> apply["llman-sdd-apply<br/>实施"]
+    apply --> verify["llman-sdd-verify<br/>验证"]
+    verify --> archive["llman-sdd-archive<br/>归档"]
+
+    style draft fill:#fff3cd,stroke:#ffc107,stroke-width:3px
+```
+
+> 📍 你现在在草案阶段 → 下一步：完善 `proposal.md`，然后运行 `llman-sdd-propose` 正式化
+> 📎 本技能创建**草案** change（仅 proposal.md）。完整提案走 Git-native：tasks → Branch binding → Specs landing（见 propose 的生命周期图）
+> 🗺️ Skill 导航 ≠ Git-native 生命周期；Branch binding / Specs landing 不是独立 skill
+
+## 硬约束
+
+- **MUST NOT 询问用户 change id**：由 `change new --from` 从描述推导并告知用户。
+- **MUST NOT 创建 tasks/design/specs/attach**：本技能仅创建 `proposal.md` 草案壳。完整规划工件属于 `llman-sdd-propose`。
+- **MUST NOT 做 triage 或判断变更规模**：那是 propose 的职责。若用户想开始实现，建议 `llman-sdd-propose`。
+- **适用边界**：若描述明显涉及 MUST/SHALL 行为合约变更或多文件改动，建议用 `llman-sdd-propose` 而非停在草案——但仍先建草案壳以免想法丢失。
+- **frontmatter 有固定 schema**：充实 `proposal.md` 时只接受 `llmanspec/AGENTS.md`「Change Proposal Frontmatter SSOT」中的合法字段（含 `depends_on`、`blocks`、`branch`、`base_sha`、`needs_specs_change`）。`status`/`title`/`priority`/`author` 等会被 `llman sdd validate` 报 ERROR 拒绝。生命周期阶段是推断量——用 `llman sdd show`/`list` 查看，绝不写进 frontmatter。正文 MUST NOT 复读 frontmatter 字段（不要 `## Status` 段）；正文 H1 用人类可读标题，不要复读 change id。
+
+## 步骤
+
+### 0) Preflight
+- 读取 `llmanspec/config.yaml` 了解项目上下文、规则、locale。
+- 必须存在 `llmanspec/`；若不存在，提示先运行 `llman sdd init`，然后 STOP。
+
+### 1) 捕获描述
+- 直接采用用户的描述（如「draft: 加一个导出 json 的命令」「记一下: sdd change 应该支持 worktree」）。
+- **MUST NOT 询问 change id。** 由描述推导。
+
+### 2) 创建草案壳
+```bash
+llman sdd change new --from "<用户描述>"
+```
+- CLI 会生成合法的 kebab-case id（清洗 + 校验），在 `llmanspec/changes/<生成的 id>/` 下创建 `proposal.md`（含 `## Why` / `## What Changes` TODO 段的 skeleton），并打印最终 id 与路径。
+- 若生成的 id 与既有 change 冲突，CLI 以非零退出码失败；建议改写描述或用 `--force` 覆盖（对草案很罕见）。
+
+### 3) 告知并交接
+- **MUST 告知用户已生成的 id**（例如「已创建草案 change `<id>`，路径 `llmanspec/changes/<id>/proposal.md`」）。
+- 建议下一步：
+  - 现在或稍后完善 `proposal.md`（Why / What Changes / Capabilities / Impact）。
+  - 准备好落实时，运行 `llman-sdd-propose` 正式化（triage + tasks → `change start`/`attach` → Specs landing）。
+
+> 💡 草案已记 → 下一步：编辑 `proposal.md`，然后 `llman-sdd-propose` 正式化。
+
+> 命令细节用 `llman sdd <cmd> --help` 查看；命令参考以 CLI 为准，skill 不内嵌命令表。
+> 文中「规约」= 本项目 `llmanspec/specs/` 下的 `.feature` 文件；用 `llman sdd list --specs` / `llman sdd show <capability>` 查全文。
+
+{{ unit("skills/ethics-governance") }}

package/templates/zh-Hans/skills/llman-sdd-explore.md

@@ -0,0 +1,78 @@
+---
+name: "llman-sdd-explore"
+description: "进入 llman SDD 探索模式：理清思路、调查需求、分析问题。仅思考，禁止写代码。用于意图不明确或需要分析后再行动的场景。"
+metadata:
+  version: "{{ llman_version }}"
+---
+
+# LLMAN SDD Explore
+
+当用户希望在开始实现之前先理清思路、调查问题或澄清需求时，使用此 skill。
+
+**重要：探索模式只用于思考，不用于实现。**
+- 你可以阅读文件、搜索代码、调查代码库。
+- 你可以创建/更新规划壳工件（proposal/design/tasks）。
+- live specs：**只读**，除非 change 已 Branch-bound 且你在该分支上；否则 STOP 并建议 `llman-sdd-propose` / `change start`。
+- 你绝对不能在探索模式下写应用代码或实现功能。
+
+## Pipeline 位置
+
+{{ unit("skills/git-native-flow-brief") }}
+
+### Skill 导航（非生命周期；仅指示当前 skill）
+
+```mermaid
+flowchart LR
+    explore["★ llman-sdd-explore ★<br/>探索（你现在在这里）"]
+    explore --> propose["llman-sdd-propose<br/>提案（含 Branch binding 与 Specs landing）"]
+    propose --> apply["llman-sdd-apply<br/>实施"]
+    apply --> verify["llman-sdd-verify<br/>验证"]
+    verify --> archive["llman-sdd-archive<br/>归档"]
+
+    style explore fill:#fff3cd,stroke:#ffc107,stroke-width:3px
+```
+
+> 📍 你现在在探索阶段（仅思考）→ 常规路径下一步 `llman-sdd-propose`（提案）
+> 📎 如果是小改动（不改行为合约），可直接走 `llman-sdd-quick`（快速路径）
+> 🗺️ Skill 导航 ≠ Git-native 生命周期
+
+## 探索姿态
+- 好奇而不教条
+- 以真实代码为依据
+- 需要时用 ASCII 图可视化
+- 同时保留多个选项与权衡
+
+## 建议动作
+1. 使用 `llman sdd context --task "<任务>" --paths "<文件>"` 快速定位相关 specs。
+   - 阅读 context 的 `direct` 列出的 spec 全文（这些是必须理解的合约）。
+   - 如果 context 不可用，运行 `llman sdd index rebuild`（默认 `pageindex`，无需模型）后重试。
+2. 澄清目标与约束（问 1–3 个问题）。
+3. **逐问深挖分支（可选，仅当用户显式触发时进入）**：触发词为「深挖」「grill」「逐个问」「彻底理清」。进入后一问一答走清决策：
+   - **一次只问一个问题**，并附你的推荐答案，等用户反馈后再继续下一个。
+   - **事实 vs 决策分离**：能通过读 capability `.feature`/代码/运行命令查证的事实，自行查证，**不问**用户；只有**决策**（取舍、偏好、范围边界）才交给用户。
+   - **术语校准**：遇到术语冲突或模糊词时立即指出（「你的 spec 定义 'X' 为 A，但你刚说成 B——哪个对？」）；解决后：若 change 已 Branch binding 且在绑定分支上，可更新 live `.feature`（Specs landing）；否则只记入 `proposal.md`，**禁止**在默认分支改 live specs。MUST NOT 另建 `CONTEXT.md` 词表作为第二权威。
+   - **决策回写**：已解决的决策回写到该 change 的 `proposal.md`「Open Questions」段（规划壳；可短暂在默认分支）。
+   - **完成判据**：每个待定决策都已解决或被显式推迟。未触发时保持默认（问 1–3 个问题）行为不变。
+4. 如果某个 change id 相关，阅读 `llmanspec/changes/<id>/` 下的 artifacts。
+   - 诊断校验错误时优先跑 `llman sdd validate <spec> --strict --no-check`（fast mode，跳过可能耗时的 `bdd.run_command`），先解决结构门禁（Gherkin / `@req` 链接 / 双写 / req_id 唯一性），再跑 full mode（`--check` 或 `cargo test --features bdd`）。错误输出中的 `FAIL <item_type>/<id>` 行会逐条指明失败项。
+5. 探索 2–3 个选项与权衡。
+6. 判断变更规模（triage），确定是否需要走完整 SDD 流程。
+7. 当结论逐渐清晰时，建议用户把它记录下来（不要自动写入）：
+   - 范围变化 / 设计决策 / 工作项 → 规划壳（`proposal.md` / `design.md` / `tasks.md`）
+   - 约束 / 可执行 harness → **仅建议**写入 live `llmanspec/specs/**`（每 capability 一个 `.feature`）；实际编辑须先 Branch binding，再 Specs landing。探索模式未 binding 时只记到 proposal，勿直接改 live specs。
+
+> Git-native：先 `change start`/`attach`（Branch binding）进入 Full，再在绑定分支编辑 live `.feature`（Specs landing）；无 `change delta` / solidify / feature_delta。
+
+## 退出探索模式
+当用户准备开始实现时，根据变更规模选择路径：
+- 行为合约变更 → `llman-sdd-propose`（创建提案工件）
+- 小改动 / 不改合约 → `llman-sdd-quick`（快速路径）
+- `readyToImplement=true` → `llman-sdd-apply`（按 tasks 实施）
+若用户在探索模式中要求你开始实现，STOP 并提醒其先退出探索模式。
+
+> 💡 探索完成 → 下一步 `llman-sdd-propose`（提案）或 `llman-sdd-quick`（快速路径）
+
+> 命令细节用 `llman sdd <cmd> --help` 查看；命令参考以 CLI 为准，skill 不内嵌命令表。
+> 文中「规约」= 本项目 `llmanspec/specs/` 下的 `.feature` 文件；用 `llman sdd list --specs` / `llman sdd show <capability>` 查全文。
+
+{{ unit("skills/structured-protocol") }}

package/templates/zh-Hans/skills/llman-sdd-ff.md

@@ -0,0 +1,38 @@
+---
+name: "llman-sdd-ff"
+description: "Fast-forward：一次性创建规划壳（proposal/design/tasks），再 Branch binding + Specs landing。禁止写入 changes/<id>/specs/。"
+metadata:
+  version: "{{ llman_version }}"
+---
+
+# LLMAN SDD Fast-Forward (FF)
+
+快速走完 propose 等价路径：规划壳 → Branch binding → Specs landing（至 `readyToImplement=true`）。**不是**旧的 `changes/<id>/specs/` delta 模型。
+
+## 硬约束
+
+- **规划壳**只写在 `llmanspec/changes/<id>/`（proposal/design/tasks）。
+- Live 合约只写在绑定分支的 `llmanspec/specs/**`（Specs landing）。
+- **禁止**创建 `llmanspec/changes/<id>/specs/` 或 `*.feature.delta.toon`。
+- 进入 apply 前须 `readyToImplement=true`。
+
+## 步骤
+
+1. 询问用户：一句话描述、change id（或派生）、受影响 capability、确认最终 id。
+2. 确保已 `llman sdd init`（存在 `llmanspec/`）。
+3. 若 `llmanspec/changes/<id>/` 已存在：询问补齐或换 id；勿未确认就覆盖。
+4. 创建**规划壳**（可短暂在默认分支）：
+   - `llman sdd change new <id>`（或手写）→ 充实 `proposal.md`
+   - `design.md`（按需）
+   - `tasks.md`
+5. **Branch binding**：`llman sdd change start <id>`（干净树 + 默认分支）或手动建分支后 `change attach <id>`。
+6. **Specs landing**：在绑定分支编辑 live `llmanspec/specs/<capability>.feature`（扁平，或目录主文件）并 commit；无合约变更则 `needs_specs_change: false`。
+7. 校验：`llman sdd validate <id> --strict --no-interactive`。
+8. 用 `llman sdd show <id> --json` 确认 `readyToImplement=true` 后，建议 `llman-sdd-apply`（不要在未就绪时建议 apply）。
+
+{{ unit("skills/git-native-flow-brief") }}
+> 命令细节用 `llman sdd <cmd> --help` 查看；命令参考以 CLI 为准，skill 不内嵌命令表。
+> 文中「规约」= 本项目 `llmanspec/specs/` 下的 `.feature` 文件；用 `llman sdd list --specs` / `llman sdd show <capability>` 查全文。
+{{ unit("skills/validation-hints") }}
+
+{{ unit("skills/ethics-governance") }}

package/templates/zh-Hans/skills/llman-sdd-graph.md

@@ -0,0 +1,74 @@
+---
+name: "llman-sdd-graph"
+description: "以 mermaid 图可视化 llman SDD 变更间的依赖关系（depends_on/blocks）。辅助工具，任意阶段可用，不属于主实现 pipeline。"
+metadata:
+  version: "{{ llman_version }}"
+---
+
+# LLMAN SDD 依赖图
+
+使用此 skill 可视化变更之间的依赖关系。
+
+## Pipeline 位置
+
+```mermaid
+flowchart LR
+    pipeline["主 pipeline:<br/>propose → apply → verify → archive"]
+    graph["📎 llman-sdd-graph<br/>依赖可视化（辅助工具）"]
+    graph -.->|任意阶段可用| pipeline
+
+    style graph fill:#e8f4e8,stroke:#28a745,stroke-width:2px
+```
+
+> 📎 辅助工具，可在 pipeline 任意阶段使用。需要提案 → `llman-sdd-propose`；需要实施 → 仅当 `readyToImplement=true` 时用 `llman-sdd-apply`。
+
+## 用法
+
+**聚焦视图（seed 模式）：** 展示指定变更及其关系邻域。
+
+```bash
+llman sdd graph <change-id>              # 该变更 + 直接关系（depth 1）
+llman sdd graph <change-id> --depth 3    # 递归 3 层
+llman sdd graph <change-id> --depth 0    # 仅该变更自身
+```
+
+seed 模式沿 upstream（depends_on）、downstream（被谁依赖）、blocks 三个方向遍历，自动发现活跃和已归档变更。
+
+**全局视图（scope 模式）：** 按范围展示所有变更。
+
+```bash
+llman sdd graph                          # 所有活跃变更（默认）
+llman sdd graph --scope archived         # 所有已归档（已完成）变更
+llman sdd graph --scope all              # 全部
+```
+
+## 输出
+
+- 输出为 mermaid flowchart 到标准输出，可管道到文件或渲染器：
+  ```
+  llman sdd graph c50 > deps.mmd
+  llman sdd graph c50 --depth 2 | mmdc -i - -o deps.png
+  ```
+- 已归档（已完成）变更以 "✓ done" 后缀和绿色高亮显示。
+- 当图中存在互不相连的分组时，每组渲染为独立的 subgraph，标注 "Active"、"Done" 或 "Mixed"。
+
+## 提案 frontmatter 格式
+
+```yaml
+---
+depends_on:
+  - other-change-id
+blocks:
+  - blocked-change-id
+---
+
+## Why
+...
+```
+
+> 💡 这只是辅助工具 — 主流程：`llman-sdd-propose`（含 Branch binding + Specs landing）→ `llman-sdd-apply`（须 `readyToImplement`）→ `llman-sdd-verify` → `llman-sdd-archive`。
+
+> 命令细节用 `llman sdd <cmd> --help` 查看；命令参考以 CLI 为准，skill 不内嵌命令表。
+> 文中「规约」= 本项目 `llmanspec/specs/` 下的 `.feature` 文件；用 `llman sdd list --specs` / `llman sdd show <capability>` 查全文。
+
+{{ unit("skills/ethics-governance") }}

package/templates/zh-Hans/skills/llman-sdd-onboard.md

@@ -0,0 +1,34 @@
+---
+name: "llman-sdd-onboard"
+description: "了解 llman SDD 工作流并完成项目入门。"
+metadata:
+  version: "{{ llman_version }}"
+---
+
+# LLMAN SDD 入门
+
+使用此 skill 让你快速了解 llman SDD 工作流。
+
+## 步骤
+1. 阅读 `llmanspec/config.yaml` 了解项目上下文、约定与规则。
+2. 使用 `llman sdd list --specs --json` 了解项目中的 specs 概览。
+   - 或者使用 `llman sdd context --task "<任务描述>" --paths "<路径>"` 获取与当前任务相关的 specs。
+   - 如果 context 返回 `quality: "unavailable"`，先运行 `llman sdd index rebuild` 重建索引（默认 backend 为 `pageindex`；检索需 `LLMAN_SDD_INDEX_CHAT_MODEL`，但重建不需要）。
+3. 根据 context 的 `direct`/`related` 分类，只读 target spec 全文。
+4. 判断变更规模（见 triage 规则），决定走完整 SDD 流程或快速路径。
+5. 按路径推进：
+   - **完整路径**：规划壳（draft → designed [+design.md] → planned [+tasks.md]）→ Branch binding → Specs landing（或 `needs_specs_change: false`）→ `readyToImplement=true` → apply → verify → finalize/archive（Skill 导航：propose → apply → verify → archive）。
+   - **快速路径**：不改 MUST/SHALL，直接改代码 commit（触及 live specs 须已绑定分支，见 `llman-sdd-quick`）。
+6. 使用 `llman sdd graph` 可视化变更依赖关系（depends_on/blocks）。
+
+> 命令细节用 `llman sdd <cmd> --help` 查看；命令参考以 CLI 为准，skill 不内嵌命令表。
+> 文中「规约」= 本项目 `llmanspec/specs/` 下的 `.feature` 文件；用 `llman sdd list --specs` / `llman sdd show <capability>` 查全文。
+
+## 备注
+- `llmanspec/config.yaml` 包含项目上下文、规则、locale 与 skills 路径。
+- locale 仅影响模板与 skills，CLI 仍为英文。
+- 使用 `llman sdd init --update` 刷新技能。
+
+{{ unit("skills/validation-hints") }}
+
+{{ unit("skills/ethics-governance") }}

package/templates/zh-Hans/skills/llman-sdd-propose.md

@@ -0,0 +1,119 @@
+---
+name: "llman-sdd-propose"
+description: "创建带规划工件（proposal/tasks；先 `change start`/`attach` 完成 Branch binding，再在绑定分支编辑 live specs/feature）的 llman SDD 变更提案。用于 MUST/SHALL 行为合约变更。"
+metadata:
+  version: "{{ llman_version }}"
+---
+
+# LLMAN SDD Propose
+
+创建一个带规划工件的新 change（proposal + tasks；design 可选），**先** `change start`（或 `attach`）完成 Branch binding，**然后**在绑定分支上编辑 live `llmanspec/specs/<capability>.feature`（扁平，或目录主文件）（Specs landing）、校验，并建议下一步。
+
+## Pipeline 位置
+
+{{ unit("skills/git-native-flow") }}
+{{ unit("skills/human-readable-summary") }}
+
+### Skill 导航（非生命周期；仅指示当前 skill）
+
+```mermaid
+flowchart LR
+    explore["llman-sdd-explore<br/>探索"] --> propose
+    propose["★ llman-sdd-propose ★<br/>提案（Branch binding + Specs landing）"]
+    propose --> apply["llman-sdd-apply<br/>实施"]
+    apply --> verify["llman-sdd-verify<br/>验证"]
+    verify --> archive["llman-sdd-archive<br/>归档"]
+
+    style propose fill:#fff3cd,stroke:#ffc107,stroke-width:3px
+```
+
+> 📍 你现在在 propose 阶段：上方 Git-native 路径为 **规划壳（draft → designed → planned）→ Branch binding → Specs landing**（直到 `readyToImplement=true`）→ 下一步：`llman-sdd-apply`
+> 📎 小改动（不改行为合约）请走 `llman-sdd-quick`（快速路径）
+
+## 硬约束
+
+- **change id 非阻塞**：用户已给出 id 则直接采用；否则从任务描述推导一个合法 kebab-case id（动词前缀开头，通过 CLI 的 id 合法性检查，并遵循 `llmanspec/AGENTS.md` 声明的命名约定），宣布所用 id 与覆盖方式后继续，MUST NOT 等待确认——Branch binding 前更换 id 成本很低。仅当用户想先记 idea（草案、无需 id）时转 `llman-sdd-draft`。
+- **Live specs 是 SSOT**：只在 Branch binding **之后**、在**绑定的非默认分支**上编辑 `llmanspec/specs/**`（Specs landing）。**不要**在默认分支上改 live specs；**不要**在 `changes/<id>/specs/` 下撰写或使用 `change delta`（已移除）。规划壳可以短暂留在默认分支。
+- **不要问「要不要继续」**：一口气执行完整 propose 阶段，生成工件并校验。
+{% if extra_skill_continue %}
+- **change 已存在**：STOP。若 `readyToImplement=true`，建议 `llman-sdd-apply`；否则用 `llman-sdd-continue` 补完 Branch binding / Specs landing 或规划壳。
+{% else %}
+- **change 已存在**：STOP。若 `readyToImplement=true`，建议 `llman-sdd-apply`；否则补完规划壳 / Branch binding / Specs landing（编辑 `llmanspec/changes/<id>/`，或在配置启用 `extra_skills: [llman-sdd-continue]`）。
+{% endif %}
+- **frontmatter 有固定 schema**：充实 `proposal.md` 时只接受 `llmanspec/AGENTS.md`「Change Proposal Frontmatter SSOT」中的合法字段（含 `depends_on`、`blocks`、`branch`、`base_sha`、`needs_specs_change`）。`status`/`title`/`priority`/`author` 等会被 `llman sdd validate` 报 ERROR 拒绝；生命周期阶段是推断量（用 `llman sdd show`/`list` 查询），绝不写进 frontmatter。正文 MUST NOT 复读 frontmatter 字段；正文 H1 是人类可读标题，不是 change id 的复读。
+
+## 快速记录分流
+
+若用户只是想**记一个 idea**（如「draft 一个提案」「记下 X」「之后要做 Y」）而不需要完整规划，转 `llman-sdd-draft` skill——它经 `change new --from` 创建仅含 `proposal.md` 的草案壳（不问 id、无 tasks/specs/attach）。完整 propose（triage + tasks → `change start`/`attach` → Specs landing）从这里开始。
+
+## 步骤
+
+### 0) 预检
+- 读 `llmanspec/config.yaml` 获取项目上下文、规则、locale。
+- `llman sdd validate --all --strict --no-interactive`：确认现有工件干净。
+  - 若已有错误，STOP 并报告（在脏工件上叠新 change 会造成级联错误）。
+- **检查 spec valid_scope 完整性**：用 `llman sdd list --specs --json` 列出全部 specs，逐个核对其 `valid_scope` 中的路径在磁盘上是否存在。任何 scope 文件/目录缺失时，STOP 并建议更新该 spec（从 `valid_scope` 移除已删除的路径）。
+
+### 1) 评估 change 规模（triage）
+1. 判定类型：
+   - **行为合约变更**（修改 MUST/SHALL、改变外部行为）→ 完整 SDD 工作流
+   - **实现层变更**（重构、typo、性能）→ 走 `llman-sdd-quick` 快速路径
+   - **元规范变更**（SDD 模板/流程）→ 完整 SDD 工作流
+   - 不确定时选完整 SDD（保守）。
+2. 用 `llman sdd context --task "<目标>" --paths "<范围>"` 找相关 specs。
+   - context 不可用时，跑 `llman sdd index rebuild`（默认 `pageindex`，无需模型）后继续。
+3. 收集输入：
+   - 一段简短的变更描述
+   - 一个 change id（用户给出则用之；否则按上面的非阻塞规则推导并宣布）
+   - 受影响的 capability（用于命名 `specs/<capability>`）
+
+### 2) 确认项目已初始化
+   - `llmanspec/` 必须存在；若缺失，让用户运行 `llman sdd init`，然后 STOP。
+
+### 3) 创建 change 目录与工件
+   - 优先用 `llman sdd change new <change-id>` 生成 `proposal.md` 草案壳（或手动创建 `llmanspec/changes/<change-id>/`）。
+{% if extra_skill_continue %}
+   - change 已存在时，STOP 并建议 `llman-sdd-continue`。
+{% else %}
+   - change 已存在时，STOP 并建议补齐缺失工件或 `llman-sdd-apply`（可通过 `extra_skills` 启用 continue）。
+{% endif %}
+   - 充实 `proposal.md`（Why / What Changes / Capabilities / Impact）
+   - 仅当存在权衡/迁移时写 `design.md`
+   - **写 tasks.md 前确认测试边界（seam，接缝）**：列出将要测试的 seam 并与用户确认。seam = 由 `*.feature` GWT 步骤驱动的公共边界（CLI 子进程或公共接口）——MUST 复用既有 harness seam，MUST NOT 脱离 `.feature` 凭空发明 seam。没有 `.feature` 时，seam = 被测的 CLI 子命令或公共函数边界。
+   - `tasks.md`：按**垂直切片**拆分（每个 task 打穿 schema→API→UI→tests 一条窄而完整的路径，可独立验证），并带 `[blocked-by: <task-id>]` 依赖标记。**大范围重构例外**（一个机械改动扫全库、单点编辑牵动大量调用处）：按 expand-contract 排序（旧的旁边加新的 → 分批迁移调用处 → 删掉旧的），不强拆垂直切片。
+   - **先** `llman sdd change start <change-id>`（推荐；默认分支上工作树干净时）或手动建分支后 `change attach <change-id>` 到达 Full（bound）。
+   - **然后**在绑定的非默认分支上编辑 live `llmanspec/specs/<capability>.feature`（扁平，或目录 `llmanspec/specs/<capability>/` 内主文件）并 commit（Specs landing）。**不要**在 start 之前改 live specs；**不要**为过干净树门禁把 live specs commit 到默认分支。已 attach 时勿重复 `start`（丢失 specs 时用 checkout/重建 + `attach --force` 恢复）。
+   - 无 live 合约编辑的 change，设置 frontmatter `needs_specs_change: false`。仅当 `llman sdd show <id> --json` 给出 `readyToImplement=true` 才进入 apply。
+   - **破坏性合约变更**（移除/重命名字段、命令、tag 或 stage 值域）MUST 规划升级路径：`migrations/v<from>-v<to>/`（README prompt + 一次性脚本，随仓库发布）——写进提案的 What Changes。
+
+### 4) 校验
+   ```bash
+   llman sdd validate <change-id> --strict --no-interactive
+   ```
+   这一步 MUST 通过后才能继续。若出现 TOON 解析错误，修复引号：表格式行中含逗号/冒号/括号的值必须加双引号。
+
+### 4a) 可选 BDD runner（`bdd:` 段）
+- 读 `llmanspec/config.yaml`。是否含 `bdd:` 段？
+  - **有**：`validate --check` 会跑 harness；撰写仍按 4b 执行。
+  - **无**：若本次 change 涉及可执行行为场景（用户会想运行的 Given/When/Then），**一次性、前置**询问：「本次变更看起来有可执行行为。要启用 `bdd:` runner 段以便把场景作为 `.feature` 校验吗？（会向 `config.yaml` 加一个 `bdd:` 段——仅 runner，不改变生命周期。）」
+    - **是**：展示要添加的精确 `bdd:` 段（`run_command` 选匹配项目测试框架的——rstest-bdd 用 `cargo test --features bdd`，pytest-bdd 用 `pytest {feature_dir} -k {feature_name} -v`）。让用户确认或修改后写入 `config.yaml`，再按 4b 规则继续。
+    - **否**：feature 仍做结构校验；仅跳过 runner 执行。
+- **MUST NOT 静默添加 `bdd:` 段**——总是先询问。添加它会改变全项目 `validate --check` 的行为。
+
+### 4b) 单轨 feature 撰写
+- 规划壳（proposal/design/tasks）可短暂留在默认分支；**不要**在默认分支上编辑 live `llmanspec/specs/**`。Branch binding 之后，Specs landing 与实现都发生在绑定分支上。
+- **单轨**：每个 capability 只有一个 `<capability>.feature`。约束规则是 `@req:<id> @human` 场景（statement 全文放描述）；可执行验收场景带 `@executable` 并用 `@req:<req_id>` 挂回规则。绝不把场景嵌进 `Rule:` 块（runner 会静默跳过其中场景）。
+- change 壳：`llman sdd change new <change-id>` → 填 proposal/design/tasks → `llman sdd change start <change-id>`（或 `change attach`）→ **然后**在绑定分支编辑 live specs 并 commit（Specs landing）。
+- **不要**使用 `change delta` / solidify / `*.feature.delta.toon`；存在活跃 `*.feature.delta.toon` 或遗留 `spec.toon` 时，先跑 `llman sdd project migrate --kind toon2features`。
+
+### 5) 总结并建议下一步
+   - 进入实现阶段：`llman-sdd-apply`。
+   - 需要再想清楚：`llman-sdd-explore`。
+
+> 💡 提案完成 → 下一步：`llman-sdd-apply`（实施）
+
+> 命令细节用 `llman sdd <cmd> --help` 查看；命令参考以 CLI 为准，skill 不内嵌命令表。
+> 文中「规约」= 本项目 `llmanspec/specs/` 下的 `.feature` 文件；用 `llman sdd list --specs` / `llman sdd show <capability>` 查全文。
+{{ unit("skills/validation-hints") }}
+
+{{ unit("skills/structured-protocol") }}

package/templates/zh-Hans/skills/llman-sdd-quick.md

@@ -0,0 +1,56 @@
+---
+name: "llman-sdd-quick"
+description: "快速路径：处理不改行为合约的小改动——重构、修错字、性能优化。不涉及 MUST/SHALL 变更。如发现需要改合约，立即切换到 propose 完整路径。"
+metadata:
+  version: "{{ llman_version }}"
+---
+
+# LLMAN SDD Quick Path
+
+对于不涉及行为合约变更的小改动使用此路径。
+
+## Pipeline 位置
+
+```mermaid
+flowchart LR
+    explore["llman-sdd-explore<br/>探索"] --> quick
+
+    quick["★ llman-sdd-quick ★<br/>快速路径（你现在在这里）"]
+    quick --> commit["git commit<br/>完成"]
+
+    explore --> propose["完整路径:<br/>propose（含 Branch binding 与 Specs landing）→ apply → verify → archive"]
+    propose --> apply["..."]
+    apply --> verify["..."]
+    verify --> archive["..."]
+
+    style quick fill:#d4edda,stroke:#28a745,stroke-width:3px
+```
+
+> 📍 快速路径：不改行为合约，直接改代码 commit。如果发现需要改合约 → STOP，改走完整路径 `llman-sdd-propose`
+> 🗺️ 完整路径含 Git-native Branch binding + Specs landing（不是把 Specs landing 当成独立 skill）
+
+## 使用条件（所有条件必须满足）
+- 不改变任何 spec 中 MUST/SHALL 定义的外部可观测行为
+- 不涉及跨 capability 的修改
+- 不涉及迁移/兼容性
+- 不是 SDD 元规范变更
+
+## 步骤
+1. 用 `llman sdd context --task "..." --paths "..."` 确认无相关 spec 变更需要。
+   - 如果 context 返回 `quality: "unavailable"`，运行 `llman sdd index rebuild`（默认 `pageindex`，无需模型）。
+   - 可以用 `llman sdd list --specs --json` 查看 specs 元数据。
+2. 直接修改代码。
+3. 若要动 `llmanspec/specs/**`，STOP——除非已在绑定的非默认 change 分支上（迷你 change：`change start`/`attach` → 编辑 → commit）。禁止在默认分支 commit live specs，即使是 typo 或仅收紧 scope 也不行。优先把 live specs 维护路由到 `llman-sdd-propose`，或要求已有绑定分支。
+4. git commit（message 写明 why）。
+5. 无需 change 目录，无需 archive。
+
+## 边界处理
+- 如果在修改中发现需要改变行为合约 → STOP，改走 `llman-sdd-propose`（完整路径）。
+- 如果涉及到多个文件且不确定 scope → 先用 `llman sdd context` 确认。
+
+> 💡 快速路径完成 → git commit 即可。若需要走完整路径 → `llman-sdd-propose` → `llman-sdd-apply` → `llman-sdd-verify` → `llman-sdd-archive`
+
+> 命令细节用 `llman sdd <cmd> --help` 查看；命令参考以 CLI 为准，skill 不内嵌命令表。
+> 文中「规约」= 本项目 `llmanspec/specs/` 下的 `.feature` 文件；用 `llman sdd list --specs` / `llman sdd show <capability>` 查全文。
+
+{{ unit("skills/ethics-governance") }}

package/templates/zh-Hans/skills/llman-sdd-research.md

@@ -0,0 +1,46 @@
+---
+name: "llman-sdd-research"
+description: "以后台 agent 委托外部文献调研。当用户需要针对某个问题查阅官方文档/API/源码等一手资料、或想把阅读文献的活委托给后台 agent 时使用。"
+metadata:
+  version: "{{ llman_version }}"
+---
+
+# LLMAN SDD Research
+
+启动一个**后台 agent** 做文献调研，这样你可以继续手头工作而它在读。
+
+## Pipeline 位置
+
+辅助工具，任意阶段可用。常见于 explore/wayfinder 阶段，为决策提供事实输入。产出回写 change 的 proposal「Further Notes」段，供后续阶段引用。
+
+> 📍 这是独立可选 skill；调研产出供主流程的 explore/propose 消费。
+
+## 职责
+
+后台 agent 的工作：
+
+1. 针对**一手资料**调研问题——官方文档、源码、spec、第一方 API——而非对它们的二手转述。把每个论断追溯到拥有它的源头。
+2. 把发现写入单个 Markdown 文件，为每个论断标注来源引用。
+3. 存放位置（仓库另有约定时优先遵循）：**默认** `llmanspec/changes/<current-change>/research/<topic>.md`（Change 文档，**不是** live specs）。仅当主题跨多个 change、归档后仍常引用时才写 `docs/research/`；**禁止**把单 change 选型/易腐深挖塞进 `docs/research/`。
+4. **禁止**本 skill 直接编辑 `llmanspec/specs/**`。若调研表明必须改 MUST/SHALL → 建议 `llman-sdd-propose`（Branch binding → Specs landing）。
+
+## 步骤
+
+1. 明确要调研的问题（与用户确认；模糊时收窄到一个能被证实/证伪的问题）。
+2. 用 Agent 工具 `subagent_type=general-purpose` + `run_in_background: true` 启动后台调研，prompt 含：
+   - 问题陈述。
+   - 要求只引一手资料，每条论断标注来源 URL/路径。
+   - 输出文件路径（默认 `llmanspec/changes/<id>/research/<topic>.md`）。
+   - 字数上限（建议：聚焦事实，散文式叙述 < 1500 词）。
+3. 后台运行期间继续主流程工作；完成后收到通知。
+4. 读取产出，把关键结论摘要回写到当前 change 的 `proposal.md`「Further Notes」段（附文件指针）。
+5. 若调研揭示需要决策，建议进入 `llman-sdd-explore` 的逐问深挖分支。
+
+## 与 wayfinder 的协作
+
+`llman-sdd-wayfinder` 的查资料 ticket 委托本 skill 后台解决；解决后回写 ticket proposal 并在 map 的 Decisions-so-far 记一行要点。
+
+> 命令细节用 `llman sdd <cmd> --help` 查看；命令参考以 CLI 为准，skill 不内嵌命令表。
+> 文中「规约」= 本项目 `llmanspec/specs/` 下的 `.feature` 文件；用 `llman sdd list --specs` / `llman sdd show <capability>` 查全文。
+
+{{ unit("skills/structured-protocol") }}

package/templates/zh-Hans/skills/llman-sdd-show.md

@@ -0,0 +1,24 @@
+---
+name: "llman-sdd-show"
+description: "快速查看 llmanspec 变更与 specs。"
+metadata:
+  version: "{{ llman_version }}"
+---
+
+# LLMAN SDD 查看
+
+使用此 skill 快速查看变更与 specs。
+
+## 步骤
+1. 列出条目：`llman sdd list` 或 `llman sdd list --specs`。
+2. 如果 id 不明确，展示列表并让用户选择。
+3. 查看详情：`llman sdd show <id>`。
+4. 需要时使用 `--type change|spec` 消除歧义。
+5. 对 change 使用 `--json`：状态 SSOT 字段为 `stage` / `specsLanded` / `needsSpecsChange` / `readyToImplement`（勿凭「完整工件」口头判断可否 apply）。
+
+> 命令细节用 `llman sdd <cmd> --help` 查看；命令参考以 CLI 为准，skill 不内嵌命令表。
+> 文中「规约」= 本项目 `llmanspec/specs/` 下的 `.feature` 文件；用 `llman sdd list --specs` / `llman sdd show <capability>` 查全文。
+
+{{ unit("skills/validation-hints") }}
+
+{{ unit("skills/ethics-governance") }}