Make docs agent workflows autonomous (#137)

* Pack identical APM skill bundle across all reusable workflows

Every APM-importing reusable workflow in this repo currently caches its
skill bundle under the constant key `apm-copilot-` when called from
elastic/docs-content. The cache key formula
`apm-${engine}-${hashFiles('.github/workflows/*.lock.yml')}` is evaluated
in the caller's workspace, which has no lock files — so the hash segment
is empty for every workflow.

While only docs-review used APM this was benign. Once the sweeps landed
(#123-#125), every additional workflow with a different `packages:` list
started overwriting the same cache slot. The next workflow to run hit
the previous one's bundle and got `Skill not found` for the skills it
actually imports — with the agent ultimately falling back to manual
analysis ("All skills are unavailable. I'll review the changes using my
own judgment now.").

Workaround: align every APM-importing workflow's `packages:` to the
union of all skills used across the repo, so all five workflows pack
the same bundle and cache collisions are no-ops. Adds a small per-run
download cost (each workflow pulls all seven skills, uses one or two)
but restores correctness.

Filed upstream as github/gh-aw#30365 — when fixed there, we can revert
each workflow's `packages:` back to its minimum set.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Make docs agent workflows autonomous

Embed the docs review and sweep rules directly in the agent prompts so the workflows no longer depend on runtime Elastic Docs Skills, while keeping Elastic docs MCP as the bounded source for published-doc verification.

Co-authored-by: OpenAI GPT-5.5 <noreply@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* Run Vale before docs review

Add deterministic Vale output to the docs-review workflow so style findings are grounded in elastic/vale-rules instead of runtime skills or model-only judgment.

Co-authored-by: OpenAI GPT-5.5 <noreply@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* Carry over docs skill review guidance

Embed the high-value style, jargon, frontmatter, content-type, applies_to, and page-opening guidance from Elastic Docs Skills into the autonomous workflow prompts while keeping Vale and MCP as evidence sources.

Co-authored-by: OpenAI GPT-5.5 <noreply@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: OpenAI GPT-5.5 <noreply@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 4 people

.claude/skills/create-agentic-workflow/SKILL.md

@@ -27,10 +27,10 @@ You are a workflow generator for the [elastic/docs-actions](https://github.com/e
 
 ## Background
 
-This repo uses [GitHub Agent Workflows](https://github.github.com/gh-aw/). Workflow `.md` sources live in `agentic-workflows/` as a library. A compile script copies them to `.github/workflows/` for the gh-aw compiler, which produces `.lock.yml` files that consumer repos call via `uses:`.
+This repo uses [GitHub Agent Workflows](https://github.github.com/gh-aw/). Workflow `.md` sources live in `.github/workflows/` for the gh-aw compiler, which produces `.lock.yml` files that consumer repos call via `uses:`. Usage documentation and trigger templates live under `agentic-workflows/`.
 
 Each workflow needs three files:
-1. `agentic-workflows/<name>/gh-aw-<name>.md` — workflow source (frontmatter + prompt)
+1. `.github/workflows/gh-aw-<name>.md` — workflow source (frontmatter + prompt)
 2. `agentic-workflows/<name>/example.yml` — trigger template callers copy
 3. `agentic-workflows/<name>/README.md` — usage documentation
 
@@ -64,6 +64,8 @@ Use `AskUserQuestion` to collect:
 Read an existing workflow for reference:
 - `.github/workflows/gh-aw-docs-issue-scope.md` — on-demand check pattern
 - `.github/workflows/gh-aw-issue-triage.md` — triage pattern with pre-steps
+- `.github/workflows/gh-aw-docs-style-sweep.md` — deterministic pre-step pattern
+- `.github/workflows/gh-aw-docs-coherence-sweep.md` — Elastic docs MCP pattern
 
 Generate `.github/workflows/gh-aw-<name>.md`. Read the available fragments in `.github/workflows/gh-aw-fragments/` and import those relevant to the workflow. **Always include `inlined-imports: true`** — this embeds all imported content at compile time, which is required for cross-repo `workflow_call` invocation.
 
@@ -110,6 +112,11 @@ tools:
     toolsets: [repos, issues, pull_requests, search]
   bash: true
   web-fetch:
+mcp-servers:
+  elastic-docs:
+    type: http
+    url: "https://www.elastic.co/docs/_mcp/"
+    allowed: ["*"]
 network:
   allowed:
     - defaults
@@ -137,6 +144,8 @@ Follow the frontmatter with the agent prompt in markdown. The imported fragments
 5. **Quality gate** — when to noop vs. when to report (noop is the expected outcome)
 6. **Output format** — exact format for the issue body, PR body, or comment
 
+Make the workflow autonomous. Do not require runtime skills or agent-local packages for core behavior. Embed the domain rules the agent needs, use deterministic pre-steps for mechanical checks, and use Elastic docs MCP for published-doc evidence when needed. If MCP is required for a finding but is unavailable, instruct the agent to `noop` or skip the finding rather than guessing.
+
 End with `${{ inputs.additional-instructions }}` so callers can inject repo-specific guidance.
 
 Read the existing workflows for examples.
@@ -177,7 +186,7 @@ For scheduled audits, add `issues: write` to permissions. For fixes, add `conten
 
 ### Step 5: Generate the README
 
-Create `agentic-workflows/<name>/README.md` following the pattern in `agentic-workflows/docs-check/README.md`:
+Create `agentic-workflows/<name>/README.md` following the pattern in `agentic-workflows/docs-review/README.md` or `agentic-workflows/docs-issue-scope/README.md`:
 - Description
 - Triggers table
 - Install section with curl one-liner

.github/workflows/gh-aw-docs-applies-to-sweep.lock.yml

@@ -1,27 +1,15 @@
 ---
 description: |
   Validates the `applies_to` frontmatter key across a docs corpus on a rotating
-  slice each run, using the docs-applies-to-tagging skill in audit mode.
-  Opens a single labeled fix-issue with structured YAML findings consumable by
-  a future fix-agent.
+  slice each run, using self-contained validation rules and the Elastic docs
+  MCP server for published cumulative-docs guidance. Opens a single labeled
+  fix-issue with structured YAML findings consumable by a future fix-agent.
 
 inlined-imports: true
 imports:
   - gh-aw-fragments/formatting.md
   - gh-aw-fragments/rigor.md
-  - uses: github/gh-aw/.github/workflows/shared/apm.md@v0.71.1
-    with:
-      # Workaround for github/gh-aw#30365: every APM-importing workflow in this
-      # repo must pack the same package set so they don't clobber each other's
-      # cache under the constant key apm-copilot- in the caller repo.
-      packages:
-        - elastic/elastic-docs-skills/skills/authoring/applies-to-tagging
-        - elastic/elastic-docs-skills/skills/authoring/content-type-checker
-        - elastic/elastic-docs-skills/skills/authoring/frontmatter-description
-        - elastic/elastic-docs-skills/skills/authoring/page-opening-optimizer
-        - elastic/elastic-docs-skills/skills/review/docs-check-style
-        - elastic/elastic-docs-skills/skills/review/flag-jargon-skill
-        - elastic/elastic-docs-skills/skills/review/frontmatter-audit
+  - gh-aw-fragments/mcp-pagination.md
 engine:
   id: copilot
   concurrency:
@@ -81,10 +69,16 @@ tools:
     - "git log *"
     - "yq *"
     - "jq *"
+mcp-servers:
+  elastic-docs:
+    type: http
+    url: "https://www.elastic.co/docs/_mcp/"
+    allowed: ["*"]
 network:
   allowed:
     - defaults
     - github
+    - "www.elastic.co"
 safe-outputs:
   noop:
   create-issue:
@@ -208,18 +202,38 @@ A pre-step has computed the in-scope file list:
 
 Read with `cat` / `jq`. If `in_scope_count` is `0`, call `noop` with the stats and stop.
 
-## Step 1: Run the skill in audit mode
+## Step 1: Validate applies_to autonomously
+
+This workflow is autonomous. Do not invoke runtime skills or depend on a skill package being installed. For each in-scope file, read the frontmatter block at the top of the copy under `/tmp/gh-aw/sweep-data/scope/` and inspect the `applies_to` key.
+
+Audit only. Do not edit repo originals or scope copies. This sweep emits an issue, not a PR.
+
+Before filing any validity finding, verify the rule from one of these sources:
 
-Invoke `skill(skill: docs-applies-to-tagging)` against `/tmp/gh-aw/sweep-data/scope/`.
+- A checked-in repository schema or docs-builder configuration in the source repository.
+- Published cumulative-docs guidance fetched during this run with `elastic-docs.get_document_by_url`, especially `/docs/contribute-docs/how-to/cumulative-docs/guidelines` and `/docs/contribute-docs/how-to/cumulative-docs/reference`.
+- Published syntax and placement guidance fetched during this run when body-level annotations are involved, especially the docs-builder applies_to syntax guide, badge placement guidance, and cumulative-docs example scenarios.
 
-**Audit mode only — do not write any files.** The skill defaults to validation when not asked to fix; reinforce that intent in the call. This sweep produces an issue, not edits.
+Use the published reference as the source of truth for allowed dimensions, keys, lifecycle states, and version formats. If the MCP server is unavailable and no local schema is available, call `noop` with `"applies_to reference unavailable; skipping applies_to sweep"` rather than emitting unverified findings.
 
-**If the skill returns "Skill not found", do not noop.** That error is ambiguous — it can mean the skill genuinely isn't installed, or that the invocation form was reformatted by the agent's tool serialization. Either way: fall back to manual analysis instead of aborting. Procedure:
+Apply these rules after verification:
 
-1. Try invoking the skill with the exact form `skill(skill: docs-applies-to-tagging)`.
-2. If that fails or returns "Skill not found": fall back to **manual analysis**. Use `bash` to scan each in-scope file's frontmatter (the YAML block at the top), checking for missing/invalid `applies_to` keys against the documented allowed values. Produce findings as you would have from the skill output, and add a single line in the issue body's `Notes` section: "skill `docs-applies-to-tagging` did not produce output in this run; findings are agent-only."
+- Every page should include page-level `applies_to` frontmatter.
+- Page-level `applies_to` should use one primary dimension: Stack/Serverless (`stack`, `serverless`), Deployment (`deployment` with deployment subkeys and, where documented, `serverless`), or Product (`product` with documented product subkeys). Section-level and inline annotations can use a different dimension when needed to clarify local exceptions.
+- Lifecycle values must match the verified reference. Current published states include `preview`, `beta`, `ga`, `deprecated`, `removed`, and `unavailable`, but do not rely on this list without fetching the reference or reading a local schema during the run.
+- Version values must use documented formats, such as major/minor versions, exact versions, ranges, or greater-than-or-equal versions, according to the verified reference.
+- `ech` is the current key for Elastic Cloud Hosted. Treat `ess` as deprecated in new or updated content unless local build constraints require it.
+- Validate version semantics: only one version per lifecycle, only one open-ended `+` lifecycle per key, exact versions use `=x.x` or `=x.x.x`, ranges use one hyphen with no spaces, range starts must be less than or equal to ends, and ranges must not overlap.
+- Do not write version numbers in prose next to `applies_to` badges. Let the badge carry version applicability.
+- Section-level annotations belong immediately after a heading and apply until the next heading of the same or higher level. Do not put inline annotations in headings.
+- Inline annotations are appropriate for a single phrase, property, definition-list term, or table cell, not for whole sections.
+- Badge placement should match the element: frontmatter for page-level, after headings for section-level, at the beginning of list items when the whole item varies, at the end of a definition-list term when the whole item varies, and in the first column or relevant cell for tables.
+- Use `applies-switch` tabs only when code blocks or workflows differ entirely between contexts.
+- Do not require `unavailable` when omission already communicates that the content does not apply. Report `unavailable` misuse only when the page creates a high risk of user confusion or contradicts the published guidance.
+- Do not flag dimension choices unless the page-level `applies_to` clearly mixes primary dimensions, contradicts `products`, or conflicts with the page's documented scope.
+- Do not add or require tags for typo fixes, formatting changes, information architecture changes, or sections whose applicability is already established by a parent tag.
 
-Only call `noop` if you cannot produce any high-confidence findings even from manual analysis.
+Only call `noop` if you cannot produce any high-confidence findings from verified rules.
 
 ## Step 2: Build the findings list
 
@@ -229,9 +243,9 @@ Categories (use exactly these strings):
 - `invalid-applies-to-syntax` — malformed YAML or unrecognized structure under `applies_to:`.
 - `invalid-applies-to-value` — recognized structure but a value (product, deployment, lifecycle stage) that is not in the allowed vocabulary.
 - `inconsistent-applies-to` — `applies_to` contradicts other frontmatter (e.g., `products:` says one thing, `applies_to:` another).
-- `outdated-applies-to` — references a deployment/lifecycle value that is deprecated per the skill's reference set.
+- `outdated-applies-to` — references a deployment or lifecycle value that is deprecated per the verified reference.
 
-For each finding extract `file`, `line`, `category`, `severity`, `evidence`, and `suggested_fix` (concrete YAML snippet) when the skill produces one.
+For each finding extract `file`, `line`, `category`, `severity`, `evidence`, and `suggested_fix` when you can produce a concrete YAML snippet confidently.
 
 Strip the `/tmp/gh-aw/sweep-data/scope/` prefix from `file` so paths are repo-relative.
 
@@ -259,11 +273,11 @@ Shard <slot+1>/<n> · <shard_count> pages in slice · <recent_count> recently-ch
   line: 4
   category: invalid-applies-to-value
   severity: high
-  evidence: "applies_to.deployment.ess: 'preview' — not in allowed lifecycle values"
+  evidence: "applies_to.deployment.ess uses an unrecognized deployment key; use `ech` for Elastic Cloud Hosted"
   suggested_fix: |
     applies_to:
       deployment:
-        ess: ga
+        ech: ga
 - file: docs/bar.md
   line: 1
   category: missing-applies-to
@@ -272,7 +286,7 @@ Shard <slot+1>/<n> · <shard_count> pages in slice · <recent_count> recently-ch
 ```
 
 ## Done when
-- All listed pages have a valid `applies_to` block per the skill's reference set.
+- All listed pages have a valid `applies_to` block per the verified reference.
 - A PR addressing this issue is merged.
 
 ## Notes
@@ -286,7 +300,7 @@ Keep the YAML block parseable. Use the literal `|` block scalar for multi-line `
 ## What to skip
 
 - Files outside `/tmp/gh-aw/sweep-data/in-scope.txt`.
-- `applies_to` values the skill flags as warnings without a concrete remediation — they belong in the next iteration, not this sweep.
+- `applies_to` warnings without a concrete remediation — they belong in the next iteration, not this sweep.
 - Generic `applies_to` shape preferences when the existing value is technically valid.
 
 ${{ inputs.additional-instructions }}