Kelly App Skill Creator

Kelly App Skill Creator

Turn a recurring human-and-Agent operation into a Busabase-backed skill with a canonical Hono project whose normal delivery target is Busabase AirApp. Own the product workflow and the App-in-Skill artifact contract; delegate Busabase resource implementation and AirApp deployment mechanics.

Ownership Boundary

This skill is a taste layer over a format layer, and the split is what keeps both honest:

• $busabase-app-creator (also published as busabase-skill-creator and busabase-template-creator — one skill, three names) owns everything that makes the artifact valid: the skill/template/package format, AirApp runtime language, framework, server shape, dependency and SDK constraints, security boundaries, validation, sync, and deployment mechanics. Its own contract says it is "format and correctness, not taste" — it deliberately carries no visual opinions, so this layer can.
• This skill owns everything that makes the artifact Kelly's: product behavior, information architecture, visible UI, layout, interaction patterns, responsive behavior, accessibility, Help & Settings, hash routing, and visual acceptance for every generated app. Creating the underlying artifact is that skill's package-first route (§ "Two Ways In" there) with this skill's UI contract applied on top.
• $kelly-app-skill-creator-tests owns repository-level conformance, process, responsive browser, OSS Busabase, Cloud OAuth, persistence, and AirApp parity tests for the generated app.
• Do not delegate Kelly UI decisions to $busabase-app-creator, and do not let a runtime scaffold replace or weaken this skill's desktop or phone shell.
• Do not restate AirApp runtime limits here. When a runtime rule affects UI implementation, satisfy it inside the UI contract rather than creating a competing runtime contract.

Mandatory Dependencies

Before creating or changing an app:

1. Read and follow $busabase for connection, target Space, node discovery, ChangeRequests, review, merge, and trusted mutations.
2. Read and follow $busabase-app-creator for resource modeling, native Views, Vault boundaries, AirApp constraints, scaffolding, validation, sync, and deployment. Creating an app-skill takes its package-first route — that skill's own guidance already routes a skill there, because a skill carrying an app is a template. The artifact is authored as a template package and verified by installing it; this skill's UI contract governs what the app inside it looks like.

If a dependency is unavailable, preserve this skill's local artifact and product contracts, stop before the unavailable Busabase operation, and report the exact missing dependency. Do not invent a second data backend.

Before declaring a generated app complete, read and follow $kelly-app-skill-creator-tests. Keep app-owned unit tests in <app-root>/test/ and delegate shared harness, external Busabase, OAuth, responsive browser, and AirApp parity acceptance to that testing skill. If it is unavailable, run the app's deterministic local checks and report the missing conformance suites rather than claiming full completion.

Reference Map

Read the two UI references completely for every app creation or UI change. Read the other selected references completely before acting:

App-in-Skill Contract

• Every generated skill includes a complete canonical AirApp project with its own package.json, lockfile, server entry, browser files, and checks. It lives at <skill-root>/content/<name>-app/ — the busabase template layout, which is simply what an app-skill looks like: the same directory is a skill, a template, and an installable package, with no second copy of anything. kelly-email is the fleet's reference for this shape.
• A skill still holding its project at <skill-root>/app/ predates that layout and is awaiting migration — the fleet is being converted. Maintain such a skill where it is; do not relocate one as a side effect of unrelated work, because the move also rewrites harness paths, root scripts, and the scripts' own relative imports, and each one needs its suite re-run. Migration is its own task, not a by-product.
• Either root must remain locally runnable with pnpm --dir <that-root> dev, but do not start it unless the user explicitly asks for local preview or local debugging. The rest of this document calls whichever one applies the app root.
• When the user asks to start, open, or launch an existing local app, open the bare production URL without ?demo=1 or any other Demo selector. The normal launch path must exercise the Busabase connection and OAuth gate. Demo is an explicit opt-in for a requested demo, screenshot, recording, or a separate UI acceptance pass; never present its URL as the normally launched app.
• Delegate the runtime language, framework, dependency, SDK bundle, server, Nodepod, validation, and deployable-file rules to $busabase-app-creator. Never restate or override those rules here or in a generated domain skill.
• Treat the committed local source as canonical. Build and sync the AirApp from that source; never leave a remote-only AirApp edit without back-porting it.
• Use the same UI, routes, domain logic, validation, and Busabase resource map locally and in AirApp. Isolate only the runtime bootstrap/transport adapter.
• Use busabase-sdk as the application data boundary. Persistent domain config, workflow state, user decisions, locks/claims, and domain records belong in Busabase, not local JSON, app/.data/, SQLite, or browser storage.
• Permit environment variables only for connection bootstrap such as BUSABASE_BASE_URL, BUSABASE_API_KEY, and BUSABASE_SPACE_ID. They are not a parallel domain-config system.
• Never expose an API key or Vault value to browser code, UI state, logs, demos, or screenshots. Secret access stays in the Hono server or trusted AirApp execution boundary.
• Keep external side effects outside the AirApp. The AirApp may submit a ChangeRequest-producing decision or proposal; only a trusted Agent or Workflow may use Vault-backed integrations to send, publish, delete, charge, transfer, or mutate an external system after its own required authorization.
• Use local storage only for disposable browser presentation state when it cannot affect behavior, authorization, workflow, or cross-device expectations. Store operator preferences in Busabase when they should follow the operator.
• Do not offer provider choice. Local development connects to local, Cloud, or self-hosted Busabase through the same SDK contract.

Default Delivery Mode

Use airapp-first unless the user explicitly asks for pnpm dev, a local URL, local preview, or local debugging.

• In airapp-first, generate and keep the app root as the canonical source, run its deterministic checks, and submit that same reviewed tree as a Busabase AirApp ChangeRequest. Do not start a standalone local server merely because the project supports one.
• After the named AirApp CR is merged with explicit authority, Run the AirApp in the selected Busabase and perform product, desktop, phone, ambient-session, resource, and real-data acceptance there. Return the exact clickable AirApp URL; do not substitute a localhost URL.
• Use local-preview only after an explicit user request. Then start pnpm dev, apply the Connection UX Contract, report the bare non-Demo local URL as the primary user-facing URL, and state plainly that the process is standalone and has not uploaded or deployed an AirApp. When acceptance also requires Demo, exercise it as a separate validation route rather than the launch default.
• A Folder or Base created in Busabase does not prove that the AirApp exists. Confirm an actual airapp node and its merged version before saying it was uploaded, deployed, or is running in Busabase.
• Local preview never becomes a second implementation. Whether or not it is started, the same app-root tree remains the only source submitted to AirApp.

Connection UX Contract

When local-preview was explicitly requested, every standalone App-in-Skill must be usable without a CLI login or pasted API key. Only in that standalone context, when no connection exists, show one focused setup screen with:

• a selected Busabase Cloud option using the canonical Cloud URL;
• a Custom server option that reveals one URL field for self-hosted or enterprise Busabase;
• one primary Connect Busabase action that starts browser OAuth;
• one secondary, visually quieter Demo action when the app has a deterministic Demo provider.

Do not ask for an API key, device code, terminal command, provider selection, or secret-storage choice. Cloud/custom is a hosting target choice, not a data provider choice. Preserve the chosen server only as connection bootstrap; all product configuration still comes from Busabase nodes through busabase-sdk.

After OAuth returns, distinguish successful authentication, Space targeting, and resource readiness. Call Busabase auth verification without a Space header to obtain every accessible Space. When Cloud or an enterprise host returns more than one, show a native Space selector with names and safe ids; do not inspect, initialize, or repair app resources until the operator confirms one. When it returns exactly one, select it automatically. Open-source Busabase reports its single local Space and never shows this selector.

Persist only the validated Space id as local connection bootstrap, separately from domain configuration, and inject it as x-busabase-space on every proxied SDK request. Changing server or signing out clears the selection. Show the selected Space name/id on later setup and Help & Settings screens. An expired or revoked session returns to the connection screen with a concise retry message. Demo never impersonates a successful connection and remains explicitly labeled read-only.

Use the canonical createBusabaseAirAppLocalGateway() exported by busabase-sdk/airapp-node; do not copy PKCE, token refresh, Space persistence, or proxy code into each server.js. Browser-provided x-busabase-space is untrusted and must never override the gateway's validated server-side choice. Treat SPACE_SELECTION_REQUIRED and SPACE_NOT_ALLOWED as stable reasons; never parse a human error sentence to decide which setup screen to render.

"Standalone" is a fact the host states, not one the app infers

Copy assets/runtime-detection/ — do not re-derive it. Three files, and every generated App gets all three:

This is a copied asset rather than prose because prose did not hold: 65 generated Apps had each independently reinvented the same loopback-hostname test, and one App's own check script had gone as far as requiring it.

Busabase spawns the App's own process in every runtime it hosts and injects a non-empty BUSABASE_AIRAPP_RUNTIME. Nobody else sets it, so its absence is the positive fact "standalone". server.js must re-expose the result from describeBusabaseAirAppRuntime() — the browser cannot read environment variables, and the SDK keeps renamed and future runtime values compatible.

Never derive this from the URL — not the hostname, not window.self !== window.top, not a /api/airapp-preview/ path prefix. Every such test misfires in both directions. A Busabase-hosted App is served from localhost on Desktop and OSS (http://localhost:15419), so "loopback ⇒ standalone" is wrong; and a standalone pnpm dev is routinely reached over a LAN IP or a signed dev tunnel such as https://3111-t14e66e832aa5e6a.dev.budaapps.com, so "not loopback ⇒ hosted" is wrong. The second direction is the damaging one: the App hides its own connect gate, calls /api/v1 with no credential, and reports an error the operator cannot act on.

Browser code probes __airapp/runtime relatively (no leading slash — a hosted App can be served from a sub-path of Busabase's origin) and must verify the response is JSON, since a hosted origin's catch-all route can answer 200 with an HTML shell.

runtime.js resolves the probe with a top-level await, so its two predicates stay synchronous for their call sites. When a module both re-exports one of them and calls it, use import + export, never export { … } from "./runtime.js" — a re-export does not bind the name locally, and the App dies at runtime with shouldUseLocalGateway is not defined while every static check still passes.

Resolve three states, never two — hosted, standalone, unknown — and let each decision fall to its own safe side when the runtime is undetermined:

scripts/check.mjs must fail on location.hostname and iframe-nesting tests, and must assert the server exposes /__airapp/runtime.

Apply references/setup-onboarding.md after authentication. Infrastructure readiness and product onboarding are separate: a connected, materialized AirApp may still need operator context, policies, sources, thresholds, schedules, or approval rules before the workflow can act.

Never tell the operator to create Nodes/Bases, approve a list of unnamed ChangeRequests, or copy materialized ids into deployment config. For an approved lazy-provisioning blueprint, show one Initialize workspace action only after Space selection and concise progress while $busabase-app-creator submits the exact declared structure as an idempotent ChangeRequest in that Space. Continue automatically when it materializes. If the viewer lacks write permission, show the one pending CR id or the exact permission needed; the operator reviews that request, not a manual schema recipe.

This screen must fit the same phone contract as the main app: one-column server choices and full-width primary action at 390px and 360px, no horizontal overflow, and no terminal instructions. A deployed AirApp uses the ambient Busabase session and must not show the local OAuth gate, call /auth/status or /auth/start, or navigate to a Busabase OAuth endpoint.

Delegate PKCE, callback validation, owner-only local credential registration, refresh/revoke behavior, proxy injection, and AirApp ambient-session rules to $busabase-app-creator. Browser JavaScript must never receive an OAuth access token, refresh token, PKCE verifier, or Vault value.

Mandatory UI Contract

Build a quiet operator tool, not a landing page or generic dashboard. Apply references/ui-workflow-patterns.md and references/mobile-shell-layout.md as hard implementation and acceptance gates.

• Put the brand, human-attention summary, workflow navigation, and Help & Settings in a fixed desktop sidebar. Collapse it to an icon rail with a panel icon; keep the brand icon visible.
• State the human task in action language and show the primary attention count above workflow navigation. Use stable row references for review queues.
• For item-oriented work, use a desktop list/detail split such as minmax(360px, 38%) minmax(0, 1fr). Keep list and detail scrolling inside their panes.
• Use native hash routes for meaningful views, selection, and Help & Settings so refresh and browser back/forward restore context.
• At widths up to 720px, switch to a real phone shell: compact top bar, off-canvas sidebar with scrim, separate full-height list and detail panes, sticky back-to-list control, and sticky primary detail action when the workflow has one. Do not merely shrink the desktop UI.
• Keep touch targets 36-44px, wrap long values, and prevent page-level horizontal overflow. Make Help & Settings a responsive modal and a full-screen panel on phones.
• Verify at approximately 1280x820, 390x844, and 360x740. Exercise sidebar collapse/drawer, scrim, navigation, row selection, detail back, modal tabs, browser history, and overflow before handoff.

Busabase Resource Discipline

Select nodes for their native strengths instead of putting everything in one JSON blob:

• use Folder and the Node tree for the app root, resource discovery, hierarchy, stable ownership, and navigation;
• use Base for structured configuration, policies, workflow rows, review items, claims, metrics, and relations;
• use Vault for secrets and secret references; surface readiness only;
• use Doc for long-form instructions, research templates, playbooks, and editable narrative content;
• use Drive and File for imports, attachments, exports, and large artifacts;
• use native Views for routine table, gallery, kanban, calendar, and gantt work;
• use AirApp for cross-resource synthesis, prioritization, guidance, and focused commands.

Create an explicit resource map before implementation. Record stable node ids or slugs, purpose, schema/version, read/write behavior, mutation path, and the screens or jobs that consume each resource. See references/busabase-data-contract.md.

Product Loop

Default to this four-stage operating loop.

Research

Collect evidence on a schedule or on demand. Update an idempotent report for its period key and record source freshness, coverage, uncertainty, and findings.

Plan

Turn evidence into concrete, deduplicated work items linked back to their sources. Let humans opt out, block, reprioritize, reschedule, or request revision. Use an attention queue instead of forcing users to inspect every row.

Action

Claim eligible work atomically, create reviewable deliverables or ChangeRequests, record progress and failures, and keep consequential side effects behind the trusted approval/execution path.

Retrospective

Compare outcomes with original evidence and decisions. Propose improvements to prompts, skills, thresholds, sources, schedules, resource schemas, or UI as new Plan items; do not silently rewrite production rules from one outcome.

Not every stage needs its own screen. State where each stage happens or why it is intentionally omitted.

Discovery

Ask one question at a time. Learn enough to determine:

• who operates the app, how often, and what outcome they own;
• what triggers Research and defines one reporting period;
• how evidence becomes a deduplicated Plan item;
• what defaults to eligible and what humans may stop or revise;
• what Action produces, where it is reviewed, and which effects are external;
• what makes Retrospective useful;
• which states require human attention;
• which operations belong in native Views versus AirApp;
• which existing Busabase Folder, Base, Doc, Drive, File, Skill, or Vault nodes should be reused and which must be proposed.

Do not ask the user to choose a provider, framework, schema mechanism, local config path, or secret-storage method.

Product Overlay

Before creation, produce this concise overlay for $busabase-app-creator:

# Product Overlay

User and outcome: ...
App type: ...

Research: trigger, period key, evidence, freshness, idempotency
Plan: issue/recommendation rule, traceability, default eligibility, opt-out
Action: atomic claim, deliverable, review point, external side effects
Retrospective: outcome signals, cadence, skill/process feedback

Human attention states: ...
Agent responsibilities: ...
Product onboarding: required operating context and completion/version rule
Native Views needed: ...
AirApp screens and focused actions: ...
Busabase resource map: Folder/Node root, Bases, Docs, Drives/Files, Vault refs
Delivery mode: airapp-first unless the user explicitly requested local-preview
Guide copy in plain language: ...
Explicit exclusions: ...

The overlay describes product behavior. $busabase-app-creator translates it into the complete resource graph, capability matrix, security model, canonical app-root scaffold, AirApp-compatible implementation, validation, sync, and deployment.

Creation Workflow

1. Read the relevant references and inspect nearby App-based skills before choosing a structure.
2. Establish the Busabase connection and explicit target Space.
3. Discover the target Node tree and draft the resource map.
4. Agree on the Product Overlay and let $busabase-app-creator validate the technical blueprint.
5. Have $busabase-app-creator create or update the complete canonical project at the app root. Do not invent a second runtime layout in this skill.
6. Implement one Busabase repository/service boundary over busabase-sdk. Browser code calls Hono/AirApp routes; it does not hold credentials.
7. Implement the runtime/product onboarding state and every review/execution lifecycle required by the overlay. Apply references/setup-onboarding.md and references/review-and-execution-contract.md; do not invent local markers, locks, or a second provider.
8. Keep setup, seed, refresh, migration, validation, and sync scripts as thin entrypoints over shared modules. Avoid Python, native binaries, subprocess orchestration, and filesystem-backed workflow state unless a domain adapter strictly requires them and AirApp compatibility is preserved.
9. Run app-owned lint/typecheck/tests/build without starting a persistent local server, then use $kelly-app-skill-creator-tests for repository-level contract, browser, OSS, and available Cloud suites. When the user explicitly selected local-preview, also run pnpm --dir <app-root> dev and complete local connection, workflow, recovery, desktop, and phone acceptance before continuing.
10. By default, submit the same canonical source directly as a reviewable AirApp CR through $busabase-app-creator; return its clickable Busabase review URL and wait for the named merge authorization.
11. After merge, Run the AirApp in Busabase and verify the same resource map, representative data, ambient session, main workflow, recovery states, and mandatory desktop/phone shell behavior. Report the canonical AirApp URL. Report a local URL only when local-preview was explicitly requested.

Onboarding And Readiness

Apply references/setup-onboarding.md. The app must remain startable in an explicit local preview even when Busabase is not ready, and the hosted AirApp must render one setup/onboarding gate rather than silently switching to local or Demo data. Distinguish runtime readiness from product onboarding.

Runtime readiness states include:

• missing connection bootstrap;
• unauthenticated or unreachable Busabase;
• ambiguous or inaccessible Space;
• missing app Folder/resources;
• schema migration needed;
• missing Vault references;
• ready.

Product onboarding separately covers the durable operating context, policies, sources, schedules, thresholds, and approval rules required by this workflow. Persist its fields and completion/version state in Busabase. Do not enable external reads or consequential actions whose product prerequisites are incomplete.

Declare an onboarding contract in the Product Overlay and machine-readable blueprint with a positive integer version, explicit required fields, their owning Base/Doc resource keys, validation rules, and the actions each field unlocks. A product with no onboarding requirements must declare an explicit empty contract and rationale; omission is not equivalent to “none.” Persist onboarding_version, completion state, and materialized completion time in the declared Busabase resource. A version mismatch enters needs_review or migration_needed, never complete.

For missing or expired authentication, apply the Connection UX Contract above; do not replace its OAuth action with CLI instructions or a credential input.

Show sanitized connection and resource identifiers plus an actionable recovery step. Never accept or echo secret values in the browser. Provision or repair resources through reviewed ChangeRequests when required. A recovery step may ask the operator to initialize, retry, select a Space, or review one named CR; it must not delegate Node/Base construction or id wiring to them.

Completion Criteria

Finish only when:

• the skill contains a complete canonical app-root project and pnpm --dir <app-root> dev remains supported, whether or not local preview was requested;
• $busabase-app-creator runtime, SDK, security, validation, and deployment checks pass without a conflicting local runtime contract;
• $kelly-app-skill-creator-tests required local and OSS suites pass, and its Cloud/AirApp suites pass when their declared environment is available; skipped external suites are reported explicitly;
• the Busabase connection, target Space, app root, and resource map are explicit;
• all persistent config, state, decisions, claims, and domain data use busabase-sdk and appropriate Busabase nodes;
• Vault values and API credentials never reach browser-visible surfaces;
• local setup offers Cloud/custom URL OAuth plus an explicit Demo path, while deployed AirApp uses its ambient session;
• local OAuth verifies accessible Spaces, auto-selects a single/open-source Space, requires an explicit selector choice for multiple Spaces, and performs no resource initialization before that choice;
• the local Hono boundary consumes busabase-sdk/airapp-node, ignores inbound Space headers, and branches on stable Space reasons;
• Research, Plan, Action, and Retrospective are represented or intentionally omitted;
• human attention, opt-out, review, and Agent claim rules are unambiguous;
• runtime readiness, product onboarding, review verdicts, Agent revision, external execution, and recovery obey their selected reference contracts;
• the blueprint declares onboarding version, required fields, Busabase storage, validation, and unlock rules, or an explicit empty contract with rationale;
• local and AirApp runs use the same application source and resource contract;
• the default delivery produced a merged, verified AirApp and a clickable target URL; a local URL is reported only for an explicitly requested local preview;
• the Kelly desktop sidebar, attention, workflow navigation, list/detail, hash routing, and Help & Settings contract is implemented where applicable;
• 1280px desktop, 390px phone, and 360px narrow-phone workflows pass visual, interaction, and horizontal-overflow checks;
• validation, deployment, and real-data checks required by dependency skills pass, and were verified as described in "A Green Suite Is Not An Acceptance".

A Green Suite Is Not An Acceptance

Passing tests say the cases you thought of hold. Before reporting a change as verified, exercise it the way a real caller will:

• Run the actual command against a real instance, not only the unit cases. A pure-assertion check of an integration is a statement about your assumptions.
• Confirm a new regression test fails without its fix. A test written after the diagnosis usually passes either way; one that cannot fail proves nothing. Revert the fix, watch it go red, restore it.
• Ask which variant the existing test happened to take. A round-trip test that preserved server-owned ids stayed green through a bug that blanked every secret in the scope, because the failing path was the variant nobody wrote.
• Suspect the environment before the diagnosis. A stale local database, an absent encryption key, or missing node_modules produces failures that look exactly like a regression in the change under review. Establish which it is before concluding anything.
• Re-check downstream assumptions after changing a shared surface. A fix that makes a previously-404 route work turns every client's untested error path into a live code path. Ship the client-side follow-up with it, not after a user finds it.

Report what was actually executed and what was skipped. "Tests pass" without saying which environment they ran in is not a result.

Stop Conditions

Stop when a dependency is unavailable for the next required operation, the target Space or app root is ambiguous, node capabilities cannot support the intended model, a secret would cross into the browser, a side effect lacks a reviewed trusted-execution path, or local and AirApp implementations would require separate business logic.