---
name: afx-cicd
description: Day-to-day CI/CD helpers for Artifex projects. Use this skill when the user wants to watch a PR's CI run, trigger a deploy, or fetch failure logs from a workflow run. Wraps `gh run` and `gh workflow` and knows the Artifex cd.yml conventions produced by afx-cicd-scaffold.
---

# Artifex CI/CD Helpers Skill

**For Claude Code AI Assistant**

This skill provides three focused subcommands for day-to-day CI/CD work: watching a PR's CI run, triggering a deploy, and fetching failure logs. It is a thin wrapper over `gh run` and `gh workflow` that knows the Artifex CD conventions — specifically the `cd.yml` workflow produced by `afx-cicd-scaffold` and its `environment` input variable.

## Prerequisites

`gh` CLI must be installed and authenticated. If it is not, every subcommand fails fast with an actionable message:

```
error: 'gh' is not authenticated.
       Run the following to log in:
         gh auth login
       Then re-run this command.
```

Check status: `gh auth status`

## Subcommands

### `watch [<pr-number>]` — monitor a PR's CI run

Polls the most recent CI run for a PR and displays live status, refreshing until the run reaches a terminal state (success, failure, cancelled, timed_out, etc.).

**Auto-detection:** If no PR number is given, the skill auto-detects the PR for the current branch via `gh pr view --json number -q .number`. If no open PR exists for the current branch, it fails fast with a clear message.

**TTY vs non-TTY behavior:**
- **TTY (interactive terminal):** In-place live refresh using a carriage return. Status line updates in place.
- **Non-TTY (piped, e.g., `| cat` or inside an agent pipeline):** One line per poll, no ANSI sequences, no carriage return. Suitable for parsing or logging.

**Terminal states:** `success`, `completed`, `failure`, `timed_out`, `startup_failure`, `cancelled`, `skipped`, `action_required`. The watch loop exits as soon as any of these is observed.

**Conversational routing:**

| User phrasing | Invocation |
|---------------|-----------|
| "watch my PR's CI" | `afx-cicd watch` (auto-detect) |
| "is the CI passing for PR 42?" | `afx-cicd watch 42` |
| "tail the CI run for this branch" | `afx-cicd watch` |
| "check CI status faster" | `afx-cicd watch --interval=5` |

### `deploy <env> [--confirm-prod]` — trigger a deploy

Triggers the `cd.yml` workflow via `gh workflow run cd.yml -f environment=<env>`, then tails the resulting run until terminal state.

**Prod guard:** Deploying to `prod` requires `--confirm-prod`. Without it, the command refuses:

```
error: Deploying to prod requires an explicit confirmation flag.
       Re-run with --confirm-prod to proceed:
         afx-cicd deploy prod --confirm-prod
```

This guard is independent of and in addition to any GHA-side environment protection rules. The user should configure both.

**After triggering:** The skill waits up to 60 seconds for the new run to appear in the GitHub API before tailing it. If the run cannot be found, it prints `gh run list --workflow=cd.yml` for the user to inspect manually.

**Conversational routing:**

| User phrasing | Invocation |
|---------------|-----------|
| "deploy to staging" | `afx-cicd deploy staging` |
| "push to prod" / "deploy production" | `afx-cicd deploy prod --confirm-prod` |
| "trigger the CD pipeline for staging" | `afx-cicd deploy staging` |

### `logs <run-id>` — fetch failure logs

Fetches and displays only the failed steps' logs for a workflow run. Equivalent to `gh run view <run-id> --log-failed`.

**Clean factoring:** This subcommand is kept cleanly factored for reuse by ticket 13.2 (`afx-incident from-ci`). The argument shape `logs <run-id>` is stable. Output goes to stdout, errors to stderr, exit code 0 on success (even if the run itself failed), 1 on error.

**Conversational routing:**

| User phrasing | Invocation |
|---------------|-----------|
| "why did run 9876543210 fail?" | `afx-cicd logs 9876543210` |
| "show me the failure logs for that run" | `afx-cicd logs <run-id>` |
| "get the failed step output" | `afx-cicd logs <run-id>` |

## How to Run This Skill

### Watching a PR's CI run

1. If the user is on a branch with an open PR, invoke without arguments:
   ```bash
   ~/.claude/skills/afx-cicd/afx-cicd.sh watch
   ```
2. If the user specifies a PR number:
   ```bash
   ~/.claude/skills/afx-cicd/afx-cicd.sh watch 42
   ```
3. The command will poll and display status until the run completes. If it fails, it prints the `logs` command to use next.

### Deploying to an environment

1. For staging (no extra flag needed):
   ```bash
   ~/.claude/skills/afx-cicd/afx-cicd.sh deploy staging
   ```
2. For prod (must include `--confirm-prod`):
   ```bash
   ~/.claude/skills/afx-cicd/afx-cicd.sh deploy prod --confirm-prod
   ```
3. The command tails the triggered run until completion.

### Fetching failure logs

```bash
~/.claude/skills/afx-cicd/afx-cicd.sh logs 9876543210
```

The run ID can be found in:
- The URL of the Actions run page: `github.com/<org>/<repo>/actions/runs/<id>`
- Output of: `gh run list`
- Output of a previous `afx-cicd watch` or `afx-cicd deploy`

## Relationship to Other Skills

- **afx-cicd-scaffold** — produces the `cd.yml` and `ci.yml` workflows that this skill operates over. The workflow filename (`cd.yml`) and input variable name (`environment`) are the conventions this skill knows.
- **afx-incident** (ticket 13.2) — will reuse the `logs` subcommand's code path. Keep the argument shape `afx-cicd logs <run-id>` stable.

## Version

1.0.0 (ticket 12.4)