Card-Collection-Manager-3/.github/workflows/AGENTS.md

AGENTS.md

GitHub Actions workflows for CI, release automation, and policy checks.

Scope

• This file governs edits in .github/workflows/*.yml.
• Keep one top-level triggered workflow per CI intent:
  • feature-ci.yml for non-master push CI
  • master-ci.yml for merged-PR-to-master release CI
• Keep OS/platform splits in reusable workflows invoked via workflow_call.

Current workflow map

• feature-ci.yml -> orchestrator for feature branch CI.
• feature-linux.yml -> reusable Linux build/test/package workflow.
• feature-windows.yml -> reusable Windows build/test/package workflow.
• master-pr-title-guard.yml -> validates semantic-prefix policy for PRs targeting master.
• master-ci.yml -> orchestrator for merged PRs into master.
• master-windows.yml -> reusable Windows build/test/package workflow for master release flow.

CI invariants (do not break)

1. Keep workflow intent stable:
   • feature workflows produce branch+sha artifacts
   • master workflows produce semver-tagged release artifacts
2. Do not duplicate top-level triggers for the same intent (avoid split runs in Actions UI).
3. Preserve artifact naming conventions unless docs are updated in the same change:
   • ccm3-linux-<version>.zip
   • ccm3-windows-<version>.zip
   • ccm3-windows-installer-<version> (feature) and .exe (master release asset)
4. Preserve embedded app version wiring via -DCCM_APP_VERSION=... in both feature and master build flows.
5. Keep master release flow gated to merged PRs only.
6. Keep PR title prefix policy aligned with scripts/compute_master_semver.sh.

Editing rules

• Prefer minimal, surgical edits; avoid large workflow rewrites unless requested.
• Reusable workflows should declare explicit workflow_call inputs for required context (e.g., version, merge SHA).
• Keep permissions least-privilege:
  • reusable build workflows: contents: read
  • release/tag orchestrator: contents: write
• Keep shells consistent with runner setup:
  • Linux steps use standard bash-compatible shell.
  • Windows MSYS2 jobs keep shell: msys2 {0} and run msys2/setup-msys2 before MSYS2 commands.

Required follow-ups

• After changing workflow topology, update docs/ci-cd-guide.md.
• If artifact names or release behavior change, update docs/ci-cd-guide.md and docs/versioning.md if needed.
• If semver prefix policy changes, update both master-pr-title-guard.yml and docs.
• If adding/removing workflow files, update this file's "Current workflow map".

Anti-patterns

• Do not add a second top-level feature or master trigger file.
• Do not move release creation into a reusable workflow that lacks contents: write.
• Do not introduce MSVC-specific build commands; project CI targets Clang/MinGW toolchains.
• Do not silently change artifact names; downstream release/download steps depend on exact names.