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

.github/workflows/aw-prelude.yml

@@ -1,6 +1,6 @@
 name: Agentic Workflow Prelude
 
-# Shared dashboard gating and optional allow-list loading for *-aw-* workflows.
+# Shared dashboard gating, optional allow-list loading, and APM asset resolution for *-aw-* workflows.
 # Call this reusable workflow before agent-specific jobs in oblt-aw-* and docs-aw-* wrappers.
 on:
   workflow_call:
@@ -14,6 +14,25 @@ on:
         required: false
         type: boolean
         default: false
+      platform-additional-instructions:
+        description: >-
+          Control-plane baseline additional-instructions for the agentic workflow.
+          Merged with consumer apm.yml assets (platform first, then repo assets).
+        required: false
+        type: string
+        default: ""
+      platform-inputs-json:
+        description: >-
+          JSON object of platform workflow_call inputs to merge; repo apm.yml inputs
+          override per key when an asset block is selected.
+        required: false
+        type: string
+        default: "{}"
+      install-apm-packages:
+        description: Run `apm install` when apm.yml is present in the consumer repository
+        required: false
+        type: boolean
+        default: true
     outputs:
       proceed:
         description: >-
@@ -38,6 +57,24 @@ on:
       allowed-issue-authors-csv:
         description: Comma-separated allowed issue bot logins (empty when not loaded)
         value: ${{ jobs.evaluate.outputs.allowed-issue-authors-csv }}
+      apm-manifest-present:
+        description: True when the consumer repository contains apm.yml or apm.yaml
+        value: ${{ jobs.apm-assets.outputs.apm-manifest-present }}
+      apm-extension-present:
+        description: True when apm.yml contains an x-oblt-aw extension block
+        value: ${{ jobs.apm-assets.outputs.apm-extension-present }}
+      asset-source:
+        description: none, common, or workflow (APM asset block used for resolution)
+        value: ${{ jobs.apm-assets.outputs.asset-source }}
+      resolved-additional-instructions:
+        description: Platform baseline plus resolved repo additional-instructions
+        value: ${{ jobs.apm-assets.outputs.resolved-additional-instructions }}
+      resolved-inputs-json:
+        description: JSON object of merged platform and APM workflow inputs
+        value: ${{ jobs.apm-assets.outputs.resolved-inputs-json }}
+      resolved-setup-commands-json:
+        description: JSON array of setup shell commands from APM assets
+        value: ${{ jobs.apm-assets.outputs.resolved-setup-commands-json }}
 
 permissions:
   contents: read
@@ -105,3 +142,100 @@ jobs:
             echo "allowed-issue-authors-json=${ISSUE_JSON:-[]}"
             echo "allowed-issue-authors-csv=${ISSUE_CSV:-}"
           } >> "${GITHUB_OUTPUT}"
+
+  apm-assets:
+    needs: [dashboard, allowed-authors, evaluate]
+    permissions:
+      contents: read
+    if: >-
+      always() &&
+      needs.dashboard.result == 'success' &&
+      (needs.allowed-authors.result == 'success' || needs.allowed-authors.result == 'skipped') &&
+      needs.evaluate.result == 'success' &&
+      needs.evaluate.outputs.proceed == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    outputs:
+      apm-manifest-present: ${{ steps.resolve.outputs.apm-manifest-present }}
+      apm-extension-present: ${{ steps.resolve.outputs.apm-extension-present }}
+      asset-source: ${{ steps.resolve.outputs.asset-source }}
+      resolved-additional-instructions: ${{ steps.resolve.outputs.resolved-additional-instructions }}
+      resolved-inputs-json: ${{ steps.resolve.outputs.resolved-inputs-json }}
+      resolved-setup-commands-json: ${{ steps.resolve.outputs.resolved-setup-commands-json }}
+    steps:
+      - name: Checkout consumer repository
+        uses: actions/checkout@v6
+
+      - name: Checkout oblt-aw resolver scripts
+        uses: actions/checkout@v6
+        with:
+          repository: elastic/oblt-aw
+          ref: main
+          path: _oblt-aw
+          fetch-depth: 1
+          sparse-checkout: |
+            scripts/apm_agentic_assets.py
+            scripts/resolve_apm_agentic_assets.py
+            scripts/common.py
+          sparse-checkout-cone-mode: false
+
+      - name: Detect apm manifest
+        id: detect
+        run: |
+          set -euo pipefail
+          if [ -f apm.yml ] || [ -f apm.yaml ]; then
+            echo "present=true" >> "${GITHUB_OUTPUT}"
+          else
+            echo "present=false" >> "${GITHUB_OUTPUT}"
+          fi
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
+      - name: Install Python dependencies for resolver
+        run: pip install PyYAML==6.0.2
+
+      - name: Install APM CLI
+        if: >-
+          inputs.install-apm-packages &&
+          steps.detect.outputs.present == 'true'
+        env:
+          APM_VERSION: "v0.16.0"
+        run: |
+          set -euo pipefail
+          OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
+          ARCH="$(uname -m)"
+          case "${ARCH}" in
+            x86_64) ARCH="x86_64" ;;
+            arm64|aarch64) ARCH="arm64" ;;
+            *) echo "Unsupported architecture: ${ARCH}"; exit 1 ;;
+          esac
+          TARBALL="apm-${OS}-${ARCH}.tar.gz"
+          BASE_URL="https://github.com/microsoft/apm/releases/download/${APM_VERSION}"
+          curl -fsSL "${BASE_URL}/${TARBALL}" -o "/tmp/${TARBALL}"
+          curl -fsSL "${BASE_URL}/${TARBALL}.sha256" -o "/tmp/${TARBALL}.sha256"
+          EXPECTED="$(awk '{print $1}' "/tmp/${TARBALL}.sha256")"
+          echo "${EXPECTED}  /tmp/${TARBALL}" | sha256sum -c
+          mkdir -p "${HOME}/.local/bin"
+          tar -xzf "/tmp/${TARBALL}" -C /tmp "apm-${OS}-${ARCH}/apm"
+          install -m 0755 "/tmp/apm-${OS}-${ARCH}/apm" "${HOME}/.local/bin/apm"
+          echo "${HOME}/.local/bin" >> "${GITHUB_PATH}"
+
+      - name: Install agent packages from apm.yml
+        if: >-
+          inputs.install-apm-packages &&
+          steps.detect.outputs.present == 'true'
+        run: |
+          set -euo pipefail
+          apm install
+
+      - name: Resolve agentic assets from apm.yml
+        id: resolve
+        env:
+          ENABLED_WORKFLOW_ID: ${{ inputs.enabled-workflow-id }}
+          REPO_ROOT: ${{ github.workspace }}
+          PLATFORM_ADDITIONAL_INSTRUCTIONS: ${{ inputs.platform-additional-instructions }}
+          PLATFORM_INPUTS_JSON: ${{ inputs.platform-inputs-json }}
+        run: python _oblt-aw/scripts/resolve_apm_agentic_assets.py

.github/workflows/docs-aw-pr-ai-menu.yml

@@ -21,6 +21,9 @@ jobs:
     uses: ./.github/workflows/aw-prelude.yml
     with:
       enabled-workflow-id: docs:example-workflow
+      platform-additional-instructions: |
+        This repository stores documentation as markdown across the repository.
+        Prefer concise, high-signal review comments with exact replacement text when possible.
 
   post-menu:
     name: Post or refresh AI PR menu
@@ -126,8 +129,10 @@ jobs:
 
   run-docs-review:
     name: Docs AI / docs review
-    needs: [evaluate-trigger]
-    if: needs.evaluate-trigger.outputs.docs_review_triggered == 'true'
+    needs: [prelude, evaluate-trigger]
+    if: >-
+      needs.prelude.outputs.proceed == 'true' &&
+      needs.evaluate-trigger.outputs.docs_review_triggered == 'true'
     permissions:
       actions: read
       contents: read
@@ -136,9 +141,7 @@ jobs:
     uses: elastic/docs-actions/.github/workflows/gh-aw-docs-review.lock.yml@v1
     with:
       review-scope: repo-wide-markdown
-      additional-instructions: |
-        This repository stores documentation as markdown across the repository.
-        Prefer concise, high-signal review comments with exact replacement text when possible.
+      additional-instructions: ${{ needs.prelude.outputs.resolved-additional-instructions }}
     secrets:
       COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
 

.github/workflows/oblt-aw-agent-suggestions.yml

@@ -16,18 +16,7 @@ jobs:
     uses: ./.github/workflows/aw-prelude.yml
     with:
       enabled-workflow-id: obs:agent-suggestions
-
-  agent-suggestions:
-    needs: prelude
-    permissions:
-      contents: read
-      issues: write
-      pull-requests: read
-    if: needs.prelude.outputs.proceed == 'true'
-    uses: elastic/ai-github-actions/.github/workflows/gh-aw-agent-suggestions.lock.yml@main
-    with:
-      title-prefix: "[oblt-aw][agent-suggestions]"
-      additional-instructions: |
+      platform-additional-instructions: |
         Additional requirements for this repository:
 
         - If there are no net-new recommendations, or if recommendations only suggest workflows/features already in use in this repository, call `noop` and do not create any issue.
@@ -42,4 +31,16 @@ jobs:
         When calling `create_issue`, ensure the output includes:
         - `labels`: contains `agentic-workflow`
         - `expires`: `24h`
+
+  agent-suggestions:
+    needs: prelude
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: read
+    if: needs.prelude.outputs.proceed == 'true'
+    uses: elastic/ai-github-actions/.github/workflows/gh-aw-agent-suggestions.lock.yml@main
+    with:
+      title-prefix: "[oblt-aw][agent-suggestions]"
+      additional-instructions: ${{ needs.prelude.outputs.resolved-additional-instructions }}
     secrets: inherit

.github/workflows/oblt-aw-autodoc.yml

@@ -16,20 +16,7 @@ jobs:
     uses: ./.github/workflows/aw-prelude.yml
     with:
       enabled-workflow-id: obs:autodoc
-
-  # Step 1: Detect docs drift from recent code changes and create an issue with findings
-  audit:
-    needs: prelude
-    permissions:
-      contents: read
-      issues: write
-      pull-requests: read
-    if: needs.prelude.outputs.proceed == 'true'
-    uses: elastic/ai-github-actions/.github/workflows/gh-aw-docs-patrol.lock.yml@main
-    with:
-      lookback-window: 1 day ago
-      title-prefix: "[oblt-aw][autodoc]"
-      additional-instructions: |
+      platform-additional-instructions: |
         Your task is to analyze ALL documentation in this repository, identify gaps and areas for improvement, and file an issue with concrete findings.
 
         Do NOT search for open issues. Instead, perform a direct documentation audit of this repository.
@@ -56,6 +43,20 @@ jobs:
         **Issue format:** For each finding, include a clear, actionable checklist of specific documentation changes to make. Each item should reference file paths and describe the change needed.
 
         **Team notification (mandatory):** Always @mention @elastic/observablt-ci at the top of the issue body so the team receives notifications. Example: "cc @elastic/observablt-ci" or "Notify: @elastic/observablt-ci" at the start of the body.
+
+  # Step 1: Detect docs drift from recent code changes and create an issue with findings
+  audit:
+    needs: prelude
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: read
+    if: needs.prelude.outputs.proceed == 'true'
+    uses: elastic/ai-github-actions/.github/workflows/gh-aw-docs-patrol.lock.yml@main
+    with:
+      lookback-window: 1 day ago
+      title-prefix: "[oblt-aw][autodoc]"
+      additional-instructions: ${{ needs.prelude.outputs.resolved-additional-instructions }}
     secrets: inherit
 
   # Step 2: Create a PR implementing the audit findings (only when an issue was created)

.github/workflows/oblt-aw-automerge.yml

@@ -18,6 +18,8 @@ jobs:
     with:
       enabled-workflow-id: obs:automerge
       load-allowed-authors: true
+      platform-additional-instructions: |
+        Target pull request number: ${{ github.event.pull_request.number }}.
 
   # Single PR from github.event.pull_request. PR fields only (pull_request trigger).
   verify:
@@ -154,8 +156,7 @@ jobs:
     uses: elastic/ai-github-actions/.github/workflows/gh-aw-mention-in-pr.lock.yml@main
     with:
       allowed-bot-users: ${{ needs.prelude.outputs.allowed-pr-authors-csv }}
-      additional-instructions: |
-        Target pull request number: ${{ github.event.pull_request.number }}.
+      additional-instructions: ${{ needs.prelude.outputs.resolved-additional-instructions }}
       prompt: |
         For pull request #${{ github.event.pull_request.number }}: evaluate automerge eligibility.
 

.github/workflows/oblt-aw-dependency-review.yml

@@ -17,24 +17,7 @@ jobs:
     with:
       enabled-workflow-id: obs:dependency-review
       load-allowed-authors: true
-
-  dependency-review:
-    needs: prelude
-    permissions:
-      actions: read
-      contents: read
-      issues: write
-      pull-requests: write
-    if: >-
-      needs.prelude.outputs.proceed == 'true' &&
-      github.event_name == 'pull_request' &&
-      contains(fromJSON('["opened","synchronize","reopened"]'), github.event.action) &&
-      contains(fromJSON(needs.prelude.outputs.allowed-pr-authors-json), github.event.pull_request.user.login)
-    uses: elastic/ai-github-actions/.github/workflows/gh-aw-dependency-review.lock.yml@main
-    with:
-      allowed-bot-users: ${{ needs.prelude.outputs.allowed-pr-authors-csv }}
-      classification-labels: "oblt-aw/ai/merge-ready"
-      additional-instructions: |
+      platform-additional-instructions: |
         Noop when not applicable (mandatory):
         - If the PR has NO dependency updates to review (e.g. no version bumps in manifest files, no changes to lockfiles that indicate dependency updates, or changes that do not match any supported ecosystem), you MUST call `noop` — do NOT create any comment.
         - Use the format: {"noop": {"message": "No action needed: [brief explanation]"}}
@@ -62,6 +45,24 @@ jobs:
         Label application (mandatory):
         - When ALL criteria for `oblt-aw/ai/merge-ready` are met, you MUST call `add_labels` with that label. Do not only recommend it in the comment; apply it via the add_labels tool.
         - The comment's "Labels Applied" section must reflect labels you actually applied via add_labels, not merely recommended. If you applied a label, say so; if you did not apply any, say "No labels applied."
+
+  dependency-review:
+    needs: prelude
+    permissions:
+      actions: read
+      contents: read
+      issues: write
+      pull-requests: write
+    if: >-
+      needs.prelude.outputs.proceed == 'true' &&
+      github.event_name == 'pull_request' &&
+      contains(fromJSON('["opened","synchronize","reopened"]'), github.event.action) &&
+      contains(fromJSON(needs.prelude.outputs.allowed-pr-authors-json), github.event.pull_request.user.login)
+    uses: elastic/ai-github-actions/.github/workflows/gh-aw-dependency-review.lock.yml@main
+    with:
+      allowed-bot-users: ${{ needs.prelude.outputs.allowed-pr-authors-csv }}
+      classification-labels: "oblt-aw/ai/merge-ready"
+      additional-instructions: ${{ needs.prelude.outputs.resolved-additional-instructions }}
     secrets:
       COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
 

.github/workflows/oblt-aw-duplicate-issue-detector.yml

@@ -31,5 +31,7 @@ jobs:
         github.event_name == 'workflow_dispatch'
       )
     uses: elastic/ai-github-actions/.github/workflows/gh-aw-duplicate-issue-detector.lock.yml@main
+    with:
+      additional-instructions: ${{ needs.prelude.outputs.resolved-additional-instructions }}
     secrets:
       COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}

.github/workflows/oblt-aw-estc-pr-buildkite-detective.yml

@@ -19,6 +19,8 @@ jobs:
     uses: ./.github/workflows/aw-prelude.yml
     with:
       enabled-workflow-id: obs:estc-pr-buildkite-detective
+      platform-additional-instructions: |
+        If a step fails, check if the failure is reported as a GitHub issue labeled `flaky-test`. Reference the GitHub issue if so.
 
   estc-pr-buildkite-detective:
     needs: prelude
@@ -34,8 +36,7 @@ jobs:
       contains(github.event.context, 'buildkite')
     uses: elastic/ai-github-actions/.github/workflows/gh-aw-estc-pr-buildkite-detective.lock.yml@copilot/reduce-comment-spamming
     with:
-      additional-instructions: |
-        If a step fails, check if the failure is reported as a GitHub issue labeled `flaky-test`. Reference the GitHub issue if so.
+      additional-instructions: ${{ needs.prelude.outputs.resolved-additional-instructions }}
     secrets:
       COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
       BUILDKITE_API_TOKEN: ${{ secrets.BUILDKITE_API_TOKEN }}