frontier-os-app-builder 1.0.0 → 1.2.0

package/workflows/execute.md

@@ -31,6 +31,13 @@ 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`.
 
+**Generate focused SDK reference for this app's modules:**
+```bash
+MODULES=$(node -e "const m=JSON.parse(require('fs').readFileSync('.frontier-app/manifest.json','utf8')); console.log(m.modules.join(','))")
+SDK_REF=$(node "$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs" sdk-ref --modules "$MODULES")
+SDK_REF_PATH="${SDK_REF#@file:}"
+```
+
 **If .frontier-app/ not found:**
 ```
 Error: No .frontier-app/ directory found.
@@ -123,22 +130,29 @@ For each plan file in `incomplete_plans`:
    ```
    Task(
      subagent_type="fos-executor",
+     isolation="worktree",
      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>
 
+       <parallel_execution>
+       You are running as a PARALLEL executor agent. Use --no-verify on all git
+       commits to avoid pre-commit hook contention with other agents. The
+       orchestrator validates hooks once after all agents complete.
+       </parallel_execution>
+
        <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:
+       - $SDK_REF_PATH (focused SDK reference for this app's modules)
        - $PHASE_DIR/[plan_file] (The plan to execute)
        - .frontier-app/PROJECT.md (App vision, SDK modules)
        - .frontier-app/manifest.json (Permissions)
@@ -164,13 +178,33 @@ For each plan file in `incomplete_plans`:
    **Completion verification (per plan):**
    ```bash
    SUMMARY_FILE="$PHASE_DIR/[plan_prefix]-SUMMARY.md"
-   test -f "$SUMMARY_FILE" && echo "complete" || echo "incomplete"
+   if [ ! -f "$SUMMARY_FILE" ]; then
+     echo "incomplete"
+   elif grep -q "Self-Check: FAILED" "$SUMMARY_FILE"; then
+     echo "self-check-failed"
+   else
+     echo "complete"
+   fi
    ```
 
-   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.
+   - **complete:** SUMMARY.md exists, self-check passed, git log shows recent commits. Treat as successful.
+   - **self-check-failed:** SUMMARY.md exists but executor detected issues. Read the SUMMARY.md to extract what failed, then ask:
+     - "Retry this plan?" — re-spawn the executor
+     - "Fix manually?" — exit with pointer to SUMMARY.md
+     - "Continue anyway?" — note the gap for the verifier
+   - **incomplete:** SUMMARY.md missing after agent returns. Either the agent crashed or hit a checkpoint (see handle_checkpoints step). Report as failed.
+
+4. **Post-wave hook validation (parallel mode):**
 
-4. **Report wave completion:**
+   When agents committed with `--no-verify`, run pre-commit hooks once after the wave:
+   ```bash
+   git stash --quiet 2>/dev/null || true
+   git hook run pre-commit 2>&1 || echo "Warning: Pre-commit hooks failed — review before continuing"
+   git stash pop --quiet 2>/dev/null || true
+   ```
+   If hooks fail: report the failure and ask "Fix hook issues now?" or "Continue to next wave?"
+
+5. **Report wave completion:**
 
    For each completed plan, read its SUMMARY.md and extract:
    - One-liner description
@@ -189,7 +223,7 @@ For each plan file in `incomplete_plans`:
    ---
    ```
 
-5. **Handle failures:**
+6. **Handle failures:**
 
    If a plan fails:
    - Report which plan failed and why (from agent output or error)
@@ -199,6 +233,95 @@ For each plan file in `incomplete_plans`:
    - If stop: save state and exit
 </step>
 
+<step name="handle_checkpoints">
+**Handle executor agents that returned checkpoint state instead of completion.**
+
+When an executor agent returns a structured checkpoint (output contains `## CHECKPOINT REACHED` and no SUMMARY.md was created), it means a `checkpoint:human-verify` or `checkpoint:decision` task was encountered.
+
+**Detection:** After each executor returns in a wave, check:
+- If SUMMARY.md exists for that plan: agent completed normally. Skip this step.
+- If SUMMARY.md does NOT exist AND agent output contains `## CHECKPOINT REACHED`: checkpoint hit.
+
+**For each checkpoint:**
+
+1. **Parse the checkpoint return:**
+   - Type: `human-verify` or `decision`
+   - Plan ID and progress (completed/total tasks)
+   - Completed tasks table (with commit hashes)
+   - Checkpoint details (what to verify or decide)
+   - Awaiting section (what user needs to provide)
+
+2. **Present to user:**
+   ```
+   ## Checkpoint: [Type]
+
+   **Plan:** [plan ID] — [plan name]
+   **Progress:** [completed]/[total] tasks complete
+
+   [Checkpoint details from agent return]
+
+   [Awaiting section from agent return]
+   ```
+
+   Use AskUserQuestion (if available):
+   - header: "Checkpoint: [Type]"
+   - question: "[Awaiting section content]"
+   - If human-verify: options: ["Approved", "Issues found — describe below"]
+   - If decision: options from checkpoint details
+
+   If AskUserQuestion denied: default to "Approved" for human-verify, or the first/recommended option for decisions.
+
+3. **Spawn a FRESH continuation executor:**
+
+   ```
+   Task(
+     subagent_type="fos-executor",
+     isolation="worktree",
+     prompt="
+       <objective>
+       Continue execution of plan [plan_number], Phase [phase_number]-[phase_name].
+       Previous agent completed [N] tasks before hitting a checkpoint.
+       Resume from Task [resume_task_number]: [resume_task_name].
+       </objective>
+
+       <completed_tasks>
+       [Completed tasks table from checkpoint return — task names + commit hashes]
+       </completed_tasks>
+
+       <user_response>
+       [User's response to checkpoint]
+       </user_response>
+
+       <resume_instructions>
+       Start from Task [resume_task_number]: [resume_task_name].
+       Verify previous commits exist before continuing.
+       Do NOT redo completed tasks.
+       </resume_instructions>
+
+       <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/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:
+       - $SDK_REF_PATH (focused SDK reference for this app's modules)
+       - $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)
+       </files_to_read>
+     "
+   )
+   ```
+
+4. **Wait for continuation agent.** If it hits another checkpoint, repeat from step 1. If it completes (SUMMARY.md created), treat as normal completion.
+
+**Why fresh agent, not resume:** Fresh agents with explicit completed-task state are more reliable than attempting to resume a paused agent context.
+</step>
+
 <step name="spawn_verifier">
 **After all waves complete: verify the phase.**
 
@@ -211,6 +334,10 @@ Task(
     Check all success criteria from ROADMAP.md are met.
     Check all SUMMARY.md files for issues.
     Run structural and permission validation.
+
+    Read sdkPhase from manifest.json. If current phase matches sdkPhase, run BOTH
+    Tier 1 (standalone app quality) and Tier 2 (SDK integration correctness) checks.
+    Otherwise, run Tier 1 checks only.
     </objective>
 
     <files_to_read>
@@ -223,15 +350,19 @@ Task(
 
     <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
+    - node '$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs' validate structure --phase "$PHASE"
+    - node '$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs' validate permissions --phase "$PHASE"
     - npx tsc --noEmit (if app source exists)
     - npm run build (if package.json exists)
     </verification_commands>
 
     <output>
-    Return structured result:
-    - verdict: PASS or FAIL
+    Write VERIFICATION.md to $PHASE_DIR/{phase_num}-VERIFICATION.md using the Write tool,
+    following the output_format structure in your agent definition (frontmatter with status,
+    verified_date, checks_passed, gaps fields, then full check results by category).
+
+    Then return structured result to the orchestrator:
+    - verdict: PASSED or GAPS_FOUND
     - criteria_results: each success criterion with pass/fail
     - gaps: list of gaps found (if any)
     - suggestions: optional improvements
@@ -240,24 +371,48 @@ Task(
 )
 ```
 
-**If verifier returns FAIL:**
+**Parse verifier verdict from VERIFICATION.md:**
+```bash
+VERIFICATION_FILE="$PHASE_DIR/${PADDED}-VERIFICATION.md"
+VERDICT=$(grep -m1 "^status:" "$VERIFICATION_FILE" | awk '{print $2}')
 ```
-## Verification Issues
 
-The verifier found [count] issue(s):
+**If verdict is `passed`:**
+Verifier confirmed phase delivers on its promises. Continue to update_state_and_roadmap.
+
+**If verdict is `gaps_found`:**
+```
+## Verification: Gaps Found
 
-1. [Issue description]
-2. [Issue description]
+Phase [N]: [Name] — [checks_passed] checks passed, gaps remain.
 
-Options:
-- Generate fix plans for these gaps
-- Address manually and re-verify
-- Accept and move on (gaps noted)
+| # | Check | Issue | Severity |
+|---|-------|-------|----------|
+| 1 | [Check ID] | [What failed] | Blocker/Warning |
+| 2 | [Check ID] | [What failed] | Blocker/Warning |
+
+[Gap details from VERIFICATION.md Gaps section]
 ```
 
-Use AskUserQuestion to let user decide.
+Use AskUserQuestion (if available):
+- header: "Verification Gaps"
+- question: "How do you want to handle these gaps?"
+- options:
+  - "Generate gap-closure plans and re-execute" — Creates fix plans, executes them, then re-verifies
+  - "Fix manually and re-verify" — You address the issues, then run `/fos:execute [N]` again
+  - "Accept with gaps noted" — Mark phase as partial, gaps documented in VERIFICATION.md
+
+**If "Generate gap-closure plans":**
+1. Read the Gaps section from VERIFICATION.md
+2. Spawn fos-planner with the gap list as context to create targeted fix plans
+3. Execute the new plans (re-enter execute_waves for the gap-closure plans only)
+4. Re-run verifier after gap-closure plans complete
 
-**If "Generate fix plans":** Create gap-closure plans in the phase directory and re-execute.
+**If "Fix manually":** Exit with message: "Fix the gaps listed in `$VERIFICATION_FILE`, then run `/fos:execute [N]` to re-verify."
+
+**If "Accept with gaps":** Continue to update_state_and_roadmap. Update phase status to "partial" instead of "complete" in STATE.md. Gaps remain documented in VERIFICATION.md.
+
+**If AskUserQuestion denied:** Default to "Generate gap-closure plans and re-execute".
 </step>
 
 <step name="update_state_and_roadmap">
@@ -273,11 +428,20 @@ Use AskUserQuestion to let user decide.
 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"
 
+# Read sdkPhase from manifest
+SDK_PHASE=$(node -e "const m=JSON.parse(require('fs').readFileSync('.frontier-app/manifest.json','utf8')); console.log(m.sdkPhase || -1)")
+
 # 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"
+  if [ "$NEXT_PHASE" -eq "$SDK_PHASE" ]; then
+    # SDK Integration phase is mechanical — skip discuss, go straight to plan
+    node "$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs" state update next_action "/fos:plan $NEXT_PHASE"
+    node "$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs" state update status "ready-to-plan"
+  else
+    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"
+  fi
 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"
@@ -317,7 +481,23 @@ Plans completed:
 - [Plan 01]: [one-liner from SUMMARY.md]
 - [Plan 02]: [one-liner from SUMMARY.md]
 
-[If more phases remain:]
+[If completed phase was the SDK Integration phase (sdkPhase from manifest.json):]
+────────────────────────────────────────
+SDK Integration complete. App is now Frontier OS-ready.
+Next up: `/fos:ship` — Deploy to Vercel and register in the Frontier app store.
+
+Run `/clear` first to free your context window.
+────────────────────────────────────────
+
+[If more phases remain AND next phase is sdkPhase:]
+────────────────────────────────────────
+Next up: `/fos:plan [N+1]`
+  Plan Phase [N+1]: [Name] — SDK Integration is mechanical, skipping discuss.
+
+Run `/clear` first to free your context window.
+────────────────────────────────────────
+
+[If more phases remain (default):]
 ────────────────────────────────────────
 Next up: `/fos:discuss [N+1]`
   Discuss Phase [N+1]: [Name] — capture implementation decisions before planning.

package/workflows/new-app.md

@@ -38,6 +38,14 @@ 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).
+
+**Check for Studio context file:**
+Read `.frontier-studio-context.md` if it exists in the current directory or `../.frontier-studio-context.md` in the parent. This file contains Frontier Tower domain knowledge (floors, membership, events, governance, existing apps) selected by the developer in Frontier Studio. It complements the SDK technical references you already have — use it to inform module inference, domain questions, and requirements throughout the workflow. Skip if the file doesn't exist.
+
+**After reading (if it existed):** Delete the file to prevent stale context from leaking into future app creations:
+```bash
+rm -f .frontier-studio-context.md ../.frontier-studio-context.md
+```
 </step>
 
 <step name="gather_description">
@@ -50,10 +58,15 @@ Check if `$ARGUMENTS` contains a description (any text that isn't just flags).
 Building: "[description from arguments]"
 ```
 
-**If no description:** Use AskUserQuestion:
+**If no description:** Use AskUserQuestion (if available):
 - 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."
 
+If AskUserQuestion is denied (autonomous/don't-ask mode), output an error and exit — a description is required:
+```
+Error: No app description provided. Usage: /fos:new-app "describe your app"
+```
+
 **Store the description** for use in subsequent steps.
 </step>
 
@@ -125,6 +138,8 @@ Generate 2-5 questions based on WHICH modules were inferred. These are DOMAIN qu
 
 **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.
 
+**If AskUserQuestion is denied (autonomous/don't-ask mode):** Skip this step entirely. Use reasonable defaults based on the description and any Studio context file. Briefly state the defaults you're choosing and why, then proceed to confirmation.
+
 **For modules with no specific questions** (Storage, Chain): skip — these are utility modules with standard patterns.
 </step>
 
@@ -148,14 +163,15 @@ Incorporate answers from smart questions to refine the module list. If the user'
 
 ### Phases Preview
 
-1. **Phase 1: Scaffold + SDK Core** — Project setup, SdkProvider, iframe detection, dark theme
+1. **Phase 1: Scaffold + Standalone Shell** — Project setup, services layer, mock data, dark theme
 2. **Phase 2: [Feature]** — [From description + smart question answers]
-3. **Phase N: [Feature]** — [From description + smart question answers]
+...
+N. **Phase N: SDK Integration** — Wire SDK, create adapter, upgrade Layout for iframe
 
 Total permissions: [N]
 ```
 
-Use AskUserQuestion:
+Use AskUserQuestion (if available):
 - header: "Confirm"
 - question: "Does this look right?"
 - options:
@@ -165,31 +181,62 @@ Use AskUserQuestion:
 
 **If "Change something":** Ask what to change, adjust, and re-confirm.
 **If "Start over":** Return to step 2.
+
+**If AskUserQuestion is denied (autonomous/don't-ask mode):** Display the summary and proceed directly to scaffolding. The user can adjust later via `/fos:add-feature` or by editing manifest.json.
 </step>
 
 <step name="create_app_directory">
-**Create the app directory structure.**
+**Create the app directory and project state structure.**
+
+Generate the app directory name from the confirmed app name:
+- Kebab-case the name: "Tip Jar" → "tip-jar"
+- Prefix with `frontier-os-app-`: "tip-jar" → "frontier-os-app-tip-jar"
+
+If the current directory already IS the app directory (user pre-created it and cd'd in), skip directory creation — just create `.frontier-app/` in place.
+
+Otherwise, create the directory and **change into it immediately**:
 
 ```bash
-APP_DIR=$(pwd)
-mkdir -p .frontier-app/phases/01-scaffold
+APP_SLUG="frontier-os-app-[kebab-name]"
+mkdir -p "$APP_SLUG" && cd "$APP_SLUG"
+```
+
+**CRITICAL:** After creating the directory, ALL subsequent commands (file writes, git, scaffold, etc.) MUST use the new app directory as the working directory. Use absolute paths or `cd` into the directory in every Bash call. The `cd` in a single Bash call does NOT persist to subsequent Bash calls — so either:
+- Prefix every Bash command with `cd "$APP_DIR" &&`, or
+- Use absolute paths (`$APP_DIR/.frontier-app/...`) for all file operations
+
+Set `APP_DIR` to the absolute path of the new app directory:
+```bash
+APP_DIR="$(pwd)/$APP_SLUG"
+```
+
+Then create the project state directory:
+
+```bash
+mkdir -p "$APP_DIR/.frontier-app/phases/01-scaffold"
 ```
 
 This creates:
+- `frontier-os-app-[name]/` — The app project directory (auto-created)
 - `.frontier-app/` — Project state directory
 - `.frontier-app/phases/01-scaffold/` — Phase 1 directory (always created)
+
+**How to detect if already in an app directory:**
+If the user already created and cd'd into a directory named `frontier-os-app-*` that is empty (no files except maybe `.git`), treat it as the app directory and skip creation. Otherwise, create the subdirectory.
 </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.
+Phase 1 is ALWAYS "Scaffold + Standalone Shell" — this is non-negotiable for every Frontier OS app.
+The LAST phase is ALWAYS "SDK Integration" — a mechanical phase that wires the real Frontier SDK. This phase is auto-added and has fixed success criteria (no user decisions needed). It is non-negotiable.
 
 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)
+- The final phase is always "SDK Integration" — auto-added after all feature phases
 
 **Phase sizing heuristics:**
 - Simple feature (one SDK module, one view): 1 phase, 1-2 plans
@@ -260,10 +307,12 @@ Construct the manifest object:
   "permissions": ["storage:get", "storage:set", ...all permissions...],
   "milestone": "v1",
   "phases": [
-    {"number": 1, "name": "Scaffold + SDK Core", "status": "not-started"},
+    {"number": 1, "name": "Scaffold + Standalone Shell", "status": "not-started"},
     {"number": 2, "name": "[Feature]", "status": "not-started"},
     ...
-  ]
+    {"number": N, "name": "SDK Integration", "status": "not-started"}
+  ],
+  "sdkPhase": N
 }
 ```
 
@@ -273,27 +322,19 @@ Write to `.frontier-app/manifest.json`.
 <step name="git_init_and_commit">
 **Initialize git and create initial commit.**
 
+All commands in this step MUST run inside `$APP_DIR`:
+
 **If `has_git` is false:**
 ```bash
-git init
+cd "$APP_DIR" && git init
 ```
 
 **Create .gitignore if it doesn't exist:**
-```bash
-cat > .gitignore << 'GITIGNORE'
-node_modules/
-dist/
-.env
-.env.local
-*.log
-.DS_Store
-GITIGNORE
-```
+Write `.gitignore` to `$APP_DIR/.gitignore`.
 
 **Commit all state files:**
 ```bash
-git add .frontier-app/ .gitignore
-git commit -m "feat: initialize [App Name] — Frontier OS app
+cd "$APP_DIR" && 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

package/workflows/new-milestone.md

@@ -65,7 +65,7 @@ Create or append to `.frontier-app/MILESTONES.md`:
 
 | Phase | Name | Plans | Status |
 |-------|------|-------|--------|
-| 1 | Scaffold + SDK Core | 1/1 | Complete |
+| 1 | Scaffold + Standalone Shell | 1/1 | Complete |
 | 2 | [Name] | N/N | Complete |
 | ... | ... | ... | ... |
 
@@ -91,10 +91,15 @@ Check if `$ARGUMENTS` contains feature descriptions.
 
 **If description provided in $ARGUMENTS:** Use it directly.
 
-**If no description:** Use AskUserQuestion:
+**If no description:** Use AskUserQuestion (if available):
 - header: "New Milestone"
 - question: "What features should [App Name] [next version] include? Describe the new capabilities you want to add."
 
+If AskUserQuestion denied: error and exit — a description is required:
+```
+Error: No feature descriptions provided. Usage: /fos:new-milestone "describe new features"
+```
+
 Parse the response into individual features. Each feature becomes a candidate for a phase.
 </step>
 
@@ -154,13 +159,15 @@ Starting from Phase [N]:
 - [ ] **Phase [N+2]: [Feature Name]** — [Description]
 ```
 
-Use AskUserQuestion:
+Use AskUserQuestion (if available):
 - header: "Confirm"
 - question: "Does this milestone plan look right?"
 - options:
   - "Looks good" — Create the phases
   - "Change something" — Adjust phases
   - "Cancel" — Don't start new milestone yet
+
+If AskUserQuestion denied: display the plan and proceed with "Looks good".
 </step>
 
 <step name="update_all_state_files">

package/workflows/plan.md

@@ -27,6 +27,13 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 
 Parse JSON for: `phase`, `phase_dir`, `has_context`, `has_research`, `existing_plans`, `manifest`, `state`, `project_path`, `roadmap_path`, `template_home`, `version`.
 
+**Generate focused SDK reference for this app's modules:**
+```bash
+MODULES=$(node -e "const m=JSON.parse(require('fs').readFileSync('.frontier-app/manifest.json','utf8')); console.log(m.modules.join(','))")
+SDK_REF=$(node "$HOME/.claude/frontier-os-app-builder/bin/fos-tools.cjs" sdk-ref --modules "$MODULES")
+SDK_REF_PATH="${SDK_REF#@file:}"
+```
+
 **If .frontier-app/ not found:**
 ```
 Error: No .frontier-app/ directory found.
@@ -52,7 +59,7 @@ Continue anyway? (y/n)
 ```
 
 **If `existing_plans` is not empty:**
-Use AskUserQuestion:
+Use AskUserQuestion (if available):
 - header: "Existing Plans"
 - question: "Phase [N] already has [count] plan(s). What do you want to do?"
 - options:
@@ -60,6 +67,8 @@ Use AskUserQuestion:
   - "View plans" — Show existing plans before deciding
   - "Keep them" — Skip planning, proceed to execution
 
+If AskUserQuestion denied: default to "Replan" — delete existing plans and create new ones.
+
 **If "Keep them":** Exit with next-up `/fos:execute N`.
 **If "Replan":** Continue (plans will be overwritten).
 </step>
@@ -80,12 +89,12 @@ Task(
 
     <execution_context>
     @$HOME/.claude/frontier-os-app-builder/agents/fos-researcher.md
-    @$HOME/.claude/frontier-os-app-builder/references/sdk-surface.md
     @$HOME/.claude/frontier-os-app-builder/references/app-patterns.md
     </execution_context>
 
     <files_to_read>
     Read these files at execution start using the Read tool:
+    - $SDK_REF_PATH (focused SDK reference for this app's modules)
     - .frontier-app/PROJECT.md (App vision, SDK modules, constraints)
     - .frontier-app/manifest.json (Declared permissions and metadata)
     - .frontier-app/ROADMAP.md (Phase goal and requirements)
@@ -124,13 +133,13 @@ Task(
 
     <execution_context>
     @$HOME/.claude/frontier-os-app-builder/templates/state/plan.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:
+    - $SDK_REF_PATH (focused SDK reference for this app's modules)
     - .frontier-app/PROJECT.md (App vision, SDK modules, constraints)
     - .frontier-app/manifest.json (Declared permissions and metadata)
     - .frontier-app/ROADMAP.md (Phase goal, success criteria, requirements)
@@ -139,8 +148,10 @@ Task(
     </files_to_read>
 
     <planning_rules>
-    - Phase 1 (Scaffold): ALWAYS exactly 1 plan. Uses templates from templates/app/.
+    - Phase 1 (Scaffold + Standalone Shell): ALWAYS exactly 1 plan. Uses standalone templates: `frontier-services.tsx`, `layout-standalone.tsx`, `package-standalone.json`, `main-router.tsx`, `vercel-standalone.json`.
+    - SDK Integration phase: ALWAYS exactly 1 plan. Mechanical — adds SDK dependency, creates adapter, upgrades Layout. Minimal research needed.
     - Feature phases: 1-3 plans. Prefer fewer, larger plans over many small ones.
+    - Feature phase tasks reference `useServices()` from `../lib/frontier-services` for all service access. Method names are validated against the focused SDK reference for correctness.
     - Each plan gets 2-3 tasks. Tasks are atomic — one clear action each.
     - Wave 1 = no dependencies. Wave 2 = depends on Wave 1. Usually 1 wave is enough.
     - Vertical slices: Plan 01 = Event listing (hook + component + route), NOT Plan 01 = All hooks.
@@ -192,7 +203,7 @@ Task(
     5. **Verification:** Does every plan include build + typecheck verification?
     6. **Dependencies:** Are wave assignments correct? No circular deps?
     7. **File conflicts:** Do any plans modify the same files in the same wave?
-    8. **Frontier compliance:** Dark theme, iframe detection, SdkProvider wrapping — all covered?
+    8. **Tier compliance:** Dark theme, services layer, mock data — all covered? (Tier 1 for feature phases; full SDK check for SDK Integration phase only)
     </check_criteria>
 
     <output>