feat: add agentic workflow to guard documentation tone of voice

.cspell.json

@@ -263,6 +263,9 @@
     "mkdir",
     "mkdocs",
     "mlops",
+    "msal",
+    "MSAL",
+    "microsoftonline",
     "msrc",
     "MSRC",
     "MTBF",
@@ -334,6 +337,7 @@
     "pwsh",
     "pycodestyle",
     "pydocstyle",
+    "pygments",
     "Pyflakes",
     "pylint",
     "Pylint",

.gitattributes

@@ -16,4 +16,6 @@
 *.{md,[mM][dD]} text eol=lf
 *.{markdown,[mM][aA][rR][kK][dD][oO][wW][nN]} text eol=lf
 *.{markdn,[mM][aA][rR][kK][dD][nN]} text eol=lf
-*.{mdown,[mM][dD][oO][wW][nN]} text eol=lf
+*.{mdown,[mM][dD][oO][wW][nN]} text eol=lf
+
+.github/workflows/*.lock.yml linguist-generated=true merge=ours

.github/aw/actions-lock.json

@@ -0,0 +1,9 @@
+{
+  "entries": {
+    "github/gh-aw-actions/setup@v0.86.2": {
+      "repo": "github/gh-aw-actions/setup",
+      "version": "v0.86.2",
+      "sha": "6aab9e5b5c91c615506061f09bedd81a23babe3c"
+    }
+  }
+}

.github/mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "github-agentic-workflows": {
+      "command": "gh",
+      "args": [
+        "aw",
+        "mcp-server"
+      ]
+    }
+  }
+}

.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,26 @@
+name: "Copilot Setup Steps"
+
+# This workflow configures the environment for GitHub Copilot Agent with gh-aw MCP server
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+  # The job MUST be called 'copilot-setup-steps' to be recognized by GitHub Copilot Agent
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+
+    # Set minimal permissions for setup steps
+    # Copilot Agent receives its own token with appropriate permissions
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+      - name: Install gh-aw extension
+        uses: github/gh-aw-actions/setup-cli@6aab9e5b5c91c615506061f09bedd81a23babe3c # v0.86.2
+        with:
+          version: v0.86.2

.github/workflows/mkdocs.yml

@@ -15,12 +15,12 @@ jobs:
       pages: write
       pull-requests: write
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           submodules: "recursive"
           fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
       - name: Setup Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.13"
           architecture: "x64"
@@ -32,7 +32,7 @@ jobs:
       - name: Build site
         run: mkdocs build
       - name: Deploy
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./site

.github/workflows/tone-of-voice-reviewer.md

@@ -0,0 +1,84 @@
+---
+emoji: 🗣️
+description: On-demand advisory tone-of-voice reviewer for documentation PRs, grounded in the repository Writing Style Guidelines.
+on:
+  # A reviewer runs the check on demand by commenting "/review-the-tone" on a pull request.
+  slash_command:
+    name: review-the-tone
+    events: [pull_request_comment]
+permissions:
+  contents: read
+  pull-requests: read
+tools:
+  github:
+    mode: gh-proxy
+    toolsets: [pull_requests, repos]
+safe-outputs:
+  submit-pull-request-review:
+    max: 1
+    allowed-events: [COMMENT]
+  create-pull-request-review-comment:
+    max: 10
+---
+
+# Tone of Voice Reviewer
+
+## Goal
+
+Review the Markdown changes in this pull request for **tone of voice, clarity, and
+inclusivity**, and post advisory (non-blocking) feedback. This is an assistive check —
+never request changes and never approve.
+
+## Ground Truth
+
+The single source of truth for tone and style is the repository's own guidance. Read it
+before reviewing and cite it in every finding:
+
+- `docs/code-reviews/recipes/markdown.md` — the "Writing Style Guidelines" section
+  (active voice, inclusive language, concise wording, no jargon, chronological order).
+- `docs/code-reviews/inclusion-in-code-review.md` — keep feedback suggestive, not
+  prescriptive.
+- `docs/documentation/best-practices/good-documentation.md` — documentation quality.
+
+Do not invent your own style rules. If the guidance does not cover a case, stay silent.
+
+## Scope
+
+- Review **only the lines added or changed** in this PR's diff, comparing the PR head to
+  the base branch. Use `gh pr diff` and the GitHub tools to get the changed hunks.
+- Only consider prose in Markdown (`.md`) files.
+- **Ignore** fenced code blocks, inline code, tables, front matter, URLs/link targets,
+  image paths, and file names — tone rules apply to sentences, not code or markup.
+- Do **not** re-flag issues that deterministic linters already own (raw markdownlint
+  syntax rules, `write-good` grammar). Focus on judgment calls linters cannot make.
+- Before posting, fetch the PR's existing review comments (a reviewer can invoke this
+  check more than once). Do **not** repeat advisory feedback for a line or issue that a
+  previous run already commented on; only comment on newly changed or still-unaddressed prose.
+
+## What to Check
+
+For each changed prose passage, evaluate against the Writing Style Guidelines:
+
+- **Active voice** over passive voice.
+- **Clarity and concision** — remove filler, redundancy, and hedging; stick to the goal.
+- **Inclusive, jargon-free language** that is easy to understand.
+- **Consistent tone** with the surrounding document and the rest of the playbook.
+- **Chronological / logical order** where a sequence is described.
+
+## How to Report
+
+- For a specific problematic line, use `create-pull-request-review-comment` with a
+  concrete rewrite suggestion and a short citation of the rule (for example:
+  "Prefer active voice — see Writing Style Guidelines › Wording").
+- Post at most one overall summary via `submit-pull-request-review` using the `COMMENT`
+  event. Keep the summary to the top few findings.
+- Cap total **new** line comments at 10, counting only issues not already raised on
+  this PR — surface the highest-value issues only.
+- Match the tone you are enforcing: be kind, suggestive, and concise, following the
+  inclusion-in-code-review guidance.
+
+## No-Op
+
+If the changed prose already follows the guidelines (or the PR only touches code,
+config, tables, or generated files), call `noop` with a one-line explanation and post
+no comments.

.gitignore

@@ -301,6 +301,10 @@ paket-files/
 __pycache__/
 *.pyc
 
+# Python virtual environments
+.venv/
+venv/
+
 # Cake - Uncomment if you are using it
 # tools/**
 # !tools/packages.config
@@ -345,3 +349,6 @@ _site
 site/
 mkdocs/
 megalinter-reports/
+
+# Copilot agent tracking artifacts
+.copilot-tracking/

.mega-linter.yml

@@ -12,9 +12,15 @@ ENABLE_LINTERS:
   - SPELL_CSPELL
   - YAML_PRETTIER
   - YAML_YAMLLINT
-  - SPELL_LYCHEE
+  # SPELL_LYCHEE intentionally not enabled yet: the link checker surfaces a large
+  # backlog of pre-existing broken/blocked external links. Re-enable once those
+  # are triaged. The lychee.toml config is kept ready for when it's turned on.
 
 SPELL_CSPELL_DISABLE_ERRORS: true
+# gh-aw compiles workflows to *.lock.yml. These generated files use runtime features
+# (ubuntu-slim runner, queued concurrency) and long embedded JSON lines that trip
+# actionlint and yamllint. gh-aw validates its own output, so exclude them from all linters.
+FILTER_REGEX_EXCLUDE: "\\.lock\\.yml$"
 SHOW_ELAPSED_TIME: true
 FILEIO_REPORTER: false
 PARALLEL: true

README.md

@@ -23,7 +23,7 @@ If you do nothing else follow the [Engineering Fundamentals Checklist](docs/engi
 
 ## Structure of a Sprint
 
-A [breakdown of sections](docs/the-first-week-of-an-ise-project.md) according to the structure of an Agile sprint.
+A [project kickoff checklist](docs/start-here/project-kickoff-checklist.md) breaks down the playbook according to the structure of an Agile sprint.
 
 ## General Guidance
 
@@ -40,18 +40,21 @@ A [breakdown of sections](docs/the-first-week-of-an-ise-project.md) according to
 
 ## Resources
 
+* [Start Here](docs/start-here/README.md)
+* [AI-Assisted Engineering](docs/ai-assisted-engineering/README.md)
 * [Engineering Fundamentals Checklist](docs/engineering-fundamentals-checklist.md)
-* [The first week of an ISE project](docs/the-first-week-of-an-ise-project.md)
+* [Project Kickoff Checklist](docs/start-here/project-kickoff-checklist.md)
 
 ## Engineering Fundamentals
 
 * [Accessibility](docs/non-functional-requirements/accessibility.md)
+* [AI-Assisted Engineering](docs/ai-assisted-engineering/README.md)
 * [Agile Development](docs/agile-development/README.md)
 * [Automated Testing](docs/automated-testing/README.md)
 * [Code Reviews](docs/code-reviews/README.md)
 * [Continuous Delivery (CD)](docs/CI-CD/continuous-delivery.md)
 * [Continuous Integration (CI)](docs/CI-CD/continuous-integration.md)
-* [Design](docs/design/readme.md)
+* [Design](docs/design/README.md)
 * [Developer Experience](docs/developer-experience/README.md)
 * [Documentation](docs/documentation/README.md)
 * [Engineering Feedback](docs/engineering-feedback/README.md)

docs/.pages

@@ -1,10 +1,22 @@
 nav:
   - ISE Engineering Fundamentals Playbook: README.md
-  - Engineering Fundamentals Checklist: engineering-fundamentals-checklist.md
-  - The First Week of an ISE Project: the-first-week-of-an-ise-project.md
+  - Start Here: start-here
   - Who is ISE?: ISE.md
-  - Agile Development: agile-development
+  - The First Week of an ISE Project: the-first-week-of-an-ise-project.md
+  - Engineering Fundamentals Checklist: engineering-fundamentals-checklist.md
+  - Source Control: source-control
+  - Code Reviews: code-reviews
   - Automated Testing: automated-testing
   - CI/CD: CI-CD
-  - ...
+  - AI-Assisted Engineering: ai-assisted-engineering
+  - Security: security
+  - Observability: observability
+  - Agile Development: agile-development
+  - Design: design
+  - Developer Experience: developer-experience
+  - Documentation: documentation
+  - Engineering Feedback: engineering-feedback
+  - Non-Functional Requirements: non-functional-requirements
+  - ML & AI Projects: ml-and-ai-projects
   - UI/UX: UI-UX
+  - Resources: resources

docs/CI-CD/README.md

@@ -62,10 +62,19 @@ AppVeyor is another free CI service for open source projects which also supports
 
 AI tools can accelerate writing CI/CD pipeline YAML, jobs, and scripting snippets, but they must be used with explicit guardrails.
 
+For AI-powered applications, CI/CD also needs to validate the release artifacts that shape model behavior. We treat those artifacts as deployable units with owners, review history, rollback paths, and release gates, rather than as loose configuration. The artifacts we version this way include:
+
+- Prompts and safety policies
+- Model configuration and grounding indexes
+- Evaluation datasets and tool permission manifests
+
+Use the [AI-Assisted Engineering](../ai-assisted-engineering/README.md) guide for shared review, security, and traceability expectations when AI assistance is used to draft pipeline or release automation changes.
+
 Suggested workflow:
 - Use AI to draft CI/CD pipeline templates or job steps as a starting point (for example, generating a minimal GitHub Actions workflow).
 - Run the draft pipeline in a safe non-production environment or CI sandbox to validate syntax and basic behavior.
 - Require a human reviewer to validate generated steps for correctness, idempotence, and security implications (especially around secrets, permissions, and external actions).
+- For generative AI or agentic features, add automated evaluation, safety, grounding, and tool-permission checks before deployment to shared environments.
 - Add tests or smoke checks to the pipeline so changes can be validated automatically when the pipeline runs.
 - Promote approved templates into a central location (for example, `.github/workflows/` or a shared pipeline template repository) so teams reuse vetted, audited pipelines.
 
@@ -74,9 +83,12 @@ Guardrails and checklist (before merging AI-generated pipeline changes):
 - [ ] No secrets or credentials are hard-coded
 - [ ] Required linting and syntax checks pass locally and in CI
 - [ ] Security and license scans run and report no critical issues
+- [ ] Prompt, model, retrieval, safety, and tool-permission changes have evaluation evidence in the PR or release record
+- [ ] AI-enabled systems include evaluation gates for prompt, model, retrieval, and agent behavior, plus safety and regression checks, where applicable
 - [ ] Pipeline steps are idempotent and have clear rollback strategies where applicable
 - [ ] Generated content is annotated in the PR description (e.g., "AI-assisted draft") so reviewers know to apply extra scrutiny
 
 Notes:
 - AI-generated pipelines are excellent for reducing boilerplate and accelerating iteration, but they do not replace domain knowledge and security review.
 - Maintain a small set of vetted pipeline templates to reduce risk and improve reproducibility.
+- Use the [generative AI and agentic systems](../ml-and-ai-projects/generative-ai-and-agentic-systems.md#review-the-system-across-disciplines) guidance when a delivery pipeline changes prompts, grounding data, model settings, safety controls, or agent tools.

docs/CI-CD/continuous-integration.md

@@ -28,6 +28,10 @@ A robust build automation pipeline will:
 ### Code / Manifest Artifacts Required to Build Your Project Should be Maintained Within Your Projects Git Repository
 
 - CI provider-specific build pipeline definition(s) should reside within your project(s) git repository(s).
+- For generative AI and agentic applications, prompts, evaluation datasets, model configuration, grounding index definitions, safety policies, orchestration settings, and tool permission manifests should be maintained as versioned artifacts when they affect product behavior.
+- AI application artifacts should have the same review, test, rollback, and promotion expectations as application code and infrastructure templates.
+- Build validation should fail when prompt, model, retrieval, safety, or tool-permission changes are missing required evaluation evidence or schema checks.
+- Generated indexes, embeddings, and caches do not always belong in git, but the source data selection, transformation logic, index configuration, and release record should be traceable.
 
 ## Build Automation
 
@@ -82,6 +86,7 @@ Manage as much of the following as possible, as code:
 - Configuration Files
 - Configuration Management(ie environment variable automation via [terraform](https://github.com/microsoft/cobalt/blob/master/infra/modules/providers/azure/app-service/main.tf#L49))
 - Secret Management(ie creating Azure secrets via [terraform](https://github.com/microsoft/cobalt/blob/master/infra/templates/az-isolated-service-single-region/app.tf#L84))
+- AI application release artifacts, including prompt templates, eval suites, model settings, grounding index definitions, safety policies, and tool permission manifests
 - Cloud Resource Provisioning
 - Role Assignments
 - Load Test Scenarios
@@ -180,7 +185,7 @@ The schema has 30+ [validators](https://json-schema.org/tools?query=#validator)
 
 ## Integration Validation
 
-An effective way to identify bugs in your build at a rapid pace is to invest early into a reliable suite of automated tests that validate the baseline functionality of the system:
+An effective way to identify bugs in your build at a rapid pace is to invest early into a reliable suite of automated tests that validate the baseline functionality of the system. For the unit, integration, and end-to-end testing taxonomy and when to apply each, see the [automated testing fundamentals](../automated-testing/README.md#the-fundamentals) and the [end-to-end testing guide](../automated-testing/e2e-testing/README.md); the points below focus on wiring those tests into CI.
 
 ### End-to-End Integration Tests
 
@@ -216,6 +221,8 @@ An effective way to identify bugs in your build at a rapid pace is to invest ear
 
 ### Branch Policy Enforcement
 
+The canonical branch and pull request workflow lives in [source control](../source-control/README.md#creating-a-new-repository) and the [pull request guidance](../code-reviews/pull-requests.md). The CI-specific enforcement below ensures builds gate reviews and merges:
+
 - Protected [branch policies](https://help.github.com/en/github/administering-a-repository/about-protected-branches) should be setup on the main branch to ensure that CI stage(s) have passed prior to starting a code review. Code review approvers will only start reviewing a pull request once the CI pipeline run passes for the latest pushed git commit.
 - Broken builds should block pull request reviews.
 - Prevent commits directly into main branch.
@@ -233,7 +240,7 @@ In the spirit of transparency and embracing frequent communication across a dev
 ### Everyone Commits to the Git Repository Each Day
 
 - End of day checked-in code should contain unit tests at the minimum.
-- Run the build locally before checking in to avoid CI pipeline failure saturation. You should verify what caused the error, and try to solve it as soon as possible instead of committing your code. We encourage developers to follow a [lean SDLC principles](https://leankit.com/learn/lean/principles-of-lean-development/).
+- Run the build locally before checking in to avoid CI pipeline failure saturation. You should verify what caused the error, and try to solve it as soon as possible instead of committing your code. We encourage developers to follow a [lean SDLC principles](https://www.planview.com/resources/guide/lean-principles-101/).
 - Isolate work into small chunks which ties directly to business value and refactor incrementally.
 
 ## Isolated Environments

docs/README.md

@@ -9,6 +9,8 @@ An engineer working for a [ISE](ISE.md) project...
 
 This is our playbook. All contributions are welcome! Please feel free to submit a pull request to get involved.
 
+New here? Start with [How to use this playbook](start-here/README.md), then choose the guide for your role.
+
 ## Why Have a Playbook
 
 * To increase overall efficiency for team members and the whole team in general.
@@ -17,7 +19,9 @@ This is our playbook. All contributions are welcome! Please feel free to submit
 
 If you do nothing else follow the [Engineering Fundamentals Checklist](./engineering-fundamentals-checklist.md)!
 
-The [first week of an ISE project](./the-first-week-of-an-ise-project.md) is a breakdown of the sections of the playbook according to the structure of an Agile sprint.
+The [project kickoff checklist](./start-here/project-kickoff-checklist.md) is a breakdown of the sections of the playbook according to the structure of an Agile sprint.
+
+Use [AI-Assisted Engineering](./ai-assisted-engineering/README.md) as the shared baseline for using AI tools in engineering work while preserving human ownership, validation, security, privacy, accessibility, and project governance.
 
 ## General Guidance