frontier-os-app-builder 1.0.0

package/templates/state/summary.md

@@ -0,0 +1,273 @@
+# Summary Template
+
+Template for `.frontier-app/phases/XX-name/{phase}-{plan}-SUMMARY.md` — plan completion documentation.
+
+---
+
+## File Template
+
+```markdown
+---
+phase: XX-name
+plan: NN
+subsystem: [primary category: scaffold, ui, feature, integration, sdk-module, etc.]
+tags: [searchable tech: react, vite, tailwind, frontier-sdk, events, wallet]
+
+requires:
+  - phase: [prior phase this depends on]
+    provides: [what that phase built that this uses]
+provides:
+  - [bullet list of what this plan built/delivered]
+affects: [list of phase names that will need this context]
+
+tech-stack:
+  added: [libraries/tools added]
+  patterns: [patterns established]
+
+key-files:
+  created: [important files created]
+  modified: [important files modified]
+
+key-decisions:
+  - "Decision 1"
+  - "Decision 2"
+
+patterns-established:
+  - "Pattern 1: description"
+  - "Pattern 2: description"
+
+sdk-modules-used: []
+
+requirements-completed: []
+
+duration: Xmin
+completed: YYYY-MM-DD
+---
+
+# Phase [X]: [Name] — Plan [Y] Summary
+
+**[Substantive one-liner — NOT "phase complete" or "scaffold done"]**
+
+## Performance
+
+- **Duration:** [time]
+- **Started:** [ISO timestamp]
+- **Completed:** [ISO timestamp]
+- **Tasks:** [count completed]
+- **Files modified:** [count]
+
+## Accomplishments
+
+- [Most important outcome]
+- [Second key accomplishment]
+- [Third if applicable]
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: [name]** — `abc123f` (feat/fix/scaffold)
+2. **Task 2: [name]** — `def456g` (feat/fix/test)
+
+## Files Created/Modified
+
+- `src/App.tsx` — What it does
+- `src/lib/sdk-context.tsx` — What it does
+
+## SDK Integration Notes
+
+[How SDK modules were integrated, any gotchas, patterns established for SDK usage.
+Or "No SDK module integration in this plan" if scaffold-only.]
+
+## Decisions Made
+
+[Key decisions with brief rationale, or "None — followed plan as specified"]
+
+## Deviations from Plan
+
+[If no deviations: "None — plan executed exactly as written"]
+
+[If deviations occurred:]
+
+### Auto-fixed Issues
+
+**1. [Category] Brief description**
+- **Found during:** Task [N] ([task name])
+- **Issue:** [What was wrong]
+- **Fix:** [What was done]
+- **Files modified:** [file paths]
+- **Verification:** [How it was verified]
+
+---
+
+**Total deviations:** [N] auto-fixed
+**Impact on plan:** [Brief assessment]
+
+## Issues Encountered
+
+[Problems and how they were resolved, or "None"]
+
+## Verification Results
+
+- [ ] Build: [pass/fail]
+- [ ] Dev server: [pass/fail on port XXXX]
+- [ ] TypeScript: [pass/fail]
+- [ ] Dark theme: [pass/fail]
+- [ ] Iframe mode: [pass/fail or N/A]
+- [ ] Standalone mode: [pass/fail or N/A]
+
+## Next Phase Readiness
+
+[What's ready for next phase]
+[Any blockers or concerns]
+
+---
+*Phase: XX-name*
+*Completed: [date]*
+```
+
+<guidelines>
+
+**Frontmatter:**
+- MANDATORY — complete all fields
+- `sdk-modules-used` tracks which Frontier SDK modules this plan touched
+- `requirements-completed` lists requirement IDs fulfilled by this plan
+- Enables automatic context assembly for future planning
+
+**One-liner:**
+Must be substantive. Examples:
+- "Vite + React scaffold with SdkProvider, iframe detection, and dark Tailwind theme"
+- "Event listing page with real-time updates via Events SDK module"
+- "Wallet integration for USDC payments with transaction confirmation UI"
+
+NOT: "Phase complete" / "Scaffold done" / "Feature implemented"
+
+**SDK Integration Notes:**
+- Document how SDK modules were wired up in this plan
+- Document how SDK modules were wired up
+- Note any SDK quirks or workarounds
+- Helps future phases that use the same modules
+
+**Verification Results:**
+- Frontier-specific checks always included (dark theme, iframe, standalone)
+- Mark N/A for checks not applicable to this plan
+- All must pass before plan is considered complete
+
+**After creation:** STATE.md updated with position, decisions, metrics.
+
+</guidelines>
+
+<example>
+
+```markdown
+---
+phase: 01-scaffold
+plan: 01
+subsystem: scaffold
+tags: [react, vite, tailwind, frontier-sdk, iframe-detection]
+
+requires: []
+provides:
+  - "Vite + React project structure"
+  - "SdkProvider context with useSdk hook"
+  - "Iframe detection with standalone fallback"
+  - "Dark theme via Tailwind"
+affects: [02-event-listing, 03-event-creation]
+
+tech-stack:
+  added: [react, vite, tailwind, @frontiertower/frontier-sdk]
+  patterns: [SdkProvider wrapper, useSdk hook, iframe detection utility]
+
+key-files:
+  created: [src/App.tsx, src/lib/sdk-context.tsx, src/lib/iframe.ts, src/components/Layout.tsx]
+  modified: []
+
+key-decisions:
+  - "Used Tailwind for styling — matches Frontier OS design system"
+  - "Iframe detection via window.self !== window.top with fallback UI"
+
+patterns-established:
+  - "SdkProvider: All SDK access via useSdk() hook, never direct instantiation"
+  - "Dark theme: bg-neutral-950 base, text-white, no light mode support"
+
+sdk-modules-used: []
+
+requirements-completed: [PLAT-01, PLAT-02, PLAT-03, PLAT-04, PLAT-05]
+
+duration: 18min
+completed: 2026-03-27
+---
+
+# Phase 1: Scaffold + SDK Core — Plan 1 Summary
+
+**Vite + React scaffold with SdkProvider, iframe detection, dark Tailwind theme on port 5180**
+
+## Performance
+
+- **Duration:** 18 min
+- **Started:** 2026-03-27T10:00:00Z
+- **Completed:** 2026-03-27T10:18:00Z
+- **Tasks:** 3
+- **Files modified:** 8
+
+## Accomplishments
+
+- Full Vite + React + TypeScript project scaffolded
+- SdkProvider wraps app, useSdk() available everywhere
+- Iframe detection works — shows standalone banner when not in Frontier OS
+- Dark theme via Tailwind — bg-neutral-950 base, all components dark
+
+## Task Commits
+
+1. **Task 1: Scaffold Vite project** — `a1b2c3d` (feat: scaffold)
+2. **Task 2: SdkProvider + iframe detection** — `e4f5g6h` (feat: sdk integration)
+3. **Task 3: Dark theme + layout** — `i7j8k9l` (feat: dark theme)
+
+## Files Created/Modified
+
+- `src/App.tsx` — Root component with SdkProvider
+- `src/lib/sdk-context.tsx` — SdkProvider + useSdk hook
+- `src/lib/iframe.ts` — Iframe detection utility
+- `src/components/Layout.tsx` — Dark theme shell
+- `vite.config.ts` — Dev server on port 5180
+- `tailwind.config.ts` — Dark theme configuration
+- `tsconfig.json` — TypeScript strict mode
+- `postcss.config.js` — Tailwind PostCSS setup
+
+## SDK Integration Notes
+
+- SDK initialized once in SdkProvider via useRef to prevent re-instantiation
+- SDK destroyed on unmount via cleanup in useEffect
+- useSdk() throws if used outside SdkProvider — fail-fast pattern
+- No SDK modules used yet — just core initialization
+
+## Decisions Made
+
+- Used Tailwind instead of CSS modules — better dark theme support, matches Frontier OS
+- Iframe detection uses window.self !== window.top — simple, reliable
+
+## Deviations from Plan
+
+None — plan executed exactly as written
+
+## Verification Results
+
+- [x] Build: pass
+- [x] Dev server: pass on port 5180
+- [x] TypeScript: pass (strict mode, no errors)
+- [x] Dark theme: pass (no white backgrounds)
+- [x] Iframe mode: pass (renders in Frontier OS)
+- [x] Standalone mode: pass (shows fallback banner)
+
+## Next Phase Readiness
+
+- Scaffold complete, ready for feature development
+- SdkProvider available for module integration in Phase 2
+- No blockers
+
+---
+*Phase: 01-scaffold*
+*Completed: 2026-03-27*
+```
+
+</example>

package/workflows/add-feature.md

@@ -0,0 +1,234 @@
+<purpose>
+Add a new feature as a new phase to the current milestone. Takes a feature description, infers SDK modules, calculates the next phase number, creates the phase directory, updates ROADMAP.md, manifest.json, and STATE.md. Quick and focused — gets you back into the discuss->plan->execute cycle.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<available_agent_types>
+Valid FOS subagent types (use exact names):
+- fos-researcher — Researches existing Frontier OS apps for patterns
+- fos-planner — Creates detailed execution plans from research + context
+- fos-plan-checker — Reviews plan quality before execution
+- fos-executor — Executes plan tasks, commits, creates SUMMARY.md
+- fos-verifier — Verifies phase completion, checks quality gates
+</available_agent_types>
+
+<process>
+
+<step name="gather_description" priority="first">
+**Get the feature description.**
+
+**If .frontier-app/ not found:**
+```
+Error: No .frontier-app/ directory found.
+
+Run `/fos:new-app` first to initialize your Frontier OS app.
+```
+Exit workflow.
+
+Check if `$ARGUMENTS` contains a feature description.
+
+**If description provided in $ARGUMENTS:** Use it directly.
+```
+Adding feature: "[description]"
+```
+
+**If no description:** Use AskUserQuestion:
+- header: "New Feature"
+- question: "What feature do you want to add to [App Name]? Describe what it does."
+
+**Store the description** for module inference.
+</step>
+
+<step name="infer_modules">
+**Infer SDK modules for the new feature.**
+
+```bash
+MODULES=$(node "$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs" infer-modules "<feature description>")
+```
+
+Parse JSON for: `modules`, `details`, `permissions`, `moduleCount`.
+
+**Compare with existing manifest modules:**
+```bash
+MANIFEST=$(cat .frontier-app/manifest.json)
+```
+
+Identify:
+- **Already declared:** Modules in manifest that this feature also needs (no change)
+- **New modules:** Modules inferred that aren't in the manifest (need to add)
+
+```
+## Feature Analysis
+
+**Feature:** [description]
+
+**SDK Modules needed:**
+[If all modules already declared:]
+  All required modules already in manifest. No new permissions needed.
+
+[If new modules needed:]
+  New modules required:
+  | Module | Why | New Permissions |
+  |--------|-----|-----------------|
+  | [Module] | [matched keywords] | [permissions to add] |
+```
+</step>
+
+<step name="calculate_phase_number">
+**Find the next available phase number.**
+
+Read ROADMAP.md to find the highest phase number:
+```bash
+# Count existing phases from phases directory
+EXISTING_PHASES=$(ls -d .frontier-app/phases/*/ 2>/dev/null | wc -l)
+NEXT_PHASE=$((EXISTING_PHASES + 1))
+```
+
+Also check ROADMAP.md for any planned-but-not-yet-created phases to avoid conflicts.
+
+Generate the phase slug from the feature description:
+```bash
+# Example: "Event Creation Form" -> "event-creation-form"
+PHASE_SLUG=$(echo "$FEATURE_NAME" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-' | head -c 50)
+PADDED=$(printf "%02d" $NEXT_PHASE)
+PHASE_DIR=".frontier-app/phases/${PADDED}-${PHASE_SLUG}"
+```
+</step>
+
+<step name="create_phase">
+**Create the phase directory.**
+
+```bash
+mkdir -p "$PHASE_DIR"
+```
+
+Generate 1-3 requirement IDs for this feature:
+- Use existing requirement prefix pattern from REQUIREMENTS.md
+- Or generate new REQ-XX IDs
+</step>
+
+<step name="update_roadmap">
+**Add the new phase to ROADMAP.md.**
+
+Read ROADMAP.md and append:
+
+**In the phase list:**
+```markdown
+- [ ] **Phase [N]: [Feature Name]** — [One-line description]
+```
+
+**In Phase Details:**
+```markdown
+### Phase [N]: [Feature Name]
+**Goal**: [What this phase delivers — one sentence]
+**Depends on**: Phase [N-1] (or whichever phase it actually depends on)
+**Requirements**: [REQ-XX, REQ-YY]
+**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**: TBD (created during /fos:plan)
+
+Plans:
+- (created during /fos:plan [N])
+```
+
+**In Progress table:**
+```markdown
+| [N]. [Feature Name] | 0/TBD | Not started | - |
+```
+
+Update the "Last updated" footer.
+</step>
+
+<step name="update_manifest">
+**Update manifest.json with new modules and permissions if needed.**
+
+**If new modules were identified:**
+```bash
+# Read current manifest, add new modules and permissions, write back
+```
+
+Add to `modules` array: any new module names
+Add to `permissions` array: any new permissions
+Add to `phases` array: `{"number": N, "name": "[Feature Name]", "status": "not-started"}`
+
+**If no new modules:** Only add the phase entry.
+</step>
+
+<step name="update_requirements">
+**Add new requirements to REQUIREMENTS.md.**
+
+Add a new section for the feature:
+```markdown
+### [Feature Name]
+
+- [ ] **REQ-XX**: [Requirement 1 — user-centric, testable, atomic]
+- [ ] **REQ-YY**: [Requirement 2]
+```
+
+Update the traceability table:
+```markdown
+| REQ-XX | Phase [N] | Pending |
+| REQ-YY | Phase [N] | Pending |
+```
+
+Update coverage counts.
+</step>
+
+<step name="update_state">
+**Update STATE.md to point to the new feature phase.**
+
+```bash
+node "$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs" state update status "ready-to-discuss"
+node "$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs" state update phase "$NEXT_PHASE"
+node "$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs" state update next_action "/fos:discuss $NEXT_PHASE"
+```
+
+Update STATE.md body:
+- Last activity: [today] — Added feature: [feature name] as Phase [N]
+- Session Continuity: next-command = /fos:discuss N
+
+**Commit all changes:**
+```bash
+git add .frontier-app/
+git commit -m "feat: add Phase $NEXT_PHASE — [Feature Name]
+
+Feature: [description]
+[If new modules:] New SDK modules: [list]
+[If new permissions:] New permissions: [count]
+Phase: ${PADDED}-${PHASE_SLUG}"
+```
+</step>
+
+<step name="next_up">
+**Display completion and next step.**
+
+```
+## Feature Added: [Feature Name]
+
+Created Phase [N] in the current milestone.
+
+[If new modules:]
+  Added SDK modules: [list]
+  New permissions: [list]
+
+[If no new modules:]
+  No new SDK modules needed — existing modules cover this feature.
+
+Phase directory: .frontier-app/phases/${PADDED}-${PHASE_SLUG}/
+Requirements: [REQ-XX, REQ-YY]
+
+────────────────────────────────────────
+Next up: `/fos:discuss [N]`
+  Discuss implementation decisions for [Feature Name] before planning.
+
+Run `/clear` first to free your context window.
+────────────────────────────────────────
+```
+</step>
+
+</process>