ai-spec-tool 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# ai-spec-tool
+
+Installable agents + rules for AI spec workflows.
+
+## Usage
+
+```bash
+npx ai-spec-tool init
+```
+
+### What it does
+
+- Installs `.agents/` into the current project (merge-safe).
+- Updates/creates `AGENTS.md` using an anchored block so local edits are preserved.
+- Conflicts are written as `*.incoming` next to the original file.
+
+### AGENTS.md update strategy
+
+The CLI looks for the block below and replaces its content if present. If not found, it appends the block.
+
+```
+<!-- AI-SPEC-TOOL:START -->
+... managed content ...
+<!-- AI-SPEC-TOOL:END -->
+```
+
+## Conflict handling
+
+- New file missing: copy in
+- Same file: skip
+- Different file: write `<file>.incoming` (do not overwrite your file)
+
+## Requirements
+
+- Node.js 18+

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

@@ -0,0 +1,32 @@
+---
+name: bugfix
+description: 用户提供报错信息或描述异常行为时使用
+---
+
+## 依赖（必须存在且必须遵守）
+- docs/global/naming-rule.md
+- docs/global/vision.md
+- docs/global/architecture.md
+
+
+## 流程（严格执行）
+
+### 1) 依赖检查（强制）
+- 你必须先尝试读取并理解所有依赖文件内容。
+- 若任何依赖文件无法读取/不存在/内容为空：视为“依赖未满足”，进入步骤 2。
+- 若所有依赖已满足：进入步骤 3。
+
+### 2) 依赖缺失
+- 你必须只输出以下内容（禁止其他内容）：
+  `缺少依赖[<依赖名称>]\n回复「Y」开始创建依赖。`
+- 下一run使用 skill: rules-creator
+
+### 3) 依赖满足
+- 帮助用户修正问题
+
+
+
+
+
+
+

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

@@ -0,0 +1,323 @@
+---
+name: plan
+description: 用户明确需要一个新的系统、模块或功能体系，或对既有系统进行修改；本 skill 用于生成“非确定性架构裁决 Plan”
+---
+
+#前置依赖（强制）
+
+## 依赖的规范文件（必须全部存在）
+- docs/global/vision.md
+- docs/global/architecture.md
+- docs/global/naming-rule.md
+
+## 依赖检查流程（不可跳过）
+- 你必须先尝试读取并理解所有依赖文件内容
+- 若任何依赖文件无法读取 / 不存在 / 内容为空：
+- **只能输出以下内容（禁止输出任何其他文字）**
+    > 缺少依赖[<依赖名称>]
+    > 回复「Y」开始创建依赖
+- 下一次 run 必须使用 skill: rules-creator
+- 若所有依赖均存在，才可继续
+
+---
+
+## 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 或设计草案
+
+> ⚠️ 本阶段的唯一目标：**把「用户真正想做什么」问清楚**
+
+---
+
+### 2.2 澄清问题（强制逐题、单题执行）
+
+* 以下问题 **必须按顺序逐题完成**
+* **一次只允许提出一个问题**
+* 在当前问题尚未获得用户确认前：
+
+  * ❌ 不得显示后续问题
+  * ❌ 不得列出问题清单
+  * ❌ 不得暗示「接下来还会问什么」
+* 每一题都视为一个独立对话回合
+
+> ⚠️ 违反上述规则，视为澄清流程失败
+
+---
+
+### 2.3 提问与回应格式（强制）
+
+**每一轮提问必须严格遵守以下结构，不得增删：**
+
+1. 提出 **当前问题（仅此一题）**
+2. 基于以下信息，给出一段 **猜测性建议答案**：
+
+   * 已完成的前序问题回答
+   * `vision.md`
+   * `architecture.md`
+   * `naming-rule.md`
+3. 明确提示用户操作方式：
+
+```
+回复「Y」接受上述建议，
+或直接输入你的实际答案。
+```
+
+* 猜测性建议答案的目的仅是：
+
+  * 帮助用户更快理解问题
+  * 降低回答成本
+* **不得**：
+
+  * 引导用户做架构、模块、实现相关决策
+  * 在建议答案中偷渡解决方案
+
+---
+
+### 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 文件生成完成后，对话中**只允许**输出以下结构：
+
+> 已完成 Plan 文件的生成：  
+> `<文件名>`（需为可点击超链接）
+
+> 接下来你可以选择：
+> 1. 讨论并修改 Plan 文件细节  
+> 2. 直接执行 Plan（将进入 plan-executor，并把 plan 改名为 `.processing.md`）
+
+- 若用户选择「直接执行 Plan」：
+  - **必须使用** `skill: plan-executor`
+  - 不得再次生成或修改 Plan 文件
+```