From a82308d1e87561c55858953b0d59af16fb18b7bc Mon Sep 17 00:00:00 2001 From: Paul Isaris Date: Thu, 1 Oct 2026 09:09:06 +0300 Subject: [PATCH] Put the adoption rules where agents look first A fresh agent asked to adopt the workflows read the workflow files and the guide, not AGENTS.md. It pinned @v0.1.4, wrote the caller from scratch, planned to delete an unrelated workflow and guessed inputs. - Guide: five rules at the top; the procedure keeps unrelated workflows and forbids guessing inputs - Workflow headers: start from the template, use the short tag @v0.1 - AGENTS.md: the same rules --- .github/workflows/README.md | 37 ++++++++++++++++++++++++-------- .github/workflows/laravel-ci.yml | 4 ++++ .github/workflows/node-ci.yml | 4 ++++ .github/workflows/security.yml | 4 ++++ AGENTS.md | 19 ++++++++++------ 5 files changed, 53 insertions(+), 15 deletions(-) diff --git a/.github/workflows/README.md b/.github/workflows/README.md index 70b9d55..918f2d9 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -13,11 +13,26 @@ application, which inputs it accepts, and how to solve common problems. Each workflow file also starts with a comment block that shows a full example call. `self-check.yml` is the CI of this repository. Do not call it. -> **AI coding agents:** read [`AGENTS.md`](../../AGENTS.md) at the repository -> root first. To add these workflows to a repository, follow -> [Adopt in an existing repository](#adopt-in-an-existing-repository). SciFY -> developers with the `scify-devops` Claude Code plugin can run `/ci-setup`, -> which follows the same procedure. +**Read this first** (people and AI coding agents). To add these workflows to a +repository, follow [Adopt in an existing repository](#adopt-in-an-existing-repository). +These five rules prevent the common mistakes: + +1. **Start from a template** in [`workflow-templates/`](../../workflow-templates). + It sets the triggers, `concurrency` and `permissions`. Do not write the + caller file from scratch. +2. **Use the short tag `@v0.1`.** Never pin an exact release such as + `@v0.1.4`: an exact tag never moves, so the repository stops receiving fixes. +3. **Replace only CI and security workflows.** Keep every other workflow, for + example deployment, Dependabot auto-merge or release workflows. +4. **Do not guess inputs.** Read the repository's own configuration first: the + database in `phpunit.xml`, the scripts in `composer.json` and + `package.json`. Leave an input commented out when its default is right. +5. **Verify.** Run the repository's own checks, open a pull request, and read + the job logs. The required check becomes `ci / CI`. + +AI coding agents: [`AGENTS.md`](../../AGENTS.md) at the repository root has +more rules. SciFY developers with the `scify-devops` Claude Code plugin can run +`/ci-setup`, which follows the same procedure. ## Contents @@ -135,9 +150,12 @@ workflows. It applies to people and to AI coding agents. Replace `$default-branch` with the default branch, for example `main`. 4. **Map each existing command to an input.** Keep the repository's own commands where they exist, for example `lint-command: composer check`. Leave - an input commented out when its default already does the same thing. -5. **Remove what the shared workflows replace.** Delete the old workflow - files and every local copy of `scan-dev-configs` or `verify-npm-hardening`. + an input commented out when its default already does the same thing. Do not + guess: for example, `php-extensions` follows the database in `phpunit.xml`. +5. **Remove only what the shared workflows replace.** Delete the old CI and + security workflow files and every local copy of `scan-dev-configs` or + `verify-npm-hardening`. Keep every other workflow, for example deployment, + Dependabot auto-merge or release workflows. 6. **Run the repository's own checks on the new files.** Run its formatters and linters, for example `npm run check` or `composer check`, and `actionlint .github/workflows/*.yml`. @@ -153,7 +171,8 @@ workflows. It applies to people and to AI coding agents. | Pitfall | What happens | Do this | | --- | --- | --- | | An action from `scify/.github` pinned by tag | The run fails: the organisation requires actions pinned by SHA | Call `security.yml`, which loads its actions by itself. For a direct use, pin the action by SHA | -| A reusable workflow pinned by SHA | The repository stops receiving fixes | Use `@v0.1` | +| A reusable workflow pinned by SHA or by an exact release such as `@v0.1.4` | The repository stops receiving fixes | Use the short tag `@v0.1` | +| A caller file written from scratch | Missing triggers, for example no CI on pull requests | Start from the template (step 3) | | The repository's formatter does not run before the push | CI fails, for example Prettier on the new workflow file | Run the repository's own checks first (step 6) | | A commented-out input under `# with:` | Prettier moves the comment, and the uncommented input no longer sits under `with:` | Keep the extra indentation after the `#`, as in the templates: `# input: value` | | Two inputs run the same tool | Double run time, for example `composer check` that already includes `check:types` | Give each input a command that does not overlap with the others | diff --git a/.github/workflows/laravel-ci.yml b/.github/workflows/laravel-ci.yml index 21384a4..7629d18 100644 --- a/.github/workflows/laravel-ci.yml +++ b/.github/workflows/laravel-ci.yml @@ -1,5 +1,9 @@ # Reusable CI workflow for Laravel repositories. # +# To use it: start from workflow-templates/laravel-ci.yml and pin the short tag @v0.1 +# (never an exact release such as @v0.1.4). Procedure for people and AI agents: +# https://github.com/scify/.github/blob/main/.github/workflows/README.md#adopt-in-an-existing-repository +# # Minimal call (every value below is a default and can be left out): # # jobs: diff --git a/.github/workflows/node-ci.yml b/.github/workflows/node-ci.yml index 8571907..636dd8b 100644 --- a/.github/workflows/node-ci.yml +++ b/.github/workflows/node-ci.yml @@ -1,5 +1,9 @@ # Reusable CI workflow for npm-only repositories (Vue, React, TypeScript SPAs). # +# To use it: start from workflow-templates/node-ci.yml and pin the short tag @v0.1 +# (never an exact release such as @v0.1.4). Procedure for people and AI agents: +# https://github.com/scify/.github/blob/main/.github/workflows/README.md#adopt-in-an-existing-repository +# # Minimal call (every value below is a default and can be left out): # # jobs: diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml index 61ca75d..38603d4 100644 --- a/.github/workflows/security.yml +++ b/.github/workflows/security.yml @@ -1,5 +1,9 @@ # Reusable security workflow for SciFY repositories. # +# To use it: start from workflow-templates/security.yml and pin the short tag @v0.1 +# (never an exact release such as @v0.1.4). Procedure for people and AI agents: +# https://github.com/scify/.github/blob/main/.github/workflows/README.md#adopt-in-an-existing-repository +# # Call it from a repository workflow: # # on: diff --git a/AGENTS.md b/AGENTS.md index 11d4c24..c22fa0f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,7 +15,9 @@ in a different repository, `scify/scify-agent-tools`. ## Part 1: Use the shared workflows in another repository -**Current release tag: `v0.1`.** Call every workflow with `@v0.1`. +**Current release tag: `v0.1`.** Call every workflow with `@v0.1`. This short +tag moves to each fix release. Never pin an exact release such as `@v0.1.4`, +even when the release list shows it as "Latest". | Repository type | Workflows to call | Template | | --- | --- | --- | @@ -40,20 +42,25 @@ gh api 'repos/scify/.github/contents/.github/workflows/README.md?ref=v0.1' \ Rules that cause failures when you break them: -1. **Workflows by tag, actions by SHA.** Call a reusable workflow with `@v0.1`. +1. **Start from the template** and keep its triggers, `concurrency` and + `permissions`. **Replace only CI and security workflows**; keep deployment, + Dependabot auto-merge and other workflows. **Do not guess inputs**: read + `phpunit.xml`, `composer.json` and `package.json` first. + +2. **Workflows by tag, actions by SHA.** Call a reusable workflow with `@v0.1`. The organisation requires every action in a step to be pinned by full commit SHA, also actions from `scify/.github`. Do not call `scify/.github/.github/actions/@v0.1`: it fails. Use `security.yml` instead, which runs both actions. -2. **Run the target repository's own checks before you push.** Its formatters +3. **Run the target repository's own checks before you push.** Its formatters and linters also check the new workflow files. Then run `actionlint .github/workflows/*.yml`. -3. **The required check becomes `ci / CI`.** Tell the user to update the branch +4. **The required check becomes `ci / CI`.** Tell the user to update the branch ruleset or branch protection. Do not change repository settings without the user's approval. -4. **Read the job logs.** A green job can mean that a step was skipped, for +5. **Read the job logs.** A green job can mean that a step was skipped, for example "No package.json, skipping". -5. **Delete replaced files**: old CI or security workflows, and local copies of +6. **Delete replaced files**: old CI or security workflows, and local copies of `scan-dev-configs` or `verify-npm-hardening`. The npm rules that `security.yml` enforces are in the