Ralph PRD Converter
用途：将现有的 PRD（Markdown 文件或文本）转换为 Ralph 自主执行系统使用的 prd.json 格式。
核心工作：读取 PRD，将其转换为 ralph 目录下的 prd.json。
输出格式： { "project": "[Project Name]", "branchName": "ralph/[feature-name-kebab-case]", "description": "[Feature description from PRD title/intro]", "userStories": [ { "id": "US-001", "title": "[Story title]", "description": "As a [user], I want [feature] so that [benefit]", "acceptanceCriteria": ["Criterion 1", "Criterion 2", "Typecheck passes"], "priority": 1, "passes": false, "notes": "" } ] }
故事粒度规则：每个故事必须能在一次 Ralph 迭代（一个上下文窗口）内完成。Ralph 每次迭代都会启动一个全新的 Amp 实例，不记得之前的工作；故事过大时 LLM 会在完成前耗尽上下文并产出损坏代码。合适的故事包括：添加数据库列与迁移、在现有页面添加 UI 组件、更新服务器操作逻辑、为列表添加筛选下拉框。过大的故事需拆分："构建整个仪表盘"拆分为 schema、查询、UI 组件、筛选；"添加认证"拆分为 schema、中间件、登录 UI、会话处理；"重构 API"按每个端点或模式拆分为一个故事。经验法则：如果无法用 2-3 句话描述变更，它就太大了。
故事排序：按依赖优先。故事按优先级执行，较早的故事不能依赖较晚的故事。正确顺序：schema/数据库变更（迁移）→ 服务器操作/后端逻辑 → 使用后端的 UI 组件 → 聚合数据的仪表盘/摘要视图。错误顺序：UI 组件（依赖尚不存在的 schema）→ schema 变更。
验收标准：必须可验证。每条标准必须是 Ralph 可以检查的，而非模糊描述。好的标准："为 tasks 表添加 status 列，默认 'pending'"、"筛选下拉框选项：All、Active、Completed"、"点击删除显示确认对话框"、"Typecheck passes"、"Tests pass"。坏的标准："正常工作"、"用户可以轻松做 X"、"良好的 UX"、"处理边缘情况"。每个故事末尾始终包含 "Typecheck passes"；有可测试逻辑的故事还包含 "Tests pass"；改变 UI 的故事还包含 "Verify in browser using dev-browser skill"。前端故事在视觉验证前不算完成，Ralph 会使用 dev-browser 技能导航到页面、与 UI 交互并确认更改有效。
转换规则：每个用户故事对应一个 JSON 条目；ID 顺序递增（US-001、US-002 等）；优先级基于依赖顺序，其次按文档顺序；所有故事 passes: false 且 notes 为空；branchName 从功能名派生，kebab-case，前缀 ralph/；每个故事的验收标准都添加 "Typecheck passes"。
拆分大型 PRD：例如原需求 "添加用户通知系统" 拆分为 US-001 添加 notifications 表、US-002 创建通知发送服务、US-003 在头部添加通知铃铛图标、US-004 创建通知下拉面板、US-005 添加标记已读功能、US-006 添加通知偏好设置页。每个都是可独立完成并验证的聚焦变更。
示例：输入 PRD 为 Task Status Feature，要求任务列表可切换 pending/in-progress/done、按状态筛选、显示状态徽章、在数据库中持久化状态。输出 prd.json 包含 project: TaskApp、branchName: ralph/task-status，以及 US-001 添加状态字段到 tasks 表、US-002 在任务卡上显示状态徽章、US-003 为任务列表行添加状态切换、US-004 按状态筛选任务四个故事，各自带有可验证验收标准、递增优先级、passes: false 与空 notes，UI 故事均含 "Verify in browser using dev-browser skill"。
归档之前的运行：写入新 prd.json 前，检查是否存在来自不同功能的现有 prd.json。读取当前 prd.json（如存在）；检查 branchName 是否与新功能分支名不同；如果不同且 progress.txt 内容超过头部，则创建归档文件夹 archive/YYYY-MM-DD-feature-name/，将当前 prd.json 和 progress.txt 复制到归档，并用新头部重置 progress.txt。运行 ralph.sh 脚本时会自动处理；如果在两次运行之间手动更新 prd.json，需先归档。
保存前检查清单：上次运行已归档（若 prd.json 存在且 branchName 不同，先归档）；每个故事可在一次迭代内完成（足够小）；故事按依赖排序（schema 到后端到 UI）；每个故事都有 "Typecheck passes" 标准；UI 故事有 "Verify in browser using dev-browser skill" 标准；验收标准可验证（不模糊）；没有故事依赖后续故事。