docs: restructure playbook & add AI-assisted engineering guidance

.cspell.json

@@ -172,6 +172,7 @@
     "gqlgen",
     "gradlew",
     "Grafana",
+    "gescazz",
     "gremcos",
     "gremgo",
     "Gruber",
@@ -263,6 +264,9 @@
     "mkdir",
     "mkdocs",
     "mlops",
+    "msal",
+    "MSAL",
+    "microsoftonline",
     "msrc",
     "MSRC",
     "MTBF",
@@ -334,6 +338,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/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

.gitignore

@@ -345,3 +345,6 @@ _site
 site/
 mkdocs/
 megalinter-reports/
+
+# Copilot agent tracking artifacts
+.copilot-tracking/

.mega-linter.yml

@@ -12,7 +12,9 @@ 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
 SHOW_ELAPSED_TIME: 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,19 @@
 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
+  - 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

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
 

docs/UI-UX/README.md

@@ -10,6 +10,17 @@ The goal of the **User Interface** section is to provide guidance on developing
 
 Keep in mind that like all software, there is no "right way" to build a user interface application. Leverage and trust your team's or your customer's experience and expertise for the best development experience.
 
+## AI-assisted UI and UX work
+
+AI-generated prototypes, personas, copy, and flows are exploration artifacts, not validated user research. Review them with designers, engineers, product owners, and affected users before treating them as product direction.
+
+1. Review generated personas, content, alt text, captions, and flows for accessibility, inclusion, bias, plain language, and cognitive load.
+1. For AI features in the user experience, design disclosure, user control, fallback, appeal, and human escalation.
+1. Include UX evaluation for trust calibration, error recovery, overreliance, and user understanding of AI limitations.
+1. Confirm which AI tools are approved for this project and data type before uploading designs, screenshots, transcripts, or customer context.
+
+Use the [AI-Assisted Engineering](../ai-assisted-engineering/README.md) guide for shared accessibility, privacy, and governance practices.
+
 ## General Guidance
 
 The state of web platform engineering is fast moving. There is no one-size-fits-all solution. For any team to be successful in building a UI, they need to have an understanding of the higher-level aspects of all UI project.
@@ -63,7 +74,7 @@ Design Ops, short for Design Operations, is a practice that focuses on optimizin
    - Creating and maintaining a design system that includes reusable components, style guides, and design tokens.
    - Promoting consistency and efficiency by using shared design assets.
    - For most projects within ISE we use [Fluent UI](https://developer.microsoft.com/en-us/fluentui#/controls/webcomponents) to handle most projects, this enables rapid development that allow for web application re-use on non-customer engagements or _white label_ applications.
-   - Other Design Systems used by customers include: [Google's Material Design](https://mui.com/material-ui/), 
+   - Other Design Systems used by customers include: [Google's Material Design](https://mui.com/material-ui/).
 
 4. **Documentation**:
    - Documenting design decisions, guidelines, and best practices.
@@ -77,7 +88,7 @@ Design Ops, short for Design Operations, is a practice that focuses on optimizin
 6. **Metrics and KPIs**:
    - Defining key performance indicators (KPIs) to measure the effectiveness of design processes.
    - Using metrics to identify areas for improvement and track progress over time.
-   - __For long-term projects:__ Incorporate _A/B testing_ for better user experiences, and enhancements to the solution.
+   - **For long-term projects:** Incorporate _A/B testing_ for better user experiences, and enhancements to the solution.
 
 ### Benefits of Design Ops for Software Engineers and Product Owners
 
@@ -90,12 +101,12 @@ By integrating Design Ops into the development process, software engineers can w
 
 ## Establishing a web application's architecture
 
-The benefit of building software applications is that there are truly infinite ways to build something. A team can use the latest shiny tools, or they can utilize the tried-and-tested ones. It is for this reason that focussing completely on the user until a solution is defined is better than obsessing over technology choices. 
+The benefit of building software applications is that there are truly infinite ways to build something. A team can use the latest shiny tools, or they can utilize the tried-and-tested ones. It is for this reason that focussing completely on the user until a solution is defined is better than obsessing over technology choices.
 
 When choosing a front-end framework or library, consider the project's complexity, performance, and scalability needs. Evaluate the team's expertise with potential options to ensure efficient development. Assess long-term maintainability and community support. Conduct [Trade Studies](./../design/design-reviews/trade-studies/README.md) to weigh pros and cons, focusing on alignment with project goals and user experience. This thorough analysis helps balance innovation with practicality.
 
 
-### Some platforms/frameworks to consider when planning a project:
+### Some platforms/frameworks to consider when planning a project
 
 1. HTML/CSS/JavaScript
    - Back to the basics! Start with a single **index.html**, include a popular CSS framework such as [Bootstrap](https://getbootstrap.com/) using their CDN link, and start prototyping!
@@ -112,7 +123,7 @@ When choosing a front-end framework or library, consider the project's complexit
    - A robust framework for building client-side applications. [Angular](https://angular.dev/) provides a comprehensive solution with built-in features like dependency injection, routing, and state management.
    - Ideal for large-scale applications where maintainability and scalability are crucial.
    - Better Unit Testing support out of the box than React.
-   - __Angular has no support for Fluent UI, and has tight integration with Google Cloud Platform.__
+   - **Angular has no support for Fluent UI, and has tight integration with Google Cloud Platform.**
 1. Blazor
    - A framework for building interactive web UIs using C# instead of JavaScript. [Blazor](https://dotnet.microsoft.com/en-us/apps/aspnet/web-apps/blazor) allows you to share code between the client and server.
    - Great for teams already familiar with the .NET ecosystem.
@@ -125,7 +136,7 @@ When choosing a front-end framework or library, consider the project's complexit
    - A React-based framework that enables server-side rendering and static site generation. [Next.js](https://nextjs.org/) improves performance and SEO.
    - Great for building fast, scalable web applications with a focus on developer experience.
    - Provides built-in support for API routes, making it easier to build full-stack applications.
-   - __Recommended by Meta going forward rather than use create-react-app.__
+   - **Recommended by Meta going forward rather than use create-react-app.**
    - Next.js is very heavy in terms of features, and it doesn't allow for re-use in non-Next.js applications like create-react-app, React-Native, or Electron based apps.
 1. Svelte
    - [Svelte](https://svelte.dev/) is a modern framework that shifts much of the work to compile time, resulting in highly optimized and performant applications.
@@ -146,5 +157,5 @@ When choosing a front-end framework or library, consider the project's complexit
 ### Further information
 
 > For more information of utilizing any of these frameworks/platforms, read the [Recommended Technologies](./recommended-technologies.md) document.
-> 
+>
 > Continue reading the [Trade Study](./../design/design-reviews/trade-studies/README.md) section of this site for more information on completing this step in the design process.