---
name: cicadel-installables
description: Build, integrate, test, and evolve independently installable Cicadel applications and batteries using Go modules, app manifests, explicit registration, and lifecycle contracts. Use for third-party Cicadel apps or first-party contrib packages, not generic Go packages or unrelated frameworks.
---

# Cicadel installable applications

Develop the requested battery through Cicadel's public installable-app boundary. First-party capabilities are core defaults composed through that boundary; module packaging does not make them opt-in alternatives. Preserve the user's requested feature scope; this skill does not authorize publishing modules, sending messages, changing repository visibility, or deploying an application.

## Establish the actual contract

Locate the host/project and framework revision. In a framework checkout, read `docs/installable-apps.md`, `apps.go`, `application.go`, `lifecycle.go` and the relevant part of `management/management.go`. In an external app, inspect `go.mod`, `go list -m` and the APIs of the selected Cicadel version. Do not assume an API from this skill is present in an older module pin.

Read `batteries.md` and the relevant design if available. Current boundaries:

- Cicadel has no releases. Document the current implementation; do not preserve unreleased approaches through compatibility shims or upgrade guides. The app API is experimental. Go modules select code; the manifest declares the app contract and compatibility. Neither is a replacement for the other.
- Core has no native localization/internationalization or GIS. External apps may provide them without making them mandatory dependencies.
- UI uses compiled `.templ` bodies and typed `ui.Definition` props/slots, exported through `App.Components`. For component authoring use `skills/cicadel-components/SKILL.md` and read `docs/component-ui.md` for explicit overrides and required assets. Tailwind is the default; installed library class sources must be explicitly listed in the host CSS configuration. Use this component contract for application UI.
- GORM model/query integration is available. The standard migration and typed query commands use registered model metadata; inspect the documented PostgreSQL operation subset before relying on it. Do not equate `AutoMigrate` with recorded, reviewable migrations.

For a new package or host integration, read [package-authoring.md](https://cicadel.fauzaanu.com/en/dev/sources/skills/cicadel-installables/references/package-authoring.md). For startup, commands, settings or lifecycle changes, read [runtime-contracts.md](https://cicadel.fauzaanu.com/en/dev/sources/skills/cicadel-installables/references/runtime-contracts.md). For persistence, upgrades, verification or first-party promotion, read [data-and-verification.md](https://cicadel.fauzaanu.com/en/dev/sources/skills/cicadel-installables/references/data-and-verification.md). Load only the references relevant to the task.

## Choose the smallest real implementation

Use `cicadel startpackage DIRECTORY MODULE NAME` for an independent module, or inspect an existing package rather than regenerating it. Keep app-owned models, views, routes, assets and migrations with the app. A nested module inside a larger repository still needs its own test/build workflow; `go test ./...` in the parent skips it.

Use `go get MODULE@VERSION` in a consumer and an explicit factory in `project/apps.go`. No import side effects, automatic downloads at startup, global registration registry or custom dependency resolver. Use local `replace` directives for development only when appropriate; distinguish them from verified remote/versioned installation.

Expose typed options and explicit dependencies in the factory. Reserve core changes for a missing general-purpose integration contract that the requested battery actually needs. Implement that seam with tests and document its scope; do not put the whole battery in core for convenience.

Register routes, namespaced commands/checks, resource filesystems, migrations and lifecycle through the actual exported `App` fields. Preserve ownership boundaries. Do not claim model/component contributions are registered merely because their files are in `Resources`.

## Completion and handoff

Verify behavior in a separate host, not just package-unit tests. Choose the appropriate checks in the verification reference; do not introduce database or browser requirements for a package that does not need them. Use HTTP tests and terminal/API tools; do not use desktop/browser automation.

Report what can be installed and invoked, the selected module/app API versions, tests actually run, provider coverage and remaining limitations. Update the applicable battery/plan only for implemented, verified work. A scaffold, callback wrapper or passing smoke test does not complete a larger battery. Keep skill guidance aligned with changes to the public contracts when the task changes those contracts.