diff --git a/.github/AGENTS.md b/.github/AGENTS.md new file mode 100644 index 0000000..9fb5c1d --- /dev/null +++ b/.github/AGENTS.md @@ -0,0 +1,13 @@ +# GitHub Automation Rules + +## Standard + +- `GH-001` GitHub automation MUST be stored under `.github/`. +- `GH-002` Workflow definitions MUST be stored under `.github/workflows/`. +- `GH-003` Repository-local composite actions MUST be stored under `.github/actions/`. +- `GH-004` Automation SHOULD use simple, explicit structures. +- `GH-005` Names MUST be semantic and consistent. + +## Preferences + +- `GH-P001` Repository-specific preferences MAY extend rules defined in child directories. diff --git a/.github/actions/AGENTS.md b/.github/actions/AGENTS.md new file mode 100644 index 0000000..60bc782 --- /dev/null +++ b/.github/actions/AGENTS.md @@ -0,0 +1,15 @@ +# Composite Action Rules + +## Standard + +- `ACT-001` Each composite action MUST be stored in its own directory under `.github/actions/`. +- `ACT-002` Each composite action entrypoint MUST be named `action.yml`. +- `ACT-003` Composite actions SHOULD represent reusable sequences of workflow steps. +- `ACT-004` Each composite action SHOULD have one primary responsibility. +- `ACT-005` Composite action directories MUST use simple semantic names. +- `ACT-006` Composite actions SHOULD NOT be created solely to wrap a trivial single command. + +## Preferences + +- `ACT-P001` Composite actions SHOULD remain compatible with Linux runners where practical. +- `ACT-P002` Platform-specific behavior SHOULD be avoided unless required by the action. diff --git a/.github/workflows/AGENTS.md b/.github/workflows/AGENTS.md new file mode 100644 index 0000000..0126614 --- /dev/null +++ b/.github/workflows/AGENTS.md @@ -0,0 +1,21 @@ +# Workflow Rules + +## Standard + +- `WF-001` Workflows MUST be split by lifecycle concern. +- `WF-002` Workflow filenames SHOULD use semantic names such as `ci.yml`, `deploy.yml`, and `release.yml`. +- `WF-003` Reusable workflow filenames MUST use the pattern `reusable-*.yml`. +- `WF-004` A `reusable-*.yml` workflow MUST use `workflow_call`. +- `WF-005` Jobs MUST represent execution boundaries. +- `WF-006` Independent jobs SHOULD run in parallel. +- `WF-007` `needs:` MUST only represent actual job dependencies. +- `WF-008` Matrices SHOULD only represent variations of the same job. +- `WF-009` Job dependencies, conditions, and orchestration SHOULD remain explicit in workflow YAML. +- `WF-010` Workflow and job identifiers MUST use simple semantic names. + +## Preferences + +- `WF-P001` Linux runners SHOULD be the default. +- `WF-P002` A job that can execute correctly on Linux SHOULD run on Linux. +- `WF-P003` macOS or Windows runners SHOULD only be used for platform-specific requirements or explicit compatibility testing. +- `WF-P004` `lint-pr.yml` MUST NOT be modified.