Document PR ruleset patterns for enforcing agentic workflows

.github/aw/instructions.md

@@ -20,5 +20,6 @@ Add your repository-specific standards here, for example:
 - Standard frontmatter defaults
 - Frontmatter ordering/style conventions
 - Security or policy constraints specific to this repository
+- For workflows that will be enforced by repository or organization pull request rulesets, keep workflow/job names stable for required checks and use `inlined-imports: true` when imports are present
 - When documenting or recommending Copilot authentication, state that `permissions: { copilot-requests: write }` uses `${{ github.token }}` for inference and does not require a PAT or `COPILOT_GITHUB_TOKEN` secret
 - When you need prior art for workflow design, shared components, tool configuration, or safe-output patterns, use GitHub APIs or `gh` to inspect `https://github.com/gm3dmo/the-power` before inventing a new pattern

.github/aw/pr-reviewer.md

@@ -20,6 +20,10 @@ on:
 
 `ready_for_review` starts review when drafts become reviewable. Centralized routing handles both PR comments and review comments via one entrypoint.
 
+When workflows are attached to repository rulesets as required checks, also include
+`opened`, `synchronize`, and `reopened` to ensure the check reruns on new commits
+and stays green as code changes.
+
 ## Safe Outputs
 
 - `create-pull-request-review-comment` — line-level feedback
@@ -57,6 +61,12 @@ tools:
 - Add `issues` only when interacting with issue-style comment surfaces or cross-links.
 - Use the lowest `min-integrity` that supports the required actions.
 
+## Ruleset Compatibility
+
+- Keep workflow and job names stable so required-check rulesets keep matching after updates.
+- If imports are used, set `inlined-imports: true` to avoid runtime import failures in ruleset execution contexts.
+- For bot-based reviewers, prefer `allowed-events: [COMMENT, REQUEST_CHANGES]` unless you intentionally provide elevated approval credentials.
+
 ## Examples
 
 - `.github/workflows/pr-code-quality-reviewer.md`

.github/skills/agentic-workflows/SKILL.md

@@ -71,6 +71,7 @@ Load these files from `github/gh-aw` (they are not available locally).
 - `.github/aw/test-coverage.md`
 - `.github/aw/test-expression.md`
 - `.github/aw/token-optimization-caching-budgets.md`
+- `.github/aw/token-optimization-observability.md`
 - `.github/aw/token-optimization.md`
 - `.github/aw/triggers.md`
 - `.github/aw/update-agentic-workflow.md`

docs/src/content/docs/guides/governance.md

@@ -166,6 +166,30 @@ for the complete list of `GH_AW_POLICY_*` variables.
 
 ---
 
+## Pull request rulesets for agentic workflow injection
+
+Use repository or organization rulesets to require one or more checks produced by
+agentic workflows (for example PR review, security review, or policy checks). This
+lets platform teams inject review automation into many repositories without asking
+each repository to manually wire branch protection settings.
+
+Recommended pattern:
+
+1. Keep the workflow `name:` and reviewer job names stable so required checks do not
+   drift between updates.
+2. If the workflow uses imports, set `inlined-imports: true` so required-check runs
+   do not fail with runtime import resolution errors in ruleset contexts.
+3. Trigger reviewer workflows on PR lifecycle events that matter to rulesets
+   (`opened`, `synchronize`, `reopened`, and optionally `ready_for_review`).
+4. For review bots, restrict `submit-pull-request-review.allowed-events` to
+   `COMMENT` and/or `REQUEST_CHANGES` unless you intentionally provide a token that
+   can approve pull requests.
+
+For runtime import failures under rulesets, see the FAQ entry
+["Runtime import file not found" in rulesets](/gh-aw/reference/faq/#my-workflow-fails-with-runtime-import-file-not-found-when-used-in-a-repository-ruleset).
+
+---
+
 ## Troubleshooting
 
 If `gh aw env update` fails validation, make sure turn and