ai-spec-tool 0.1.2 → 0.1.4

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
 

package/assets/AGENTS.md

@@ -1,30 +1 @@
-你必须先分析用户在开发专案中的需求类型，并严格分类：
-
-- plan执行(plan-executor)
-  用户想要执行plan文件
-  `./docs/plan`为plan文件路径,去里面找用户描述的plan
-  1.若plan文件后缀为.processing.md
-    → 使用 skill: spec-executor
-  2.若plan文件后缀为.done.md
-    回复用户 > 此plan已完成
-  3.若plan文件后缀为.md
-  → 使用 skill: plan-executor
-
-- 规则文件创建(rules-creator)
-  用户想要生成规则文件
-  → 使用 skill: rules-creator
-
-- 异常修复（bugfix）
-  用户提供报错信息或描述异常行为
-  → 使用 skill: bugfix
-
-- 功能增修（update）
-  用户希望修改或新增功能
-  - 若该功能不需要建立一个目前不存在的系统 → 直接修改代码与对应 spec
-  - 若该功能需要建立一个新的系统/修改已有系统就可以 → 使用 skill: plan
-
-- 系统规划（plan）
-  用户明确需要一个新的系统、模块或功能体系
-  → 使用 skill: plan
-
-若意图并非以上,直接回答用户即可
+若有./docs/global/architecture.md,当对话满足#plan模式自动触发条件: 执行 skills spec-creator

package/assets/skills/plan/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: plan
+description: 当用户想要执行一个plan
+---
+#依赖检查
+
+依赖文件清单:
+ - ./docs/global/vision.md
+ - ./docs/global/architecture.md
+ - ./docs/projects/*/architecture.md
+
+ACTION: 请先检查专案环境下是否存在依赖清单内的所有文档
+IF: 存在缺失文件
+输出规则:
+ - __PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+ - __MISSING_FILE_NAME__ 缺失的文件名
+ - 若有多个缺失文件就多行显示
+ - 若用户选择 开始创建文档: 执行 skill: spec-creator
+ACTION: 
+<<结合输出规则,输出以下内容>>
+## 您需要先创建文档:
+ - __MISSING_FILE_NAME__
+---
+1) 开始创建文档
+<<输出以上内容,不得再输出任何其他内容>>
+ENDIF
+
+ACTION: 阅读所有依赖文件内容来了解专案,并在遵守文件内定义的规范约束下执行后续步骤
+IF: 对话记录尚未符合./docs/global/architecture.md的 #plan模式自动触发条件
+继续和用户聊相关话题,直到 #plan模式自动触发条件 满足
+ENDIF
+
+#输出文件
+*仅在以上所有流程完成后才执行
+
+输出格式:Markdown
+语言:中文为主
+输出文件内容规则:
+__PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+__2__ 列出架构能力目标（列表）。
+不得写功能描述。
+每条必须可被success_criteria验证。
+__3__ 列出可验证完成标准（列表）。
+格式：用户行为 -> 系统状态变化 -> 可观察结果。
+必须覆盖所有goal。
+__4__ 列出明确不做事项（列表）。
+不得引入新的领域主权。
+__5__ 以 module 为单位列出本 plan 涉及的所有 modules
+必须覆盖所有受影响 子项目(project)
+必须覆盖所有受影响 module（包括 change:none）
+必须遵守 layer 依赖方向。
+* 必须以 **module 为单位** 描述
+* 每个 module **必须包含以下字段**：
+  * name
+  * project
+  * layer type
+  * change（add | update | refactor | remove | none）
+  * 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
+
+__6__ 定义关键use_cases。
+每条必须映射到某个module并体现状态变化。
+
+* use_cases:
+  - trigger:
+    actor:
+    action:
+    target:
+    outcome:
+
+__7__ 记录已确定的实际接口/DB栏位/函数格式结构结论（列表）。
+必须结构化、可直接复用；不写讨论过程。
+
+* contracts:
+  - type: api | db | function
+    name:
+    spec:
+    project:
+
+__8__ 定义hard规则（列表）。
+必须为全局不可违反架构规则。
+违反则判定plan无效。
+__9__ 提供最小修改流程。
+必须：
+- 覆盖所有modules
+- 每步只包含一个module
+- 使用有序列表
+- 按依赖自底向上排序
+- 不得包含实现细节、函数名、API、文件路径
+- 若依赖顺序无法确定，必须停止并提示补问
+__PLAN_NAME__ 为<index>-<plan目标>
+<index>:根据 `./docs/plan/` 目录下已有文件夹数量,以递增顺序生成(001, 002, 003 ...)
+<plan目标>:根据本次变更的核心意图自动总结生成,不包含技术名词或实现细节
+输出文件内容结构:
+<<以下为实际输出文件格式,需结合输出规则生成部分动态内容>>
+#### intent
+#goal
+__2__
+
+#success_criteria
+__3__
+
+#non_goals
+__4__
+
+#### modules
+__5__
+
+#### flows
+__6__
+
+#### contracts
+__7__
+
+#### rules
+__8__
+
+#### execution_steps
+__9__
+
+<<以上为实际输出文件格式,需结合输出规则生成部分动态内容>>
+
+[MARK:1]
+输出规则:
+ - __PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+ - __输出文件内容__ 显示基于[输出文件内容规则/输出文件内容结构]总结输出文件内容
+ACTION: 
+<<结合输出规则,输出以下内容>>
+```md
+__输出文件内容__
+```
+<<输出以上内容>>
+ACTION: 
+<<输出以下内容>>
+## 是否接受将以上总结输出并保存成文件?
+---
+1) 接受
+2) 提出修改
+<<输出以上内容,不得再输出任何其他内容>>
+IF: 用户选择接受
+ACTION: 将最终确认的输出版本保存到./docs/plan/__PLAN_NAME__/plan.md
+ACTION: 
+<<输出以下内容>>
+> ✅文件已保存于./docs/plan/__PLAN_NAME__/plan.md
+<<输出以上内容>>
+ENDIF
+
+IF: 用户没有选择接受
+ACTION: 带着用户的修改提议,回到[MARK:1]重新执行
+ENDIF
+
+输出规则:
+ - __PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+ - plan执行时候请依照execution_steps,一序执行实际的代码修改
+ACTION: 
+<<结合输出规则,输出以下内容>>
+## 接下来
+---
+1) 依照plan计划执行代码修改
+2) 直接描述
+<<输出以上内容,不得再输出任何其他内容>>

package/assets/skills/spec-creator/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: spec-creator
+description: 当用户想要生成某个spec.md
+---
+输出规则:
+ - __PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+ - 若用户选择vision: 执行 assets/vision_gen.md 内容
+ - 若用户选择architecture: 执行 assets/architecture_gen.md 内容
+ - 若用户选择project_architecture: 执行 assets/project_architecture_gen.md 内容
+IF: 你可以通过上下文确定用户想要生成什么文件
+ACTION: 直接执行对应的 xxx_gen.md 内容
+ENDIF
+
+
+ACTION: 
+<<结合输出规则,输出以下内容>>
+## 请选择您想生成的文件
+---
+1) vision
+2) architecture
+3) project_architecture
+<<输出以上内容,不得再输出任何其他内容>>

package/assets/skills/spec-creator/assets/architecture_gen.md

@@ -0,0 +1,242 @@
+#依赖检查
+
+依赖文件清单:
+ - ./docs/global/vision.md
+
+ACTION: 请先检查专案环境下是否存在依赖清单内的所有文档
+IF: 存在缺失文件
+输出规则:
+ - __PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+ - __MISSING_FILE_NAME__ 缺失的文件名
+ - 若有多个缺失文件就多行显示
+ - 若用户选择 开始创建文档: 执行 skill: spec-creator
+ACTION: 
+<<结合输出规则,输出以下内容>>
+## 您需要先创建文档:
+ - __MISSING_FILE_NAME__
+---
+1) 开始创建文档
+<<输出以上内容,不得再输出任何其他内容>>
+ENDIF
+
+ACTION: 阅读所有依赖文件内容来了解专案,并在遵守文件内定义的规范约束下执行后续步骤
+#问题询问
+
+输出规则:
+ - __PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+ - __ADVICE__ 基于[先前的对话内容,所有依赖文件](如过有),结合问题给与建议答案
+可参考的输出格式`
+后端(Next.js): Stripe(订阅支付)
+官网(React): 多语言(自建)
+管理后台(React): 用户权限管理(自建)`记得输出的是多个子专案的组合(若用户目标只需要单一子专案就能实现,那也可以)
+ACTION: 
+<<结合输出规则,输出以下内容>>
+## [1/8] 怎样的子专案技术栈组合能实现你的专案需求?
+---
+1) ✨__ADVICE__
+2) 已部署,直接参考`projects/`内结构
+3) 直接描述
+<<输出以上内容,不得再输出任何其他内容>>
+ACTION: 等待用户回答
+
+输出规则:
+ - __PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+ - 子专案名称需与技术框架一一对应
+ - 技术框架列表在./docs/global/architecture.md里的 #技术框架组合
+ - 输出格式: <技术框架名称> = <子专案名称>
+ - [举例] 后端(Next.js) = api
+ - [举例] 官网(React) = web
+ACTION: 
+<<结合输出规则,输出以下内容>>
+## [2/8] 请为每个子专案定义名称
+---
+1) ✨__ADVICE__
+2) 已部署,直接参考`projects/`内结构
+3) 直接描述
+<<输出以上内容,不得再输出任何其他内容>>
+ACTION: 等待用户回答
+
+输出规则:
+ - __PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+ - __ADVICE__ 基于[先前的对话内容,所有依赖文件](如过有),结合问题给与建议答案
+每个流程发生在哪一端,端的专案名称必须明确
+ACTION: 
+<<结合输出规则,输出以下内容>>
+## [3/8] 关键的端到端链路有哪些?
+ - 可列出多条
+---
+1) ✨__ADVICE__
+2) 直接描述
+<<输出以上内容,不得再输出任何其他内容>>
+ACTION: 等待用户回答
+
+输出规则:
+ - __PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+ - __ADVICE__ 基于[先前的对话内容,所有依赖文件](如过有),结合问题给与建议答案
+ACTION: 
+<<结合输出规则,输出以下内容>>
+## [4/8] 功能新增修改计划的多端执行流程?
+ - [举例]DB → server → web
+---
+1) ✨__ADVICE__
+2) 无
+3) 直接描述
+<<输出以上内容,不得再输出任何其他内容>>
+ACTION: 等待用户回答
+
+输出规则:
+ - __PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+ - __ADVICE__ 可以用上一题的答案的第一个流程完成后
+ACTION: 
+<<结合输出规则,输出以下内容>>
+## [5/8] plan模式执行的最低标准?
+ - [举例]当DB的更改细节确定后
+---
+1) ✨__ADVICE__
+2) 理清更改需求后
+3) 直接描述
+<<输出以上内容,不得再输出任何其他内容>>
+ACTION: 等待用户回答
+
+ACTION: 
+<<输出以下内容>>
+## [6/8] 发布前必须遵循的验证流程?
+ - [举例]staging验证通过 → 端到端测试通过 → 部署到生产环境
+---
+1) 无
+2) 直接描述
+<<输出以上内容,不得再输出任何其他内容>>
+ACTION: 等待用户回答
+
+ACTION: 
+<<输出以下内容>>
+## [7/8] 跨端API有没有统一规范？
+ - [举例]响应格式、错误码、鉴权方式、trace_id 传递规则
+---
+1) 无
+2) 直接描述
+<<输出以上内容,不得再输出任何其他内容>>
+ACTION: 等待用户回答
+
+ACTION: 
+<<输出以下内容>>
+## [8/8] 有没有所有端都明确的禁止事项？
+ - [举例]不能用某类云服务
+---
+1) 无
+2) 直接描述
+<<输出以上内容,不得再输出任何其他内容>>
+ACTION: 等待用户回答
+
+#输出文件
+*仅在以上所有流程完成后才执行
+
+输出格式:Markdown
+语言:中文为主
+输出文件内容规则:
+__PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+__2__ 必须列出子专案的[目录,技术栈,功能性名称]
+<<以下为举例>>
+## axg-web
+- 目录: /projects/axg-web
+- 技术栈: Next.js
+- 描述: 网页前端
+## axg-server
+- 目录: /projects/axg-server
+- 技术栈: NestJS
+- 描述: 后端
+<<以上为举例>>
+__3__ 关键的端到端链路有哪些?
+ - 可列出多条
+__4__ 功能新增修改计划的多端执行流程?
+ - [举例]DB → server → web
+__5__ 发布前必须遵循的验证流程?
+ - [举例]staging验证通过 → 端到端测试通过 → 部署到生产环境
+__6__ 跨端API有没有统一规范？
+ - [举例]响应格式、错误码、鉴权方式、trace_id 传递规则
+__8__ 有没有什么所有端都必须遵守的限制条件？
+ - [举例]只能用现有技术栈、必须符合法规、预算上限
+__9__ 有没有所有端都明确的禁止事项？
+ - [举例]不能用某类云服务
+__10__ 把 plan模式执行的最低标准 这题的答案写进来
+输出文件内容结构:
+<<以下为实际输出文件格式,需结合输出规则生成部分动态内容>>
+#✅要做什么
+#子专案目录
+__2__
+
+#关键链路列表
+__3__
+
+#落地流程
+__4__
+
+#验证流程
+__5__
+
+#跨端API规范
+__6__
+
+#⛔守则
+#限制条件
+__8__
+
+#禁止事项
+__9__
+
+#plan模式自动触发条件
+__10__
+
+<<以上为实际输出文件格式,需结合输出规则生成部分动态内容>>
+
+[MARK:1]
+输出规则:
+ - __PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+ - __输出文件内容__ 显示基于[输出文件内容规则/输出文件内容结构]总结输出文件内容
+ACTION: 
+<<结合输出规则,输出以下内容>>
+```md
+__输出文件内容__
+```
+<<输出以上内容>>
+ACTION: 
+<<输出以下内容>>
+## 是否接受将以上总结输出并保存成文件?
+---
+1) 接受
+2) 提出修改
+<<输出以上内容,不得再输出任何其他内容>>
+IF: 用户选择接受
+ACTION: 将最终确认的输出版本保存到./docs/global/architecture.md
+ACTION: 
+<<输出以下内容>>
+> ✅文件已保存于./docs/global/architecture.md
+<<输出以上内容>>
+ENDIF
+
+IF: 用户没有选择接受
+ACTION: 带着用户的修改提议,回到[MARK:1]重新执行
+ENDIF
+
+IF: projects/下有还没有部署的子专案
+ACTION: 
+<<输出以下内容>>
+## 是否部署目前的技术框架组合?
+---
+1) 好
+2) 跳过
+<<输出以上内容,不得再输出任何其他内容>>
+IF: 用户回答`1 or 好`
+ACTION: 逐一部署技术框架,基于选择的技术框架以专案名称,用其最官方的指令部署到./projects/<子专案名称>,
+ACTION: 将每个子专案的启动指令都加入.vscode/launch.json
+ENDIF
+
+ENDIF
+
+ACTION: 
+<<输出以下内容>>
+## 接下来...
+---
+1) 建立每个子专案的architecture文件
+2) 直接描述
+<<输出以上内容,不得再输出任何其他内容>>

package/assets/skills/spec-creator/assets/project_architecture_gen.md

@@ -0,0 +1,128 @@
+#依赖检查
+
+依赖文件清单:
+ - ./docs/global/vision.md
+ - ./docs/global/architecture.md
+
+ACTION: 请先检查专案环境下是否存在依赖清单内的所有文档
+IF: 存在缺失文件
+输出规则:
+ - __PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+ - __MISSING_FILE_NAME__ 缺失的文件名
+ - 若有多个缺失文件就多行显示
+ - 若用户选择 开始创建文档: 执行 skill: spec-creator
+ACTION: 
+<<结合输出规则,输出以下内容>>
+## 您需要先创建文档:
+ - __MISSING_FILE_NAME__
+---
+1) 开始创建文档
+<<输出以上内容,不得再输出任何其他内容>>
+ENDIF
+
+ACTION: 阅读所有依赖文件内容来了解专案,并在遵守文件内定义的规范约束下执行后续步骤
+ACTION: 基于[所有依赖文件,与用户的对话记录]整理出用户想要实现的功能会改动是什么
+ACTION: 检视./docs/global/architecture.md里#子专案目录,记住[__专案目录__,__专案名称(##标题就是专案名称)__]
+[MARK:2]
+<<以下操作一个子专案都执行一次>>ACTION: 
+<<输出以下内容>>
+## 现在开始建立 __专案名称__ 的architecture文档
+<<输出以上内容>>
+#问题询问
+
+输出规则:
+ - __PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+ - __ADVICE__ 基于[先前的对话内容,所有依赖文件](如过有),结合问题给与建议答案,层级名称请用英文命名,[回答格式范例]([Adapter]对接并隔离外部系统（如支付、Discord 登录等; [Service]承载业务流程与状态规则;[Component]组合逻辑与视图，形成可复用组件单元)
+ACTION: 
+<<结合输出规则,输出以下内容>>
+## [1/3] __专案名称__的分层設計?
+ - 请描述:层级名称&其功能
+---
+1) ✨__ADVICE__
+2) 直接参考`__专案目录__`总结其分层設計,再与我确认
+3) 直接描述
+<<输出以上内容,不得再输出任何其他内容>>
+ACTION: 等待用户回答
+
+输出规则:
+ - __PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+ - __ADVICE__ 基于[先前的对话内容,所有依赖文件](如过有),结合问题给与建议答案,层级名称请用英文命名,[回答格式范例](Adapter 可访问[无]; Service 可访问[Service, Adapter];Component 可访问[ComponentLogic, ComponentView])
+ACTION: 
+<<结合输出规则,输出以下内容>>
+## [2/3] 请定义每一层的可访问层?
+---
+1) ✨__ADVICE__
+2) 直接参考`__专案目录__`总结其分层設計,再与我确认
+3) 直接描述
+<<输出以上内容,不得再输出任何其他内容>>
+ACTION: 等待用户回答
+
+输出规则:
+ - __PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+ - __ADVICE__ 基于[先前的对话内容,所有依赖文件](如过有),结合问题给与建议答案,层级名称请用英文命名,[回答格式范例](Adapter: `__专案目录__/src/adapters/`; Service: `__专案目录__/src/services/`;Component: `__专案目录__/src/components/`)
+ACTION: 
+<<结合输出规则,输出以下内容>>
+## [3/3] 请定义每一层的文件落点?
+---
+1) ✨__ADVICE__
+2) 直接参考`__专案目录__`总结其分层設計,再与我确认
+3) 直接描述
+<<输出以上内容,不得再输出任何其他内容>>
+ACTION: 等待用户回答
+
+#输出文件
+*仅在以上所有流程完成后才执行
+
+输出格式:Markdown
+语言:中文为主
+输出文件内容规则:
+__PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+__1__ 遵循以下范例结构生成
+```yaml
+layer_rules:
+  - from: Adapter
+    allow: []
+    path: projects/axg-global-web/src/adapters/
+    notes: 对接并隔离外部系统（如支付、Discord 登录等），作为统一入口。
+  - from: Service
+    allow: [Service, Adapter]
+    path: projects/axg-global-web/src/services/
+    notes: 承载业务流程与状态规则（订阅、账号、联盟行销）。
+```
+输出文件内容结构:
+<<以下为实际输出文件格式,需结合输出规则生成部分动态内容>>
+#分层结构定义
+__1__
+
+<<以上为实际输出文件格式,需结合输出规则生成部分动态内容>>
+
+[MARK:1]
+输出规则:
+ - __PLACEHOLDER__ 为占位符,请勿输出,而是基于规则输出动态内容
+ - __输出文件内容__ 显示基于[输出文件内容规则/输出文件内容结构]总结输出文件内容
+ACTION: 
+<<结合输出规则,输出以下内容>>
+```md
+__输出文件内容__
+```
+<<输出以上内容>>
+ACTION: 
+<<输出以下内容>>
+## 是否接受将以上总结输出并保存成文件?
+---
+1) 接受
+2) 提出修改
+<<输出以上内容,不得再输出任何其他内容>>
+IF: 用户选择接受
+ACTION: 将最终确认的输出版本保存到./docs/projects/__专案名称__/architecture.md
+ACTION: 
+<<输出以下内容>>
+> ✅文件已保存于./docs/projects/__专案名称__/architecture.md
+<<输出以上内容>>
+ENDIF
+
+IF: 用户没有选择接受
+ACTION: 带着用户的修改提议,回到[MARK:1]重新执行
+ENDIF
+
+<<以上操作一个子专案都执行一次,若还有子专案没执行,回到[MARK:2]重新执行>>