new-app

# New App Create one new repository app package from official upstream deployment references. This skill follows `docs/ai-sdlc/04-new-app-pipeline.md`, `docs/ai-sdlc/05-quality-gates.md`, and `docs/ai-sdlc/06-test-report-format.md`. Supporting files in this skill: - `checklist.md` - `prompt-fragments.md` - `report-template.md` ## Inputs - app name (required) - trademark (required) - official references (required): at least one URL for the project repository, image registry, or install docs If any required input is missing, stop and ask the user for it before researching or scaffolding. Never guess the trademark and never research without at least one official reference URL. ## Steps 1. Load the libs CLI venv first: run `make install` if `.venv/` does not exist, then run `.venv/bin/libs list --include-archived --json`. Get the most complete app list (active + archived + internal). If `<app>` is in the list, stop immediately and report its key attributes (status, scope, cadence, update_policy). Then route: active/frozen → `app-update` skill; archived → `restore-app` skill (`.venv/bin/libs app-restore`); or ask the user to provide a different app name / terminate. Do not create, modify, or overwrite anything. 2. Read the issue requirements and official upstream docs. 3. Read repository rules from `docs/code_owner.md`, `docs/w9-env-spec.md`, and the machine template under `metadata/templates/new-app/`. 4. Research the real image and version from upstream sources. 5. Scaffold the package skeleton with `.venv/bin/libs app-new --name <app> --trademark <brand> --json` plus `--version <x.x>` and `--repo <image>` when the research has already resolved them (otherwise the CLI writes explicit TODO placeholders). When upstream sources are known, also pass `--upstream-releases <url>`, `--upstream-compose <url>`, and `--upstream-env <url>` as applicable so `variables.json` starts with the current repository shape. The command refuses duplicates and runs the quality gates automatically. 6. Fill `.env`, `docker-compose.yml`, `variables.json`, `README.md`, `CHANGELOG.md`, and `src/` beyond the skeleton, following the todo list returned by the scaffold command. Use `docs/w9-env-spec.md` as the canonical decision source for `W9_*` variables and use existing apps only as secondary examples when the spec leaves a genuine gap. Decide the env groups from research: enable the password group (uncomment and fill) when the app has a DB or login; enable the web group when it exposes a web page; delete groups the app does not need. If the app has an install-time or first-startup external URL setting such as `root_url`, `base_url`, `public_url`, `site_url`, `app_url`, `host`, or `domain`, declare `W9_URL` and set `W9_URL_REPLACE=true` in `.env`; use a domain-style placeholder (for example `appname.example.com` or `example.youdomain.com`) and do not use `internet_ip:${W9_HTTP_PORT_SET}`. In `variables.json`, set `access.defaultScheme` to `https` when the package defaults to HTTPS; otherwise use `http`, and only add a per-surface `scheme` for exceptions such as `wss` or `ssh`. In the `.env` "image environment variables" section, keep only the variables required by the current package shape plus any user-facing essentials, set the single Docs URL, list the vars actually used by `docker-compose.yml`, and add up to 5 unused vars commented out. Mirror the template layout in `metadata/templates/new-app/.env.tmpl`: keep the section banner, the Docs URL, the "Used by docker-compose.yml" group, and the commented "Not used by default" group; do not restructure the application-env section freely. Reference environment variables in the braced form `${VAR}` (for example `${W9_POWER_PASSWORD}`, `${W9_URL}`); do not use bare `$VAR`. 7. When the app needs a custom image, start from `metadata/templates/new-app/Dockerfile.tmpl` and keep the standard OCI labels (`org.opencontainers.image.*`) unless there is a documented exception. 8. Author `docker-compose.yml` so every published port line carries an inline `# purpose` comment, and never add `# image:` / `# docs:` source comments — the image and documentation sources live only in `variables.json` `upstream`. Update `variables.json` `upstream.image` as the single version source. Reference environment variables in the braced form `${VAR}` (for example `${W9_REPO}`, `${W9_HTTP_PORT_SET}`); do not use bare `$VAR` in new files. 9. Register any new translatable env key in `i18n/translation.json`. 10. Healthchecks should default to the main app container only. Add healthchecks to sidecar or dependency containers only when the official upstream compose explicitly defines them or the task explicitly requires them. 11. If a credential or config env var only takes effect on first container startup (the image entrypoint uses a marker file, e.g. `webconsole.security.enabled`), record it in `variables.json` as `env.first_startup_only` (list of env names) so the README auto-renders the warning. 12. If the app creates its initial username, password, or token interactively and the consumer can resolve it after deployment, declare `variables.json.credentials.<slot>` metadata where `<slot>` is `username`, `password`, or `token`. Supported sources are `inline`, `container-env`, `container-file`, `container-log`, and `container-cli`. Prefer this declarative metadata over legacy `W9_LOGIN_GET_PASSWORD` / `W9_LOGIN_GET_TOKEN` command strings. 13. Keep `apps/<app>/CHANGELOG.md` as the single source of app change history. Use a pure-date heading `## YYYY-MM-DD` as the first-level heading for the initial change batch (the template already injects today's date); list the initial package changes below it. Do not duplicate changelog content into `README.md`. 14. Run `.venv/bin/libs app-gen-readme --app <app> --json` after metadata or README marker content changes so generated sections stay current. 15. For dependency images such as PostgreSQL, MySQL, MariaDB, Redis, or pgvector, prefer `x.x` tags even when upstream examples show `x.x.x`, unless exact patch pinning is demonstrably required. Hard-coded dependency `x.x.x` tags in `docker-compose.yml` are policy drift and should be normalized before handoff. 16. Author `apps/<app>/tests/cases.yml` per `docs/app-tests.md`: keep the built-in adaptive checks and add the minimum app-specific cases the defaults cannot cover, such as `http-basic` for an authenticated console or API, `web-access` for a dedicated health endpoint, or `script` only when built-ins are insufficient. Do not add a case that duplicates a default check. 17. Run the `deploy-validation` skill to prove the app deploys. 18. Produce a short test report. 19. Assign a maintenance cadence and update policy: write the app into the matching buckets of `metadata/maintenance.yaml` (apps not listed inherit the monthly/patch-minor defaults), and state the assignment in the report. The owner reviews it at merge. 20. Write the repo catalog fields from the upstream research: copy `metadata/templates/catalog.json` to `metadata/catalog/<app>.json` and fill trademark, summary, overview, description, websiteurl, screenshots, and `catalogBindings`. Choose `catalogBindings` from `metadata/catalog-taxonomy.json` when it exists; parent/child keys must be valid. Keep `summary` to at most 8 words (prefer 5 or fewer) and `overview` to at most 30 words (prefer 20 or fewer); the `catalog-seed` skill is the canonical reference for these limits. This repo catalog file is the fallback editorial source and the input to `.venv/bin/libs catalog-push`. The owner reviews the catalog data before the first Contentful write; AI never writes Contentful directly. The owner applies with `.venv/bin/libs catalog-push --app <app> --apply` after review. If the task is only catalog-file authoring for an existing app, use the `catalog-seed` skill instead of `new-app`. ## Output - created files - upstream references - automated validation result - risks - assigned cadence and update policy - owner E2E focus ## Rules - Existence is decided by `.venv/bin/libs list --include-archived`, never by checking `apps/<app>/` alone; an archived or internal app also counts as existing. - If `<app>` exists, stop at step 1, report its status/scope, and ask the user; never fall through to creation. - The CLI input contract is `metadata/new-app.schema.json`; the issue itself is prose, AI converts it to flags. - The CLI scaffold reads `metadata/templates/new-app/`; `template/` stays as a human reference and must not be treated as the machine template source. - Prefer official images or trusted upstream images. - Keep the app aligned to repository conventions. - `variables.json` should declare the `upstream` structure explicitly when sources are known. `releases`, `compose.compose`, and `compose.env` should be considered during research and scaffold completion, but should be omitted when they are not applicable or not yet verified. - Keep `upstream.image` as the single version source. Never write `version_from`, `fork_url`, or `requirements.url`. - Do not change unrelated apps. - Produce the report in the same language the user used unless the user asks otherwise.