frontier-os-app-builder 1.0.0

package/templates/state/project.md

@@ -0,0 +1,118 @@
+# PROJECT.md Template
+
+Template for `.frontier-app/PROJECT.md` — the living app context document.
+
+<template>
+
+```markdown
+# {{APP_NAME}}
+
+## What This Is
+
+{{APP_DESCRIPTION}}
+
+[2-3 sentences. What does this app do and who is it for within the Frontier ecosystem?
+Use the user's language and framing. Update whenever reality drifts from this description.]
+
+## Core Value
+
+[The ONE thing that matters most. If everything else fails, this must work.
+One sentence that drives prioritization when tradeoffs arise.]
+
+## SDK Modules
+
+| Module | Why Needed | Key APIs |
+|--------|-----------|----------|
+| [Module] | [What it enables for this app] | [Primary methods used] |
+
+[Only modules this app actually uses. Each must have a clear reason.
+Common modules: Events, Wallet, Identity, Storage, Notifications, Social, Commerce.]
+
+## Target Users
+
+[Who uses this app? Be specific to the Frontier ecosystem.
+- Primary users: [Who and what they want]
+- Secondary users: [If applicable]
+- Non-users: [Who this is NOT for — prevents scope creep]]
+
+## Constraints
+
+These are hard limits on all implementation choices:
+
+- **Runtime**: Runs inside Frontier OS iframe — no direct DOM access to parent, postMessage communication only
+- **Theme**: Dark theme mandatory — must match Frontier OS visual language
+- **SDK**: All platform features via `@frontiertower/frontier-sdk` — no direct API calls to Frontier services
+- **Auth**: Identity provided by Frontier OS — no custom auth flows
+- **CORS**: All external API calls must handle CORS (app runs in iframe on different origin)
+- **Standalone**: Must detect iframe vs standalone and degrade gracefully
+- **[App-specific]**: [What] — [Why]
+
+## Key Decisions
+
+<!-- Decisions that constrain future work. Add throughout project lifecycle. -->
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| [Choice] | [Why] | [Pending] |
+
+---
+*Last updated: {{DATE}} after {{TRIGGER}}*
+```
+
+</template>
+
+<guidelines>
+
+**What This Is:**
+- Current accurate description of the app
+- 2-3 sentences capturing what it does and who it's for
+- Use the user's words and framing
+- Update when the app evolves beyond this description
+
+**Core Value:**
+- The single most important thing this app does
+- Everything else can fail; this cannot
+- Drives prioritization when tradeoffs arise
+- Rarely changes; if it does, it's a significant pivot
+
+**SDK Modules:**
+- Only list modules the app actually uses
+- Each module must have a clear reason (not "might need later")
+- Key APIs column helps planner and executor know which methods to use
+- Updated when new modules are added or removed during development
+
+**Target Users:**
+- Specific to Frontier ecosystem (members, operators, admins)
+- Include non-users to prevent scope creep
+- Informs UX decisions throughout development
+
+**Constraints:**
+- The first 6 constraints are ALWAYS present for every Frontier OS app
+- App-specific constraints added during /fos:new-app
+- Include the "why" — constraints without rationale get questioned
+
+**Key Decisions:**
+- Significant choices that affect future work
+- Added during /fos:discuss phases
+- Track outcome when known:
+  - Good — decision proved correct
+  - Revisit — decision may need reconsideration
+  - Pending — too early to evaluate
+
+</guidelines>
+
+<evolution>
+
+**After each phase transition:**
+1. SDK modules still accurate? Update if new modules needed or old ones dropped
+2. Decisions to log? Add to Key Decisions
+3. "What This Is" still accurate? Update if drifted
+4. Constraints changed? (rare — usually only app-specific ones)
+
+**After each milestone:**
+1. Full review of all sections
+2. Core Value check — still the right priority?
+3. Target Users check — did the audience shift?
+4. SDK Modules audit — any unused modules to remove?
+
+</evolution>

package/templates/state/requirements.md

@@ -0,0 +1,133 @@
+# Requirements Template
+
+Template for `.frontier-app/REQUIREMENTS.md` — checkable requirements that define "done."
+
+<template>
+
+```markdown
+# Requirements: {{APP_NAME}}
+
+**Defined:** {{DATE}}
+**Core Value:** [from PROJECT.md]
+
+## {{MILESTONE_VERSION}} Requirements
+
+Requirements for this milestone. Each maps to roadmap phases.
+
+### Platform Integration (Standard)
+
+Every Frontier OS app ships with these. Non-negotiable.
+
+- [ ] **PLAT-01**: App detects iframe context and adjusts behavior accordingly
+- [ ] **PLAT-02**: App renders correctly in standalone mode as fallback
+- [ ] **PLAT-03**: App uses dark theme matching Frontier OS visual language
+- [ ] **PLAT-04**: All external API calls handle CORS correctly
+- [ ] **PLAT-05**: SdkProvider wraps the entire app, SDK initializes on mount
+
+### [Feature Category 1]
+
+- [ ] **REQ-01**: [Requirement description — user-centric, testable, atomic]
+- [ ] **REQ-02**: [Requirement description]
+- [ ] **REQ-03**: [Requirement description]
+
+### [Feature Category 2]
+
+- [ ] **REQ-04**: [Requirement description]
+- [ ] **REQ-05**: [Requirement description]
+
+### [Feature Category N]
+
+- [ ] **REQ-NN**: [Requirement description]
+
+## Future Milestone Requirements
+
+Deferred to a later milestone. Tracked but not in current roadmap.
+
+### [Category]
+
+- **REQ-XX**: [Requirement description]
+- **REQ-YY**: [Requirement description]
+
+## Out of Scope
+
+Explicitly excluded. Documented to prevent scope creep.
+
+| Feature | Reason |
+|---------|--------|
+| Custom auth flows | Identity provided by Frontier OS |
+| Direct API calls to Frontier services | Must use SDK — no bypassing the access layer |
+| [Feature] | [Why excluded] |
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| PLAT-01 | Phase 1 | Pending |
+| PLAT-02 | Phase 1 | Pending |
+| PLAT-03 | Phase 1 | Pending |
+| PLAT-04 | Phase 1 | Pending |
+| PLAT-05 | Phase 1 | Pending |
+| REQ-01 | Phase [N] | Pending |
+
+**Coverage:**
+- Total requirements: [X]
+- Mapped to phases: [Y]
+- Unmapped: [Z]
+
+---
+*Requirements defined: {{DATE}}*
+*Last updated: {{DATE}} after {{TRIGGER}}*
+```
+
+</template>
+
+<guidelines>
+
+**Standard Platform Requirements:**
+- PLAT-01 through PLAT-05 are ALWAYS included for every Frontier OS app
+- They always map to Phase 1 (Scaffold + SDK Core)
+- They are non-negotiable — an app without these cannot run in Frontier OS
+
+**Requirement Format:**
+- ID: `[CATEGORY]-[NUMBER]` (REQ-01, WALL-02, EVNT-03)
+- Description: User-centric, testable, atomic
+- Checkbox: Only for current milestone requirements (future milestones are not yet actionable)
+
+**Categories:**
+- Derive from the app's feature areas
+- Keep consistent with SDK module names where applicable
+- PLAT = platform integration (always first, always standard)
+
+**Out of Scope:**
+- The first two exclusions (custom auth, direct API calls) are ALWAYS present
+- Add app-specific exclusions during /fos:new-app
+- Include reasoning to prevent re-adding later
+
+**Traceability:**
+- PLAT requirements always map to Phase 1
+- Feature requirements map to subsequent phases
+- Updated during roadmap creation and after each phase completes
+
+**Status Values:**
+- Pending: Not started
+- In Progress: Phase is active
+- Complete: Requirement verified
+- Blocked: Waiting on external factor
+
+</guidelines>
+
+<evolution>
+
+**After each phase completes:**
+1. Mark covered requirements as Complete
+2. Update traceability status
+3. Note any requirements that changed scope
+
+**After roadmap updates:**
+1. Verify all current milestone requirements are mapped
+2. Add new requirements if scope expanded
+3. Move requirements to future milestone or out of scope if descoped
+
+</evolution>

package/templates/state/roadmap.md

@@ -0,0 +1,129 @@
+# Roadmap Template
+
+Template for `.frontier-app/ROADMAP.md` — the phased build plan.
+
+<template>
+
+```markdown
+# Roadmap: {{APP_NAME}}
+
+## Overview
+
+[One paragraph describing the journey from scaffold to shipped app.
+What makes this app worth building and what does the finished product look like?]
+
+## {{MILESTONE_VERSION}} Phases
+
+- [ ] **Phase 1: Scaffold + SDK Core** — Project setup, SdkProvider, iframe detection, dark theme, standalone fallback
+- [ ] **Phase 2: [Feature Name]** — [One-line description]
+- [ ] **Phase 3: [Feature Name]** — [One-line description]
+- [ ] **Phase N: [Feature Name]** — [One-line description]
+
+## Phase Details
+
+### Phase 1: Scaffold + SDK Core
+**Goal**: Working app shell with SDK connected, running in iframe and standalone
+**Depends on**: Nothing (always first)
+**Requirements**: PLAT-01, PLAT-02, PLAT-03, PLAT-04, PLAT-05
+**Success Criteria** (what must be TRUE):
+  1. App renders inside Frontier OS iframe without errors
+  2. App detects standalone mode and shows appropriate fallback UI
+  3. Dark theme applied — no white backgrounds, no light-mode artifacts
+  4. SdkProvider initializes and useSdk() returns a valid SDK instance
+  5. Dev server runs on assigned port with HMR working
+**Plans**: 1 plan
+
+Plans:
+- [ ] 01-01: Vite + React scaffold, SdkProvider, iframe detection, dark theme, dev config
+
+### Phase 2: [Feature Name]
+**Goal**: [What this phase delivers — one sentence]
+**Depends on**: Phase 1
+**Requirements**: [REQ-01, REQ-02, REQ-03]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
+  3. [Observable behavior from user perspective]
+**Plans**: [Number of plans or TBD]
+
+Plans:
+- [ ] 02-01: [Brief description of first plan]
+- [ ] 02-02: [Brief description of second plan]
+
+### Phase N: [Feature Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Phase [N-1]
+**Requirements**: [REQ-XX, REQ-YY]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
+**Plans**: [Number of plans or TBD]
+
+Plans:
+- [ ] NN-01: [Brief description]
+
+## Progress
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. Scaffold + SDK Core | 0/1 | Not started | - |
+| 2. [Name] | 0/N | Not started | - |
+| N. [Name] | 0/N | Not started | - |
+
+---
+*Roadmap created: {{DATE}}*
+*Last updated: {{DATE}} after {{TRIGGER}}*
+```
+
+</template>
+
+<guidelines>
+
+**Phase 1 is always the same:**
+- "Scaffold + SDK Core" — never skip, never rename
+- Covers all PLAT-* requirements
+- Always 1 plan (the scaffold is well-defined)
+- Success criteria are standardized (see template)
+- Uses templates from `templates/app/` directory
+
+**Phase structure:**
+- Phase 1: Scaffold (always)
+- Phases 2-N: Feature phases (from requirements)
+- Keep to 3-6 total phases for v1 — ship fast
+- Each phase delivers something coherent and testable
+
+**Success criteria:**
+- 2-5 observable behaviors per phase
+- Written from user perspective ("User can..." or "[Thing] works")
+- Cross-checked against requirements during creation
+- Flow downstream to `must_haves` in PLAN.md
+- Verified after execution
+
+**Plans within phases:**
+- Phase 1 always has 1 plan
+- Feature phases have 1-3 plans depending on complexity
+- Plans use naming: {phase}-{plan}-PLAN.md (e.g., 02-01-PLAN.md)
+- Plan count can be "TBD" initially, refined during /fos:plan
+
+**Progress tracking:**
+- Updated after each plan completes
+- Status values: Not started, In progress, Complete, Deferred
+
+</guidelines>
+
+<frontier_specifics>
+
+**Phase 1 always generates from templates:**
+- `templates/app/vite.config.ts` → configured with app's dev port
+- `templates/app/sdk-context.tsx` → SdkProvider + useSdk hook
+- `templates/app/layout.tsx` → dark theme shell with iframe detection
+- `templates/app/main-simple.tsx` or `main-router.tsx` → entry point
+- `templates/app/tsconfig.json` → TypeScript config
+- `templates/app/postcss.config.js` → Tailwind setup
+
+**Feature phases should reference SDK modules:**
+- If a phase uses Events module, note it in the goal
+- If a phase uses Wallet module, note it in the goal
+- This helps the planner know which SDK APIs to use
+
+</frontier_specifics>

package/templates/state/state.md

@@ -0,0 +1,131 @@
+# State Template
+
+Template for `.frontier-app/STATE.md` — the app's living memory that bridges `/clear` boundaries.
+
+<template>
+
+```markdown
+---
+milestone: {{MILESTONE_VERSION}}
+phase: {{CURRENT_PHASE}}
+plan: {{CURRENT_PLAN}}
+status: {{STATUS}}
+next_action: {{NEXT_ACTION}}
+---
+
+# App State
+
+## Current Position
+
+Phase: [X] of [Y] ([Phase name])
+Plan: [A] of [B] in current phase
+Status: [Ready to discuss / Discussing / Ready to plan / Planning / Ready to execute / Executing / Phase complete]
+Last activity: [YYYY-MM-DD] — [What happened]
+
+Progress: [░░░░░░░░░░] 0%
+
+## App Reference
+
+See: .frontier-app/PROJECT.md (updated [date])
+
+**App:** [App name]
+**Core value:** [One-liner from PROJECT.md]
+**SDK Modules:** [Comma-separated list of active modules]
+**Dev port:** [Port number]
+
+## Recent Decisions
+
+Decisions affecting current work (full log in PROJECT.md):
+
+- [Phase X]: [Decision summary]
+
+## Blockers
+
+[Issues that affect current or future work]
+
+None yet.
+
+## Metrics
+
+**Velocity:**
+- Plans completed: [N]
+- Average duration: [X] min
+
+**By Phase:**
+
+| Phase | Plans | Avg/Plan |
+|-------|-------|----------|
+| - | - | - |
+
+## Session Continuity
+
+Last session: [YYYY-MM-DD HH:MM]
+Stopped at: [Description of last completed action]
+Next command: [/fos:discuss N, /fos:plan N, /fos:execute N, /fos:ship]
+```
+
+</template>
+
+<purpose>
+
+STATE.md is the app's short-term memory spanning all phases and sessions.
+
+**Problem it solves:** After `/clear`, Claude has no memory. STATE.md is read first by every /fos: command to know where the project stands.
+
+**Solution:** A single, small file (under 100 lines) that:
+- Is read first in every workflow
+- Is updated after every significant action
+- Contains digest of accumulated context
+- Tells Claude exactly what command to run next
+
+</purpose>
+
+<frontmatter>
+
+The YAML frontmatter enables machine parsing by workflows:
+
+| Field | Values | Purpose |
+|-------|--------|---------|
+| `milestone` | v1, v2, ... | Current milestone version |
+| `phase` | 1, 2, 3, ... | Current phase number |
+| `plan` | 01, 02, ... | Current plan within phase |
+| `status` | ready-to-discuss, discussing, ready-to-plan, planning, ready-to-execute, executing, phase-complete, milestone-complete | Machine-readable state |
+| `next_action` | /fos:discuss N, /fos:plan N, /fos:execute N, /fos:ship | Exact command to run next |
+
+</frontmatter>
+
+<lifecycle>
+
+**Creation:** After ROADMAP.md is created during /fos:new-app
+- Reference PROJECT.md for app context
+- Initialize empty sections
+- Set position to "Phase 1 ready to discuss"
+- Set next_action to "/fos:discuss 1"
+
+**Reading:** First step of EVERY /fos: command
+- /fos:discuss — know which phase to discuss
+- /fos:plan — know which phase to plan, read recent decisions
+- /fos:execute — know current position, which plan to run
+- /fos:status — present full state to user
+- /fos:next — read next_action and route
+
+**Writing:** After every significant action
+- After discuss: Update status, log decisions, set next_action to /fos:plan
+- After plan: Update status, set next_action to /fos:execute
+- After execute: Update position, metrics, set next_action
+- After phase complete: Advance phase, update progress bar
+
+</lifecycle>
+
+<size_constraint>
+
+Keep STATE.md under 100 lines.
+
+It's a DIGEST, not an archive. If accumulated context grows too large:
+- Keep only 3-5 recent decisions (full log in PROJECT.md)
+- Keep only active blockers, remove resolved ones
+- Metrics are summary only — details in SUMMARY.md files
+
+The goal is "read once, know where we are" — if it's too long, that fails.
+
+</size_constraint>