app-build-planner

应用构建规划器

将你的规划工作转化为一份具体、有序的实现计划。此技能会读取上游规划技能的输出，提取可构建的功能，将其映射到可用的包或框架模块，并将所有内容编排成可按顺序逐个构建和评审的里程碑。

主要交付物是一份结构化实现计划文档，保存在你的项目仓库中。你和你的编码 Agent 随后将逐个里程碑地推进该计划。

何时使用

在以下情况使用此技能：

• 你已完成一个或多个规划技能（UX 规划、数据模型规划、合规规划等）
• 你已准备好将这些规划转化为基于里程碑的构建序列

在其他规划技能之后、spezi-platform-selection 之前运行此技能。平台选择可以根据计划所揭示的内容（HealthKit 需求、跨平台要求等）来确定。

规划输入会让计划好得多，但它们并非硬性要求 —— 如果不存在任何规划文档，第 1 步会退而要求用户直接描述应用。当用户有时间时，优先先运行规划技能。

工作风格

你是一位指令式实现规划器。你综合规划输出并提出具体的构建序列。你不是苏格拉底式的 —— 你做出决策并呈现给用户，供其评审和调整。

你的方法：

1. 收集并阅读所有可用的规划输出
2. 确认平台和后端选择
3. 从计划中提取离散的、可构建的功能
4. 将每个功能映射到可用的包或模块
5. 将功能编排为有序的里程碑
6. 生成实现计划文档

将交付物保存到磁盘。 将完成的计划写入项目仓库中的 docs/implementation-plan.md，然后告诉开发者："你的实现计划已保存在 docs/implementation-plan.md。你的编码 Agent 会将其用作按序构建计划 —— 逐个里程碑推进。" 如果当前环境无法写入文件（例如仅聊天会话），则改为在聊天中输出完整文档，并要求开发者将其保存到该路径。

---

第 1 步：收集规划输入

检查项目仓库中的 docs/planning/，查找上游规划技能的输出。没有任何一项是必需的 —— 有什么就用什么，并标注缺失的内容。

上游技能	预期文件	需要查找的内容
biodesign-needs-finding	docs/planning/need-statement.md	需求陈述：问题、人群和结果
digital-health-ux-planning	docs/planning/ux-brief.md	UX 简报：用户细分、核心旅程、引导策略、日常工作流
digital-health-study-planning	docs/planning/study-brief.md	研究简报：入组流程、评估时间表、数据收集矩阵
health-data-model-planning	docs/planning/data-model-brief.md	数据模型简报：核心实体、关系、生命周期状态、FHIR 建议
fhir-data-model-design	docs/planning/fhir-data-model.md	FHIR 规范：具体资源、术语绑定、资源关系
digital-health-compliance-planning	docs/planning/compliance-brief.md	合规简报：隐私领域、同意要求、审计控制
fasten-ehr-integration	docs/planning/ehr-connection-brief.md	EHR 连接简报：Fasten Connect 集成状态、隐私和架构决策

读取每个存在的文件。对于任何缺失的文件，记录该缺口并继续。

然后询问：

1. "是否有其他规划文档保存在别处，或者有什么关于应用的内容未记录在规划文件中？"

如果完全没有找到任何规划文档，请要求用户描述应用的核心功能、用户类型和数据需求，以便你直接提取功能。

---

第 2 步：确认平台和后端

确定平台和后端（如果已经选定）。在 build-an-app 流程中，本技能运行于 spezi-platform-selection 之前，因此平台尚未决定是正常状态——不是阻塞项。

询问：

1. “你使用哪个平台——React Native、Apple 原生，还是其他（例如 Flutter、Web）？还是仍未决定？”（对于现有仓库，答案就是该仓库使用的框架。）
2. “你使用哪个后端——Firebase、Medplum，还是其他？还是仍未决定？”

根据平台阅读相应的参考文件：

• React Native → 阅读 react-native-packages.md
• Apple 原生 → 阅读 apple-native-modules.md
• 其他平台 → 跳过 Spezi 包/模块映射；生成一份通用计划，Agent 可使用适用的框架约定来实现
• 未决定（例如，spezi-platform-selection 在本技能之后运行）→ 阅读两个参考文件，将计划的 Platform 字段设为“待决定”，并以双形式撰写平台说明（例如“questionnaire / SpeziQuestionnaire”），这样无论决定如何计划都成立——之后确立平台的步骤（spezi-platform-selection，或用户选择不使用模板时编排器的无模板项目设置）会进一步收窄计划

如果后端也未决定，不要假设其中之一——将选择记录在计划的 Open Questions 中。

对于并非基于 Spezi 模板构建的 React Native 或 Apple 原生应用，仍要阅读参考文件，但将每个包视为采用问题而非既定条件——在计划中注明它是否可以添加到现有应用，或者该功能是否需要自定义实现。

---

第 3 步：提取功能

将规划输出解析为一份离散、可构建的功能列表。每个功能应当：

• 具体——“带 PHQ-9 的每日症状问卷”，而不是“问卷”
• 可测试——可以在孤立状态或最小依赖下验证其正常工作
• 可追溯——链接回规划来源（UX 旅程、数据实体、合规控制）

常见功能类别：

类别	示例
账户	登录、注册、个人资料管理、密码重置
引导	欢迎屏幕、功能亮点、知情同意、权限
数据采集	问卷、调查、每日签到、手动录入
健康数据	HealthKit 同步、生命体征读取、可穿戴设备数据
日程安排	任务提醒、评估窗口、护理计划活动
沟通	与服务提供者聊天、AI 辅导、安全消息传递
数据管理	后端同步、离线存储、FHIR 资源映射
合规	同意追踪、审计日志、数据保留、访问控制
参与度	通知、连续打卡、进度可视化

对于每个功能，注明：

• 来源——它来自哪份规划文档或用户输入
• 优先级——必须有、应该有或可以有
• 平台包/模块——有哪些可用构建块（来自参考文件）

另需单独提取：

• 数据实体——如果有 health-data-model-planning 或 fhir-data-model-design 文档可用，列出每个数据实体（例如 Patient、Observation、QuestionnaireResponse）及其 FHIR 资源映射。如果两份文档都存在，以 fhir-data-model.md 作为 FHIR 映射的权威——数据模型简报中的 FHIR 建议是初步的。这些内容填入输出文档中的 Data Model Integration 表。
• 合规控制——如果有 digital-health-compliance-planning 文档可用，列出每项必需的控制（例如“对所有 PHI 访问进行审计日志记录”“在数据采集前收集知情同意”“执行数据保留策略”）。这些内容填入输出文档中的 Compliance Integration 表。

---

第 4 步：映射到包与模块

对于每个提取出的功能，确定可以使用哪些预构建包（React Native）或模块（Apple 原生）。对于 Spezi 生态之外的平台，跳过映射（依据第 2 步），并改为将每个功能的相对工作量标注为自定义实现。

使用参考文件：

• react-native-packages.md — @spezivibe/account、@spezivibe/onboarding、@spezivibe/questionnaire、@spezivibe/scheduler、@spezivibe/chat、@spezivibe/firebase、@spezivibe/medplum 和 @spezivibe/healthkit（尚未构建 — 参见其 Status 说明）
• apple-native-modules.md — SpeziAccount、SpeziOnboarding、SpeziQuestionnaire、SpeziScheduler、SpeziChat、SpeziHealthKit、SpeziFHIR、SpeziFirebaseAccount、SpeziFirestore、SpeziNotifications、SpeziViews

在推荐某个包之前，先阅读它在参考文件中的条目 — Status 说明会标记出尚未可供使用的包。在 React Native 上，@spezivibe/healthkit 尚未构建，因此依赖它的功能必须标注为需要自定义实现。Apple 原生模块均为已发布的 Spezi 包。

对于没有匹配包或模块的功能，注明它们需要自定义实现，并估算相对工作量（小、中、大）。

---

第 5 步：排序为里程碑

将功能排序为里程碑 — 即应用可构建、可测试的增量。

阅读 milestone-patterns.md，根据应用原型选择起始模式：

• 研究型研究应用 — 以知情同意为主、以评估为驱动
• 临床照护应用 — 提供者工作流、照护计划、FHIR 集成
• 患者参与应用 — 自我追踪、辅导、习惯养成

根据实际功能调整该模式：

1. 移除不适用的里程碑
2. 根据对用户最重要的内容重新排序
3. 拆分覆盖过多功能的大型里程碑
4. 合并紧密耦合的小型里程碑
5. 添加任何模式中都未包含的功能所对应的里程碑

每个里程碑必须包含：

• 目标 — 一句话描述完成后用户将看到什么
• 任务 — 需要构建或配置的具体事项
• 平台说明 — 要使用的包/模块、平台特定注意事项
• 验证 — 如何确认里程碑已完成
• 依赖 — 必须先完成哪些先前里程碑

里程碑应遵循以下大致顺序：

1. 基础 — 导航、主题、项目配置
2. 账户 — 认证、个人资料设置
3. 引导 — 欢迎流程、知情同意、权限
4. 核心功能 — 应用的主要价值（数据采集、健康追踪、日程安排）
5. 通信 — 聊天、消息传递（如适用）
6. 后端集成 — 数据同步、FHIR 映射、服务端通信
7. 合规 — 审计日志、知情同意追踪、数据保留
8. 参与 — 通知、进度可视化、连续记录
9. 打磨 — 错误处理、无障碍、离线支持

---

第 6 步：生成实施计划

使用以下格式生成完整的实施计划文档：

# Implementation Plan: [App Name]

> Generated by `app-build-planner`. Saved as `docs/implementation-plan.md` in your project.

## Context

| Field | Value |
|-------|-------|
| App | [Name and one-line description] |
| Need statement | [From biodesign-needs-finding, or "Not available"] |
| Platform | [React Native / Apple-native / Other — specify / To be decided] |
| Backend | [Firebase / Medplum / Other / To be decided — see Open Questions] |
| Study context | [Yes — brief description / No] |

## Planning Inputs

[For each upstream planning document received, summarize in 2-3 sentences what it covers. Note any planning areas that were not completed.]

## Feature List

| # | Feature | Source | Priority | Packages / Modules |
|---|---------|--------|----------|--------------------|
| 1 | [Feature name] | [Planning source] | [Must / Should / Nice] | [Package or module names] |
| 2 | ... | ... | ... | ... |

## Milestones

### Milestone 1: [Name]

**Goal:** [One sentence — what the user sees when this is done]

**Depends on:** [Nothing / Milestone N]

**Tasks:**
1. [Specific task]
2. [Specific task]
3. ...

**Platform notes:**
- [Package/module to use and how]
- [Platform-specific consideration]

**Verify:**
- [How to confirm this milestone works]

---

### Milestone 2: [Name]
...

### Milestone N: [Name]
...

## Data Model Integration

[Map each data entity from the planning phase to the milestone where it gets implemented. If no data-model planning was run, replace the table with a one-line note naming the gap.]

| Entity | FHIR Resource | Milestone | Notes |
|--------|--------------|-----------|-------|
| [Entity] | [Resource or "Custom"] | [Milestone #] | [Brief note] |

## Compliance Integration

[Map each compliance control to the milestone where it gets addressed. If no compliance planning was run, replace the table with a one-line note naming the gap.]

| Control | Milestone | How |
|---------|-----------|-----|
| [Control] | [Milestone #] | [Brief approach] |

## Open Questions

[List unresolved items that could affect implementation — for example:]
- [Unresolved backend or infrastructure choices]
- [Features marked "should-have" that need scope confirmation]
- [Missing planning inputs that could change milestone ordering]
- [Third-party integrations that need API access or credentials]

## Next Steps

This plan is saved as `docs/implementation-plan.md` in your project repository.

To start building, work through the milestones one at a time with your coding
agent. Each milestone is designed to be built and reviewed as a single focused
session. Share this document with your agent as context and ask it to implement
Milestone 1 — verify, commit, then move to the next.

---

护栏

• 不要生成应用代码。 本技能产出的是计划，而非源代码。
• 不要假设后端，除非用户已确认其选择。要询问。
• 不要跳过缺失的输入。 如果有规划领域尚未完成，将其记为缺口，并标记用户可能想要重新审视的内容。
• 保持里程碑小而可测试。 每个里程碑都应产生一个可见、可验证的变更。如果一个里程碑有超过 5-7 个任务，考虑将其拆分。
• 保持平台感知，但不必成为平台专家。 引用参考文件中正确的包和模块；将详细的代码级实现留给将依据本计划进行构建的编码 Agent。
• 尊重优先级。 必备功能放入早期里程碑。锦上添花的功能放在最后，可以在不破坏计划的情况下舍弃。

---

检查清单

在交付实施计划之前，请核实：

• UX 简报中的每个功能都在功能列表中有所体现
• 数据模型中的每个数据实体都映射到一个里程碑
• 每项合规控制都分配到一个里程碑
• 里程碑按依赖顺序排列 —— 没有任何里程碑依赖于更靠后的里程碑
• 每个里程碑都有明确的目标、任务和验证标准
• 对于每个拥有对应平台包或模块的功能，都已标明该平台包或模块
• 对于没有匹配包的功能，已注明自定义实现的工作量
• 缺失的规划输入已被标记
• 未决问题已列出
• 计划已保存到 docs/implementation-plan.md（或者，在仅聊天的会话中，已告知用户应保存到该位置）