Aif CI

4.1 GitHub Actions Generation

One workflow per concern — each file has its own triggers, permissions, concurrency:

Why one file per concern:

• Each check is a separate status check in PR — instantly see what failed
• Independent triggers — security on schedule, tests on push/PR, build only after tests
• Independent permissions — security may need security-events: write
• Can disable/re-run one workflow without touching others
• Branch protection rules can require specific workflows (e.g. require tests but not security)

When to keep single file: Only for very small projects with just lint + tests (2 jobs). As soon as there are 3+ concerns — split.

Every workflow gets the same header pattern:

name: <Name>

on:
  push:
    branches: [main]
  pull_request:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: read

Per-file job organization:

lint.yml — all code quality checks in parallel:

All jobs run in parallel (no needs). If only one tool detected (e.g. Go with just golangci-lint) — single job in the file is fine.

tests.yml — test suite:

Matrix builds (multiple language versions) only in this file.

build.yml — build verification:

security.yml — security scanning:

Per-job rules:

1. Each job gets its own setup (checkout, language setup, cache, dependency install)
2. Use language-specific setup actions with built-in cache:
   • PHP: shivammathur/setup-php@v2 with tools: parameter
   • Node.js: actions/setup-node@v4 with cache: parameter
   • Python: astral-sh/setup-uv@v5 (if uv) or actions/setup-python@v5 (if pip)
   • Go: actions/setup-go@v5 (auto-caches)
   • Rust: dtolnay/rust-toolchain@stable + Swatinem/rust-cache@v2
   • Java: actions/setup-java@v4 with cache: parameter
3. Use fail-fast: false in matrix builds
4. Upload coverage as artifact when WANT_COVERAGE

Matrix builds (when WANT_MATRIX):

Only the tests job uses a matrix. Lint/SA jobs run on the latest version only.

tests:
  name: Tests (${{ matrix.<language>-version }})
  strategy:
    fail-fast: false
    matrix:
      <language>-version: <language_versions from PROJECT_PROFILE>

Combining linter jobs:

If the project has both a formatter AND a linter from the same ecosystem, combine them into one job:

• PHP: php-cs-fixer check + other lint -> code-style job
• Node.js: eslint + prettier -> lint job. Biome replaces BOTH ESLint and Prettier — if Biome is detected, use only npx biome check . in a single lint job
• Python: ruff check + ruff format --check -> lint job (Ruff handles both)
• Rust: cargo fmt + cargo clippy -> can be separate (fmt is fast, clippy needs compilation)

Do NOT combine lint/SA with tests — they should fail independently with clear feedback.

Use the templates in templates/github/ and templates/gitlab/ as a base for generating workflow files. Follow the header pattern (name, on, concurrency, permissions) and per-file job organization described above.

4.2 GitLab CI Generation

Output file: .gitlab-ci.yml

For GitLab-specific pipeline structure, cache strategy, report format integration, and language-specific patterns → read references/GITLAB-PATTERNS.md

Pipeline stages: install → lint → test → build → security

4.3 Service Containers

If services_needed is not empty, add service containers to the test job. For GitHub Actions and GitLab CI service container syntax → read references/SERVICE-CONTAINERS.md

Quality Checks (Before Writing)

Verify generated pipeline before writing:

Correctness:

• Every job has checkout/setup/install steps
• Cache is configured for the correct lock file
• All commands match tools actually present in the project
• Matrix versions match the project's version constraints
• Service containers have health checks

Best practices:

• concurrency group set (GitHub Actions)
• permissions: contents: read set (GitHub Actions)
• interruptible: true set (GitLab CI)
• workflow.rules defined (GitLab CI)
• Jobs are parallel where possible (no unnecessary needs)
• fail-fast: false on matrix builds

No over-engineering:

• No jobs for tools not present in the project
• No matrix builds if the project only targets one version
• No security scanning unless requested or tools are installed
• No build job if the project has no build step

Step 5: Enhance / Audit Existing Pipeline

When MODE = "enhance" or MODE = "audit", analyze EXISTING_CONTENT against the project profile and best practices.

5.1 Gap Analysis

Compare existing pipeline against PROJECT_PROFILE:

Missing jobs:

• Linter installed but no lint job in CI?
• SA tool installed but no SA job?
• Tests exist but no test job?
• Security tools installed but no security job?

Configuration issues:

• No caching configured?
• No concurrency group (GitHub Actions)?
• Using deprecated actions (e.g., actions-rs instead of dtolnay/rust-toolchain)?
• Hardcoded language versions instead of variable/matrix?
• Missing fail-fast: false on matrix?
• Using policy: pull-push on all GitLab jobs instead of pull on non-install jobs?

Missing features:

• No coverage reporting when coverage tools are available?
• No JUnit/codequality report integration (GitLab)?
• No path filtering for monorepos?
• No workflow_dispatch trigger (GitHub Actions)?

5.2 Audit Report & Fix

For audit report format, fix flow options, and display templates → read references/AUDIT-REPORT.md

Present results as tables with ✅/❌/⚠️ per check. Categorize recommendations by severity (CRITICAL, HIGH, MEDIUM, LOW). Ask user to choose: fix all, fix critical only, or show details first.

If fixing: preserve existing structure, job names, and ordering conventions.

Step 6: Write Files

6.1 Generate Mode — Write Pipeline

GitHub Actions:

Bash: mkdir -p .github/workflows
Write .github/workflows/lint.yml        # If linters/SA detected
Write .github/workflows/tests.yml       # Always
Write .github/workflows/build.yml       # If has_build_step
Write .github/workflows/security.yml    # If WANT_SECURITY

Only create files for detected concerns. If only lint + tests — two files. If the project is trivially small (single lint + single test job) — a single ci.yml is acceptable.

GitLab CI:

Write .gitlab-ci.yml

GitLab CI uses a single .gitlab-ci.yml — stages and DAG (needs:) handle separation.

6.2 Enhance / Audit Mode — Update Existing

Edit existing files using the Edit tool. Preserve the original structure and only add/modify what's needed.

Step 7: Summary & Follow-Up

7.1 Display Summary

Display summary using format from references/AUDIT-REPORT.md (Summary Display Template section). Show platform, files created, features, and quick start commands.

7.2 Suggest Follow-Up Skills

Suggest: /aif-build-automation for CI targets in Makefile/Taskfile, /aif-dockerize for containerization.

Artifact Ownership and Config Policy

• Primary ownership: CI pipeline artifacts such as .github/workflows/* and .gitlab-ci.yml.
• Allowed companion updates: none by default outside CI files.
• Config policy: config-agnostic by design. This skill relies on repository detection and explicit user choices, not config.yaml.