@wozhuzaisi/prdd-cli 0.1.0

package/README.md

@@ -0,0 +1,60 @@
+# @wozhuzaisi/prdd-cli
+
+面向 **Claude Code** 的轻量安装器：把 **PRD 驱动开发** 所需的目录约定与 **5 个 Skills** 写入目标仓库。
+
+- **源码仓库：** [wozhuzaisi/xiaoma-dd](https://github.com/wozhuzaisi/xiaoma-dd)（可为私有，不影响 npm 安装）
+
+## 功能
+
+- `install`：落盘 `_xiaoma-dd/`、`_xiaoma-dd-output/`（合并拷贝，不覆盖已有 `project-context.md` 等）、`.claude/skills/prdd-*`，并可选在 `CLAUDE.md` 追加说明块。
+- `status`：读取 `_xiaoma-dd/.prdd-install.json`。
+- `uninstall`：移除 `_xiaoma-dd` 与 `prdd-*` Skills；`--remove-output` 可一并删除 `_xiaoma-dd-output`（慎用）。
+
+## 要求
+
+- Node.js **≥ 18**
+
+## 使用
+
+在项目根目录执行：
+
+```bash
+# 开发阶段可直接使用本仓库内脚本
+node Projects/06-XiaoMa-dd/prdd-cli/bin/prdd-cli.js install --yes
+
+# 全局安装后
+npm install -g @wozhuzaisi/prdd-cli
+prdd-cli install --yes
+
+# 或使用 npx（推荐先试）
+npx @wozhuzaisi/prdd-cli install --yes
+
+# 指定目录
+prdd-cli install --yes --directory /path/to/repo
+
+# 覆盖已有 _xiaoma-dd（会重写 Skills 与配置目录）
+prdd-cli install --yes --force
+
+# CI 可用环境变量代替 --yes
+PRDD_CLI_YES=1 prdd-cli install
+```
+
+## 安装后的 Skills（Claude Code）
+
+| Skill | 作用 |
+|--------|------|
+| `prdd-ingest` | PRD 校验、摘要、需求表与缺口清单 |
+| `prdd-spec-from-prd` | 技术规格 `tech-spec-from-prd.md` |
+| `prdd-story-split` | 拆分 `stories/story-*.md` 与 `story-index.md` |
+| `prdd-implement-story` | 按 Story 实现代码与测试 |
+| `prdd-review` | 对照 PRD/Story 的审查报告 |
+
+详细口令与顺序见安装后的 **`_xiaoma-dd/CHEATSHEET.md`**。
+
+## 示例 PRD
+
+见本包 `examples/sample-PRD.md`，可复制到 `planning-artifacts/` 后跑 `prdd-ingest`。
+
+## 协议
+
+MIT

package/bin/prdd-cli.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import fs from "node:fs/promises";
+import {
+  installProject,
+  readManifest,
+  uninstallProject,
+} from "../lib/install.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+async function readPackageVersion() {
+  const pkg = path.join(__dirname, "..", "package.json");
+  const raw = await fs.readFile(pkg, "utf8");
+  return JSON.parse(raw).version;
+}
+
+function parseArgs(argv) {
+  const args = { _: [], command: null };
+  const rest = [...argv];
+  while (rest.length) {
+    const a = rest.shift();
+    if (a === "--directory" || a === "-d") {
+      args.directory = rest.shift();
+      continue;
+    }
+    if (a === "--yes" || a === "-y") {
+      args.yes = true;
+      continue;
+    }
+    if (a === "--force" || a === "-f") {
+      args.force = true;
+      continue;
+    }
+    if (a === "--remove-output") {
+      args.removeOutput = true;
+      continue;
+    }
+    if (a.startsWith("-")) {
+      args.unknown = a;
+      continue;
+    }
+    args._.push(a);
+  }
+  args.command = args._[0] || null;
+  return args;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const args = parseArgs(argv);
+  const version = await readPackageVersion();
+
+  if (args._[0] === "version" || args._[0] === "-v" || args._[0] === "--version") {
+    console.log(version);
+    process.exit(0);
+  }
+
+  const projectRoot = path.resolve(args.directory || process.cwd());
+
+  switch (args.command) {
+    case "install": {
+      if (!args.yes && !process.env.PRDD_CLI_YES) {
+        console.error(
+          "即将安装到:",
+          projectRoot,
+          "\n若确认无误，请使用: prdd-cli install --yes\n或设置环境变量 PRDD_CLI_YES=1"
+        );
+        process.exit(1);
+      }
+      const r = await installProject({
+        projectRoot,
+        force: Boolean(args.force),
+        version,
+      });
+      console.log("prdd-cli 安装完成");
+      console.log("- 配置与文档:", r.destXiaoma);
+      console.log("- 产出物目录:", r.destOut);
+      console.log("- Claude Skills:", r.destClaudeSkills);
+      console.log("- 版本:", r.manifest.version);
+      break;
+    }
+    case "status": {
+      const m = await readManifest(projectRoot);
+      if (!m) {
+        console.log("未安装 prdd-cli（未找到 _xiaoma-dd/.prdd-install.json）");
+        process.exit(1);
+      }
+      console.log(JSON.stringify({ ...m, projectRoot }, null, 2));
+      break;
+    }
+    case "uninstall": {
+      if (!args.yes && !process.env.PRDD_CLI_YES) {
+        console.error(
+          "将移除 _xiaoma-dd 与 prdd-* Skills" +
+            (args.removeOutput ? " 以及 _xiaoma-dd-output" : "") +
+            "。\n确认请使用: prdd-cli uninstall --yes" +
+            (args.removeOutput ? " --remove-output" : "")
+        );
+        process.exit(1);
+      }
+      await uninstallProject({
+        projectRoot,
+        removeOutput: Boolean(args.removeOutput),
+      });
+      console.log("已卸载 prdd-cli 资产");
+      break;
+    }
+    default:
+      console.log(`prdd-cli ${version}
+
+用法:
+  prdd-cli install --yes [--directory <path>] [--force]
+  prdd-cli status [--directory <path>]
+  prdd-cli uninstall --yes [--remove-output] [--directory <path>]
+
+环境变量:
+  PRDD_CLI_YES=1  等价于 --yes（便于 CI）
+`);
+      process.exit(args.command ? 1 : 0);
+  }
+}
+
+main().catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/examples/sample-PRD.md

@@ -0,0 +1,24 @@
+# 示例 PRD：待办列表最小功能
+
+**版本：** 0.1  
+**日期：** 2026-04-14  
+
+## 背景
+
+为演示 prdd-cli 流程，实现一个仅本地的待办增删改查。
+
+## 需求
+
+| ID | 描述 | 优先级 | 验收标准 |
+|----|------|--------|----------|
+| REQ-001 | 用户可新增一条待办标题 | P0 | 提交后列表中可见该条 |
+| REQ-002 | 用户可将待办标为完成 | P0 | 状态持久化，刷新后仍存在 |
+| REQ-003 | 用户可删除一条待办 | P1 | 删除后不再出现 |
+
+## 范围外
+
+- 多用户、登录、云端同步。
+
+## 非功能
+
+- 单测覆盖核心逻辑；启动命令见 `project-context.md`。

package/lib/fs-utils.js

@@ -0,0 +1,46 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function exists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureDir(dir) {
+  await fs.mkdir(dir, { recursive: true });
+}
+
+export async function copyDir(src, dest, { filter } = {}) {
+  await ensureDir(dest);
+  const entries = await fs.readdir(src, { withFileTypes: true });
+  for (const ent of entries) {
+    const from = path.join(src, ent.name);
+    const to = path.join(dest, ent.name);
+    const rel = path.relative(src, from);
+    if (filter && !filter(rel, ent)) continue;
+    if (ent.isDirectory()) {
+      await copyDir(from, to, { filter });
+    } else if (ent.isFile()) {
+      await ensureDir(path.dirname(to));
+      await fs.copyFile(from, to);
+    }
+  }
+}
+
+export async function readJsonSafe(file, fallback) {
+  try {
+    const raw = await fs.readFile(file, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return fallback;
+  }
+}
+
+export async function writeJson(file, obj) {
+  await ensureDir(path.dirname(file));
+  await fs.writeFile(file, `${JSON.stringify(obj, null, 2)}\n`, "utf8");
+}

package/lib/index.js

@@ -0,0 +1,6 @@
+export {
+  installProject,
+  uninstallProject,
+  readManifest,
+  manifestPath,
+} from "./install.js";

package/lib/install.js

@@ -0,0 +1,188 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { copyDir, ensureDir, exists, readJsonSafe, writeJson } from "./fs-utils.js";
+import { templatePath } from "./paths.js";
+
+/** 合并拷贝：目标已存在且非 force 时跳过该文件 */
+async function copyDirMergeSkipExisting(src, dest, { force }) {
+  await ensureDir(dest);
+  const entries = await fs.readdir(src, { withFileTypes: true });
+  for (const ent of entries) {
+    const from = path.join(src, ent.name);
+    const to = path.join(dest, ent.name);
+    if (ent.isDirectory()) {
+      await copyDirMergeSkipExisting(from, to, { force });
+    } else if (ent.isFile()) {
+      if (!force && (await exists(to))) continue;
+      await ensureDir(path.dirname(to));
+      await fs.copyFile(from, to);
+    }
+  }
+}
+
+const MANIFEST_NAME = ".prdd-install.json";
+const SKILL_PREFIX = "prdd-";
+
+const BUNDLED_SKILLS = [
+  "prdd-ingest",
+  "prdd-spec-from-prd",
+  "prdd-story-split",
+  "prdd-implement-story",
+  "prdd-review",
+];
+
+export function manifestPath(projectRoot) {
+  return path.join(projectRoot, "_xiaoma-dd", MANIFEST_NAME);
+}
+
+export async function readManifest(projectRoot) {
+  return readJsonSafe(manifestPath(projectRoot), null);
+}
+
+async function backupIfExists(file) {
+  if (!(await exists(file))) return;
+  const bak = `${file}.bak`;
+  let n = 0;
+  let target = bak;
+  while (await exists(target)) {
+    n += 1;
+    target = `${file}.bak.${n}`;
+  }
+  await fs.rename(file, target);
+  return target;
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.projectRoot - absolute path
+ * @param {boolean} opts.force - overwrite _xiaoma-dd non-merge files
+ * @param {string} opts.version - cli package version
+ */
+export async function installProject({ projectRoot, force, version }) {
+  const abs = path.resolve(projectRoot);
+  const tplXiaoma = templatePath("_xiaoma-dd");
+  const tplOut = templatePath("_xiaoma-dd-output");
+  const tplSkills = templatePath(".claude", "skills");
+
+  if (!(await exists(tplXiaoma))) {
+    throw new Error(`Missing templates: ${tplXiaoma}`);
+  }
+
+  const destXiaoma = path.join(abs, "_xiaoma-dd");
+  const destOut = path.join(abs, "_xiaoma-dd-output");
+  const destClaudeSkills = path.join(abs, ".claude", "skills");
+
+  if ((await exists(destXiaoma)) && !force) {
+    const m = await readManifest(abs);
+    if (m?.version) {
+      throw new Error(
+        `已有安装（版本 ${m.version}）。使用 --force 覆盖 _xiaoma-dd，或先 prdd-cli uninstall`
+      );
+    }
+    throw new Error(
+      "目录 _xiaoma-dd 已存在但无 prdd-cli 安装记录。请改用 --force 覆盖，或先手动处理该目录。"
+    );
+  }
+
+  if (force && (await exists(path.join(destXiaoma, MANIFEST_NAME)))) {
+    await backupIfExists(path.join(destXiaoma, MANIFEST_NAME));
+  }
+
+  await ensureDir(destXiaoma);
+  await copyDir(tplXiaoma, destXiaoma);
+
+  await ensureDir(destOut);
+  await copyDirMergeSkipExisting(tplOut, destOut, { force });
+
+  await ensureDir(destClaudeSkills);
+  for (const name of BUNDLED_SKILLS) {
+    const src = path.join(tplSkills, name);
+    const dest = path.join(destClaudeSkills, name);
+    if (!(await exists(src))) continue;
+    if ((await exists(dest)) && !force) {
+      // merge: skip existing skill dir unless force
+      continue;
+    }
+    if (force && (await exists(dest))) {
+      await fs.rm(dest, { recursive: true });
+    }
+    await copyDir(src, dest);
+  }
+
+  const manifest = {
+    package: "prdd-cli",
+    version,
+    installedAt: new Date().toISOString(),
+    skills: BUNDLED_SKILLS,
+    outputRoot: "_xiaoma-dd-output",
+  };
+  await writeJson(path.join(destXiaoma, MANIFEST_NAME), manifest);
+
+  await writeClaudeSnippet(abs, force);
+
+  return { destXiaoma, destOut, destClaudeSkills, manifest };
+}
+
+async function writeClaudeSnippet(projectRoot, force) {
+  const claudeMd = path.join(projectRoot, "CLAUDE.md");
+  const block = [
+    "",
+    "<!-- prdd-cli: begin -->",
+    "## PRD 驱动开发（prdd-cli）",
+    "",
+    "- 产出物根目录：`./_xiaoma-dd-output/`",
+    "- 速查：`./_xiaoma-dd/CHEATSHEET.md`",
+    "- 在 Claude Code 中使用 Skills：`prdd-ingest`、`prdd-spec-from-prd`、`prdd-story-split`、`prdd-implement-story`、`prdd-review`",
+    "<!-- prdd-cli: end -->",
+    "",
+  ].join("\n");
+
+  if (!(await exists(claudeMd))) {
+    await fs.writeFile(
+      claudeMd,
+      `# 项目说明\n\n${block}`,
+      "utf8"
+    );
+    return;
+  }
+  const cur = await fs.readFile(claudeMd, "utf8");
+  if (cur.includes("<!-- prdd-cli: begin -->")) {
+    if (!force) return;
+    const next = cur.replace(
+      /<!-- prdd-cli: begin -->[\s\S]*?<!-- prdd-cli: end -->/,
+      block.trim()
+    );
+    await fs.writeFile(claudeMd, next, "utf8");
+    return;
+  }
+  await fs.appendFile(claudeMd, block, "utf8");
+}
+
+export async function uninstallProject({ projectRoot, removeOutput }) {
+  const abs = path.resolve(projectRoot);
+  const m = await readManifest(abs);
+  if (!m?.version) {
+    throw new Error("未检测到 prdd-cli 安装记录（_xiaoma-dd/.prdd-install.json）");
+  }
+
+  const destClaudeSkills = path.join(abs, ".claude", "skills");
+  for (const name of m.skills || BUNDLED_SKILLS) {
+    if (!name.startsWith(SKILL_PREFIX)) continue;
+    const p = path.join(destClaudeSkills, name);
+    if (await exists(p)) {
+      await fs.rm(p, { recursive: true });
+    }
+  }
+
+  const xiaoma = path.join(abs, "_xiaoma-dd");
+  if (await exists(xiaoma)) {
+    await fs.rm(xiaoma, { recursive: true });
+  }
+
+  if (removeOutput) {
+    const out = path.join(abs, "_xiaoma-dd-output");
+    if (await exists(out)) {
+      await fs.rm(out, { recursive: true });
+    }
+  }
+}

package/lib/paths.js

@@ -0,0 +1,12 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export function templatesRoot() {
+  return path.join(__dirname, "..", "templates");
+}
+
+export function templatePath(...parts) {
+  return path.join(templatesRoot(), ...parts);
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@wozhuzaisi/prdd-cli",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Install PRD-driven Claude Code skills and project scaffolding (XiaoMa-dd style)",
+  "bin": {
+    "prdd-cli": "bin/prdd-cli.js"
+  },
+  "main": "lib/index.js",
+  "files": [
+    "bin",
+    "lib",
+    "templates",
+    "examples"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "claude-code",
+    "prd",
+    "skills",
+    "xiaoma"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wozhuzaisi/xiaoma-dd.git",
+    "directory": "prdd-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/wozhuzaisi/xiaoma-dd/issues"
+  },
+  "homepage": "https://github.com/wozhuzaisi/xiaoma-dd#readme"
+}

package/templates/.claude/skills/prdd-implement-story/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: prdd-implement-story
+description: '按单个 Story 文件实现代码与测试并更新 Story 状态。用户给出 Story 路径或说「实现当前 Story」「prdd implement」时使用。'
+---
+
+Follow the instructions in ./workflow.md.

package/templates/.claude/skills/prdd-implement-story/prdd-skill-manifest.yaml

@@ -0,0 +1 @@
+type: skill

package/templates/.claude/skills/prdd-implement-story/workflow.md

@@ -0,0 +1,40 @@
+# prdd-implement-story：按 Story 实现
+
+**目标：** 完成 Story 中全部 AC，并留下可核验的测试与记录。
+
+---
+
+## 输入
+
+- 目标 `planning-artifacts/stories/story-NNN-*.md`（若用户未指定，读取 `story-index.md` 中第一个「待开发」）。  
+- `tech-spec-from-prd.md` 与相关 PRD 片段（仅读与本次 Story 相关的部分）。  
+- `_xiaoma-dd-output/project-context.md`。
+
+---
+
+## 输出
+
+1. **代码与测试**：按 `project-context` 的测试命令可运行通过。  
+2. **Story 文件更新**：在同一 Story 文件末尾「完成记录」中填写：
+   - 实现概要  
+   - 变更文件列表  
+   - 如何验证（命令）  
+   - 将「元数据-状态」改为 `已完成`（或你们团队约定状态）  
+3. **implementation-artifacts**：追加或更新 `change-log.md`（若不存在则创建），记录一行：`日期 | Story ID | 摘要 | 关联 REQ`。
+
+---
+
+## 执行步骤
+
+1. 阅读 Story 的 AC 与依赖；若依赖未满足，先提示用户或先实现依赖 Story。  
+2. 在仓库中定位修改点；优先复用现有模式与工具函数。  
+3. 编写最小必要测试（单元/集成按项目惯例）。  
+4. 本地运行测试与 lint（若 project-context 有说明）。  
+5. 更新 Story 与 `change-log.md`，并给用户简短总结与下一步（下一 Story 或 `prdd-review`）。
+
+---
+
+## 约束
+
+- 不扩展 Story 范围；若发现必须扩大范围，在 Story 中记录「范围变更建议」并暂停自动扩展，提示用户走规格/PRD 更新流程。  
+- 所有行为应可追溯至 Story 的 REQ / AC。

package/templates/.claude/skills/prdd-ingest/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: prdd-ingest
+description: '读取并校验产品需求文档（PRD），生成摘要与需求 ID 表。在用户提供 PRD 路径、导入 PRD、或说「prdd ingest / 校验 PRD」时使用。'
+---
+
+Follow the instructions in ./workflow.md.

package/templates/.claude/skills/prdd-ingest/prdd-skill-manifest.yaml

@@ -0,0 +1 @@
+type: skill

package/templates/.claude/skills/prdd-ingest/workflow.md

@@ -0,0 +1,42 @@
+# prdd-ingest：PRD 摄入与校验
+
+**目标：** 将 PRD 结构化为可开发输入，并暴露缺口。
+
+**语言：** 与用户对话使用简体中文；落盘文档默认简体中文（若 `project-context` 另有约定则从其约定）。
+
+---
+
+## 输入
+
+- 用户给出的 **PRD 文件路径**（相对仓库根或绝对路径）；若未给出，在仓库内按 `_xiaoma-dd/config.yaml` 的 `prd_glob` 搜索并列出候选，请用户确认一个。
+- 可选：`_xiaoma-dd-output/project-context.md`（棕地约束）。
+
+---
+
+## 输出（写入 `_xiaoma-dd-output/planning-artifacts/`）
+
+1. `prd-summary.md`  
+   - 元信息：PRD 路径、版本/日期（若原文有）、负责人  
+   - 一页内 **执行摘要**（目标用户、问题、范围 In/Out、里程碑）  
+   - **需求表**：列包含 `需求 ID`（稳定可引用，如 REQ-001）、描述、优先级、验收要点、对应 PRD 章节锚点  
+
+2. `prd-gaps.md`  
+   - **缺口清单**：模糊描述、缺失验收标准、未定义边界、依赖与风险未澄清项  
+   - 每条缺口标注建议动作（补 PRD / 当面确认 / 技术假设）
+
+---
+
+## 执行步骤
+
+1. 完整阅读 PRD 原文（必要时拆分为多段读取，避免遗漏章节）。  
+2. 提取或分配 **需求 ID**；若 PRD 已有编号，沿用并映射到 REQ 表。  
+3. 对照「可开发」检查：是否有明确验收标准、数据字段、接口语义、异常与权限；记录到 `prd-gaps.md`。  
+4. 若 **阻塞性缺口** 过多，在对话中置顶说明：建议先修订 PRD，再继续 `prdd-spec-from-prd`。  
+5. 写文件前确认目录存在；写完后用简短摘要回复用户下一步建议（通常是补缺口或进入 `prdd-spec-from-prd`）。
+
+---
+
+## 约束
+
+- 不编造 PRD 中不存在的需求；不确定处写入 gaps，不得静默猜测为事实。  
+- 所有摘要条目尽量可追溯至 PRD 章节标题或锚点。

package/templates/.claude/skills/prdd-review/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: prdd-review
+description: '对照 PRD 与 Story 验收标准审查代码改动（含风险与遗漏）。用户说「对照 PRD 审查」「prdd review」「实现是否满足需求」时使用。'
+---
+
+Follow the instructions in ./workflow.md.

package/templates/.claude/skills/prdd-review/prdd-skill-manifest.yaml

@@ -0,0 +1 @@
+type: skill

package/templates/.claude/skills/prdd-review/workflow.md

@@ -0,0 +1,39 @@
+# prdd-review：PRD / Story 对齐审查
+
+**目标：** 发现实现与 PRD、技术规格、Story AC 的偏离，以及明显的质量与风险问题。
+
+---
+
+## 输入
+
+- 当前分支相对主干的 **diff**（或用户指定的文件列表 / Story ID）。  
+- `planning-artifacts/prd-summary.md`、`tech-spec-from-prd.md`。  
+- 已声称完成的 `stories/story-NNN-*.md`。  
+- 可选：`prd-gaps.md` 中未关闭项。
+
+---
+
+## 输出
+
+在 `_xiaoma-dd-output/implementation-artifacts/` 写入 `review-report-YYYYMMDD.md`（若用户指定名称则从其），包含：
+
+1. **范围与对象**：审查了哪些 Story / REQ、哪些文件。  
+2. **对齐检查表**：列 `REQ 或 AC | 证据（文件/函数） | 结论（满足/部分/不满足） | 说明`。  
+3. **风险**：安全、兼容、性能、可维护性。  
+4. **行动项**：需补测试、需改文档、需回退设计等，带优先级。
+
+---
+
+## 执行步骤
+
+1. 从 Story 的 AC 出发，逐项在代码与测试中找证据；没有证据则标为不满足或风险。  
+2. 对照 `tech-spec-from-prd` 的追溯矩阵，检查是否有 REQ 完全未覆盖。  
+3. 不重复实现功能；仅审查与记录。  
+4. 给出可执行的修复顺序建议。
+
+---
+
+## 约束
+
+- 不以「代码看起来没问题」代替对 AC 的逐条核验。  
+- 对假设与缺口使用明确措辞（Assumption / Gap），避免臆断业务含义。

package/templates/.claude/skills/prdd-spec-from-prd/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: prdd-spec-from-prd
+description: '在已通过校验的 PRD 基础上编写技术规格（接口、数据模型、约束）。用户说「写技术规格」「从 PRD 出 spec」「prdd spec」时使用。'
+---
+
+Follow the instructions in ./workflow.md.

package/templates/.claude/skills/prdd-spec-from-prd/prdd-skill-manifest.yaml

@@ -0,0 +1 @@
+type: skill

package/templates/.claude/skills/prdd-spec-from-prd/workflow.md

@@ -0,0 +1,42 @@
+# prdd-spec-from-prd：从 PRD 生成技术规格
+
+**目标：** 把需求翻译成可实现、可测试的技术设计，并与 PRD 需求 ID 对齐。
+
+---
+
+## 输入
+
+- `planning-artifacts/prd-summary.md`（必需）与原始 PRD 文件。  
+- `planning-artifacts/prd-gaps.md`（若存在）：对仍开放的假设显式标注 **Assumption**。  
+- `_xiaoma-dd-output/project-context.md`：技术栈与仓库约定。
+
+---
+
+## 输出
+
+在 `_xiaoma-dd-output/planning-artifacts/` 写入：
+
+- `tech-spec-from-prd.md`，建议包含：
+  - **范围与目标**（对应 REQ ID 列表）  
+  - **架构与模块边界**（简图或条目即可）  
+  - **数据模型 / 状态机**（若适用）  
+  - **API 或模块接口**（签名、错误码、幂等、分页等）  
+  - **非功能**：性能、安全、观测、兼容  
+  - **追溯矩阵**：表格列 `REQ ID | 设计章节 | 备注`  
+  - **开放问题**：引用 `prd-gaps` 中未关闭项  
+
+---
+
+## 执行步骤
+
+1. 阅读 `prd-summary.md` 与 PRD 相关章节，列出本迭代必须满足的 REQ。  
+2. 结合 `project-context` 选择与本仓库一致的模式（目录、命名、测试策略）。  
+3. 将每个 REQ 映射到具体设计条目；无法映射的 REQ 写入开放问题。  
+4. 完成后提示用户运行 `prdd-story-split` 进行任务拆分。
+
+---
+
+## 约束
+
+- 规格中每条关键决策应能引用 **REQ ID** 或明确标记为假设。  
+- 避免与 `project-context` 中的禁止事项冲突。

package/templates/.claude/skills/prdd-story-split/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: prdd-story-split
+description: '将技术规格拆分为可实施的 Story 文件（含验收标准与 PRD/REQ 追溯）。用户说「拆 Story」「划分迭代任务」「prdd stories」时使用。'
+---
+
+Follow the instructions in ./workflow.md.

package/templates/.claude/skills/prdd-story-split/prdd-skill-manifest.yaml

@@ -0,0 +1 @@
+type: skill

package/templates/.claude/skills/prdd-story-split/workflow.md

@@ -0,0 +1,61 @@
+# prdd-story-split：Story 拆分
+
+**目标：** 生成小而可验收的 Story 文件，便于逐条实现与审查。
+
+---
+
+## 输入
+
+- `planning-artifacts/tech-spec-from-prd.md`（必需）  
+- `planning-artifacts/prd-summary.md`  
+- `_xiaoma-dd-output/project-context.md`
+
+---
+
+## 输出
+
+在 `_xiaoma-dd-output/planning-artifacts/stories/` 为每个 Story 创建一个文件，命名：`story-NNN-短标题.md`（NNN 为三位序号）。
+
+每个 Story 文件模板结构如下（保持标题层级一致便于解析）：
+
+```markdown
+# Story: <标题>
+
+## 元数据
+- Story ID: STORY-NNN
+- 状态: 待开发
+- 关联 REQ: REQ-xxx, REQ-yyy
+- 依赖: STORY-...（无则写 无）
+
+## 背景
+（1 段）
+
+## 验收标准（AC）
+1. ...
+2. ...
+
+## 实现说明
+- 涉及路径/模块建议：
+- 测试要求：
+
+## 完成记录
+（实现阶段由 prdd-implement-story 勾选/填写）
+```
+
+另外更新或创建 `planning-artifacts/story-index.md`：表格列 `Story ID | 标题 | REQ | 状态 | 文件路径`。
+
+---
+
+## 执行步骤
+
+1. 根据 tech-spec 划分子任务，确保每个 Story 可在 1 个会话或 1 个 PR 内完成（尽量小）。  
+2. 为每个 Story 写清 **可验证** 的 AC（避免「优化体验」类模糊句）。  
+3. 标注依赖顺序（阻塞关系）。  
+4. 完成后建议用户从 STORY-001 起使用 `prdd-implement-story`。
+
+---
+
+## 约束
+
+- 每个 Story 必须关联至少一个 **REQ ID**。  
+- 不在 Story 中隐藏架构级变更；若需架构调整，应回到 tech-spec 或单独 Story。

package/templates/_xiaoma-dd/CHEATSHEET.md

@@ -0,0 +1,37 @@
+# prdd-cli · Claude Code 速查
+
+## 前置
+
+1. 将 **PRD** 放入仓库（任意路径，建议在 `_xiaoma-dd-output/planning-artifacts/` 或你的文档目录）。
+2. 棕地项目请先填写 `_xiaoma-dd-output/project-context.md`（技术栈、目录约定、测试方式）。
+3. 在 Claude Code 中确保已加载本项目的 **Skills**（`.claude/skills/prdd-*`）。
+
+## 推荐顺序（MVP）
+
+| 顺序 | Skill | 作用 |
+|------|---------|------|
+| 1 | `prdd-ingest` | 读 PRD，输出校验报告 + 摘要 + 需求 ID 表 |
+| 2 | `prdd-spec-from-prd` | 在 PRD 与技术上下文基础上写 **技术规格** |
+| 3 | `prdd-story-split` | 拆 **Story** 文件（含验收标准与 PRD 追溯） |
+| 4 | `prdd-implement-story` | 按单个 Story 改代码与测试 |
+| 5 | `prdd-review` | 对照 PRD / Story 做实现审查 |
+
+## 在对话里怎么说
+
+自然语言示例（Claude 会按 Skill 描述匹配）：
+
+- 「用 prdd-ingest 处理 `xxx/PRD.md`」
+- 「根据 PRD 写技术规格」→ `prdd-spec-from-prd`
+- 「把规格拆成多个 Story」→ `prdd-story-split`
+- 「实现 `story-001.md` 这个 Story」→ `prdd-implement-story`
+- 「审查当前改动是否符合 PRD」→ `prdd-review`
+
+## 产出物路径（默认）
+
+- 规划：`./_xiaoma-dd-output/planning-artifacts/`
+- Story：`./_xiaoma-dd-output/planning-artifacts/stories/`
+- 实施记录：`./_xiaoma-dd-output/implementation-artifacts/`
+
+## 与通用 XiaoMa 技能的关系
+
+若本仓库同时安装了其他 `xiaoma-*` Skills，可复用例如 `xiaoma-generate-project-context` 来生成/更新 `project-context.md`，再执行 prdd 流程。

package/templates/_xiaoma-dd/README.md

@@ -0,0 +1,10 @@
+# XiaoMa-dd / prdd-cli 资产说明
+
+本目录由 **prdd-cli** 安装生成，包含：
+
+- `config.yaml`：路径与语言约定。
+- `CHEATSHEET.md`：在 Claude Code 中应优先打开的速查表。
+- `agents/`：可选的角色提示（轻量）；执行时以 **Skills** 为主。
+- `workflows/`：给人看的阶段说明（非自动执行脚本）。
+
+产出物统一写入仓库根目录的 `_xiaoma-dd-output/`，与业务源码分离。

package/templates/_xiaoma-dd/agents/architect.md

@@ -0,0 +1,4 @@
+# 角色：架构师
+
+- 把 PRD 约束落实为可落地的技术决策（接口、模块边界、数据与部署）。
+- 记录关键权衡与风险；避免在 Story 中隐含未文档化的架构假设。

package/templates/_xiaoma-dd/agents/developer.md

@@ -0,0 +1,4 @@
+# 角色：开发者
+
+- 严格按 **Story 的验收标准** 实现，并遵守 `project-context.md`。
+- 变更应有测试；接口变更需同步文档或 Story 引用。

package/templates/_xiaoma-dd/agents/pm.md

@@ -0,0 +1,5 @@
+# 角色：产品经理（PRD 侧）
+
+- 关注范围、优先级、验收标准与用户价值。
+- 所有实现必须能映射回 **PRD 章节或需求 ID**。
+- 不直接写代码；输出以文档与 Story 为主。

package/templates/_xiaoma-dd/config.yaml

@@ -0,0 +1,14 @@
+# prdd-cli 项目侧配置（安装器落盘，可按需修改）
+project_name: "${PROJECT_NAME}"
+output_root: "_xiaoma-dd-output"
+communication_language: "zh-CN"
+document_output_language: "zh-CN"
+
+# PRD 文件默认搜索 glob（相对仓库根）
+prd_glob: "**/*PRD*.md"
+
+paths:
+  planning: "_xiaoma-dd-output/planning-artifacts"
+  stories: "_xiaoma-dd-output/planning-artifacts/stories"
+  implementation: "_xiaoma-dd-output/implementation-artifacts"
+  project_context: "_xiaoma-dd-output/project-context.md"

package/templates/_xiaoma-dd/workflows/mvp-pipeline.md

@@ -0,0 +1,9 @@
+# MVP 流水线（人工/对话驱动）
+
+1. **ingest**：确认 PRD 完整、可测、有优先级与范围边界。
+2. **spec**：把需求翻译成技术方案（接口、数据模型、错误码、非功能约束）。
+3. **stories**：每个 Story 小而可验收，并带 PRD 追溯字段。
+4. **implement**：一次一个 Story，提交前自检（测试、lint）。
+5. **review**：对照 PRD 与 Story 的 AC，检查遗漏与过度实现。
+
+每步应在 `_xiaoma-dd-output/` 中留下可追溯文件，便于复盘与多会话接力。

package/templates/_xiaoma-dd-output/implementation-artifacts/README.md

@@ -0,0 +1,3 @@
+# implementation-artifacts
+
+放置变更日志、审查记录、与发布相关的实施侧说明。

package/templates/_xiaoma-dd-output/implementation-artifacts/change-log.md

@@ -0,0 +1,7 @@
+# change-log
+
+| 日期 | Story | 摘要 | REQ |
+|------|--------|------|-----|
+|  |  |  |  |
+
+由 `prdd-implement-story` 在实现时追加行。

package/templates/_xiaoma-dd-output/planning-artifacts/README.md

@@ -0,0 +1,5 @@
+# planning-artifacts
+
+放置 PRD 副本或链接、校验报告、技术规格、Story 等规划类产出。
+
+建议将权威 PRD 路径记录在 `prd-summary.md` 的元信息中。

package/templates/_xiaoma-dd-output/planning-artifacts/stories/README.md

@@ -0,0 +1,3 @@
+# stories
+
+由 `prdd-story-split` Skill 生成的 Story 文件放在此目录，命名建议：`story-001-xxx.md`。

package/templates/_xiaoma-dd-output/project-context.md

@@ -0,0 +1,21 @@
+# project-context（棕地项目必填，绿场可简写）
+
+## 技术栈
+
+- 语言与版本：
+- 框架：
+- 包管理：
+
+## 仓库约定
+
+- 源码根目录：
+- 测试命令：
+- Lint / Format：
+
+## 禁止事项
+
+- （例如：禁止在业务层直接访问环境变量）
+
+## 与 PRD 的关系
+
+- 当前迭代 PRD 路径或链接：