ai-spec-tool 0.1.0 → 0.1.2

package/README.md

@@ -33,3 +33,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/plan/SKILL.md

@@ -23,25 +23,38 @@ description: 用户明确需要一个新的系统、模块或功能体系，或
 
 ## 1) 框架存在性检查（强制）
 
-在进入需求澄清前，必须确认当前项目是否已建立 `docs/global/architecture.md` 中「技术栈选择」指定的主框架。
-默认项目根目录为 `./project`（若不存在则视为尚未建立框架）。
+在进入需求澄清前，必须确认当前项目是否已建立 `docs/global/architecture.md` 中「技术栈选择」指定的框架组合。
+默认项目根目录为 `./projects`（若不存在则视为尚未建立任何框架）。
 
 执行规则：
 - 先读取 `docs/global/architecture.md` 的「技术栈选择」
-- 判断 `./project` 内是否已具备该框架的标准结构/配置
-- 若尚未建立：
-  - 必须先询问用户是否需要你建立框架
-  - 若用户同意：**只能使用该框架的主流标准初始化指令**（例如官方 CLI/脚手架），且必须初始化在 `./project`
+- 根据「技术栈选择」列出的每个框架，判断 `./projects/<框架目录>` 内是否已具备该框架的标准结构/配置
+- 若任一框架尚未建立：
+  - 必须先询问用户是否需要你建立这些缺失框架（可逐个确认）
+  - 若用户同意：**只能使用该框架的主流标准初始化指令**（例如官方 CLI/脚手架），且必须初始化在 `./projects/<框架目录>`
   - **禁止在 `./` 根目录初始化**，也禁止手动逐文件创建
   - 若用户拒绝：停止并等待用户自行处理
- - 若已建立框架：
-   - 检查 `.vscode/launch.json` 是否存在
-   - 若不存在：询问用户是否需要你建立**符合该技术框架**的快速启动方案
-   - **专案根目录为 `./project/`,但`launch.json`是在`.vscode/launch.json` 而不是`.vscode/project/launch.json` 
+- 若已建立框架：
+  - 检查 `.vscode/launch.json` 是否存在
+  - 若不存在：询问用户是否需要你建立**符合该技术框架组合**的快速启动方案
+  - **各框架工程根目录为 `./projects/<框架目录>`，但 `launch.json` 在 `.vscode/launch.json` 而不是 `.vscode/projects/launch.json`**
 
 ---
 
-## 2) 需求澄清阶段（强制）
+## 2) UI 规范参照（强制，条件触发）
+
+当 `docs/global/architecture.md` 的技术栈选择**包含前端技术栈**时，生成 plan 之前必须：
+- 读取并理解：
+  - `docs/global/ui/design-tokens.md`
+  - `docs/global/ui/layout-and-responsive.md`
+  - `docs/global/ui/patterns.md`
+- 若任一文件缺失 / 为空：**停止并要求补齐**（下一次 run 使用 `rules-creator` 走 UI 规范生成）
+- 在 plan 的 `rules.hard` 或相关 UI module 的 `constraints.must` 中**明确写入**：
+  - “所有 UI 交互必须遵守 `docs/global/ui/patterns.md` 的交互模式”
+
+---
+
+## 3) 需求澄清阶段（强制）
 
 ### 2.1 澄清目的（不可偏离）
 

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

@@ -36,7 +36,19 @@ description: 当用户想要执行某个plan
 
 ---
 
-### 1.1 组件使用规范（Component Rules）生成条件（强制）
+### 1.1 UI 规范文件读取（强制）
+
+在执行任何生成之前，若 plan 中存在 UI 显示组件类型模块（见 `./docs/global/ui/module-ui-types.md`），必须先读取并理解：
+- `docs/global/ui/design-tokens.md`
+- `docs/global/ui/layout-and-responsive.md`
+- `docs/global/ui/patterns.md`
+
+规则：
+- 若任一文件缺失 / 为空：**停止并要求补齐**（下一次 run 使用 `rules-creator` 走 UI 规范生成）
+
+---
+
+### 1.2 组件使用规范（Component Rules）生成条件（强制）
 
 在执行任何生成之前，必须先检查：
 `./docs/global/ui/module-ui-types.md` 是否存在且包含「UI 显示组件类型」清单
@@ -50,7 +62,7 @@ description: 当用户想要执行某个plan
 
 ---
 
-### 1.2 争议咨询（强制）
+### 1.3 争议咨询（强制）
 
 在生成任何 Module spec **之前**，你必须先完整阅读 plan，并执行以下流程：
 

package/assets/.agents/skills/rules-creator/assets/architecture-gen.md

@@ -47,14 +47,15 @@
 
 ---
 
-## Q1. 技术栈选择（Primary Framework）
+## Q1. 技术栈选择（Framework Set）
 
-> ⚠️ 本题用于确定本项目的**主框架**，以约束 AI 后续产出一致性。
-> 只允许给出 **1–2 个「单一主框架」**备选；**禁止组合方案**（例如「X + Y」）。
+> ⚠️ 本题用于确定本项目的**框架组合**，以约束 AI 后续产出一致性。
+> 允许选择 **1–3 个框架** 组成组合（例如「前端 + 后端」），
+> **每个条目必须是单一框架**，禁止在同一条目中拼接多个框架（例如「X + Y」）。
 
 ### 系统建议（一次性给出）
 
-基于 `vision.md` 判定交付形态后，系统给出 1–2 个主框架备选，并对每个备选用 **2–4 句**说明：
+基于 `vision.md` 判定交付形态后，系统给出 1–2 组框架组合备选，并对每个备选用 **2–4 句**说明：
 
 * 适合点（为什么匹配目标 / 迭代速度 / 风险）
 * 代价点（会带来什么约束或复杂度）
@@ -62,13 +63,23 @@
 
 输出格式（固定）：
 
-**方案 A：主框架 = <框架名>**
+**方案 A：框架组合**
+
+* 前端：<框架名>（目录：`/projects/<frontend>`）
+* 后端：<框架名>（目录：`/projects/<backend>`）
+* 其他（可选）：<框架名>（目录：`/projects/<other>`）
+* 互通方式：<高层次说明，例如：契约驱动 / API 约定 / 共享协议文件>
 
 * 优点：…
 * 缺点：…
 * 适用边界：…
 
-**方案 B：主框架 = <框架名>（可选）**
+**方案 B：框架组合（可选）**
+
+* 前端：<框架名>（目录：`/projects/<frontend>`）
+* 后端：<框架名>（目录：`/projects/<backend>`）
+* 其他（可选）：<框架名>（目录：`/projects/<other>`）
+* 互通方式：<高层次说明，例如：契约驱动 / API 约定 / 共享协议文件>
 
 * 优点：…
 * 缺点：…
@@ -76,8 +87,8 @@
 
 ### 用户选择（只需回答一个字母）
 
-> 请选择主框架：A / B
-> 或：C) 我自行指定（写：交付形态 + 框架名）
+> 请选择框架组合：A / B
+> 或：C) 我自行指定（写：交付形态 + 框架组合 + 各自目录）
 
 ---
 
@@ -90,7 +101,7 @@
 
 系统需基于以下依据动态生成模块模型：
 
-* Q1 选择的主技术框架
+* Q1 选择的框架组合（按各框架分别给出模块类型建议）
 * `vision.md` 描述的产品目标与复杂度
 * 当前阶段对可维护性与演进速度的需求
 
@@ -153,6 +164,29 @@
 
 1. **目录与落点清单**（每条目录只负责一种职责）
 2. **一句总规则**：所有模块必须落在对应目录，不得跨目录落点
+3. **跨框架互通落点规则**：明确契约/接口/共享协议的落点位置与修改边界
+
+---
+
+## Q4.1 跨项目互通规则（Inter-Project Rules）
+
+> ⚠️ 本题用于明确 `/projects` 下多个工程之间的协作边界与互通方式，
+> 以避免实现时出现重复定义、协议不一致或跨工程越界修改。
+
+### Step 1：系统生成草案（必须）
+
+系统需提供：
+
+1. **互通方式清单**：每一组 project 之间如何互通（API / 契约 / 共享协议等）
+2. **契约落点位置**：协议或接口定义文件放在哪里（例如 `/projects/<frontend>/...` 或 `/projects/<backend>/...` 或共享目录）
+3. **修改边界**：哪些工程可修改、哪些只能读取
+4. **版本与兼容**（若适用）：协议变更时的兼容策略
+
+### Step 2：用户确认
+
+> 对这份「跨项目互通规则」：
+> A) 接受
+> B) 修改（请直接改）
 
 ---
 
@@ -198,6 +232,7 @@
 layer_rules: ...
 ```
 ## 目录与落点规则
+## 跨项目互通规则
 ## 禁止事项
 ```
 
@@ -207,7 +242,7 @@ layer_rules: ...
 
 在完成 `architecture.md` 生成后：
 
-1. 判断「技术栈选择」是否为**前端技术栈**
+1. 判断「技术栈选择」是否**包含前端技术栈**
 2. 若是前端：
    - 必须询问用户是否要继续执行 `ui-architecture-gen.md`
    - 若用户同意：继续进入 UI 规范生成流程

package/assets/.agents/skills/rules-creator/assets/ui-template-gen.md

@@ -10,10 +10,10 @@
 ## 2) 执行前置条件（强制）
 
 执行前**必须确认**：
-* `/project` 目录存在
-* `./docs/global/architecture.md` 已明确技术框架且已完成基础工程初始化
+* `/projects` 目录存在
+* `./docs/global/architecture.md` 已明确前端技术框架与对应目录，且已完成基础工程初始化
 * 已基于 `./docs/global/ui/` 生成可被页面直接使用的视觉定义
-  - 固定输出：`./src/styles/ui-tokens.css`（CSS 变量）
+  - 固定输出：`/projects/<frontend>/src/styles/ui-tokens.css`（CSS 变量）
 
 若任一条件不满足：**停止并要求补齐**。
 
@@ -31,21 +31,21 @@
 ## 4) 可渲染界面输出（强制）
 
 若 `architecture.md` 指定为网页前端框架（如 Next.js），**必须额外生成一个可直接渲染的范例界面页面**：
-* 使用当前技术框架的默认页面结构与目录（例如 Next.js App Router：`./src/app/example-screen/page.tsx`）
+* 使用当前技术框架的默认页面结构与目录（例如 Next.js App Router：`/projects/<frontend>/src/app/example-screen/page.tsx`）
 * 页面内容与样式必须严格引用 UI 规范（design-tokens / layout-and-responsive / patterns）
 * 仅展示范例界面，不引入业务逻辑
 * **单文件产出**：不得拆分或创建任何额外的组件文件（如 `src/components`）
 * 除 UI 规范定义文件外，不得依赖任何外部组件或资源
-* **必须显式引入并使用** `./src/styles/ui-tokens.css`
+* **必须显式引入并使用** `/projects/<frontend>/src/styles/ui-tokens.css`
 * 页面中所有颜色/字体/间距/圆角/阴影/动效 **必须使用 tokens 变量**，不得出现未定义的硬编码值
 * 必须在页面中体现响应式断点变化（至少覆盖 XS/S 与 L/XL 的差异）
 * 必须展示交互状态的可视差异（hover / active / disabled / focus），且在页面中可直接观察
 * **禁止使用内联样式**（如 `style={{ ... }}`），必须通过类名与样式规则实现
-* `./src/styles/ui-tokens.css` 必须采用 **两层结构**：
+* `/projects/<frontend>/src/styles/ui-tokens.css` 必须采用 **两层结构**：
   - Base Tokens：仅定义原子数值（颜色刻度/字号/间距/圆角/阴影/动效）
   - Semantic Tokens：将 Base Tokens 映射到语义（文字/背景/边框/交互/反馈）
 * 页面样式**优先使用语义层 tokens**，仅在必要时使用 Base Tokens
-* `./src/styles/ui-tokens.css` 必须使用 `:root {}` 包裹，并按以下分区注释顺序输出：
+* `/projects/<frontend>/src/styles/ui-tokens.css` 必须使用 `:root {}` 包裹，并按以下分区注释顺序输出：
   - `/* Base Tokens - Colors */`
   - `/* Base Tokens - Typography */`
   - `/* Base Tokens - Spacing */`
@@ -57,7 +57,7 @@
   - `/* Semantic Tokens - Border */`
   - `/* Semantic Tokens - Interactive */`
   - `/* Semantic Tokens - Feedback */`
-* 若框架尚未初始化或目录不存在：**停止并要求先完成工程初始化**
+* 若框架尚未初始化或前端目录不存在：**停止并要求先完成工程初始化**
 * 范例界面页面内需包含以下说明区块（可以是页面中的说明模块）：
   - 页面定位（页面类型、主要场景）
   - 整体结构（Header / Main / Footer 与 Main 分区）
@@ -97,13 +97,13 @@
 * 页面文件不得包含：
   - 内联样式（`style=`）
   - 任何 `rgba(...)` / `rgb(...)` / 十六进制颜色（`#fff` 等）
-* 除 `./src/styles/ui-tokens.css` 外，其它样式文件不得包含硬编码颜色值
+* 除 `/projects/<frontend>/src/styles/ui-tokens.css` 外，其它样式文件不得包含硬编码颜色值
 * 页面文件所有颜色/字体/间距/圆角/阴影/动效必须来自 tokens（`var(--*)` 或对应语义类）
 
 建议检查命令（可直接使用 `rg`）：
-* `rg -n "style=" ./src/app/example-screen/page.tsx`
-* `rg -n "rgba\\(|rgb\\(|#[0-9a-fA-F]{3,8}" ./src/app/example-screen/page.tsx`
-* `rg -n "rgba\\(|rgb\\(|#[0-9a-fA-F]{3,8}" ./src/app -g \"*.css\" -g \"!ui-tokens.css\"`
+* `rg -n "style=" /projects/<frontend>/src/app/example-screen/page.tsx`
+* `rg -n "rgba\\(|rgb\\(|#[0-9a-fA-F]{3,8}" /projects/<frontend>/src/app/example-screen/page.tsx`
+* `rg -n "rgba\\(|rgb\\(|#[0-9a-fA-F]{3,8}" /projects/<frontend>/src/app -g \"*.css\" -g \"!ui-tokens.css\"`
 
 ---
 
@@ -112,9 +112,9 @@
 在生成范例界面后，**必须基于当前环境给出查看方式**，并进入调整阶段：
 
 1. 告知用户如何启动与访问页面（必须给出具体命令与访问地址）  
-   - 以当前工程为准：`/project` 为 Next.js 项目  
+   - 以当前工程为准：`/projects/<frontend>` 为前端项目  
    - 示例指令：  
-     - `cd /project`  
+     - `cd /projects/<frontend>`  
      - `npm run dev`  
    - 示例地址：`http://localhost:3000/example-screen`
 

package/assets/.agents/skills/spec-executor/SKILL.md

@@ -82,6 +82,8 @@ description: 执行已进入 processing 状态的 plan，按 execution_steps 读
    - 必须遵守 `docs/global/ui/design-tokens.md`、`layout-and-responsive.md`、`patterns.md` 的约束
    - 若缺失任一 UI 规范文件：**停止并要求补齐**
    - 若存在 `docs/global/ui/accessibility.md`：**应遵守其约束**（可选）
+   - **必须逐条对照 `docs/global/ui/patterns.md` 的「交互模式」并落实到实现**
+     - 若 Component Rules 未覆盖或与 patterns 冲突：**停止并要求先补齐 Component Rules / patterns**
 4. 每完成一个 module 的代码改动：
    - 将该 module spec 文件从  
      `<module-name>.update.md` → `<module-name>.md`

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "ai-spec-tool",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Installable agents + rules for AI spec workflows",
   "bin": {
     "ai-spec-tool": "bin/ai-spec-tool.js"
   },
+  "scripts": {
+    "version:patch": "node ./scripts/release.js patch",
+    "version:minor": "node ./scripts/release.js minor",
+    "version:major": "node ./scripts/release.js major"
+  },
   "files": [
     "bin",
     "assets",