feat: Add comprehensive documentation prompts for OO components, specifications, and .NET best practices
- Introduced a prompt for creating standardized documentation for object-oriented components, adhering to industry best practices and architectural standards. - Added a prompt for generating new specification files optimized for Generative AI consumption, including best practices for AI-ready specifications. - Created a prompt for reviewing .NET/C# code against best practices, focusing on documentation, design patterns, dependency injection, and error handling. - Developed a prompt for reviewing design pattern implementations in .NET/C# code, providing a checklist and improvement focus areas. - Implemented a prompt for updating Azure Verified Modules in Bicep files to the latest versions, including a breaking change policy. - Added a prompt for updating existing implementation plans with new requirements or updates to existing code. - Created a prompt for updating the llms.txt file to reflect changes in documentation or specifications. - Developed a prompt for updating markdown file sections with an index/table of files from specified folders. - Introduced a prompt for updating existing object-oriented component documentation based on current implementation. - Added a prompt for updating existing specifications based on new requirements or code updates.
This commit is contained in:
Daniel Scott-Raynsford
parent
b4ea7c6950
commit
8229a03986
97
prompts/create_architectural_decision_record.prompt.md
Normal file
97
prompts/create_architectural_decision_record.prompt.md
Normal file
@ -0,0 +1,97 @@
|
|||||||
|
---
|
||||||
|
mode: 'agent'
|
||||||
|
description: Create an Architectural Decision Record (ADR) document for AI-optimized decision documentation.
|
||||||
|
tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'githubRepo', 'openSimpleBrowser', 'problems', 'runTasks', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure', 'usages', 'vscodeAPI']
|
||||||
|
---
|
||||||
|
# Create Architectural Decision Record
|
||||||
|
|
||||||
|
Create an ADR document for `${input:DecisionTitle}` using structured formatting optimized for AI consumption and human readability.
|
||||||
|
|
||||||
|
**Inputs:**
|
||||||
|
|
||||||
|
- **Context**: `${input:Context}`
|
||||||
|
- **Decision**: `${input:Decision}`
|
||||||
|
- **Alternatives**: `${input:Alternatives}`
|
||||||
|
- **Stakeholders**: `${input:Stakeholders}`
|
||||||
|
|
||||||
|
**Input Validation:**
|
||||||
|
If any of the required inputs are not provided or cannot be determined from the conversation history, ask the user to provide the missing information before proceeding with ADR generation.
|
||||||
|
|
||||||
|
**Requirements:**
|
||||||
|
|
||||||
|
- Use precise, unambiguous language
|
||||||
|
- Follow standardized ADR format with front matter
|
||||||
|
- Include both positive and negative consequences
|
||||||
|
- Document alternatives with rejection rationale
|
||||||
|
- Structure for machine parsing and human reference
|
||||||
|
- Use coded bullet points (3-4 letter codes + 3-digit numbers) for multi-item sections
|
||||||
|
|
||||||
|
The ADR must be saved in the `/docs/adr/` directory using the naming convention: `adr-NNNN-[title-slug].md`, where NNNN is the next sequential 4-digit number (e.g., `adr-0001-database-selection.md`).
|
||||||
|
|
||||||
|
**Required Documentation Structure:**
|
||||||
|
|
||||||
|
The documentation file 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:
|
||||||
|
|
||||||
|
```md
|
||||||
|
---
|
||||||
|
title: "ADR-NNNN: [Decision Title]"
|
||||||
|
status: "Proposed"
|
||||||
|
date: "YYYY-MM-DD"
|
||||||
|
authors: "[Stakeholder Names/Roles]"
|
||||||
|
tags: ["architecture", "decision"]
|
||||||
|
supersedes: ""
|
||||||
|
superseded_by: ""
|
||||||
|
---
|
||||||
|
|
||||||
|
# ADR-NNNN: [Decision Title]
|
||||||
|
|
||||||
|
## Status
|
||||||
|
|
||||||
|
**Proposed** | Accepted | Rejected | Superseded | Deprecated
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
[Problem statement, technical constraints, business requirements, and environmental factors requiring this decision.]
|
||||||
|
|
||||||
|
## Decision
|
||||||
|
|
||||||
|
[Chosen solution with clear rationale for selection.]
|
||||||
|
|
||||||
|
## Consequences
|
||||||
|
|
||||||
|
### Positive
|
||||||
|
|
||||||
|
- **POS-001**: [Beneficial outcomes and advantages]
|
||||||
|
- **POS-002**: [Performance, maintainability, scalability improvements]
|
||||||
|
- **POS-003**: [Alignment with architectural principles]
|
||||||
|
|
||||||
|
### Negative
|
||||||
|
|
||||||
|
- **NEG-001**: [Trade-offs, limitations, drawbacks]
|
||||||
|
- **NEG-002**: [Technical debt or complexity introduced]
|
||||||
|
- **NEG-003**: [Risks and future challenges]
|
||||||
|
|
||||||
|
## Alternatives Considered
|
||||||
|
|
||||||
|
### [Alternative 1 Name]
|
||||||
|
|
||||||
|
- **ALT-001**: **Description**: [Brief technical description]
|
||||||
|
- **ALT-002**: **Rejection Reason**: [Why this option was not selected]
|
||||||
|
|
||||||
|
### [Alternative 2 Name]
|
||||||
|
|
||||||
|
- **ALT-003**: **Description**: [Brief technical description]
|
||||||
|
- **ALT-004**: **Rejection Reason**: [Why this option was not selected]
|
||||||
|
|
||||||
|
## Implementation Notes
|
||||||
|
|
||||||
|
- **IMP-001**: [Key implementation considerations]
|
||||||
|
- **IMP-002**: [Migration or rollout strategy if applicable]
|
||||||
|
- **IMP-003**: [Monitoring and success criteria]
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
- **REF-001**: [Related ADRs]
|
||||||
|
- **REF-002**: [External documentation]
|
||||||
|
- **REF-003**: [Standards or frameworks referenced]
|
||||||
|
```
|
||||||
@ -0,0 +1,28 @@
|
|||||||
|
---
|
||||||
|
mode: 'agent'
|
||||||
|
description: 'Create GitHub Issue for feature request from specification file using feature_request.yml template.'
|
||||||
|
tools: ['codebase', 'search', 'github', 'create_issue', 'search_issues', 'update_issue']
|
||||||
|
---
|
||||||
|
# Create GitHub Issue from Specification
|
||||||
|
|
||||||
|
Create GitHub Issue for the specification at `${file}`.
|
||||||
|
|
||||||
|
**Process:**
|
||||||
|
|
||||||
|
1. Analyze specification file to extract requirements
|
||||||
|
2. Check existing issues using `search_issues`
|
||||||
|
3. Create new issue using `create_issue` or update existing with `update_issue`
|
||||||
|
4. Use `feature_request.yml` template (fallback to default)
|
||||||
|
|
||||||
|
**Requirements:**
|
||||||
|
|
||||||
|
- Single issue for the complete specification
|
||||||
|
- Clear title identifying the specification
|
||||||
|
- Include only changes required by the specification
|
||||||
|
- Verify against existing issues before creation
|
||||||
|
|
||||||
|
**Issue Content:**
|
||||||
|
|
||||||
|
- Title: Feature name from specification
|
||||||
|
- Description: Problem statement, proposed solution, and context
|
||||||
|
- Labels: feature, enhancement (as appropriate)
|
||||||
@ -0,0 +1,28 @@
|
|||||||
|
---
|
||||||
|
mode: 'agent'
|
||||||
|
description: 'Create GitHub Issues from implementation plan phases using feature_request.yml or chore_request.yml templates.'
|
||||||
|
tools: ['codebase', 'search', 'github', 'create_issue', 'search_issues', 'update_issue']
|
||||||
|
---
|
||||||
|
# Create GitHub Issue from Implementation Plan
|
||||||
|
|
||||||
|
Create GitHub Issues for the implementation plan at `${file}`.
|
||||||
|
|
||||||
|
**Process:**
|
||||||
|
|
||||||
|
1. Analyze plan file to identify phases
|
||||||
|
2. Check existing issues using `search_issues`
|
||||||
|
3. Create new issue per phase using `create_issue` or update existing with `update_issue`
|
||||||
|
4. Use `feature_request.yml` or `chore_request.yml` templates (fallback to default)
|
||||||
|
|
||||||
|
**Requirements:**
|
||||||
|
|
||||||
|
- One issue per implementation phase
|
||||||
|
- Clear, structured titles and descriptions
|
||||||
|
- Include only changes required by the plan
|
||||||
|
- Verify against existing issues before creation
|
||||||
|
|
||||||
|
**Issue Content:**
|
||||||
|
|
||||||
|
- Title: Phase name from implementation plan
|
||||||
|
- Description: Phase details, requirements, and context
|
||||||
|
- Labels: Appropriate for issue type (feature/chore)
|
||||||
@ -0,0 +1,35 @@
|
|||||||
|
---
|
||||||
|
mode: 'agent'
|
||||||
|
description: 'Create GitHub Issues for unimplemented requirements from specification files using feature_request.yml template.'
|
||||||
|
tools: ['codebase', 'search', 'github', 'create_issue', 'search_issues', 'update_issue']
|
||||||
|
---
|
||||||
|
# Create GitHub Issues for Unmet Specification Requirements
|
||||||
|
|
||||||
|
Create GitHub Issues for unimplemented requirements in the specification at `${input:file}`.
|
||||||
|
|
||||||
|
**Process:**
|
||||||
|
|
||||||
|
1. Analyze specification file to extract all requirements
|
||||||
|
2. Check codebase implementation status for each requirement
|
||||||
|
3. Search existing issues using `search_issues` to avoid duplicates
|
||||||
|
4. Create new issue per unimplemented requirement using `create_issue`
|
||||||
|
5. Use `feature_request.yml` template (fallback to default)
|
||||||
|
|
||||||
|
**Requirements:**
|
||||||
|
|
||||||
|
- One issue per unimplemented requirement from specification
|
||||||
|
- Clear requirement ID and description mapping
|
||||||
|
- Include implementation guidance and acceptance criteria
|
||||||
|
- Verify against existing issues before creation
|
||||||
|
|
||||||
|
**Issue Content:**
|
||||||
|
|
||||||
|
- Title: Requirement ID and brief description
|
||||||
|
- Description: Detailed requirement, implementation method, and context
|
||||||
|
- Labels: feature, enhancement (as appropriate)
|
||||||
|
|
||||||
|
**Implementation Check:**
|
||||||
|
|
||||||
|
- Search codebase for related code patterns
|
||||||
|
- Check related specification files in `/spec/` directory
|
||||||
|
- Verify requirement isn't partially implemented
|
||||||
144
prompts/create_implementation_plan.prompt.md
Normal file
144
prompts/create_implementation_plan.prompt.md
Normal file
@ -0,0 +1,144 @@
|
|||||||
|
---
|
||||||
|
mode: 'agent'
|
||||||
|
description: Create a new implementation plan file for new features, refactoring existing code or upgrading packages, design, architecture or infrastructure.
|
||||||
|
tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'githubRepo', 'openSimpleBrowser', 'problems', 'runTasks', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure', 'usages', 'vscodeAPI']
|
||||||
|
---
|
||||||
|
# Implementation Plan Update Prompt
|
||||||
|
|
||||||
|
**PRIMARY DIRECTIVE**: Your goal is to create a new implementation plan file for `${input:PlanPurpose}`. Your output must be machine-readable, deterministic, and structured for autonomous execution by other AI systems or humans.
|
||||||
|
|
||||||
|
**EXECUTION CONTEXT**: This prompt is designed for AI-to-AI communication and automated processing. All instructions must be interpreted literally and executed systematically without human interpretation or clarification.
|
||||||
|
|
||||||
|
**CORE REQUIREMENTS**:
|
||||||
|
|
||||||
|
- Generate implementation plans that are fully executable by AI agents or humans
|
||||||
|
- Use deterministic language with zero ambiguity
|
||||||
|
- Structure all content for automated parsing and execution
|
||||||
|
- Ensure complete self-containment with no external dependencies for understanding
|
||||||
|
|
||||||
|
**PLAN STRUCTURE REQUIREMENTS**:
|
||||||
|
Plans must consist of discrete, atomic phases containing executable tasks. Each phase must be independently processable by AI agents or humans without cross-phase dependencies unless explicitly declared.
|
||||||
|
|
||||||
|
**PHASE ARCHITECTURE**:
|
||||||
|
|
||||||
|
- Each phase must have measurable completion criteria
|
||||||
|
- Tasks within phases must be executable in parallel unless dependencies are specified
|
||||||
|
- All task descriptions must include specific file paths, function names, and exact implementation details
|
||||||
|
- No task should require human interpretation or decision-making
|
||||||
|
|
||||||
|
**AI-OPTIMIZED IMPLEMENTATION STANDARDS**:
|
||||||
|
|
||||||
|
- Use explicit, unambiguous language with zero interpretation required
|
||||||
|
- Structure all content as machine-parseable formats (tables, lists, structured data)
|
||||||
|
- Include specific file paths, line numbers, and exact code references where applicable
|
||||||
|
- Define all variables, constants, and configuration values explicitly
|
||||||
|
- Provide complete context within each task description
|
||||||
|
- Use standardized prefixes for all identifiers (REQ-, TASK-, etc.)
|
||||||
|
- Include validation criteria that can be automatically verified
|
||||||
|
|
||||||
|
**OUTPUT FILE SPECIFICATIONS**:
|
||||||
|
|
||||||
|
- Save implementation plan files in `/plan/` directory
|
||||||
|
- Use naming convention: `[purpose]-[component]-[version].md`
|
||||||
|
- Purpose prefixes: `upgrade|refactor|feature|data|infrastructure|process|architecture|design`
|
||||||
|
- Example: `upgrade-system-command-4.md`, `feature-auth-module-1.md`
|
||||||
|
- File must be valid Markdown with proper front matter structure
|
||||||
|
|
||||||
|
**MANDATORY TEMPLATE STRUCTURE**:
|
||||||
|
All implementation plans must strictly adhere to the following template. Each section is required and must be populated with specific, actionable content. AI agents must validate template compliance before execution.
|
||||||
|
|
||||||
|
**TEMPLATE VALIDATION RULES**:
|
||||||
|
|
||||||
|
- All front matter fields must be present and properly formatted
|
||||||
|
- All section headers must match exactly (case-sensitive)
|
||||||
|
- All identifier prefixes must follow the specified format
|
||||||
|
- Tables must include all required columns
|
||||||
|
- No placeholder text may remain in the final output
|
||||||
|
|
||||||
|
```md
|
||||||
|
---
|
||||||
|
goal: [Concise Title Describing the Package Implementation Plan's Goal]
|
||||||
|
version: [Optional: e.g., 1.0, Date]
|
||||||
|
date_created: [YYYY-MM-DD]
|
||||||
|
last_updated: [Optional: YYYY-MM-DD]
|
||||||
|
owner: [Optional: Team/Individual responsible for this spec]
|
||||||
|
tags: [Optional: List of relevant tags or categories, e.g., `feature`, `upgrade`, `chore`, `architecture`, `migration`, `bug` etc]
|
||||||
|
---
|
||||||
|
|
||||||
|
# Introduction
|
||||||
|
|
||||||
|
[A short concise introduction to the plan and the goal it is intended to achieve.]
|
||||||
|
|
||||||
|
## 1. Requirements & Constraints
|
||||||
|
|
||||||
|
[Explicitly list all requirements & constraints that affect the plan and constrain how it is implemented. Use bullet points or tables for clarity.]
|
||||||
|
|
||||||
|
- **REQ-001**: Requirement 1
|
||||||
|
- **SEC-001**: Security Requirement 1
|
||||||
|
- **[3 LETTERS]-001**: Other Requirement 1
|
||||||
|
- **CON-001**: Constraint 1
|
||||||
|
- **GUD-001**: Guideline 1
|
||||||
|
- **PAT-001**: Pattern to follow 1
|
||||||
|
|
||||||
|
## 2. Implementation Steps
|
||||||
|
|
||||||
|
### Implementation Phase 1
|
||||||
|
|
||||||
|
- GOAL-001: [Describe the goal of this phase, e.g., "Implement feature X", "Refactor module Y", etc.]
|
||||||
|
|
||||||
|
| Task | Description | Completed | Date |
|
||||||
|
|------|-------------|-----------|------|
|
||||||
|
| TASK-001 | Description of task 1 | ✅ | 2025-04-25 |
|
||||||
|
| TASK-002 | Description of task 2 | | |
|
||||||
|
| TASK-003 | Description of task 3 | | |
|
||||||
|
|
||||||
|
### Implementation Phase 2
|
||||||
|
|
||||||
|
- GOAL-002: [Describe the goal of this phase, e.g., "Implement feature X", "Refactor module Y", etc.]
|
||||||
|
|
||||||
|
| Task | Description | Completed | Date |
|
||||||
|
|------|-------------|-----------|------|
|
||||||
|
| TASK-004 | Description of task 4 | | |
|
||||||
|
| TASK-005 | Description of task 5 | | |
|
||||||
|
| TASK-006 | Description of task 6 | | |
|
||||||
|
|
||||||
|
## 3. Alternatives
|
||||||
|
|
||||||
|
[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.]
|
||||||
|
|
||||||
|
- **ALT-001**: Alternative approach 1
|
||||||
|
- **ALT-002**: Alternative approach 2
|
||||||
|
|
||||||
|
## 4. Dependencies
|
||||||
|
|
||||||
|
[List any dependencies that need to be addressed, such as libraries, frameworks, or other components that the plan relies on.]
|
||||||
|
|
||||||
|
- **DEP-001**: Dependency 1
|
||||||
|
- **DEP-002**: Dependency 2
|
||||||
|
|
||||||
|
## 5. Files
|
||||||
|
|
||||||
|
[List the files that will be affected by the feature or refactoring task.]
|
||||||
|
|
||||||
|
- **FILE-001**: Description of file 1
|
||||||
|
- **FILE-002**: Description of file 2
|
||||||
|
|
||||||
|
## 6. Testing
|
||||||
|
|
||||||
|
[List the tests that need to be implemented to verify the feature or refactoring task.]
|
||||||
|
|
||||||
|
- **TEST-001**: Description of test 1
|
||||||
|
- **TEST-002**: Description of test 2
|
||||||
|
|
||||||
|
## 7. Risks & Assumptions
|
||||||
|
|
||||||
|
[List any risks or assumptions related to the implementation of the plan.]
|
||||||
|
|
||||||
|
- **RISK-001**: Risk 1
|
||||||
|
- **ASSUMPTION-001**: Assumption 1
|
||||||
|
|
||||||
|
## 8. Related Specifications / Further Reading
|
||||||
|
|
||||||
|
[Link to related spec 1]
|
||||||
|
[Link to relevant external documentation]
|
||||||
|
```
|
||||||
193
prompts/create_oo_component_documentation.prompt.md
Normal file
193
prompts/create_oo_component_documentation.prompt.md
Normal file
@ -0,0 +1,193 @@
|
|||||||
|
---
|
||||||
|
mode: 'agent'
|
||||||
|
description: 'Create comprehensive, standardized documentation for object-oriented components following industry best practices and architectural documentation standards.'
|
||||||
|
tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'githubRepo', 'openSimpleBrowser', 'problems', 'runTasks', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure', 'usages', 'vscodeAPI']
|
||||||
|
---
|
||||||
|
# Generate Standard OO Component Documentation
|
||||||
|
|
||||||
|
Create comprehensive documentation for the object-oriented component(s) at: `${input:ComponentPath}`.
|
||||||
|
|
||||||
|
Analyze the component by examining code in the provided path. If folder, analyze all source files. If single file, treat as main component and analyze related files in same directory.
|
||||||
|
|
||||||
|
**Documentation Standards:**
|
||||||
|
|
||||||
|
- DOC-001: Follow C4 Model documentation levels (Context, Containers, Components, Code)
|
||||||
|
- DOC-002: Align with Arc42 software architecture documentation template
|
||||||
|
- DOC-003: Comply with IEEE 1016 Software Design Description standard
|
||||||
|
- DOC-004: Use Agile Documentation principles (just enough documentation that adds value)
|
||||||
|
- DOC-005: Target developers and maintainers as primary audience
|
||||||
|
|
||||||
|
**Analysis Instructions:**
|
||||||
|
|
||||||
|
- ANA-001: Determine path type (folder vs single file) and identify primary component
|
||||||
|
- ANA-002: Examine source code files for class structures and inheritance
|
||||||
|
- ANA-003: Identify design patterns and architectural decisions
|
||||||
|
- ANA-004: Document public APIs, interfaces, and dependencies
|
||||||
|
- ANA-005: Recognize creational/structural/behavioral patterns
|
||||||
|
- ANA-006: Document method parameters, return values, exceptions
|
||||||
|
- ANA-007: Assess performance, security, reliability, maintainability
|
||||||
|
- ANA-008: Infer integration patterns and data flow
|
||||||
|
|
||||||
|
**Language-Specific Optimizations:**
|
||||||
|
|
||||||
|
- LNG-001: **C#/.NET** - async/await, dependency injection, configuration, disposal
|
||||||
|
- LNG-002: **Java** - Spring framework, annotations, exception handling, packaging
|
||||||
|
- LNG-003: **TypeScript/JavaScript** - modules, async patterns, types, npm
|
||||||
|
- LNG-004: **Python** - packages, virtual environments, type hints, testing
|
||||||
|
|
||||||
|
**Error Handling:**
|
||||||
|
|
||||||
|
- ERR-001: Path doesn't exist - provide correct format guidance
|
||||||
|
- ERR-002: No source files found - suggest alternative locations
|
||||||
|
- ERR-003: Unclear structure - document findings and request clarification
|
||||||
|
- ERR-004: Non-standard patterns - document custom approaches
|
||||||
|
- ERR-005: Insufficient code - focus on available information, highlight gaps
|
||||||
|
|
||||||
|
**Output Format:**
|
||||||
|
|
||||||
|
Generate well-structured Markdown with clear heading hierarchy, code blocks, tables, bullet points, and proper formatting for readability and maintainability.
|
||||||
|
|
||||||
|
**File Location:**
|
||||||
|
|
||||||
|
The documentation should be saved in the `/docs/components/` directory and named according to the convention: `[component-name]-documentation.md`.
|
||||||
|
|
||||||
|
**Required Documentation Structure:**
|
||||||
|
|
||||||
|
The documentation file 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:
|
||||||
|
|
||||||
|
```md
|
||||||
|
---
|
||||||
|
title: [Component Name] - Technical Documentation
|
||||||
|
component_path: `${input:ComponentPath}`
|
||||||
|
version: [Optional: e.g., 1.0, Date]
|
||||||
|
date_created: [YYYY-MM-DD]
|
||||||
|
last_updated: [Optional: YYYY-MM-DD]
|
||||||
|
owner: [Optional: Team/Individual responsible for this component]
|
||||||
|
tags: [Optional: List of relevant tags or categories, e.g., `component`,`service`,`tool`,`infrastructure`,`documentation`,`architecture` etc]
|
||||||
|
---
|
||||||
|
|
||||||
|
# [Component Name] Documentation
|
||||||
|
|
||||||
|
[A short concise introduction to the component and its purpose within the system.]
|
||||||
|
|
||||||
|
## 1. Component Overview
|
||||||
|
|
||||||
|
### Purpose/Responsibility
|
||||||
|
- OVR-001: State component's primary responsibility
|
||||||
|
- OVR-002: Define scope (included/excluded functionality)
|
||||||
|
- OVR-003: Describe system context and relationships
|
||||||
|
|
||||||
|
## 2. Architecture Section
|
||||||
|
|
||||||
|
- ARC-001: Document design patterns used (Repository, Factory, Observer, etc.)
|
||||||
|
- ARC-002: List internal and external dependencies with purposes
|
||||||
|
- ARC-003: Document component interactions and relationships
|
||||||
|
- ARC-004: Include visual diagrams (UML class, sequence, component)
|
||||||
|
- ARC-005: Create mermaid diagram showing component structure, relationships, and dependencies
|
||||||
|
|
||||||
|
### Component Structure and Dependencies Diagram
|
||||||
|
|
||||||
|
Include a comprehensive mermaid diagram that shows:
|
||||||
|
- **Component structure** - Main classes, interfaces, and their relationships
|
||||||
|
- **Internal dependencies** - How components interact within the system
|
||||||
|
- **External dependencies** - External libraries, services, databases, APIs
|
||||||
|
- **Data flow** - Direction of dependencies and interactions
|
||||||
|
- **Inheritance/composition** - Class hierarchies and composition relationships
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
subgraph "Component System"
|
||||||
|
A[Main Component] --> B[Internal Service]
|
||||||
|
A --> C[Internal Repository]
|
||||||
|
B --> D[Business Logic]
|
||||||
|
C --> E[Data Access Layer]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph "External Dependencies"
|
||||||
|
F[External API]
|
||||||
|
G[Database]
|
||||||
|
H[Third-party Library]
|
||||||
|
I[Configuration Service]
|
||||||
|
end
|
||||||
|
|
||||||
|
A --> F
|
||||||
|
E --> G
|
||||||
|
B --> H
|
||||||
|
A --> I
|
||||||
|
|
||||||
|
classDiagram
|
||||||
|
class MainComponent {
|
||||||
|
+property: Type
|
||||||
|
+method(): ReturnType
|
||||||
|
+asyncMethod(): Promise~Type~
|
||||||
|
}
|
||||||
|
class InternalService {
|
||||||
|
+businessOperation(): Result
|
||||||
|
}
|
||||||
|
class ExternalAPI {
|
||||||
|
<<external>>
|
||||||
|
+apiCall(): Data
|
||||||
|
}
|
||||||
|
|
||||||
|
MainComponent --> InternalService
|
||||||
|
MainComponent --> ExternalAPI
|
||||||
|
```
|
||||||
|
|
||||||
|
## 3. Interface Documentation
|
||||||
|
|
||||||
|
- INT-001: Document all public interfaces and usage patterns
|
||||||
|
- INT-002: Create method/property reference table
|
||||||
|
- INT-003: Document events/callbacks/notification mechanisms
|
||||||
|
|
||||||
|
| Method/Property | Purpose | Parameters | Return Type | Usage Notes |
|
||||||
|
|-----------------|---------|------------|-------------|-------------|
|
||||||
|
| [Name] | [Purpose] | [Parameters] | [Type] | [Notes] |
|
||||||
|
|
||||||
|
## 4. Implementation Details
|
||||||
|
|
||||||
|
- IMP-001: Document main implementation classes and responsibilities
|
||||||
|
- IMP-002: Describe configuration requirements and initialization
|
||||||
|
- IMP-003: Document key algorithms and business logic
|
||||||
|
- IMP-004: Note performance characteristics and bottlenecks
|
||||||
|
|
||||||
|
## 5. Usage Examples
|
||||||
|
|
||||||
|
### Basic Usage
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
// Basic usage example
|
||||||
|
var component = new ComponentName();
|
||||||
|
component.DoSomething();
|
||||||
|
```
|
||||||
|
|
||||||
|
### Advanced Usage
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
// Advanced configuration patterns
|
||||||
|
var options = new ComponentOptions();
|
||||||
|
var component = ComponentFactory.Create(options);
|
||||||
|
await component.ProcessAsync(data);
|
||||||
|
```
|
||||||
|
|
||||||
|
- USE-001: Provide basic usage examples
|
||||||
|
- USE-002: Show advanced configuration patterns
|
||||||
|
- USE-003: Document best practices and recommended patterns
|
||||||
|
|
||||||
|
## 6. Quality Attributes
|
||||||
|
|
||||||
|
- QUA-001: Security (authentication, authorization, data protection)
|
||||||
|
- QUA-002: Performance (characteristics, scalability, resource usage)
|
||||||
|
- QUA-003: Reliability (error handling, fault tolerance, recovery)
|
||||||
|
- QUA-004: Maintainability (standards, testing, documentation)
|
||||||
|
- QUA-005: Extensibility (extension points, customization options)
|
||||||
|
|
||||||
|
## 7. Reference Information
|
||||||
|
|
||||||
|
- REF-001: List dependencies with versions and purposes
|
||||||
|
- REF-002: Complete configuration options reference
|
||||||
|
- REF-003: Testing guidelines and mock setup
|
||||||
|
- REF-004: Troubleshooting (common issues, error messages)
|
||||||
|
- REF-005: Related documentation links
|
||||||
|
- REF-006: Change history and migration notes
|
||||||
|
|
||||||
|
```
|
||||||
127
prompts/create_specification.prompt.md
Normal file
127
prompts/create_specification.prompt.md
Normal file
@ -0,0 +1,127 @@
|
|||||||
|
---
|
||||||
|
mode: 'agent'
|
||||||
|
description: Create a new specification file for the solution, optimized for Generative AI consumption.
|
||||||
|
tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'githubRepo', 'openSimpleBrowser', 'problems', 'runTasks', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure', 'usages', 'vscodeAPI']
|
||||||
|
---
|
||||||
|
# Create Specification Prompt
|
||||||
|
|
||||||
|
Your goal is to create a new specification file for `${input:SpecPurpose}`.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
**Best Practices for AI-Ready Specifications:**
|
||||||
|
|
||||||
|
- Use precise, explicit, and unambiguous language.
|
||||||
|
- Clearly distinguish between requirements, constraints, and recommendations.
|
||||||
|
- Use structured formatting (headings, lists, tables) for easy parsing.
|
||||||
|
- Avoid idioms, metaphors, or context-dependent references.
|
||||||
|
- Define all acronyms and domain-specific terms.
|
||||||
|
- Include examples and edge cases where applicable.
|
||||||
|
- Ensure the document is self-contained and does not rely on external context.
|
||||||
|
|
||||||
|
The specification should be saved in the [/spec/](/spec/) directory and named according to the following convention: `spec-[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].
|
||||||
|
|
||||||
|
The specification file must be formatted in well formed Markdown.
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
```md
|
||||||
|
---
|
||||||
|
title: [Concise Title Describing the Specification's Focus]
|
||||||
|
version: [Optional: e.g., 1.0, Date]
|
||||||
|
date_created: [YYYY-MM-DD]
|
||||||
|
last_updated: [Optional: YYYY-MM-DD]
|
||||||
|
owner: [Optional: Team/Individual responsible for this spec]
|
||||||
|
tags: [Optional: List of relevant tags or categories, e.g., `infrastructure`, `process`, `design`, `app` etc]
|
||||||
|
---
|
||||||
|
|
||||||
|
# Introduction
|
||||||
|
|
||||||
|
[A short concise introduction to the specification and the goal it is intended to achieve.]
|
||||||
|
|
||||||
|
## 1. Purpose & Scope
|
||||||
|
|
||||||
|
[Provide a clear, concise description of the specification's purpose and the scope of its application. State the intended audience and any assumptions.]
|
||||||
|
|
||||||
|
## 2. Definitions
|
||||||
|
|
||||||
|
[List and define all acronyms, abbreviations, and domain-specific terms used in this specification.]
|
||||||
|
|
||||||
|
## 3. Requirements, Constraints & Guidelines
|
||||||
|
|
||||||
|
[Explicitly list all requirements, constraints, rules, and guidelines. Use bullet points or tables for clarity.]
|
||||||
|
|
||||||
|
- **REQ-001**: Requirement 1
|
||||||
|
- **SEC-001**: Security Requirement 1
|
||||||
|
- **[3 LETTERS]-001**: Other Requirement 1
|
||||||
|
- **CON-001**: Constraint 1
|
||||||
|
- **GUD-001**: Guideline 1
|
||||||
|
- **PAT-001**: Pattern to follow 1
|
||||||
|
|
||||||
|
## 4. Interfaces & Data Contracts
|
||||||
|
|
||||||
|
[Describe the interfaces, APIs, data contracts, or integration points. Use tables or code blocks for schemas and examples.]
|
||||||
|
|
||||||
|
## 5. Acceptance Criteria
|
||||||
|
|
||||||
|
[Define clear, testable acceptance criteria for each requirement using Given-When-Then format where appropriate.]
|
||||||
|
|
||||||
|
- **AC-001**: Given [context], When [action], Then [expected outcome]
|
||||||
|
- **AC-002**: The system shall [specific behavior] when [condition]
|
||||||
|
- **AC-003**: [Additional acceptance criteria as needed]
|
||||||
|
|
||||||
|
## 6. Test Automation Strategy
|
||||||
|
|
||||||
|
[Define the testing approach, frameworks, and automation requirements.]
|
||||||
|
|
||||||
|
- **Test Levels**: Unit, Integration, End-to-End
|
||||||
|
- **Frameworks**: MSTest, FluentAssertions, Moq (for .NET applications)
|
||||||
|
- **Test Data Management**: [approach for test data creation and cleanup]
|
||||||
|
- **CI/CD Integration**: [automated testing in GitHub Actions pipelines]
|
||||||
|
- **Coverage Requirements**: [minimum code coverage thresholds]
|
||||||
|
- **Performance Testing**: [approach for load and performance testing]
|
||||||
|
|
||||||
|
## 7. Rationale & Context
|
||||||
|
|
||||||
|
[Explain the reasoning behind the requirements, constraints, and guidelines. Provide context for design decisions.]
|
||||||
|
|
||||||
|
## 8. Dependencies & External Integrations
|
||||||
|
|
||||||
|
[Define the external systems, services, and architectural dependencies required for this specification. Focus on **what** is needed rather than **how** it's implemented. Avoid specific package or library versions unless they represent architectural constraints.]
|
||||||
|
|
||||||
|
### External Systems
|
||||||
|
- **EXT-001**: [External system name] - [Purpose and integration type]
|
||||||
|
|
||||||
|
### Third-Party Services
|
||||||
|
- **SVC-001**: [Service name] - [Required capabilities and SLA requirements]
|
||||||
|
|
||||||
|
### Infrastructure Dependencies
|
||||||
|
- **INF-001**: [Infrastructure component] - [Requirements and constraints]
|
||||||
|
|
||||||
|
### Data Dependencies
|
||||||
|
- **DAT-001**: [External data source] - [Format, frequency, and access requirements]
|
||||||
|
|
||||||
|
### Technology Platform Dependencies
|
||||||
|
- **PLT-001**: [Platform/runtime requirement] - [Version constraints and rationale]
|
||||||
|
|
||||||
|
### Compliance Dependencies
|
||||||
|
- **COM-001**: [Regulatory or compliance requirement] - [Impact on implementation]
|
||||||
|
|
||||||
|
**Note**: This section should focus on architectural and business dependencies, not specific package implementations. For example, specify "OAuth 2.0 authentication library" rather than "Microsoft.AspNetCore.Authentication.JwtBearer v6.0.1".
|
||||||
|
|
||||||
|
## 9. Examples & Edge Cases
|
||||||
|
|
||||||
|
```code
|
||||||
|
// Code snippet or data example demonstrating the correct application of the guidelines, including edge cases
|
||||||
|
```
|
||||||
|
|
||||||
|
## 10. Validation Criteria
|
||||||
|
|
||||||
|
[List the criteria or tests that must be satisfied for compliance with this specification.]
|
||||||
|
|
||||||
|
## 11. Related Specifications / Further Reading
|
||||||
|
|
||||||
|
[Link to related spec 1]
|
||||||
|
[Link to relevant external documentation]
|
||||||
|
|
||||||
|
```
|
||||||
83
prompts/dotnet_best_practices.prompt.md
Normal file
83
prompts/dotnet_best_practices.prompt.md
Normal file
@ -0,0 +1,83 @@
|
|||||||
|
---
|
||||||
|
mode: 'edit'
|
||||||
|
---
|
||||||
|
# .NET/C# Best Practices
|
||||||
|
|
||||||
|
Your task is to ensure .NET/C# code in ${selection} meets the best practices specific to the this soltion/project. This includes:
|
||||||
|
|
||||||
|
## Documentation & Structure
|
||||||
|
|
||||||
|
- Create comprehensive XML documentation comments for all public classes, interfaces, methods, and properties
|
||||||
|
- Include parameter descriptions and return value descriptions in XML comments
|
||||||
|
- Follow the established namespace structure: {Core|Console|App|Service}.{Feature}
|
||||||
|
|
||||||
|
## Design Patterns & Architecture
|
||||||
|
|
||||||
|
- Use primary constructor syntax for dependency injection (e.g., `public class MyClass(IDependency dependency)`)
|
||||||
|
- Implement the Command Handler pattern with generic base classes (e.g., `CommandHandler<TOptions>`)
|
||||||
|
- Use interface segregation with clear naming conventions (prefix interfaces with 'I')
|
||||||
|
- Follow the Factory pattern for complex object creation.
|
||||||
|
|
||||||
|
## Dependency Injection & Services
|
||||||
|
|
||||||
|
- Use constructor dependency injection with null checks via ArgumentNullException
|
||||||
|
- Register services with appropriate lifetimes (Singleton, Scoped, Transient)
|
||||||
|
- Use Microsoft.Extensions.DependencyInjection patterns
|
||||||
|
- Implement service interfaces for testability
|
||||||
|
|
||||||
|
## Resource Management & Localization
|
||||||
|
|
||||||
|
- Use ResourceManager for localized messages and error strings
|
||||||
|
- Separate LogMessages and ErrorMessages resource files
|
||||||
|
- Access resources via `_resourceManager.GetString("MessageKey")`
|
||||||
|
|
||||||
|
## Async/Await Patterns
|
||||||
|
|
||||||
|
- Use async/await for all I/O operations and long-running tasks
|
||||||
|
- Return Task or Task<T> from async methods
|
||||||
|
- Use ConfigureAwait(false) where appropriate
|
||||||
|
- Handle async exceptions properly
|
||||||
|
|
||||||
|
## Testing Standards
|
||||||
|
|
||||||
|
- Use MSTest framework with FluentAssertions for assertions
|
||||||
|
- Follow AAA pattern (Arrange, Act, Assert)
|
||||||
|
- Use Moq for mocking dependencies
|
||||||
|
- Test both success and failure scenarios
|
||||||
|
- Include null parameter validation tests
|
||||||
|
|
||||||
|
## Configuration & Settings
|
||||||
|
|
||||||
|
- Use strongly-typed configuration classes with data annotations
|
||||||
|
- Implement validation attributes (Required, NotEmptyOrWhitespace)
|
||||||
|
- Use IConfiguration binding for settings
|
||||||
|
- Support appsettings.json configuration files
|
||||||
|
|
||||||
|
## Semantic Kernel & AI Integration
|
||||||
|
|
||||||
|
- Use Microsoft.SemanticKernel for AI operations
|
||||||
|
- Implement proper kernel configuration and service registration
|
||||||
|
- Handle AI model settings (ChatCompletion, Embedding, etc.)
|
||||||
|
- Use structured output patterns for reliable AI responses
|
||||||
|
|
||||||
|
## Error Handling & Logging
|
||||||
|
|
||||||
|
- Use structured logging with Microsoft.Extensions.Logging
|
||||||
|
- Include scoped logging with meaningful context
|
||||||
|
- Throw specific exceptions with descriptive messages
|
||||||
|
- Use try-catch blocks for expected failure scenarios
|
||||||
|
|
||||||
|
## Performance & Security
|
||||||
|
|
||||||
|
- Use C# 12+ features and .NET 8 optimizations where applicable
|
||||||
|
- Implement proper input validation and sanitization
|
||||||
|
- Use parameterized queries for database operations
|
||||||
|
- Follow secure coding practices for AI/ML operations
|
||||||
|
|
||||||
|
## Code Quality
|
||||||
|
|
||||||
|
- Ensure SOLID principles compliance
|
||||||
|
- Avoid code duplication through base classes and utilities
|
||||||
|
- Use meaningful names that reflect domain concepts
|
||||||
|
- Keep methods focused and cohesive
|
||||||
|
- Implement proper disposal patterns for resources
|
||||||
40
prompts/dotnet_design_pattern_review.prompt.md
Normal file
40
prompts/dotnet_design_pattern_review.prompt.md
Normal file
@ -0,0 +1,40 @@
|
|||||||
|
---
|
||||||
|
mode: 'ask'
|
||||||
|
---
|
||||||
|
# .NET/C# Design Pattern Review
|
||||||
|
|
||||||
|
Review the C#/.NET code in ${selection} for design pattern implementation and suggest improvements for the solution/project.
|
||||||
|
|
||||||
|
## Required Design Patterns
|
||||||
|
|
||||||
|
- **Command Pattern**: Generic base classes (`CommandHandler<TOptions>`), `ICommandHandler<TOptions>` interface, `CommandHandlerOptions` inheritance, static `SetupCommand(IHost host)` methods
|
||||||
|
- **Factory Pattern**: Complex object creation service provider integration
|
||||||
|
- **Dependency Injection**: Primary constructor syntax, `ArgumentNullException` null checks, interface abstractions, proper service lifetimes
|
||||||
|
- **Repository Pattern**: Async data access interfaces provider abstractions for connections
|
||||||
|
- **Provider Pattern**: External service abstractions (database, AI), clear contracts, configuration handling
|
||||||
|
- **Resource Pattern**: ResourceManager for localized messages, separate .resx files (LogMessages, ErrorMessages)
|
||||||
|
|
||||||
|
## Review Checklist
|
||||||
|
|
||||||
|
- **Design Patterns**: Identify patterns used. Are Command Handler, Factory, Provider, and Repository patterns correctly implemented? Missing beneficial patterns?
|
||||||
|
- **Architecture**: Follow namespace conventions (`{Core|Console|App|Service}.{Feature}`)? Proper separation between Core/Console projects? Modular and readable?
|
||||||
|
- **.NET Best Practices**: Primary constructors, async/await with Task returns, ResourceManager usage, structured logging, strongly-typed configuration?
|
||||||
|
- **GoF Patterns**: Command, Factory, Template Method, Strategy patterns correctly implemented?
|
||||||
|
- **SOLID Principles**: Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion violations?
|
||||||
|
- **Performance**: Proper async/await, resource disposal, ConfigureAwait(false), parallel processing opportunities?
|
||||||
|
- **Maintainability**: Clear separation of concerns, consistent error handling, proper configuration usage?
|
||||||
|
- **Testability**: Dependencies abstracted via interfaces, mockable components, async testability, AAA pattern compatibility?
|
||||||
|
- **Security**: Input validation, secure credential handling, parameterized queries, safe exception handling?
|
||||||
|
- **Documentation**: XML docs for public APIs, parameter/return descriptions, resource file organization?
|
||||||
|
- **Code Clarity**: Meaningful names reflecting domain concepts, clear intent through patterns, self-explanatory structure?
|
||||||
|
- **Clean Code**: Consistent style, appropriate method/class size, minimal complexity, eliminated duplication?
|
||||||
|
|
||||||
|
## Improvement Focus Areas
|
||||||
|
|
||||||
|
- **Command Handlers**: Validation in base class, consistent error handling, proper resource management
|
||||||
|
- **Factories**: Dependency configuration, service provider integration, disposal patterns
|
||||||
|
- **Providers**: Connection management, async patterns, exception handling and logging
|
||||||
|
- **Configuration**: Data annotations, validation attributes, secure sensitive value handling
|
||||||
|
- **AI/ML Integration**: Semantic Kernel patterns, structured output handling, model configuration
|
||||||
|
|
||||||
|
Provide specific, actionable recommendations for improvements aligned with the project's architecture and .NET best practices.
|
||||||
47
prompts/update_avm_modules_in_bicep.prompt.md
Normal file
47
prompts/update_avm_modules_in_bicep.prompt.md
Normal file
@ -0,0 +1,47 @@
|
|||||||
|
---
|
||||||
|
mode: 'agent'
|
||||||
|
description: 'Update Azure Verified Modules to latest versions in Bicep files.'
|
||||||
|
tools: ['changes', 'codebase', 'editFiles', 'fetch', 'runCommands', 'azure_get_deployment_best_practices', 'azure_get_schema_for_Bicep']
|
||||||
|
---
|
||||||
|
# Update Azure Verified Modules in Bicep Files
|
||||||
|
|
||||||
|
Update Bicep file `${file}` to use latest Azure Verified Module (AVM) versions.
|
||||||
|
|
||||||
|
## Process
|
||||||
|
|
||||||
|
1. **Scan**: Extract AVM modules and current versions from `${file}`
|
||||||
|
2. **Check**: Fetch latest versions from MCR: `https://mcr.microsoft.com/v2/bicep/avm/res/{service}/{resource}/tags/list`
|
||||||
|
3. **Compare**: Parse semantic versions to identify updates
|
||||||
|
4. **Review**: For breaking changes, fetch docs from: `https://github.com/Azure/bicep-registry-modules/tree/main/avm/res/{service}/{resource}`
|
||||||
|
5. **Update**: Apply version updates and parameter changes
|
||||||
|
6. **Validate**: Run `bicep lint` to ensure compliance
|
||||||
|
|
||||||
|
## Breaking Change Policy
|
||||||
|
|
||||||
|
⚠️ **PAUSE for approval** if updates involve:
|
||||||
|
- Incompatible parameter changes
|
||||||
|
- Security/compliance modifications
|
||||||
|
- Behavioral changes
|
||||||
|
|
||||||
|
## Output Format
|
||||||
|
|
||||||
|
Display results in table with icons:
|
||||||
|
|
||||||
|
| Module | Current | Latest | Status | Action | Docs |
|
||||||
|
|--------|---------|--------|--------|--------|------|
|
||||||
|
| avm/res/compute/vm | 0.1.0 | 0.2.0 | 🔄 | Updated | [📖](link) |
|
||||||
|
| avm/res/storage/account | 0.3.0 | 0.3.0 | ✅ | Current | [📖](link) |
|
||||||
|
|
||||||
|
## Icons
|
||||||
|
|
||||||
|
- 🔄 Updated
|
||||||
|
- ✅ Current
|
||||||
|
- ⚠️ Manual review required
|
||||||
|
- ❌ Failed
|
||||||
|
- 📖 Documentation
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- Use MCR tags API only for version discovery
|
||||||
|
- Parse JSON tags array and sort by semantic versioning
|
||||||
|
- Maintain Bicep file validity and linting compliance
|
||||||
144
prompts/update_implementation_plan.prompt.md
Normal file
144
prompts/update_implementation_plan.prompt.md
Normal file
@ -0,0 +1,144 @@
|
|||||||
|
---
|
||||||
|
mode: 'agent'
|
||||||
|
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.
|
||||||
|
tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'githubRepo', 'openSimpleBrowser', 'problems', 'runTasks', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure', 'usages', 'vscodeAPI']
|
||||||
|
---
|
||||||
|
# Implementation Plan Update Prompt
|
||||||
|
|
||||||
|
**PRIMARY DIRECTIVE**: You are an AI agent tasked with updating the implementation plan file `${file}` based on new or updated requirements. Your output must be machine-readable, deterministic, and structured for autonomous execution by other AI systems or humans.
|
||||||
|
|
||||||
|
**EXECUTION CONTEXT**: This prompt is designed for AI-to-AI communication and automated processing. All instructions must be interpreted literally and executed systematically without human interpretation or clarification.
|
||||||
|
|
||||||
|
**CORE REQUIREMENTS**:
|
||||||
|
|
||||||
|
- Generate implementation plans that are fully executable by AI agents or humans
|
||||||
|
- Use deterministic language with zero ambiguity
|
||||||
|
- Structure all content for automated parsing and execution
|
||||||
|
- Ensure complete self-containment with no external dependencies for understanding
|
||||||
|
|
||||||
|
**PLAN STRUCTURE REQUIREMENTS**:
|
||||||
|
Plans must consist of discrete, atomic phases containing executable tasks. Each phase must be independently processable by AI agents or humans without cross-phase dependencies unless explicitly declared.
|
||||||
|
|
||||||
|
**PHASE ARCHITECTURE**:
|
||||||
|
|
||||||
|
- Each phase must have measurable completion criteria
|
||||||
|
- Tasks within phases must be executable in parallel unless dependencies are specified
|
||||||
|
- All task descriptions must include specific file paths, function names, and exact implementation details
|
||||||
|
- No task should require human interpretation or decision-making
|
||||||
|
|
||||||
|
**AI-OPTIMIZED IMPLEMENTATION STANDARDS**:
|
||||||
|
|
||||||
|
- Use explicit, unambiguous language with zero interpretation required
|
||||||
|
- Structure all content as machine-parseable formats (tables, lists, structured data)
|
||||||
|
- Include specific file paths, line numbers, and exact code references where applicable
|
||||||
|
- Define all variables, constants, and configuration values explicitly
|
||||||
|
- Provide complete context within each task description
|
||||||
|
- Use standardized prefixes for all identifiers (REQ-, TASK-, etc.)
|
||||||
|
- Include validation criteria that can be automatically verified
|
||||||
|
|
||||||
|
**OUTPUT FILE SPECIFICATIONS**:
|
||||||
|
|
||||||
|
- Save implementation plan files in `/plan/` directory
|
||||||
|
- Use naming convention: `[purpose]-[component]-[version].md`
|
||||||
|
- Purpose prefixes: `upgrade|refactor|feature|data|infrastructure|process|architecture|design`
|
||||||
|
- Example: `upgrade-system-command-4.md`, `feature-auth-module-1.md`
|
||||||
|
- File must be valid Markdown with proper front matter structure
|
||||||
|
|
||||||
|
**MANDATORY TEMPLATE STRUCTURE**:
|
||||||
|
All implementation plans must strictly adhere to the following template. Each section is required and must be populated with specific, actionable content. AI agents must validate template compliance before execution.
|
||||||
|
|
||||||
|
**TEMPLATE VALIDATION RULES**:
|
||||||
|
|
||||||
|
- All front matter fields must be present and properly formatted
|
||||||
|
- All section headers must match exactly (case-sensitive)
|
||||||
|
- All identifier prefixes must follow the specified format
|
||||||
|
- Tables must include all required columns
|
||||||
|
- No placeholder text may remain in the final output
|
||||||
|
|
||||||
|
```md
|
||||||
|
---
|
||||||
|
goal: [Concise Title Describing the Package Implementation Plan's Goal]
|
||||||
|
version: [Optional: e.g., 1.0, Date]
|
||||||
|
date_created: [YYYY-MM-DD]
|
||||||
|
last_updated: [Optional: YYYY-MM-DD]
|
||||||
|
owner: [Optional: Team/Individual responsible for this spec]
|
||||||
|
tags: [Optional: List of relevant tags or categories, e.g., `feature`, `upgrade`, `chore`, `architecture`, `migration`, `bug` etc]
|
||||||
|
---
|
||||||
|
|
||||||
|
# Introduction
|
||||||
|
|
||||||
|
[A short concise introduction to the plan and the goal it is intended to achieve.]
|
||||||
|
|
||||||
|
## 1. Requirements & Constraints
|
||||||
|
|
||||||
|
[Explicitly list all requirements & constraints that affect the plan and constrain how it is implemented. Use bullet points or tables for clarity.]
|
||||||
|
|
||||||
|
- **REQ-001**: Requirement 1
|
||||||
|
- **SEC-001**: Security Requirement 1
|
||||||
|
- **[3 LETTERS]-001**: Other Requirement 1
|
||||||
|
- **CON-001**: Constraint 1
|
||||||
|
- **GUD-001**: Guideline 1
|
||||||
|
- **PAT-001**: Pattern to follow 1
|
||||||
|
|
||||||
|
## 2. Implementation Steps
|
||||||
|
|
||||||
|
### Implementation Phase 1
|
||||||
|
|
||||||
|
- GOAL-001: [Describe the goal of this phase, e.g., "Implement feature X", "Refactor module Y", etc.]
|
||||||
|
|
||||||
|
| Task | Description | Completed | Date |
|
||||||
|
|------|-------------|-----------|------|
|
||||||
|
| TASK-001 | Description of task 1 | ✅ | 2025-04-25 |
|
||||||
|
| TASK-002 | Description of task 2 | | |
|
||||||
|
| TASK-003 | Description of task 3 | | |
|
||||||
|
|
||||||
|
### Implementation Phase 2
|
||||||
|
|
||||||
|
- GOAL-002: [Describe the goal of this phase, e.g., "Implement feature X", "Refactor module Y", etc.]
|
||||||
|
|
||||||
|
| Task | Description | Completed | Date |
|
||||||
|
|------|-------------|-----------|------|
|
||||||
|
| TASK-004 | Description of task 4 | | |
|
||||||
|
| TASK-005 | Description of task 5 | | |
|
||||||
|
| TASK-006 | Description of task 6 | | |
|
||||||
|
|
||||||
|
## 3. Alternatives
|
||||||
|
|
||||||
|
[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.]
|
||||||
|
|
||||||
|
- **ALT-001**: Alternative approach 1
|
||||||
|
- **ALT-002**: Alternative approach 2
|
||||||
|
|
||||||
|
## 4. Dependencies
|
||||||
|
|
||||||
|
[List any dependencies that need to be addressed, such as libraries, frameworks, or other components that the plan relies on.]
|
||||||
|
|
||||||
|
- **DEP-001**: Dependency 1
|
||||||
|
- **DEP-002**: Dependency 2
|
||||||
|
|
||||||
|
## 5. Files
|
||||||
|
|
||||||
|
[List the files that will be affected by the feature or refactoring task.]
|
||||||
|
|
||||||
|
- **FILE-001**: Description of file 1
|
||||||
|
- **FILE-002**: Description of file 2
|
||||||
|
|
||||||
|
## 6. Testing
|
||||||
|
|
||||||
|
[List the tests that need to be implemented to verify the feature or refactoring task.]
|
||||||
|
|
||||||
|
- **TEST-001**: Description of test 1
|
||||||
|
- **TEST-002**: Description of test 2
|
||||||
|
|
||||||
|
## 7. Risks & Assumptions
|
||||||
|
|
||||||
|
[List any risks or assumptions related to the implementation of the plan.]
|
||||||
|
|
||||||
|
- **RISK-001**: Risk 1
|
||||||
|
- **ASSUMPTION-001**: Assumption 1
|
||||||
|
|
||||||
|
## 8. Related Specifications / Further Reading
|
||||||
|
|
||||||
|
[Link to related spec 1]
|
||||||
|
[Link to relevant external documentation]
|
||||||
|
```
|
||||||
38
prompts/update_llms.prompt.md
Normal file
38
prompts/update_llms.prompt.md
Normal file
@ -0,0 +1,38 @@
|
|||||||
|
---
|
||||||
|
mode: 'agent'
|
||||||
|
description: 'Update the llms.txt file in the root folder to reflect changes in documentation or specifications'
|
||||||
|
tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'githubRepo', 'openSimpleBrowser', 'problems', 'runTasks', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure', 'usages', 'vscodeAPI']
|
||||||
|
---
|
||||||
|
# Update LLMs Guidance File
|
||||||
|
|
||||||
|
Your task is to update the [llms.txt](/llms.txt) file located in the root of the repository. This file provides high-level guidance to large language models (LLMs) on where to find relevant content for understanding the solution's purpose and specifications.
|
||||||
|
|
||||||
|
**Instructions:**
|
||||||
|
|
||||||
|
- Ensure the `llms.txt` file accurately references all folders and files that are important for LLM comprehension, including the `specs/` folder (for machine-readable specifications) and the `docs/` folder (for developer and user documentation).
|
||||||
|
- If new documentation or specification folders/files are added, update `llms.txt` accordingly.
|
||||||
|
- Use clear, concise language and structured formatting for easy parsing by LLMs.
|
||||||
|
- Do not include implementation details or code—focus on navigation and content discovery.
|
||||||
|
|
||||||
|
Example structure for `llms.txt`:
|
||||||
|
|
||||||
|
```txt
|
||||||
|
# Solution: [Concise Title Describing the Solution's Purpose]
|
||||||
|
|
||||||
|
**Version:** [Optional: e.g., 1.0, Date]
|
||||||
|
**Last Updated:** [Optional: YYYY-MM-DD]
|
||||||
|
**Owner:** [Optional: Team/Individual responsible for this solution]
|
||||||
|
**GitHub Repository:** https://github.com/PlagueHO/azure-ai-foundry-jumpstart
|
||||||
|
|
||||||
|
## 1. Purpose & Scope
|
||||||
|
|
||||||
|
[Provide a clear, concise description of the purpose of this repository and scope of its solution. State the intended audience and any assumptions.]
|
||||||
|
|
||||||
|
## 2. Folder Structure
|
||||||
|
|
||||||
|
[Describe the structure of the repository, including the purpose of each folder and file. Use visual folder structure. Include subfolders where applicable.]
|
||||||
|
|
||||||
|
## 3. Important Files
|
||||||
|
|
||||||
|
[Explicitly list all important files, their purpose, and how they relate to the solution. Use bullet points or tables for clarity.]
|
||||||
|
```
|
||||||
76
prompts/update_markdown_file_index.prompt.md
Normal file
76
prompts/update_markdown_file_index.prompt.md
Normal file
@ -0,0 +1,76 @@
|
|||||||
|
---
|
||||||
|
mode: 'agent'
|
||||||
|
description: 'Update a markdown file section with an index/table of files from a specified folder.'
|
||||||
|
tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'findTestFiles', 'githubRepo', 'openSimpleBrowser', 'problems', 'runCommands', 'runTasks', 'runTests', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure', 'updateUserPreferences', 'usages', 'vscodeAPI', 'ado']
|
||||||
|
---
|
||||||
|
# Update Markdown File Index
|
||||||
|
|
||||||
|
Update markdown file `${file}` with an index/table of files from folder `${input:folder}`.
|
||||||
|
|
||||||
|
## Process
|
||||||
|
|
||||||
|
1. **Scan**: Read the target markdown file `${file}` to understand existing structure
|
||||||
|
2. **Discover**: List all files in the specified folder `${input:folder}` matching pattern `${input:pattern}`
|
||||||
|
3. **Analyze**: Identify if an existing table/index section exists to update, or create new structure
|
||||||
|
4. **Structure**: Generate appropriate table/list format based on file types and existing content
|
||||||
|
5. **Update**: Replace existing section or add new section with file index
|
||||||
|
6. **Validate**: Ensure markdown syntax is valid and formatting is consistent
|
||||||
|
|
||||||
|
## File Analysis
|
||||||
|
|
||||||
|
For each discovered file, extract:
|
||||||
|
|
||||||
|
- **Name**: Filename with or without extension based on context
|
||||||
|
- **Type**: File extension and category (e.g., `.md`, `.js`, `.py`)
|
||||||
|
- **Description**: First line comment, header, or inferred purpose
|
||||||
|
- **Size**: File size for reference (optional)
|
||||||
|
- **Modified**: Last modified date (optional)
|
||||||
|
|
||||||
|
## Table Structure Options
|
||||||
|
|
||||||
|
Choose format based on file types and existing content:
|
||||||
|
|
||||||
|
### Option 1: Simple List
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Files in ${folder}
|
||||||
|
|
||||||
|
- [filename.ext](path/to/filename.ext) - Description
|
||||||
|
- [filename2.ext](path/to/filename2.ext) - Description
|
||||||
|
```
|
||||||
|
|
||||||
|
### Option 2: Detailed Table
|
||||||
|
|
||||||
|
| File | Type | Description |
|
||||||
|
|------|------|-------------|
|
||||||
|
| [filename.ext](path/to/filename.ext) | Extension | Description |
|
||||||
|
| [filename2.ext](path/to/filename2.ext) | Extension | Description |
|
||||||
|
|
||||||
|
### Option 3: Categorized Sections
|
||||||
|
|
||||||
|
Group files by type/category with separate sections or sub-tables.
|
||||||
|
|
||||||
|
## Update Strategy
|
||||||
|
|
||||||
|
- 🔄 **Update existing**: If table/index section exists, replace content while preserving structure
|
||||||
|
- ➕ **Add new**: If no existing section, create new section using best-fit format
|
||||||
|
- 📋 **Preserve**: Maintain existing markdown formatting, heading levels, and document flow
|
||||||
|
- 🔗 **Links**: Use relative paths for file links within the repository
|
||||||
|
|
||||||
|
## Section Identification
|
||||||
|
|
||||||
|
Look for existing sections with these patterns:
|
||||||
|
|
||||||
|
- Headings containing: "index", "files", "contents", "directory", "list"
|
||||||
|
- Tables with file-related columns
|
||||||
|
- Lists with file links
|
||||||
|
- HTML comments marking file index sections
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- Preserve existing markdown structure and formatting
|
||||||
|
- Use relative paths for file links
|
||||||
|
- Include file descriptions when available
|
||||||
|
- Sort files alphabetically by default
|
||||||
|
- Handle special characters in filenames
|
||||||
|
- Validate all generated markdown syntax
|
||||||
162
prompts/update_oo_component_documentation.prompt.md
Normal file
162
prompts/update_oo_component_documentation.prompt.md
Normal file
@ -0,0 +1,162 @@
|
|||||||
|
---
|
||||||
|
mode: 'agent'
|
||||||
|
description: 'Update existing object-oriented component documentation following industry best practices and architectural documentation standards.'
|
||||||
|
tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'githubRepo', 'openSimpleBrowser', 'problems', 'runTasks', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure', 'usages', 'vscodeAPI']
|
||||||
|
---
|
||||||
|
# Update Standard OO Component Documentation
|
||||||
|
|
||||||
|
Update the existing documentation file at: `${file}` by analyzing the corresponding component code.
|
||||||
|
|
||||||
|
Extract the component path from the existing documentation's front matter (`component_path` field) or infer it from the documentation content. Analyze the current component implementation and update the documentation accordingly.
|
||||||
|
|
||||||
|
**Documentation Standards:**
|
||||||
|
|
||||||
|
- DOC-001: Follow C4 Model documentation levels (Context, Containers, Components, Code)
|
||||||
|
- DOC-002: Align with Arc42 software architecture documentation template
|
||||||
|
- DOC-003: Comply with IEEE 1016 Software Design Description standard
|
||||||
|
- DOC-004: Use Agile Documentation principles (just enough documentation that adds value)
|
||||||
|
- DOC-005: Target developers and maintainers as primary audience
|
||||||
|
|
||||||
|
**Analysis Instructions:**
|
||||||
|
|
||||||
|
- ANA-001: Read existing documentation to understand component context and structure
|
||||||
|
- ANA-002: Identify component path from front matter or content analysis
|
||||||
|
- ANA-003: Examine current source code files for class structures and inheritance
|
||||||
|
- ANA-004: Compare existing documentation with current implementation
|
||||||
|
- ANA-005: Identify design patterns and architectural changes
|
||||||
|
- ANA-006: Update public APIs, interfaces, and dependencies
|
||||||
|
- ANA-007: Recognize new/changed creational/structural/behavioral patterns
|
||||||
|
- ANA-008: Update method parameters, return values, exceptions
|
||||||
|
- ANA-009: Reassess performance, security, reliability, maintainability
|
||||||
|
- ANA-010: Update integration patterns and data flow
|
||||||
|
|
||||||
|
**Language-Specific Optimizations:**
|
||||||
|
|
||||||
|
- LNG-001: **C#/.NET** - async/await, dependency injection, configuration, disposal
|
||||||
|
- LNG-002: **Java** - Spring framework, annotations, exception handling, packaging
|
||||||
|
- LNG-003: **TypeScript/JavaScript** - modules, async patterns, types, npm
|
||||||
|
- LNG-004: **Python** - packages, virtual environments, type hints, testing
|
||||||
|
|
||||||
|
**Update Strategy:**
|
||||||
|
|
||||||
|
- UPD-001: Preserve existing documentation structure and format
|
||||||
|
- UPD-002: Update `last_updated` field to current date
|
||||||
|
- UPD-003: Maintain version history in front matter if present
|
||||||
|
- UPD-004: Add new sections if component has significantly expanded
|
||||||
|
- UPD-005: Mark deprecated features or breaking changes
|
||||||
|
- UPD-006: Update examples to reflect current API
|
||||||
|
- UPD-007: Refresh dependency lists and versions
|
||||||
|
- UPD-008: Update mermaid diagrams to reflect current architecture
|
||||||
|
|
||||||
|
**Error Handling:**
|
||||||
|
|
||||||
|
- ERR-001: Documentation file doesn't exist - provide guidance on file location
|
||||||
|
- ERR-002: Component path not found in documentation - request clarification
|
||||||
|
- ERR-003: Source code has moved - suggest updated paths
|
||||||
|
- ERR-004: Major architectural changes - highlight breaking changes
|
||||||
|
- ERR-005: Insufficient access to source - document limitations
|
||||||
|
|
||||||
|
**Output Format:**
|
||||||
|
|
||||||
|
Update the existing Markdown file maintaining its structure while refreshing content to match current implementation. Preserve formatting, heading hierarchy, and existing organizational decisions.
|
||||||
|
|
||||||
|
**Required Documentation Structure:**
|
||||||
|
|
||||||
|
Update the existing documentation following the same template structure, ensuring all sections reflect current implementation:
|
||||||
|
|
||||||
|
```md
|
||||||
|
---
|
||||||
|
title: [Component Name] - Technical Documentation
|
||||||
|
component_path: [Current component path]
|
||||||
|
version: [Updated version if applicable]
|
||||||
|
date_created: [Original creation date - preserve]
|
||||||
|
last_updated: [YYYY-MM-DD - update to current date]
|
||||||
|
owner: [Preserve existing or update if changed]
|
||||||
|
tags: [Update tags as needed based on current functionality]
|
||||||
|
---
|
||||||
|
|
||||||
|
# [Component Name] Documentation
|
||||||
|
|
||||||
|
[Update introduction to reflect current component purpose and capabilities]
|
||||||
|
|
||||||
|
## 1. Component Overview
|
||||||
|
|
||||||
|
### Purpose/Responsibility
|
||||||
|
- OVR-001: Update component's primary responsibility
|
||||||
|
- OVR-002: Refresh scope (included/excluded functionality)
|
||||||
|
- OVR-003: Update system context and relationships
|
||||||
|
|
||||||
|
## 2. Architecture Section
|
||||||
|
|
||||||
|
- ARC-001: Update design patterns used (Repository, Factory, Observer, etc.)
|
||||||
|
- ARC-002: Refresh internal and external dependencies with current purposes
|
||||||
|
- ARC-003: Update component interactions and relationships
|
||||||
|
- ARC-004: Update visual diagrams (UML class, sequence, component)
|
||||||
|
- ARC-005: Refresh mermaid diagram showing current component structure, relationships, and dependencies
|
||||||
|
|
||||||
|
### Component Structure and Dependencies Diagram
|
||||||
|
|
||||||
|
Update the mermaid diagram to show current:
|
||||||
|
- **Component structure** - Current classes, interfaces, and their relationships
|
||||||
|
- **Internal dependencies** - How components currently interact within the system
|
||||||
|
- **External dependencies** - Current external libraries, services, databases, APIs
|
||||||
|
- **Data flow** - Current direction of dependencies and interactions
|
||||||
|
- **Inheritance/composition** - Current class hierarchies and composition relationships
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
[Update diagram to reflect current architecture]
|
||||||
|
```
|
||||||
|
|
||||||
|
## 3. Interface Documentation
|
||||||
|
|
||||||
|
- INT-001: Update all public interfaces and current usage patterns
|
||||||
|
- INT-002: Refresh method/property reference table with current API
|
||||||
|
- INT-003: Update events/callbacks/notification mechanisms
|
||||||
|
|
||||||
|
| Method/Property | Purpose | Parameters | Return Type | Usage Notes |
|
||||||
|
|-----------------|---------|------------|-------------|-------------|
|
||||||
|
| [Update table with current API] | | | | |
|
||||||
|
|
||||||
|
## 4. Implementation Details
|
||||||
|
|
||||||
|
- IMP-001: Update main implementation classes and current responsibilities
|
||||||
|
- IMP-002: Refresh configuration requirements and initialization patterns
|
||||||
|
- IMP-003: Update key algorithms and business logic
|
||||||
|
- IMP-004: Update performance characteristics and bottlenecks
|
||||||
|
|
||||||
|
## 5. Usage Examples
|
||||||
|
|
||||||
|
### Basic Usage
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
// Update basic usage example to current API
|
||||||
|
```
|
||||||
|
|
||||||
|
### Advanced Usage
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
// Update advanced configuration patterns to current implementation
|
||||||
|
```
|
||||||
|
|
||||||
|
- USE-001: Update basic usage examples
|
||||||
|
- USE-002: Refresh advanced configuration patterns
|
||||||
|
- USE-003: Update best practices and recommended patterns
|
||||||
|
|
||||||
|
## 6. Quality Attributes
|
||||||
|
|
||||||
|
- QUA-001: Update security (authentication, authorization, data protection)
|
||||||
|
- QUA-002: Refresh performance (characteristics, scalability, resource usage)
|
||||||
|
- QUA-003: Update reliability (error handling, fault tolerance, recovery)
|
||||||
|
- QUA-004: Refresh maintainability (standards, testing, documentation)
|
||||||
|
- QUA-005: Update extensibility (extension points, customization options)
|
||||||
|
|
||||||
|
## 7. Reference Information
|
||||||
|
|
||||||
|
- REF-001: Update dependencies with current versions and purposes
|
||||||
|
- REF-002: Refresh configuration options reference
|
||||||
|
- REF-003: Update testing guidelines and mock setup
|
||||||
|
- REF-004: Refresh troubleshooting (common issues, error messages)
|
||||||
|
- REF-005: Update related documentation links
|
||||||
|
- REF-006: Add change history and migration notes for this update
|
||||||
|
|
||||||
|
```
|
||||||
127
prompts/update_specification.prompt.md
Normal file
127
prompts/update_specification.prompt.md
Normal file
@ -0,0 +1,127 @@
|
|||||||
|
---
|
||||||
|
mode: 'agent'
|
||||||
|
description: Update an existing specification file for the solution, optimized for Generative AI consumption based on new requirements or updates to any existing code.
|
||||||
|
tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'githubRepo', 'openSimpleBrowser', 'problems', 'runTasks', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure', 'usages', 'vscodeAPI']
|
||||||
|
---
|
||||||
|
# Update Specification
|
||||||
|
|
||||||
|
Your goal is to update the existing specification file `${file}` based on new requirements or updates to any existing code.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
**Best Practices for AI-Ready Specifications:**
|
||||||
|
|
||||||
|
- Use precise, explicit, and unambiguous language.
|
||||||
|
- Clearly distinguish between requirements, constraints, and recommendations.
|
||||||
|
- Use structured formatting (headings, lists, tables) for easy parsing.
|
||||||
|
- Avoid idioms, metaphors, or context-dependent references.
|
||||||
|
- Define all acronyms and domain-specific terms.
|
||||||
|
- Include examples and edge cases where applicable.
|
||||||
|
- Ensure the document is self-contained and does not rely on external context.
|
||||||
|
|
||||||
|
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].
|
||||||
|
|
||||||
|
The specification file must be formatted in well formed Markdown.
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
```md
|
||||||
|
---
|
||||||
|
title: [Concise Title Describing the Specification's Focus]
|
||||||
|
version: [Optional: e.g., 1.0, Date]
|
||||||
|
date_created: [YYYY-MM-DD]
|
||||||
|
last_updated: [Optional: YYYY-MM-DD]
|
||||||
|
owner: [Optional: Team/Individual responsible for this spec]
|
||||||
|
tags: [Optional: List of relevant tags or categories, e.g., `infrastructure`, `process`, `design`, `app` etc]
|
||||||
|
---
|
||||||
|
|
||||||
|
# Introduction
|
||||||
|
|
||||||
|
[A short concise introduction to the specification and the goal it is intended to achieve.]
|
||||||
|
|
||||||
|
## 1. Purpose & Scope
|
||||||
|
|
||||||
|
[Provide a clear, concise description of the specification's purpose and the scope of its application. State the intended audience and any assumptions.]
|
||||||
|
|
||||||
|
## 2. Definitions
|
||||||
|
|
||||||
|
[List and define all acronyms, abbreviations, and domain-specific terms used in this specification.]
|
||||||
|
|
||||||
|
## 3. Requirements, Constraints & Guidelines
|
||||||
|
|
||||||
|
[Explicitly list all requirements, constraints, rules, and guidelines. Use bullet points or tables for clarity.]
|
||||||
|
|
||||||
|
- **REQ-001**: Requirement 1
|
||||||
|
- **SEC-001**: Security Requirement 1
|
||||||
|
- **[3 LETTERS]-001**: Other Requirement 1
|
||||||
|
- **CON-001**: Constraint 1
|
||||||
|
- **GUD-001**: Guideline 1
|
||||||
|
- **PAT-001**: Pattern to follow 1
|
||||||
|
|
||||||
|
## 4. Interfaces & Data Contracts
|
||||||
|
|
||||||
|
[Describe the interfaces, APIs, data contracts, or integration points. Use tables or code blocks for schemas and examples.]
|
||||||
|
|
||||||
|
## 5. Acceptance Criteria
|
||||||
|
|
||||||
|
[Define clear, testable acceptance criteria for each requirement using Given-When-Then format where appropriate.]
|
||||||
|
|
||||||
|
- **AC-001**: Given [context], When [action], Then [expected outcome]
|
||||||
|
- **AC-002**: The system shall [specific behavior] when [condition]
|
||||||
|
- **AC-003**: [Additional acceptance criteria as needed]
|
||||||
|
|
||||||
|
## 6. Test Automation Strategy
|
||||||
|
|
||||||
|
[Define the testing approach, frameworks, and automation requirements.]
|
||||||
|
|
||||||
|
- **Test Levels**: Unit, Integration, End-to-End
|
||||||
|
- **Frameworks**: MSTest, FluentAssertions, Moq (for .NET applications)
|
||||||
|
- **Test Data Management**: [approach for test data creation and cleanup]
|
||||||
|
- **CI/CD Integration**: [automated testing in GitHub Actions pipelines]
|
||||||
|
- **Coverage Requirements**: [minimum code coverage thresholds]
|
||||||
|
- **Performance Testing**: [approach for load and performance testing]
|
||||||
|
|
||||||
|
## 7. Rationale & Context
|
||||||
|
|
||||||
|
[Explain the reasoning behind the requirements, constraints, and guidelines. Provide context for design decisions.]
|
||||||
|
|
||||||
|
## 8. Dependencies & External Integrations
|
||||||
|
|
||||||
|
[Define the external systems, services, and architectural dependencies required for this specification. Focus on **what** is needed rather than **how** it's implemented. Avoid specific package or library versions unless they represent architectural constraints.]
|
||||||
|
|
||||||
|
### External Systems
|
||||||
|
- **EXT-001**: [External system name] - [Purpose and integration type]
|
||||||
|
|
||||||
|
### Third-Party Services
|
||||||
|
- **SVC-001**: [Service name] - [Required capabilities and SLA requirements]
|
||||||
|
|
||||||
|
### Infrastructure Dependencies
|
||||||
|
- **INF-001**: [Infrastructure component] - [Requirements and constraints]
|
||||||
|
|
||||||
|
### Data Dependencies
|
||||||
|
- **DAT-001**: [External data source] - [Format, frequency, and access requirements]
|
||||||
|
|
||||||
|
### Technology Platform Dependencies
|
||||||
|
- **PLT-001**: [Platform/runtime requirement] - [Version constraints and rationale]
|
||||||
|
|
||||||
|
### Compliance Dependencies
|
||||||
|
- **COM-001**: [Regulatory or compliance requirement] - [Impact on implementation]
|
||||||
|
|
||||||
|
**Note**: This section should focus on architectural and business dependencies, not specific package implementations. For example, specify "OAuth 2.0 authentication library" rather than "Microsoft.AspNetCore.Authentication.JwtBearer v6.0.1".
|
||||||
|
|
||||||
|
## 9. Examples & Edge Cases
|
||||||
|
|
||||||
|
```code
|
||||||
|
// Code snippet or data example demonstrating the correct application of the guidelines, including edge cases
|
||||||
|
```
|
||||||
|
|
||||||
|
## 10. Validation Criteria
|
||||||
|
|
||||||
|
[List the criteria or tests that must be satisfied for compliance with this specification.]
|
||||||
|
|
||||||
|
## 11. Related Specifications / Further Reading
|
||||||
|
|
||||||
|
[Link to related spec 1]
|
||||||
|
[Link to relevant external documentation]
|
||||||
|
|
||||||
|
```
|
||||||
Loading…
x
Reference in New Issue
Block a user