feat: add agentic workflow to guard documentation tone of voice - #1135
Open
vdstrizhkova wants to merge 12 commits into
Open
feat: add agentic workflow to guard documentation tone of voice#1135vdstrizhkova wants to merge 12 commits into
vdstrizhkova wants to merge 12 commits into
Conversation
added 4 commits
July 16, 2026 09:16
- align wording and tone across observability, security, code-review, and other docs - fix outdated/broken external links and dead references - add cspell terms, gitignore/gitattributes, and mkdocs workflow action bumps 📝 - Generated by Copilot
- lychee surfaces a backlog of pre-existing broken/blocked external links - keep it disabled (as in the source PR) until that backlog is triaged 🔧 - Generated by Copilot
- add AI-assisted engineering hub (docs/ai-assisted-engineering/README.md) - add generative-AI and agentic systems guidance, including HVE references 🤖 - Generated by Copilot
- add Start Here section with role on-ramps and project kickoff checklist - add Non-Functional Requirements section and update navigation (.pages, READMEs) - rename docs/design/readme.md to README.md; remove superseded first-week page 🗂️ - Generated by Copilot
6 tasks
vdstrizhkova
marked this pull request as ready for review
July 16, 2026 17:03
vdstrizhkova
requested review from
Tess Ferrandez (TessFerrandez),
N Youens (nyouens) and
Shiran Rubin (shiranr)
as code owners
July 16, 2026 17:03
| - Workflow files: `.github/workflows/*.md` and `.github/workflows/**/*.md` | ||
| - Workflow lock files: `.github/workflows/*.lock.yml` | ||
| - Shared components: `.github/workflows/shared/*.md` | ||
| - Configuration: `.github/aw/github-agentic-workflows.md` |
Contributor
There was a problem hiding this comment.
This dispatcher references many .github/aw/*.md paths throughout the file (create-agentic-workflow.md, debug-agentic-workflow.md, network.md, patterns.md, token-optimization.md, github-agentic-workflows.md, cli-commands.md, report.md, dependabot.md, test-coverage.md, etc.). None of those files exist in this repo — they live in github/gh-aw. As written, the agent will follow dead links. Either vendor the referenced files into this repo, or rewrite every reference to point to https://github.com/github/gh-aw/blob/main/.github/aw/... (as the designer skill already does in its "Portable HTTPS references" section)
There was a problem hiding this comment.
Pull request overview
This PR adds GitHub Agentic Workflows (gh-aw) automation scaffolding under .github/ (agent + skills + MCP config + setup workflow), intended to support agentic workflow usage in this repository (per PR description, to enforce documentation tone-of-voice consistency going forward).
Changes:
- Adds a
copilot-setup-stepsGitHub Actions workflow to install/configure the gh-aw CLI extension for Copilot Agent runs. - Adds an “Agentic Workflows” dispatcher agent plus supporting routing and “workflow designer” skills.
- Adds an MCP server configuration to expose
gh aw mcp-server.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
.github/workflows/copilot-setup-steps.yml |
Adds CI setup steps for Copilot Agent runs (checkout + gh-aw setup). |
.github/skills/agentic-workflows/SKILL.md |
Adds a router/dispatcher skill for gh-aw workflow-related requests. |
.github/skills/agentic-workflow-designer/SKILL.md |
Adds an interview-style skill to design workflows before generating a workflow .md. |
.github/mcp.json |
Configures an MCP server backed by gh aw mcp-server. |
.github/agents/agentic-workflows.md |
Adds an agent definition to route gh-aw workflow tasks to the right prompts/guides. |
Suppressed comments (1)
.github/skills/agentic-workflows/SKILL.md:80
- This line references
skills/otel-queries/SKILL.md, but that file does not exist in the repo (and the path also omits the.github/prefix used elsewhere in this skill). As written, it will send users/agents to a dead reference.
When the task involves OTEL, OTLP, traces, observability backends, or telemetry-driven analysis, also read and follow `skills/otel-queries/SKILL.md` after loading the matching workflow prompt or skill.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| - `.github/skills/agentic-workflow-designer/SKILL.md` | ||
| After loading the matching workflow prompt or skill, follow it directly: | ||
| - Design workflows from scratch via interview: `skills/agentic-workflow-designer/SKILL.md` |
Comment on lines
+13
to
+17
| Use this before `.github/aw/create-agentic-workflow.md` when requirements are unclear or incomplete. | ||
|
|
||
| - Use `skills/agentic-workflow-designer/SKILL.md` to discover and confirm requirements. | ||
| - Use `.github/aw/create-agentic-workflow.md` once requirements are clear and ready for implementation. | ||
| - Use `.github/aw/agentic-chat.md` when the user wants a specification/pseudo-code instead of a runnable workflow file. |
Comment on lines
+2
to
+4
| name: Agentic Workflows | ||
| description: GitHub Agentic Workflows (gh-aw) - Create, debug, and upgrade AI-powered workflows with intelligent prompt routing. | ||
| disable-model-invocation: true |
Comment on lines
+55
to
+56
| ## Available Prompts | ||
|
|
| @@ -0,0 +1,11 @@ | |||
| { | |||
| "mcpServers": { | |||
| "github-agentic-workflows": { | |||
|
|
||
| Follow up: | ||
| - **"Any third-party services or MCP servers to include (for example Slack, Jira, Datadog, custom internal MCP)?"** | ||
| - **"Are you deploying on GitHub.com, GHEC with custom endpoints, or GHES?"** |
Contributor
There was a problem hiding this comment.
I think this is not relevant for this repository
| @@ -0,0 +1,224 @@ | |||
| --- | |||
Contributor
There was a problem hiding this comment.
Thanks for splitting this out of #1130. Before going further, could we discuss the direction? The files added look like a general-purpose assistant for authoring gh-aw workflows rather than something specific to the repository tone of voice.
Co-authored-by: Shiran Rubin <shiranrubin@gmail.com>
- add agentic-workflows agent and supporting skills (designer + workflows) - add mcp.json and copilot-setup-steps workflow to run the agent in CI 🤖 - Generated by Copilot
vdstrizhkova
force-pushed
the
feat/agentic-tone-of-voice
branch
from
August 11, 2026 11:10
0eb8c4d to
49b8800
Compare
added 5 commits
August 24, 2026 12:29
Commit the gh-aw workflow source (.md), its compiled lock (.lock.yml), and the action pin lock so the generated artifact stays in sync with its source. Align copilot-setup-steps gh-aw CLI to v0.86.2 to match the compiled lock.
The compiled *.lock.yml uses gh-aw runtime features (ubuntu-slim runner label, queued concurrency) that actionlint does not recognize. gh-aw validates its own output, so exclude generated lock files from the ACTION_ACTIONLINT linter.
Generated *.lock.yml files use gh-aw runtime features and long embedded JSON lines that trip actionlint and yamllint. Exclude them from all linters via the global FILTER_REGEX_EXCLUDE since gh-aw validates its own compiled output.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pull Request Template
What are you trying to address
This PR adds an on-demand tone-of-voice guard for documentation PRs, plus the AI-assisted engineering content that gives the guard a consistent standard to enforce
1. Tone-of-voice guard (automation)
.github/workflows/tone-of-voice-reviewer.md+.github/workflows/tone-of-voice-reviewer.lock.yml— advisory (non-blocking) gh-aw reviewer. A reviewer with write, maintainer, or admin access triggers it on demand by commenting /review-the-tone on a pull request; it then checks the changed Markdown prose against the repository's Writing Style Guidelines and posts COMMENT-only reviews. Caller permission is enforced by gh-aw's command role check (admin, maintainer, write) plus an author_association gate, so non-collaborators cannot invoke it..github/aw/actions-lock.json— gh-aw runtime setup and version pinning..github/agents/agentic-workflows.md,.github/skills/agentic-workflow-designer/SKILL.md,.github/skills/agentic-workflows/SKILL.md— supporting gh-aw authoring assistant. (Flagged for possible removal — see review notes RI-2/RI-3.).mega-linter.yml(exclude generated*.lock.yml, pauseSPELL_LYCHEE),.gitattributes,.gitignore,.cspell.json,mkdocs-overrides/main.html.2. New AI-assisted engineering guidance
docs/ai-assisted-engineering/README.mdanddocs/ml-and-ai-projects/generative-ai-and-agentic-systems.md, plus AI-assisted sections added across the security, testing, observability, code-review, source-control, design, privacy, and CI/CD pages.Validation: gh aw compile reproduces the committed .lock.yml; mkdocs build succeeds; MegaLinter passes with the documented exclusions. The reviewer is advisory only, runs only when a reviewer invokes /review-the-tone (no automatic CI load), and introduces no breaking change.
Key changes:
Checklist
READY TO PR? Use the check-list below to ensure your branch is ready for PR.