Skip to content

Commit 5eb162a

Browse files
PlagueHOPlagueHO
committed
CHANGE: Update specifications and prompts for clarity
- Revised acceptance criteria and test automation strategy in specification files. - Enhanced clarity in implementation plan and specification prompts. - Added Microsoft Docs MCP tool to various chat modes and prompts for improved guidance. - Updated requirements in the data semantic model repository specification. - Introduced new Azure Verified Modules Terraform chat mode.
1 parent f318c6b commit 5eb162a

8 files changed

Lines changed: 285 additions & 12 deletions

‎.github/chatmodes/azure_verified_modules_bicep.chatmode.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
description: Create, update or review Azure infrastructure as code in Bicep syntax using Azure Verified Modules .
3-
tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'findTestFiles', 'githubRepo', 'new', 'openSimpleBrowser', 'problems', 'runCommands', 'runNotebooks', 'runTasks', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure', 'usages', 'vscodeAPI', 'giphy', 'playwright', 'azure_get_deployment_best_practices', 'azure_get_schema_for_Bicep', 'websearch']
3+
tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'findTestFiles', 'githubRepo', 'new', 'openSimpleBrowser', 'problems', 'runCommands', 'runNotebooks', 'runTasks', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure', 'usages', 'vscodeAPI', 'playwright', 'azure_get_deployment_best_practices', 'azure_get_schema_for_Bicep', 'websearch', 'microsoft.docs.mcp']
44
---
55
# Azure Verified Modules Bicep mode instructions
66

@@ -14,4 +14,8 @@ You can find use the `fetch` tool to get the latest version of an Azure Verified
1414

1515
You can find the documentation and example configurations for each Azure Verified Module resource in a folder based on the module name. For example, for module `avm/res/compute/virtual-machine` you will find the documentation in [https://github.com/Azure/bicep-registry-modules/tree/main/avm/res/compute/virtual-machine](https://github.com/Azure/bicep-registry-modules/tree/main/avm/res/compute/virtual-machine)
1616

17-
You can optionally use the Giphy tools to include relevant GIFs to illustrate concepts or add humor to your responses.
17+
You can search the Microsoft Learn documentation for Bicep resources using the `microsoft.docs.mcp` tool. For example, to search for Bicep resources related to virtual machines, you can use the query `bicep virtual machine`, but you should prioritize AVM documentation over generic Bicep documentation. But you should refer to the specifics of how an Azure service works and the best practices for deploying it using the Microsoft Learn documentation.
18+
19+
When you are creating or updating Bicep files, you should always ensure that the Bicep file is valid and adheres to the latest standards for Azure Verified Modules. You can use the `azure_get_deployment_best_practices` tool to get the best practices for deploying Azure resources using Bicep.
20+
21+
When you are creating or updating Bicep files, you should always ensure that the Bicep file is valid and adheres to the latest standards for Azure Verified Modules. You can use the `azure_get_schema_for_Bicep` tool to get the latest schema for Bicep files.

‎.github/chatmodes/azure_verified_modules_terraform.chatmode.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
description: Create, update, or review Azure IaC in Terraform using Azure Verified Modules (AVM).
3+
tools: ['changes','codebase','editFiles','extensions','fetch','findTestFiles','githubRepo','new','openSimpleBrowser','problems','runCommands','runNotebooks','runTasks','search','searchResults','terminalLastCommand','terminalSelection','testFailure','usages','vscodeAPI','playwright','azure_get_deployment_best_practices','websearch','microsoft.docs.mcp']
4+
---
5+
# Azure AVM Terraform mode
6+
Use Azure Verified Modules for Terraform to enforce Azure best practices via pre-built modules.
7+
8+
## Discover modules
9+
- Terraform Registry: search "avm" + resource, filter by Partner tag.
10+
- AVM Index: https://azure.github.io/Azure-Verified-Modules/indexes/terraform/tf-resource-modules/
11+
12+
## Usage
13+
- **Examples**: Copy example, replace `source = "../../"` with `source = "Azure/avm-res-{service}-{resource}/azurerm"`, add `version`, set `enable_telemetry`.
14+
- **Custom**: Copy Provision Instructions, set inputs, pin `version`.
15+
16+
## Versioning
17+
- Endpoint: `https://registry.terraform.io/v1/modules/Azure/{module}/azurerm/versions`
18+
19+
## Sources
20+
- Registry: `https://registry.terraform.io/modules/Azure/{module}/azurerm/latest`
21+
- GitHub: `https://github.com/Azure/terraform-azurerm-avm-res-{service}-{resource}`
22+
23+
## Naming conventions
24+
- Resource: Azure/avm-res-{service}-{resource}/azurerm
25+
- Pattern: Azure/avm-ptn-{pattern}/azurerm
26+
- Utility: Azure/avm-utl-{utility}/azurerm
27+
28+
## Best practices
29+
- Pin module and provider versions
30+
- Start with official examples
31+
- Review inputs and outputs
32+
- Enable telemetry
33+
- Use AVM utility modules
34+
- Follow AzureRM provider requirements
35+
- Use `microsoft.docs.mcp` tool to look up Azure service-specific guidance

‎.github/chatmodes/specification.chatmode.md‎

Lines changed: 23 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -62,21 +62,40 @@ tags: [Optional: List of relevant tags or categories, e.g., `infrastructure`, `p
6262

6363
[Describe the interfaces, APIs, data contracts, or integration points. Use tables or code blocks for schemas and examples.]
6464

65-
## 5. Rationale & Context
65+
## 5. Acceptance Criteria
66+
67+
[Define clear, testable acceptance criteria for each requirement using Given-When-Then format where appropriate.]
68+
69+
- **AC-001**: Given [context], When [action], Then [expected outcome]
70+
- **AC-002**: The system shall [specific behavior] when [condition]
71+
- **AC-003**: [Additional acceptance criteria as needed]
72+
73+
## 6. Test Automation Strategy
74+
75+
[Define the testing approach, frameworks, and automation requirements.]
76+
77+
- **Test Levels**: Unit, Integration, End-to-End
78+
- **Frameworks**: MSTest, FluentAssertions, Moq (for .NET applications)
79+
- **Test Data Management**: [approach for test data creation and cleanup]
80+
- **CI/CD Integration**: [automated testing in GitHub Actions pipelines]
81+
- **Coverage Requirements**: [minimum code coverage thresholds]
82+
- **Performance Testing**: [approach for load and performance testing]
83+
84+
## 7. Rationale & Context
6685

6786
[Explain the reasoning behind the requirements, constraints, and guidelines. Provide context for design decisions.]
6887

69-
## 6. Examples & Edge Cases
88+
## 8. Examples & Edge Cases
7089

7190
``````
7291
// Code snippet or data example demonstrating the correct application of the guidelines, including edge cases
7392
``````
7493

75-
## 7. Validation Criteria
94+
## 9. Validation Criteria
7695

7796
[List the criteria or tests that must be satisfied for compliance with this specification.]
7897

79-
## 8. Related Specifications / Further Reading
98+
## 10. Related Specifications / Further Reading
8099

81100
[Link to related spec 1]
82101
[Link to relevant external documentation]

‎.github/prompts/create_spec.prompt.md‎

Lines changed: 23 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -61,21 +61,40 @@ tags: [Optional: List of relevant tags or categories, e.g., `infrastructure`, `p
6161

6262
[Describe the interfaces, APIs, data contracts, or integration points. Use tables or code blocks for schemas and examples.]
6363

64-
## 5. Rationale & Context
64+
## 5. Acceptance Criteria
65+
66+
[Define clear, testable acceptance criteria for each requirement using Given-When-Then format where appropriate.]
67+
68+
- **AC-001**: Given [context], When [action], Then [expected outcome]
69+
- **AC-002**: The system shall [specific behavior] when [condition]
70+
- **AC-003**: [Additional acceptance criteria as needed]
71+
72+
## 6. Test Automation Strategy
73+
74+
[Define the testing approach, frameworks, and automation requirements.]
75+
76+
- **Test Levels**: Unit, Integration, End-to-End
77+
- **Frameworks**: MSTest, FluentAssertions, Moq (for .NET applications)
78+
- **Test Data Management**: [approach for test data creation and cleanup]
79+
- **CI/CD Integration**: [automated testing in GitHub Actions pipelines]
80+
- **Coverage Requirements**: [minimum code coverage thresholds]
81+
- **Performance Testing**: [approach for load and performance testing]
82+
83+
## 7. Rationale & Context
6584

6685
[Explain the reasoning behind the requirements, constraints, and guidelines. Provide context for design decisions.]
6786

68-
## 6. Examples & Edge Cases
87+
## 8. Examples & Edge Cases
6988

7089
``````
7190
// Code snippet or data example demonstrating the correct application of the guidelines, including edge cases
7291
``````
7392

74-
## 7. Validation Criteria
93+
## 9. Validation Criteria
7594

7695
[List the criteria or tests that must be satisfied for compliance with this specification.]
7796

78-
## 8. Related Specifications / Further Reading
97+
## 10. Related Specifications / Further Reading
7998

8099
[Link to related spec 1]
81100
[Link to relevant external documentation]

‎.github/prompts/update_avm_modules_in_bicep.prompt.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
mode: 'agent'
33
description: 'Update the Azure Verified Module to the latest version for the Bicep infrastructure as code file.'
4-
tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'githubRepo', 'openSimpleBrowser', 'problems', 'runTasks', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure', 'usages', 'vscodeAPI']
4+
tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'githubRepo', 'openSimpleBrowser', 'problems', 'runTasks', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure', 'usages', 'vscodeAPI', 'microsoft.docs.mcp']
55
---
66

77
Your goal is to update the Bicep file `${file}` to use the latest available versions of Azure Verified Modules (AVM).

‎.github/prompts/update_plan.prompt.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
mode: 'agent'
3+
description: Update an existing implementation plan file with new or update requirements to provide new features, refactoring existing code or upgrading packages, design, architecture or infrastructure.
4+
tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'githubRepo', 'openSimpleBrowser', 'problems', 'runTasks', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure', 'usages', 'vscodeAPI']
5+
---
6+
## Update Plan Prompt
7+
8+
Your goal is to update the existing implementation plan file for `${input:PlanPurpose}` based on new or updated requirements to provide new features, refactoring existing code or upgrading packages, design, architecture or infrastructure.
9+
10+
The plan file must define the implementation details, including specific tasks, dependencies, and testing strategies, in a manner that is clear, unambiguous, and structured for effective use by Generative AIs. Follow established documentation standards and ensure the content is machine-readable and self-contained.
11+
12+
**Best Practices for AI-Ready Specifications:**
13+
- Use precise, explicit, and unambiguous language.
14+
- Clearly distinguish between requirements, constraints, and recommendations.
15+
- Use structured formatting (headings, lists, tables) for easy parsing.
16+
- Avoid idioms, metaphors, or context-dependent references.
17+
- Define all acronyms and domain-specific terms.
18+
- Include examples and edge cases where applicable.
19+
- Ensure the document is self-contained and does not rely on external context.
20+
21+
The plan file should be saved in the [/plan/](/plan/) directory and named according to the following convention: `[a-z0-9-]+.md`, where the name should be descriptive of the plan's goal, such as `upgrade-system-command-4.md` or `refactor-lodash-4.md` and and starting with the highlevel purpose, which is one of [upgrade, refactor, feature, data, infrastructure, process, architecture, or design].
22+
23+
The plan file must be formatted in well formed Markdown.
24+
25+
Plan files must follow the template below, ensuring that all sections are filled out appropriately. The front matter and structure of the markdown for the plan should be structured correctly as per the example following:
26+
27+
```md
28+
---
29+
goal: [Concise Title Describing the Package Plan's Goal]
30+
version: [Optional: e.g., 1.0, Date]
31+
date_created: [YYYY-MM-DD]
32+
last_updated: [Optional: YYYY-MM-DD]
33+
owner: [Optional: Team/Individual responsible for this spec]
34+
tags: [Optional: List of relevant tags or categories, e.g., `feature`, `upgrade`, `chore`, `architecture`, `migration`, `bug` etc]
35+
---
36+
37+
# Introduction
38+
39+
[A short concise introduction to the plan and the goal it is intended to achieve.]
40+
41+
## 1. Requirements & Constraints
42+
43+
[Explicitly list all requirements & constraints that affect the plan and constrain how it is implemented. Use bullet points or tables for clarity.]
44+
45+
- **REQ-001**: Requirement 1
46+
- **SEC-001**: Security Requirement 1
47+
- **[3 LETTERS]-001**: Other Requirement 1
48+
- **CON-001**: Constraint 1
49+
- **GUD-001**: Guideline 1
50+
- **PAT-001**: Pattern to follow 1
51+
52+
## 2. Implementation Steps
53+
54+
[Describe the steps/tasks required to achieve the goal.]
55+
56+
## 3. Alternatives
57+
58+
[A bullet point list of any alternative approaches that were considered and why they were not chosen. This helps to provide context and rationale for the chosen approach.]
59+
60+
- **ALT-001**: Alternative approach 1
61+
- **ALT-002**: Alternative approach 2
62+
63+
## 4. Dependencies
64+
65+
[List any dependencies that need to be addressed, such as libraries, frameworks, or other components that the plan relies on.]
66+
67+
- **DEP-001**: Dependency 1
68+
- **DEP-002**: Dependency 2
69+
70+
## 5. Files
71+
72+
[List the files that will be affected by the feature or refactoring task.]
73+
74+
- **FILE-001**: Description of file 1
75+
- **FILE-002**: Description of file 2
76+
77+
## 6. Testing
78+
79+
[List the tests that need to be implemented to verify the feature or refactoring task.]
80+
81+
- **TEST-001**: Description of test 1
82+
- **TEST-002**: Description of test 2
83+
84+
## 7. Risks & Assumptions
85+
86+
[List any risks or assumptions related to the implementation of the plan.]
87+
88+
- **RISK-001**: Risk 1
89+
- **ASSUMPTION-001**: Assumption 1
90+
91+
## 8. Related Specifications / Further Reading
92+
93+
[Link to related spec 1]
94+
[Link to relevant external documentation]
95+
```

‎.github/prompts/update_spec.prompt.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
mode: 'agent'
3+
description: Update an existing specification file for the solution, optimized for Generative AI consumption based on new requirements or updates to any existing code.
4+
tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'githubRepo', 'openSimpleBrowser', 'problems', 'runTasks', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure', 'usages', 'vscodeAPI']
5+
---
6+
## Update Specification Prompt
7+
8+
Your goal is to update the existing specification file for `${input:SpecPurpose}` based on new requirements or updates to any existing code.
9+
10+
The specification file must define the requirements, constraints, and interfaces for the solution components in a manner that is clear, unambiguous, and structured for effective use by Generative AIs. Follow established documentation standards and ensure the content is machine-readable and self-contained.
11+
12+
**Best Practices for AI-Ready Specifications:**
13+
- Use precise, explicit, and unambiguous language.
14+
- Clearly distinguish between requirements, constraints, and recommendations.
15+
- Use structured formatting (headings, lists, tables) for easy parsing.
16+
- Avoid idioms, metaphors, or context-dependent references.
17+
- Define all acronyms and domain-specific terms.
18+
- Include examples and edge cases where applicable.
19+
- Ensure the document is self-contained and does not rely on external context.
20+
21+
The specification should be saved in the [/spec/](/spec/) directory and named according to the following convention: `[a-z0-9-]+.md`, where the name should be descriptive of the specification's content and starting with the highlevel purpose, which is one of [schema, tool, data, infrastructure, process, architecture, or design].
22+
23+
The specification file must be formatted in well formed Markdown.
24+
25+
Specification files must follow the template below, ensuring that all sections are filled out appropriately. The front matter for the markdown should be structured correctly as per the example following:
26+
27+
```md
28+
---
29+
title: [Concise Title Describing the Specification's Focus]
30+
version: [Optional: e.g., 1.0, Date]
31+
date_created: [YYYY-MM-DD]
32+
last_updated: [Optional: YYYY-MM-DD]
33+
owner: [Optional: Team/Individual responsible for this spec]
34+
tags: [Optional: List of relevant tags or categories, e.g., `infrastructure`, `process`, `design`, `app` etc]
35+
---
36+
37+
# Introduction
38+
39+
[A short concise introduction to the specification and the goal it is intended to achieve.]
40+
41+
## 1. Purpose & Scope
42+
43+
[Provide a clear, concise description of the specification's purpose and the scope of its application. State the intended audience and any assumptions.]
44+
45+
## 2. Definitions
46+
47+
[List and define all acronyms, abbreviations, and domain-specific terms used in this specification.]
48+
49+
## 3. Requirements, Constraints & Guidelines
50+
51+
[Explicitly list all requirements, constraints, rules, and guidelines. Use bullet points or tables for clarity.]
52+
53+
- **REQ-001**: Requirement 1
54+
- **SEC-001**: Security Requirement 1
55+
- **[3 LETTERS]-001**: Other Requirement 1
56+
- **CON-001**: Constraint 1
57+
- **GUD-001**: Guideline 1
58+
- **PAT-001**: Pattern to follow 1
59+
60+
## 4. Interfaces & Data Contracts
61+
62+
[Describe the interfaces, APIs, data contracts, or integration points. Use tables or code blocks for schemas and examples.]
63+
64+
## 5. Acceptance Criteria
65+
66+
[Define clear, testable acceptance criteria for each requirement using Given-When-Then format where appropriate.]
67+
68+
- **AC-001**: Given [context], When [action], Then [expected outcome]
69+
- **AC-002**: The system shall [specific behavior] when [condition]
70+
- **AC-003**: [Additional acceptance criteria as needed]
71+
72+
## 6. Test Automation Strategy
73+
74+
[Define the testing approach, frameworks, and automation requirements.]
75+
76+
- **Test Levels**: Unit, Integration, End-to-End
77+
- **Frameworks**: MSTest, FluentAssertions, Moq (for .NET applications)
78+
- **Test Data Management**: [approach for test data creation and cleanup]
79+
- **CI/CD Integration**: [automated testing in GitHub Actions pipelines]
80+
- **Coverage Requirements**: [minimum code coverage thresholds]
81+
- **Performance Testing**: [approach for load and performance testing]
82+
83+
## 7. Rationale & Context
84+
85+
[Explain the reasoning behind the requirements, constraints, and guidelines. Provide context for design decisions.]
86+
87+
## 8. Examples & Edge Cases
88+
89+
``````
90+
// Code snippet or data example demonstrating the correct application of the guidelines, including edge cases
91+
``````
92+
93+
## 9. Validation Criteria
94+
95+
[List the criteria or tests that must be satisfied for compliance with this specification.]
96+
97+
## 10. Related Specifications / Further Reading
98+
99+
[Link to related spec 1]
100+
[Link to relevant external documentation]
101+
```

‎spec/data-semantic-model-repository.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ This specification defines the requirements for implementing a repository patter
4545

4646
- **REQ-001**: The repository pattern MUST provide abstraction for semantic model persistence operations
4747
- **REQ-002**: The implementation MUST support asynchronous operations for all I/O-bound activities
48-
- **REQ-003**: The repository MUST handle both file-based and future database-based persistence strategies
48+
- **REQ-003**: The repository MUST handle both file-based (local and blob storage) and future document database-based persistence strategies
4949
- **REQ-004**: The semantic model MUST be persisted in a hierarchical structure with separate files for entities
5050
- **REQ-005**: The repository MUST support CRUD operations (Create, Read, Update, Delete) for semantic models
5151
- **REQ-006**: The implementation MUST use dependency injection for component management

0 commit comments

Comments
 (0)