@gong-ym/ai-spec-auto 0.2.3

package/.agents/skills/common/execute-task/evals/train_queries.json

@@ -0,0 +1,18 @@
+[
+  {
+    "query": "按 tasks.md 开始执行第一个任务",
+    "should_trigger": true
+  },
+  {
+    "query": "帮我应用这个 OpenSpec 变更",
+    "should_trigger": true
+  },
+  {
+    "query": "先生成一个提案",
+    "should_trigger": false
+  },
+  {
+    "query": "归档这个 change",
+    "should_trigger": false
+  }
+]

package/.agents/skills/common/execute-task/evals/validation_queries.json

@@ -0,0 +1,18 @@
+[
+  {
+    "query": "从 tasks.md 第一条未完成任务开始写代码",
+    "should_trigger": true
+  },
+  {
+    "query": "/opsx:apply user-manage-redesign",
+    "should_trigger": true
+  },
+  {
+    "query": "分析一下这个设计稿",
+    "should_trigger": false
+  },
+  {
+    "query": "给我做 UI 验收",
+    "should_trigger": false
+  }
+]

package/.agents/skills/common/find-skills/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: find-skills
+description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## Search Checklist
+
+- [ ] Confirm the user is asking for a capability, workflow, or installable help
+- [ ] Extract the domain and the concrete task
+- [ ] Search with specific keywords before suggesting manual reinvention
+
+## Gotchas
+
+- Do not recommend a skill before checking whether it actually matches the user request
+- Do not present installation steps as mandatory if the user only asked what exists
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query]` - Search for skills interactively or by keyword
+- `npx skills add <package>` - Install a skill from GitHub or other sources
+- `npx skills check` - Check for skill updates
+- `npx skills update` - Update all installed skills
+
+**Browse skills at:** https://skills.sh/
+
+## How to Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Search for Skills
+
+Run the find command with a relevant query:
+
+```bash
+npx skills find [query]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+The command will return results like:
+
+```
+Install with npx skills add <owner/repo@skill>
+
+vercel-labs/agent-skills@vercel-react-best-practices
+└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 3: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install command they can run
+3. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "vercel-react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+
+To install it:
+npx skills add vercel-labs/agent-skills@vercel-react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 4: Offer to Install
+
+If the user wants to proceed, you can install the skill for them:
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category        | Example Queries                          |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing         | testing, jest, playwright, e2e           |
+| DevOps          | deploy, docker, kubernetes, ci-cd        |
+| Documentation   | docs, readme, changelog, api-docs        |
+| Code Quality    | review, lint, refactor, best-practices   |
+| Design          | ui, ux, design-system, accessibility     |
+| Productivity    | workflow, automation, git                |
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Suggest the user could create their own skill with `npx skills init`
+
+Example:
+
+```
+I searched for skills related to "xyz" but didn't find any matches.
+I can still help you with this task directly! Would you like me to proceed?
+
+If this is something you do often, you could create your own skill:
+npx skills init my-xyz-skill
+```

package/.agents/skills/common/install-ai-spec-auto/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: install-ai-spec-auto
+description: 当用户要求给当前项目接入 ai-spec-auto(安装工具)、自动执行 init(初始化安装) 命令、安装规则/技能/OpenSpec(需求规范流程) 或完成首次安装时，使用本技能自动检查前置条件、推断 profile(技术栈) 与安装目标，并在当前项目执行安装和自检。
+compatibility: 需要当前工作区可执行 Node.js(运行时) 与 npm(包管理工具) 或 pnpm(包管理工具)，并且能够访问 @ex 内网 registry(包仓库)。前端项目通常包含 package.json；NestJS/Node 后端项目包含 package.json + @nestjs/core；Spring Boot 后端项目包含 pom.xml 或 build.gradle；Node 工具仓通常包含 package.json + tsconfig.json。同一仓库存在多个技术栈子包时（如 Vue + NestJS），在根目录执行一次安装，写入多 profile manifest。
+metadata:
+  version: "1.2.0"
+---
+
+# ai-spec-auto 安装初始化
+
+## 定位
+
+本技能负责把 `ai-spec-auto(安装工具)` 安装到当前项目，并执行首次 `init(初始化安装)`。
+
+职责边界：
+
+- 本技能负责安装前检查、命令执行、安装后自检与结果摘要
+- `project-init(项目规范初始化)` 负责安装完成后的项目规则生成，不负责首次安装
+- `update(更新)`、`check(自检)`、`uninstall(卸载)` 不属于本技能主路径
+
+## 触发条件
+
+当用户表达以下意思时，调用本技能：
+
+- "给当前项目安装 ai-spec-auto"
+- "帮我在这个仓库执行 init"
+- "帮我把这套规范接入当前项目"
+- "自动初始化安装规则和技能"
+- "给别人项目快速装上这套 ai 规范"
+- "在当前项目执行 ai-spec-auto init"
+
+以下场景不要触发：
+
+- 用户明确要执行 `project-init(项目规范初始化)`
+- 用户只想执行 `update(更新)`、`check(自检)` 或 `uninstall(卸载)`
+- 用户想创建一个新的 `skill(技能)`
+- 用户只是问安装文档位置，没有要求执行安装
+
+## 执行原则
+
+- 默认直接执行命令，不先输出长篇安装说明
+- 尽量使用显式参数，避免用户卡在交互式选择
+- 能自动推断的内容就自动推断；只有高风险歧义时才确认
+- 默认启用 `--custom-rules(自定义规则)`，让 `init(初始化安装)` 自动勾选当前支持按项目自定义生成的全部规则
+- 已安装项目优先提醒使用 `check(自检)` 或 `update(更新)`，除非用户明确要求重装
+
+## 安装前核对清单
+
+- [ ] 当前目录或目标目录是要安装的业务项目
+- [ ] 本机可执行 `node(运行时)` 与 `npm(包管理工具)` 或 `pnpm(包管理工具)`
+- [ ] `~/.npmrc` 已配置 `@engineered:registry=https://registry.npmjs.org/`
+- [ ] 已判断当前项目是否已安装，避免误把重复安装当成首次接入
+
+## 自动判断规则
+
+### 1. 是否已安装
+
+以下任一条件成立，都视为项目已经接入过：
+
+- 存在 `.ai-spec/install-state.json`
+- 存在 `.agents/`
+- 存在 `openspec/`
+
+处理方式：
+
+- 已安装且用户没有明确要求重装：优先执行 `check(自检)`，必要时建议 `update(更新)`
+- 已安装且用户明确要求重装：允许继续执行 `init(初始化安装)`，但要先说明会覆盖受管安装产物
+
+### 2. 推断 profile(技术栈)
+
+按下面顺序判断：
+
+1. 已存在 `.ai-spec/manifest.json` 且包含 `profile` / `profiles` 字段 → 直接使用已记录的值
+2. `package.json` 中存在 `vue`、`@vitejs/plugin-vue`、`nuxt` 等依赖 → 命中 `vue`
+3. `package.json` 中存在 `react`、`next`、`@vitejs/plugin-react` 等依赖 → 命中 `react`
+4. `package.json` 中存在 `@nestjs/core`、`@nestjs/common` 等依赖 → 命中 `nestjs`
+5. 存在 `pom.xml` 或 `build.gradle`（且无 `package.json`）→ 命中 `springboot`（待确认）
+6. 存在 `package.json` + 主要依赖为工具链相关（commander、yargs、zod 等），且无 UI/服务端框架 → 命中 `node-tooling`（待确认）
+7. 命中结果处理：
+   - 命中 **1 个** profile 且置信度高 → 直接使用，执行前说明推断结果
+   - 命中 **多个** profile（如 `vue` + `nestjs`）→ 进入"多 profile 确认"流程（见下方）
+   - 命中 **0 个** 或置信度低 → 进入"用户手动选择"流程（见下方）
+
+#### 多 profile 确认（自动命中多个时）
+
+展示推断结果，让用户确认或补充：
+
+```
+检测到以下技术栈：
+  [x] vue      packages/front/
+  [x] nestjs   packages/server/
+
+请确认或修改，然后继续。
+```
+
+#### 用户手动选择（无法自动推断时）
+
+展示多选提示，**允许选择多个**：
+
+```
+请选择当前项目的技术栈（可多选，空格选中，回车确认）：
+
+  [ ] vue          Frontend / Vue
+  [ ] react        Frontend / React
+  [ ] nestjs       Backend / NestJS
+  [ ] springboot   Backend / Spring Boot
+  [ ] node-tooling Tooling / Node.js
+
+> 选择后按回车继续
+```
+
+**不得默认勾选任何项，不得在用户未确认时擅自写入。**
+
+### 3. 判断安装目标
+
+- 当前目录本身就是单技术栈业务包：直接对 `.(当前目录)` 安装
+- 同一仓库包含多个技术栈子包：在**根目录**安装，写多 profile manifest
+- 单包仓库：直接执行 `init .`
+
+### 4. 选择命令入口
+
+单 profile 时，优先使用：
+
+```bash
+npx @engineered/ai-spec-auto@latest init . --profile <profile> --custom-rules
+```
+
+其中 `<profile>` 为 `vue`、`react`、`nestjs`、`springboot` 或 `node-tooling`。
+
+多 profile 时，传入逗号分隔的 profiles：
+
+```bash
+npx @engineered/ai-spec-auto@latest init . --profiles vue,nestjs --custom-rules
+```
+
+仅在"当前工作区就是 `ai-spec-auto(安装工具)` 源码仓库，且用户明确要走本地源码调试安装"时，才改用：
+
+```bash
+node ./bin/cli.js init <target> --profile <profile> --custom-rules
+```
+
+### 5. 自定义规则选择策略
+
+本技能默认把 `--custom-rules(自定义规则)` 作为首次安装命令的一部分。
+
+原因：
+
+- 底层 `install-workflow(安装主链)` 已支持在非交互模式下把全部可自定义规则自动选中
+- 这样安装完成后，`project-init(项目规范初始化)` 会按项目事实补齐和刷新这些规则，而不是沿用固定模板
+- 这符合"自动初始化安装"的目标，不需要用户再手动进入交互界面逐条勾选
+
+各 profile 支持自动全选的规则集由 `profiles.json` 中的 `project_init_rule_ids` 字段决定。
+
+如果用户明确要求"沿用标准模板，不要自定义规则"，才改用 `--standard-rules(标准规则)`，不要同时传两者。
+
+## 标准工作流
+
+Progress:
+- [ ] 1. 读取项目标记文件（`package.json` / `pom.xml` / `build.gradle`）、目录结构、`.npmrc`
+- [ ] 2. 判断是否已安装、是否多 profile 场景、确定或推断 `profile(技术栈)`
+- [ ] 3. 组装并实际执行 `init(初始化安装)` 命令
+- [ ] 4. 安装完成后执行 `check(自检)` 或核对关键安装产物
+- [ ] 5. 输出简短安装摘要，并提示下一步执行 `project-init(项目规范初始化)`
+
+## 详细步骤
+
+### 第一步：环境与仓库检查
+
+至少检查以下事实：
+
+- 项目标记文件是否存在（`package.json` / `pom.xml` / `build.gradle`）
+- `node -v`、`npm -v` 是否可用
+- `~/.npmrc` 是否包含 `@engineered:registry=https://registry.npmjs.org/`
+- 是否已存在 `.ai-spec/install-state.json`、`.agents/`、`openspec/`
+
+如果发现 `registry(包仓库)` 配置缺失：
+
+- 明确告诉用户当前阻塞点
+- 给出准确修复命令
+- 不要假装已经安装成功
+
+### 第二步：构造非交互命令
+
+默认应显式传入 `--profile(技术栈)`，避免安装过程进入交互式选择。
+默认还应显式传入 `--custom-rules(自定义规则)`，让所有支持按项目自定义的规则自动全选。
+
+单 profile 安装命令：
+
+```bash
+npx @engineered/ai-spec-auto@latest init . --profile <profile> --custom-rules
+```
+
+多 profile（同一仓库含多技术栈子包）安装命令：
+
+```bash
+npx @engineered/ai-spec-auto@latest init . --profiles vue,nestjs --custom-rules
+```
+
+如用户提供 `manifest(安装清单)`，命令改为：
+
+```bash
+npx @engineered/ai-spec-auto@latest init . --profile <profile> --custom-rules --manifest <file-or-url>
+```
+
+### 第三步：执行安装
+
+- 真正执行命令，不要只把命令贴给用户
+- 执行前用一句话说明：安装目标、推断出的 `profile(技术栈)` 或多 profile 列表
+- 若项目已安装且用户没有明确要求重装，不要强行再跑 `init(初始化安装)`
+
+### 第四步：安装后验证
+
+优先执行：
+
+```bash
+npx @engineered/ai-spec-auto@latest check .
+```
+
+如果当前环境不适合再次走 `npx(包执行命令)`，至少核对：
+
+- `.agents/`
+- `.ai-spec/install-state.json`
+- `openspec/`（完整安装时）
+- `.cursor/`、`.claude/` 等 `IDE(开发工具)` 入口目录
+
+### 第五步：结果摘要
+
+结果摘要至少包含：
+
+- 安装目标目录
+- 实际执行的命令
+- 判定出的 `profile(技术栈)` 或多 profile 列表
+- 是否首次安装 / 已安装改走 `check(自检)`
+- 验证结果
+- 下一步建议：`project-init(项目规范初始化)` 或"初始化项目规范"
+
+## Gotchas(易错点)
+
+- 不要把 `project-init(项目规范初始化)` 当成首次安装命令
+- 不要忘记追加 `--custom-rules(自定义规则)`，否则非交互模式会回退到标准规则
+- **无法推断 profile 时，不得默认为 `vue`**，必须展示多选提示让用户明确选择
+- 兜底提示必须是**多选**，不能是单选数字列表——用户可能同时需要 vue + nestjs
+- 同一仓库含多技术栈子包时，**在根目录安装**，写多 profile manifest；不要分别进入子包目录各自安装一套 `.agents/`
+- NestJS 项目依据 `@nestjs/core` 依赖识别，**不要把它归为 `node-tooling`**
+- 不要漏掉 `@ex:registry(内网包仓库)` 检查，否则 `npx(包执行命令)` 很可能失败
+- 不要只输出命令，不实际执行
+- 已安装项目如果只需要检查状态，优先走 `check(自检)`，不要机械重复 `init(初始化安装)`
+- Spring Boot 项目不一定存在 `package.json`，不要因为缺少 `package.json` 就直接报错或跳过
+
+## 验证标准
+
+1. 已成功执行 `init(初始化安装)` 或在已安装场景下正确改走 `check(自检)`
+2. 用户能从摘要里看到安装目标、命令、技术栈和验证结果
+3. 输出明确区分"安装完成"与"下一步执行 `project-init(项目规范初始化)`"
+
+## 资源导航
+
+- [README.md](/Users/lizhenwei/workspace/vueworkspace/bairong/br-ai-spec/README.md)
+- [docs/install-guide.md](/Users/lizhenwei/workspace/vueworkspace/bairong/br-ai-spec/docs/install-guide.md)
+- [bin/install-workflow.js](/Users/lizhenwei/workspace/vueworkspace/bairong/br-ai-spec/bin/install-workflow.js)

package/.agents/skills/common/install-ai-spec-auto/evals/evals.json

@@ -0,0 +1,17 @@
+{
+  "skill_name": "install-ai-spec-auto",
+  "evals": [
+    {
+      "id": "install-ai-spec-auto-output-1",
+      "prompt": "在一个尚未接入规范库的 Vue 项目中，自动检查前置条件并执行 ai-spec-auto init 安装，安装完成后给出验证结果和下一步。",
+      "files": [],
+      "expected_output": "输出应覆盖环境检查、registry 配置检查、profile 推断、实际执行 init 命令、安装后验证，以及 project-init 作为下一步建议。",
+      "assertions": [
+        "明确检查 @ex registry 配置",
+        "执行 init 而不是只贴命令",
+        "区分 install 与 project-init",
+        "包含 check 或关键安装产物验证"
+      ]
+    }
+  ]
+}

package/.agents/skills/common/install-ai-spec-auto/evals/train_queries.json

@@ -0,0 +1,18 @@
+[
+  {
+    "query": "给当前项目安装 ai-spec-auto，并直接执行 init",
+    "should_trigger": true
+  },
+  {
+    "query": "帮我把这套规范接入当前 Vue 项目，自动跑安装命令",
+    "should_trigger": true
+  },
+  {
+    "query": "当前项目已经装过了，帮我跑 check 看状态",
+    "should_trigger": false
+  },
+  {
+    "query": "执行 project-init，补 01 和 03",
+    "should_trigger": false
+  }
+]

package/.agents/skills/common/install-ai-spec-auto/evals/validation_queries.json

@@ -0,0 +1,18 @@
+[
+  {
+    "query": "在这个仓库里自动初始化安装 ai-spec-auto，别只给命令，直接执行",
+    "should_trigger": true
+  },
+  {
+    "query": "给别人项目快速装上 rules 和 skills，自动跑 init",
+    "should_trigger": true
+  },
+  {
+    "query": "帮我更新已经安装过的规范库",
+    "should_trigger": false
+  },
+  {
+    "query": "给我新建一个 skill，用来安装项目",
+    "should_trigger": false
+  }
+]

package/.agents/skills/common/project-init/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: project-init
+description: 自动分析当前项目的技术栈、目录结构与实现约定，生成 01-项目概述.md、03-项目结构.md、context/PROJECT.md，并按当前 profile 补生成对应的能力规则。当需要初始化项目规范、生成项目概述、填写项目信息或根据项目生成自定义规则时使用本技能。
+compatibility: 要求当前工作区存在 .agents/rules/ 目录（通过 ai-spec-auto init 安装），以及 .ai-spec/manifest.json 中记录的 profile。前端项目还需要 package.json；后端项目需要 pom.xml / build.gradle；Node 工具仓需要 package.json + tsconfig.json。
+metadata:
+  version: "2.2.0"
+---
+
+# 项目规范初始化
+
+## 触发条件
+
+当用户输入以下类似指令时，调用此技能：
+
+- "初始化项目规范"
+- "初始化项目"
+- "初始化当前项目"
+- "初始化当前项目规范"
+- "生成项目概述"
+- "填写 01 和 03"
+- "分析项目技术栈"
+- "生成项目结构文档"
+- "根据项目生成自定义规则"
+- "生成项目规则"
+- "project-init"
+- "project init"
+
+## 环境依赖
+
+- 依赖本仓库的 `.agents/rules/` 目录结构和可写的 `context/`
+- 若存在 `openspec/`，会同步写入 `openspec/project.md`
+- 若可用，可先运行 `scripts/inspect-project.js` 输出项目事实摘要，再补读关键文件
+
+## 注意事项
+
+- 只要判定需要补生成 profile 对应的能力规则，就不能只写 `01/03`
+- 不能根据猜测编造业务背景，缺失信息只能写已确认事实
+- 自定义规则必须基于项目实际代码、目录和依赖归纳，严禁照搬通用模板
+- `openspec/` 不存在时，只跳过 `openspec/project.md`，不要强制创建 OpenSpec
+
+## 执行核对清单
+
+- [ ] `01-项目概述.md` 已生成或刷新
+- [ ] `03-项目结构.md` 已生成或刷新
+- [ ] `context/PROJECT.md` 已生成或刷新
+- [ ] 待生成/待刷新规则已全部落盘
+
+## 前置要求
+
+1. 当前工作区已通过 `ai-spec-auto init` 安装，存在 `.agents/rules/` 目录。
+2. 存在 `.ai-spec/manifest.json`，其中包含 `profile` 字段，用于确定当前项目类型。
+3. 若 `context/` 目录不存在，可由本技能创建。
+4. 规则生成范围由两类信号共同决定：
+   - `.agents/rules/` 中规则文件是否缺失
+   - `.ai-spec/manifest.json` 中 `local_preferences.project_init.custom_rules` 是否声明了需要按项目自定义生成或刷新的规则
+
+## Profile 驱动的规则生成
+
+### 读取 profiles
+
+1. 读取 `.ai-spec/manifest.json`
+2. 支持两种格式，统一处理为 profile 列表：
+   - `"profile": "vue"` → 列表为 `["vue"]`
+   - `"profiles": ["vue", "nestjs"]` → 列表为 `["vue", "nestjs"]`
+3. 从 `.agents/registry/profiles.json` 中查询每个 profile 的 `project_init_rule_ids`，合并为本次应生成的规则集合
+
+### 各 profile 的默认能力规则集合
+
+| Profile | 应生成的能力规则 |
+|---------|----------------|
+| `vue` | 04-组件规范、05-API规范、06-路由规范、07-状态管理、09-样式规范、11-测试规范、13-代码格式化 |
+| `react` | 04-组件规范、05-API规范、06-路由规范、07-状态管理、09-样式规范、11-测试规范、13-代码格式化 |
+| `springboot` | 04-分层规范、05-接口与契约规范、06-数据访问规范、07-配置与运行时规范、09-异常与日志规范、11-测试规范、13-代码格式化 |
+| `nestjs` | 04-模块结构规范、05-接口与契约规范、06-数据访问规范、07-配置与运行时规范、09-异常与日志规范、11-测试规范、13-代码格式化 |
+| `node-tooling` | 04-CLI与模块规范、05-Contract与Schema规范、06-运行时文件规范、07-日志与错误处理规范、09-脚本与入口规范、11-测试规范、13-代码格式化 |
+
+实际使用的规则集合以 `profiles.json` 中的 `project_init_rule_ids` 为准。
+
+不同 profile 的同序号规则因文件名不同（如 `04-组件规范.md` vs `04-模块结构规范.md`）天然不冲突，直接共存于同一目录。
+
+## 固定产物
+
+本技能的固定目标是：
+
+- 始终生成或刷新（写入 `.agents/rules/`）：
+  - `01-项目概述.md`
+  - `03-项目结构.md`
+  - `context/PROJECT.md`
+- 若项目已安装 OpenSpec（存在 `openspec/`），同步 `openspec/project.md` 中的项目概述
+- 对于安装时选择了"根据项目自定义"的规则，按项目事实生成对应的能力规则文件
+
+## 完成标准（强约束）
+
+以下条件必须同时满足，才算本次 `project-init` 完成：
+
+1. `01-项目概述.md` 已生成或刷新（写入 `.agents/rules/`）
+2. `03-项目结构.md` 已生成或刷新（写入 `.agents/rules/`）
+3. `context/PROJECT.md` 已生成或刷新
+4. 若存在 `openspec/`，则 `openspec/project.md` 已同步
+5. 若能力规则目录中缺失任意应有规则，则这些缺失项必须在本次执行中一并补生成
+6. 若 `local_preferences.project_init.custom_rules` 中包含任意规则，则这些规则即使文件已存在，也必须在本次执行中按项目事实刷新
+
+也就是说：
+
+- **如果待生成列表非空，只写 `01/03 + PROJECT` 视为未完成**
+- **不能在摘要里只说"后续再补能力规则"**
+- **不能只分析、不落盘**
+- **不能只生成其中一部分缺失规则后就结束**
+
+## 资源导航
+
+- `scripts/inspect-project.js`
+  - 何时用：需要先快速汇总技术栈、目录、缺失规则与 OpenSpec 信号时
+  - 用法：`node scripts/inspect-project.js [workspace-root]`
+- `references/scope-resolution.md`
+  - 何时读：确定 `待生成列表 / 待刷新列表 / 本轮写入清单` 时
+- `references/repo-fact-gathering.md`
+  - 何时读：采集项目标记文件、README.md、源码目录时
+- `references/deep-scan-rules.md`
+  - 何时读：只对本轮待生成/刷新规则做深度扫描时
+- `references/output-contracts.md`
+  - 何时读：写 `01/03/PROJECT/openspec/project.md` 前
+- `references/custom-rule-generation.md`
+  - 何时读：补生成能力规则时
+
+## 执行步骤
+
+### 第零步：确定 profiles 与规则生成范围
+
+- 读取 `.ai-spec/manifest.json`，将 `profile`（字符串）或 `profiles`（数组）统一处理为 profile 列表
+- 从 `.agents/registry/profiles.json` 中查询各 profile 的 `project_init_rule_ids`，合并为本次规则集合
+- 按 `references/scope-resolution.md` 确定 `待生成列表`、`待刷新列表` 和 `本轮写入清单`
+- 若有需要，可先运行 `node scripts/inspect-project.js` 看一版摘要
+- 后续所有写入必须严格遵守这份清单
+
+### 第一步：采集基础项目信息
+
+- 根据 profile 类型，采集对应的项目标记文件：
+  - **frontend（vue/react）**：`package.json`、`vite.config.*`、`src/` 目录
+  - **backend（springboot）**：`pom.xml` / `build.gradle`、`src/main/` 目录、`application.yml`
+  - **backend（nestjs）**：`package.json`（含 @nestjs/core）、`src/` 目录、`*.module.ts`、`.env*`
+  - **tooling（node-tooling）**：`package.json`、`tsconfig.json`、`src/` 目录
+  - **多 profile**：按以上规则分别采集各子包的标记文件，01/03/PROJECT.md 需综合描述
+- 只提取稳定事实，不把任务期假设写进项目长期上下文
+- 详细采集项见 `references/repo-fact-gathering.md`
+
+### 第二步：仅对待生成/刷新规则做深度扫描
+
+- 只对 `待生成列表 + 待刷新列表` 对应的能力域做深扫
+- 每个能力域至少读取 2-3 个真实样本，再归纳规则
+- 详细扫描要求见 `references/deep-scan-rules.md`
+
+### 第三步：写入核心产物
+
+生成或刷新（统一写入 `.agents/rules/`）：
+- `01-项目概述.md`（含所有 profile 涉及的技术栈与项目定位）
+- `03-项目结构.md`（覆盖整个项目目录结构）
+- `context/PROJECT.md`
+
+若存在 `openspec/`，同步 `openspec/project.md`。每个产物的写法与边界见 `references/output-contracts.md`
+
+### 第四步：补生成或刷新能力规则
+
+- 仅处理 `待生成列表` 与 `待刷新列表` 中的规则
+- 每条规则必须基于仓库事实生成
+- 规则统一写入 `.agents/rules/`，文件名含领域关键词，不同 profile 的规则因名称不同天然共存
+- 详细覆盖要求见 `references/custom-rule-generation.md`
+
+### 第五步：用户确认并一次性写入
+
+- 真正写入前，按 `references/output-contracts.md` 的确认摘要格式向用户说明：
+  - 当前 profiles 列表
+  - 各技术栈说明
+  - 目录结构
+  - 项目定位
+  - 本轮将补哪些规则
+  - 是否同步 `openspec/project.md`
+- 用户确认后，必须按 `本轮写入清单` 一次性完成全部写入