---
name: goalmatic-app-builder
description: Use when creating or improving a Goalmatic mini app in Site Builder, connecting platform resources, or preparing an app release.
---

# Build a Goalmatic app

Create a focused app that uses Goalmatic identity, workspace resources, agents, workflows and integrations. Establish the requested app behavior and whether the user wants a draft, preview or published release.

## Start with the existing project

1. Open the user's selected project through the connected Goalmatic builder tools or https://goalmatic.site. Inspect available tool schemas and the current project before editing.
2. Identify the main user journey, existing source, app settings and resource declarations. Preserve unrelated edits and the current published version.
3. Reuse generic platform capabilities. Keep product-specific UI and business behavior in the app; do not invent private core endpoints or embed another workspace's resource IDs.

## Declare resources

In Settings → Goalmatic App, review the name, slug, semantic version, visibility, support links and fork policy. The versioned `.goalmatic/app.json` contract declares capabilities and logical resources.

Use logical IDs such as `customers`, `research-agent` or `daily-report-flow`. Resolve them through the installation rather than copying a physical table, agent, workflow or connection ID. Declare only capabilities needed by the app's actual journeys.

## Use the runtime contract

Inspect the current runtime documentation and existing call sites for exact argument shapes before writing code. Published app pages expose these platform APIs:

- `GoalmaticAuth.getUser()` for safe session identity.
- `GoalmaticData.fetch/submit/update/remove` for the installation's mapped Tables.
- `GoalmaticConnect.agents.chat` for a declared agent.
- `GoalmaticApp.execute` for capability-approved platform operations.
- `GoalmaticAI.text` and `GoalmaticAI.json` for AI generation through the shared platform.

Keep privileged credentials out of browser code. Use the app session and approved connection flows. Treat authorization and insufficient-credit responses as visible product states with a useful next step.

For tools and workflow nodes, reference the supported versioned operation ID and request its capability. Discover current operations; do not assume a made-up method exists.

## Design the full journey

- Include loading, empty, success and recoverable failure states.
- Separate demo data from live workspace data. Guest access must use the intended public contract.
- Confirm who pays for AI under the current app settings; do not assume the creator always pays.
- Check ownership and resource mapping after installation or a fork. Source copying does not copy user records, connections or authorization.
- An offline app shell does not prove offline data access or queued writes. Design those behaviors explicitly if requested.

## Verify and release

1. Save the source and inspect the preview. Exercise the main journey and at least the relevant permission or empty-data state.
2. Verify persistence by reopening the changed record or screen; a successful render alone is insufficient.
3. Before publishing, identify the exact saved version, app identity, visibility and permissions. Publish only when the user's request authorizes that release.
4. Increment the semantic version for a changed published source. A release is immutable; prepare a new version to change it.
5. Verify the published runtime separately from the preview. Check the public app listing separately from publication; marketplace review and caching may affect discoverability.
6. Report the preview or release URL, version and evidence, with any remaining review or installation step.

## Entry points

- Builder: https://goalmatic.site
- Apps: https://goalmatic.io/apps
- Core operations guide: https://goalmatic.io/skills/goalmatic-core/SKILL.md