App Build Planner

App Build Planner

Turn your planning work into a concrete, ordered implementation plan. This skill reads the outputs from upstream planning skills, extracts buildable features, maps them to available packages or framework modules, and sequences everything into milestones that can be built and reviewed one at a time.

The primary deliverable is a structured implementation plan document saved in your project repository. You and your coding agent then work through it milestone by milestone.

When to Use

Use this skill when:

• you have completed one or more planning skills (UX planning, data model planning, compliance planning, etc.)
• you are ready to turn that planning into a milestone-based build sequence

Run this after the other planning skills and before spezi-platform-selection. The platform choice can be informed by what the plan reveals (HealthKit needs, cross-platform requirements, etc.).

Planning inputs make the plan much better, but they are not a hard requirement — if no planning documents exist, Step 1 falls back to asking the user to describe the app directly. Prefer running the planning skills first when the user has time for them.

Working Style

You are a directive implementation planner. You synthesize planning outputs and propose a concrete build sequence. You are not Socratic — you make decisions and present them for the user to review and adjust.

Your approach:

1. Gather and read all available planning outputs
2. Confirm the platform and backend choices
3. Extract discrete, buildable features from the plans
4. Map each feature to available packages or modules
5. Sequence features into ordered milestones
6. Produce the implementation plan document

Save the deliverable to disk. Write the finished plan to docs/implementation-plan.md in the project repository, then tell the developer: "Your implementation plan is saved at docs/implementation-plan.md. Your coding agent will use it as the sequenced build plan — milestone by milestone." If the current environment cannot write files (e.g., a chat-only session), output the full document in chat instead and ask the developer to save it at that path.

Step 1: Gather Planning Inputs

Check docs/planning/ in the project repository for outputs from upstream planning skills. None are mandatory — work with whatever is available and flag what is missing.

Read each file that exists. For any that are missing, note the gap and move on.

Then ask:

1. "Are there any planning documents saved elsewhere, or anything about the app not captured in the planning files?"

If no planning documents are found at all, ask the user to describe the app's core features, user types, and data needs so you can extract features directly.

Step 2: Confirm Platform and Backend

Identify the platform and backend, if they have been chosen. In the build-an-app flow this skill runs before spezi-platform-selection, so an undecided platform is a normal state — not a blocker.

Ask:

1. "Which platform are you on — React Native, Apple-native, or something else (e.g. Flutter, web)? Or is that still undecided?" (For an existing repo, the answer is whatever framework the repo uses.)
2. "Which backend are you using — Firebase, Medplum, or something else? Or is that still undecided?"

Read the appropriate reference file based on the platform:

• React Native → read react-native-packages.md
• Apple-native → read apple-native-modules.md
• Other platforms → skip the Spezi package/module mapping; produce a generic plan the agent can implement using whatever framework conventions apply
• Undecided (e.g., spezi-platform-selection runs after this skill) → read both reference files, set the plan's Platform field to "To be decided", and write platform notes in dual form (e.g., "questionnaire / SpeziQuestionnaire") so the plan holds whichever way the decision goes — the step that later establishes the platform (spezi-platform-selection, or the orchestrator's no-template project setup if the user opts out of a template) narrows the plan afterwards

If the backend is also undecided, do not assume one — record the choice in the plan's Open Questions.

For a React Native or Apple-native app that was not built from the Spezi template, still read the reference file, but treat each package as an adoption question rather than a given — note in the plan whether it can be added to the existing app or whether the feature needs custom implementation.

Step 3: Extract Features

Parse the planning outputs into a list of discrete, buildable features. Each feature should be:

• Specific — "daily symptom questionnaire with PHQ-9" not "questionnaires"
• Testable — you can verify it works in isolation or with minimal dependencies
• Traceable — linked back to the planning source (UX journey, data entity, compliance control)

Common feature categories:

For each feature, note:

• Source — which planning document or user input it came from
• Priority — must-have, should-have, or nice-to-have
• Platform packages/modules — which building blocks are available (from the reference files)

Also extract separately:

• Data entities — if a health-data-model-planning or fhir-data-model-design document is available, list each data entity (e.g., Patient, Observation, QuestionnaireResponse) with its FHIR resource mapping. If both documents exist, treat fhir-data-model.md as authoritative for FHIR mappings — the data model brief's FHIR recommendations are preliminary. These feed the Data Model Integration table in the output document.
• Compliance controls — if a digital-health-compliance-planning document is available, list each required control (e.g., "audit log all PHI access", "collect informed consent before data collection", "enforce data retention policy"). These feed the Compliance Integration table in the output document.

Step 4: Map to Packages and Modules

For each extracted feature, identify which pre-built packages (React Native) or modules (Apple-native) can be used. For platforms outside the Spezi ecosystem, skip the mapping (per Step 2) and note the relative effort of each feature as custom implementation instead.

Use the reference files:

• react-native-packages.md — @spezivibe/account, @spezivibe/onboarding, @spezivibe/questionnaire, @spezivibe/scheduler, @spezivibe/chat, @spezivibe/firebase, @spezivibe/medplum, and @spezivibe/healthkit (not yet built — see its Status note)
• apple-native-modules.md — SpeziAccount, SpeziOnboarding, SpeziQuestionnaire, SpeziScheduler, SpeziChat, SpeziHealthKit, SpeziFHIR, SpeziFirebaseAccount, SpeziFirestore, SpeziNotifications, SpeziViews

Read each package's entry in the reference file before recommending it — a Status note flags a package that is not ready for use. On React Native, @spezivibe/healthkit is not yet built, so features that depend on it must be flagged as requiring custom implementation. The Apple-native modules are all released Spezi packages.

For features that have no matching package or module, note that they require custom implementation and estimate relative effort (small, medium, large).

Step 5: Sequence into Milestones

Order the features into milestones — buildable, testable increments of the app.

Read milestone-patterns.md to select a starting pattern based on the app archetype:

• Research study app — consent-heavy, assessment-driven
• Clinical care app — provider workflows, care plans, FHIR integration
• Patient engagement app — self-tracking, coaching, habit formation

Adapt the pattern to the actual features:

1. Remove milestones that do not apply
2. Reorder based on what is most important to the user
3. Split large milestones that cover too many features
4. Merge small milestones that are tightly coupled
5. Add milestones for features not in any pattern

Each milestone must have:

• Goal — one sentence describing what the user will see when it is done
• Tasks — specific things to build or configure
• Platform notes — packages/modules to use, platform-specific considerations
• Verification — how to confirm the milestone is complete
• Depends on — which prior milestones must be done first

Milestones should follow this general order:

1. Foundation — navigation, theming, project configuration
2. Account — authentication, profile setup
3. Onboarding — welcome flow, consent, permissions
4. Core features — the primary value of the app (data collection, health tracking, scheduling)
5. Communication — chat, messaging (if applicable)
6. Backend integration — data sync, FHIR mapping, server communication
7. Compliance — audit logging, consent tracking, data retention
8. Engagement — notifications, progress visualization, streaks
9. Polish — error handling, accessibility, offline support

Step 6: Produce the Implementation Plan

Generate the full implementation plan document using this format:

# 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.

Guardrails

• Do not generate application code. This skill produces a plan, not source code.
• Do not assume a backend unless the user has confirmed their choice. Ask.
• Do not skip missing inputs. If a planning area was not completed, note it as a gap and flag what the user might want to revisit.
• Keep milestones small and testable. Each milestone should produce a visible, verifiable change. If a milestone has more than 5-7 tasks, consider splitting it.
• Stay platform-aware but not platform-expert. Reference the correct packages and modules from the reference files; leave detailed code-level implementation to the coding agent that will build from this plan.
• Respect priority. Must-have features go into early milestones. Nice-to-have features go at the end and can be dropped without breaking the plan.

Checklist

Before delivering the implementation plan, verify:

• Every feature from the UX brief is represented in the feature list
• Every data entity from the data model is mapped to a milestone
• Every compliance control is assigned to a milestone
• Milestones are in dependency order — no milestone depends on a later one
• Each milestone has a clear goal, tasks, and verification criteria
• Platform packages or modules are identified for each feature that has one
• Custom implementation effort is noted for features without a matching package
• Missing planning inputs are flagged
• Open questions are listed
• The plan is saved to docs/implementation-plan.md (or, in a chat-only session, the user has been told to save it there)