agent-app-creator

Files (9)

• SKILL.md
• EXAMPLES.md · references/
• INTEGRATIONS.md · references/
• MVC-A.md · references/
• QUESTIONNAIRE.md · references/
• STANDARDS.md · references/
• TRIGGERS.md · references/
• TROUBLESHOOTING.md · references/
• VERIFY.md · references/

SKILL.md (first lines)

# 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/`:

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

## Before coding

0. **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.
1. Read `agent_file_system/GLOBAL_AGENT_APP.md` — colors, fonts, enforced rules.
2. 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.
3. **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.
4. 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`.

## Per feature: schema → verbs → UI

**Schema** — add a new file in `pb/pb_migrations/`. **Never edit AND never
rename or delete a migration that has been applied** (i.e. after any
successful launch): the filename is the identity in the live database.
Renaming one makes every boot re-run its "new" replacement into the existing
schema — PocketBase exits before serving anything and the app cannot start
until the original filename is restored. Fixing a migration's mistake =
writing a NEW migration that alters the collection.
The ONLY top-level call is `migrate(upFn, downFn)` — the down/rollback
function is the **second argument**. A top-level `rollback(...)` does not
exist and panics the whole PocketBase process at load. Follow the starter
migration's pattern exactly: field types, `autodate`
created/updated, and rules matching the project's `authMode` (`manifest.json`):
`''` open rules for `none`; `@request.auth.id != ""` (or owner-scoped
`owner = @request.auth.id` with a `relation` to `users`) for `multi-user`.

**Seeding records in a migration:** `new Record(...)` takes the **Collection
OBJECT — never an id string**. Passing `someCollection.id` nil-panics
PocketBase internally and can WEDGE the process (alive, silent, never
serving). The gate kills and reports it, but write it right:

```js
const locations = app.findCollectionByNameOrId('locations'); // the OBJECT
const record = new Record(locations);
record.set('city_name', 'Manchester');
app.save(record);
```

**Relation fields — the #1 migration mistake:** `collectionId` must be the
target collection's **ID, never its name**. Save the target collection first,
then reference it:

```js

From CraftOS-dev/CraftBot, MIT.

More from CraftOS-dev/CraftBot