# Foundation App Builder

Canonical agent workflow for frontend apps that consume the Foundation backend through `foundation-sdk`.

Last updated: 2026-06-29

## Use This When

- Creating a new Foundation-backed web app.
- Adding Foundation SDK integration to an existing React, Vue, Svelte, Next, or plain web app.
- Adding Foundation-backed features such as auth, database CRUD, files, integrations, account screens, OAuth consent, or config-driven UI.
- Reviewing a consumer app before Foundation deployment.

## Required References

- SDK reference: https://docs.foundationmvp.com/agents/foundation-sdk-reference.md
- Deploy contract: https://docs.foundationmvp.com/agents/foundation-deploy-contract.md
- Full docs bundle: https://docs.foundationmvp.com/llms-full.txt

## Workflow

Classify the request first:

- New app: create or adapt a frontend app that consumes Foundation.
- Existing app: add Foundation SDK initialization, auth, services, or deployment files without rewriting unrelated code.
- Feature: add one Foundation-backed workflow to an app that already has SDK initialization.
- Review: audit SDK usage and deploy readiness.

## New App Or Retrofit

1. Inspect the existing repo before editing. Preserve framework, routing, styling, and state-management conventions.
2. Install `foundation-sdk` plus the selected auth peer: `aws-amplify` for Cognito or `@auth0/auth0-spa-js` for Auth0.
3. Create one SDK initialization module or provider. Await `createFoundation(...)` once and share the instance through app context/state.
4. Support local development with explicit `configUrl`, `tenantId`, `appId`, and optional dev-only `baseUrl`.
5. Support production by allowing `createFoundation({ auth })` to read `/foundation-env.json`.
6. Implement login, registration, auth callback, logout, and guarded routes as requested.
7. Build the requested core workflow with `foundation.db`, `foundation.files`, `foundation.integration`, `foundation.account`, `foundation.oauth`, `foundation.config`, or `foundation.log`.
8. Add `mvp.config.json` at the app repo root and verify its output directory and entry file.
9. Run available typecheck, lint, tests, and build scripts.

## Feature Additions

Reuse the existing Foundation instance. Do not introduce a second `createFoundation()` call.

Keep service calls in the app's established data layer, hook, store, or route loader pattern. Add loading, empty, success, and error states. Handle unauthenticated users before calling authenticated services.

Use pagination for lists that can grow, compute `sha256` before file upload, refresh integration status after connect/disconnect, and respect `foundation.config` for backend-provided theme, features, plans, connectors, and resources.

## Review Mode

Use a code-review stance. Lead with findings ordered by severity and include file/line references.

Prioritize:

- Missing or invalid `mvp.config.json`.
- Build output mismatch with `files` or `entry`.
- Missing SDK or auth peer dependency.
- Wrong auth provider entry point.
- Un-awaited or duplicated SDK initialization.
- Production code that depends on dev-only `baseUrl`.
- Sign-in or sign-up flows that ignore result objects.
- Missing hosted-login callback handling.
- Unguarded authenticated routes.
- File uploads without `sha256`.
- Integration flows that only handle one connect response shape.
- Frontend secrets or hardcoded user tokens.

If no major issues are found, say so and list remaining test gaps or backend assumptions.

## Default `mvp.config.json`

```json
{
  "build": "npm install && npm run build",
  "files": "dist",
  "entry": "index.html",
  "sdk": "^1.0.0"
}
```

Adjust `files` and `entry` only when the chosen framework uses a different build output.

## Starter User Prompt

```text
Use https://docs.foundationmvp.com/agents/foundation-app-builder.md to build a production-ready frontend app that consumes the Foundation backend.

App goal:
Framework and router:
Styling system:
Auth provider: Cognito or Auth0
Foundation config URL for local development:
Foundation tenant ID for local development:
Foundation app ID for local development:
Optional local API proxy base URL:
Entities to use through foundation.db:
File workflows to support through foundation.files:
Integrations to support through foundation.integration:
Account/profile fields:
Deployment output directory:
Deployment entry file:
```