# Workflow Templates Reference

## Overview

This reference describes the 4 GitHub Actions workflow templates generated by the spec-driven-ci skill. Each template has configurable parameters that are applied from $MERGED_CONFIG during Phase 03.

## Template 1: dev-story.yml

**Purpose:** Execute `/dev` command in headless mode for a single story
**Trigger:** `workflow_dispatch` with `story_id` input
**Template file:** `assets/templates/dev-story-workflow.yml`

### Key Components

| Component | Value | Configurable |
|-----------|-------|-------------|
| Trigger | workflow_dispatch | No |
| Input | story_id (STORY-NNN format) | No |
| Runner | $MERGED_CONFIG.runner | Yes |
| Timeout | $MERGED_CONFIG.timeout_minutes | Yes |
| Model | Based on $MERGED_CONFIG.prefer_haiku | Yes |
| Caching | $MERGED_CONFIG.enable_prompt_caching | Yes |

### Required Steps

1. `actions/checkout@v4` - Checkout repository
2. Story ID validation - Regex check for STORY-NNN format
3. `anthropics/claude-code-action@v1` - Setup Claude Code
4. Execute `/dev` command with env vars
5. `actions/upload-artifact@v4` - Upload results

### Customization Points

- **Environment variables:** CLAUDE_CODE_MODEL, CLAUDE_CODE_CACHE_ENABLED, CLAUDE_CODE_DEBUG
- **Artifact paths:** dev-result.json, TestResults/, story files

---

## Template 2: qa-validation.yml

**Purpose:** Run `/qa` validation as PR quality gate
**Trigger:** `pull_request` on main (opened, synchronize)
**Template file:** `assets/templates/qa-validation-workflow.yml`

### Key Components

| Component | Value | Configurable |
|-----------|-------|-------------|
| Trigger | pull_request to main | No |
| Story extraction | From PR title (STORY-NNN) | No |
| Runner | $MERGED_CONFIG.runner | Yes |
| Timeout | $MERGED_CONFIG.timeout_minutes | Yes |
| Caching | $MERGED_CONFIG.enable_prompt_caching | Yes |

### Required Steps

1. `actions/checkout@v4` - Checkout repository
2. Extract Story ID from PR title using grep
3. Run `/qa {STORY_ID} deep` with Claude Code
4. Post results as PR comment via `actions/github-script@v7`

### Customization Points

- **Branch filter:** Default `main`, can be expanded to `[main, develop]`
- **QA mode:** Default `deep`, can be changed to `light`
- **PR comment format:** Customizable via github-script

---

## Template 3: parallel-stories.yml

**Purpose:** Execute `/dev` for multiple stories in parallel via matrix build
**Trigger:** `workflow_dispatch` with `story_ids` JSON array input
**Template file:** `assets/templates/parallel-stories-workflow.yml`

### Key Components

| Component | Value | Configurable |
|-----------|-------|-------------|
| Trigger | workflow_dispatch | No |
| Input | story_ids (JSON array) | No |
| Matrix | fromJSON(inputs.story_ids) | No |
| Max parallel | $MERGED_CONFIG.max_parallel_jobs | Yes |
| Fail-fast | false (always) | No |
| Runner | $MERGED_CONFIG.runner | Yes |
| Timeout | $MERGED_CONFIG.timeout_minutes | Yes |
| Model | Based on $MERGED_CONFIG.prefer_haiku | Yes |
| Caching | $MERGED_CONFIG.enable_prompt_caching | Yes |

### Required Steps

1. `actions/checkout@v4` - Checkout repository
2. `anthropics/claude-code-action@v1` - Setup Claude Code
3. Execute `/dev` for each matrix story_id
4. Upload per-story artifacts

### Customization Points

- **max-parallel:** Controls concurrent story execution (default: 5)
- **fail-fast:** Always false so one story failure doesn't cancel others
- **Artifact naming:** Per-story via `${{ matrix.story_id }}`

---

## Template 4: installer-testing.yml (Optional)

**Purpose:** Validate DevForgeAI installer on clean environments
**Trigger:** `push` to main or `workflow_dispatch`
**Template file:** `assets/templates/installer-testing-workflow.yml`

### Key Components

| Component | Value | Configurable |
|-----------|-------|-------------|
| Trigger | push to main + workflow_dispatch | No |
| Runner | $MERGED_CONFIG.runner | Yes |
| Timeout | 15 minutes (fixed) | No |

### Required Steps

1. `actions/checkout@v4` - Checkout repository
2. Run installer in clean environment
3. Verify installation (check files, CLI availability)
4. Run smoke test

### Enablement

This workflow is only generated when:
- `$MERGED_CONFIG.installer_testing.enabled == true`, OR
- Project has an `installer/` directory (auto-detected)

If neither condition is met, this workflow is skipped with a documented reason.

---

## Environment Variables Applied to All Workflows

| Variable | Source | Default |
|----------|--------|---------|
| `CLAUDE_CODE_CACHE_ENABLED` | $MERGED_CONFIG.enable_prompt_caching | true |
| `CLAUDE_CODE_MODEL` | $MERGED_CONFIG.prefer_haiku | claude-opus-4-7 |
| `CLAUDE_CODE_MAX_TURNS` | $MERGED_CONFIG.max_turns.{complexity} | unlimited |
| `CLAUDE_CODE_DEBUG` | Not configurable | false |

## Error Handling Patterns

### API Key Validation

All workflows include fail-fast validation:
```yaml
- name: Validate API Key
  run: |
    if [ -z "${{ secrets.ANTHROPIC_API_KEY }}" ]; then
      echo "::error::ANTHROPIC_API_KEY secret not configured"
      exit 1
    fi
```

### Rate Limit Retry

For parallel workflows, consider adding retry logic:
```yaml
- name: Execute with Retry
  uses: nick-fields/retry@v2
  with:
    timeout_minutes: 10
    max_attempts: 3
    retry_wait_seconds: 30
    command: claude -p "/dev ${{ inputs.story_id }}"
```
