feat(agentic-shared-framework): resolve consumer apm.yml per gh-aw invocation via aw-resolve-apm-assets

[fr4nc1sc0-r4m0n]

Overview

This PR introduces a shared agentic assets framework for consumer repositories. Repositories opt in by adding an apm.yml manifest (standard APM dependencies plus an x-oblt-aw extension). The control plane resolves those assets in aw-resolve-apm-assets.yml immediately before each gh-aw-* job (not in aw-prelude), so teams can define repository-wide and per-workflow AI configuration without forking elastic/oblt-aw workflow YAML.

The design separates four concerns:

Layer	Owner	Purpose
Dashboard gate	aw-prelude.yml	Once per wrapper run: enabled-workflows gate and optional allow lists.
APM resolution	aw-resolve-apm-assets.yml	Per agent invocation: apm install, merge x-oblt-aw assets with platform baselines.
Platform	elastic/oblt-aw	Non-negotiable rules via platform-additional-instructions / platform-inputs-json on each resolve job.
APM dependencies	Consumer apm.yml	Skills, plugins, MCP servers, and other agent primitives via apm install.

Workflow ids under x-oblt-aw.workflows match id in config/<org-key>/workflow-registry.json (for example agent-suggestions, autodoc). Dashboard gating continues to use compound ids (obs:agent-suggestions).

---

Architecture diagram

flowchart TB
  subgraph consumer["Consumer repository"]
    TRG["trigger-oblt-aw-*.yml"]
    APM["apm.yml"]
    X_OBLT["x-oblt-aw: common | workflows.<id>"]
    APM --> X_OBLT
  end

  subgraph control_plane["elastic/oblt-aw"]
    OBLT["oblt-aw-*.yml / docs-aw-*.yml"]
    PRELUDE["aw-prelude.yml"]
    RESOLVE_WF["aw-resolve-apm-assets.yml"]
    DASH["get-enabled-workflows"]
  end

  subgraph upstream["Upstream agentic engine"]
    GHAW["gh-aw-*.lock.yml"]
  end

  TRG --> OBLT
  OBLT --> PRELUDE
  PRELUDE -->|proceed| RESOLVE_WF
  X_OBLT -.->|read at runtime| RESOLVE_WF
  RESOLVE_WF -->|resolved-additional-instructions| OBLT
  OBLT --> GHAW
  PRELUDE --> DASH

Loading

---

Per-invocation resolve flow

flowchart TD
  START([Wrapper triggered]) --> PRELUDE[aw-prelude: dashboard gate]
  PRELUDE -->|proceed false| SKIP([Agent jobs skipped])
  PRELUDE -->|proceed true| GATES[Optional upstream gates e.g. verify, discover, evaluate-trigger]
  GATES --> RESOLVE[aw-resolve-apm-assets for this gh-aw job]
  RESOLVE --> MANIFEST{apm.yml present?}
  MANIFEST -->|yes| INSTALL[apm install + resolve x-oblt-aw]
  MANIFEST -->|no| PLATFORM[Platform baseline only]
  INSTALL --> MERGE[Merge platform + APM outputs]
  PLATFORM --> MERGE
  MERGE --> GHAW([gh-aw-* workflow_call])

Loading

Each resolve-apm-assets job uses the same if expression as the gh-aw-* job it feeds, and runs immediately before that agent job (after any prerequisite gates such as automerge verify or resource detector discover).

Multi-agent wrappers call resolve once per agent step (for example oblt-aw-autodoc: audit vs fix with different platform-additional-instructions).

---

Precedence rules

Platform vs repository (x-oblt-aw)

• Additional instructions: Platform text (platform-additional-instructions on the resolve job) is prepended; repository text from the selected asset block is appended.
• Other inputs: platform-inputs-json defaults; APM inputs override per key.

Common vs workflow-specific

• If workflows.<registry-id> exists, that block is used and common is ignored entirely (override, not merge).
• If only common exists, it applies to all workflows without a workflow block.
• Neither → platform baseline only.

---

Control-plane changes

Area	Change
aw-prelude.yml	Dashboard gating and allow lists only (APM removed).
aw-resolve-apm-assets.yml	New reusable: registry id lookup, requirements-runtime.txt + pip cache, optional apm install, asset resolution.
scripts/apm_agentic_assets.py	Resolution library.
scripts/resolve_apm_agentic_assets.py	Actions CLI entrypoint.
oblt-aw-* / docs-aw-*	Prelude for gate; one resolve job per gh-aw-* call with matching if / needs.
scripts/validate_aw_workflow_resolve_apm_assets.py	CI: every gh-aw-* wrapper must call aw-resolve-apm-assets.yml.
Docs	docs/architecture/apm-agentic-assets.md, docs/workflows/aw-resolve-apm-assets.md, docs/examples/consumer-apm.yml.example.

Wrappers without agents (for example oblt-aw-security-detector) call prelude only.

---

Test plan

• pytest tests/test_apm_agentic_assets.py
• python scripts/validate_aw_workflow_prelude.py
• python scripts/validate_aw_workflow_resolve_apm_assets.py
• CI on this PR
• Pilot: add apm.yml with x-oblt-aw to a consumer repo; confirm resolve job logs asset-source and agent receives expected resolved-additional-instructions

---

Related issue: https://github.com/elastic/observability-robots/issues/3674

[Copilot]

Pull request overview

Adds support for resolving consumer-provided “agentic assets” from apm.yml (via x-oblt-aw) inside aw-prelude, then propagates the resolved instructions into downstream gh-aw-* workflow calls. This lets the control plane apply a platform baseline plus repo/workflow-specific overrides consistently across wrapper workflows.

Changes:

• Introduces scripts/apm_agentic_assets.py + scripts/resolve_apm_agentic_assets.py and unit tests to resolve x-oblt-aw blocks (common vs per-workflow override) and merge platform inputs/instructions.
• Extends aw-prelude.yml with an apm-assets job to optionally run apm install and emit resolved-* outputs used by downstream jobs.
• Updates multiple oblt-aw-* and docs-aw-* workflows to pass platform baselines through the prelude and consume needs.prelude.outputs.resolved-additional-instructions.

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tests/test_apm_agentic_assets.py	Adds unit tests covering asset-block selection, file inputs, and platform/APM merge behavior.
scripts/apm_agentic_assets.py	Core resolver: parses apm.yml, selects common vs workflow blocks, loads file-backed inputs, merges inputs, composes instructions.
scripts/resolve_apm_agentic_assets.py	CLI entrypoint for GitHub Actions to output resolved instructions/inputs/setup commands.
scripts/validate_aw_workflow_prelude.py	Excludes trg-* client templates from prelude enforcement.
requirements-ci.txt	Adds PyYAML for CI test execution.
config/schema/apm-agentic-workflows.schema.json	Defines JSON Schema for x-oblt-aw extension in apm.yml.
docs/architecture/apm-agentic-assets.md	Documents precedence/behavior and runtime flow through aw-prelude.
docs/examples/consumer-apm.yml.example	Provides a consumer-facing apm.yml example using x-oblt-aw.
docs/architecture/overview.md	Mentions APM asset resolution as part of the prelude.
.github/workflows/aw-prelude.yml	Adds platform-* inputs, apm-assets job, and new outputs (resolved-*, manifest/extension presence, asset source).
.github/workflows/oblt-aw-security-triage.yml	Moves baseline instructions into platform-additional-instructions; uses resolved-additional-instructions downstream.
.github/workflows/oblt-aw-security-fixer.yml	Same: baseline into prelude; downstream uses resolved instructions.
.github/workflows/oblt-aw-resource-not-accessible-by-integration-triage.yml	Same: baseline into prelude; downstream uses resolved instructions.
.github/workflows/oblt-aw-resource-not-accessible-by-integration-fixer.yml	Same: baseline into prelude; downstream uses resolved instructions.
.github/workflows/oblt-aw-resource-not-accessible-by-integration-detector.yml	Same: baseline into prelude; downstream uses resolved instructions; adjusts needs.
.github/workflows/oblt-aw-mention-in-issue.yml	Passes resolved instructions to upstream gh-aw-mention-in-issue.
.github/workflows/oblt-aw-issue-triage.yml	Passes resolved instructions to upstream gh-aw-issue-triage.
.github/workflows/oblt-aw-issue-fixer.yml	Moves baseline into prelude; downstream uses resolved instructions.
.github/workflows/oblt-aw-estc-pr-buildkite-detective.yml	Moves baseline into prelude; downstream uses resolved instructions.
.github/workflows/oblt-aw-duplicate-issue-detector.yml	Passes resolved instructions to upstream detector workflow.
.github/workflows/oblt-aw-dependency-review.yml	Moves baseline into prelude; downstream uses resolved instructions.
.github/workflows/oblt-aw-automerge.yml	Moves baseline into prelude; downstream uses resolved instructions.
.github/workflows/oblt-aw-autodoc.yml	Moves baseline into prelude; downstream uses resolved instructions.
.github/workflows/oblt-aw-agent-suggestions.yml	Moves baseline into prelude; downstream uses resolved instructions.
.github/workflows/docs-aw-pr-ai-menu.yml	Moves baseline into prelude; ensures run-docs-review is gated by prelude proceed + uses resolved instructions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[fr4nc1sc0-r4m0n]

@copilot resolve the merge conflicts in this pull request

[Copilot]

@copilot resolve the merge conflicts in this pull request

Resolved all merge conflicts in commit 7059399. The key resolutions were:

• All oblt-aw-* and docs-aw-* workflows: replaced enabled-workflow-id with control-plane-workflow (adopting main's registry-based id lookup) while keeping platform-additional-instructions
• aw-prelude.yml: added compound-workflow-id as an output of the evaluate job and used it as ENABLED_WORKFLOW_ID in the apm-assets resolver step (replacing the removed inputs.enabled-workflow-id reference)
• scripts/validate_aw_workflow_prelude.py: adopted main's ("trg-", "trigger-") tuple exclusion
• docs/architecture/overview.md: combined both descriptions (APM assets mention + updated trigger-oblt-aw-* naming)