specline 2.0.2 → 2.0.3

package/core/bootstrap/using-specline.md

@@ -12,3 +12,11 @@ description: >-
 3. 1-3 文件小改 → specline-quickfix
 4. 思考探索 → specline-explore
 5. 读 specline/config.yaml 了解 human_gate_policy
+
+## Skill 语言风格
+
+1. Skill 面向 Agent/用户的说明采用中文主导；系统契约、CLI、配置字段、文件字段和固定术语保留英文原文。
+2. 标题骨架使用中文，如 `第 1 层：速览与定位`、`主流程`、`步骤 1：创建 Change`、`约束`、`验证清单`。
+3. 不使用 `Layer`、`Happy Path`、`Steps`、`Guardrails`、`Verification Checklist` 等说明性英文作为主标题。
+4. `Pipeline`、`Quickfix`、`Gate`、`Human Gate`、`Artifact`、`Spec`、`Change`、`Agent`、`Hook`、`Type`、`Depends`、`Covers`、`Files`、`WHEN`、`THEN`、CLI 命令、路径和配置键保持英文。
+5. 首次出现的核心术语可使用“中文说明（English Term）”，同一文件内保持一致。

package/core/skills/specline-apply-change/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: specline-apply-change
-description: Implement tasks from a Specline change. Use when the user wants to start implementing, continue implementation, or work through tasks.
+description: 实现 Specline change 中的任务。用于用户想开始实现、继续实现或逐项推进 tasks。
 license: MIT
 compatibility: Compatible with specline.
 metadata:
@@ -9,11 +9,11 @@ metadata:
   generatedBy: "1.3.1"
 ---
 
-Implement tasks from a Specline change.
+实现 Specline change 中的任务。
 
-**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+**输入**：可选传入 change name。若未传入，先判断能否从对话上下文推断；若模糊或有歧义，必须展示可用 change 让用户选择。
 
-## 速览 (Layer 1)
+## 第 1 层：速览
 
 > **一句话**：实现 Specline change 中的编码任务。
 > **入口**：`/specline-apply-change [change-name]` 或直接说「继续实现」
@@ -23,11 +23,11 @@ Implement tasks from a Specline change.
 > - change 选择 → 若上下文中已有 change name，直接使用；否则取第一个活跃 change
 > - 其他 {{CONFIRM}} 交互 → 自动采用默认安全选项继续，不暂停等待人工输入
 
-**Fluid Workflow Integration**
+**流动式工作流集成**
 
-This skill supports the "actions on a change" model:
-- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
-- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
+本 Skill 支持围绕单个 change 持续执行 action 的模型：
+- **可随时调用**：Artifact 尚未全部完成但已有 tasks 时、部分实现后、或与其他 action 交错时都可调用
+- **允许更新 Artifact**：如果实现暴露设计问题，建议更新 Artifact；不被阶段锁死，按实际情况流动推进
 
 **开始前请确认：**
 - [ ] Change 已选中（`/specline-pipeline --change <name>`）
@@ -36,71 +36,71 @@ This skill supports the "actions on a change" model:
 - [ ] 已读取 design.md（知道技术决策）
 - [ ] 已读取 tasks.md（知道实现清单）
 
-## 详细步骤 — Happy Path (Layer 2)
+## 第 2 层：主流程
 
-**Steps**
+**步骤**
 
-1. **Select the change**
+1. **选择 change**
 
-   If a name is provided, use it. Otherwise:
-   - Infer from conversation context if the user mentioned a change
-   - Auto-select if only one active change exists
-   - If ambiguous, run `specline gate list --json` to get available changes and use {{CONFIRM}} to let the user select
+   如果提供了 name，直接使用。否则：
+   - 如果用户在对话中提到 change，则从上下文推断
+   - 如果只有一个活跃 change，自动选择
+   - 如果有歧义，运行 `specline gate list --json` 获取可用 change，并使用 {{CONFIRM}} 让用户选择
 
-   Always announce: "Using change: <name>" and how to override (e.g., `/specline-pipeline --change <other>`).
+   始终告知："Using change: <name>"，并说明如何覆盖选择（如 `/specline-pipeline --change <other>`）。
 
-2. **Check status to understand the schema**
+2. **检查状态以识别 schema**
    ```bash
    specline gate artifacts --change "<name>" --json
    ```
-   Parse the JSON to understand:
-   - `schemaName`: The workflow being used (e.g., "spec-driven")
-   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+   解析 JSON，确认：
+   - `schemaName`：当前使用的工作流（如 "spec-driven"）
+   - 哪个 Artifact 包含 tasks（spec-driven 通常是 "tasks"，其他 schema 以状态为准）
 
-3. **Read context files**
+3. **读取上下文文件**
 
-   Read the planning files at `specline/changes/<name>/`:
-   - `proposal.md` — what & why
-   - `specs/<capability>/spec.md` — requirements & scenarios
-   - `design.md` — architecture & decisions
-   - `tasks.md` — implementation checklist
+   读取 `specline/changes/<name>/` 下的规划文件：
+   - `proposal.md` — 做什么与为什么
+   - `specs/<capability>/spec.md` — Requirements 与 Scenarios
+   - `design.md` — 架构与决策
+   - `tasks.md` — 实现清单
 
-   Check task completion: count `- [ ]` (incomplete) vs `- [x]` (complete).
+   检查 task 完成度：统计 `- [ ]`（未完成）与 `- [x]`（已完成）。
 
-4. **Show current progress**
+4. **展示当前进度**
 
-   Display:
-   - Progress: "N/M tasks complete"
-   - Remaining tasks overview
+   展示：
+   - 进度："N/M tasks complete"
+   - 剩余任务概览
 
-5. **Implement tasks (loop until done or blocked)**
+5. **实现 tasks（循环直到完成或阻塞）**
 
-   For each pending task:
-   - Show which task is being worked on
-   - Make the code changes required
-   - Keep changes minimal and focused
-   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
-   - Continue to next task
+   对每个待完成 task：
+   - 展示当前正在处理的 task
+   - 完成所需代码修改
+   - 保持修改最小且聚焦
+   - 在 tasks 文件中标记完成：`- [ ]` → `- [x]`
+   - 继续下一个 task
 
-   **Pause if:**
-   - Task is unclear → ask for clarification
-   - Implementation reveals a design issue → suggest updating artifacts
-   - Error or blocker encountered → report and wait for guidance
-   - User interrupts
+   **出现以下情况时暂停：**
+   - Task 不清晰 → 请求澄清
+   - 实现暴露设计问题 → 建议更新 Artifact
+   - 遇到错误或阻塞 → 报告并等待指引
+   - 用户中断
 
-6. **On completion or pause, show status**
+6. **完成或暂停时展示状态**
 
-   Display:
-   - Tasks completed this session
-   - Overall progress: "N/M tasks complete"
-   - If all done: suggest archive
-   - If paused: explain why and wait for guidance
+   展示：
+   - 本 session 完成的 tasks
+   - 总体进度："N/M tasks complete"
+   - 如果全部完成：建议归档
+   - 如果暂停：解释原因并等待指引
 
-## 输出模板 & 高级话题 (Layer 3)
+## 第 3 层：输出模板与高级话题
 
 ### 输出模板
 
-**Output During Implementation**
+**实现过程输出**
 
 ```
 ## Implementing: <change-name> (schema: <schema-name>)
@@ -114,7 +114,7 @@ Working on task 4/7: <task description>
 ✓ Task complete
 ```
 
-**Output On Completion**
+**完成时输出**
 
 ```
 ## Implementation Complete
@@ -131,7 +131,7 @@ Working on task 4/7: <task description>
 All tasks complete! Ready to archive this change.
 ```
 
-**Output On Pause (Issue Encountered)**
+**暂停时输出（遇到问题）**
 
 ```
 ## Implementation Paused
@@ -151,16 +151,16 @@ All tasks complete! Ready to archive this change.
 What would you like to do?
 ```
 
-### Guardrails
-- Keep going through tasks until done or blocked
-- Always read context files before starting (from the apply instructions output)
-- If task is ambiguous, pause and ask before implementing
-- If implementation reveals issues, pause and suggest artifact updates
-- Keep code changes minimal and scoped to each task
-- Update task checkbox immediately after completing each task
-- Pause on errors, blockers, or unclear requirements - don't guess
-- Use contextFiles from CLI output, don't assume specific file names
-- **Hook blocked → no silent fallback**: If this skill is invoked because a coding subagent (specline-frontend-dev / specline-backend-dev) was blocked by a hook, you MUST first notify the user of the blocking cause and attempt diagnosis. Do not silently execute tasks that should have been handled by the blocked subagent. Reference the Hook Blocking Resolution Protocol in the specline-pipeline skill.
+### 约束
+- 持续推进 tasks，直到完成或阻塞
+- 开始前始终读取上下文文件（来自 apply 指令输出）
+- task 有歧义时，先暂停询问，再实现
+- 实现暴露问题时，暂停并建议更新 Artifact
+- 保持代码修改最小化，并限定在当前 task 范围内
+- 每完成一个 task，立即更新 checkbox
+- 遇到错误、阻塞或需求不清时暂停，不要猜测
+- 使用 CLI 输出中的 contextFiles，不要假设固定文件名
+- **Hook blocked → no silent fallback**：如果本 Skill 是因为 coding subagent（specline-frontend-dev / specline-backend-dev）被 hook 阻断而被调用，必须先告知用户阻断原因并尝试诊断。不要静默执行本应由被阻断 subagent 处理的任务。参考 specline-pipeline Skill 中的 Hook Blocking Resolution Protocol。
 
 ---
 
@@ -176,7 +176,7 @@ What would you like to do?
 | "这个任务没有测试也没关系，下一个任务会补" | 每个 Testable=true 的任务必须产出测试。推迟 = 不写。 |
 | "tasks.md 的 Covers 追溯链我不用管，代码写对就行" | Covers 链是 Spec → Code 的可追溯纽带。不维护它，Code Review 和测试失败定位都失去锚点。 |
 
-## Verification Checklist
+## 验证清单
 
 每完成一个任务后自查，全部完成后终查：
 

package/core/skills/specline-archive-change/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: specline-archive-change
-description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
+description: 归档已完成的 Specline change。用于实现完成后 finalize 并 archive change。
 license: MIT
 compatibility: Compatible with specline.
 metadata:
@@ -9,11 +9,11 @@ metadata:
   generatedBy: "1.3.1"
 ---
 
-## TL;DR (Layer 1)
+## 第 1 层：速览
 
 > **一句话**：归档已完成的 Specline change。
 > **入口**：`/specline-archive-change [change-name]`
-> **流程**：选 change → 检查完成度 → Delta spec sync 决策 → 移动目录 → 完成
+> **流程**：选 change → 检查完成度 → Delta spec sync 决策 → 移动目录 → 归档后可选知识库更新建议 → 完成
 
 ### 归档前后目录结构变化
 
@@ -29,48 +29,48 @@ specline/changes/                  specline/changes/
                                   │       └── specs/
 ```
 
-**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+**输入**：可选传入 change name。若未传入，先判断能否从对话上下文推断；若模糊或有歧义，必须展示可用 change 让用户选择。
 
 ---
 
-## Steps (Layer 2 — Happy Path)
+## 第 2 层：主流程
 
-1. **If no change name provided, prompt for selection**
+1. **未提供 change name 时，请用户选择**
 
-   Run `specline gate list --json` to get available changes. Use {{CONFIRM}} to let the user select.
+   运行 `specline gate list --json` 获取可用 change。使用 {{CONFIRM}} 让用户选择。
 
-   Show only active changes (not already archived).
-   Include the schema used for each change if available.
+   只展示活跃 change（不展示已归档项）。
+   如果可用，展示每个 change 使用的 schema。
 
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+   **重要**：不要猜测或自动选择 change。始终让用户选择。
 
-2. **Check artifact completion status**
+2. **检查 Artifact 完成状态**
 
-   Run `specline gate artifacts --change "<name>" --json` to check artifact completion.
+   运行 `specline gate artifacts --change "<name>" --json` 检查 Artifact 完成状态。
 
-   Parse the JSON to understand:
-   - `schemaName`: The workflow being used
-   - `artifacts`: List of artifacts with their status (`done` or other)
+   解析 JSON，确认：
+   - `schemaName`：当前使用的工作流
+   - `artifacts`：Artifact 列表及状态（`done` 或其他）
 
-   **If any artifacts are not `done`:**
-   - Display warning listing incomplete artifacts
-   - Use {{CONFIRM}} to confirm user wants to proceed
-   - Proceed if user confirms
+   **如果存在未 `done` 的 Artifact：**
+   - 展示警告，列出未完成的 Artifact
+   - 使用 {{CONFIRM}} 确认用户是否继续
+   - 用户确认后继续
 
-3. **Check task completion status**
+3. **检查 task 完成状态**
 
-   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+   读取 tasks 文件（通常是 `tasks.md`），检查未完成任务。
 
-   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+   统计 `- [ ]`（未完成）和 `- [x]`（已完成）的任务数量。
 
-   **If incomplete tasks found:**
-   - Display warning showing count of incomplete tasks
-   - Use {{CONFIRM}} to confirm user wants to proceed
-   - Proceed if user confirms
+   **如果发现未完成任务：**
+   - 展示警告，说明未完成任务数量
+   - 使用 {{CONFIRM}} 确认用户是否继续
+   - 用户确认后继续
 
-   **If no tasks file exists:** Proceed without task-related warning.
+   **如果不存在 tasks 文件：** 不展示 task 相关警告，继续执行。
 
-4. **Assess delta spec sync state**
+4. **评估 delta spec sync 状态**
 
    **决策流程：**
 
@@ -84,69 +84,130 @@ specline/changes/                  specline/changes/
                             └── 跳过 → 归档
    ```
 
-   Check for delta specs at `specline/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+   检查 `specline/changes/<name>/specs/` 下是否存在 delta specs。若不存在，不提示 sync，直接继续。
 
-   **If delta specs exist:**
-   - Compare each delta spec with its corresponding main spec at `specline/specs/<capability>/spec.md`
-   - Determine what changes would be applied (adds, modifications, removals, renames)
-   - Show a combined summary before prompting
+   **如果存在 delta specs：**
+   - 将每个 delta spec 与 `specline/specs/<capability>/spec.md` 中对应的 main spec 比较
+   - 判断将应用哪些变化（新增、修改、删除、重命名）
+   - 提示用户前先展示合并摘要
 
-   **Prompt options:**
-   - If changes needed: "Sync now (recommended)", "Archive without syncing"
-   - If already synced: "Archive now", "Sync anyway", "Cancel"
+   **提示选项：**
+   - 需要同步时："Sync now (recommended)", "Archive without syncing"
+   - 已同步时："Archive now", "Sync anyway", "Cancel"
 
-   If user chooses sync, {{DISPATCH}}，role="general-purpose"，prompt: "Use Skill tool to invoke specline-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>". Proceed to archive regardless of choice.
+   如果用户选择 sync，{{DISPATCH}}，role="general-purpose"，prompt: "Use Skill tool to invoke specline-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"。无论用户是否选择 sync，之后都继续归档。
 
-5. **Perform the archive**
+5. **执行归档**
 
-   Create the archive directory if it doesn't exist:
+   如果归档目录不存在，先创建：
    ```bash
    mkdir -p specline/changes/archive
    ```
 
-   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+   使用当前日期生成目标名称：`YYYY-MM-DD-<change-name>`
 
-   **Check if target already exists:**
-   - If yes: Fail with error, suggest renaming existing archive or using different date
-   - If no: Move the change directory to archive
+   **检查目标目录是否已存在：**
+   - 如果存在：失败并报错，建议重命名已有归档或使用不同日期
+   - 如果不存在：将 change 目录移动到 archive
 
    ```bash
    specline gate archive --execute --change <name>
    ```
 
-6. **Display summary**
-
-   Show archive completion summary including:
-   - Change name
-   - Schema that was used
-   - Archive location
-   - Whether specs were synced (if applicable)
-   - Note about any warnings (incomplete artifacts/tasks)
-
-### Output On Success
+6. **展示摘要**
+
+   展示归档完成摘要，包括：
+   - Change 名称
+   - 使用的 schema
+   - 归档位置
+   - specs 是否已同步（如适用）
+   - 任何警告说明（Artifact/task 未完成）
+
+7. **归档后知识库更新建议**
+
+   归档成功后，评估该 change 是否包含值得为未来 AI Agent 或维护者沉淀的知识。
+
+   **重要边界：**
+   - 该步骤发生在归档之后且是可选动作，绝不能阻塞归档成功。
+   - 更新任何知识文件前都必须先询问用户。
+   - 如果用户跳过更新，正常完成，不视为警告。
+   - 不要假设项目一定使用 `specline-knowledge`；它只是可能的知识落点之一。
+
+   **可检查输入：**
+   - `proposal.md` — 目的与范围
+   - `design.md` — 架构决策与替代方案
+   - `tasks.md` — 实际工作拆解与触达范围
+   - `specs/` — 用户可见能力变化
+   - `summary.md` — 最终归档摘要（如存在）
+
+   **当 change 包含以下内容时，建议更新知识库：**
+   - 新增或改变核心架构、pipeline 阶段行为、Agent 职责或 Skill 职责
+   - 新增或改变 CLI 命令、配置字段、公开接口、Hook 行为或用户可见工作流
+   - 新的长期项目概念或术语
+   - 有意义的设计决策、权衡或被拒绝的替代方案
+   - 未来维护者或 Agent 应知道的可复用操作指南
+   - 跨模块核心变更，且 `proposal.md`、`design.md` 或 `summary.md` 解释了长期有效的 why
+
+   **以下情况不建议更新知识库：**
+   - 没有长期设计变化的纯 bug 修复
+   - 仅 copy、注释、格式或 typo 修改
+   - 小范围本地测试更新
+   - 不应沉淀为长期项目知识的临时兼容修复
+
+   **如果不建议更新：**
+   - 在归档摘要中简短说明：`Knowledge: no update suggested`。
+
+   **如果建议更新：**
+   - 用简短列表展示可沉淀的知识。
+   - 询问用户是否现在更新知识库。
+   - 至少提供 `Update knowledge base` 和 `Skip` 两个选项。
+
+   **如果用户确认：**
+   1. 先查找 `specline-knowledge` 风格结构：
+      - `AGENTS.md` 存在并链接到 `docs/knowledge/*`，或
+      - `docs/knowledge/` 存在。
+   2. 如果找到，以 archive Artifact 为增量输入更新最相关的知识文件。优先选择：
+      - 架构或 pipeline 流程变化 → `docs/knowledge/architecture.md`
+      - 长期编码/工作流约定 → `docs/knowledge/conventions.md`
+      - CLI/config/API/Hook 参考 → `docs/knowledge/reference.md`
+      - 可复用操作流程 → `docs/knowledge/howtos/`
+      - 重大决策和权衡 → `docs/knowledge/decisions/`
+      - 长期概念 → `docs/knowledge/glossary.md`
+   3. 如果不存在 `specline-knowledge` 结构，查找项目自有的可能知识落点：
+      - `AGENTS.md`, `CLAUDE.md`, `CURSOR.md`, `.cursor/rules/`
+      - `docs/adr/`, `docs/decisions/`, `docs/architecture/`
+      - 仅当 change 影响用户可见行为或安装配置时，才考虑 `README.md`
+   4. 如果合适落点很明显，告知用户计划更新的位置，并在编辑前确认。
+   5. 如果没有明显落点，询问用户知识应写到哪里。
+
+### 成功输出
 
 ```
-## Archive Complete
+## 归档完成
 
 **Change:** <change-name>
 **Schema:** <schema-name>
 **Archived to:** specline/changes/archive/YYYY-MM-DD-<name>/
 **Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
+**Knowledge:** No update suggested / Suggested and skipped / Updated <path>
 
 All artifacts complete. All tasks complete.
 ```
 
 ---
 
-## Guardrails (Layer 3 — 高级话题)
+## 第 3 层：约束与高级话题
 
-- Always prompt for change selection if not provided
-- Use artifact graph (specline gate artifacts --json) for completion checking
-- Don't block archive on warnings - just inform and confirm
-- Preserve .specline.yaml when moving to archive (it moves with the directory)
-- Show clear summary of what happened
-- If sync is requested, use specline-sync-specs approach (agent-driven)
-- If delta specs exist, always run the sync assessment and show the combined summary before prompting
+- 未提供 change 时，始终提示用户选择
+- 使用 Artifact 图（`specline gate artifacts --json`）检查完成度
+- 警告不阻塞归档，只需告知并确认
+- 移动到 archive 时保留 `.specline.yaml`（随目录一起移动）
+- 清晰展示发生了什么
+- 如果请求 sync，使用 specline-sync-specs 方案（Agent 驱动）
+- 如果存在 delta specs，始终执行 sync 评估，并在提示用户前展示合并摘要
+- 仅在归档成功后运行知识库更新建议，绝不把它变成 Gate
+- 没有用户明确确认时，绝不更新知识文件
+- 不要假设项目使用 `specline-knowledge`；探测可能的知识落点，歧义时询问用户
 
 ---
 
@@ -160,8 +221,10 @@ All artifacts complete. All tasks complete.
 | "Delta spec 不用同步，下次再说" | 未同步的 Delta spec 意味着 spec 与代码脱节。归档后几乎不会再有人回来补。 |
 | "归档就是移动目录，不需要通知用户" | 归档改变了 change 的可见性和可修改性。用户需要知道发生了什么。 |
 | "警告不用管，自动继续就行" | 警告（artifact 不完整、task 未完成）是信号。归档时应确认而非忽略。 |
+| "知识库更新也算归档完成条件" | 知识沉淀是归档后的可选收尾动作。用户跳过时 pipeline 仍然成功完成。 |
+| "项目一定用 specline-knowledge" | 用户项目可能有自己的 AGENTS.md、CLAUDE.md、ADR 或 README 维护方式。先探测，再确认，找不到就问。 |
 
-## Verification Checklist
+## 验证清单
 
 归档前自查：
 
@@ -171,3 +234,5 @@ All artifacts complete. All tasks complete.
 - [ ] Delta spec sync 决策已完成（存在则展示摘要→询问；不存在则跳过）
 - [ ] 归档目录已创建（`specline/changes/archive/YYYY-MM-DD-<name>/`）
 - [ ] 归档摘要已展示给用户
+- [ ] 归档成功后已判断是否需要知识库更新建议
+- [ ] 若建议更新知识库，已由用户确认后才写入；跳过不视为失败