To make sure I create the most relevant and comprehensive planning document for you, could you please confirm a few details:

1. Which specific tools and languages are your primary focus? You’ve mentioned Azure Bicep, Terraform, Ansible, and PowerShell — are all equally important?
2. Are you using GitHub Copilot Chat in a team setting, or just for yourself?
3. Do you want the output to include sample templates (for documents like Architecture, Runbooks, ToDo lists, etc.) or just the structure/standards and folder layout?
4. Are there any specific compliance standards (e.g., ISO, NIST, CIS) you want to align your documentation and repo structure with?

Once I have this, I can proceed with the detailed planning document for ChatMode, prompts, and instruction files.

My answers to GPT-4.5’s questions:

1. The only other tools we would use is azure cli. arm would be included but not focused on.
2. I am using Github copilot chat for myself right now, but this may be something for the entire team.
3. No samples right now.
4. No compliance requirements right now. just waf and caf if possible.

Great, I’ll prepare a detailed planning document that defines and distinguishes ChatMode, Prompt, and Instruction files for GitHub Copilot Chat, aligned for an Azure Architect and Hybrid Expert use case. This will include guidance on best practices and complementarity, project and document structure, tools required (Azure CLI, Bicep, Terraform, Ansible), and recommendations for VS Code configuration.

I’ll also include document formatting standards, inventory tracking, and operational/deployment doc planning with Microsoft CAF and WAF guidance in mind. I’ll let you know when it’s ready for your review.

Thanks! I’ll now create a comprehensive planning document tailored for an Azure-focused GitHub Copilot Chat setup. This will cover ChatMode, Prompt, and Instruction file design, explain how they complement each other, and include supporting repo and document structures, tooling, VS Code configurations, and inventories. I’ll let you know as soon as it’s ready.

Configuring GitHub Copilot Chat for Azure IaC – Planning Document

1. Chat Modes, Prompt Files, and Instruction Files in Copilot Chat

Chat Modes in GitHub Copilot Chat

Chat Modes are predefined configurations that tailor the Copilot Chat’s behavior for specific tasks. VS Code includes three built-in modes – Ask, Edit, and Agent – each optimized for a use case (asking questions, making code edits, or autonomous multi-file changes). In Ask mode, Copilot Chat focuses on answering questions or explaining code; Edit mode applies code changes directly in your editor; Agent mode can perform broader tasks, potentially running CLI commands and editing multiple files autonomously. You can also define custom chat modes by creating a <name>.chatmode.md file with a YAML front matter and instruction body. This allows setting a mode description, selecting tools (e.g. code search, terminal, or Microsoft Docs search via MCP), and even a specific AI model. The body of a custom chat mode contains mode-specific instructions or behavior guidelines. By switching to a custom mode in the VS Code Chat view, you activate those instructions and tool configurations without re-entering them each time. In summary, Chat Modes provide a higher-level context or persona for Copilot Chat, controlling which tools and approach the AI uses for a given session.

Prompt Files (.prompt.md)

Prompt Files are reusable chat prompts stored as Markdown files (with a .prompt.md extension) that encapsulate instructions for a specific task or query. Think of a prompt file as a saved query or script for Copilot Chat – for example, a prompt file could contain instructions to “perform a security review of a REST API” or “generate a new React form component,” including step-by-step guidelines or acceptance criteria for that task. You can run a prompt file in chat directly (e.g. by typing / and the prompt name, or via the Chat UI) to have Copilot execute that complex prompt without typing it out each time. Prompt files support an optional YAML front matter to specify metadata like the default chat mode (ask/edit/agent), a target model, or required tools to use when running that prompt. The body of the file contains the actual prompt text (in natural language instructions, potentially with code blocks or lists). Prompt files can also reference other files or instructions – for example, a prompt file for code security review might include a link to an instruction file containing general security best practices, thereby combining common guidelines with the task-specific prompt. In practice, use Prompt Files to capture frequently used queries (like scaffold a project, perform code review, generate IaC boilerplate) so that they can be executed consistently and shared with the team. Unlike chat modes (which set a persistent environment), a prompt file is a one-time conversation starter or task blueprint for Copilot Chat.

Instruction Files (.instructions.md or copilot-instructions.md)

Instruction Files provide custom guidance and context that Copilot Chat will automatically include in its prompts. They serve as persistent project-wide or context-specific instructions (coding style guidelines, naming conventions, project context, etc.) that the AI should follow across all queries. In GitHub Copilot for VS Code, an instruction file is a Markdown file (with .instructions.md suffix) typically stored in the .github/instructions/ folder of the repository (for workspace-scoped instructions) or in a user’s VS Code profile (for global reuse). Each instructions file can contain a YAML header where you can set an applyTo glob pattern – for example, applyTo: "**" would apply the instructions to all files/requests in this repo, or you could scope instructions to only certain file paths (e.g. only apply certain guidelines to .bicep files). The body of an instruction file is a series of statements or rules that Copilot should adhere to. For instance, a repository instruction file might say: “Use PascalCase for Bicep resource names” or “Always use Azure CLI for examples, not Azure PowerShell”. These instructions are automatically prepended to Copilot Chat requests (when matching the scope) so that the assistant’s answers align with the project’s standards. In GitHub’s terminology, a single repository-wide instructions file (.github/copilot-instructions.md) can cover general practices for the whole project. VS Code’s newer implementation also allows multiple granular instruction files. In short, Instruction Files provide persistent background knowledge or style rules, whereas prompt files are active queries and chat modes are situational configurations.

Use Cases, Overlaps, and How They Work Together

All three customization mechanisms – chat modes, prompt files, and instruction files – complement each other to enhance Copilot Chat:

• Use Cases: Chat modes are ideal for mode-switching the AI’s role (e.g. a “Planning” mode vs. a “Coding” mode). Prompt files are ideal for repetitive tasks or complex queries, allowing one-click execution of a well-crafted prompt (e.g. “Generate Terraform module documentation”). Instruction files are ideal for enforcing standards or injecting domain knowledge (e.g. coding conventions, preferred tools) into every response.

• Overlaps: All three use Markdown and can include instructions for Copilot. In fact, custom chat modes often reference instruction files in their body, and prompt files can include links to instructions files as well. For example, a custom “Azure Architecture Advisor” chat mode might specify a set of tools (like the Microsoft Docs search tool) and include instructions to always follow Azure Well-Architected Framework pillars when giving advice – effectively overlapping with what could also be an instruction file. Prompt files can also link to other prompt files, enabling a hierarchy of reusability.

• Key Differences: Scope & Persistence – Instruction files are always-on (persistent) context (either globally or when applicable by file pattern), whereas prompt files are invoked on demand for a specific chat session. Chat modes persist until you switch mode, affecting all interactions in that mode, and can automatically bring in relevant tools/instructions in that context. Content vs Configuration – Prompt files and instruction files focus on content of prompts (what to ask or what guidelines to follow), whereas chat modes are a higher-level configuration (they can bundle content and tool choices and even model selection). Granularity – Prompt files are typically task-level (you might have many prompt files for different tasks), instruction files tend to be broader (a few files covering coding standards or specific frameworks), and chat modes are few and broad (you likely have just a handful of modes like default, planning, troubleshooting, etc.).

Working Together: These features can be combined for maximum effect. For instance, you might switch Copilot Chat into a custom “DevOps Advisor” mode which loads an instruction file of CI/CD best practices and enables the azureCLI tool, then run a “Review Terraform Plan” prompt file that uses that context. The instruction file ensures the AI’s recommendations follow your organization’s standards, the prompt file ensures the query is well-structured, and the chat mode makes sure the right tools (like documentation search or terminal access) are available. When used together thoughtfully, Chat Modes, Prompt Files, and Instruction Files create a powerful, context-rich Copilot Chat experience tailored to your Azure environment.

2. Project Repository Design and Structure

A well-structured repository is key for scaling and maintaining Infrastructure-as-Code projects. Below is a recommended repository layout, using clearly separated folders for different purposes:

Best Practices for IaC Repos: In designing this structure, adhere to infrastructure-as-code repository best practices:

• Separation of Concerns: Keep modules and reusable components (libraries of IaC code) separate from environment-specific instantiations. For example, Bicep modules can live under src/bicep/modules/ and be referenced by environment-specific Bicep files in project/dev/ or similar. Terraform similarly should use modules to avoid duplicate code. Ansible should use roles for reusability. This modular approach makes deployments more extendable.
• Environment Consistency: Use the same structure for each environment to avoid drift. As noted, a pattern is to have parallel folders for dev, stage, prod with analogous files, making promotion of changes straightforward. Alternatively, use a single source with parameter switching, but still validate each environment’s config.
• Idempotence and State Management: Ensure that running deployments from this repo is idempotent – the same code and config should produce the same result every time (barring intentional changes). For Terraform, store state files remotely (e.g., in Azure storage) and document the backend config; for Bicep, rely on ARM’s idempotent deployment nature and use what-if or deployment scripts; for Ansible, design playbooks to handle repeated runs gracefully.
• Consistency in Naming/Tagging: Adopt a naming convention (possibly from Azure CAF) for resources and ensure variables/inputs follow a consistent style. This could be enforced via linting or manual code reviews. Keep naming conventions documented (possibly in an instruction file for Copilot to learn).
• Use of CI/CD: The repo layout should support automated pipelines. For example, each push triggers validations: lint the code, run bicep build to catch syntax errors, terraform validate/plan on Terraform code, and ansible-lint for Ansible. Integrate security scanning tools like Checkov/Snyk for IaC scanning and PSRule for Azure for Bicep to catch policy violations. Automate these in pipeline so that repository always maintains compliance and quality checks.
• Documentation in Code: Encourage including README.md files in various subfolders (src/bicep/README.md describing module usage, etc.). This helps team members understand each part of the repo in context. Also consider a root README.md that provides an overview and links to key docs in docs/.

By following this structure and practices, the repository will be scalable (easy to extend for new projects or environments), maintainable, and clear for any Azure Architect or team member to navigate.

3. Documentation Standards and Formatting

Clear and standardized documentation is crucial for team-wide use. We will establish a consistent Markdown documentation format for all files in docs/ (and elsewhere) to ensure readability and easy navigation. Key standards include:

• YAML Front Matter (Metadata Header): Every Markdown documentation file should begin with a YAML front matter block delineated by --- lines. This block contains metadata such as title, description, author, creation date, version, and tags. For example:

  ---
  title: "Deployment Runbook - Azure Networking Hub"
  description: "Step-by-step deployment guide for the hub virtual network and its components."
  author: "Jane Doe"
  lastUpdated: "2025-07-10"
  version: "1.3"
  tags: ["networking","runbook","hub-spoke"]
  ---
  

  Including this at the top provides a quick overview and is useful if we publish the docs or use tools that harvest metadata. (In some systems like DocFX or MkDocs, this metadata can drive indexes and search.) At minimum, title, date/lastUpdated, and version should be present.

• Document Header Section: After the front matter, each document should have a top section that acts as an in-document header. This typically includes:

  • Title Heading (#): A human-friendly title of the document (which should match the title in metadata).
  • Badges: Small informative badges providing at-a-glance info. For instance, a badge for build status, last updated, or intended audience. Badges (often from services like Shields.io) can be embedded as images with links. Example: ![Build Status](https://img.shields.io/github/actions/workflow/status/YourOrg/Repo/deploy.yml?branch=main) Badges offer a quick visual summary and can serve as quick links (many are clickable). Choose badges that make sense for documentation – e.g., a “Docs version” badge or a badge linking to latest release. Keep them tastefully minimal to avoid clutter.
  • Quick Links / Table of Contents: If a document is lengthy (like a deployment guide with multiple sections), include a “Quick Links” or mini table of contents. This could be a bulleted list of anchor links to major sections in the doc (using [Section Name](#section-anchor) syntax). For example: “Quick Links: Prerequisites • Deployment Steps • Rollback”. This helps readers jump directly to relevant sections and scan content quickly.

• Body Content with Clear Headings: Use a logical hierarchy of Markdown headings for the content. Primary sections should be H2 (##) headings (e.g., ## Prerequisites, ## Architecture Overview), with sub-sections as H3 (###), and so on. Each document should follow a predictable flow; for instance, a design document might have sections for Overview, Assumptions, Design Details, Trade-offs, Conclusion. A runbook might have Prerequisites, Procedure, Verification, Troubleshooting. Keep paragraphs concise (around 3-5 sentences) and use lists or tables to break up complex information. This planning document itself follows that approach (note the use of bullet points and short paragraphs for readability).

• Document Footer Section: Conclude each document with a consistent footer. This typically includes:

  • References or Footnotes: If the document cites external sources or has footnotes, list them at the bottom under a References heading. In our case, we use the citation format 【source†Lx-Ly】 to refer to external material, and those will be listed as endnotes or reference links (as you see at the end of this document). Ensure any such references are enumerated or linked for transparency.
  • Version Block / Change Log: A small section indicating the document version and change history. For example: Version 1.3 – Updated on 2025-07-10 by J.Doe to add Terraform section. Version 1.2 – Initial draft on 2025-06-01. This can also be presented as a table (Date, Version, Changes, Author).
  • Optionally, Related Documents: e.g., “See also: Architecture Diagram, Operational Runbook”. This cross-references other relevant docs for easy navigation.

• Styling and Formatting Rules:

  • Use consistent terminology. For example, if referring to Azure resources, use official names (e.g. “Azure Virtual Network (VNet)”). If abbreviations are used, define them.
  • When describing code or CLI commands in docs, use code fences or inline code formatting. E.g., `az deployment group create` for CLI, or multi-line fenced blocks for longer scripts.
  • Prefer tables for presenting structured data (like comparison of options, environment configurations), as they are easier to scan than prose.
  • Admonitions/Notes: If a point is important, consider using a call-out. In markdown, we might not have built-in admonitions unless using a converter, but you can simulate by emphasizing “Note:” or using blockquotes for tips. (If we adopt a system like DocFX or MkDocs later, we can use their admonition syntax for notes, tips, warnings, etc..)
  • Ensure cross-references within and between documents use consistent link text. For example, always refer to the “Document Inventory” by that exact name and link to its section or file so readers can find it.

By enforcing these documentation standards, we will have uniform, professional, and easy-to-read docs. This consistency helps new team members quickly get up to speed and ensures that even as the documentation grows, it remains navigable. All template or boilerplate files for documentation (like a doc template with pre-filled front matter and headers) should be stored (perhaps in docs/templates/ or similar) to encourage their usage. Our goal is that any document opened by a reader immediately provides context (via front matter and header), is easy to scan (thanks to headings and quick links), and is easy to trust (with version info and references clearly provided).

4. Inventory Tracking for Documents and Scripts

To maintain clarity as the repository grows, we will implement two “inventory” indexes: one for documentation and one for scripts/IaC components. These serve as living catalogs so anyone can discover resources in the repo and understand their purpose at a glance.

Document Inventory

We will create a Document Inventory (likely as a Markdown file, e.g. docs/Inventory.md or in the repository README) that lists all documentation files along with key metadata. Each entry (row) in this inventory will include: Filename, Path, Tags/Keywords, Category, and Subcategory. This structured list makes it easy to search for docs by topic or type.

For example, the inventory might look like:

How to use it: The Category column groups documents into high-level areas (e.g. Architecture, Operations, Standards, How-to Guides, etc.), while Subcategory refines that (for instance, under Operations you might have Deployment Guides, Day-2 Procedures, Incident Response, etc.). Tags/Keywords provide free-form descriptors that help with search – e.g., one might quickly search the inventory for “Bicep” and find all docs tagged with Bicep (perhaps design decisions involving Bicep modules, etc.). We will update this inventory each time a new doc is added or an existing doc is renamed, ensuring it remains the go-to index of documentation. This also doubles as a lightweight documentation Table of Contents. (Automation Tip: We could enforce via PR checklist that any new Markdown file is added to the inventory, and possibly use a script to validate that all docs are listed.)

Script Inventory

Similarly, a Script Inventory (e.g. docs/ScriptInventory.md or part of the main README) will track all significant scripts and infrastructure code files, especially entry points and modules. Given that our repository includes multiple IaC languages and possibly utility scripts, this inventory focuses on what each script is and why it exists. We will list: Script Name, Language/Type, Location (Path), and Purpose/Description. Group the scripts by language or tool for clarity.

Example snippet of the Script Inventory:

In this table, Language/Type can be categories like PowerShell, Bicep, Terraform, Ansible, Azure CLI, etc., so one can scan for all scripts of a certain kind. The Purpose field should be a concise one-liner explaining what that script or IaC file does. This is especially useful when there are many modules – e.g., multiple Bicep files – so you don’t have to open each to know which one to use or edit. The Script Inventory is also useful for new team members to discover where particular functionality resides (e.g., “Where is the code that sets up monitoring?” – a quick look at inventory might point to monitoring.bicep or an Ansible role).

We will keep this Script Inventory updated as new scripts or modules are added. Again, we can automate the detection of new .ps1, .bicep, .tf, .yml files and prompt to update the inventory. Over time, this becomes a high-level map of the codebase’s capabilities.

Both the Document and Script inventories contribute to operational efficiency: they reduce the time to find information or code, and they act as a form of documentation themselves. They should be easily accessible (linked from the main README or docs index).

5. Tooling and Best Practices for Azure & Hybrid Cloud Development

To maximize productivity and ensure best practices, we recommend a set of tools, VS Code extensions, and frameworks to incorporate into this workflow, along with aligning to industry frameworks (CAF/WAF) for high-quality architecture:

• Azure CLI: The Azure CLI is essential for scripting and interactive work in a hybrid cloud environment. Ensure Azure CLI is installed and available for Copilot Chat (so that Copilot’s suggestions or agent mode can actually run Azure CLI commands when needed). We also recommend the Azure CLI Tools extension for VS Code, which provides features like CLI command autocomplete, syntax highlighting for .azcli files, and easy Azure login integration within VS Code. Azure CLI will be used in runbooks and scripts – for example, deploying Bicep templates (az deployment group create ...) or querying resources. Encourage using Azure CLI in scripts over manual portal steps to maintain IaC principles even for administrative tasks.

• VS Code Extensions for IaC: A number of extensions will make editing and maintaining IaC code easier:

  • Bicep – Install the Bicep VS Code extension (for language support, intellisense, ARM template export, etc.).
  • Terraform – Install HashiCorp Terraform extension (enables Terraform syntax highlighting, validation, snippet support).
  • Ansible – Install Ansible extension (for YAML syntax, schema validation of playbooks, etc.).
  • PowerShell – Install PowerShell extension if using PowerShell scripts, for proper script editing and PSScriptAnalyzer integration.
  • Azure Tools – The Azure Tools Extension Pack is a convenient bundle which includes Azure Resource Manager tools, Azure CLI, Azure Policy, etc., that an Azure architect often uses.
  • GitHub Copilot – Obviously, ensure GitHub Copilot Chat extension is installed and enabled. Also consider the GitHub Copilot Labs extension if available, which sometimes offers experimental features that could assist in code translation or brushes.

• Microsoft CAF (Cloud Adoption Framework) and WAF (Well-Architected Framework): These frameworks provide best practice guidance for Azure architectures. We recommend aligning our project with CAF for organizational standards (resource group structure, naming conventions, tagging, management group hierarchy if enterprise scale is needed) and using WAF’s pillars (Security, Reliability, Performance, Cost, Operational Excellence) as a guiding checklist for both design and implementation. Practically, this means:

  • Following Azure CAF naming conventions for resources (we can incorporate the official CAF naming tool or reference in instructions so Copilot suggests correct names).
  • Using CAF’s Enterprise-Scale Landing Zone principles if applicable (for example, hub-and-spoke network architecture, which we are using, is part of those best practices).
  • Using WAF checklists during design reviews – perhaps maintaining a document that maps our implementation to WAF pillars to ensure nothing is overlooked (e.g., have we enabled diagnostics logs for resources? That’s operational excellence and reliability).
  • These frameworks can be included in Copilot’s context via instruction files. For instance, an instruction file might remind Copilot: “Always consider the Azure Well-Architected pillars when suggesting solutions, and prefer solutions that align with CAF best practices (e.g., use resource tags, treat security as code).”
  • Tools: Microsoft provides a CAF Terraform module and Bicep modules (the “AzResources” module library). We could leverage those as submodules or references if appropriate, rather than reinventing baseline definitions. For example, use the CAF Terraform module for Azure naming and tagging strategy.
  • Additionally, consider the Azure Well-Architected Review tool (in Azure portal or as guidance) as something we do periodically on our environment.

• Microsoft Docs/MCP (Model Content/Context Protocol): To boost our Copilot Chat’s knowledge, we can integrate the Microsoft Docs MCP server tool. This is effectively an AI-accessible index of official Microsoft documentation (Learn content). In VS Code Copilot Chat, enabling the Docs tool (often called microsoft.docs.mcp in the tools list) allows the AI to fetch up-to-date Azure documentation or examples on command. We strongly recommend enabling this, especially in Agent mode or custom modes, so that Copilot can directly reference Azure documentation (for example, if you ask, “What does this Azure CLI command do?” it can pull the explanation from MS Docs). This results in more accurate and trustworthy answers. From a setup perspective, ensure the setting for MCP (if any) is enabled, and that internet access for Copilot is allowed in your environment (some enterprise settings might restrict it).

• IaC Best Practice Tools: Incorporate linters, security scanners, and test frameworks into your workflow:

  • Linting: Use Terraform TFLint (with the Azure ruleset) to catch common Terraform issues, ansible-lint for Ansible playbooks (to enforce YAML formatting and best practices), and the built-in bicep build/bicep lint for Bicep. Microsoft’s PSRule for Azure can lint ARM/Bicep deployments against Azure governance rules. These tools can run in pre-commit hooks or CI pipelines to enforce standards.
  • Security Scanning: Use Checkov or Terrascan for static analysis of Terraform and Bicep (Checkov has some Azure policy rules). Enable Credential Detections (like GitHub’s secret scanning or pre-commit hooks) to ensure no secrets in scripts.
  • Testing Frameworks: For complex scenarios, use Terratest (Go) or Azure CLI Script Testing to validate that infrastructure comes up as expected. Ansible roles can be tested with Molecule in conjunction with containers or VMs to simulate the playbook execution.
  • Pipeline Integration: As mentioned, integrate these into CI. For example, a GitHub Actions workflow can run: terraform fmt -check (for formatting), terraform plan (to detect any changes), tflint, bicep build (which acts as validation), psrule (for Bicep), ansible-lint, etc. This automation ensures continuous compliance with best practices – developers get immediate feedback if something is off-standard.

• Collaboration and Repository Tools: If working with a team, leverage:

  • GitHub or Azure DevOps Pull Request templates to remind authors to update docs and inventories with each change.
  • Pre-commit hooks (via a tool like pre-commit) to auto-run markdownlint on docs, format code, etc., before commits.
  • Visual Studio Code Profiles/Workspaces – Create a recommended VS Code Workspace file for the project that opens the relevant folders and perhaps defines some workspace-specific settings (like default shell, or path mappings). A profile can be exported that includes the extension recommendations for this project. This can be shared (document the steps to import it) so every team member’s VS Code is set up consistently.

By using these tools and adhering to best practices, the team will maintain high quality in both the code and the architecture. The combination of automation (linting, scanning), guidance (CAF/WAF), and Copilot’s AI (with custom instructions and access to Microsoft’s documentation) will greatly enhance productivity while ensuring that the solutions are robust and secure. For instance, a developer writing a Terraform script can get immediate suggestions from Copilot that are security-conscious (thanks to our instructions and tools) and then have their code automatically checked by TFLint and Checkov in a pull request – a comprehensive safety net.

6. VS Code Configuration for Copilot Chat & Azure IaC

Optimizing Visual Studio Code for GitHub Copilot Chat in an Azure IaC context involves tweaking both workspace settings and user profile settings. Our goal is to ensure Copilot Chat is context-aware of our project (IaC files, Azure terminology) and that VS Code is equipped to make the most of it.

Here are recommended configurations and files to add/edit:

• Enable Experimental Features: In VS Code’s settings (settings.json), make sure to enable the Copilot Chat experimental features for prompt/instructions files and custom modes. Specifically:

  • "github.copilot.chat.enable": true – (If not enabled by default) ensure the chat extension is active.

  • "chat.promptFiles": true – Enable support for prompt files and instruction files (this setting may be under an experimental flag as of VS Code 1.101+). This allows VS Code to recognize .prompt.md and .instructions.md files and provide the UI to manage them.

  • "chat.promptFilesLocations" – If we decide to store prompt files in a different path than the default .github/prompts, configure it here. By default, VS Code looks in .github/prompts for workspace prompt files and .github/instructions for instruction files, but if our repo uses docs/prompts/ for instance, set:

    "chat.promptFilesLocations": {
        "docs/prompts": true,
        ".github/prompts": false
    }
    

    to point the extension to the right location.

  • "chat.modeFilesLocations" – Similar concept for custom chat modes. By default .github/chatmodes is scanned. If we use that (likely yes), we might not need to change it. Just be aware of it if we want to store modes elsewhere.

  • "github.copilot.chat.codeGeneration.useInstructionFiles": true – This ensures that the Copilot code generation features (like suggestions and completions, not just chat) also respect the repository instruction file. It basically ties in .github/copilot-instructions.md to the inline suggestions as well.

  • Profiles: Encourage team members to use a VS Code Profile dedicated to Azure IaC work. This profile can have the above settings and all recommended extensions pre-installed. We can export a profile (VS Code has an export profile feature) and include instructions in the docs on how to import it. The profile ensures a consistent environment across the team.

• Workspace Recommendations: Create a .vscode/extensions.json file in the repo that lists recommended extensions (as discussed in section 5, like Bicep, Terraform, Ansible, Copilot, Azure Tools). VS Code will prompt users to install these when they open the workspace. Also, a .vscode/settings.json can be added to source control with workspace-scoped settings: e.g.,

  {
    "[bicep]": { "editor.tabSize": 2 },
    "files.exclude": {
        "node_modules": true
     },
    "editor.formatOnSave": true,
    "terminal.integrated.defaultProfile.windows": "PowerShell"
  }
  

  and importantly the Copilot Chat settings as mentioned. However, be cautious with workspace settings – if any contain user-specific info (like paths or credentials), those should not be committed.

• GitHub Copilot Chat Specific Config: We should add the custom files to the repository so that everyone benefits:

  • .github/copilot-instructions.md – This is the repository custom instructions file (global for the repo). Ours will contain the key guidelines (naming conventions, tool preferences, etc. as discussed). We already saw an example: e.g., instruct Copilot about using double quotes in JSON, or always using Azure CLI over Azure PowerShell. Once this file is present, Copilot Chat will load it automatically for all users in this repo. (Ensure each developer has not disabled repository instructions in their settings.)
  • .github/prompts/ – Create this directory and add any prepared prompt files (like security-review.prompt.md, scaffold-bicep-module.prompt.md, etc.). Having them in the repo means they are workspace prompt files accessible to all. Team members can invoke them via the chat interface dropdown or by / command. We might also include a README in that folder listing what prompt files are available and their purpose.
  • .github/chatmodes/ – If we develop custom chat modes (for example, a mode that has tools for running Terraform commands and instructions like “You are a Terraform Assistant…”), those .chatmode.md files can live here so the whole team can use them. For instance, a planning.chatmode.md as per the earlier example. Once stored here, any team member’s VS Code should detect the custom mode (especially if they have the chat.promptFiles experimental feature on).
  • Note: The .github folder is a conventional place for such files, and by using it we avoid cluttering the root. It also aligns with GitHub’s expectations for the instructions file name and location.

• User Settings Sync: Advise enabling Settings Sync for VS Code, which can sync extensions, settings, and even prompt/instruction files across devices. For instance, if a user creates a useful prompt file in their profile, they can contribute it to workspace if general. But at minimum, syncing ensures their Copilot customizations follow them. We might also set up Enterprise policy to enable prompt/instruction features for all developers (if using VS Code in enterprise environment).

• Terminal and CLI Integration: In the context of Copilot Chat’s agent mode, it can execute terminal commands. Ensure the VS Code terminal is configured in a comfortable way: e.g., default profile to bash (for Unix) or PowerShell (for Windows) depending on team preference. That way, any /terminal commands executed by Copilot (like running az cli or terraform plan) will use the correct shell. This can be set in the workspace settings (as shown in example above for Windows). Also, make sure the required CLI tools (Azure CLI, Terraform, Ansible if needed, Bicep CLI – note Bicep CLI is bundled with Azure CLI now as az bicep) are installed on developer machines or devcontainers.

• DevContainer (Optional): If the team is open to using Docker Dev Containers or Codespaces, we could configure a .devcontainer that has all tools and the VS Code settings baked in. This is a bit beyond the scope, but it’s worth mentioning as a future optimization.

In summary, by configuring VS Code with these settings and including the .github custom Copilot files, we create a smart IDE environment: Copilot Chat will automatically consider our coding standards (via instruction file), we can easily invoke prepared prompts, and even switch among custom chat modes for different tasks. Each team member opening the repository in VS Code gets a ready-to-use setup with minimal manual configuration. We will document these setup steps in the repository README (e.g., “Upon first open, accept installing recommended extensions. Ensure Copilot is logged in…” etc.) to make onboarding smooth.

7. Additional Guidance for Simplicity and Operational Efficiency

As we implement the above, here are additional suggestions to keep our workflows simple yet effective, and our documentation lean but technically deep:

• Focus on “Day 2” from Day 1: Beyond initial deployment, think about operability. We should create Runbooks for common Day-2 operations (scaling, patching, recovering from issues). These can be simple step-by-step guides (possibly in the docs/runbooks/ folder) that assume the infrastructure is deployed and explain how to perform changes or maintenance. For example, a runbook on “How to rotate secrets for the application” or “How to fail over the database to DR”. Having these in place (and keeping them updated as architecture evolves) greatly eases operational burden. Copilot can assist in writing these, but they should be reviewed by SMEs for accuracy.

• Minimal but Comprehensive Documentation: Aim for a single source of truth for each topic. Avoid duplicating information across multiple documents. For instance, if our architecture diagram is documented in an Architecture doc, the runbook should refer to it rather than re-explaining the whole architecture. This prevents divergence. The Document Inventory will help identify if two docs overlap in content. If something feels redundant, consider merging them or clearly delineating their scopes. Each doc should have a clear purpose: if a topic doesn’t fit, it might belong in a different doc.

• Use Templates and Automation to Keep Docs Updated: Use the front matter metadata (version, lastUpdated) diligently. Perhaps implement a simple script to update the lastUpdated field on docs when they’re modified (could be a git pre-commit hook or part of PR review to encourage authors to bump the date). This way readers know how fresh the information is. Additionally, consider generating certain documentation from code when possible. For example, if we tag resources with certain metadata, maybe generate an inventory of resources or a network diagram automatically. The article on automating Azure documentation with an AI assistant shows how ARM templates could be summarized to Markdown. In our case, we might not automate that fully yet, but it’s a future possibility.

• Architecture Templates & Diagrams: Provide high-level reference architecture templates. These could be visual diagrams (stored in docs/architecture/ as images or draw.io files) illustrating the deployment. They help new joiners and also serve as a communication tool with stakeholders. Additionally, if we have recurring patterns (like a template for a new microservice environment), document those as templates (possibly as additional prompt files for Copilot Chat – e.g., a prompt file that generates a boilerplate Bicep for a standard web app + DB pattern). This bridges design and implementation nicely.

• Operational Efficiency: Embrace infrastructure pipelines to automate everything possible. For example, incorporate a deployment script or pipeline that can deploy the entire stack in one go (for new environments) and document the usage in a quick-start guide. This lowers the bar for spinning up test environments (which is good for experimenting or disaster recovery drills). Maintain a small “operations README” that describes how to do common tasks like deployments, rollbacks, and environment creation in a concise way (with links to detailed runbooks if needed). In other words, provide a TL;DR for operators, with deeper documentation as backup.

• Review and Prune Documentation Regularly: Set a cadence (perhaps every major release or quarterly) to review docs for relevance. Remove or archive outdated docs (but don’t throw them away—maybe keep an /archive folder if needed). This keeps the documentation corpus lean. If using our Document Inventory table, add a status field or a tag for deprecated docs to clearly mark them.

• Leverage Copilot for Documentation but Verify: Copilot (and other AI) can be a great assistant in writing and updating docs – for example, generating a draft from a set of bullet points. Continue to use it to maintain technical depth (it can quickly insert Azure CLI command examples or architecture descriptions), but always review for accuracy. Encourage team members to actually test any code snippet in docs (so our runbook steps are verified).

• Knowledge Sharing Culture: Encourage the team to contribute tips and improvements. Maybe maintain a docs/tips.md for quick gists (like “How to quickly find out which Terraform version is used” or “Handy Azure CLI one-liners”). These can later be formalized into docs or just serve as a living cheat-sheet. This keeps knowledge from being lost and fosters collaboration.

By following these suggestions, we ensure that our configuration of Copilot Chat and our overall project documentation remain effective and manageable over the long term. The philosophy is simplicity in processes (so they’re easy to follow, reducing errors), while not sacrificing technical depth (so all important details are captured somewhere accessible). We want just enough documentation to cover our needs – no more, no less – and the right tools and automations in place to reduce manual toil (both in deployments and in writing docs).

Finally, remember that this is a living plan. As Copilot Chat evolves (it’s a relatively new tech) and as our project grows, we’ll iterate on these practices. Regular retrospectives on “what’s working or not” with Copilot and our repo structure will allow us to adjust this plan for continuous improvement. With this plan as a baseline, our Azure Architect and team can confidently onboard GitHub Copilot Chat into daily workflows, knowing it’s configured with guardrails and aligned to our hybrid cloud infrastructure needs.

References:

1. Visual Studio Code Docs – Chat modes in VS Code
2. Visual Studio Code Docs – Custom chat modes and configuration
3. Visual Studio Code Docs – Prompt files (experimental) overview
4. Visual Studio Code Docs – Prompt file structure and examples
5. Visual Studio Code Docs – Instruction files structure
6. GitHub Docs – Repository custom instructions vs. prompt files
7. Microsoft ISE DevBlog – Best practices for IaC – consistency, idempotency, modularity
8. Microsoft ISE DevBlog – Testing and linting in IaC pipelines
9. Daily.dev Blog – GitHub Markdown Badges Explained (use of badges for quick info)
10. Microsoft TechCommunity – Microsoft Docs MCP introduction (Copilot integration with MS Docs)

Of course. GitHub Copilot Chat’s customization features—instruction, prompt, and chatmode files—are powerful tools for tailoring its behavior to your specific project needs. They work together to create a highly specialized and efficient assistant.

Here’s a detailed plan to configure Copilot Chat for your Azure-focused projects, incorporating your requirements for project management, documentation, and IaC best practices.

Understanding Copilot Customization Files

These three file types allow you to control Copilot’s responses, from setting broad ground rules to creating shortcuts for specific, repetitive tasks. They all live within the .github/copilot/ directory in your repository’s root.

In short:

• Use instruction for global, always-on rules for your repo.
• Use prompt for quick, one-off commands.
• Use chatmode to have a dedicated conversation with a specialized expert persona.

The Master Plan: A Unified Strategy for Azure Architecture

This plan aligns all three file types to enforce your standards consistently.

1. The Foundation: The @workspace Instruction File

This is the most important file. It sets the ground rules for everything Copilot does in your repository.

File Location: .github/copilot/instruction

# Persona and Core Directives
You are an expert assistant for a senior Azure Hybrid Cloud Architect. Your primary goal is to enforce consistency, best practices, and meticulous documentation across this repository.

# Primary Frameworks and Standards
All recommendations, code, and documentation must align with:
1.  **Microsoft Cloud Adoption Framework (CAF)**
2.  **Azure Well-Architected Framework (WAF)**: Prioritize security, reliability, and cost optimization.
3.  **Azure Resource Naming Conventions**: Strictly adhere to the recommended naming and tagging standards.

# Repository Structure
When asked to create files or suggest structure, you must adhere to the following layout:
- `/.github/`: For GitHub-specific files (workflows, issue templates, Copilot configs).
- `/docs/`: All Markdown documentation.
  - `/docs/architecture/`: For high-level design and architecture documents.
  - `/docs/operations/`: For runbooks and day-two operational guides.
  - `/docs/provisioning/`: For deployment steps and "how-to" guides.
  - `/docs/assets/`: For images and other assets.
- `/src/`: All source code and IaC templates.
  - `/src/bicep/`: Bicep modules and main deployment files.
  - `/src/terraform/`: Terraform configurations.
  - `/src/ansible/`: Ansible playbooks and roles.
  - `/src/powershell/`: PowerShell scripts.
- `/config/`: Environment-specific configuration files (e.g., `.tfvars`, `.json`).
- `/tests/`: All test files for code and IaC.
- `/.logs/`: For local log files (should be in .gitignore).
- `/PROJECT_MANAGEMENT/`: For planning documents.

# Documentation Standard (MANDATORY)
All Markdown documents (`.md`) created in the `/docs/` folder MUST follow this exact format.

## Front Matter Header (YAML)
Every document must begin with a YAML front matter block:
```yaml
---
title: "Document Title"
description: "A concise, one-sentence description of the document's content."
author: "TBD"
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
version: "1.0.0"
status: "Draft" # Draft | In Review | Approved | Archived
scope: "TBD" # e.g., "Azure Landing Zone - Identity"
category: "TBD" # Architecture | Operations | Provisioning
subcategory: "TBD" # e.g., Security, Networking, Identity
tags: ["tag1", "tag2"]
keywords: ["keyword1", "keyword2"]
master_reference: "ID or Link to parent doc if any"
badges: ["Azure", "Terraform"]
---
```

## In-Document Header & Footer

Immediately following the front matter, the document body must contain:

**Header:**

  - Badges for category and subcategory.
  - **Reference:** Scope | Category | Version
  - **Purpose:** A clear statement of what this document aims to achieve.
  - **Quick Links:** Links to related documents.

**Footer:**

  - **Cross-Reference:** Links to documents that reference this one.
  - **Version History:** A block detailing changes.

# Inventory Management

When a new document or script is created, you must remind the user to update the corresponding inventory file:

  - **Document Inventory:** `/docs/inventory.md`
  - **Script Inventory:** `/src/inventory.md`

<!-- end list -->

2. Quick Actions: Custom Prompt Files

Create these files to automate your most common tasks.

File Location: .github/copilot/prompts/new-doc.prompt

name: new-doc
description: Creates a new documentation file from our standard template.
prompt: |
  Based on the rules in the @workspace instruction, create a new document for the following topic: {{user_prompt}}.

  - The file should be named appropriately (e.g., `AD-Identity-Services.md`) and placed in the correct subfolder within `/docs/`.
  - The `title` should be "Architecture Design: {{user_prompt}}".
  - Infer the `category`, `subcategory`, `tags`, and `keywords` from the user's prompt.
  - Fill out all mandatory front matter and header/footer sections, using "TBD" for information that requires manual input.
  - Generate a basic outline for the document, including sections like "Overview," "Requirements," "Design Decisions," and "Implementation Details."  

File Location: .github/copilot/prompts/review-iac.prompt

name: review-iac
description: Reviews the selected IaC code for best practices.
prompt: |
  Review the selected code snippet (`{{selection}}`).

  1.  Does it comply with the Azure Well-Architected Framework (specifically security, cost, and reliability)?
  2.  Does it follow Azure naming and tagging conventions as defined in the @workspace context?
  3.  Is the code properly documented with comments explaining its purpose?
  4.  Suggest specific improvements with code examples.  

3. Expert Personas: Custom Chat Mode

Create a dedicated chat mode for deep-dive architectural discussions.

File Location: .github/copilot/chatmodes/azure-architect.chatmode

name: azure-architect
description: Chat with an expert on Azure Architecture, IaC, and Hybrid Cloud.
instructions: |
  You are an expert-level Azure Hybrid Cloud Architect.
  - Your primary sources of information MUST be the official Microsoft Docs, Azure Architecture Center, HashiCorp Learn, and Ansible Documentation.
  - You must strictly adhere to ALL rules defined in the `@workspace` instruction file, especially documentation and repository standards.
  - When providing advice, explicitly reference which WAF pillar (e.g., "For cost optimization, you should...") or CAF principle your recommendation supports.
  - Be proactive. If a user asks for a solution, also mention potential trade-offs, security vulnerabilities, or operational considerations.
  - Always ask clarifying questions to ensure your response is tailored to the specific context of the project (e.g., "Is this for a production or development environment?").  

VS Code and Tooling Configuration

To make this ecosystem work flawlessly, here are the recommended tools and settings.

VS Code Extensions

• GitHub Copilot Chat: The core extension (you already have this).
• Microsoft Docs Authoring Pack: This bundle includes markdownlint to enforce Markdown standards, which you can configure to match your documentation rules.
• Front Matter: A fantastic extension that provides a UI for managing the YAML front matter in your Markdown files, making it easy to update fields like status or version.
• Azure Tools Extension Pack: Essential for working with Azure resources, ARM, and Bicep.
• HashiCorp Terraform: Official extension for Terraform syntax highlighting, validation, and language server.
• Ansible: Provides support for Ansible playbooks.
• GitLens: Supercharges the Git capabilities built into VS Code.

VS Code settings.json

You generally don’t need to edit settings.json for Copilot to find these files, as it automatically looks in .github/copilot/. However, you can configure markdownlint to enforce your standards.

Location: .vscode/settings.json (This creates workspace-specific settings)

{
  // Markdownlint configuration to enforce documentation style
  "markdownlint.config": {
    "default": true,
    "MD041": false, // Allow first line to be a heading (for simple docs)
    "MD033": {
      // Allow specific HTML tags if you use them for badges, etc.
      "allowed_elements": ["img", "a", "p", "div"]
    },
    "MD025": {
      // Allow multiple top-level headings if needed
      "level": 1
    }
  },
  // Recommended file associations
  "files.associations": {
    "*.tfvars": "terraform"
  }
}

I’ll create a comprehensive document that addresses your GitHub Copilot Chat configuration needs and explains the relationships between chatmode, instruction, and prompt files. This will be designed specifically for an Azure architect working with hybrid environments.

I’ve created a comprehensive guide that addresses all your GitHub Copilot Chat configuration needs. Let me walk you through the key concepts and relationships to help you understand how these pieces work together.

The fundamental relationship between the three file types works like layers of a system. Think of chatmode files as establishing the “personality” and core expertise of your AI assistant. This is where you define that Copilot should act as an Azure architect with specific knowledge domains. The chatmode creates the foundational context that influences every interaction.

Instruction files serve as your detailed knowledge base and procedure manual. These contain the comprehensive standards, best practices, and methodologies that Copilot references when providing guidance. They’re like having a library of your organization’s accumulated wisdom that Copilot can draw from. For your Azure work, these would include your architecture standards, documentation requirements, and IaC best practices.

Prompt files are your actionable templates that leverage both the chatmode context and instruction knowledge to produce specific outputs. These are the “quick actions” that help you accomplish repetitive tasks like generating project structures, creating Bicep modules, or producing architecture documents with consistent formatting.

The document I’ve created shows how these three types work together in a hierarchical fashion. The chatmode establishes who Copilot is (an Azure architect), the instructions tell it what standards to follow (your documentation requirements, naming conventions, project structures), and the prompts provide the specific templates for common tasks (creating projects, generating documentation, building infrastructure code).

For your specific needs around project management and documentation, I’ve included a comprehensive document management system that addresses your requirements for headers, footers, document inventory, and script inventory. The system uses YAML front matter to capture all the metadata you specified, including tags, keywords, version information, and cross-references.

The VS Code configuration section shows you exactly which files to modify to integrate this system with your development environment. The workspace settings ensure Copilot has access to your instruction and prompt files, while the extensions configuration sets up the tools you’ll need for Azure development.

One particularly important aspect is the project structure template I’ve included. This creates the well-organized repository structure you need for different types of projects, whether you’re working with Bicep, Terraform, or Ansible. The structure separates concerns clearly while maintaining consistency across projects.

The implementation strategy I’ve outlined provides a phased approach to deploying this system. Starting with the foundation allows you to test the basic functionality before building more sophisticated capabilities. This approach reduces risk and allows you to refine the system based on real-world usage.

Would you like me to elaborate on any specific aspect of this configuration, such as how to create custom MCPs for Microsoft documentation access, or would you prefer to see examples of how these files would work together in a real project scenario?

GitHub Copilot Chat Configuration Guide for Azure Architects

Executive Summary

This document provides a comprehensive guide for configuring GitHub Copilot Chat through chatmode, instruction, and prompt files specifically tailored for Azure architects working with hybrid environments. The configuration focuses on project management excellence, Infrastructure as Code (IaC) best practices, and streamlined documentation workflows.

Understanding the Three File Types

Chatmode Files (.chatmode)

Chatmode files define the behavioral context and personality of your Copilot Chat sessions. Think of them as the “character” or “role” that Copilot assumes during conversations. These files establish the foundational knowledge base, communication style, and domain expertise that Copilot will maintain throughout interactions.

Key Characteristics:

• Define the AI’s persona and expertise level
• Set the knowledge domain and focus areas
• Establish communication patterns and preferences
• Provide context about your working environment

Instruction Files (.md or .txt)

Instruction files contain detailed, structured guidance that Copilot references when performing specific tasks. These are comprehensive reference documents that outline methodologies, standards, and procedures. They serve as the “knowledge base” that informs Copilot’s responses and suggestions.

Key Characteristics:

• Contain detailed procedural knowledge
• Define standards and best practices
• Provide templates and examples
• Reference external documentation and resources

Prompt Files (.md or .txt)

Prompt files are specific, actionable templates that guide Copilot toward producing particular outputs. They contain pre-written prompts with placeholders and structured formats for common tasks. These are the “quick actions” that help you accomplish repetitive tasks efficiently.

Key Characteristics:

• Task-specific templates
• Structured input/output formats
• Reusable prompt patterns
• Context-aware suggestions

File Relationships and Workflow

The three file types work together in a hierarchical relationship:

1. Chatmode establishes the foundational context and expertise level
2. Instructions provide the detailed knowledge and procedures
3. Prompts deliver specific, actionable templates for common tasks

This creates a workflow where Copilot understands your role (chatmode), knows your standards (instructions), and can quickly execute common tasks (prompts).

Azure Architect Chatmode Configuration

Primary Chatmode File: azure-hybrid-architect.chatmode

You are an expert Azure Solutions Architect with deep expertise in hybrid cloud environments. Your knowledge spans:

CORE EXPERTISE:
- Azure infrastructure design and implementation
- Hybrid cloud architectures (Azure Arc, Azure Stack)
- Infrastructure as Code using Bicep, Terraform, and Ansible
- Microsoft Cloud Adoption Framework (CAF) and Well-Architected Framework (WAF)
- Azure resource naming conventions and governance
- GitLab CI/CD integration with Azure DevOps
- Project management for infrastructure projects

COMMUNICATION STYLE:
- Provide technically accurate, implementation-focused responses
- Reference Microsoft documentation and best practices
- Consider hybrid scenarios in all recommendations
- Emphasize security, scalability, and maintainability
- Structure responses with clear next steps

WORKING CONTEXT:
- Primary repository platform: GitHub (with GitLab integration)
- Focus on well-structured project organization
- Emphasis on comprehensive documentation
- Day-2 operations and lifecycle management priority
- Template-driven approach to accelerate delivery

RESPONSE FORMAT:
- Lead with architectural considerations
- Provide code examples with detailed comments
- Reference relevant Microsoft documentation
- Include deployment and testing considerations
- Suggest monitoring and maintenance approaches

Instruction Files Structure

Core Instructions Directory: .copilot/instructions/

1. azure-architecture-standards.md

Contains comprehensive Azure architecture standards including:

• Resource naming conventions following Microsoft CAF
• Network segmentation patterns
• Security baseline configurations
• Governance and compliance requirements
• Performance and scalability guidelines

2. project-structure-standards.md

Defines standardized project organization:

• Repository structure templates
• Documentation hierarchy
• Configuration management patterns
• Testing framework organization
• CI/CD pipeline standards

3. iac-best-practices.md

Infrastructure as Code guidelines covering:

• Bicep module development standards
• Terraform module structure and versioning
• Ansible playbook organization
• Configuration drift prevention
• Testing and validation procedures

4. documentation-standards.md

Document management specifications including:

• Markdown formatting standards
• Required header metadata
• Document classification system
• Cross-reference management
• Version control procedures

Prompt Files Structure

Core Prompts Directory: .copilot/prompts/

Project Management Prompts

create-project-structure.md

Create a complete project structure for a {{PROJECT_TYPE}} project using {{TECHNOLOGY_STACK}}. Include:

1. Root directory structure with all required folders
2. Documentation hierarchy following our standards
3. Configuration management structure
4. Testing framework organization
5. CI/CD pipeline configuration templates
6. Initial README with project overview

Project Context:
- Target Environment: {{ENVIRONMENT}}
- Primary Technologies: {{TECHNOLOGIES}}
- Integration Requirements: {{INTEGRATIONS}}

generate-architecture-doc.md

Generate a comprehensive architecture document for {{PROJECT_NAME}} including:

DOCUMENT STRUCTURE:
- Executive Summary
- Architecture Overview
- Component Details
- Security Considerations
- Deployment Strategy
- Monitoring and Maintenance
- Risk Assessment
- Next Steps

REQUIREMENTS:
- Follow Microsoft WAF principles
- Include hybrid considerations
- Reference CAF patterns
- Provide implementation timeline
- Include cost analysis

Infrastructure Prompts

create-bicep-module.md

Create a Bicep module for {{RESOURCE_TYPE}} with the following specifications:

MODULE REQUIREMENTS:
- Follow Azure naming conventions
- Include comprehensive parameter validation
- Implement proper resource tags
- Include monitoring and diagnostics
- Provide deployment examples
- Include unit tests

CONTEXT:
- Resource Group: {{RESOURCE_GROUP}}
- Environment: {{ENVIRONMENT}}
- Dependencies: {{DEPENDENCIES}}

generate-terraform-module.md

Generate a Terraform module for {{RESOURCE_TYPE}} including:

MODULE STRUCTURE:
- Main configuration (main.tf)
- Variable definitions (variables.tf)
- Output definitions (outputs.tf)
- Provider requirements (versions.tf)
- Example usage (examples/)
- Module documentation (README.md)

REQUIREMENTS:
- Follow Terraform best practices
- Include comprehensive validation
- Implement proper resource lifecycle
- Include testing configuration

create-ansible-playbook.md

Create an Ansible playbook for {{TASK_DESCRIPTION}} with:

PLAYBOOK STRUCTURE:
- Task organization by logical groups
- Proper error handling and rollback
- Idempotent operations
- Comprehensive logging
- Variable management
- Testing tasks

REQUIREMENTS:
- Follow Ansible best practices
- Include molecule testing
- Implement proper handlers
- Include documentation

VS Code Configuration

Workspace Settings (.vscode/settings.json)

{
  "copilot.enable": {
    "*": true,
    "yaml": true,
    "json": true,
    "markdown": true,
    "bicep": true,
    "terraform": true,
    "ansible": true
  },
  "copilot.chat.enableContext": true,
  "copilot.chat.contextFiles": [
    ".copilot/instructions/**/*.md",
    ".copilot/prompts/**/*.md",
    "docs/architecture/**/*.md",
    "docs/standards/**/*.md"
  ],
  "files.associations": {
    "*.chatmode": "plaintext",
    "*.bicep": "bicep",
    "*.tf": "terraform",
    "*.yml": "ansible"
  },
  "yaml.schemas": {
    "https://raw.githubusercontent.com/ansible/ansible-lint/main/src/ansiblelint/schemas/ansible.json": "playbooks/*.yml"
  }
}

User Settings Configuration

{
  "copilot.chat.followUps": "always",
  "copilot.chat.suggestCodeBlocks": true,
  "copilot.chat.experimental.codeActions": true,
  "copilot.enable": {
    "*": true,
    "plaintext": false,
    "markdown": true,
    "scminput": false
  }
}

Extensions Configuration (.vscode/extensions.json)

{
  "recommendations": [
    "github.copilot",
    "github.copilot-chat",
    "ms-azuretools.vscode-bicep",
    "hashicorp.terraform",
    "redhat.vscode-yaml",
    "ms-vscode.azure-account",
    "ms-azuretools.vscode-azureresourcegroups",
    "redhat.ansible",
    "ms-vscode.powershell",
    "ms-azuretools.vscode-azurecli"
  ]
}

Document Management System

Document Header Template

---
title: "{{DOCUMENT_TITLE}}"
document_type: "{{DOCUMENT_TYPE}}"
author: "{{AUTHOR_NAME}}"
created: "{{CREATION_DATE}}"
updated: "{{LAST_UPDATED}}"
version: "{{VERSION_NUMBER}}"
master_reference: "{{MASTER_DOC_ID}}"
purpose: "{{DOCUMENT_PURPOSE}}"
scope: "{{DOCUMENT_SCOPE}}"
category: "{{PRIMARY_CATEGORY}}"
subcategory: "{{SECONDARY_CATEGORY}}"
description: "{{BRIEF_DESCRIPTION}}"
status: "{{DOCUMENT_STATUS}}"
tags: [{{COMMA_SEPARATED_TAGS}}]
keywords: [{{COMMA_SEPARATED_KEYWORDS}}]
badges:
  - category: "{{CATEGORY_BADGE}}"
  - status: "{{STATUS_BADGE}}"
  - version: "{{VERSION_BADGE}}"
---

Document Structure Template

# {{DOCUMENT_TITLE}}

## Document Information
**Category:** {{CATEGORY}} | **Subcategory:** {{SUBCATEGORY}} | **Version:** {{VERSION}}

**Purpose:** {{PURPOSE_STATEMENT}}

### Quick Links
- [Related Architecture Document]({{ARCH_DOC_LINK}})
- [Implementation Guide]({{IMPL_GUIDE_LINK}})
- [Reference Standards]({{STANDARDS_LINK}})

---

## Content Section

[Document content here]

---

## Cross-References
- **Related Documents:** {{RELATED_DOCS}}
- **Dependencies:** {{DEPENDENCIES}}
- **Supersedes:** {{SUPERSEDED_DOCS}}

## Version Information
- **Author:** {{AUTHOR}}
- **Created:** {{CREATED_DATE}}
- **Last Updated:** {{UPDATED_DATE}}
- **Version:** {{VERSION}}
- **Status:** {{STATUS}}

Project Structure Template

project-root/
├── .copilot/
│   ├── instructions/
│   │   ├── azure-architecture-standards.md
│   │   ├── project-structure-standards.md
│   │   ├── iac-best-practices.md
│   │   └── documentation-standards.md
│   ├── prompts/
│   │   ├── project-management/
│   │   ├── infrastructure/
│   │   ├── documentation/
│   │   └── operations/
│   └── chatmodes/
│       ├── azure-hybrid-architect.chatmode
│       ├── devops-engineer.chatmode
│       └── security-specialist.chatmode
├── docs/
│   ├── architecture/
│   ├── design/
│   ├── operations/
│   ├── deployment/
│   ├── templates/
│   └── inventory/
│       ├── document-inventory.md
│       └── script-inventory.md
├── src/
│   ├── bicep/
│   ├── terraform/
│   ├── ansible/
│   └── powershell/
├── config/
│   ├── environments/
│   ├── pipelines/
│   └── monitoring/
├── tests/
│   ├── unit/
│   ├── integration/
│   └── acceptance/
├── logs/
│   ├── deployment/
│   ├── operations/
│   └── testing/
└── project-management/
    ├── planning/
    ├── tracking/
    └── templates/

Implementation Strategy

Phase 1: Foundation Setup

1. Create the basic directory structure
2. Implement the core chatmode file
3. Develop essential instruction files
4. Configure VS Code workspace settings

Phase 2: Prompt Development

1. Create project management prompts
2. Develop infrastructure-specific prompts
3. Build documentation automation prompts
4. Test and refine prompt effectiveness

Phase 3: Integration and Testing

1. Integrate with GitLab CI/CD workflows
2. Test documentation generation
3. Validate infrastructure code generation
4. Refine based on real-world usage

Phase 4: Advanced Features

1. Implement custom MCPs for Microsoft documentation
2. Add advanced project tracking capabilities
3. Integrate with Azure DevOps for project management
4. Develop automated compliance checking

Required Tools and Extensions

Microsoft Documentation Access

• Microsoft Graph PowerShell SDK for accessing Microsoft documentation
• Azure CLI for real-time Azure resource information
• Custom MCP for Microsoft Docs (to be developed)

Development Tools

• Bicep CLI for Azure resource deployment
• Terraform CLI for multi-cloud infrastructure
• Ansible for configuration management
• Azure PowerShell for Azure automation

Documentation Tools

• Markdown lint for document quality
• Vale for prose style checking
• Pandoc for document conversion
• PlantUML for architecture diagrams

Best Practices and Recommendations

Chatmode Best Practices

• Keep chatmode files focused on specific expertise areas
• Regularly update based on new Azure features and services
• Test chatmode effectiveness with real scenarios
• Maintain separate chatmodes for different project phases

Instruction File Management

• Version control all instruction files
• Regular reviews and updates based on Microsoft updates
• Cross-reference between related instruction files
• Include practical examples in all instructions

Prompt Optimization

• Test prompts with various input scenarios
• Gather feedback from team usage
• Maintain prompt libraries for common tasks
• Document prompt usage patterns and effectiveness

This comprehensive configuration will transform your GitHub Copilot Chat into a specialized Azure architecture assistant that understands your project management needs, follows your documentation standards, and accelerates your Infrastructure as Code development while maintaining consistency with Microsoft best practices.

Key Points

• Chatmode, instruction, and prompt files customize GitHub Copilot Chat for Azure-focused tasks.
• Chatmode files define task-specific contexts; instruction files set global guidelines; prompt templates guide user inputs.
• Repository structure organizes docs, code, configs, logs, tests, and project management.
• Document management includes standardized headers, footers, and inventories.
• Script inventory tracks Bicep, Terraform, Ansible scripts.
• VS Code settings enhance Copilot integration.

Chatmode, Instruction, Prompt Files

• Chatmode (.chatmode.md): Task-specific configurations in .github/chatmodes/. Example: Azure architecture mode for hybrid designs.
• Instruction (.github/copilot-instructions.md): Global guidelines for all modes, e.g., follow Azure best practices.
• Prompt Templates: Example prompts for tasks like Bicep template generation, stored in docs/prompt_templates.md.

Repository Structure

• Folders: docs/, src/, config/, logs/, tests/, project_management/.
• Subfolders for Bicep, Terraform, Ansible in src/.

Document Management

• Headers: Front matter with title, author, version, etc.; in-document badges, references, quick links.
• Footer: Cross-references, version block.
• Inventory: docs/inventory.md tracks all documents.

Script Inventory

• scripts/inventory.md lists Bicep, Terraform, Ansible scripts with purpose, path.

VS Code Configuration

• Install GitHub Copilot, Azure Tools, Terraform, Ansible extensions.
• Configure chat.modeFilesLocations in settings.json.

Additional Suggestions

• Use GitHub Projects for task tracking.
• Follow Microsoft CAF, WAF, and Azure naming standards.

GitHub Copilot Chat Configuration for Azure Architects and Hybrid Experts

1. Introduction

This document outlines the configuration of GitHub Copilot Chat for an Azure architect and hybrid expert, focusing on project management, infrastructure as code (IaC) with Azure Bicep, Terraform, and Ansible, and documentation. It details chatmode, instruction, and prompt files, repository structure, document management, script inventory, and VS Code configurations, ensuring alignment with Azure best practices, Microsoft Cloud Adoption Framework (CAF), Well-Architected Framework (WAF), and Microsoft documentation. The setup supports GitHub repositories while being adaptable for GitLab workflows.

2. Understanding Chatmode, Instruction, and Prompt Files

2.1 Chatmode Files (.chatmode.md)

• Purpose: Define task-specific configurations for Copilot Chat, tailoring behavior and tools.
• Usage: Stored in .github/chatmodes/ (workspace) or user profile. Selected via chat mode dropdown in VS Code.
• Content:
  • Front Matter: description (brief mode description), tools (e.g., ‘codebase’, ‘fetch’, ‘Azure CLI’), model (e.g., Claude Sonnet 4, optional).
  • Body: Task-specific instructions, can reference other instruction files via Markdown links.
• When to Use: For focused tasks like Azure architecture design or IaC development.
• Creation Steps:
  1. Run “Chat: New Mode File” from Command Palette (⇧⌘P / Ctrl+Shift+P).
  2. Choose workspace or user profile.
  3. Enter mode name.
  4. Edit .chatmode.md with description, tools, instructions.
• Configuration: Set chat.modeFilesLocations in VS Code settings to specify locations.

Example: Azure Architecture Mode

---
description: Design and explain Azure architectures, focusing on hybrid scenarios
tools: ['codebase', 'fetch', 'search', 'Azure CLI']
model: Claude Sonnet 4
---
Follow Azure CAF and WAF. Prioritize hybrid architectures integrating on-premises and Azure. Use Microsoft documentation for accuracy.

Citation: Chat modes in VS Code

2.2 Instruction Files (.github/copilot-instructions.md)

• Purpose: Provide global guidelines applied across all chat modes.
• Usage: Automatically included in chat prompts if enabled, listed as a reference in responses.
• Content: General instructions, e.g., Azure best practices, naming conventions.
• When to Use: To ensure consistent context for all Copilot interactions.
• Configuration: Can be disabled in Copilot extension settings.

Example:

# Copilot Instructions
- Follow Azure best practices and naming conventions (CAF, WAF).
- Reference Microsoft documentation for accuracy.
- Focus on hybrid scenarios (on-premises and Azure).
- Use standard IaC practices for Bicep, Terraform, Ansible.
- Ensure documentation includes mandatory headers and footers per document management design.
- Track all repository changes.

Citation: Responsible use of GitHub Copilot Chat in your IDE

2.3 Prompt Templates

• Purpose: Example prompts to guide effective Copilot interactions.
• Usage: Stored in docs/prompt_templates.md for team reference.
• Content: Predefined questions/commands for common tasks.
• When to Use: To standardize and simplify user interactions with Copilot.

Example:

# Prompt Templates
- **Bicep Template**: "Generate a Bicep template for deploying a virtual network in Azure with [specifications]."
- **Terraform**: "Create a Terraform configuration for provisioning an Azure VM with [parameters]."
- **Ansible**: "Write an Ansible playbook to configure [task] on [target]."
- **Documentation**: "Create a documentation page for [topic] following the standard template."
- **Project Management**: "Create a todo list for the current sprint based on open issues."

Citation: Getting started with prompts for Copilot Chat

2.4 Differences and Similarities

• Similarities:
  • All enhance Copilot interactions by providing structure and context.
  • Ensure consistency and alignment with project goals.
• Differences:
  • Chatmode: Task-specific, defines tools and instructions for a mode.
  • Instructions: Global context for all modes.
  • Prompt Templates: User-facing examples for crafting effective prompts.

3. Custom Chat Modes

Proposed chat modes tailored for Azure architects:

3.1 Azure Architecture Mode

• Description: Design and explain Azure architectures, emphasizing hybrid scenarios.
• Tools: Azure documentation, architecture diagrams, Azure CLI, search, fetch.
• Instructions: Adhere to CAF, WAF, and Azure naming standards. Focus on hybrid integration.
• Example Prompt: “Design a hybrid architecture for integrating on-premises AD with Azure AD.”

3.2 IaC Mode

• Description: Develop IaC with Bicep, Terraform, Ansible for Azure and on-premises.
• Tools: Bicep, Terraform, Ansible documentation, Azure CLI, codebase, fetch.
• Instructions: Follow standard IaC practices, Azure naming conventions, CAF compatibility.
• Example Prompt: “Generate a Bicep template for a virtual network with specific subnets.”

3.3 Documentation Mode

• Description: Generate and manage project documentation.
• Tools: Markdown, documentation templates, search, fetch.
• Instructions: Follow document management design, include mandatory headers/footers.
• Example Prompt: “Create a documentation page for the project’s architecture.”

3.4 Project Management Mode

• Description: Plan and track project tasks, including todo lists and repository structure.
• Tools: GitHub Projects, todo lists, search, fetch.
• Instructions: Integrate with repository structure, track all changes.
• Example Prompt: “Create a todo list for the current sprint based on open issues.”

4. Repository Structure

A standardized structure ensures organization:

5. Document Management

5.1 Document Format

All documents must include:

• Header (Front Matter):

  ---
  title: [Document Title]
  author: [Author Name]
  created: [Date]
  updated: [Date]
  version: [Version]
  purpose: [Purpose]
  scope: [Scope]
  category: [Category]
  subcategory: [Subcategory]
  keywords: [Keywords]
  tags: [Tags]
  ---
  

• In-Document Header:
  • Badges: Category, Subcategory
  • Reference Information: Scope, Category, Version
  • Quick Links: Related documents
• Footer:
  • Cross-references
  • Version block (author, created, edited)

5.2 Document Inventory

Stored in docs/inventory.md:

6. Script Inventory

Stored in scripts/inventory.md:

7. VS Code Configuration

• Extensions:
  • GitHub Copilot
  • Azure Tools for VS Code
  • Terraform
  • Ansible
  • Markdownlint
• Workspace Settings (settings.json):

  {
    "chat.modeFilesLocations": [".github/chatmodes"]
  }
  

• User Profile Settings: Configure global Copilot settings if needed.

8. Additional Tools and Resources

• Project Management: Use GitHub Projects for issue tracking and Kanban boards. Azure DevOps optional for advanced needs.
• Documentation: Use Markdown, consider static site generators for hosting.
• Learning Resources:
  • Microsoft Learn
  • Terraform Documentation
  • Ansible Documentation

9. Final Notes

• Configurations are optimized for GitHub but adaptable for GitLab.
• Prioritize Microsoft documentation, CAF, WAF, and Azure naming standards.
• Contact @CountryCloudBoy on X for further project insights.

Citations:

• Chat modes in VS Code
• Responsible use of GitHub Copilot Chat in your IDE
• Getting started with prompts for Copilot Chat

Plan for Chatmode, Prompt, and Instruction Files in GitHub Copilot Chat

This document outlines a unified approach to designing Chatmode, Prompt, and Instruction files tailored for an Azure Hybrid Architect. It covers repository and folder structures, document and script inventories, best practices in IaC and documentation, VS Code configurations, and guidance on when and how to use each file type.

1. Repository & Folder Structure

A consistent repo layout ensures clarity, traceability, and ease of navigation across Azure Bicep, Terraform, and Ansible projects.

my-azure-hybrid-project/
├── .github/
│   ├── workflows/            # CI/CD pipelines
│   └── ISSUE_TEMPLATE.md
├── docs/
│   ├── design/               # Architecture & deep-dive docs
│   ├── operations/           # Day-2 runbooks & playbooks
│   └── templates/            # Document header/footer templates
├── src/                      # Application or module source code
├── config/                   # Configuration files (e.g., YAML, JSON)
├── scripts/                  # Automation scripts (PS, Azure CLI, Ansible)
├── tests/                    # Pester, Terraform validate, Molecule tests
├── logs/                     # Example logs and log-parsing templates
├── project-management/
│   ├── roadmap.md
│   └── todo.md
└── .vscode/                  # Workspace settings & recommendations

2. Document Management Design

A central “templates” folder contains the canonical header/footer layouts and metadata schema.

2.1. Front-Matter Header (YAML)

---
title:              "<Document Title>"
type:               "<Design|Operations|Runbook|Template>"
tags:               ["Azure", "Terraform"]
keywords:           ["iac","hybrid"]
author:             "Kristopher"
created:            "2025-07-15"
updated:            "2025-07-15"
version:            "0.1.0"
master_reference:   "Design-Overview"
purpose:            "Define Azure Landing Zone"
scope:              "Hybrid Cloud"
category:           "Architecture"
description:        "High-level design for Azure Hybrid Landing Zone"
status:             "Draft"
badges:             ["Architecture","Hybrid"]
---

2.2. Inline Header & Footer Structure

• Badges line: Category / Subcategory
• Reference line: Scope • Category • Version
• Purpose: One-sentence mission statement
• Quick Links: Related docs with relative paths
• Footer:
  • Cross-references (links to impacted docs)
  • Version block table

3. Document & Script Inventories

3.1. Document Inventory (docs/inventory.md)

3.2. Script Inventory (docs/scripts-inventory.md)

4. Best Practices

• Adopt Microsoft Cloud Adoption Framework (CAF) guidance for naming, RBAC, and landing zones.
• Enforce naming standards: <env>-<app>-<component>-<region>
• Tag resources for cost center, project, and owner.
• In-script documentation: header comment, parameter validation, example usage.
• Leverage Pester for PowerShell modules, Molecule for Ansible roles, and Terraform Validate.

5. Project Management

• Use GitHub Projects (kanban) or GitLab Epics for feature tracking.
• Maintain project-management/roadmap.md for quarterly goals.
• todo.md: living backlog with priorities, statuses, and owners.
• Tag Issues with labels: enhancement, bug, documentation, ops.

6. Chatmode, Prompt, and Instruction Files

6.1. Definitions & Use Cases

1. Chatmode File

   • Name: .chatmode.json
   • Purpose: Defines persona, default context, tooling integrations.
   • Use when: You need Copilot Chat tailored to Azure Hybrid Architect persona and preloaded context.

2. Prompt File

   • Name: example.prompt or .prompts/**/*.prompt
   • Purpose: Houses reusable prompt templates (e.g., “Generate ARM template for…”).
   • Use when: You want a library of pre-written queries.

3. Instruction File

   • Name: .instructions.md or .instructions.yml
   • Purpose: High-level guidelines for Copilot behavior, tone, and policies.
   • Use when: You require consistent style, formatting, and guardrails.

6.2. Similarities & Differences

6.3. Complementary Usage

• Load Chatmode at session start to set context.
• Use Prompt Files to quickly insert specialized queries.
• Rely on Instruction Files to enforce doc formatting, security constraints, and tone.

7. VS Code Configuration

7.1. Workspace (.code-workspace)

{
  "folders": [
    { "path": "." }
  ],
  "settings": {
    "github.copilotChat.chatFiles": ["**/*.prompt", ".chatmode.json", ".instructions.md"],
    "editor.formatOnSave": true
  }
}

7.2. User Settings (settings.json)

• Enable YAML schema validation for front-matter.
• Link .chatmode.json to Copilot Chat plugin.
• Configure snippets for headers and badges.

7.3. Recommended Extensions

• Azure Resource Manager (ARM) Tools
• Terraform
• Ansible
• YAML
• GitLens
• Pester Test Explorer

8. Tools & References

• Azure CLI & Azure PowerShell
• Terraform & azurerm provider
• Bicep CLI
• Ansible + azure.azcollection
• Microsoft Cloud Adoption Framework
• Azure Well-Architected Framework
• Microsoft Docs (MCPs)
• GitHub Copilot Chat documentation

9. Additional Considerations

1. Branching Strategy: GitFlow or trunk-based for release predictability.
2. CI/CD Pipelines: YAML pipelines in GitHub Actions or GitLab CI for automated linting, test, and deploy.
3. Security Scanning: Integrate azure-cli-scan, tfsec, Ansible Lint.
4. License & Contribution: Add LICENSE.md, CODE_OF_CONDUCT.md, and PR templates.
5. Monitoring & Telemetry: Include Azure Monitor ARM templates, Log Analytics workspaces, and Grafana dashboards.

This plan provides a holistic blueprint for managing Chatmode, Prompt, and Instruction files in support of your Azure Hybrid Architect workflows.