ai-spec-tool 0.1.2 → 0.1.3

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

@@ -1,122 +1,66 @@
 ---
 name: spec-executor
-description: 执行已进入 processing 状态的 plan，按 execution_steps 读取 module spec 并落实到代码，同时更新 spec/plan 文件后缀
+description: 执行 processing 状态的 plan，按 module-plan 修改代码并更新 module-spec
 ---
 
-# 前置依赖（强制）
-
-## 依赖的规范文件（必须全部存在）
-- docs/global/vision.md
-- docs/global/architecture.md
-- docs/global/naming-rule.md
-
-## 依赖检查流程（不可跳过）
-- 你必须先尝试读取并理解所有依赖文件内容
-- 若任何依赖文件无法读取 / 不存在 / 内容为空：
-- **只能输出以下内容（禁止输出任何其他文字）**
-    > 缺少依赖[<依赖名称>]
-    > 回复「Y」开始创建依赖
-- 下一次 run 必须使用 skill: rules-creator
-- 若所有依赖均存在，才可继续
-
----
-
-# Prompt：Processing Plan → Code Executor
-
-你是「Spec Executor」。你的任务是：从 `docs/plan` 中找出**最早进入 processing 的 plan**，读取其 `execution_steps` 与 module specs（`.update.md`），并**按步骤修改代码**。每完成一个 module 的变更，就把对应 spec 文件从 `.update.md` 改名为 `.md`；当所有模块完成后，把 plan 从 `.processing.md` 改为 `.done.md`。
-
----
-
-## 1) 选择要执行的 plan（强制）
-
-1. 扫描 `./docs/plan/` 下所有 `*.processing.md`
-2. 若不存在：**停止并输出**  
-   > 未发现可执行的 plan（.processing.md）
-3. 若存在多个：
-   - **优先使用文件名 index**（如 `001-xxx.processing.md`）判断最老 → 取最小 index
-   - 若无 index 可用，则以文件修改时间最早者为准
+# 前置依赖检查（统一规则）
+
+## 依赖清单（必须存在且非占位）
+- `docs/plan/*/plan.processing.md`
+- `docs/_shared/conventions.md`
+- `docs/_shared/glossary.md`
+- 若 plan 含 `source_interface`：必须读取 `docs/requirements/<spec-id>.md`
+- `docs/architecture/<project>/architecture.md`
+- `docs/architecture/<project>/layer_rules.yaml`
+- `docs/plan/<plan-id>/projects/<project>/project-plan.md`
+- `docs/plan/<plan-id>/projects/<project>/modules/<module>-plan.md`
+- 若 module 为 UI Component，需额外存在：
+  - `docs/specs/<project>/components/<module>-rules.md`
+  - `docs/architecture/<project>/ui/design-tokens.md`
+  - `docs/architecture/<project>/ui/layout-and-responsive.md`
+  - `docs/architecture/<project>/ui/patterns.md`
+
+## 缺失判定
+文件不存在 / 内容为空 / 首行含 `AI-SPEC-TOOL:PLACEHOLDER`
+
+## 缺失时唯一输出
+<<<
+缺少依赖[<path>]
+
+【下一步】请选择一项：
+1. 开始创建依赖
+请回复：1
+>>>
+用户回复 `1` 后切换 `rules-creator` 生成缺失文件。
 
 ---
 
-## 2) 读取 plan 并建立执行清单（强制）
-
-从选定的 plan 文件中读取：
-- `intent`（理解目标）
-- `modules[]`（知道涉及哪些 module / type）
-- `execution_steps`（执行顺序）
-
-**硬规则：**
-- `execution_steps` 必须为有序列表（1. 2. 3.）
-- **每一步只能提到一个 module**
-- `execution_steps` 必须覆盖 plan 中所有 `modules[]`
-- 若任一规则不满足：**停止并要求补齐 plan**
+# 1) 选择要执行的 plan（强制，流程[1/3]）
+- 优先读取 `docs/plan/index.yaml` 取得 processing plan
+- 若 index 缺失或未记录 processing plan：再扫描 `docs/plan/*/plan.processing.md`
+- 若不存在：输出 `未发现可执行的 plan（plan.processing.md）`
 
 ---
 
-## 3) 定位与校验 module spec（强制）
-
-对每个 `execution_steps` 中提到的 module：
-
-1. 推导 module spec 路径：  
-   `./docs/spec/<module-type>/<module-name>.update.md`
-2. 读取 spec 的 YAML frontmatter，**必须包含**：
-   - `module name`
-   - `module type`
-   - `source plan`
-3. `source plan` 匹配规则：
-   - 去除后缀的 plan 基名要等于`source plan`除后缀的 plan 基名（如 `001-多语言内容管理`）
-4. 若 spec 不存在或 frontmatter 不一致：**停止并要求修正**
+# 2) 执行步骤（强制，流程[2/3]）
+对 `execution_steps` 的每个 `<project>/<module>`：
+1. 将 `<module>-plan.md` → `<module>-plan.processing.md`
+2. 读取对应 `module-plan`
+3. 按约束修改代码
+4. 更新/生成 `docs/specs/<project>/<module>-spec.md`
+   - 必须写入 `last_updated_plan: <plan-id>`
+   - 必须写入 `source_interface: <path>`
+5. 若 module 为 UI Component：
+   - 必须确认 module-plan 内有 UI 规范引用
+   - 必要时更新 `<module>-rules.md`
+6. 将 `<module>-plan.processing.md` → `<module>-plan.done.md`
+
+完成所有模块后：
+- 将 `plan.processing.md` → `plan.done.md`
 
 ---
 
-## 4) 执行代码修改（强制）
-
-按 `execution_steps` 顺序逐一处理 module：
-
-1. 阅读该 module 的 `.update.md` spec（只用于理解职责与边界）
-2. 根据 plan 的 intent + rules + flows + spec 要求修改代码  
-   - **必须遵守 docs/global/architecture.md 的依赖规则与目录落点**
-   - **不得违背 spec 的「不做什么 / 禁止依赖 / 禁止扩充方向」**
-3. 若当前模块属于 UI 显示组件类型（见 `docs/global/ui/module-ui-types.md`）：
-   - 执行前必须读取对应的 Component Rules
-   - 必须遵守 `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`
-
-> 说明：如果模块不存在，需要创建其对应目录与基础结构；若已存在，只修改必要部分。
-
----
-
-## 5) 完成收尾（强制）
-
-当所有 module 都完成并已改名为 `.md`：
-- 将 plan 文件从  
-  `<plan>.processing.md` → `<plan>.done.md`
-
----
-
-## 6) 对话输出（唯一允许的文字输出）
-
-完成后，只允许输出以下结构：
-
-> 已完成 Plan 执行：  
-> `<plan文件名>`（需为可点击超链接）
->
-> 已完成 Module：
-> 1.`<module spec 文件名>`  
-> 2.`<module spec 文件名>`  
-> 3.`<module spec 文件名>`
-
----
-
-## 7) 失败时的输出（强制）
-
-若因缺失文件或规则不满足而停止，只允许输出：
-
-> 无法执行：<原因>
-> 请修正后再执行。
+# 3) 对话输出（唯一允许的文字输出，流程[3/3]）
+- 输出已完成的 plan 路径
+- 输出已完成的 module spec 路径
+- 提示下一步选项：进入 plan

package/assets/AGENTS.md

@@ -1,30 +1,14 @@
-你必须先分析用户在开发专案中的需求类型，并严格分类：
-
-- 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
-
-若意图并非以上,直接回答用户即可
+先判断需求类型，再选择对应 skill（精简路由）：
+
+- 执行 Plan：  
+  - 有 `docs/plan/<plan-id>/plan.processing.md` → `spec-executor`  
+  - 有 `docs/plan/<plan-id>/plan.done.md` → 回复“此 plan 已完成”  
+  - 有 `docs/plan/<plan-id>/plan.md` → `plan-executor`
+- 生成/补齐规则文件 → `rules-creator`
+- 异常修复 → `bugfix`
+- **进入 plan 模式的严格条件**：  
+  - 只有当用户明确说“要 plan/规划/制定计划/产出 Plan”才进入 `plan`  
+  - 用户仅说“要新功能/需求/改动”时，先讨论澄清，不自动进入 `plan`  
+  - 若功能与接口讨论已清晰无疑虑，再**提议**用户是否需要进入 `plan`
+- 若已完成接口/DB 规格讨论，可先生成 Interface 规格书（rules-creator → interface）
+- 其他 → 直接回答

package/assets/docs/_shared/adr/README.md

@@ -0,0 +1,4 @@
+<!-- AI-SPEC-TOOL:PLACEHOLDER -->
+# ADR
+
+架构决策记录存放于此目录。

package/assets/docs/_shared/conventions.md

@@ -0,0 +1,37 @@
+<!-- AI-SPEC-TOOL:PLACEHOLDER -->
+# 通用规范（Conventions）
+
+（由 rules-creator 生成）
+
+## 计划执行流程
+- 生成多个 `project-plan.md` 后：先给出每个 project 的简短摘要，询问是否修改，确认后继续。
+- 生成多个 `<module>-plan.md` 后：先给出每个 module 的简短摘要，询问是否修改，确认后才可进入 spec-executor。
+- 所有多题澄清必须标注进度：`问题[当前/总数]`。
+- 所有关键流程阶段必须标注进度：`流程[当前/总数]`。
+- 优先使用 `docs/plan/index.yaml` 作为计划索引；若不存在再扫描目录。
+- 生成 plan / project-plan / module-plan 后应产出对应 `summary.md` 以降低后续读取成本。
+- summary 文件路径建议：
+  - `docs/plan/<plan-id>/summary.md`
+  - `docs/plan/<plan-id>/projects/<project>/summary.md`
+  - `docs/plan/<plan-id>/projects/<project>/modules/<module>.summary.md`
+- summary 模板参考：
+  - `assets/templates/summary-plan.md`
+  - `assets/templates/summary-project.md`
+  - `assets/templates/summary-module.md`
+- 若存在 Interface 规格书：
+  - 其路径必须写入 `plan.md / project-plan.md / module-plan.md`
+  - 最终写入每个 `module-spec.md` 的 frontmatter
+
+## Interface 规格书
+- 位置：`docs/requirements/<spec-id>.md`
+- 索引：`docs/requirements/index.yaml`
+- 命名：`001-支付流程` 形式
+
+## 规格书优先规则
+- 当接口与 DB 细节讨论已清晰，可先生成 Interface 规格书，再进入 plan。
+
+### 进度标识示例
+- `问题[1/4] 这次变更的目标是什么？`
+- `问题[2/4] 这次的成功标准有哪些？`
+- `流程[1/3] 读取 plan 并建立执行清单`
+- `流程[2/3] 生成 project-plan 与 module-plan`

package/assets/docs/_shared/glossary.md

@@ -0,0 +1,4 @@
+<!-- AI-SPEC-TOOL:PLACEHOLDER -->
+# 术语表（Glossary）
+
+（由 rules-creator 生成）

package/assets/docs/architecture/README.md

@@ -0,0 +1,6 @@
+<!-- AI-SPEC-TOOL:PLACEHOLDER -->
+# Architecture 目录
+
+每个 project 各自维护架构与依赖规则：
+- `docs/architecture/<project>/architecture.md`
+- `docs/architecture/<project>/layer_rules.yaml`

package/assets/docs/plan/README.md

@@ -0,0 +1,11 @@
+<!-- AI-SPEC-TOOL:PLACEHOLDER -->
+# Plan 目录
+
+此目录用于存放每次变更的 Plan：  
+`docs/plan/<plan-id>/plan.md`
+
+索引文件：  
+`docs/plan/index.yaml`
+
+若存在 Interface 规格书：
+`docs/requirements/<spec-id>.md`

package/assets/docs/plan/index.yaml

@@ -0,0 +1,2 @@
+# AI-SPEC-TOOL:PLACEHOLDER
+plans: []

package/assets/docs/plan/summary.md

@@ -0,0 +1,2 @@
+<!-- AI-SPEC-TOOL:PLACEHOLDER -->
+# Plan Summary

package/assets/docs/requirements/README.md

@@ -0,0 +1,5 @@
+<!-- AI-SPEC-TOOL:PLACEHOLDER -->
+# Requirements (Interface Specs)
+
+规格书存放于：  
+`docs/requirements/<spec-id>.md`

package/assets/docs/requirements/index.yaml

@@ -0,0 +1,2 @@
+# AI-SPEC-TOOL:PLACEHOLDER
+requirements: []

package/assets/docs/specs/README.md

@@ -0,0 +1,6 @@
+<!-- AI-SPEC-TOOL:PLACEHOLDER -->
+# Specs 目录
+
+每个 project 的 module spec 与 component rules 将放在：
+- `docs/specs/<project>/<module>-spec.md`
+- `docs/specs/<project>/components/<module>-rules.md`

package/bin/ai-spec-tool.js

@@ -2,10 +2,12 @@
 
 const fs = require("fs");
 const path = require("path");
+const readline = require("readline");
 
 const ASSET_ROOT = path.resolve(__dirname, "..", "assets");
 const TEMPLATE_AGENTS = path.join(ASSET_ROOT, "AGENTS.md");
 const TEMPLATE_AGENTS_DIR = path.join(ASSET_ROOT, ".agents");
+const TEMPLATE_DOCS_DIR = path.join(ASSET_ROOT, "docs");
 
 const START = "<!-- AI-SPEC-TOOL:START -->";
 const END = "<!-- AI-SPEC-TOOL:END -->";
@@ -32,7 +34,7 @@ function nextIncomingPath(destPath) {
   return `${candidate}.${i}`;
 }
 
-function copyFileSafe(srcPath, destPath, report) {
+function copyFileSafe(srcPath, destPath, report, options) {
   if (!fs.existsSync(destPath)) {
     ensureDir(path.dirname(destPath));
     fs.copyFileSync(srcPath, destPath);
@@ -43,12 +45,17 @@ function copyFileSafe(srcPath, destPath, report) {
     report.skipped.push(destPath);
     return;
   }
+  if (options.force) {
+    fs.copyFileSync(srcPath, destPath);
+    report.updated.push(destPath);
+    return;
+  }
   const incoming = nextIncomingPath(destPath);
   fs.copyFileSync(srcPath, incoming);
   report.conflicts.push({ target: destPath, incoming });
 }
 
-function copyDirSafe(srcDir, destDir, report) {
+function copyDirSafe(srcDir, destDir, report, options) {
   ensureDir(destDir);
   const entries = fs.readdirSync(srcDir, { withFileTypes: true });
   entries.forEach((entry) => {
@@ -56,15 +63,42 @@ function copyDirSafe(srcDir, destDir, report) {
     const src = path.join(srcDir, entry.name);
     const dest = path.join(destDir, entry.name);
     if (entry.isDirectory()) {
-      copyDirSafe(src, dest, report);
+      copyDirSafe(src, dest, report, options);
       return;
     }
     if (entry.isFile()) {
-      copyFileSafe(src, dest, report);
+      copyFileSafe(src, dest, report, options);
     }
   });
 }
 
+function askYesNo(prompt) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => {
+      rl.close();
+      const normalized = String(answer || "").trim().toLowerCase();
+      resolve(normalized === "y" || normalized === "yes");
+    });
+  });
+}
+
+async function resolveConflictsInteractively(report, options) {
+  if (!report.conflicts.length || !options.ask) return;
+  if (!process.stdin.isTTY) return;
+
+  for (const conflict of report.conflicts) {
+    const prompt = `Overwrite ${conflict.target} with incoming? (y/N) `;
+    const yes = await askYesNo(prompt);
+    if (yes) {
+      fs.copyFileSync(conflict.incoming, conflict.target);
+      report.updated.push(conflict.target);
+      report.conflictsResolved.push(conflict.target);
+      fs.unlinkSync(conflict.incoming);
+    }
+  }
+}
+
 function updateAgentsMd(targetPath, report) {
   const template = readFile(TEMPLATE_AGENTS).trimEnd();
   const block = `${START}\n${template}\n${END}\n`;
@@ -99,7 +133,7 @@ function updateAgentsMd(targetPath, report) {
   report.updated.push(targetPath);
 }
 
-function init() {
+async function init(options) {
   const cwd = process.cwd();
   const targetAgents = path.join(cwd, "AGENTS.md");
   const targetAgentsDir = path.join(cwd, ".agents");
@@ -108,7 +142,8 @@ function init() {
     added: [],
     updated: [],
     skipped: [],
-    conflicts: []
+    conflicts: [],
+    conflictsResolved: []
   };
 
   if (!fs.existsSync(TEMPLATE_AGENTS) || !fs.existsSync(TEMPLATE_AGENTS_DIR)) {
@@ -116,14 +151,22 @@ function init() {
     process.exit(1);
   }
 
-  copyDirSafe(TEMPLATE_AGENTS_DIR, targetAgentsDir, report);
+  copyDirSafe(TEMPLATE_AGENTS_DIR, targetAgentsDir, report, options);
+  if (fs.existsSync(TEMPLATE_DOCS_DIR)) {
+    const targetDocsDir = path.join(cwd, "docs");
+    copyDirSafe(TEMPLATE_DOCS_DIR, targetDocsDir, report, options);
+  }
   updateAgentsMd(targetAgents, report);
+  await resolveConflictsInteractively(report, options);
 
   console.log("ai-spec-tool init complete.");
   console.log(`Added: ${report.added.length}`);
   console.log(`Updated: ${report.updated.length}`);
   console.log(`Skipped: ${report.skipped.length}`);
   console.log(`Conflicts: ${report.conflicts.length}`);
+  if (report.conflictsResolved.length) {
+    console.log(`Resolved: ${report.conflictsResolved.length}`);
+  }
 
   if (report.conflicts.length) {
     console.log("\nConflicts (new versions saved as .incoming):");
@@ -134,13 +177,20 @@ function init() {
 }
 
 function main() {
-  const [command] = process.argv.slice(2);
+  const [command, ...args] = process.argv.slice(2);
+  const options = {
+    force: args.includes("--force"),
+    ask: args.includes("--ask")
+  };
   if (!command || command === "help" || command === "--help" || command === "-h") {
-    console.log("ai-spec-tool\n\nUsage:\n  ai-spec-tool init\n");
+    console.log("ai-spec-tool\n\nUsage:\n  ai-spec-tool init [--force|--ask]\n");
     return;
   }
   if (command === "init") {
-    init();
+    init(options).catch((err) => {
+      console.error(err?.message || err);
+      process.exit(1);
+    });
     return;
   }
   console.error(`Unknown command: ${command}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-spec-tool",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Installable agents + rules for AI spec workflows",
   "bin": {
     "ai-spec-tool": "bin/ai-spec-tool.js"

package/assets/.agents/skills/rules-creator/assets/naming-rule-gen.md

@@ -1,77 +0,0 @@
-# Naming Rule File Generator (Spec)
-
-## 0) 生成目标（不可变，不询问用户）
-- 输出文件：./docs/global/naming-rule.md
-- 输出格式：Markdown
-- 语言：中文为主
-
----
-
-## 1) 交互入口（优先确认默认方案）
-
-### 1.0 默认方案确认（必须最先执行）
-
-在开始任何详细询问前，**先询问用户一句话**：
-
-> 现在开始创建命名规范\n是否使用默认方案？
-
-并同时简要展示默认方案内容：
-
-- 文件 / 目录：kebab-case
-- 变量 / 函数：camelCase
-- 类 / 构造类型：PascalCase
-- 缩写策略：允许常见缩写（API / URL / DB / ID）
-
-回答「Y」或「N」
-
-#### 用户响应处理规则
-- 若用户回答「Y/y/是 / 使用默认 / OK」：
-  - 直接使用默认推荐值
-  - 跳过所有后续询问
-  - 进入生成流程（第 3 节）
-- 若用户回答「N/n/否 / 自定义 / 调整」：
-  - 进入第 1.1 节，逐项询问
-
----
-
-## 1.1 必问项（仅在用户拒绝默认方案时执行）
-
-请依次询问以下问题，用户只需回复选项编号或关键字：
-
-**Q1. 文件 / 目录命名风格**
-- A) kebab-case（推荐）
-- B) snake_case
-- C) camelCase（不推荐）
-- D) PascalCase（不推荐）
-
-**Q2. 变量 / 函数命名风格**
-- A) camelCase（推荐）
-- B) snake_case
-- C) kebab-case（不推荐）
-
-**Q3. 类 / 构造类型命名风格**
-- A) PascalCase（推荐）
-- B) camelCase
-- C) snake_case
-
-**Q4. 缩写策略（防止风格漂移）**
-- A) 不允许随意缩写（必须写全）
-- B) 允许常见缩写（API / URL / DB / ID）
-
----
-
-## 1.2 用户回答不足时的处理
-- 若只回答部分问题：继续追问未回答项
-- 若回答“随便 / 你定”：使用默认推荐值，并在生成结果中说明
-- 避免开放式问题，始终优先使用选项
-
----
-
-## 2) 默认推荐值（与 1.0 展示内容保持一致）
-- 文件 / 目录：kebab-case
-- 变量 / 函数：camelCase
-- 类 / 构造类型：PascalCase
-- 缩写策略：允许常见缩写（API / URL / DB / ID）
-- 测试文件：*.test.ts / *.spec.ts
-- React 组件：PascalCase.tsx
-- Hook：useXxx