agent-app-creator

Agent App Creator

A Agent App is a self-contained local web app: one PocketBase process (data, auth, realtime, custom verbs) serving a React frontend built from a preset kit. You declare schema, compose UI, wire verbs — the platform owns the rest.

Step 0: Have a registered project (MANDATORY FIRST)

1. Task instruction contains Project ID + Project Path → the project is already scaffolded. Use those values. Skip scaffolding.
2. No Project ID in your instruction (user asked in a regular chat) → call agent_app_scaffold(name, description, auth_mode) — it scaffolds AND dispatches the build to the project's dedicated session. Tell the user the build started, then end your turn. Do NOT build in the chat session.

Pick auth_mode from requirements: none (personal local tool — default) or multi-user (accounts; the kit's LoginGate wraps the app automatically).

The ownership rule (the gate enforces this)

Edit ONLY:

Path	Purpose
frontend/src/app/	all UI code
pb/pb_migrations/	schema — one NEW migration per change
pb/pb_hooks/ops.pb.js + new *.pb.js / *.js modules	custom verbs + their helpers
operations.json	declarations for those verbs (non-system entries)
AGENT_APP.md	your plan/context/index — keep current

NEVER edit frontend/src/kit/, frontend/src/main.tsx, frontend/src/config.gen.ts, pb/pb_hooks/_system.pb.js, manifest.json, or build configs — the validation gate hashes them and fails the build if they changed. Need a variant of a kit component? Wrap it in app/:

// frontend/src/app/components/DueBadge.tsx
import { cn } from '../../kit/index.ts';
export function DueBadge({ overdue }: { overdue: boolean }) { /* compose */ }

Before coding

1. If reference/requirements.md starts with MARKETPLACE DECISION: install <app-id> — do NOT build. Call agent_app_marketplace_install(app_id=..., name=..., description=..., will_adapt=<true if the decision line says adapt: yes>). It installs INTO this project (same tab and id — never a duplicate).
   • adapt: no — the install completes the build and the system announces it; do NOT send your own summary and do NOT call notify_ready or walk_verify. End the run.
   • adapt: yes — after the install, apply ONLY the adaptations listed under ## Adaptations (modify flow: edit → agent_app_notify_ready → agent_app_walk_verify). If the list says "none specified", ask the user what to change (a FINAL send_message) instead of guessing. The user explicitly chose reuse over a fresh build — never rebuild what was just installed, even if a later trigger asks you to "continue" it.
2. Read agent_file_system/GLOBAL_AGENT_APP.md — colors, fonts, enforced rules.
3. Read {project_path}/AGENT_APP.md and reference/requirements.md. The creation wizard interviewed the user and synthesized requirements.md — it is the binding spec: implement it exactly and mirror its checklist into AGENT_APP.md. If it is absent, build from the project description; only ask the user (a FINAL send_message, continue_work=false) when something is genuinely blocking and you cannot reasonably decide it yourself.
4. Any feature need data from outside the app? Check, then research. FIRST check the [INTEGRATIONS this app can use] block already in your context — if a connected integration's action covers the feature (email = send_gmail), use bridge.callAction; nothing to research. Only for THIRD-PARTY public APIs: research like an engineer — endpoint, auth, response shape, limits. Spawn a research_agent; never write an integration hook from memory.
   • User named an API/service → research it. If it needs a key, tenant URL, or account detail you cannot find online, ask the user (final send_message) and build the rest of the app while waiting.
   • No API named → research candidates and pick a keyless public API yourself (e.g. Open-Meteo for weather). Choosing the source is your engineering call — no user round-trip.
   • Nothing usable exists → build the honest empty/offline state and REPORT the blocker in your final message. Mock or generated data is forbidden unless requirements explicitly ask for demo data.
5. A Agent App build is substantial work — the standard run protocol applies as-is (scope, plan, execute, verify, deliver); this skill adds nothing to it. reference/requirements.md is the binding spec verification checks against; mirror the feature checklist in AGENT_APP.md.