From 6dac87c915d3e69fd1d69d53f42a5bb18cf115ea Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Wed, 3 Jun 2026 13:16:01 +0200 Subject: [PATCH 1/2] docs(agents): add AGENTS.md with template-drift sync reference Create AGENTS.md documenting the canonical template-drift workflow: how drift-scan.yml detects/auto-closes drift issues, how scripts/sync-template.sh reconciles a consumer's .github/ tree, and the universal-core dependabot scoping that avoids dependency_file_not_found. Migrated from project memory during the 2026-06-03 memory cleanup. Signed-off-by: Sebastian Mendel --- AGENTS.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..6337f37 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,27 @@ +# Agent Guide — netresearch/.github + +Organization-level community health files, reusable GitHub Actions workflows, +and the canonical Go repository templates (`templates/go-app`, `templates/go-lib`) +that consumer repos are kept in sync with. + +## Template-drift sync + +The `go-app` and `go-lib` templates under `templates/` are the source of truth +for each consumer repo's `.github/` tree. Drift between a consumer and its +template is detected and reconciled by dedicated tooling: + +- **Detect:** `.github/workflows/drift-scan.yml` runs weekly (Mon 06:00 UTC) and + on `workflow_dispatch` (with an optional space-separated `repos:` input). It + auto-opens "Template drift: \ vs \" issues and + auto-closes them once drift is gone — so after merging fixes, dispatch the + scan to close immediately instead of waiting for the next schedule. +- **Fix:** `scripts/sync-template.sh netresearch/` + SSH-clones the consumer, copies the template `.github/` tree, commits with + `-S --signoff`, pushes a `sync/...` branch, and opens a PR. Only drifting + files change. `template.yaml` is created on first sync only and never + overwritten — it carries each repo's `intentional-drift:` state. +- **Scope:** keep templates trimmed to a universal core (gomod + github-actions); + per-repo extras (docker, npm, devcontainers) are opt-in via a self-managed + `dependabot.yml` plus `intentional-drift`, because not every consumer has + those manifests and an undeclared ecosystem fails Dependabot with + `dependency_file_not_found`. From 66bd5bc73cef8b06a70adfa9ece21c33cd806aec Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Wed, 3 Jun 2026 13:27:45 +0200 Subject: [PATCH 2/2] docs(agents): correct dependabot scope, template.yaml path, issue-title rendering Address review feedback on the new AGENTS.md template-drift section: - Scope: clarify the per-template Dependabot baseline. go-lib baselines gomod + github-actions; go-app adds docker (every go-app repo ships a Dockerfile). npm, devcontainers, and docker-for-go-lib are opt-in. The previous text implied docker was opt-in for both, misstating the go-app baseline. - Use the full .github/template.yaml path to match sync-template.sh and drift-scan.yml instead of the bare template.yaml. - Wrap the auto-opened issue title in backticks instead of backslash-escaped angle brackets for consistent Markdown rendering. Signed-off-by: Sebastian Mendel --- AGENTS.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6337f37..3c63b41 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,16 +12,18 @@ template is detected and reconciled by dedicated tooling: - **Detect:** `.github/workflows/drift-scan.yml` runs weekly (Mon 06:00 UTC) and on `workflow_dispatch` (with an optional space-separated `repos:` input). It - auto-opens "Template drift: \ vs \" issues and + auto-opens `Template drift: vs ` issues and auto-closes them once drift is gone — so after merging fixes, dispatch the scan to close immediately instead of waiting for the next schedule. - **Fix:** `scripts/sync-template.sh netresearch/` SSH-clones the consumer, copies the template `.github/` tree, commits with `-S --signoff`, pushes a `sync/...` branch, and opens a PR. Only drifting - files change. `template.yaml` is created on first sync only and never + files change. `.github/template.yaml` is created on first sync only and never overwritten — it carries each repo's `intentional-drift:` state. -- **Scope:** keep templates trimmed to a universal core (gomod + github-actions); - per-repo extras (docker, npm, devcontainers) are opt-in via a self-managed +- **Scope:** templates declare only the ecosystems every consumer is guaranteed + to have. `go-lib` baselines `gomod + github-actions`; `go-app` adds `docker` + on top (every go-app repo ships a Dockerfile). Further extras — `npm`, + `devcontainers`, and `docker` for `go-lib` — are opt-in via a self-managed `dependabot.yml` plus `intentional-drift`, because not every consumer has those manifests and an undeclared ecosystem fails Dependabot with `dependency_file_not_found`.