@betterdanlins/ai-memory 0.1.0

package/README.md

@@ -0,0 +1,26 @@
+# @betterdanlins/ai-memory
+
+AI 记忆 + 需求工作流脚手架:一条命令在项目里生成跨 Claude Code / Codex 的
+记忆层(.ai/memory)、方法论层(.ai/skills)、需求版本目录(docs/requirements)
+与两侧薄适配层。
+
+## 用法
+
+```bash
+npx @betterdanlins/ai-memory init
+# 非交互:
+npx @betterdanlins/ai-memory init --name demo --stack "PHP + Vue" --tools claude,codex --yes
+# 从已有项目导入用户级记忆:
+npx @betterdanlins/ai-memory init --import /path/to/other-project
+```
+
+`--import` 从已有项目导入 user-profile/feedback;目标文件已存在时按冲突策略处理(--yes 下跳过,交互下询问),绝不静默覆盖。
+
+## 设计
+
+- 单一源:所有正文只在 `.ai/`,`.claude/`、`.agents/` 只是触发包装
+- 节点式记忆:完成任务节点立即写 session-log,跨工具切换不断档
+- 需求双目录:人工粗稿 `draft/` → AI 定稿 `final/`(强制 critic 门)
+- 幂等:已存在的文件逐个询问,绝不静默覆盖(`--yes` 一律跳过)
+
+设计文档:`docs/superpowers/specs/2026-07-05-ai-memory-framework-design.md`

package/bin/cli.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { scaffold } from '../src/scaffold.js';
+
+const TEMPLATES = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'templates');
+const program = new Command();
+
+program.name('ai-memory').description('AI memory + requirements workflow scaffolder');
+
+program
+  .command('init')
+  .description('在当前目录生成 ai-memory 框架')
+  .option('--name <name>', '项目名')
+  .option('--stack <desc>', '技术栈描述')
+  .option('--tools <list>', '启用工具,逗号分隔:claude,codex')
+  .option('--import <path>', '从已有项目导入 user-profile/feedback')
+  .option('--yes', '非交互模式:缺参用默认值,冲突一律跳过')
+  .action(async (opts) => {
+    const targetDir = process.cwd();
+    let { name, stack, tools: toolsRaw } = opts;
+
+    // Validate CLI-supplied --tools before entering interactive prompts
+    if (toolsRaw !== undefined) {
+      for (const t of toolsRaw.split(',').map(s => s.trim()).filter(Boolean)) {
+        if (t !== 'claude' && t !== 'codex') {
+          console.error(`tools 仅支持 claude、codex,收到: ${t}`);
+          process.exit(1);
+        }
+      }
+    }
+
+    let importFrom = opts.import;
+    if (!opts.yes) {
+      const { input, checkbox } = await import('@inquirer/prompts');
+      name ??= await input({ message: '项目名:', default: path.basename(targetDir) });
+      stack ??= await input({ message: '技术栈描述:', default: '(待补充)' });
+      toolsRaw ??= (await checkbox({
+        message: '启用哪些工具适配:',
+        choices: [
+          { name: 'Claude Code', value: 'claude', checked: true },
+          { name: 'Codex', value: 'codex', checked: true },
+        ],
+      })).join(',');
+      importFrom ??= (await input({
+        message: '从已有项目导入 user-profile/feedback?(输入项目路径,留空跳过)', default: '',
+      })) || undefined;
+    }
+    name ??= path.basename(targetDir);
+    stack ??= '(待补充)';
+    toolsRaw ??= 'claude,codex';
+
+    const tools = toolsRaw.split(',').map(s => s.trim()).filter(Boolean);
+    if (tools.length === 0) {
+      console.log('未启用任何工具适配,仅生成 .ai/ 通用层');
+    }
+
+    const onConflict = opts.yes
+      ? () => 'skip'
+      : async (dest) => {
+          const { confirm } = await import('@inquirer/prompts');
+          return (await confirm({ message: `${dest} 已存在,覆盖?`, default: false })) ? 'overwrite' : 'skip';
+        };
+
+    const vars = { projectName: name, techStack: stack, date: new Date().toISOString().slice(0, 10) };
+    const r = await scaffold({ templatesRoot: TEMPLATES, targetDir, vars, tools, onConflict, importFrom });
+    console.log(`完成:写入 ${r.written.length},跳过 ${r.skipped.length}`);
+    if (r.skipped.length) for (const d of r.skipped) console.log(`  跳过 ${d}`);
+    console.log('下一步:打开项目让 agent 读 .ai/memory/MEMORY.md;把项目命令补进 CLAUDE.md/AGENTS.md。');
+  });
+
+program.parseAsync().catch((e) => {
+  if (e.name === 'ExitPromptError') {
+    console.log('已取消');
+  } else {
+    console.error('错误: ' + e.message);
+  }
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@betterdanlins/ai-memory",
+  "version": "0.1.0",
+  "description": "AI memory + requirements workflow scaffolder for Claude Code & Codex",
+  "type": "module",
+  "bin": {
+    "ai-memory": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=20.17.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "license": "MIT",
+  "author": "Betterdan",
+  "keywords": ["ai", "memory", "claude-code", "codex", "scaffold", "cli"],
+  "repository": {"type": "git", "url": "git+https://github.com/Betterdan/ai-memory.git"},
+  "publishConfig": {"access": "public"},
+  "dependencies": {
+    "@inquirer/prompts": "^8.5.2",
+    "commander": "^13.1.0"
+  }
+}

package/src/manifest.js

@@ -0,0 +1,37 @@
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+
+const GROUPS = {
+  common: () => true,
+  claude: (tools) => tools.includes('claude'),
+  codex: (tools) => tools.includes('codex'),
+};
+
+export async function buildManifest(templatesRoot, tools) {
+  const entries = [];
+  for (const [group, enabled] of Object.entries(GROUPS)) {
+    if (!enabled(tools)) continue;
+    const groupDir = path.join(templatesRoot, group);
+    for (const rel of await walk(groupDir, '')) {
+      entries.push({ src: path.join(groupDir, ...rel.split('/')), dest: rel });
+    }
+  }
+  return entries.sort((a, b) => a.dest < b.dest ? -1 : a.dest > b.dest ? 1 : 0);
+}
+
+async function walk(dir, prefix) {
+  let dirents;
+  try {
+    dirents = await readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+  const out = [];
+  for (const d of dirents) {
+    const rel = prefix ? `${prefix}/${d.name}` : d.name;
+    if (d.isDirectory()) out.push(...(await walk(path.join(dir, d.name), rel)));
+    else out.push(rel);
+  }
+  return out;
+}

package/src/render.js

@@ -0,0 +1,6 @@
+export function render(content, vars) {
+  return content.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+    if (!(key in vars)) throw new Error(`未定义的模板变量: ${key}`);
+    return vars[key];
+  });
+}

package/src/scaffold.js

@@ -0,0 +1,33 @@
+import { mkdir, readFile, writeFile, access } from 'node:fs/promises';
+import path from 'node:path';
+import { buildManifest } from './manifest.js';
+import { render } from './render.js';
+
+const IMPORT_DESTS = new Set(['.ai/memory/user-profile.md', '.ai/memory/feedback.md']);
+
+export async function scaffold({ templatesRoot, targetDir, vars, tools, onConflict, importFrom }) {
+  const manifest = await buildManifest(templatesRoot, tools);
+  const summary = { written: [], skipped: [] };
+  for (const { src, dest } of manifest) {
+    const destPath = path.join(targetDir, ...dest.split('/'));
+    if (await exists(destPath)) {
+      if ((await onConflict(dest)) !== 'overwrite') { summary.skipped.push(dest); continue; }
+    }
+    let content;
+    if (importFrom && IMPORT_DESTS.has(dest)) {
+      const importSrc = path.join(importFrom, '.ai', 'memory', path.basename(dest));
+      if (await exists(importSrc)) {
+        content = await readFile(importSrc, 'utf8');
+      }
+    }
+    if (content === undefined) {
+      content = render(await readFile(src, 'utf8'), vars);
+    }
+    await mkdir(path.dirname(destPath), { recursive: true });
+    await writeFile(destPath, content);
+    summary.written.push(dest);
+  }
+  return summary;
+}
+
+const exists = (p) => access(p).then(() => true, () => false);

package/templates/claude/.claude/agents/critic.md

@@ -0,0 +1,8 @@
+---
+name: critic
+description: 对需求定稿/架构设计/实现方案做对抗性检查。传入文档路径,不要传对话历史。
+tools: Read, Grep, Glob
+---
+
+你是对抗性审查者。读取指定文档与 `.ai/skills/critic.md`,按四类清单(假设攻击/契约漏洞/过度设计/遗漏场景)攻击该文档。
+只输出质疑列表:每条 `[high|medium|low] 质疑 + 触发条件`。不提供修复方案,不表扬,不复述文档。

package/templates/claude/.claude/commands/critic.md

@@ -0,0 +1,6 @@
+---
+description: 对指定文档做对抗性检查
+argument-hint: <文档路径>
+---
+
+派发 critic subagent 检查 $ARGUMENTS:只给文档路径与 `.ai/skills/critic.md`,不携带对话历史。返回后逐条回应「接受并修改」或「有理由反驳」,不允许沉默跳过。

package/templates/claude/.claude/commands/finalize-requirement.md

@@ -0,0 +1,7 @@
+---
+description: 将 draft 需求定稿为 final(含强制 critic 门)
+argument-hint: <需求名>
+---
+
+按 `.ai/skills/requirements-flow.md` 的「定稿」章节执行,需求名:$ARGUMENTS。
+critic 门必须由 critic subagent 独立上下文执行,逐条回应后才写 final/。

package/templates/claude/.claude/commands/new-requirement.md

@@ -0,0 +1,6 @@
+---
+description: 新建需求 draft 骨架并在 project-state 登记
+argument-hint: <需求名> [版本,默认当前迭代]
+---
+
+按 `.ai/skills/requirements-flow.md` 的「新建」章节执行。需求名与版本:$ARGUMENTS

package/templates/claude/.claude/commands/update-memory.md

@@ -0,0 +1,8 @@
+---
+description: 主动总结当前进展并按路由写入 .ai/memory/
+---
+
+按 `.ai/skills/memory-update.md` 执行:
+1. 读 `.ai/memory/MEMORY.md` 与 `session-log.md`
+2. 追加本次节点条目(时间戳 + 做了什么 + 关键决策 + 下一步)
+3. 需求/里程碑状态有变则更新 `project-state.md` 对应表格行

package/templates/claude/.claude/settings.json

@@ -0,0 +1,24 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo '[ai-memory] 会话收尾:请确认本次进展已按节点式协议写入 .ai/memory/session-log.md'"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo '[ai-memory] 上下文即将压缩:请先把关键进展写入 .ai/memory/session-log.md'"
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/claude/.claude/skills/critic/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: critic
+description: Use when 需要对需求定稿、架构设计或实现方案做对抗性检查/反驳/挑毛病
+---
+
+派发 critic subagent(独立上下文,只给文档路径与 `.ai/skills/critic.md`,不给对话历史),随后按其纪律逐条回应质疑。

package/templates/claude/.claude/skills/memory-update/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: memory-update
+description: Use when 完成一个任务节点、做出关键决策、会话收尾,或用户要求更新记忆/总结进展
+---
+
+读取并严格遵循 `.ai/skills/memory-update.md` 的写入路由与硬性约束执行。

package/templates/claude/.claude/skills/requirements-flow/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: requirements-flow
+description: Use when 用户要新建需求、定稿需求、把 draft 转 final,或提到「需求文档/定稿/finalize」
+---
+
+读取并严格遵循 `.ai/skills/requirements-flow.md` 执行,不要凭记忆复述流程。

package/templates/claude/CLAUDE.md

@@ -0,0 +1,19 @@
+# {{projectName}}
+
+## AI 协作框架(ai-memory)
+
+进场先读 `.ai/memory/MEMORY.md`,随后遵循 `.ai/README.md` 的进场协议。
+
+- 需求文档工作(新建/定稿)→ requirements-flow skill,产物在 `docs/requirements/vX.Y.Z/{draft,final}/`
+- 记忆更新 → 节点式(完成任务节点立即写),协议见 `.ai/skills/memory-update.md`;手动 /update-memory
+- 反驳检查 → /critic 或定稿流程内强制触发;必须派 critic subagent 独立上下文执行
+
+## 与 superpowers 的编排(未安装则忽略本节)
+
+1. 需求定稿(what/why)走 requirements-flow;实现设计(how)走 brainstorming,以 `docs/requirements/*/final/*.md` 为输入
+2. code review 走 superpowers 流程,叠加 `.ai/skills/code-review.md` 的项目检查项
+
+## 项目信息
+
+- 技术栈:{{techStack}}
+<!-- 在此补充启动/测试/构建命令 -->

package/templates/codex/.agents/skills/critic/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: critic
+description: Use when 需要对需求定稿、架构设计或实现方案做对抗性检查/反驳/挑毛病
+---
+
+读取 `.ai/skills/critic.md`,按四类清单攻击目标文档;输出带严重度的质疑列表后,逐条回应「接受并修改」或「有理由反驳」。刻意抵制为自己刚写内容辩护的倾向。

package/templates/codex/.agents/skills/memory-update/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: memory-update
+description: Use when 完成一个任务节点、做出关键决策、会话收尾,或用户要求更新记忆/总结进展
+---
+
+读取并严格遵循 `.ai/skills/memory-update.md` 的写入路由与硬性约束执行。

package/templates/codex/.agents/skills/requirements-flow/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: requirements-flow
+description: Use when 用户要新建需求、定稿需求、把 draft 转 final,或提到「需求文档/定稿/finalize」
+---
+
+读取并严格遵循 `.ai/skills/requirements-flow.md` 执行,不要凭记忆复述流程。
+critic 门在 Codex 侧为同上下文自检:严格按 `.ai/skills/critic.md` 的四类清单与纪律执行。

package/templates/codex/AGENTS.md

@@ -0,0 +1,19 @@
+# {{projectName}}
+
+## AI 协作框架(ai-memory)
+
+进场先读 `.ai/memory/MEMORY.md`,随后遵循 `.ai/README.md` 的进场协议。
+
+- 需求文档工作(新建/定稿)→ requirements-flow skill,产物在 `docs/requirements/vX.Y.Z/{draft,final}/`
+- 记忆更新 → 节点式(完成任务节点立即写),协议见 `.ai/skills/memory-update.md`
+- 反驳检查 → critic skill 或定稿流程内强制触发;同上下文自检,刻意抵制自我辩护(见 `.ai/skills/critic.md` 纪律)
+
+## 与 superpowers 的编排(未安装则忽略本节)
+
+1. 需求定稿(what/why)走 requirements-flow;实现设计(how)走 brainstorming,以 `docs/requirements/*/final/*.md` 为输入
+2. code review 走 superpowers 流程,叠加 `.ai/skills/code-review.md` 的项目检查项
+
+## 项目信息
+
+- 技术栈:{{techStack}}
+<!-- 在此补充启动/测试/构建命令 -->

package/templates/common/.ai/README.md

@@ -0,0 +1,20 @@
+# .ai/ — 跨 Agent 知识框架({{projectName}})
+
+本目录是 agent-agnostic 的项目知识库,Claude Code、Codex 等所有 AI 工具共享同一份内容。
+由 @betterdanlins/ai-memory 生成于 {{date}}。
+
+## 进场协议(每次会话开始)
+
+1. 读 `memory/MEMORY.md`(记忆索引)
+2. 读 `memory/session-log.md` 末尾条目(接上进度)
+3. 按任务类型按需加载 `skills/` 对应方法论
+
+## 目录
+
+- `memory/` — 记忆层:MEMORY.md 索引、project-state 全景、session-log 流水、user-profile/feedback 用户级记忆、features/ 功能档案
+- `skills/` — 方法论层:requirements-flow、architecture、code-review、critic、memory-update
+
+## 与工具专属配置的关系
+
+CLAUDE.md、AGENTS.md 只是薄入口;`.claude/skills/`、`.agents/skills/` 只是触发包装。
+**正文永远只有本目录一份**,修改方法论只改这里,适配层不需要动。

package/templates/common/.ai/memory/MEMORY.md

@@ -0,0 +1,9 @@
+# 记忆索引
+
+> agent 进场先读本文件,再按需加载指向的文件。一行一条;新增记忆文件必须在此登记。
+
+- [项目状态](project-state.md) — 技术栈、当前版本、需求进度、遗留问题
+- [Session 日志](session-log.md) — 最新进展、下一步、未落盘决策
+- [用户画像](user-profile.md) — 背景、偏好、沟通方式
+- [协作规范](feedback.md) — 历史反馈提炼的行为规范
+<!-- features/ 功能档案在下方逐行登记 -->

package/templates/common/.ai/memory/feedback.md

@@ -0,0 +1,6 @@
+# 协作规范
+
+> 从历史协作反馈中提炼的行为规范,用户级记忆,跨项目可复用。
+> 每条写清:规范 + 为什么 + 如何应用。
+
+(暂无条目)

package/templates/common/.ai/memory/project-state.md

@@ -0,0 +1,23 @@
+# 项目状态
+
+> 最后更新:{{date}}
+> 低频全景文件:只在需求/里程碑状态变化时更新对应行,不写流水。
+
+## 基本信息
+
+- 项目:{{projectName}}
+- 技术栈:{{techStack}}
+- 当前迭代:v1.0.0
+
+## 需求进度
+
+| 版本 | 需求 | 状态(draft/finalized/in-progress/done) | 备注 |
+|---|---|---|---|
+
+## 已知遗留问题
+
+(无)
+
+## 归档的 session 摘要
+
+(session-log 超长时压缩至此)

package/templates/common/.ai/memory/session-log.md

@@ -0,0 +1,15 @@
+# Session 日志
+
+> 高频追加文件:每完成一个任务节点/关键决策,带时间戳追加一条;只增不改。
+> 超过约 200 行时,把旧条目压缩进 project-state.md 的「归档的 session 摘要」。
+> 跨工具(Claude Code ↔ Codex)切换前,必须确认本文件已落盘并 commit。
+
+## 条目格式
+
+### YYYY-MM-DD HH:mm — <节点标题>
+
+- 做了什么:
+- 关键决策:
+- 下一步:
+
+---

package/templates/common/.ai/memory/user-profile.md

@@ -0,0 +1,13 @@
+# 用户画像
+
+> 用户级记忆,跨项目可复用(init 时可从已有项目导入)。
+
+## 背景与角色
+
+(技术背景、当前角色)
+
+## 偏好
+
+- 沟通语言:
+- 回复风格:
+- 技术偏好:

package/templates/common/.ai/skills/architecture.md

@@ -0,0 +1,22 @@
+# 架构方法论(语言无关)
+
+## 模块边界
+
+- 每个模块用一句话说清职责;说不清 = 边界有问题
+- 模块间只通过显式接口通信;不看内部实现也能正确使用
+- 依赖单向:上层可依赖下层,禁止反向依赖与循环依赖
+
+## 接口契约格式(定稿时写入 final/*.md 的「接口契约」章节)
+
+每个接口写清:
+
+- **名称与语义**:做什么,明确不做什么
+- **输入**:参数、类型、边界值约定
+- **输出**:返回结构、错误路径(每种失败如何表达给调用方)
+- **幂等/并发**:重复调用的后果,是否需要去重或加锁
+- **兼容**:后续变更如何不破坏既有调用方
+
+## 跨技术栈落地
+
+本文件只写原则。具体项目的模块清单、依赖层级、数据规范写在
+`.ai/memory/project-state.md` 或 `features/` 对应档案里,由 agent 按本原则裁剪到当前技术栈。

package/templates/common/.ai/skills/code-review.md

@@ -0,0 +1,9 @@
+# Review 检查项(项目专属)
+
+> 不注册为 skill;供 superpowers 的 code review 流程作为附加检查项引用。
+
+- **契约一致**:实现与 `final/*.md` 的接口契约、验收标准逐条对照
+- **错误路径**:失败表达与契约声明一致,没有吞掉错误
+- **记忆同步**:功能行为变化已更新 `features/` 对应档案
+- **范围**:未引入需求「不做什么」里排除的内容
+- **简洁**:没有单人项目不需要的抽象(YAGNI)

package/templates/common/.ai/skills/critic.md

@@ -0,0 +1,21 @@
+# 对抗性检查方法论
+
+输入:一份需求定稿、架构设计或实现方案。你的职责是攻击它,不是完善它。
+
+## 四类检查
+
+1. **假设攻击**:依赖了哪些未验证的前提?哪条假设崩了整个方案就崩?
+2. **契约漏洞**:错误路径、边界值、并发/幂等是否有定义?调用方误用会发生什么?
+3. **过度设计**:哪些部分是 YAGNI?这个抽象在单人项目里值得吗?
+4. **遗漏场景**:验收标准覆盖不到的行为?与 `.ai/memory/features/` 已有功能的冲突?
+
+## 输出格式
+
+质疑列表,每条:`[high|medium|low] 质疑内容 + 触发条件`。不提供修复方案,不表扬。
+
+## 纪律
+
+- 主 agent 必须逐条回应「接受并修改」或「给出理由反驳」,不允许沉默跳过
+- 全部处理完毕才算通过
+- Claude Code 侧:由 critic subagent 独立上下文执行,只给文档路径,不给对话历史
+- Codex 侧:同上下文自检,刻意抵制为自己刚写内容辩护的倾向

package/templates/common/.ai/skills/memory-update.md

@@ -0,0 +1,24 @@
+# 记忆更新协议(节点式)
+
+## 触发时机
+
+1. **完成一个任务节点 / 做出关键决策 → 立即写**,不攒到会话结束(主路径)
+2. 用户说「更新记忆」或 /update-memory
+3. 会话收尾、上下文即将压缩
+4. 需求状态变化(requirements-flow 第 5 步联动)
+
+## 写入路由
+
+| 内容 | 去处 |
+|---|---|
+| 进展流水(做到哪/下一步/踩坑) | `session-log.md` 带时间戳追加 |
+| 需求/里程碑状态变化 | `project-state.md` 对应表格行 |
+| 功能设计决策、契约变更 | `features/<名>.md` |
+| 新增记忆文件 | `MEMORY.md` 加索引行 |
+
+## 硬性约束
+
+- 写前先读目标文件
+- 只增量追加,不重构既有格式与历史条目
+- session-log 超约 200 行:把旧条目压缩进 project-state.md 的归档章节
+- 跨工具切换前确认 session-log 已落盘;记忆变更随代码一起 commit

package/templates/common/.ai/skills/requirements-flow.md

@@ -0,0 +1,23 @@
+# 需求定稿流程(draft → final)
+
+触发:用户要求新建/定稿需求,或 /new-requirement、/finalize-requirement。
+
+## 新建(new)
+
+1. 确认目标版本目录 `docs/requirements/vX.Y.Z/`(不存在则创建 draft/ 与 final/)
+2. 在 `draft/<需求名>.md` 生成骨架:背景 / 想要什么 / 不确定的点
+3. 在 `.ai/memory/project-state.md` 需求进度表登记一行(状态 draft)
+
+## 定稿(finalize)
+
+1. 读 `draft/<需求名>.md`
+2. 逐个澄清模糊点:一次只问一个问题,优先选择题
+3. 按固定结构成稿:**目标 / 范围(必须含「不做什么」)/ 接口契约(格式见 architecture.md)/ 验收标准 / 开放问题**
+4. 强制 critic 门:按 `critic.md` 检查,逐条回应完毕才可写入 `final/<需求名>.md`
+5. 联动记忆:project-state 状态改 finalized;`features/<需求名>.md` 建档登记契约要点;MEMORY.md 加索引行
+6. 需求文档与记忆变更一起 commit
+
+## 与 superpowers 的衔接
+
+实现阶段由 brainstorming/writing-plans 以 `final/<需求名>.md` 为输入。
+本流程只产出需求(what/why),不做实现设计(how)。

package/templates/common/docs/requirements/README.md

@@ -0,0 +1,6 @@
+# 需求目录
+
+- 每个迭代版本一个目录:`vX.Y.Z/`
+- `draft/` — 人工粗稿,自由格式,想到哪写到哪
+- `final/` — AI 协作定稿,固定结构:目标 / 范围 / 接口契约 / 验收标准 / 开放问题
+- 定稿流程见 `.ai/skills/requirements-flow.md`(/new-requirement、/finalize-requirement)