diff --git a/README.md b/README.md index fd24234..cc0832c 100644 --- a/README.md +++ b/README.md @@ -85,6 +85,7 @@ Ready-to-use prompt templates for specific development scenarios and tasks, defi | [Azure Resource Health & Issue Diagnosis](prompts/azure-resource-health-diagnose.prompt.md) | Analyze Azure resource health, diagnose issues from logs and telemetry, and create a remediation plan for identified problems. | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fazure-resource-health-diagnose.prompt.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fazure-resource-health-diagnose.prompt.md) | | [Comment Code Generate A Tutorial](prompts/comment-code-generate-a-tutorial.prompt.md) | Transform this Python script into a polished, beginner-friendly project by refactoring the code, adding clear instructional comments, and generating a complete markdown tutorial. | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcomment-code-generate-a-tutorial.prompt.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcomment-code-generate-a-tutorial.prompt.md) | | [Create Architectural Decision Record](prompts/create-architectural-decision-record.prompt.md) | Create an Architectural Decision Record (ADR) document for AI-optimized decision documentation. | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-architectural-decision-record.prompt.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-architectural-decision-record.prompt.md) | +| [Create GitHub Actions Workflow Specification](prompts/create-github-action-workflow-specification.prompt.md) | Create a formal specification for an existing GitHub Actions CI/CD workflow, optimized for AI consumption and workflow maintenance. | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-github-action-workflow-specification.prompt.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-github-action-workflow-specification.prompt.md) | | [Create GitHub Issue from Specification](prompts/create-github-issue-feature-from-specification.prompt.md) | Create GitHub Issue for feature request from specification file using feature_request.yml template. | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-github-issue-feature-from-specification.prompt.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-github-issue-feature-from-specification.prompt.md) | | [Create GitHub Issue from Implementation Plan](prompts/create-github-issues-feature-from-implementation-plan.prompt.md) | Create GitHub Issues from implementation plan phases using feature_request.yml or chore_request.yml templates. | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-github-issues-feature-from-implementation-plan.prompt.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-github-issues-feature-from-implementation-plan.prompt.md) | | [Create GitHub Issues for Unmet Specification Requirements](prompts/create-github-issues-for-unmet-specification-requirements.prompt.md) | Create GitHub Issues for unimplemented requirements from specification files using feature_request.yml template. | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-github-issues-for-unmet-specification-requirements.prompt.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fcreate-github-issues-for-unmet-specification-requirements.prompt.md) | diff --git a/prompts/create-github-action-workflow-specification.prompt.md b/prompts/create-github-action-workflow-specification.prompt.md new file mode 100644 index 0000000..ee2f556 --- /dev/null +++ b/prompts/create-github-action-workflow-specification.prompt.md @@ -0,0 +1,276 @@ +--- +mode: 'agent' +description: 'Create a formal specification for an existing GitHub Actions CI/CD workflow, optimized for AI consumption and workflow maintenance.' +tools: ['changes', 'codebase', 'editFiles', 'extensions', 'fetch', 'findTestFiles', 'githubRepo', 'new', 'openSimpleBrowser', 'problems', 'runCommands', 'runInTerminal2', 'runNotebooks', 'runTasks', 'runTests', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure', 'usages', 'vscodeAPI', 'microsoft.docs.mcp', 'github', 'Microsoft Docs'] +--- +# Create GitHub Actions Workflow Specification + +Create a comprehensive specification for the GitHub Actions workflow: `${input:WorkflowFile}`. + +This specification serves as a specification for the workflow's behavior, requirements, and constraints. It must be implementation-agnostic, focusing on **what** the workflow accomplishes rather than **how** it's implemented. + +## AI-Optimized Requirements + +- **Token Efficiency**: Use concise language without sacrificing clarity +- **Structured Data**: Leverage tables, lists, and diagrams for dense information +- **Semantic Clarity**: Use precise terminology consistently throughout +- **Implementation Abstraction**: Avoid specific syntax, commands, or tool versions +- **Maintainability**: Design for easy updates as workflow evolves + +## Specification Template + +Save as: `/spec/spec-process-cicd-[workflow-name].md` + +```md +--- +title: CI/CD Workflow Specification - [Workflow Name] +version: 1.0 +date_created: [YYYY-MM-DD] +last_updated: [YYYY-MM-DD] +owner: DevOps Team +tags: [process, cicd, github-actions, automation, [domain-specific-tags]] +--- + +## Workflow Overview + +**Purpose**: [One sentence describing workflow's primary goal] +**Trigger Events**: [List trigger conditions] +**Target Environments**: [Environment scope] + +## Execution Flow Diagram + +```mermaid +graph TD + A[Trigger Event] --> B[Job 1] + B --> C[Job 2] + C --> D[Job 3] + D --> E[End] + + B --> F[Parallel Job] + F --> D + + style A fill:#e1f5fe + style E fill:#e8f5e8 +``` + +## Jobs & Dependencies + +| Job Name | Purpose | Dependencies | Execution Context | +|----------|---------|--------------|-------------------| +| job-1 | [Purpose] | [Prerequisites] | [Runner/Environment] | +| job-2 | [Purpose] | job-1 | [Runner/Environment] | + +## Requirements Matrix + +### Functional Requirements +| ID | Requirement | Priority | Acceptance Criteria | +|----|-------------|----------|-------------------| +| REQ-001 | [Requirement] | High | [Testable criteria] | +| REQ-002 | [Requirement] | Medium | [Testable criteria] | + +### Security Requirements +| ID | Requirement | Implementation Constraint | +|----|-------------|---------------------------| +| SEC-001 | [Security requirement] | [Constraint description] | + +### Performance Requirements +| ID | Metric | Target | Measurement Method | +|----|-------|--------|-------------------| +| PERF-001 | [Metric] | [Target value] | [How measured] | + +## Input/Output Contracts + +### Inputs + +```yaml +# Environment Variables +ENV_VAR_1: string # Purpose: [description] +ENV_VAR_2: secret # Purpose: [description] + +# Repository Triggers +paths: [list of path filters] +branches: [list of branch patterns] +``` + +### Outputs + +```yaml +# Job Outputs +job_1_output: string # Description: [purpose] +build_artifact: file # Description: [content type] +``` + +### Secrets & Variables + +| Type | Name | Purpose | Scope | +|------|------|---------|-------| +| Secret | SECRET_1 | [Purpose] | Workflow | +| Variable | VAR_1 | [Purpose] | Repository | + +## Execution Constraints + +### Runtime Constraints + +- **Timeout**: [Maximum execution time] +- **Concurrency**: [Parallel execution limits] +- **Resource Limits**: [Memory/CPU constraints] + +### Environmental Constraints + +- **Runner Requirements**: [OS/hardware needs] +- **Network Access**: [External connectivity needs] +- **Permissions**: [Required access levels] + +## Error Handling Strategy + +| Error Type | Response | Recovery Action | +|------------|----------|-----------------| +| Build Failure | [Response] | [Recovery steps] | +| Test Failure | [Response] | [Recovery steps] | +| Deployment Failure | [Response] | [Recovery steps] | + +## Quality Gates + +### Gate Definitions + +| Gate | Criteria | Bypass Conditions | +|------|----------|-------------------| +| Code Quality | [Standards] | [When allowed] | +| Security Scan | [Thresholds] | [When allowed] | +| Test Coverage | [Percentage] | [When allowed] | + +## Monitoring & Observability + +### Key Metrics + +- **Success Rate**: [Target percentage] +- **Execution Time**: [Target duration] +- **Resource Usage**: [Monitoring approach] + +### Alerting + +| Condition | Severity | Notification Target | +|-----------|----------|-------------------| +| [Condition] | [Level] | [Who/Where] | + +## Integration Points + +### External Systems + +| System | Integration Type | Data Exchange | SLA Requirements | +|--------|------------------|---------------|------------------| +| [System] | [Type] | [Data format] | [Requirements] | + +### Dependent Workflows + +| Workflow | Relationship | Trigger Mechanism | +|----------|--------------|-------------------| +| [Workflow] | [Type] | [How triggered] | + +## Compliance & Governance + +### Audit Requirements + +- **Execution Logs**: [Retention policy] +- **Approval Gates**: [Required approvals] +- **Change Control**: [Update process] + +### Security Controls + +- **Access Control**: [Permission model] +- **Secret Management**: [Rotation policy] +- **Vulnerability Scanning**: [Scan frequency] + +## Edge Cases & Exceptions + +### Scenario Matrix + +| Scenario | Expected Behavior | Validation Method | +|----------|-------------------|-------------------| +| [Edge case] | [Behavior] | [How to verify] | + +## Validation Criteria + +### Workflow Validation + +- **VLD-001**: [Validation rule] +- **VLD-002**: [Validation rule] + +### Performance Benchmarks + +- **PERF-001**: [Benchmark criteria] +- **PERF-002**: [Benchmark criteria] + +## Change Management + +### Update Process + +1. **Specification Update**: Modify this document first +2. **Review & Approval**: [Approval process] +3. **Implementation**: Apply changes to workflow +4. **Testing**: [Validation approach] +5. **Deployment**: [Release process] + +### Version History + +| Version | Date | Changes | Author | +|---------|------|---------|--------| +| 1.0 | [Date] | Initial specification | [Author] | + +## Related Specifications + +- [Link to related workflow specs] +- [Link to infrastructure specs] +- [Link to deployment specs] + +``` + +## Analysis Instructions + +When analyzing the workflow file: + +1. **Extract Core Purpose**: Identify the primary business objective +2. **Map Job Flow**: Create dependency graph showing execution order +3. **Identify Contracts**: Document inputs, outputs, and interfaces +4. **Capture Constraints**: Extract timeouts, permissions, and limits +5. **Define Quality Gates**: Identify validation and approval points +6. **Document Error Paths**: Map failure scenarios and recovery +7. **Abstract Implementation**: Focus on behavior, not syntax + +## Mermaid Diagram Guidelines + +### Flow Types +- **Sequential**: `A --> B --> C` +- **Parallel**: `A --> B & A --> C; B --> D & C --> D` +- **Conditional**: `A --> B{Decision}; B -->|Yes| C; B -->|No| D` + +### Styling +```mermaid +style TriggerNode fill:#e1f5fe +style SuccessNode fill:#e8f5e8 +style FailureNode fill:#ffebee +style ProcessNode fill:#f3e5f5 +``` + +### Complex Workflows +For workflows with 5+ jobs, use subgraphs: +```mermaid +graph TD + subgraph "Build Phase" + A[Lint] --> B[Test] --> C[Build] + end + subgraph "Deploy Phase" + D[Staging] --> E[Production] + end + C --> D +``` + +## Token Optimization Strategies + +1. **Use Tables**: Dense information in structured format +2. **Abbreviate Consistently**: Define once, use throughout +3. **Bullet Points**: Avoid prose paragraphs +4. **Code Blocks**: Structured data over narrative +5. **Cross-Reference**: Link instead of repeat information + +Focus on creating a specification that serves as both documentation and a template for workflow updates.