Alma Cloud App Agent

Agent instructions and skills for developing Ex Libris Alma Cloud Apps.

This package, in the agents/ folder of the Cloud App SDK repository, is intended for Cloud App developers who have access to:

• Their Cloud App project.
• The public Ex Libris Cloud App SDK.
• Official Cloud Apps documentation.
• An Alma environment in which they are authorized to develop and test.

It does not assume access to Alma source code, private Ex Libris repositories, internal databases, or internal services.

Distribution layout

| Path | Purpose | In npm package | |---|---|---| | agents/ | Agent profiles to install at user or target-repository level | Yes | | skills/ | Self-contained skills to install in other repositories | Yes | | templates/ | AGENTS.md and CLAUDE.md templates for Cloud App repositories | Yes | | dist/ | Compiled installer command and library, generated by npm run build | Yes | | INSTALLATION.md | Installation, skill relationships, precedence, and compatibility | Yes | | LICENSE | BSD 3-Clause license, shared with the Cloud App SDK | Yes | | src/ | Strict TypeScript installer command and implementation | No | | test/ | Installer tests using Node.js built-in test support | No | | references/ | Maintainer-facing versioned technical references | No | | tools/ | Maintainer-only public-source inspection and refresh utilities | No | | AGENTS.md | Instructions for maintaining this distribution package | No | | CLAUDE.md | Delegates package maintenance to AGENTS.md | No |

Files not in the npm package are available in the agents folder of the Cloud App SDK repository.

The distributable assets intentionally do not live in auto-discovery directories. Opening this package must not activate the Cloud App developer agent or skills.

Requirements

• Node.js 18 or later.
• An Alma Cloud App project: a package.json that depends on a Cloud App SDK package, a manifest.json, and a cloudapp/ folder.
• For eca agents, a Cloud App CLI release that includes the agent package.

Installation into a Cloud App repository

From a Cloud App project with the Cloud App CLI installed, run:

eca agents install

eca agents also supports update and status, plus the --skills and --dry-run options described in INSTALLATION.md. It uses the agent package bundled with the installed CLI and targets the current directory.

Without the Cloud App CLI, run the published package:

npx @exlibris/exl-cloudapp-agent install /path/to/cloudapp

From a Cloud App SDK checkout, the equivalent is:

cd /path/to/cloudapp-sdk/agents
npm install
npm run cli -- install /path/to/cloudapp

The installer validates the target, preserves conflicts, installs the agent and skills, and writes .exl-cloudapp-agent.json so unchanged distributed files can be updated safely. See INSTALLATION.md for commands and conflict semantics.

Manual installation remains supported. The recommended target layout is:

.github/
  agents/
    alma-cloudapp-developer.agent.md
  skills/
    alma-cloudapp-project/
    alma-cloudapp-code-practices/
    alma-cloudapp-api/
    alma-cloudapp-open-workflows/
    alma-cloudapp-manifest/
    alma-cloudapp-translations/
    alma-cloudapp-styles/
    alma-cloudapp-ui-ux/
    alma-cloudapp-testing/
    alma-cloudapp-sdk-migration/
    alma-cloudapp-release/
    alma-cloudapp-validation/
AGENTS.md
CLAUDE.md

Copy:

• agents/alma-cloudapp-developer.agent.md to .github/agents/.
• Selected directories from skills/ to .github/skills/.
• templates/AGENTS.md and templates/CLAUDE.md to the repository root.

For personal installation, skills may instead be added to ~/.copilot/skills and the agent profile to ~/.copilot/agents.

See INSTALLATION.md for selective installation, compatibility, precedence, and distribution updates.

Initial scope

The first version focuses on the workflows with the highest correctness risk:

1. Orchestrating a task-aware lifecycle with acceptance criteria, proportional review, and an evidence-based definition of done.
2. Understanding or creating a Cloud App project.
3. Applying safe Angular, TypeScript, RxJS, accessibility, and maintainability practices.
4. Selecting current Alma OpenAPI operations and using the public SDK services correctly.
5. Triggering Library Open Workflows (LibOW) through the Alma Run Workflow API or a JWT-verified webhook.
6. Editing the manifest with least privilege.
7. Implementing translation, fallback, extraction, and text direction.
8. Implementing SDK-compatible styles, themes, and responsive layouts.
9. Designing task-focused workflows, navigation, and visual feedback.
10. Testing components, SDK boundaries, API behavior, and reactive workflows.
11. Preparing reproducible, audited builds and publishing releases.
12. Migrating deliberately between SDK, Angular, and Material versions.
13. Validating behavior in the correct Alma environment.

The skills should be reviewed on real Cloud App tasks before the distribution is considered stable.

Knowledge policy

The agent checks the project's installed SDK before relying on examples. Public documentation is treated as supporting material because some examples target older SDK, Angular, or Angular Material versions.

The distribution is designed for phase-specific loading. The agent and target instructions provide orchestration and critical safety boundaries; an owning skill supplies the current workflow, and its detailed references are read only when needed. Installing every skill does not require loading every skill into a single model context.

When behavior belongs to Alma rather than the public SDK, the agent must either validate it in the target Alma environment or describe it as unverified and version-sensitive.

Current baseline

The bundled references were prepared against:

• Cloud App SDK package version 2.1.0.
• Public SDK commit 5c3b11e1fcc6ef305601ecf0775285005168b1bb.
• Angular 18.2.x.
• TypeScript 5.5.x.
• Alma OpenAPI catalog snapshot retrieved 2026-08-31.

The local project always overrides this baseline when it uses another version.

Maintainers should use references/maintenance.md, references/agent-evaluation-scenarios.md, references/agent-evaluation-harness.md, and the utilities under tools/ when refreshing SDK or OpenAPI references or checking agent behavior. These files are in the SDK repository, not the npm package.

Development

From agents/ in a Cloud App SDK checkout:

npm install
npm test
npm run cli -- status /path/to/cloudapp
npm pack --dry-run

npm test rebuilds dist/ and runs the installer tests. Check the npm pack --dry-run file list whenever packaged files or installation paths change. The package is published with the other SDK packages by the repository's publish.sh script.

License

This package is licensed under the terms of the BSD 3-Clause license, the same as the Cloud App SDK.

References

• https://developers.exlibrisgroup.com/cloudapps/
• https://github.com/ExLibrisGroup/cloudapp-sdk
• https://github.com/ExLibrisGroup/cloudapp-sdk/tree/master/agents