CAIRA

Install this skill when a user wants to build or extend an Azure AI solution. This skill is the primary entrypoint for using CAIRA: the agent should inspect the CAIRA repository as reference material and adapt what it finds into a user-specific solution instead of defaulting to editing the CAIRA repository itself.

Entrypoint model

• Default to helping the user build or adapt their own solution, not to changing CAIRA itself.
• Treat the CAIRA repository as live reference material that the agent can inspect at runtime.
• Only treat the CAIRA repository itself as the target workspace when the user explicitly asks to modify CAIRA itself.

Core rules

• Every scenario that requires some kind of OpenAI-compatible endpoints should use them from CAIRA's Foundry reference architecture unless the user explicitly wants to use their own endpoints or another approach. Don't create standalone Azure OpenAI services or resources. The main entrypoint for LLM-based capabilities should be the Foundry architecture in CAIRA, and the agent should adapt that architecture into the user's scenario instead of defaulting to building a new one from scratch.
• Treat the CAIRA repository as the source-of-truth reference library.
• Start with deployment-strategies/ and docs/ as the main reference entry points for end-to-end guidance and runnable patterns.
• Use strategy-builder/ only when the deployment strategies or docs do not answer the question, or when you need the underlying source-of-truth implementation details behind a generated strategy.
• Default to creating or modifying files in the user's target workspace, not inside CAIRA, unless the user explicitly wants to change CAIRA itself.
• Before generating files in the user's repo, ask whether they want to copy the needed CAIRA assets into their repo (copy mode) or keep a dependency on the CAIRA repo (reference mode).
• Use main as the default discovery ref when browsing CAIRA.
• If the user chooses reference mode, ask whether they have a preferred CAIRA release, tag, or commit. If they do not, prefer a concrete pinned ref (release tag first, then commit SHA) instead of leaving generated references on main.
• Discover the current reference architectures, modules, and deployment strategies at runtime instead of hardcoding lists.
• Reason across the whole product surface: layered reference-architecture infra, application components, and generated deployment strategies.
• Map discovered CAIRA assets to the user's scenario before generating code, infrastructure, or recommendations.
• Explain which CAIRA assets influenced the recommendation or generated output.
• Prefer passwordless Azure authentication unless the user explicitly requests another approach.
• Determine what the user already has before proposing or generating a full end-to-end implementation.
• Reuse existing user assets when possible, such as Foundry resources, projects, endpoints, Application Insights instances, API Management instances, and app layers.
• Before proposing or generating app-layer changes, ask which app components are actually needed, such as frontend, API, agent service/container, capability host, or other app-facing services.
• For each needed app component, ask how the user wants to run it right now: local process/container only, existing hosting they already have, or new Azure-hosted deployment.
• For each needed app component, ask whether its supporting dependencies are already provided or need to be created, such as container registry, hosting environment, identities, endpoints, secrets/config, storage, and observability.
• If the user wants a component to run locally for now, do not default to Azure deployment, registry creation, hosted infrastructure, or CI/CD wiring for that component.
• If a component is containerized and the user already has a registry, reuse it; only add registry creation when the user explicitly needs it.
• Treat pirate, captain, specialist, shanty, treasure, and crew content as sample-only. Never copy that sample domain as real business logic unless the user explicitly asks for sample content.
• Exclude CAIRA internal testing and deployed-validation overlay assets from the default reference set unless the user explicitly asks for testing infrastructure.
• Treat deployment strategies as composable slices, not all-or-nothing bundles. Copy or adapt only the slices the user actually needs.
• Do not bring a whole CAIRA strategy into the target solution just to disable most of it later. Prefer omitting unused slices entirely.
• If the user wants APIM / AI gateway behavior, include the whole APIM slice together: Terraform resources, outputs, environment wiring, deploy/test wiring, and any related docs or policies.
• If the user does not want APIM, ignore that slice completely and remove APIM-specific code, variables, outputs, and documentation from the target solution instead of carrying them in a disabled state.
• Apply the same selective-slice rule to every major feature area: observability, private networking, capability hosts, extra projects, testing overlays, frontend, API, and agent containers.

Dynamic discovery workflow

1. Resolve the discovery ref: use main by default when browsing CAIRA. If the user later chooses reference mode for generated dependencies, pin those generated references to a specific release tag or commit instead of leaving them on main.
2. Inspect the user's project and requirements first to determine which architecture slices are missing versus already present.
3. Build a per-component intake matrix for each app component in scope, such as frontend, API, agent service/container, capability host, and other app services. For each component, ask whether it is needed, how it should run, and whether its supporting assets are already provided or need creation.
4. If a component should run locally for now, keep that component local-first and omit Azure deployment wiring, registry creation, hosted infrastructure, and CI/CD wiring unless the user explicitly asks for them.
5. If a component is containerized, ask whether it should stay local, use an existing registry, or require a new registry plus image push flow.
6. Ask whether the user wants copy mode (copy CAIRA assets into their repo) or reference mode (keep a dependency on the CAIRA repo) before generating files.
7. If the user chooses reference mode, ask whether they want a specific CAIRA release, tag, or commit. If they do not care, resolve a concrete pinned ref yourself, preferring a release tag and falling back to a commit SHA.
8. Identify feature slices and their supporting files before copying anything. For example, treat APIM, observability, private networking, capability hosts, app layers, and testing overlays as separate selectable slices.
9. Discover available assets from repository APIs in this order:
   • deployment-strategies/
   • docs/
   • strategy-builder/infra/reference-architectures/
   • strategy-builder/infra/modules/
   • strategy-builder/infra/testing/
   • strategy-builder/
10. Treat the generated deployment strategies and the docs as the default working reference. Only drop into strategy-builder/ when you need deeper implementation details, reference-architecture internals, or source-of-truth files that are not already surfaced by the generated strategies and docs.
11. Inspect the default reference architecture first (strategy-builder/infra/reference-architectures/foundry_agentic_app/), starting with README.md, main.tf, application_platform.tf, agent_service.tf, api_service.tf, frontend_service.tf, dependant_resources.tf, and the referenced modules, unless the user's requirements clearly demand a different discovered option.
12. Treat advanced capability-host, private-networking, and extra-project patterns as opt-in. Do not copy them by default when the basic sample already fits the user's scenario.
13. Treat selective adoption as a first-class path. Decide whether the user needs only infra, only app code, only observability hookup, only endpoint wiring, or a full end-to-end sample.
14. For every selected slice, include the supporting wiring that makes it actually work end-to-end. For every unselected slice, leave it out rather than copying it in a disabled form.
15. Exclude testing_overlay.tf, testing_variables.tf, testing_outputs.tf, and related internal testing assets unless the user explicitly asks for testing or validation resources.
16. Inspect the relevant files for the chosen architecture or strategy.
17. Translate the discovered CAIRA patterns into a user-specific recommendation, design, or implementation plan.
18. Present the recommendation plus trade-offs before generating changes.

Partial adoption checklist

• Check whether the user already has a Foundry account or project.
• Check whether the user already has application hosting and only needs agent/app code.
• Check whether the user already has observability resources and only needs OTEL/App Insights hookup.
• Check whether the user already has API Management and only needs AI gateway exposure or policies.
• Check whether the user only needs resource IDs, endpoints, or environment settings from the architecture.
• For each app component in scope, check whether the user wants or needs it at all:
  • frontend
  • API
  • agent service / container
  • capability host for Foundry Agent Service-specific standard (not basic) deployment
  • other app-facing services
• For each needed app component, check how it should run right now:
  • local process
  • local container
  • existing hosting the user already has
  • new Azure-hosted deployment
• For each needed app component, check whether its required dependencies are provided or should be created:
  • container registry
  • hosting environment
  • identities / auth wiring
  • endpoints / ingress
  • secrets / configuration
  • storage / data dependencies
  • observability wiring
• If a component is containerized, check whether the user already has a Docker/container registry and whether images should stay local or be pushed there.
• If the user wants a component to stay local for now, avoid adding Azure deployment artifacts or registry wiring for that component.
• Check whether the user prefers copy mode or reference mode for CAIRA assets in their repo.
• If they prefer reference mode, check whether they already require a specific CAIRA release, tag, or commit; otherwise propose the concrete pinned ref you will use.
• Check whether each optional slice is explicitly in scope or out of scope:
  • APIM / AI gateway
  • observability
  • private networking
  • capability hosts
  • frontend
  • API
  • agent container
• For each out-of-scope slice, avoid copying its related files, variables, outputs, and docs into the target solution.

Source-of-truth URLs

• Repository root: https://github.com/pablozaiden/CAIRA
• Default discovery ref: main unless the user explicitly asks to browse another ref.
• Reference-mode generated module or file URLs should use a concrete pinned ref, not main, unless the user explicitly asks for a floating dependency.
• Latest release tag API (for pinned reference mode dependencies): https://api.github.com/repos/pablozaiden/CAIRA/releases/latest
• Deployment strategies listing API: GET /repos/pablozaiden/CAIRA/contents/deployment-strategies?ref=main
• Docs listing API: GET /repos/pablozaiden/CAIRA/contents/docs?ref=main
• Reference architectures listing API: GET /repos/pablozaiden/CAIRA/contents/strategy-builder/infra/reference-architectures?ref=main
• Modules listing API: GET /repos/pablozaiden/CAIRA/contents/strategy-builder/infra/modules?ref=main
• Infra testing listing API: GET /repos/pablozaiden/CAIRA/contents/strategy-builder/infra/testing?ref=main
• Strategy builder listing API: GET /repos/pablozaiden/CAIRA/contents/strategy-builder?ref=main