feat: add Archipelago agent skills and app starter

2026-10-09 07:31:06 -04:00
parent 940b28dd9b
commit 820df9a196
21 changed files with 484 additions and 0 deletions
@@ -0,0 +1,49 @@
+---
+name: archipelago-app
+description: Build, package, test, and update a manifest-driven Archipelago app using the real app developer contract, rootless runtime, and lifecycle acceptance flow.
+metadata:
+  short-description: Build a real Archipelago app
+---
+
+# Archipelago app development
+
+Use this skill when creating or changing an Archipelago app, manifest, container
+build, app integration, credentials, signer flow, or app preview. Always load
+`archipelago-design` for newly authored UI.
+
+Read [app-contract.md](references/app-contract.md),
+`docs/app-developer-guide.md`, and `docs/app-manifest-spec.md` before coding.
+
+## Required loop
+
+1. Create a dedicated worktree or project directory and choose the smallest
+   useful app scope. Prefer the maintained starter and its pinned dependencies.
+2. Implement the app as a manifest, rootless container, persistent data path,
+   truthful health/readiness check, declared interface, and tests. Never add a
+   per-app Rust installer or rootful/Docker-socket shortcut.
+3. Use generated secrets or declared secret files; never put credentials in a
+   manifest, image, logs, URL, or frontend bundle. Keep production wallets and
+   app databases outside development fixtures.
+4. Validate the manifest and build context, then run the app through install,
+   start, stop, restart, manager restart, uninstall with data preservation, and
+   reinstall. Verify the real My Apps/Services launch path, not only a direct
+   port.
+5. For UI, exercise standalone and embedded modes at 320, 390, 768, and 1440px
+   plus phone landscape, keyboard navigation, loading/empty/error/retry/success,
+   safe areas, and reduced motion.
+6. Report source, disposable-node, actual-node, and release-artifact evidence
+   separately. Catalog publication is a separate request.
+
+Important runtime facts:
+
+- `/opt/archipelago/apps` is rebuilt from the runtime payload at backend start;
+  staging only there will be lost. Follow the developer guide's payload path.
+- Signed catalog entries take precedence over disk manifests for catalog apps.
+- Installed does not mean ready or launchable; use health and readiness evidence.
+- App interfaces describe the service behind the gate. Do not hard-code a node
+  IP, scheme, app path, or host frame URL into app code.
+
+## References
+
+- [app contract and acceptance](references/app-contract.md)
+- [design routing](../archipelago-design/SKILL.md)
@@ -0,0 +1,7 @@
+interface:
+  display_name: "Archipelago app"
+  short_description: "Build a real Archipelago app"
+  brand_color: "#F7931A"
+  default_prompt: "Use $archipelago-app to build and validate this Archipelago app."
+policy:
+  allow_implicit_invocation: true
@@ -0,0 +1,17 @@
+# App contract
+
+Start with `docs/app-developer-guide.md` and `docs/app-manifest-spec.md`; those
+files are authoritative for fields and launch behavior. Validate with:
+
+```bash
+./scripts/validate-app-manifest.sh apps/<id>/manifest.yml
+python3 scripts/generate-app-catalog.py
+python3 scripts/check-app-catalog-drift.py --release --strict
+```
+
+Use pinned image versions, read-only root, no-new-privileges, minimal
+capabilities, rootless Podman, declared persistent data under
+`/var/lib/archipelago/<id>`, health checks, generated/declared secrets, and
+truthful interfaces. Test install/start/stop/restart/manager-restart/uninstall
+with data preservation/reinstall on a disposable node. Do not replace the
+signed catalog to make a local test app appear.