frontier-os-app-builder 1.0.0

package/workflows/execute.md

@@ -0,0 +1,338 @@
+<purpose>
+Execute all plans in a phase using wave-based execution. Orchestrator stays lean — delegates plan execution to subagents, each getting a fresh context window with the full execute-plan workflow. After all plans complete, spawns a verifier to confirm the phase delivers what it promised.
+</purpose>
+
+<core_principle>
+Orchestrator coordinates, not executes. Each subagent loads the full execute-plan context. Orchestrator: discover plans -> analyze deps -> group waves -> spawn agents -> collect results -> verify.
+</core_principle>
+
+<required_reading>
+Read STATE.md before any operation to load project context.
+</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="initialize" priority="first">
+**Phase number from argument (required).**
+
+```bash
+INIT=$(node "$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs" init execute "$PHASE")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse JSON for: `phase`, `phase_dir`, `plans`, `summaries`, `incomplete_plans`, `all_complete`, `manifest`, `state`, `project_path`, `roadmap_path`, `template_home`, `version`.
+
+**If .frontier-app/ not found:**
+```
+Error: No .frontier-app/ directory found.
+
+Run `/fos:new-app` first to initialize your Frontier OS app.
+```
+Exit workflow.
+
+**If `phase_dir` is null:**
+```
+Error: Phase [N] directory not found.
+
+Run `/fos:plan [N]` first to create execution plans.
+```
+Exit workflow.
+
+**If `plans` is empty:**
+```
+Error: No plans found in Phase [N].
+
+Run `/fos:plan [N]` first to create execution plans.
+```
+Exit workflow.
+
+**If `all_complete` is true:**
+```
+Phase [N] is already fully executed — all plans have SUMMARY.md files.
+
+Run `/fos:status` to see project state, or `/fos:next` for the next step.
+```
+Exit workflow.
+
+Report status:
+```
+## Phase [N]: [Name]
+
+Found [total] plan(s), [incomplete] remaining to execute.
+[If some complete: "[complete] plan(s) already done — resuming from where we left off."]
+```
+</step>
+
+<step name="discover_and_group_plans">
+**Read all plan files and group into execution waves.**
+
+For each plan file in `incomplete_plans`:
+1. Read the plan file
+2. Parse frontmatter for: `wave`, `depends_on`, `autonomous`, `files_modified`
+3. Parse `<objective>` for the plan description
+
+**Group plans by wave number:**
+- Wave 1: Plans with `depends_on: []` or `wave: 1`
+- Wave 2: Plans with `wave: 2` (depends on Wave 1 plans)
+- Wave 3+: Subsequent waves
+
+**If no wave field in frontmatter:** Default to Wave 1 (no dependencies).
+
+**Report execution plan:**
+```
+## Execution Plan
+
+**Phase [N]: [Name]** — [count] plans across [wave_count] wave(s)
+
+| Wave | Plans | What It Builds |
+|------|-------|----------------|
+| 1 | 01-01, 01-02 | [from plan objectives, 3-8 words] |
+| 2 | 01-03 | [from plan objectives, 3-8 words] |
+```
+</step>
+
+<step name="execute_waves">
+**Execute each wave in sequence. Plans within a wave run in parallel.**
+
+**For each wave:**
+
+1. **Describe what's being built (BEFORE spawning):**
+
+   ```
+   ---
+   ## Wave [N]
+
+   **[Plan ID]: [Plan Name]**
+   [2-3 sentences: what this builds, which SDK modules, why it matters]
+
+   Spawning [count] agent(s)...
+   ---
+   ```
+
+2. **Spawn fos-executor per plan:**
+
+   ```
+   Task(
+     subagent_type="fos-executor",
+     prompt="
+       <objective>
+       Execute plan [plan_number] of Phase [phase_number]-[phase_name].
+       Commit each task atomically. Create SUMMARY.md when done. Update STATE.md.
+       </objective>
+
+       <execution_context>
+       @$HOME/.claude/frontier-os-app-builder/workflows/execute-plan.md
+       @$HOME/.claude/frontier-os-app-builder/templates/state/summary.md
+       @$HOME/.claude/frontier-os-app-builder/references/sdk-surface.md
+       @$HOME/.claude/frontier-os-app-builder/references/app-patterns.md
+       @$HOME/.claude/frontier-os-app-builder/references/verification-rules.md
+       </execution_context>
+
+       <files_to_read>
+       Read these files at execution start using the Read tool:
+       - $PHASE_DIR/[plan_file] (The plan to execute)
+       - .frontier-app/PROJECT.md (App vision, SDK modules)
+       - .frontier-app/manifest.json (Permissions)
+       - .frontier-app/STATE.md (Current state)
+       - $PHASE_DIR/$PADDED-CONTEXT.md (User decisions, if exists)
+       - $PHASE_DIR/$PADDED-RESEARCH.md (Research findings, if exists)
+       </files_to_read>
+
+       <success_criteria>
+       - [ ] All tasks executed
+       - [ ] Each task committed individually
+       - [ ] SUMMARY.md created in phase directory
+       - [ ] Build succeeds (npm run build)
+       - [ ] No TypeScript errors (npx tsc --noEmit)
+       - [ ] Dark theme verified
+       </success_criteria>
+     "
+   )
+   ```
+
+3. **Wait for all agents in wave to complete before starting next wave.**
+
+   **Completion verification (per plan):**
+   ```bash
+   SUMMARY_FILE="$PHASE_DIR/[plan_prefix]-SUMMARY.md"
+   test -f "$SUMMARY_FILE" && echo "complete" || echo "incomplete"
+   ```
+
+   If SUMMARY.md exists and git log shows recent commits for this plan: treat as complete.
+   If SUMMARY.md missing after agent returns: report as failed.
+
+4. **Report wave completion:**
+
+   For each completed plan, read its SUMMARY.md and extract:
+   - One-liner description
+   - Files created/modified
+   - Any deviations from plan
+
+   ```
+   ---
+   ## Wave [N] Complete
+
+   **[Plan ID]: [Plan Name]**
+   [What was built — from SUMMARY.md]
+   [Notable deviations, if any]
+
+   [If more waves: what this enables for next wave]
+   ---
+   ```
+
+5. **Handle failures:**
+
+   If a plan fails:
+   - Report which plan failed and why (from agent output or error)
+   - Ask: "Retry this plan?" / "Skip and continue?" / "Stop execution?"
+   - If retry: re-spawn the executor for that plan
+   - If skip: note the gap for the verifier
+   - If stop: save state and exit
+</step>
+
+<step name="spawn_verifier">
+**After all waves complete: verify the phase.**
+
+```
+Task(
+  subagent_type="fos-verifier",
+  prompt="
+    <objective>
+    Verify Phase [N]: [Name] delivers what the roadmap promised.
+    Check all success criteria from ROADMAP.md are met.
+    Check all SUMMARY.md files for issues.
+    Run structural and permission validation.
+    </objective>
+
+    <files_to_read>
+    Read these files at execution start using the Read tool:
+    - .frontier-app/ROADMAP.md (Phase success criteria)
+    - .frontier-app/PROJECT.md (App constraints)
+    - .frontier-app/manifest.json (Permissions)
+    - All SUMMARY.md files in $PHASE_DIR/
+    </files_to_read>
+
+    <verification_commands>
+    Run these checks:
+    - node '$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs' validate structure
+    - node '$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs' validate permissions
+    - npx tsc --noEmit (if app source exists)
+    - npm run build (if package.json exists)
+    </verification_commands>
+
+    <output>
+    Return structured result:
+    - verdict: PASS or FAIL
+    - criteria_results: each success criterion with pass/fail
+    - gaps: list of gaps found (if any)
+    - suggestions: optional improvements
+    </output>
+  "
+)
+```
+
+**If verifier returns FAIL:**
+```
+## Verification Issues
+
+The verifier found [count] issue(s):
+
+1. [Issue description]
+2. [Issue description]
+
+Options:
+- Generate fix plans for these gaps
+- Address manually and re-verify
+- Accept and move on (gaps noted)
+```
+
+Use AskUserQuestion to let user decide.
+
+**If "Generate fix plans":** Create gap-closure plans in the phase directory and re-execute.
+</step>
+
+<step name="update_state_and_roadmap">
+**Update STATE.md and ROADMAP.md.**
+
+**Determine next phase:**
+- Read ROADMAP.md for total phase count
+- If current phase < total phases: next is discuss for phase N+1
+- If current phase = total phases: next is ship
+
+```bash
+# Update state
+node "$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs" state update status "phase-complete"
+node "$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs" state update phase "$PHASE"
+
+# Set next action based on whether more phases remain
+if [ "$PHASE" -lt "$TOTAL_PHASES" ]; then
+  NEXT_PHASE=$((PHASE + 1))
+  node "$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs" state update next_action "/fos:discuss $NEXT_PHASE"
+  node "$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs" state update status "ready-to-discuss"
+else
+  node "$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs" state update next_action "/fos:ship"
+  node "$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs" state update status "milestone-complete"
+fi
+```
+
+**Update ROADMAP.md:**
+- Mark phase plans as complete in the progress table
+- Update phase status to "Complete" (or "Partial" if gaps)
+- Add completion date
+
+**Update STATE.md body:**
+- Current Position: Advance to next phase or "Ready to ship"
+- Update progress bar
+- Update metrics (plans completed, duration)
+- Last activity: [today] — Executed Phase [N]: [Name]
+
+```bash
+git add .frontier-app/
+git commit -m "docs: Phase $PHASE complete — [plan_count] plans executed
+
+Verification: [PASS/FAIL]
+Next: [/fos:discuss N+1 or /fos:ship]"
+```
+</step>
+
+<step name="next_up">
+**Display completion and next step.**
+
+```
+## Phase [N]: [Name] — Complete
+
+Executed [plan_count] plan(s) across [wave_count] wave(s).
+Verification: [PASS / PASS with notes / FAIL with gaps]
+
+Plans completed:
+- [Plan 01]: [one-liner from SUMMARY.md]
+- [Plan 02]: [one-liner from SUMMARY.md]
+
+[If more phases remain:]
+────────────────────────────────────────
+Next up: `/fos:discuss [N+1]`
+  Discuss Phase [N+1]: [Name] — capture implementation decisions before planning.
+
+Run `/clear` first to free your context window.
+────────────────────────────────────────
+
+[If all phases complete:]
+────────────────────────────────────────
+Next up: `/fos:ship`
+  Deploy to Vercel and register in the Frontier app store.
+
+Run `/clear` first to free your context window.
+────────────────────────────────────────
+```
+</step>
+
+</process>

package/workflows/new-app.md

@@ -0,0 +1,331 @@
+<purpose>
+Initialize a new Frontier OS app through guided flow: gather a natural language description, infer SDK modules, ask domain-specific questions, create phased roadmap and all project state files. This is the most leveraged moment in any app — deep questioning here means the right SDK modules, the right phases, the right architecture from day one.
+</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="setup" priority="first">
+**MANDATORY FIRST STEP — Execute before any user interaction:**
+
+```bash
+INIT=$(node "$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs" init new-app)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse JSON for: `project_exists`, `has_git`, `cwd`, `template_home`, `version`.
+
+**If `project_exists` is true:**
+```
+Error: This directory already has a .frontier-app/ directory.
+
+If you want to see your project status: /fos:status
+If you want to continue building: /fos:next
+If you want to start fresh: delete .frontier-app/ and run /fos:new-app again
+```
+Exit workflow.
+
+**If `has_git` is false:** Will initialize git after scaffolding (step 9).
+</step>
+
+<step name="gather_description">
+**Get the app description.**
+
+Check if `$ARGUMENTS` contains a description (any text that isn't just flags).
+
+**If description provided in $ARGUMENTS:** Use it directly. Display it back:
+```
+Building: "[description from arguments]"
+```
+
+**If no description:** Use AskUserQuestion:
+- header: "App Idea"
+- question: "What Frontier OS app do you want to build? Describe it in plain language — what it does, who uses it, and what Frontier features it needs."
+
+**Store the description** for use in subsequent steps.
+</step>
+
+<step name="infer_modules">
+**Infer SDK modules from the description.**
+
+```bash
+MODULES=$(node "$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs" infer-modules "<description>")
+```
+
+Parse JSON for: `modules`, `details`, `permissions`, `moduleCount`.
+
+**Present the inferred modules to the user:**
+
+```
+## SDK Modules Detected
+
+Based on your description, your app will use these Frontier SDK modules:
+
+| Module | Why | Key Methods |
+|--------|-----|-------------|
+| [Module] | [Matched keywords from description] | [suggestedMethods from details] |
+
+**Always included:**
+- Storage — App state persistence (preferences, drafts, etc.)
+- Chain — Network configuration and contract addresses
+
+**Permissions requested:** [count] permissions across [moduleCount] modules
+```
+
+This is informational — the user will confirm or adjust in step 5.
+</step>
+
+<step name="smart_questions">
+**Ask domain-specific questions based on inferred modules.**
+
+Generate 2-5 questions based on WHICH modules were inferred. These are DOMAIN questions about the user's app, NOT SDK implementation questions.
+
+**Question bank by module:**
+
+**Wallet module detected:**
+- "Should transactions use FND (Frontier Dollar) only, or also support fiat on/off-ramp?"
+- "Will users send money to each other (P2P), or only pay for services?"
+- "Do you need transaction history displayed in the app?"
+
+**Events module detected:**
+- "Do you need real-time availability updates, or is periodic refresh fine?"
+- "Should users be able to create events, or only browse and RSVP?"
+- "Are events tied to physical locations (rooms/venues) or virtual?"
+
+**Communities module detected:**
+- "Is this for a specific community, or should users browse/join multiple communities?"
+- "Do you need member lists visible, or just community-level info?"
+
+**Partnerships module detected:**
+- "Are sponsors displayed publicly, or is this for internal partner management?"
+- "Do sponsors get special access passes or visibility?"
+
+**Offices module detected:**
+- "Is this for visitor access passes, member day passes, or both?"
+- "Do users need to see available rooms/spaces?"
+
+**User module detected (implied):**
+- "Do you need to show user profiles beyond basic name/avatar?"
+- "Are there different user roles (member vs admin vs operator)?"
+
+**ThirdParty module detected:**
+- "Is this a developer-facing tool, or does it use ThirdParty APIs behind the scenes?"
+
+**Ask questions one batch at a time** using AskUserQuestion with appropriate options for each. Keep it to ONE round of questions — do not over-interrogate.
+
+**For modules with no specific questions** (Storage, Chain): skip — these are utility modules with standard patterns.
+</step>
+
+<step name="confirm">
+**Present final module list and permissions for approval.**
+
+Incorporate answers from smart questions to refine the module list. If the user's answers suggest additional modules or removal of inferred modules, adjust.
+
+```
+## App Summary
+
+**Name:** [Inferred from description, or ask]
+**Description:** [From step 2, refined by step 4 answers]
+**Dev Port:** [Pick from 5180-5199 range, avoid common ports]
+
+### SDK Modules (Final)
+
+| Module | Key Methods | Permissions |
+|--------|-------------|-------------|
+| [Module] | [methods] | [permissions count] |
+
+### Phases Preview
+
+1. **Phase 1: Scaffold + SDK Core** — Project setup, SdkProvider, iframe detection, dark theme
+2. **Phase 2: [Feature]** — [From description + smart question answers]
+3. **Phase N: [Feature]** — [From description + smart question answers]
+
+Total permissions: [N]
+```
+
+Use AskUserQuestion:
+- header: "Confirm"
+- question: "Does this look right?"
+- options:
+  - "Looks good — create the app" — Proceed to scaffolding
+  - "Change something" — Let user modify modules, name, or phases
+  - "Start over" — Go back to description
+
+**If "Change something":** Ask what to change, adjust, and re-confirm.
+**If "Start over":** Return to step 2.
+</step>
+
+<step name="create_app_directory">
+**Create the app directory structure.**
+
+```bash
+APP_DIR=$(pwd)
+mkdir -p .frontier-app/phases/01-scaffold
+```
+
+This creates:
+- `.frontier-app/` — Project state directory
+- `.frontier-app/phases/01-scaffold/` — Phase 1 directory (always created)
+</step>
+
+<step name="create_roadmap">
+**Build the phased roadmap.**
+
+Phase 1 is ALWAYS "Scaffold + SDK Core" — this is non-negotiable for every Frontier OS app.
+
+Additional phases come from the features identified in steps 3-5:
+- Group related features into coherent phases
+- Each phase should deliver something testable
+- Keep to 3-6 total phases for v1 — ship fast
+- Order phases by dependency (features that build on each other)
+
+**Phase sizing heuristics:**
+- Simple feature (one SDK module, one view): 1 phase, 1-2 plans
+- Medium feature (SDK module + UI + state): 1 phase, 2-3 plans
+- Complex feature (multiple modules, multiple views): 1-2 phases, 2-3 plans each
+</step>
+
+<step name="write_state_files">
+**Write all project state files using templates.**
+
+**1. PROJECT.md:**
+```bash
+node "$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs" scaffold "state/project.md" --raw --vars '{"APP_NAME":"[name]","APP_DESCRIPTION":"[description]","DATE":"[today]","TRIGGER":"initial creation"}'
+```
+Then fill in the template sections:
+- SDK Modules table with actual module data from step 3
+- Target Users from description and smart question answers
+- Core Value from the description
+- Constraints (standard 6 + any app-specific from answers)
+
+Write to `.frontier-app/PROJECT.md`.
+
+**2. REQUIREMENTS.md:**
+```bash
+node "$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs" scaffold "state/requirements.md" --raw --vars '{"APP_NAME":"[name]","MILESTONE_VERSION":"v1","DATE":"[today]","TRIGGER":"initial creation"}'
+```
+Then fill in:
+- Standard PLAT-01 through PLAT-05 (always)
+- Feature requirements REQ-01+ (from phases)
+- Traceability table mapping requirements to phases
+- Out of scope (standard 2 + app-specific)
+
+Write to `.frontier-app/REQUIREMENTS.md`.
+
+**3. ROADMAP.md:**
+```bash
+node "$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs" scaffold "state/roadmap.md" --raw --vars '{"APP_NAME":"[name]","MILESTONE_VERSION":"v1","DATE":"[today]","TRIGGER":"initial creation"}'
+```
+Then fill in:
+- Phase list with all phases from step 7
+- Phase details with goals, dependencies, requirements, success criteria
+- Progress table initialized to "Not started"
+
+Write to `.frontier-app/ROADMAP.md`.
+
+**4. STATE.md:**
+```bash
+node "$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs" scaffold "state/state.md" --raw --vars '{"MILESTONE_VERSION":"v1","CURRENT_PHASE":"1","CURRENT_PLAN":"01","STATUS":"ready-to-discuss","NEXT_ACTION":"/fos:discuss 1"}'
+```
+Then fill in:
+- Current Position: Phase 1 of [N], ready to discuss
+- App Reference: Name, core value, SDK modules, dev port
+- Empty Recent Decisions, Blockers, Metrics
+- Next command: /fos:discuss 1
+
+Write to `.frontier-app/STATE.md`.
+
+**5. manifest.json:**
+Construct the manifest object:
+```json
+{
+  "name": "[App Name]",
+  "packageName": "[package-name]",
+  "description": "[Description]",
+  "sdkVersion": "latest",
+  "devPort": [port],
+  "modules": ["Storage", "Chain", ...other modules...],
+  "permissions": ["storage:get", "storage:set", ...all permissions...],
+  "milestone": "v1",
+  "phases": [
+    {"number": 1, "name": "Scaffold + SDK Core", "status": "not-started"},
+    {"number": 2, "name": "[Feature]", "status": "not-started"},
+    ...
+  ]
+}
+```
+
+Write to `.frontier-app/manifest.json`.
+</step>
+
+<step name="git_init_and_commit">
+**Initialize git and create initial commit.**
+
+**If `has_git` is false:**
+```bash
+git init
+```
+
+**Create .gitignore if it doesn't exist:**
+```bash
+cat > .gitignore << 'GITIGNORE'
+node_modules/
+dist/
+.env
+.env.local
+*.log
+.DS_Store
+GITIGNORE
+```
+
+**Commit all state files:**
+```bash
+git add .frontier-app/ .gitignore
+git commit -m "feat: initialize [App Name] — Frontier OS app
+
+SDK Modules: [comma-separated modules]
+Phases: [count] phases planned for v1
+Created by: /fos:new-app"
+```
+</step>
+
+<step name="next_up">
+**Display completion and next step.**
+
+```
+## App Initialized
+
+**[App Name]** is ready to build.
+
+Created:
+  .frontier-app/PROJECT.md      — App vision and SDK modules
+  .frontier-app/REQUIREMENTS.md — Scoped requirements
+  .frontier-app/ROADMAP.md      — [N]-phase build plan
+  .frontier-app/STATE.md        — Project memory
+  .frontier-app/manifest.json   — Machine-readable metadata
+
+SDK Modules: [list]
+Phases: [list of phase names]
+
+────────────────────────────────────────
+Next up: `/fos:discuss 1`
+  Discuss Phase 1 approach — minimal decisions for scaffold, but establishes patterns.
+
+Run `/clear` first to free your context window.
+────────────────────────────────────────
+```
+</step>
+
+</process>