frontier-os-app-builder 1.0.0

package/templates/app/router.tsx

@@ -0,0 +1,22 @@
+import { createBrowserRouter } from 'react-router-dom';
+import { Layout } from './views/Layout';
+
+// {{ROUTES}}
+// Import your view components and define routes below.
+// Pattern:
+//   import { Home } from './views/Home';
+//   import { Detail } from './views/Detail';
+//
+// Then add route objects to the children array:
+//   { index: true, element: <Home /> },
+//   { path: 'detail/:id', element: <Detail /> },
+
+export const router = createBrowserRouter([
+  {
+    path: '/',
+    element: <Layout />,
+    children: [
+      // {{ROUTES}}
+    ],
+  },
+]);

package/templates/app/sdk-context.tsx

@@ -0,0 +1,33 @@
+import { createContext, useContext, useEffect, useRef, useState, type ReactNode } from 'react';
+import { FrontierSDK } from '@frontiertower/frontier-sdk';
+
+const SdkContext = createContext<FrontierSDK | null>(null);
+
+export const useSdk = (): FrontierSDK => {
+  const sdk = useContext(SdkContext);
+  if (!sdk) throw new Error('useSdk must be used within SdkProvider');
+  return sdk;
+};
+
+export const SdkProvider = ({ children }: { children: ReactNode }) => {
+  const sdkRef = useRef<FrontierSDK | null>(null);
+  const [ready, setReady] = useState(false);
+
+  useEffect(() => {
+    const sdk = new FrontierSDK();
+    sdkRef.current = sdk;
+    setReady(true);
+
+    return () => {
+      sdk.destroy();
+    };
+  }, []);
+
+  if (!ready) return null;
+
+  return (
+    <SdkContext.Provider value={sdkRef.current}>
+      {children}
+    </SdkContext.Provider>
+  );
+};

package/templates/app/test-setup.ts

@@ -0,0 +1,19 @@
+import '@testing-library/jest-dom';
+import { vi } from 'vitest';
+
+// Mock window.open for external links
+vi.stubGlobal('open', vi.fn());
+
+// Mock ResizeObserver
+vi.stubGlobal('ResizeObserver', vi.fn().mockImplementation(() => ({
+  observe: vi.fn(),
+  unobserve: vi.fn(),
+  disconnect: vi.fn(),
+})));
+
+// Mock IntersectionObserver
+vi.stubGlobal('IntersectionObserver', vi.fn().mockImplementation(() => ({
+  observe: vi.fn(),
+  unobserve: vi.fn(),
+  disconnect: vi.fn(),
+})));

package/templates/app/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "skipLibCheck": true,
+    "jsx": "react-jsx",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "types": ["vitest/globals", "@testing-library/jest-dom"]
+  },
+  "include": ["src"],
+  "exclude": ["src/test", "**/*.test.ts", "**/*.test.tsx"]
+}

package/templates/app/vercel.json

@@ -0,0 +1,127 @@
+{
+  "rewrites": [
+    { "source": "/(.*)", "destination": "/index.html" }
+  ],
+  "headers": [
+    {
+      "source": "/(.*)",
+      "has": [
+        {
+          "type": "header",
+          "key": "Origin",
+          "value": "https://os.frontiertower.io"
+        }
+      ],
+      "headers": [
+        {
+          "key": "Access-Control-Allow-Origin",
+          "value": "https://os.frontiertower.io"
+        },
+        {
+          "key": "Access-Control-Allow-Methods",
+          "value": "GET, OPTIONS"
+        },
+        {
+          "key": "Access-Control-Allow-Headers",
+          "value": "Content-Type"
+        }
+      ]
+    },
+    {
+      "source": "/(.*)",
+      "has": [
+        {
+          "type": "header",
+          "key": "Origin",
+          "value": "https://alpha.os.frontiertower.io"
+        }
+      ],
+      "headers": [
+        {
+          "key": "Access-Control-Allow-Origin",
+          "value": "https://alpha.os.frontiertower.io"
+        },
+        {
+          "key": "Access-Control-Allow-Methods",
+          "value": "GET, OPTIONS"
+        },
+        {
+          "key": "Access-Control-Allow-Headers",
+          "value": "Content-Type"
+        }
+      ]
+    },
+    {
+      "source": "/(.*)",
+      "has": [
+        {
+          "type": "header",
+          "key": "Origin",
+          "value": "https://beta.os.frontiertower.io"
+        }
+      ],
+      "headers": [
+        {
+          "key": "Access-Control-Allow-Origin",
+          "value": "https://beta.os.frontiertower.io"
+        },
+        {
+          "key": "Access-Control-Allow-Methods",
+          "value": "GET, OPTIONS"
+        },
+        {
+          "key": "Access-Control-Allow-Headers",
+          "value": "Content-Type"
+        }
+      ]
+    },
+    {
+      "source": "/(.*)",
+      "has": [
+        {
+          "type": "header",
+          "key": "Origin",
+          "value": "https://sandbox.os.frontiertower.io"
+        }
+      ],
+      "headers": [
+        {
+          "key": "Access-Control-Allow-Origin",
+          "value": "https://sandbox.os.frontiertower.io"
+        },
+        {
+          "key": "Access-Control-Allow-Methods",
+          "value": "GET, OPTIONS"
+        },
+        {
+          "key": "Access-Control-Allow-Headers",
+          "value": "Content-Type"
+        }
+      ]
+    },
+    {
+      "source": "/(.*)",
+      "has": [
+        {
+          "type": "header",
+          "key": "Origin",
+          "value": "http://localhost:5173"
+        }
+      ],
+      "headers": [
+        {
+          "key": "Access-Control-Allow-Origin",
+          "value": "http://localhost:5173"
+        },
+        {
+          "key": "Access-Control-Allow-Methods",
+          "value": "GET, OPTIONS"
+        },
+        {
+          "key": "Access-Control-Allow-Headers",
+          "value": "Content-Type"
+        }
+      ]
+    }
+  ]
+}

package/templates/app/vite.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: {{DEV_PORT}},
+  },
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: ['./src/test/setup.ts'],
+    include: ['src/test/**/*.test.{ts,tsx}'],
+  },
+});

package/templates/state/context.md

@@ -0,0 +1,248 @@
+# Context Template
+
+Template for `.frontier-app/phases/XX-name/{phase_num}-CONTEXT.md` — captures implementation decisions for a phase.
+
+**Purpose:** Document decisions that downstream agents need. Planner uses this to know what choices are locked vs flexible. Executor uses this to know what to build.
+
+**Key principle:** Categories emerge from what was actually discussed for THIS phase. An events phase has events-relevant sections, a payments phase has payments-relevant sections.
+
+---
+
+## File Template
+
+```markdown
+# Phase {{PHASE_NUM}}: {{PHASE_NAME}} — Context
+
+**Gathered:** {{DATE}}
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+[Clear statement of what this phase delivers — the scope anchor.
+This comes from ROADMAP.md and is fixed.
+Discussion during /fos:discuss clarifies implementation within this boundary.]
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### [Area 1 that was discussed]
+- **D-01:** [Specific decision made]
+- **D-02:** [Another decision if applicable]
+
+### [Area 2 that was discussed]
+- **D-03:** [Specific decision made]
+
+### SDK Usage
+- **D-XX:** [Which SDK module methods to use and how]
+- **D-YY:** [Data flow: SDK → component state → UI]
+
+### Claude's Discretion
+[Areas where user explicitly said "you decide" — Claude has flexibility here during planning/implementation]
+
+- [Area Claude can decide]
+- [Area Claude can decide]
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+[Any particular references, examples, or "I want it like X" moments from discussion.
+Product references, specific behaviors, interaction patterns, visual references.]
+
+[If none: "No specific requirements — open to standard Frontier OS app patterns"]
+
+</specifics>
+
+<sdk_context>
+## SDK Module Context
+
+### Modules Used in This Phase
+
+| Module | Methods | Purpose |
+|--------|---------|---------|
+| [Module] | [method1(), method2()] | [What they enable] |
+
+### Integration Pattern
+[How SDK data flows into the UI for this phase.
+Example: "Events.list() → React Query → EventList component → EventCard"]
+
+### Known SDK Constraints
+[Any SDK limitations that affect this phase's implementation.
+Example: "Events.list() returns max 50 items — need pagination"]
+
+[If no SDK modules: "No SDK modules in this phase — UI/scaffold only"]
+
+</sdk_context>
+
+<references>
+## References to Read
+
+**Planner and executor MUST read these before working on this phase.**
+
+### SDK Documentation
+- `frontier-sdk/docs/[module].md` — [What this doc covers]
+
+### Existing App Patterns
+- `[app-name]/src/[path]` — [What pattern to reference]
+
+### Project State
+- `.frontier-app/PROJECT.md` — App vision, constraints, SDK modules
+- `.frontier-app/REQUIREMENTS.md` — Requirements this phase addresses
+
+[If no external references: "No external references — requirements fully captured in decisions above"]
+
+</references>
+
+<deferred>
+## Deferred Ideas
+
+[Ideas that came up during /fos:discuss but belong in other phases.
+Captured here so they're not lost, but explicitly out of scope for this phase.]
+
+[If none: "None — discussion stayed within phase scope"]
+
+</deferred>
+
+---
+
+*Phase: XX-name*
+*Context gathered: {{DATE}}*
+```
+
+---
+
+## Good Examples
+
+**Example: Events feature phase**
+
+```markdown
+# Phase 2: Event Listing — Context
+
+**Gathered:** 2026-03-27
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Display upcoming events from the Frontier Events module in a browsable list. Users can view event details and RSVP. Event creation is a separate phase.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Layout
+- **D-01:** Card grid layout, responsive — 1 column mobile, 2 tablet, 3 desktop
+- **D-02:** Each card shows: event name, date/time, location, attendee count, RSVP button
+- **D-03:** Cards sorted by date (soonest first), past events filtered out
+
+### RSVP Flow
+- **D-04:** Single-tap RSVP — no confirmation modal (keep it fast)
+- **D-05:** Optimistic UI update — show RSVP immediately, revert on error
+- **D-06:** RSVP count updates in real-time for all viewers
+
+### Empty State
+- **D-07:** "No upcoming events" with illustration — no CTA to create (that's a different phase)
+
+### SDK Usage
+- **D-08:** Use Events.list() for fetching, Events.rsvp() for RSVP action
+- **D-09:** Poll every 30 seconds for new events (no WebSocket available)
+
+### Claude's Discretion
+- Loading skeleton design
+- Exact card spacing and border radius
+- Error toast styling
+- Animation for RSVP button state change
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- "I want the event cards to feel like Luma's event pages — clean, focused on the key info"
+- RSVP should feel instant — "tap and done, like a Like button"
+
+</specifics>
+
+<sdk_context>
+## SDK Module Context
+
+### Modules Used in This Phase
+
+| Module | Methods | Purpose |
+|--------|---------|---------|
+| Events | Events.list(), Events.rsvp(), Events.get() | Fetch events, handle RSVP |
+
+### Integration Pattern
+Events.list() → React Query with 30s refetch → EventGrid component → EventCard with RSVP button → Events.rsvp() on click → optimistic update
+
+### Known SDK Constraints
+- Events.list() returns max 50 items — sufficient for v1, pagination deferred
+- Events.rsvp() requires user identity from SDK — no anonymous RSVP
+
+</sdk_context>
+
+<references>
+## References to Read
+
+### SDK Documentation
+- `frontier-sdk/docs/events.md` — Events module API, method signatures, return types
+
+### Existing App Patterns
+- `frontier-tower-pwa/src/components/EventCard.tsx` — Card pattern from the main PWA
+
+### Project State
+- `.frontier-app/PROJECT.md` — App vision and SDK modules
+- `.frontier-app/REQUIREMENTS.md` — REQ-01 through REQ-03
+
+</references>
+
+<deferred>
+## Deferred Ideas
+
+- Event creation form — Phase 3
+- Event categories/filtering — add to backlog
+- Calendar view — future milestone
+
+</deferred>
+
+---
+
+*Phase: 02-event-listing*
+*Context gathered: 2026-03-27*
+```
+
+---
+
+## Guidelines
+
+**This template captures DECISIONS for downstream planning and execution.**
+
+The output should answer: "What choices are locked? What's flexible? Which SDK methods to use?"
+
+**Good content (concrete decisions):**
+- "Card grid, 1/2/3 columns responsive"
+- "Use Events.list() with 30s polling"
+- "Optimistic UI for RSVP"
+- "Sort by date, filter out past events"
+
+**Bad content (too vague):**
+- "Should look nice"
+- "Good user experience"
+- "Fast loading"
+- "Use the SDK"
+
+**SDK Module Context is mandatory:**
+- Every Frontier OS app phase that touches SDK modules must document which methods are used
+- Include the data flow: SDK call → state management → UI
+- Note any SDK constraints that affect implementation
+
+**After creation:**
+- File lives in phase directory: `.frontier-app/phases/XX-name/{phase_num}-CONTEXT.md`
+- /fos:plan reads this to create specific tasks
+- /fos:execute reads this to know what choices are locked
+- Downstream agents should NOT need to ask the user again about captured decisions

package/templates/state/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "{{APP_NAME}}",
+  "packageName": "{{PACKAGE_NAME}}",
+  "description": "{{APP_DESCRIPTION}}",
+  "sdkVersion": "{{SDK_VERSION}}",
+  "devPort": {{DEV_PORT}},
+  "modules": [],
+  "permissions": [],
+  "milestone": "v1",
+  "phases": []
+}

package/templates/state/plan.md

@@ -0,0 +1,187 @@
+# Plan Template
+
+Template for `.frontier-app/phases/XX-name/{phase}-{plan}-PLAN.md` — executable plans for Frontier OS app phases.
+
+**Naming:** Use `{phase}-{plan}-PLAN.md` format (e.g., `01-01-PLAN.md` for Phase 1, Plan 1)
+
+---
+
+## File Template
+
+```markdown
+---
+phase: XX-name
+plan: NN
+wave: N
+depends_on: []
+requirements: []
+files_modified: []
+autonomous: true
+
+must_haves:
+  truths: []
+  artifacts: []
+  key_links: []
+---
+
+<objective>
+[What this plan accomplishes for the Frontier OS app]
+
+Purpose: [Why this matters — which feature/capability it delivers]
+Output: [What artifacts will be created]
+SDK Modules: [Which SDK modules are used in this plan, if any]
+</objective>
+
+<execution_context>
+@frontier-os-app-builder/workflows/execute-plan.md
+@frontier-os-app-builder/templates/state/summary.md
+</execution_context>
+
+<context>
+@.frontier-app/PROJECT.md
+@.frontier-app/ROADMAP.md
+@.frontier-app/STATE.md
+
+# SDK reference for modules used in this plan:
+@frontier-sdk/docs/[module].md
+
+# Only reference prior plan SUMMARYs if genuinely needed:
+# - This plan uses types/exports from prior plan
+# - Prior plan made decision affecting this plan
+
+[Relevant source files:]
+@src/path/to/relevant.ts
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: [Action-oriented name]</name>
+  <files>path/to/file.ext, another/file.ext</files>
+  <read_first>path/to/reference.ext, path/to/source-of-truth.ext</read_first>
+  <action>[Specific implementation — what to do, how to do it, what to avoid and WHY.
+  Include CONCRETE values: exact identifiers, parameters, SDK method names, file paths.
+  For SDK usage: specify exact import path, method signature, expected return type.
+  Never say "align X with Y" without specifying the exact target state.]</action>
+  <verify>[Command or check to prove it worked]</verify>
+  <acceptance_criteria>
+    - [Grep-verifiable: "file.ext contains 'FrontierSDK'"]
+    - [Measurable: "component renders without console errors"]
+  </acceptance_criteria>
+  <done>[Measurable acceptance criteria]</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: [Action-oriented name]</name>
+  <files>path/to/file.ext</files>
+  <read_first>path/to/reference.ext</read_first>
+  <action>[Specific implementation with concrete values]</action>
+  <verify>[Command or check]</verify>
+  <acceptance_criteria>
+    - [Grep-verifiable condition]
+  </acceptance_criteria>
+  <done>[Acceptance criteria]</done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>[What Claude built] — dev server at http://localhost:{{DEV_PORT}}</what-built>
+  <how-to-verify>Visit http://localhost:{{DEV_PORT}} and verify:
+  - [Visual check 1]
+  - [Visual check 2]
+  Open Frontier OS at localhost:3000 and verify app loads in iframe.</how-to-verify>
+  <resume-signal>Type "approved" or describe issues</resume-signal>
+</task>
+
+</tasks>
+
+<verification>
+Before declaring plan complete:
+- [ ] `npm run build` succeeds with no errors
+- [ ] `npm run dev` starts without errors on port {{DEV_PORT}}
+- [ ] No TypeScript errors (`npx tsc --noEmit`)
+- [ ] [Plan-specific verification]
+</verification>
+
+<success_criteria>
+
+- All tasks completed
+- All verification checks pass
+- No console errors in browser
+- App renders correctly in dark theme
+- [Plan-specific criteria]
+
+</success_criteria>
+
+<output>
+After completion, create `.frontier-app/phases/XX-name/{phase}-{plan}-SUMMARY.md`
+</output>
+```
+
+---
+
+## Frontmatter Fields
+
+| Field | Required | Purpose |
+|-------|----------|---------|
+| `phase` | Yes | Phase identifier (e.g., `01-scaffold`) |
+| `plan` | Yes | Plan number within phase (e.g., `01`, `02`) |
+| `wave` | Yes | Execution wave (1, 2, 3...) for parallel scheduling |
+| `depends_on` | Yes | Plan IDs this plan requires (e.g., `["01-01"]`) |
+| `requirements` | Yes | Requirement IDs this plan addresses (PLAT-01, REQ-03, etc.) |
+| `files_modified` | Yes | Files this plan creates or modifies |
+| `autonomous` | Yes | `true` if no checkpoints, `false` if has user verification |
+| `must_haves` | Yes | Goal-backward verification criteria |
+
+---
+
+## Frontier OS Specifics
+
+**Phase 1 plans always include:**
+- Vite scaffold from `templates/app/vite.config.ts`
+- SdkProvider from `templates/app/sdk-context.tsx`
+- Layout with iframe detection from `templates/app/layout.tsx`
+- Dark theme setup via Tailwind
+- Standalone fallback UI
+- Dev server on assigned port
+
+**SDK usage in tasks:**
+- Always specify the exact import: `import { FrontierSDK } from '@frontiertower/frontier-sdk'`
+- Always use `useSdk()` hook, never instantiate SDK directly in components
+- Always wrap SDK calls in try/catch — SDK may not be available in standalone mode
+- Reference the specific SDK module docs in `<context>` section
+
+**Verification always includes:**
+- Build succeeds (`npm run build`)
+- Dev server starts on correct port
+- No TypeScript errors
+- Dark theme renders correctly (no white backgrounds)
+- App works in both iframe and standalone modes
+
+---
+
+## Task Types
+
+| Type | Use For | Autonomy |
+|------|---------|----------|
+| `auto` | Everything Claude can do independently | Fully autonomous |
+| `checkpoint:human-verify` | Visual verification in browser/iframe | Pauses for user |
+| `checkpoint:decision` | Implementation choices needing user input | Pauses for user |
+
+---
+
+## Scope Guidance
+
+**Plan sizing:**
+- 2-3 tasks per plan
+- Phase 1 (scaffold): Always 1 plan
+- Feature phases: 1-3 plans depending on complexity
+
+**Vertical slices preferred:**
+```
+PREFER: Plan 01 = Event listing (model + API hook + UI component)
+        Plan 02 = Event creation (form + validation + SDK call)
+
+AVOID:  Plan 01 = All data models
+        Plan 02 = All API hooks
+        Plan 03 = All UI components
+```