Imported from ColineApp/coline-sdk (packages/create-coline-app/AGENTS.md). Install upstream with npx skills add ColineApp/coline-sdk --skill create-coline-app. Copyright stays with the author.

create-coline-app package agent guide

This package owns the external developer experience: the create-coline-app scaffold and the coline-app push/dev CLI. The template is a tested public contract, not illustrative pseudocode.

Source of truth

• src/scaffold.ts copies templates/backendless and replaces app placeholders.
• src/push.ts bundles app.config.ts, extracts the manifest, and collects main.tsx plus app .ts, .tsx, and .css source for React surfaces.
• templates/backendless/AGENTS.md is the primary guidance delivered to every generated app.
• templates/backendless/.agents/skills/ contains the reusable task skill discovered by OpenCode/Codex-style agents.

Non-negotiable scaffold contract

After a clean npx create-coline-app app && cd app && npm install, the project must have a working backend example, a working React starter, accurate agent guidance, and tests that do not need the Coline product repository or a running Coline server.

Keep these versions aligned in one release:

• @colineapp/sdk — logic, manifest, capabilities, tree UI, test workspace
• @colineapp/ui — React provider, hooks, components, stylesheet
• @colineapp/app-runtime — transitive guest/host bridge dependency
• create-coline-app — scaffold and push/dev CLI

When any public API changes, update the package README, package AGENTS.md, template AGENTS.md, template skill, template dependencies, and the focused smoke test together.

Agent-safety rules

• A generated app must be self-describing. Agents should not need to inspect [private-repository-path], a worktree, or private first-party apps.
• Do not make the template point at local workspace packages or private URLs.
• Do not claim a dependency is “already wired” unless it is in the generated package.json and exercised by the template.
• Do not add a React example without the main.tsx entry, React peer packages, CSS export, and a manifest surface that references it.
• Keep external hosting, network, auth, and database claims explicit. The default app is hosted and backendless.

Verification

• Run pnpm --filter create-coline-app typecheck and pnpm --filter create-coline-app test.
• The CLI tests must assert placeholder replacement, exact package dependency wiring, the React starter's presence, and that the app config bundles against the real SDK source.
• Never use a checked-in private app as the only proof that a public scaffold works. Add the smallest self-contained fixture instead.

Release hygiene

The package publishes bin, src, templates, README.md, AGENTS.md, and LICENSE. Bump the CLI version when the template contract changes. Publish the three runtime libraries first, then publish this CLI with matching ranges.