Skip to content

JiayiV/question_mixing / skills/create-github-action-workflow-specification

create-github-action-workflow-specification

Unverified

Create a formal specification for an existing GitHub Actions CI/CD workflow, optimized for AI consumption and workflow maintenance.

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

---
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 NamePurposeDependenciesExecution Context
job-1[Purpose][Prerequisites][Runner/Environment]
job-2[Purpose]job-1[Runner/Environment]

Requirements Matrix

Functional Requirements

IDRequirementPriorityAcceptance Criteria
REQ-001[Requirement]High[Testable criteria]
REQ-002[Requirement]Medium[Testable criteria]

Security Requirements

IDRequirementImplementation Constraint
SEC-001[Security requirement][Constraint description]

Performance Requirements

IDMetricTargetMeasurement Method
PERF-001[Metric][Target value][How measured]

Input/Output Contracts

Inputs

# 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

# Job Outputs
job_1_output: string  # Description: [purpose]
build_artifact: file  # Description: [content type]

Secrets & Variables

TypeNamePurposeScope
SecretSECRET_1[Purpose]Workflow
VariableVAR_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 TypeResponseRecovery Action
Build Failure[Response][Recovery steps]
Test Failure[Response][Recovery steps]
Deployment Failure[Response][Recovery steps]

Quality Gates

Gate Definitions

GateCriteriaBypass 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

ConditionSeverityNotification Target
[Condition][Level][Who/Where]

Integration Points

External Systems

SystemIntegration TypeData ExchangeSLA Requirements
[System][Type][Data format][Requirements]

Dependent Workflows

WorkflowRelationshipTrigger 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

ScenarioExpected BehaviorValidation 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

VersionDateChangesAuthor
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:

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.

writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 318kUpdated Claude CodeCodexUnverifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 117kUpdated Claude CodeCodexUnverifiedInstall