Improve ADR management and automation

Add new sections and workflows for ADR management and validation.

* **`docs/decisions/README.md`**:
  - Add sections explaining the purpose of the `docs/decisions` directory, the MADR template, and the benefits of using ADRs.
* **`docs/decisions/adr-template.md`**:
  - Update the template to include a section for "Validation".
  - Add a note about the importance of listing decision drivers.
* **`docs/decisions/adr-short-template.md`**:
  - Update the short template to include a section for "Validation".
  - Add a note about the importance of listing decision drivers.
* **`.github/workflows/adr-validation.yml`**:
  - Create a new GitHub Actions workflow for ADR validation.
  - Add steps to validate the structure and content of ADRs using a linter.
  - Schedule the workflow to run weekly.
* **`.github/workflows/adr-report-generation.yml`**:
  - Create a new GitHub Actions workflow for ADR report generation.
  - Add steps to scan the `docs/decisions` directory for ADR files and generate a summary report.
  - Schedule the workflow to run weekly.
* **`docs/adr-reports/summary.md`**:
  - Create a new file to store the generated ADR summary report.

---

For more details, open the [Copilot Workspace session](https://copilot-workspace.githubnext.com/Bryan-Roe-ai/semantic-kernel?shareId=XXXX-XXXX-XXXX-XXXX).

.github/workflows/adr-report-generation.yml

@@ -0,0 +1,33 @@
+name: ADR Report Generation
+
+on:
+  schedule:
+    - cron: '0 0 * * 0' # Runs weekly on Sunday at midnight
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  generate-adr-report:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.x'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install markdown
+
+      - name: Generate ADR Report
+        run: |
+          python scripts/generate_adr_report.py

.github/workflows/adr-validation.yml

@@ -0,0 +1,33 @@
+name: ADR Validation
+
+on:
+  schedule:
+    - cron: '0 0 * * 0' # Runs weekly on Sunday at midnight
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  validate-adrs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.x'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install markdownlint-cli
+
+      - name: Validate ADRs
+        run: |
+          markdownlint docs/decisions/*.md

docs/adr-reports/summary.md

@@ -0,0 +1,95 @@
+# ADR Summary Report
+
+This document provides a summary of the Architectural Decision Records (ADRs) in the repository.
+
+## ADRs
+
+### ADR-0001: Use Markdown Any Decision Records to track Semantic Kernel Architecture Decisions
+- **Status**: accepted
+- **Date**: 2023-05-29
+- **Deciders**: dluc, shawncal, hathind, alliscode
+- **Context and Problem Statement**: We have multiple different language versions of the Semantic Kernel under active development. We need a way to keep the implementations aligned with regard to key architectural decisions.
+- **Decision Drivers**: Architecture changes and the associated decision-making process should be transparent to the community. Decision records are stored in the repository and are easily discoverable for teams involved in the various language ports.
+- **Considered Options**: Use MADR format and store decision documents in the repository.
+- **Decision Outcome**: Chosen option: Use MADR format and store decision documents in the repository.
+
+### ADR-0002: Java Folder Structure
+- **Status**: accepted
+- **Date**: 2013-06-19
+- **Deciders**: shawncal, johnoliver
+- **Context and Problem Statement**: A port of the Semantic Kernel to Java is under development. The folder structure being used has diverged from the .Net implementation.
+- **Decision Drivers**: The Java SK should follow the general design guidelines and conventions of Java. Different language versions should be consistent with the .Net implementation.
+- **Considered Options**: Comparison of .Net and Java Folder structures.
+- **Decision Outcome**: Follow guidelines for folder names and structure to match those used (or planned for .Net) but in the idiomatic Java folder naming convention.
+
+### ADR-0003: Add support for multiple native function arguments of many types
+- **Status**: accepted
+- **Date**: 2023-06-16
+- **Deciders**: shawncal, dluc
+- **Context and Problem Statement**: Move native functions closer to a normal C# experience.
+- **Decision Drivers**: Native skills can now have any number of parameters. The parameters are populated from context variables of the same name.
+- **Considered Options**: Examples of before and after code for native functions.
+- **Decision Outcome**: PR 1195
+
+### ADR-0004: Error handling improvements
+- **Status**: accepted
+- **Date**: 2023-06-23
+- **Deciders**: shawncal
+- **Context and Problem Statement**: Enhance error handling in SK to simplify SK code and SK client code, ensuring consistency and maintainability.
+- **Decision Drivers**: Exceptions should be propagated to the SK client code instead of being stored in the SKContext. The SK exception hierarchy should be designed following the principle of "less is more."
+- **Considered Options**: Simplify existing SK exception hierarchy, use .NET standard exceptions, remove unnecessary exceptions, preserve original exception details.
+- **Decision Outcome**: Implement the proposed changes to improve error handling in SK.
+
+### ADR-0005: Kernel/Function Handlers - Phase 1
+- **Status**: accepted
+- **Date**: 2023-05-29
+- **Deciders**: rogerbarreto, shawncal, stephentoub
+- **Context and Problem Statement**: A Kernel function caller needs to handle/intercept any function execution in the Kernel before and after it was attempted.
+- **Decision Drivers**: Architecture changes and the associated decision-making process should be transparent to the community. Decision records are stored in the repository and are easily discoverable for teams involved in the various language ports.
+- **Considered Options**: Callback Registration + Recursive, Single Callback, Event Based Registration, Middleware, ISKFunction Event Support Interfaces.
+- **Decision Outcome**: Chosen option: Event Base Registration (Kernel only).
+
+### ADR-0006: Dynamic payload building for PUT and POST RestAPI operations and parameter namespacing
+- **Status**: accepted
+- **Date**: 2023-08-15
+- **Deciders**: shawncal
+- **Context and Problem Statement**: The SK OpenAPI does not allow the dynamic creation of payload/body for PUT and POST RestAPI operations.
+- **Decision Drivers**: Create a mechanism that enables the dynamic construction of the payload/body for PUT and POST RestAPI operations. Develop a mechanism(namespacing) that allows differentiation of payload properties with identical names at various levels for PUT and POST RestAPI operations.
+- **Considered Options**: Enable the dynamic creation of payload and/or namespacing by default. Enable the dynamic creation of payload and/or namespacing based on configuration.
+- **Decision Outcome**: Chosen option: Enable the dynamic creation of payload and/or namespacing based on configuration.
+
+### ADR-0007: Extract the Prompt Template Engine from Semantic Kernel core
+- **Status**: accepted
+- **Date**: 2023-08-25
+- **Deciders**: shawncal
+- **Context and Problem Statement**: The Semantic Kernel includes a default prompt template engine which is used to render Semantic Kernel prompts. To reduce the complexity and API surface of the Semantic Kernel, the prompt template engine is going to be extracted and added to its own package.
+- **Decision Drivers**: Reduce API surface and complexity of the Semantic Kernel core. Simplify the `IPromptTemplateEngine` interface to make it easier to implement a custom template engine. Make the change without breaking existing clients.
+- **Considered Options**: Create a new package called `Microsoft.SemanticKernel.TemplateEngine`. Maintain the existing namespace for all prompt template engine code. Simplify the `IPromptTemplateEngine` interface to just require implementation of `RenderAsync`. Dynamically load the existing `PromptTemplateEngine` if the `Microsoft.SemanticKernel.TemplateEngine` assembly is available.
+- **Decision Outcome**: Implement the proposed changes to extract the prompt template engine from the Semantic Kernel core.
+
+### ADR-0008: Refactor to support generic LLM request settings
+- **Status**: accepted
+- **Date**: 2023-09-15
+- **Deciders**: shawncal
+- **Context and Problem Statement**: The Semantic Kernel abstractions package includes a number of classes that are used to support passing LLM request settings when invoking an AI service. The problem with these classes is they include OpenAI specific properties only.
+- **Decision Drivers**: Semantic Kernel abstractions must be AI Service agnostic. Solution must continue to support loading Semantic Function configuration from `config.json`. Provide a good experience for developers and implementors of AI services.
+- **Considered Options**: Use `dynamic` to pass request settings. Use `object` to pass request settings. Define a base class for AI request settings which all implementations must extend.
+- **Decision Outcome**: Chosen option: Define a base class for AI request settings which all implementations must extend.
+
+### ADR-0009: Add support for multiple named arguments in template function calls
+- **Status**: accepted
+- **Date**: 2013-06-16
+- **Deciders**: shawncal, hario90
+- **Context and Problem Statement**: Native functions now support multiple parameters, populated from context values with the same name. Semantic functions currently only support calling native functions with no more than 1 argument.
+- **Decision Drivers**: Parity with Guidance. Readability. Similarity to languages familiar to SK developers. YAML compatibility.
+- **Considered Options**: Syntax idea 1: Using commas. Syntax idea 2: JavaScript/C#-Style delimiter (colon). Syntax idea 3: Python/Guidance-Style delimiter. Syntax idea 4: Allow whitespace between arg name/value delimiter.
+- **Decision Outcome**: Chosen options: "Syntax idea 3: Python/Guidance-Style keyword arguments" and "Syntax idea 4: Allow whitespace between arg name/value delimiter".
+
+### ADR-0010: DotNet Project Structure for 1.0 Release
+- **Status**: superseded by [ADR-0042](0042-samples-restructure.md)
+- **Date**: 2023-09-29
+- **Deciders**: SergeyMenshykh, dmytrostruk, RogerBarreto
+- **Context and Problem Statement**: Provide a cohesive, well-defined set of assemblies that developers can easily combine based on their needs. Remove `Skills` naming from NuGet packages and replace with `Plugins`.
+- **Decision Drivers**: Avoid having too many assemblies because of impact of signing these and to reduce complexity. Follow .Net naming guidelines.
+- **Considered Options**: Option #1: New `planning`, `functions` and `plugins` project areas. Option #2: Folder naming matches assembly name.
+- **Decision Outcome**: Chosen option: Option #2: Folder naming matches assembly name.

docs/decisions/README.md

@@ -22,3 +22,42 @@ For more information [see](https://adr.github.io/)
    2. The status must be updated to `accepted` once a decision is agreed and the date must also be updated.
    3. Approval of the decision is captured using PR approval.
 5. Decisions can be changed later and superseded by a new ADR. In this case it is useful to record any negative outcomes in the original ADR.
+
+## Purpose of the `docs/decisions` Directory and the Use of ADRs
+
+The purpose of the `docs/decisions` directory is to store architectural decision records (ADRs) for the project. These records document the context, decision drivers, considered options, and outcomes of significant architectural decisions made during the development of the project. This helps in maintaining a transparent decision-making process and provides a historical record of why certain decisions were made.
+
+* The directory contains markdown files that follow a structured template to capture the details of each decision.
+* Each file is named with a unique identifier and a descriptive title, making it easy to locate and reference specific decisions.
+* The ADRs cover a wide range of topics, including project structure, error handling, support for multiple arguments in functions, and more.
+* The records are intended to be easily discoverable for teams involved in the project, ensuring that architectural changes and the associated decision-making process are transparent to the community.
+* The directory also includes templates for creating new ADRs, ensuring consistency in how decisions are documented.
+
+## MADR Template and Its Structure
+
+The MADR (Markdown Any Decision Records) template is used to document architectural decisions in a structured way. Here are the key points about the MADR template based on the repository:
+
+* The `docs/decisions` directory contains architectural decision records (ADRs) that follow the MADR template.
+* Each ADR is a markdown file named with a unique identifier and a descriptive title, such as `docs/decisions/0001-madr-architecture-decisions.md`.
+* The template includes sections like status, date, deciders, context and problem statement, decision drivers, considered options, decision outcome, and more.
+* The status of an ADR can be `proposed`, `accepted`, or `superseded`.
+* The context and problem statement section describes the issue or decision to be made.
+* The decision drivers section lists the factors influencing the decision.
+* The considered options section outlines the different options considered for the decision.
+* The decision outcome section details the chosen option and its pros and cons.
+* The template ensures consistency and transparency in documenting architectural decisions.
+* The repository includes a template file `docs/decisions/adr-template.md` for creating new ADRs.
+* There is also a short form template `docs/decisions/adr-short-template.md` for simpler decisions.
+
+## Benefits of Using ADRs in Software Projects
+
+* ADRs provide a structured way to document significant architectural decisions, ensuring that the reasoning behind decisions is clear and accessible.
+* They help maintain a historical record of decisions, making it easier to understand the evolution of the project's architecture.
+* ADRs promote transparency and collaboration among team members, as decisions are documented and shared openly.
+* They facilitate better communication and understanding among team members, especially when new members join the project.
+* ADRs can serve as a reference for future decision-making, helping to avoid repeating past mistakes and ensuring consistency in the project's architecture.
+* They provide a way to capture the context and problem statement for each decision, making it easier to understand the rationale behind the choices made.
+* ADRs can help in identifying and evaluating alternative solutions, ensuring that the best possible decision is made based on the available information.
+* They support the use of templates, such as the MADR template, which ensures consistency and completeness in documenting decisions.
+* ADRs can be easily integrated into version control systems, making them accessible and maintainable alongside the project's codebase.
+* They help in managing technical debt by providing a clear record of decisions that may need to be revisited or revised in the future.

docs/decisions/adr-short-template.md

@@ -23,6 +23,8 @@ You may want to articulate the problem in form of a question and add links to co
 - {decision driver 2, e.g., a force, facing concern, …}
 - … <!-- numbers of drivers can vary -->
 
+* It is important to list decision drivers to provide context and rationale for the decision.
+
 ## Considered Options
 
 - {title of option 1}
@@ -34,3 +36,7 @@ You may want to articulate the problem in form of a question and add links to co
 
 Chosen option: "{title of option 1}", because
 {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.
+
+## Validation
+
+{describe how the implementation of/compliance with the ADR is validated. E.g., by a review or an ArchUnit test}

docs/decisions/adr-template.md

@@ -23,6 +23,9 @@ You may want to articulate the problem in form of a question and add links to co
 - {decision driver 2, e.g., a force, facing concern, …}
 - … <!-- numbers of drivers can vary -->
 
+<!-- Pcb12 -->
+* It is important to list decision drivers to provide context and rationale for the decision.
+
 ## Considered Options
 
 - {title of option 1}
@@ -49,7 +52,7 @@ Chosen option: "{title of option 1}", because
 
 {describe how the implementation of/compliance with the ADR is validated. E.g., by a review or an ArchUnit test}
 
-<!-- This is an optional element. Feel free to remove. -->
+<!-- Pd9ba -->
 
 ## Pros and Cons of the Options