frontier-os-app-builder 1.0.0

package/bin/install.js

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ─────────────────────────────────────────────
+// Frontier OS App Builder — Installer
+// Copies commands, agents, workflows, references,
+// and templates into ~/.claude/
+// ─────────────────────────────────────────────
+
+const VERSION = '1.0.0';
+const PRODUCT = 'frontier-os-app-builder';
+
+// Source: this repo
+const SRC_ROOT = path.resolve(__dirname, '..');
+
+// Target: ~/.claude/
+const CLAUDE_HOME = path.join(require('os').homedir(), '.claude');
+const FOS_HOME = path.join(CLAUDE_HOME, PRODUCT);
+
+// Manifest tracking file
+const MANIFEST_PATH = path.join(FOS_HOME, 'fos-file-manifest.json');
+
+// ── Helpers ──────────────────────────────────
+
+function log(msg) { console.log(`  ${msg}`); }
+function success(msg) { console.log(`\x1b[32m  ✓\x1b[0m ${msg}`); }
+function warn(msg) { console.log(`\x1b[33m  !\x1b[0m ${msg}`); }
+function err(msg) { console.error(`\x1b[31m  ✗\x1b[0m ${msg}`); }
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function copyFile(src, dest) {
+  ensureDir(path.dirname(dest));
+  fs.copyFileSync(src, dest);
+  return dest;
+}
+
+function copyDir(srcDir, destDir) {
+  const copied = [];
+  if (!fs.existsSync(srcDir)) return copied;
+
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      copied.push(...copyDir(srcPath, destPath));
+    } else if (entry.isFile()) {
+      copyFile(srcPath, destPath);
+      copied.push(destPath);
+    }
+  }
+  return copied;
+}
+
+function removeFile(filePath) {
+  if (fs.existsSync(filePath)) {
+    fs.unlinkSync(filePath);
+    return true;
+  }
+  return false;
+}
+
+function removeDirIfEmpty(dir) {
+  if (fs.existsSync(dir)) {
+    const entries = fs.readdirSync(dir);
+    if (entries.length === 0) {
+      fs.rmdirSync(dir);
+      return true;
+    }
+  }
+  return false;
+}
+
+// ── Install ──────────────────────────────────
+
+function install() {
+  console.log(`\n\x1b[1mFrontier OS App Builder v${VERSION}\x1b[0m\n`);
+
+  // Check ~/.claude/ exists
+  if (!fs.existsSync(CLAUDE_HOME)) {
+    err(`~/.claude/ not found. Is Claude Code installed?`);
+    process.exit(1);
+  }
+
+  const installedFiles = [];
+
+  // 1. Commands → ~/.claude/commands/fos/
+  log('Installing commands...');
+  const cmdSrc = path.join(SRC_ROOT, 'commands', 'fos');
+  const cmdDest = path.join(CLAUDE_HOME, 'commands', 'fos');
+  const cmdFiles = copyDir(cmdSrc, cmdDest);
+  installedFiles.push(...cmdFiles);
+  success(`${cmdFiles.length} commands → ~/.claude/commands/fos/`);
+
+  // 2. Agents → ~/.claude/agents/
+  log('Installing agents...');
+  const agentSrc = path.join(SRC_ROOT, 'agents');
+  const agentDest = path.join(CLAUDE_HOME, 'agents');
+  if (fs.existsSync(agentSrc)) {
+    for (const file of fs.readdirSync(agentSrc)) {
+      if (file.startsWith('fos-') && file.endsWith('.md')) {
+        const dest = copyFile(path.join(agentSrc, file), path.join(agentDest, file));
+        installedFiles.push(dest);
+      }
+    }
+  }
+  const agentCount = installedFiles.filter(f => f.includes('/agents/fos-')).length;
+  success(`${agentCount} agents → ~/.claude/agents/`);
+
+  // 3. Workflows → ~/.claude/frontier-os-app-builder/workflows/
+  log('Installing workflows...');
+  const wfSrc = path.join(SRC_ROOT, 'workflows');
+  const wfDest = path.join(FOS_HOME, 'workflows');
+  const wfFiles = copyDir(wfSrc, wfDest);
+  installedFiles.push(...wfFiles);
+  success(`${wfFiles.length} workflows → ~/.claude/${PRODUCT}/workflows/`);
+
+  // 4. References → ~/.claude/frontier-os-app-builder/references/
+  log('Installing references...');
+  const refSrc = path.join(SRC_ROOT, 'references');
+  const refDest = path.join(FOS_HOME, 'references');
+  const refFiles = copyDir(refSrc, refDest);
+  installedFiles.push(...refFiles);
+  success(`${refFiles.length} references → ~/.claude/${PRODUCT}/references/`);
+
+  // 5. Templates → ~/.claude/frontier-os-app-builder/templates/
+  log('Installing templates...');
+  const tplSrc = path.join(SRC_ROOT, 'templates');
+  const tplDest = path.join(FOS_HOME, 'templates');
+  const tplFiles = copyDir(tplSrc, tplDest);
+  installedFiles.push(...tplFiles);
+  success(`${tplFiles.length} templates → ~/.claude/${PRODUCT}/templates/`);
+
+  // 6. CLI tool → ~/.claude/frontier-os-app-builder/bin/
+  log('Installing CLI tool...');
+  const binSrc = path.join(SRC_ROOT, 'bin', 'fos-tools.cjs');
+  const binDest = path.join(FOS_HOME, 'bin', 'fos-tools.cjs');
+  if (fs.existsSync(binSrc)) {
+    copyFile(binSrc, binDest);
+    installedFiles.push(binDest);
+    success(`CLI tool → ~/.claude/${PRODUCT}/bin/fos-tools.cjs`);
+  }
+
+  // 7. Write manifest
+  const manifest = {
+    version: VERSION,
+    installed_at: new Date().toISOString(),
+    files: installedFiles
+  };
+  ensureDir(path.dirname(MANIFEST_PATH));
+  fs.writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2));
+  installedFiles.push(MANIFEST_PATH);
+
+  // Summary
+  console.log(`\n\x1b[32m  ✓ Installed ${installedFiles.length} files\x1b[0m\n`);
+  console.log(`  Usage:\n`);
+  console.log(`    1. Create a directory for your new app`);
+  console.log(`    2. Run: /fos:new-app "your app description"`);
+  console.log(`    3. Follow the guided workflow\n`);
+  console.log(`  Commands: /fos:new-app, /fos:discuss, /fos:plan, /fos:execute,`);
+  console.log(`            /fos:ship, /fos:new-milestone, /fos:add-feature,`);
+  console.log(`            /fos:next, /fos:status\n`);
+}
+
+// ── Uninstall ────────────────────────────────
+
+function uninstall() {
+  console.log(`\n\x1b[1mUninstalling Frontier OS App Builder\x1b[0m\n`);
+
+  let removed = 0;
+
+  // Load manifest
+  if (fs.existsSync(MANIFEST_PATH)) {
+    const manifest = JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf-8'));
+    for (const file of manifest.files) {
+      if (removeFile(file)) removed++;
+    }
+  }
+
+  // Clean up directories
+  const dirsToClean = [
+    path.join(CLAUDE_HOME, 'commands', 'fos'),
+    path.join(FOS_HOME, 'workflows'),
+    path.join(FOS_HOME, 'references'),
+    path.join(FOS_HOME, 'templates', 'app'),
+    path.join(FOS_HOME, 'templates', 'state'),
+    path.join(FOS_HOME, 'templates'),
+    path.join(FOS_HOME, 'bin'),
+    FOS_HOME
+  ];
+
+  for (const dir of dirsToClean) {
+    removeDirIfEmpty(dir);
+  }
+
+  // Remove agent files
+  const agentDir = path.join(CLAUDE_HOME, 'agents');
+  if (fs.existsSync(agentDir)) {
+    for (const file of fs.readdirSync(agentDir)) {
+      if (file.startsWith('fos-') && file.endsWith('.md')) {
+        if (removeFile(path.join(agentDir, file))) removed++;
+      }
+    }
+  }
+
+  console.log(`\x1b[32m  ✓ Removed ${removed} files\x1b[0m\n`);
+}
+
+// ── Main ─────────────────────────────────────
+
+const args = process.argv.slice(2);
+
+if (args.includes('--uninstall')) {
+  uninstall();
+} else if (args.includes('--help') || args.includes('-h')) {
+  console.log(`
+Frontier OS App Builder Installer
+
+Usage:
+  node install.js              Install to ~/.claude/
+  node install.js --uninstall  Remove from ~/.claude/
+  node install.js --help       Show this help
+`);
+} else {
+  install();
+}

package/commands/fos/add-feature.md

@@ -0,0 +1,29 @@
+---
+name: fos:add-feature
+description: Add a feature as a new phase to the current milestone
+argument-hint: '"feature description"'
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+<objective>
+Add a new feature to the current milestone. Infers required SDK modules, creates a new phase in the roadmap, updates manifest with new permissions.
+
+**After this command:** Run `/clear` then `/fos:discuss <N>` for the new phase.
+</objective>
+
+<execution_context>
+@$HOME/.claude/frontier-os-app-builder/workflows/add-feature.md
+@$HOME/.claude/frontier-os-app-builder/references/module-inference.md
+@$HOME/.claude/frontier-os-app-builder/references/sdk-surface.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+Execute the add-feature workflow from @$HOME/.claude/frontier-os-app-builder/workflows/add-feature.md end-to-end.
+</process>

package/commands/fos/discuss.md

@@ -0,0 +1,31 @@
+---
+name: fos:discuss
+description: Discuss gray area decisions for a phase before planning
+argument-hint: "<phase-number>"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+<objective>
+Gather implementation decisions for a phase by identifying gray areas and discussing them with the developer. Produces CONTEXT.md that downstream planning and execution agents will honor.
+
+**Creates:**
+- `.frontier-app/phases/XX-name/XX-CONTEXT.md` — decisions, discretion areas, deferred ideas
+
+**After this command:** Run `/clear` then `/fos:plan <N>` to create execution plans.
+</objective>
+
+<execution_context>
+@$HOME/.claude/frontier-os-app-builder/workflows/discuss.md
+@$HOME/.claude/frontier-os-app-builder/references/sdk-surface.md
+</execution_context>
+
+<context>
+Phase: $ARGUMENTS
+</context>
+
+<process>
+Execute the discuss workflow from @$HOME/.claude/frontier-os-app-builder/workflows/discuss.md end-to-end.
+</process>

package/commands/fos/execute.md

@@ -0,0 +1,35 @@
+---
+name: fos:execute
+description: Execute all plans in a phase with automatic verification
+argument-hint: "<phase-number>"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Execute all plans in a phase using wave-based execution, then automatically verify the result.
+
+**Flow:** Analyze plan dependencies → spawn executor agents (parallel within waves) → spawn verifier agent
+
+Orchestrator stays lean: discover plans, group into waves, spawn subagents, collect results. Each executor gets a fresh context window with the full execute-plan workflow.
+
+**After this command:** Routes to `/fos:discuss <N+1>` for the next phase, or `/fos:ship` if all phases are done.
+</objective>
+
+<execution_context>
+@$HOME/.claude/frontier-os-app-builder/workflows/execute.md
+</execution_context>
+
+<context>
+Phase: $ARGUMENTS
+</context>
+
+<process>
+Execute the execute workflow from @$HOME/.claude/frontier-os-app-builder/workflows/execute.md end-to-end.
+</process>

package/commands/fos/new-app.md

@@ -0,0 +1,39 @@
+---
+name: fos:new-app
+description: Create a new Frontier OS app from a natural language description
+argument-hint: '"app description" [--auto]'
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Initialize a new Frontier OS app through guided flow: gather requirements, infer SDK modules from description, create phased roadmap.
+
+**Creates:**
+- `.frontier-app/PROJECT.md` — app vision, SDK modules, constraints
+- `.frontier-app/REQUIREMENTS.md` — scoped requirements
+- `.frontier-app/ROADMAP.md` — phased execution plan
+- `.frontier-app/STATE.md` — project memory
+- `.frontier-app/manifest.json` — machine-readable metadata
+
+**After this command:** Run `/clear` then `/fos:discuss 1` to discuss Phase 1 approach.
+</objective>
+
+<execution_context>
+@$HOME/.claude/frontier-os-app-builder/workflows/new-app.md
+@$HOME/.claude/frontier-os-app-builder/references/sdk-surface.md
+@$HOME/.claude/frontier-os-app-builder/references/module-inference.md
+@$HOME/.claude/frontier-os-app-builder/references/app-patterns.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+Execute the new-app workflow from @$HOME/.claude/frontier-os-app-builder/workflows/new-app.md end-to-end.
+Preserve all workflow gates (validation, approvals, routing).
+</process>

package/commands/fos/new-milestone.md

@@ -0,0 +1,28 @@
+---
+name: fos:new-milestone
+description: Start a new version milestone (v2, v3...) with additional features
+argument-hint: '"feature descriptions"'
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+<objective>
+Archive the current milestone and start a new one. Gathers new feature descriptions, infers SDK modules, creates new phases in the roadmap.
+
+**After this command:** Run `/clear` then `/fos:discuss <N>` for the first phase of the new milestone.
+</objective>
+
+<execution_context>
+@$HOME/.claude/frontier-os-app-builder/workflows/new-milestone.md
+@$HOME/.claude/frontier-os-app-builder/references/module-inference.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+Execute the new-milestone workflow from @$HOME/.claude/frontier-os-app-builder/workflows/new-milestone.md end-to-end.
+</process>

package/commands/fos/next.md

@@ -0,0 +1,29 @@
+---
+name: fos:next
+description: Auto-route to the next step in the workflow
+allowed-tools:
+  - Read
+  - Bash
+---
+<objective>
+Determine and route to the next logical step based on current project state.
+
+Reads `.frontier-app/STATE.md` and the project artifacts to determine what's needed next:
+- No context for current phase → `/fos:discuss N`
+- No plans for current phase → `/fos:plan N`
+- Unexecuted plans → `/fos:execute N`
+- All phases done → `/fos:ship`
+- Already shipped → `/fos:new-milestone` or `/fos:add-feature`
+</objective>
+
+<execution_context>
+@$HOME/.claude/frontier-os-app-builder/workflows/next.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+Execute the next workflow from @$HOME/.claude/frontier-os-app-builder/workflows/next.md end-to-end.
+</process>

package/commands/fos/plan.md

@@ -0,0 +1,37 @@
+---
+name: fos:plan
+description: Research existing apps and create execution plans for a phase
+argument-hint: "<phase-number>"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Create execution plans for a phase by researching existing Frontier OS apps, then planning with verification.
+
+**Flow:** Spawn researcher → planner → plan-checker (max 3 revision loops)
+
+**Creates:**
+- `.frontier-app/phases/XX-name/XX-RESEARCH.md` — patterns from existing apps
+- `.frontier-app/phases/XX-name/XX-YY-PLAN.md` — executable plans with tasks
+
+**After this command:** Run `/clear` then `/fos:execute <N>` to build the phase.
+</objective>
+
+<execution_context>
+@$HOME/.claude/frontier-os-app-builder/workflows/plan.md
+@$HOME/.claude/frontier-os-app-builder/references/sdk-surface.md
+@$HOME/.claude/frontier-os-app-builder/references/app-patterns.md
+</execution_context>
+
+<context>
+Phase: $ARGUMENTS
+</context>
+
+<process>
+Execute the plan workflow from @$HOME/.claude/frontier-os-app-builder/workflows/plan.md end-to-end.
+Preserve the plan-checker verification loop (max 3 iterations).
+</process>

package/commands/fos/ship.md

@@ -0,0 +1,29 @@
+---
+name: fos:ship
+description: Deploy to Vercel and register app in Frontier app store
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+<objective>
+Deploy the Frontier OS app to Vercel and optionally register it in the Frontier app store.
+
+**Flow:** Preflight checks (build, tests, verification) → Vercel deploy → app registration
+
+**After this command:** `/fos:new-milestone` to plan v2, or `/fos:add-feature` to extend.
+</objective>
+
+<execution_context>
+@$HOME/.claude/frontier-os-app-builder/workflows/ship.md
+@$HOME/.claude/frontier-os-app-builder/references/deployment.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+Execute the ship workflow from @$HOME/.claude/frontier-os-app-builder/workflows/ship.md end-to-end.
+</process>

package/commands/fos/status.md

@@ -0,0 +1,22 @@
+---
+name: fos:status
+description: Show current project state — milestone, phases, modules, progress
+allowed-tools:
+  - Read
+  - Bash
+---
+<objective>
+Display the current state of the Frontier OS app project: milestone, phases with status, SDK modules, permissions, and what to do next.
+</objective>
+
+<execution_context>
+@$HOME/.claude/frontier-os-app-builder/workflows/status.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+Execute the status workflow from @$HOME/.claude/frontier-os-app-builder/workflows/status.md end-to-end.
+</process>

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "frontier-os-app-builder",
+  "version": "1.0.0",
+  "description": "Meta-prompting framework for building Frontier OS apps with Claude Code",
+  "author": "BerlinhouseLabs",
+  "license": "MIT",
+  "bin": {
+    "frontier-os-app-builder": "./bin/install.js"
+  },
+  "files": [
+    "bin/",
+    "commands/",
+    "agents/",
+    "workflows/",
+    "references/",
+    "templates/",
+    "README.md"
+  ],
+  "keywords": [
+    "frontier-os",
+    "claude-code",
+    "frontier-sdk",
+    "app-builder",
+    "meta-prompting"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BerlinhouseLabs/frontier-os-app-builder.git"
+  }
+}