|
| 1 | +--- |
| 2 | +mode: 'agent' |
| 3 | +description: 'Create a formal specification for an existing GitHub Actions CI/CD workflow, optimized for AI consumption and workflow maintenance.' |
| 4 | +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'] |
| 5 | +--- |
| 6 | +# Create GitHub Actions Workflow Specification |
| 7 | + |
| 8 | +Create a comprehensive specification for the GitHub Actions workflow: `${input:WorkflowFile}`. |
| 9 | + |
| 10 | +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. |
| 11 | + |
| 12 | +## AI-Optimized Requirements |
| 13 | + |
| 14 | +- **Token Efficiency**: Use concise language without sacrificing clarity |
| 15 | +- **Structured Data**: Leverage tables, lists, and diagrams for dense information |
| 16 | +- **Semantic Clarity**: Use precise terminology consistently throughout |
| 17 | +- **Implementation Abstraction**: Avoid specific syntax, commands, or tool versions |
| 18 | +- **Maintainability**: Design for easy updates as workflow evolves |
| 19 | + |
| 20 | +## Specification Template |
| 21 | + |
| 22 | +Save as: `/spec/spec-process-cicd-[workflow-name].md` |
| 23 | + |
| 24 | +```md |
| 25 | +--- |
| 26 | +title: CI/CD Workflow Specification - [Workflow Name] |
| 27 | +version: 1.0 |
| 28 | +date_created: [YYYY-MM-DD] |
| 29 | +last_updated: [YYYY-MM-DD] |
| 30 | +owner: DevOps Team |
| 31 | +tags: [process, cicd, github-actions, automation, [domain-specific-tags]] |
| 32 | +--- |
| 33 | + |
| 34 | +## Workflow Overview |
| 35 | + |
| 36 | +**Purpose**: [One sentence describing workflow's primary goal] |
| 37 | +**Trigger Events**: [List trigger conditions] |
| 38 | +**Target Environments**: [Environment scope] |
| 39 | + |
| 40 | +## Execution Flow Diagram |
| 41 | + |
| 42 | +```mermaid |
| 43 | +graph TD |
| 44 | + A[Trigger Event] --> B[Job 1] |
| 45 | + B --> C[Job 2] |
| 46 | + C --> D[Job 3] |
| 47 | + D --> E[End] |
| 48 | + |
| 49 | + B --> F[Parallel Job] |
| 50 | + F --> D |
| 51 | + |
| 52 | + style A fill:#e1f5fe |
| 53 | + style E fill:#e8f5e8 |
| 54 | +``` |
| 55 | + |
| 56 | +## Jobs & Dependencies |
| 57 | + |
| 58 | +| Job Name | Purpose | Dependencies | Execution Context | |
| 59 | +|----------|---------|--------------|-------------------| |
| 60 | +| job-1 | [Purpose] | [Prerequisites] | [Runner/Environment] | |
| 61 | +| job-2 | [Purpose] | job-1 | [Runner/Environment] | |
| 62 | + |
| 63 | +## Requirements Matrix |
| 64 | + |
| 65 | +### Functional Requirements |
| 66 | +| ID | Requirement | Priority | Acceptance Criteria | |
| 67 | +|----|-------------|----------|-------------------| |
| 68 | +| REQ-001 | [Requirement] | High | [Testable criteria] | |
| 69 | +| REQ-002 | [Requirement] | Medium | [Testable criteria] | |
| 70 | + |
| 71 | +### Security Requirements |
| 72 | +| ID | Requirement | Implementation Constraint | |
| 73 | +|----|-------------|---------------------------| |
| 74 | +| SEC-001 | [Security requirement] | [Constraint description] | |
| 75 | + |
| 76 | +### Performance Requirements |
| 77 | +| ID | Metric | Target | Measurement Method | |
| 78 | +|----|-------|--------|-------------------| |
| 79 | +| PERF-001 | [Metric] | [Target value] | [How measured] | |
| 80 | + |
| 81 | +## Input/Output Contracts |
| 82 | + |
| 83 | +### Inputs |
| 84 | + |
| 85 | +```yaml |
| 86 | +# Environment Variables |
| 87 | +ENV_VAR_1: string # Purpose: [description] |
| 88 | +ENV_VAR_2: secret # Purpose: [description] |
| 89 | + |
| 90 | +# Repository Triggers |
| 91 | +paths: [list of path filters] |
| 92 | +branches: [list of branch patterns] |
| 93 | +``` |
| 94 | +
|
| 95 | +### Outputs |
| 96 | +
|
| 97 | +```yaml |
| 98 | +# Job Outputs |
| 99 | +job_1_output: string # Description: [purpose] |
| 100 | +build_artifact: file # Description: [content type] |
| 101 | +``` |
| 102 | +
|
| 103 | +### Secrets & Variables |
| 104 | +
|
| 105 | +| Type | Name | Purpose | Scope | |
| 106 | +|------|------|---------|-------| |
| 107 | +| Secret | SECRET_1 | [Purpose] | Workflow | |
| 108 | +| Variable | VAR_1 | [Purpose] | Repository | |
| 109 | +
|
| 110 | +## Execution Constraints |
| 111 | +
|
| 112 | +### Runtime Constraints |
| 113 | +
|
| 114 | +- **Timeout**: [Maximum execution time] |
| 115 | +- **Concurrency**: [Parallel execution limits] |
| 116 | +- **Resource Limits**: [Memory/CPU constraints] |
| 117 | +
|
| 118 | +### Environmental Constraints |
| 119 | +
|
| 120 | +- **Runner Requirements**: [OS/hardware needs] |
| 121 | +- **Network Access**: [External connectivity needs] |
| 122 | +- **Permissions**: [Required access levels] |
| 123 | +
|
| 124 | +## Error Handling Strategy |
| 125 | +
|
| 126 | +| Error Type | Response | Recovery Action | |
| 127 | +|------------|----------|-----------------| |
| 128 | +| Build Failure | [Response] | [Recovery steps] | |
| 129 | +| Test Failure | [Response] | [Recovery steps] | |
| 130 | +| Deployment Failure | [Response] | [Recovery steps] | |
| 131 | +
|
| 132 | +## Quality Gates |
| 133 | +
|
| 134 | +### Gate Definitions |
| 135 | +
|
| 136 | +| Gate | Criteria | Bypass Conditions | |
| 137 | +|------|----------|-------------------| |
| 138 | +| Code Quality | [Standards] | [When allowed] | |
| 139 | +| Security Scan | [Thresholds] | [When allowed] | |
| 140 | +| Test Coverage | [Percentage] | [When allowed] | |
| 141 | +
|
| 142 | +## Monitoring & Observability |
| 143 | +
|
| 144 | +### Key Metrics |
| 145 | +
|
| 146 | +- **Success Rate**: [Target percentage] |
| 147 | +- **Execution Time**: [Target duration] |
| 148 | +- **Resource Usage**: [Monitoring approach] |
| 149 | +
|
| 150 | +### Alerting |
| 151 | +
|
| 152 | +| Condition | Severity | Notification Target | |
| 153 | +|-----------|----------|-------------------| |
| 154 | +| [Condition] | [Level] | [Who/Where] | |
| 155 | +
|
| 156 | +## Integration Points |
| 157 | +
|
| 158 | +### External Systems |
| 159 | +
|
| 160 | +| System | Integration Type | Data Exchange | SLA Requirements | |
| 161 | +|--------|------------------|---------------|------------------| |
| 162 | +| [System] | [Type] | [Data format] | [Requirements] | |
| 163 | +
|
| 164 | +### Dependent Workflows |
| 165 | +
|
| 166 | +| Workflow | Relationship | Trigger Mechanism | |
| 167 | +|----------|--------------|-------------------| |
| 168 | +| [Workflow] | [Type] | [How triggered] | |
| 169 | +
|
| 170 | +## Compliance & Governance |
| 171 | +
|
| 172 | +### Audit Requirements |
| 173 | +
|
| 174 | +- **Execution Logs**: [Retention policy] |
| 175 | +- **Approval Gates**: [Required approvals] |
| 176 | +- **Change Control**: [Update process] |
| 177 | +
|
| 178 | +### Security Controls |
| 179 | +
|
| 180 | +- **Access Control**: [Permission model] |
| 181 | +- **Secret Management**: [Rotation policy] |
| 182 | +- **Vulnerability Scanning**: [Scan frequency] |
| 183 | +
|
| 184 | +## Edge Cases & Exceptions |
| 185 | +
|
| 186 | +### Scenario Matrix |
| 187 | +
|
| 188 | +| Scenario | Expected Behavior | Validation Method | |
| 189 | +|----------|-------------------|-------------------| |
| 190 | +| [Edge case] | [Behavior] | [How to verify] | |
| 191 | +
|
| 192 | +## Validation Criteria |
| 193 | +
|
| 194 | +### Workflow Validation |
| 195 | +
|
| 196 | +- **VLD-001**: [Validation rule] |
| 197 | +- **VLD-002**: [Validation rule] |
| 198 | +
|
| 199 | +### Performance Benchmarks |
| 200 | +
|
| 201 | +- **PERF-001**: [Benchmark criteria] |
| 202 | +- **PERF-002**: [Benchmark criteria] |
| 203 | +
|
| 204 | +## Change Management |
| 205 | +
|
| 206 | +### Update Process |
| 207 | +
|
| 208 | +1. **Specification Update**: Modify this document first |
| 209 | +2. **Review & Approval**: [Approval process] |
| 210 | +3. **Implementation**: Apply changes to workflow |
| 211 | +4. **Testing**: [Validation approach] |
| 212 | +5. **Deployment**: [Release process] |
| 213 | +
|
| 214 | +### Version History |
| 215 | +
|
| 216 | +| Version | Date | Changes | Author | |
| 217 | +|---------|------|---------|--------| |
| 218 | +| 1.0 | [Date] | Initial specification | [Author] | |
| 219 | +
|
| 220 | +## Related Specifications |
| 221 | +
|
| 222 | +- [Link to related workflow specs] |
| 223 | +- [Link to infrastructure specs] |
| 224 | +- [Link to deployment specs] |
| 225 | +
|
| 226 | +``` |
| 227 | + |
| 228 | +## Analysis Instructions |
| 229 | + |
| 230 | +When analyzing the workflow file: |
| 231 | + |
| 232 | +1. **Extract Core Purpose**: Identify the primary business objective |
| 233 | +2. **Map Job Flow**: Create dependency graph showing execution order |
| 234 | +3. **Identify Contracts**: Document inputs, outputs, and interfaces |
| 235 | +4. **Capture Constraints**: Extract timeouts, permissions, and limits |
| 236 | +5. **Define Quality Gates**: Identify validation and approval points |
| 237 | +6. **Document Error Paths**: Map failure scenarios and recovery |
| 238 | +7. **Abstract Implementation**: Focus on behavior, not syntax |
| 239 | + |
| 240 | +## Mermaid Diagram Guidelines |
| 241 | + |
| 242 | +### Flow Types |
| 243 | +- **Sequential**: `A --> B --> C` |
| 244 | +- **Parallel**: `A --> B & A --> C; B --> D & C --> D` |
| 245 | +- **Conditional**: `A --> B{Decision}; B -->|Yes| C; B -->|No| D` |
| 246 | + |
| 247 | +### Styling |
| 248 | +```mermaid |
| 249 | +style TriggerNode fill:#e1f5fe |
| 250 | +style SuccessNode fill:#e8f5e8 |
| 251 | +style FailureNode fill:#ffebee |
| 252 | +style ProcessNode fill:#f3e5f5 |
| 253 | +``` |
| 254 | + |
| 255 | +### Complex Workflows |
| 256 | +For workflows with 5+ jobs, use subgraphs: |
| 257 | +```mermaid |
| 258 | +graph TD |
| 259 | + subgraph "Build Phase" |
| 260 | + A[Lint] --> B[Test] --> C[Build] |
| 261 | + end |
| 262 | + subgraph "Deploy Phase" |
| 263 | + D[Staging] --> E[Production] |
| 264 | + end |
| 265 | + C --> D |
| 266 | +``` |
| 267 | + |
| 268 | +## Token Optimization Strategies |
| 269 | + |
| 270 | +1. **Use Tables**: Dense information in structured format |
| 271 | +2. **Abbreviate Consistently**: Define once, use throughout |
| 272 | +3. **Bullet Points**: Avoid prose paragraphs |
| 273 | +4. **Code Blocks**: Structured data over narrative |
| 274 | +5. **Cross-Reference**: Link instead of repeat information |
| 275 | + |
| 276 | +Focus on creating a specification that serves as both documentation and a template for workflow updates. |
0 commit comments