ai-spec-tool 0.1.0 → 0.1.3

package/README.md

@@ -8,11 +8,18 @@ Installable agents + rules for AI spec workflows.
 npx ai-spec-tool init
 ```
 
+Optional:
+```bash
+npx ai-spec-tool init --ask
+npx ai-spec-tool init --force
+```
+
 ### What it does
 
 - Installs `.agents/` into the current project (merge-safe).
+- Scaffolds `docs/` base structure (no preset projects).
 - Updates/creates `AGENTS.md` using an anchored block so local edits are preserved.
-- Conflicts are written as `*.incoming` next to the original file.
+- Conflicts are written as `*.incoming` next to the original file (unless `--force` or `--ask` resolves them).
 
 ### AGENTS.md update strategy
 
@@ -33,3 +40,15 @@ The CLI looks for the block below and replaces its content if present. If not fo
 ## Requirements
 
 - Node.js 18+
+
+## Release workflow
+
+1. Update assets under `assets/` if needed.
+2. Bump version and update changelog (requires clean git status):
+   - `npm run version:patch`
+   - `npm run version:minor`
+   - `npm run version:major`
+   - The changelog auto-includes recent git commit subjects (last tag or last 20 commits).
+   - The script commits and tags the release as `vX.Y.Z`.
+3. Publish:
+   - `npm publish --access public`

package/assets/.agents/skills/bugfix/SKILL.md

@@ -3,30 +3,46 @@ name: bugfix
 description: 用户提供报错信息或描述异常行为时使用
 ---
 
-## 依赖（必须存在且必须遵守）
-- docs/global/naming-rule.md
-- docs/global/vision.md
-- docs/global/architecture.md
+# 前置依赖检查（统一规则）
 
+## 依赖清单（必须存在且非占位）
+- `docs/_shared/conventions.md`
+- `docs/_shared/glossary.md`
+- `docs/architecture/<project>/architecture.md`
+- `docs/architecture/<project>/layer_rules.yaml`
+- 相关 module spec（若存在则必须读取）
 
-## 流程（严格执行）
+## 缺失判定
+文件不存在 / 内容为空 / 首行含 `AI-SPEC-TOOL:PLACEHOLDER`
 
-### 1) 依赖检查（强制）
-- 你必须先尝试读取并理解所有依赖文件内容。
-- 若任何依赖文件无法读取/不存在/内容为空：视为“依赖未满足”，进入步骤 2。
-- 若所有依赖已满足：进入步骤 3。
-
-### 2) 依赖缺失
-- 你必须只输出以下内容（禁止其他内容）：
-  `缺少依赖[<依赖名称>]\n回复「Y」开始创建依赖。`
-- 下一run使用 skill: rules-creator
-
-### 3) 依赖满足
-- 帮助用户修正问题
+## 缺失时唯一输出
+<<<
+缺少依赖[<path>]
 
+【下一步】请选择一项：
+1. 开始创建依赖
+请回复：1
+>>>
+用户回复 `1` 后切换 `rules-creator` 生成缺失文件。
 
+---
 
+# 1) 修复流程（简版）
+1. 复述问题与影响
+2. 定位可能模块与层级
+3. 给出修复方案并修改代码
+4. 更新相关 module spec（如需）
 
+---
 
+# 2) 对话输出（必须包含下一步）
 
+<<<
+已完成问题修复：  
+`<简述>`
 
+【下一步】请选择一项：
+1. 继续修正其他问题（bugfix）
+2. 进入新的需求讨论（plan）
+请回复：1/2
+>>>

package/assets/.agents/skills/plan/SKILL.md

@@ -1,323 +1,56 @@
 ---
 name: plan
-description: 用户明确需要一个新的系统、模块或功能体系，或对既有系统进行修改；本 skill 用于生成“非确定性架构裁决 Plan”
+description: 用户明确需要新的系统/模块/功能体系或跨项目协作时，用于生成顶层 Plan（multi-project）
 ---
 
-#前置依赖（强制）
+# 前置依赖检查（统一规则）
 
-## 依赖的规范文件（必须全部存在）
-- docs/global/vision.md
-- docs/global/architecture.md
-- docs/global/naming-rule.md
+## 依赖清单（必须存在且非占位）
+- `docs/_shared/conventions.md`
+- `docs/_shared/glossary.md`
+- `docs/architecture/<project>/architecture.md`（计划涉及的每个 project）
+- `docs/architecture/<project>/layer_rules.yaml`（计划涉及的每个 project）
+- 前端 project 需额外存在：
+  - `docs/architecture/<project>/ui/design-tokens.md`
+  - `docs/architecture/<project>/ui/layout-and-responsive.md`
+  - `docs/architecture/<project>/ui/patterns.md`
 
-## 依赖检查流程（不可跳过）
-- 你必须先尝试读取并理解所有依赖文件内容
-- 若任何依赖文件无法读取 / 不存在 / 内容为空：
-- **只能输出以下内容（禁止输出任何其他文字）**
-    > 缺少依赖[<依赖名称>]
-    > 回复「Y」开始创建依赖
-- 下一次 run 必须使用 skill: rules-creator
-- 若所有依赖均存在，才可继续
+## 缺失判定（必须）
+视为缺失：文件不存在 / 内容为空 / 首行包含 `AI-SPEC-TOOL:PLACEHOLDER`
 
----
-
-## 1) 框架存在性检查（强制）
-
-在进入需求澄清前，必须确认当前项目是否已建立 `docs/global/architecture.md` 中「技术栈选择」指定的主框架。
-默认项目根目录为 `./project`（若不存在则视为尚未建立框架）。
-
-执行规则：
-- 先读取 `docs/global/architecture.md` 的「技术栈选择」
-- 判断 `./project` 内是否已具备该框架的标准结构/配置
-- 若尚未建立：
-  - 必须先询问用户是否需要你建立框架
-  - 若用户同意：**只能使用该框架的主流标准初始化指令**（例如官方 CLI/脚手架），且必须初始化在 `./project`
-  - **禁止在 `./` 根目录初始化**，也禁止手动逐文件创建
-  - 若用户拒绝：停止并等待用户自行处理
- - 若已建立框架：
-   - 检查 `.vscode/launch.json` 是否存在
-   - 若不存在：询问用户是否需要你建立**符合该技术框架**的快速启动方案
-   - **专案根目录为 `./project/`,但`launch.json`是在`.vscode/launch.json` 而不是`.vscode/project/launch.json` 
-
----
-
-## 2) 需求澄清阶段（强制）
-
-### 2.1 澄清目的（不可偏离）
-
-* 本阶段**仅用于理解用户真实意图与需求边界**
-* 本阶段**不产出任何设计或结论**
-* 在本阶段中 **严禁**：
-
-  * 讨论或暗示模块类型（Service / Adapter / Core 等）
-  * 讨论架构、分层、依赖关系
-  * 讨论技术选型、实现方式、数据结构
-  * 产出任何 spec、plan 或设计草案
-
-> ⚠️ 本阶段的唯一目标：**把「用户真正想做什么」问清楚**
-
----
+## 缺失时的唯一输出
+<<<
+缺少依赖[<path>]
 
-### 2.2 澄清问题（强制逐题、单题执行）
-
-* 以下问题 **必须按顺序逐题完成**
-* **一次只允许提出一个问题**
-* 在当前问题尚未获得用户确认前：
-
-  * ❌ 不得显示后续问题
-  * ❌ 不得列出问题清单
-  * ❌ 不得暗示「接下来还会问什么」
-* 每一题都视为一个独立对话回合
-
-> ⚠️ 违反上述规则，视为澄清流程失败
+【下一步】请选择一项：
+1. 开始创建依赖
+请回复：1
+>>>
+用户回复 `1` 后，切换到 `rules-creator` 并生成对应文件。
 
 ---
 
-### 2.3 提问与回应格式（强制）
-
-**每一轮提问必须严格遵守以下结构，不得增删：**
-
-1. 提出 **当前问题（仅此一题）**
-2. 基于以下信息，给出一段 **猜测性建议答案**：
-
-   * 已完成的前序问题回答
-   * `vision.md`
-   * `architecture.md`
-   * `naming-rule.md`
-3. 明确提示用户操作方式：
-
-```
-回复「Y」接受上述建议，
-或直接输入你的实际答案。
-```
-
-* 猜测性建议答案的目的仅是：
-
-  * 帮助用户更快理解问题
-  * 降低回答成本
-* **不得**：
-
-  * 引导用户做架构、模块、实现相关决策
-  * 在建议答案中偷渡解决方案
+# 1) 需求澄清（必须）
+每次提问都必须标注进度，例如：`问题[1/4]`。
+只澄清“本次变更目标、成功标准、非目标、涉及哪些 project”。
+若用户未明确 project scope：先列出候选 projects，再确认 scope。
+若用户已有规格书（Interface）：必须获取其路径并在 plan 中记录。
 
 ---
 
-### 2.4 澄清问题池（内部使用，不得一次性输出）
-
-> 以下问题仅作为**内部顺序控制用**
-> **不得在任何一次输出中同时展示多个问题**
-
-#### 问题 1
-
-你这次想新增或修改的核心能力是什么？
-（完成后，系统「多了什么」或「哪里不一样」？）
-
-#### 问题 2
-
-这个能力通常在什么情境下被需要？
-（谁、在什么情况下，会用到它？）
-
-#### 问题 3
-
-和现在相比，这次变更会让哪些行为或结果发生改变？
-
-#### 问题 4
-
-你觉得这个能力最容易出问题的地方是什么？
-（例如：状态混乱、规则分散、依赖外部、不稳定）
-
-#### 问题 5
-
-如果这次改动出错，你最不能接受的失败结果是什么？
-
----
-
-### 2.5 推进规则（状态机约束）
-
-* 若尚未取得 **问题 N** 的有效回答：
-
-  * **只能**继续停留在问题 N
-* 当用户：
-
-  * 回复「Y」→ 视为接受建议答案，记录为该题结论
-  * 输入自定义答案 → 以用户答案为准，覆盖建议
-* 完成问题 N 后：
-
-  * 下一轮对话 **只能**提出问题 N+1
-* 在问题 1～5 全部完成前：
-
-  * ❌ 不得总结
-  * ❌ 不得生成 plan / spec / 模块拆分
-  * ❌ 不得进入下一阶段
-
----
-
-### 2.6 违规防护（强制）
-
-* 若当前问题未完成，却出现以下任一行为，必须立即自我修正并重新提问当前问题：
-
-  * 提前出现后续问题内容
-  * 总结尚未完成的澄清结果
-  * 引入架构 / 模块 / 实现讨论
-  * 解释「接下来会做什么」
-
----
-
-## 3) Plan 生成原则（非常重要）
-
-### 3.1 Plan 的角色定义
-- plan.md 是 **非确定性架构裁决的集合**
-- plan.md 是 **plan 执行器的输入**
-- plan.md 的内容应：
-- 让后续 module spec 的生成 **几乎不需要猜**
-- 明确哪些事情已经被裁决，后续不得再推断
-
-### 3.2 禁止在 Plan 中出现的内容
-- ❌ 文件创建顺序
-- ❌ 技术选型
-- ❌ 实现细节
-- ❌ 函数名 / API / 参数
-
----
-
-## 4) plan.md 输出结构（强制使用，不得增删章节）
-
-你**必须**生成符合以下结构的 plan.md：
-
-<以下为plan.md输出范例>
----
-plan_id: <自动生成>
-kind: <feature|update|refactor>
-scope: <系统或子系统>
-version: 1
----
-
----
-
-### intent
-
-* goal: 架构目标（列表）
-* non_goals: 明确不做的事（列表）
-* success_criteria: 可验证完成标准（列表）
-
----
-
-### modules
-
-* 必须以 **module 为单位**
-* 每个 module **必须包含以下字段**：
-
-  * name
-  * type
-  * change
-  * purpose
-  * capabilities（reads / writes / events / subscribes / calls 等）
-  * ownership（ssot_facts / state_owner）
-  * dependencies（must / forbid）
-  * constraints（must / must_not）
-  * collaboration
-  * 若 state_owner=true，必须包含 state_model
-
----
-
-### flows
-
-* use_cases：以结构化 chain 描述关键流程
-* 每个 use case 必须明确：
-
-  * trigger
-  * actor
-  * action
-  * target
-  * outcome
-
----
-
-### rules
-
-* hard: 全局不可违反规则（列表）
-
----
-### execution_steps
-
-* 必须提供「建议修改流程」的最小步骤
-* 必须按 **模块依赖关系** 排序：先基础依赖、后上层组合
-* **必须覆盖本次 plan 中所有 modules**
-* 每一步 **只能提到一个 module**（新增或修改），不得合并
-* 每一步必须使用 **有序列表**（1. 2. 3.）来强调顺序
-* 允许引用模块名或章节名，但不得包含实现细节、函数名、API 或文件路径
-* 每一步需可被 spec-executor 按序执行或核对
-* 若依赖顺序无法确定，必须停止并向用户补问
-
----
-<以上为plan.md输出范例>
-
-## 5) 若信息不足的处理规则（强制）
-
-* 若无法确定 module 边界 / 状态归属 / SSOT：
-
-  * **必须停止**
-  * 明确列出缺失信息
-  * 向用户提问补充
-* ❌ 不得在信息不足时生成假设性 plan.md
-
----
-
-## 6) 最终输出要求（非常重要）
-- 1.生成一份 Plan 文件
-  - 文件路径：`./docs/plan/<index>-<plan目标>.md`
-    - `<index>`：根据 `./docs/plan/` 目录下已有文件数量顺序递增生成
-    - `<plan目标>`：在完成需求澄清后，根据本次变更的核心意图自动总结生成
-  - 输出格式：Markdown
-  - 语言：中文为主
-
-- 2.文字输出
-  > 已完成plan文件的生成<显示文件名(带有超链接)>
-  > 
-  > 接下来
-  > 1.讨论修改plan文件细节
-  > 2.直接执行plan
-  - 直接执行plan → 使用 skill: plan-executor
-
-
-## 6) 最终输出要求（非常重要）
-
-### 6.1 Plan 文件生成（强制）
-
-- 在完成「需求澄清阶段」全部问题后：
-  - **必须生成一份 Plan 文件**
-  - **不得将 Plan 文件内容直接输出在对话中**
-
-#### 文件路径规则
-- 文件路径：`./docs/plan/<index>-<plan目标>.md`
-
-- `<index>`：
-  - 根据 `./docs/plan/` 目录下已有文件数量
-  - 以递增顺序生成（001, 002, 003 ...）
-
-- `<plan目标>`：
-  - 在完成需求澄清后
-  - 根据本次变更的核心意图自动总结生成
-  - 不包含技术名词或实现细节
-
-#### 文件格式
-- 内容格式：Markdown
-- 语言：中文为主
-
----
-
-### 6.2 对话反馈（唯一允许的文字输出）
-
-在 Plan 文件生成完成后，对话中**只允许**输出以下结构：
+# 2) Plan 文件生成（强制，流程[2/3]）
+详细结构与字段定义见：`assets/templates/plan.md`
+生成后必须：
+- 更新 `docs/plan/index.yaml`
+- 生成 `docs/plan/<plan-id>/summary.md`
 
-> 已完成 Plan 文件的生成：  
-> `<文件名>`（需为可点击超链接）
+## 输出路径
+`./docs/plan/<plan-id>/plan.md`
 
-> 接下来你可以选择：
-> 1. 讨论并修改 Plan 文件细节  
-> 2. 直接执行 Plan（将进入 plan-executor，并把 plan 改名为 `.processing.md`）
+`<plan-id>` 规则：
+- `<index>-<slug>`（index 3 位递增）
+- slug 为本次变更目标摘要（不含技术实现）
 
-- 若用户选择「直接执行 Plan」：
-  - **必须使用** `skill: plan-executor`
-  - 不得再次生成或修改 Plan 文件
-```
+# 3) 对话输出（唯一允许的文字输出，流程[3/3]）
+- 输出已生成文件路径
+- 提示下一步选项：讨论 / 直接执行（plan-executor）

package/assets/.agents/skills/plan/assets/templates/plan.md

@@ -0,0 +1,47 @@
+# Plan 文件模板
+
+```md
+---
+plan_id: <plan-id>
+kind: <feature|update|refactor>
+version: 1
+projects: [<project>, ...]
+source_interface: docs/requirements/<spec-id>.md
+---
+
+## intent
+- goal
+- non_goals
+- success_criteria
+
+## project_objectives
+### <project>
+- 本次目标
+
+## modules
+```yaml
+- project: <project>
+  name: <module>
+  layer: <layer>
+  change: <create|update|refactor>
+  purpose: ...
+  capabilities: ...
+  ownership: ...
+  dependencies:
+    must: [...]
+    forbid: [...]
+  constraints:
+    must: [...]
+    must_not: [...]
+```
+
+## flows
+- use_cases: ...
+
+## rules
+- hard: [...]
+
+## execution_steps
+1. <project>/<module>
+2. <project>/<module>
+```