manifest-generator

ManifestGenerator

根据项目描述，在当前目录中生成两个文件：

1. PROJECT_MANIFEST.md — 结构化的项目上下文，供每个工厂 Agent 阅读
2. SOFTWARE_FACTORY_MANIFEST.md — 由 6 个 Agent 组成的 SDLC 流水线蓝图

按顺序执行每个阶段。不得跳过阶段。未获得所需输入前，不得越过任何停止点。

---

FILE_WRITE_GUARD

在写入任一输出文件前调用此过程。将实际文件名代入。

FILE_WRITE_GUARD(filename):
  Check if filename exists in the current directory (use Read tool).
  If it exists:
    Ask the user: "filename already exists. Overwrite, rename to filename.bak, or abort?"
    Overwrite → proceed.
    Rename → rename the existing file to filename.bak, then proceed.
    Abort → stop execution entirely.
  If it does not exist → proceed to write.

---

阶段 0：恢复检测

在执行任何操作前，检查是否存在输出文件（使用 Read 工具——如果文件不存在，预期会出现“file not found”错误，这是正常情况）：

1. 当前目录中是否存在 PROJECT_MANIFEST.md？
2. 当前目录中是否存在 SOFTWARE_FACTORY_MANIFEST.md？

两者都不存在： 继续进入阶段 1。

PROJECT_MANIFEST.md 存在，SOFTWARE_FACTORY_MANIFEST.md 不存在： 将 PROJECT_MANIFEST.md 读入上下文。跳过阶段 1–5。 告知用户：“已找到现有的 PROJECT_MANIFEST.md——跳过并直接生成工厂清单。” 跳转至阶段 6。

两者都存在： 询问用户：“两个输出文件都已存在。要从头重新生成，还是中止？” 重新生成 → 继续进入阶段 1（FILE_WRITE_GUARD 将处理覆盖操作）。 中止 → 停止。

---

阶段 1：接收输入

运行时检测探测： 尝试调用 AskUserQuestion，并提出下方的问题。 如果成功 → 交互模式：在所有剩余阶段中，每次使用 AskUserQuestion 提出一个问题。如果失败（找不到工具）→ 文本模式：在所有剩余阶段中，以编号列表形式打印待回答的问题，等待用户回答后再继续。

输入检查（第一个问题／探测）：

检查用户当前消息或调用参数：

• 包含文件路径（例如 PROJECT_OVERVIEW.md）：使用 Read 工具读取该文件。
  • 找不到文件 → 告知用户，并请其直接粘贴描述。停止。
  • 找到文件，但看起来不是文本文件（JSON、二进制文件、package.json 等）→ 告知用户：“该文件看起来不像项目描述。”请其直接提供文本。停止。
  • 找到文件且为文本 → 将其用作描述。
• 包含项目描述（多句话描述正在构建的内容）→ 使用该描述。
• 两者都不包含 → 询问：“请粘贴项目描述，或描述你正在构建的内容。请包括它的功能、使用者、已选定的技术栈（如有）以及任何限制条件。”

停止。只有在上下文中已有项目描述后，才能继续。

阶段 2：提取

将描述与 11 个 PROJECT_MANIFEST 部分进行对照。为每个部分分配以下状态：

• EXTRACTED — 存在具体且以项目为对象的内容（真实技术名称、实际用户角色、具体约束、命名实体）
• PARTIAL — 存在一些内容，但不完整或含糊
• MISSING — 未找到相关内容

使用本文底部 HTML 注释标记之间的 WORKED EXAMPLE 来校准每个部分达到什么程度才算“EXTRACTED”。不要将示例内容用作输出。

必须询问的部分——如果状态为 PARTIAL 或 MISSING，就要提问，绝不使用默认值：

部分 1：概述
部分 2：技术栈
部分 4：领域模型  ← 最重要；绝不生成默认值
部分 6：约束
部分 9：成功标准

可使用默认值的部分——如果状态为 MISSING，可根据上下文生成，并添加标签：

部分 3：项目结构
  → 根据技术栈推断
  → 标签：(拟定 — 脚手架搭建后更新)

部分 5：约定
  → 根据技术栈推断（例如，Node.js → kebab-case 文件、*.test.ts、
    conventional commits；Python → snake_case、test_*.py 等）
  → 标签：(默认 — 脚手架搭建后更新)

部分 7：任务输入
  → 根据领域模型 + 固定流水线顺序推导
  → 标签：(流水线关键 — 运行 factory 前验证)
  → 注意：领域模型薄弱 = 任务输入薄弱；这会破坏流水线顺序

部分 8：要连接的服务
  → 如果未提及，则使用空表格

部分 10：评审标准
  → 适用于检测到的技术栈的通用规则
  → 标签：(默认 — 根据此项目进行自定义)

部分 11：发布标准
  → 适用于项目类型的通用检查清单
  → 标签：(默认 — 根据此项目进行自定义)

完成映射后，找出状态为 PARTIAL 或 MISSING 的必问部分。 继续进入阶段 3。

---

阶段 3：补充缺失信息

针对每个状态为 PARTIAL 或 MISSING 的必问部分，提出一个有针对性的问题。 按以下顺序提问：概述 → 技术栈 → 领域模型 → 约束 → 成功标准。

交互模式： 每次调用 AskUserQuestion 提出一个问题。等待回答后 再提出下一个问题。

文本模式： 将所有待回答问题打印为编号列表。等待用户 回答全部问题后再继续。

不要询问状态已为 EXTRACTED 的部分。

领域模型特别规则： 如果领域模型回答不包含任何实体名称 （例如“它管理数据”或“它有用户”这样的含糊单句），则提出一个后续问题： “你能说出核心数据实体的名称吗？例如：Order、Customer、Staff——也就是系统跟踪和存储的主要 ‘事物’。” 无论第二次回答内容如何，都接受。如果仍然没有实体名称，则标记为 FILLED，但添加 标签 (较弱 — 运行 factory 前加强部分 4)。

停止。所有必问部分均为 FILLED 前，不得继续。

---

阶段 4：验证

检查全部 11 个部分。符合以下任一情况的部分仍属于占位内容：

• 内容为空
• 包含未经编辑的模板文本（例如 [核心实体及其字段...]）
• 仅包含适用于任何项目的通用内容

对于仍为占位内容的可使用默认值的部分：生成合理的默认内容 并添加标签 (已生成 — 使用前验证)。

对于仍为占位内容的必问部分：这种情况不应发生（阶段 3 本应发现）。如果确实发生，现在提出一个有针对性的问题。

继续进入阶段 5。

---

阶段 5：编写 PROJECT_MANIFEST.md

调用 FILE_WRITE_GUARD("PROJECT_MANIFEST.md")。

使用 Write 工具将 PROJECT_MANIFEST.md 写入当前目录。 使用下方 Schema 部分定义的 PROJECT_MANIFEST 模板。 填写所有部分。任何部分都不得留空或包含模板占位文本。

报告：“PROJECT_MANIFEST.md 已写入。从描述中提取了 N/11 个部分， 通过问答填写了 M 个部分，生成了 K 个默认部分。”

第 6 阶段：生成 SOFTWARE_FACTORY_MANIFEST

使用当前上下文中已有的 PROJECT_MANIFEST 内容（在第 5 阶段生成，或在第 0 阶段恢复时读取）。不要从磁盘重新读取。

填写 SOFTWARE_FACTORY_MANIFEST 的 7 个部分：

第 1 部分 — 工厂概览 用一段话介绍：项目名称 + “This factory runs a 6-agent sequential pipeline...” + 从项目清单中提取的技术栈摘要。

第 2 部分 — 流水线顺序 固定的 6 个 Agent 顺序。使用项目名称的小写、连字符形式作为 ：

1. Planner
   读取：  功能请求 + PROJECT_MANIFEST.md
   写入：  work-packages/<slug>.md

2. Architect
   读取：  Planner 工作包 + PROJECT_MANIFEST.md 的 Tech Stack 部分
   写入：  docs/adr/NNNN-<slug>.md

3. Designer
   读取：  Architect ADR + PROJECT_MANIFEST.md 的 Domain Model 部分
   写入：  design/<slug>-spec.md

4. Coder
   读取：  Designer 规范 + PROJECT_MANIFEST.md 的 Conventions 部分
   写入：  功能分支 <slug>-<feature> 中的 src/

5. Reviewer
   读取：  代码差异 + PROJECT_MANIFEST.md 的 Review Standards 部分
   写入：  review-reports/<slug>-review.md

6. Deployer
   读取：  Reviewer 报告 + PROJECT_MANIFEST.md 的 Release Criteria 部分
   写入：  release-gates/<slug>-gate.md

第 3 部分 — 人工关卡

关卡 1：Architect 完成后，人工审批 ADR，之后 Designer 才能运行。
关卡 2：Reviewer 完成后，人工审批审查报告，之后 Deployer 才能运行。

第 4 部分 — 各 Agent 的系统提示词种子 对 6 个 Agent 分别使用此模板：

"你是 {ProjectName} 的 {Agent}。你使用 PROJECT_MANIFEST.md 中的
{relevant manifest sections}，执行 {role description}。"

填写以下内容：

• {ProjectName}：取自项目清单第 1 部分（Overview）
• {Agent}：Planner / Architect / Designer / Coder / Reviewer / Deployer
• {role description}：与该 Agent 职能相符的描述
• {relevant manifest sections}：该 Agent 读取的部分

每条种子都必须包含项目名称，以及项目清单第 4 部分（Domain Model）中的至少一个领域实体名称。如果领域模型较弱（标记为 “weak”），则在每条种子中添加：(update with domain entities once Section 4 is strengthened)。

“Fired Up Pizza”的种子示例：

Planner:   "你是 Fired Up Pizza 的 Planner。你使用 PROJECT_MANIFEST.md
           中的 Domain Model 和 Tech Stack，将功能请求拆解为工作包。"

Architect: "你是 Fired Up Pizza 的 Architect。你使用 PROJECT_MANIFEST.md
           中的 Tech Stack 和 Constraints，编写架构决策记录。"

Designer:  "你是 Fired Up Pizza 的 Designer。你使用 PROJECT_MANIFEST.md
           中的 Domain Model 和 Conventions，编写 UX 规范和交互设计。"

Coder:     "你是 Fired Up Pizza 的 Coder。你遵循 PROJECT_MANIFEST.md
           中的 Conventions 和 Task Inputs，实现功能。"

Reviewer:  "你是 Fired Up Pizza 的 Reviewer。你依据 PROJECT_MANIFEST.md
           中的 Review Standards，审查每一处代码差异。"

Deployer:  "你是 Fired Up Pizza 的 Deployer。你依据 PROJECT_MANIFEST.md
           中的 Release Criteria，对发布进行把关。"

第 5 部分 — 质量关卡 从项目清单中复制 Review Standards 和 Release Criteria 部分。 按以下格式组织 6 个阶段：“阶段 N 通过条件：[标准]”。

第 6 部分 — 编排器配置

协调模式：带交接的顺序流水线
失败处理：在失败的 Agent 处停止流水线，并向人工反馈错误
重试策略：不自动重试（由人工决定是否重新运行）
分支策略：每个工作项使用一个功能分支，Deployer 关卡通过后合并

第 7 部分 — 约定参考 从项目清单第 5 部分（Conventions）逐字复制。

---

阶段 7：验证并写入

写入前进行验证。如果有任何失败，请使用上下文中的项目清单内容重新生成该部分并修复问题。

1. Pipeline Sequence 中的全部 6 个 Agent 都有非空的 Reads 和 Writes — 通过或修复。
2. Gate 1 位于 Architect 之后，Gate 2 位于 Reviewer 之后（而非 Deployer 之后）— 通过或修复。
3. 全部 6 个种子都包含项目名称和至少一个领域实体 — 通过或修复。
4. Quality Gates 部分非空且内容具体 — 通过或修复。

调用 FILE_WRITE_GUARD("SOFTWARE_FACTORY_MANIFEST.md")。

将 SOFTWARE_FACTORY_MANIFEST.md 写入当前目录。

报告："SOFTWARE_FACTORY_MANIFEST.md written and validated. Both manifests ready — your 6-agent factory has context."

---

PROJECT_MANIFEST 架构

按此结构准确写入输出文件。填写每个部分。

# 项目清单：[项目名称]

## 概览

[一段话：软件的功能及其使用者。]

## 技术栈

| 层级   | 技术 | 备注 |
|----------|-----------|-------|
| 前端 |           |       |
| 样式  |           |       |
| 状态管理    |           |       |
| 路由  |           |       |
| 后端  |           |       |
| 数据库 |           |       |
| 测试  |           |       |
| 代码检查  |           |       |

## 项目结构

[顶层目录树，附带说明。编码前请标注（拟定）。]

## 领域模型

[核心实体、字段及其关系。]

## 约定

- 文件命名：
- 测试文件：
- API 路由：
- 提交：
- 分支：

## 约束

- [明确列出范围外的事项或禁止采用的方案。]

---

## 任务输入

| Agent     | 接收内容                  | 来源                     |
|-----------|--------------------------|--------------------------|
| Planner   |                          |                          |
| Architect |                          |                          |
| Designer  |                          |                          |
| Coder     |                          |                          |
| Reviewer  |                          |                          |
| Deployer  |                          |                          |

## 要连接的服务

| 服务 | 用途 | 配置 |
|---------|---------|--------|
|         |         |        |

## 成功标准

### 各功能的成功标准

- [ ]
- [ ]

### 工厂级成功标准

- [ ]
- [ ]

---

## 审查标准

### 规范符合性

- [Reviewer 根据 Designer 的规范执行的规则。]

### 风格

- [项目特定的风格规则。]

### 安全

- [项目特定的安全规则。]

### 严重程度等级

- **低**：外观问题、轻微不一致
- **中**：功能缺失、遗漏边缘情况
- **高**：数据丢失、安全漏洞、违反规范

---

## 发布标准

### 必需（必须全部通过）

1. [ ]
2. [ ]

### 参考信息（需报告，但不阻止发布）

- [指标 1]

---

SOFTWARE_FACTORY_MANIFEST 架构

请严格按照以下结构编写输出文件。

# 软件工厂清单：[项目名称]

## 工厂概览

[项目名称。此工厂运行一个由 6 个 Agent 组成的顺序流水线（Planner →
Architect → Designer → Coder → Reviewer → Deployer），并设有两个人工审核关卡。
技术栈：[PROJECT_MANIFEST.md 中的摘要]。]

## 流水线顺序

1. **Planner**
   - 读取：功能需求 + PROJECT_MANIFEST.md
   - 写入：work-packages/[slug].md

2. **Architect**
   - 读取：Planner 工作包 + Tech Stack 部分
   - 写入：docs/adr/NNNN-[slug].md

3. **Designer**
   - 读取：Architect ADR + Domain Model 部分
   - 写入：design/[slug]-spec.md

4. **Coder**
   - 读取：Designer 规范 + Conventions 部分
   - 写入：功能分支 [slug]-[feature] 中的 src/

5. **Reviewer**
   - 读取：代码差异 + Review Standards 部分
   - 写入：review-reports/[slug]-review.md

6. **Deployer**
   - 读取：Reviewer 报告 + Release Criteria 部分
   - 写入：release-gates/[slug]-gate.md

## 人工审核关卡

- **关卡 1 — Architect 之后：** 人工批准 ADR 后，Designer 才能运行。
- **关卡 2 — Reviewer 之后：** 人工批准审查报告后，Deployer 才能运行。

## 各 Agent 的系统提示词种子

**Planner：**“[seed]”

**Architect：**“[seed]”

**Designer：**“[seed]”

**Coder：**“[seed]”

**Reviewer：**“[seed]”

**Deployer：**“[seed]”

## 质量关卡

[根据 PROJECT_MANIFEST.md 中的 Review Standards 和 Release Criteria，列出各阶段的通过标准。
格式：“Stage N (AgentName) passes when: [criteria]”。]

## 编排器配置

- 协调模式：采用交接机制的顺序流水线
- 故障处理：在失败的 Agent 处停止流水线，并向人工操作员显示错误
- 重试策略：不自动重试（由人工决定是否重新运行）
- 分支策略：每个工作项使用一个功能分支，通过 Deployer 关卡后合并

## 规范参考

[逐字复制 PROJECT_MANIFEST.md 中的 Conventions 部分。]

---

完整示例：Fired Up Pizza

输入描述

Fired Up Pizza 是一款面向小型社区披萨餐厅的 Web 应用。顾客可以浏览菜单、自定义披萨（尺寸、饼底、配料）、通过电话号码下单，并跟踪订单状态：“已下单 → 正在制作 → 已备好 → 已送达”。员工使用同一款应用管理菜单项目，并在披萨经过厨房时更新订单状态。它取代了仅通过电话接单的工作流程，解决订单丢失、顾客无法了解订单进度的问题。

目标：顾客无需打电话即可下单和跟踪订单；员工可以在一个视图中查看所有实时订单，并一键更新状态；可在单台机器上通过 npm install && npm run dev 运行，无需配置云服务。

技术栈：React 18 + TypeScript + Vite；Tailwind；Node.js + Express REST API；通过 better-sqlite3 使用 SQLite；Vitest + React Testing Library。

范围之外：在线支付（柜台付款）、短信/推送通知、多门店支持、会员账户。

约束：不使用外部身份验证（以电话号码作为身份标识）、不使用外部数据库服务器、不使用实时基础设施——允许轮询。

用户：顾客（下单和跟踪订单，以电话号码作为身份标识）；员工（查看实时订单队列、更新订单状态、编辑菜单项目）。

“EXTRACTED” 的样例（带注释摘录）

第 1 节 — 概览（EXTRACTED）： Fired Up Pizza 是一家小型社区餐厅的 Web 应用，顾客可以浏览菜单、按电话号码自定义并下单，还能追踪订单状态：已下单 → 制作中 → 已备好 → 已送达。员工可以查看实时订单队列并更新状态。该应用取代了仅通过电话处理订单的工作流。 [好：以项目名称为主体，描述了具体角色和具体工作流。]

第 2 节 — 技术栈（EXTRACTED）： 前端：React 18 + TypeScript + Vite | 样式：Tailwind CSS | 后端：Node.js + Express（REST）| 数据库：通过 better-sqlite3 使用 SQLite（单机运行，无需外部服务）| 测试：Vitest + React Testing Library [好：列出了具名技术，并在适用时注明版本和限制。]

第 4 节 — 领域模型（EXTRACTED）： MenuItem：id、name、description、base_price、available（布尔值） Order：id、phone_number、status（placed|preparing|ready|delivered）、created_at OrderItem：id、order_id、menu_item_id、size、crust、toppings[]、unit_price Customer：通过 phone_number 标识（无账户实体） Staff：仅需角色，无需单独实体 [好：列出了具名实体和关键字段，并隐含了关系。这就是“EXTRACTED”的样例。]

第 4 节 — 领域模型（PARTIAL）： “该应用为顾客和员工管理订单及菜单项。” [不好：虽然提到了实体名称（订单、菜单项、顾客、员工），但没有字段、关系或状态，因此需要追问。]

第 6 节 — 限制（EXTRACTED）：

• 不支持在线支付（仅限柜台付款）
• 不发送短信或推送通知
• 不支持多地点
• 不使用外部身份验证 — 仅通过电话号码识别身份
• 不使用外部数据库服务 — 使用 SQLite，单机运行
• 可接受轮询（无需实时基础设施） [好：明确列出限制，内容可执行。]

第 9 节 — 成功标准（EXTRACTED）： 单项功能：顾客无需打电话即可下单；顾客可追踪订单经过 4 个状态阶段；员工可在一个视图中查看所有实时订单；员工可一键更新状态；员工可编辑菜单项。 工厂级：运行 npm install && npm run dev 即可启动应用；在干净检出环境中所有测试均通过。 [好：具体、可测试，并包含工厂级标准。]