frontier-os-app-builder 1.1.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.
@@ -139,13 +146,13 @@ For each plan file in `incomplete_plans`:
        <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)
@@ -256,12 +263,14 @@ When an executor agent returns a structured checkpoint (output contains `## CHEC
    [Awaiting section from agent return]
    ```
 
-   Use AskUserQuestion:
+   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:**
 
    ```
@@ -292,13 +301,13 @@ When an executor agent returns a structured checkpoint (output contains `## CHEC
        <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)
@@ -341,8 +350,8 @@ 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>
@@ -385,7 +394,7 @@ Phase [N]: [Name] — [checks_passed] checks passed, gaps remain.
 [Gap details from VERIFICATION.md Gaps section]
 ```
 
-Use AskUserQuestion:
+Use AskUserQuestion (if available):
 - header: "Verification Gaps"
 - question: "How do you want to handle these gaps?"
 - options:
@@ -402,6 +411,8 @@ Use AskUserQuestion:
 **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">

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>
 
@@ -156,7 +171,7 @@ N. **Phase N: SDK Integration** — Wire SDK, create adapter, upgrade Layout for
 Total permissions: [N]
 ```
 
-Use AskUserQuestion:
+Use AskUserQuestion (if available):
 - header: "Confirm"
 - question: "Does this look right?"
 - options:
@@ -166,19 +181,48 @@ 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">
@@ -278,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

@@ -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,10 +148,10 @@ Task(
     </files_to_read>
 
     <planning_rules>
-    - Phase 1 (Scaffold + Standalone Shell): ALWAYS exactly 1 plan. Uses standalone templates: `frontier-services.tsx`, `layout-standalone.tsx`, `package-standalone.json`, `main-simple-standalone.tsx` (for simple apps), `vercel-standalone.json`.
+    - 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 `sdk-surface.md` for correctness.
+    - 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.

package/workflows/ship.md

@@ -43,7 +43,7 @@ Recommended: Run `/fos:status` to see which phases are incomplete.
 Continue with deployment anyway? Some features may be missing.
 ```
 
-Use AskUserQuestion:
+Use AskUserQuestion (if available):
 - header: "Incomplete Phases"
 - question: "Deploy with incomplete phases?"
 - options:
@@ -52,6 +52,7 @@ Use AskUserQuestion:
   - "Cancel" — Go back and finish phases
 
 **If "Check status first" or "Cancel":** Exit workflow.
+**If AskUserQuestion denied:** Default to "Deploy anyway".
 
 **Display ship summary:**
 ```
@@ -90,14 +91,19 @@ else
   TEST_STATUS=0
 fi
 
+# Read the SDK Integration phase from the manifest so the validators run their
+# Tier-2 checks (CORS origins, SDK→services bridge, exact permissions). Empty
+# when no sdkPhase is set — the validator then falls back to the STATE.md phase.
+SDK_PHASE=$(node -e "const m=JSON.parse(require('fs').readFileSync('.frontier-app/manifest.json','utf8')); console.log(m.sdkPhase ?? '')")
+
 # 4. FOS structure validation
 echo "--- Structure ---"
-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 structure ${SDK_PHASE:+--phase "$SDK_PHASE"}
 STRUCT_STATUS=$?
 
 # 5. FOS permissions validation
 echo "--- Permissions ---"
-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 permissions ${SDK_PHASE:+--phase "$SDK_PHASE"}
 PERMS_STATUS=$?
 ```
 
@@ -172,9 +178,16 @@ Read the app name from manifest.json to construct the repo name.
 PACKAGE_NAME=$(node -e "const m=JSON.parse(require('fs').readFileSync('.frontier-app/manifest.json','utf8')); console.log(m.packageName)")
 REPO_NAME="frontier-os-${PACKAGE_NAME}"
 APP_DESC=$(node -e "const m=JSON.parse(require('fs').readFileSync('.frontier-app/manifest.json','utf8')); console.log(m.description)")
-ORG="BerlinhouseLabs"
+# Org is optional. Set FOS_GITHUB_ORG to create the repo under a GitHub org;
+# when it's empty the repo is created under the authenticated gh user.
+ORG="${FOS_GITHUB_ORG:-}"
+if [ -n "$ORG" ]; then
+  REPO_TARGET="$ORG/$REPO_NAME"
+else
+  REPO_TARGET="$REPO_NAME"
+fi
 
-echo "Repo: $ORG/$REPO_NAME"
+echo "Repo: $REPO_TARGET"
 ```
 
 **Check if remote already exists:**
@@ -184,16 +197,17 @@ git remote get-url origin 2>/dev/null
 
 **If no remote:**
 ```bash
-# Create private repo in the org
-gh repo create "$ORG/$REPO_NAME" --private --description "$APP_DESC" --source . --push
+# Create private repo (under $FOS_GITHUB_ORG if set, else the authed gh user)
+gh repo create "$REPO_TARGET" --private --description "$APP_DESC" --source . --push
 
 # Verify
-gh repo view "$ORG/$REPO_NAME" --json url -q .url
+gh repo view "$REPO_TARGET" --json url -q .url
 ```
 
 **If remote already exists:** Just push.
 ```bash
-git push -u origin main
+BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || echo main)
+git push -u origin "$BRANCH"
 ```
 </step>
 
@@ -247,7 +261,7 @@ This will prompt for team/project selection. After first deploy, subsequent depl
 <step name="app_registration">
 **Optionally register the app in the Frontier app store.**
 
-Use AskUserQuestion:
+Use AskUserQuestion (if available):
 - header: "App Store"
 - question: "Register this app in the Frontier app store? This makes it discoverable to Frontier OS users."
 - options:
@@ -255,6 +269,8 @@ Use AskUserQuestion:
   - "Later" — Skip registration, I'll do it manually
   - "Not needed" — This is a private/internal app
 
+If AskUserQuestion denied: default to "Later" — skip registration.
+
 **If "Register now":**
 ```
 ## App Registration

package/workflows/status.md

@@ -119,7 +119,6 @@ done
 
 wallet:
   - wallet:getBalance
-  - wallet:getBalanceFormatted
   - wallet:transferFrontierDollar
 
 events: