@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/cicd/github-flow/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: github-flow
+description: "Deliver a change after the commit: push, open a PR, wait for checks, and merge to main through the repo's flow (direct push, pull request, or merge queue). Use whenever you commit or finish a change, when CONTRIBUTING.md has a Delivery section, and for asks like 'commit this', 'push it', 'open a PR', 'ship it', 'land it', 'get it merged'. Also: declare a repo's delivery flow, or write the CI conventions and Delivery section into CONTRIBUTING.md on request. NOT for writing workflow YAML (github-actions), Mergify config or a stuck queued PR (mergify), cutting a release (resolve-release), or PRs that resolve-issues or rush-issues deliver."
+release-version: 0.36.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# GitHub Flow
+
+Take a committed change to done. Set `SKILL_DIR` to the directory you read this file from.
+
+## Routing index
+
+| You are… | Go to |
+|---|---|
+| Just committed, or finished a change | [Deliver](#deliver) |
+| Asked to push, open a PR, or merge | [Deliver](#deliver) |
+| A check on your PR is red | [Fix a red check](#fix-a-red-check) |
+| A merge waits on a review or approval | [Stop at a human gate](#stop-at-a-human-gate) |
+| A queued PR is stuck or dequeued | the `mergify` skill |
+| Asked to write the CI rules or delivery flow into the repo | [Persist to CONTRIBUTING.md](#persist-to-contributingmd) |
+
+## Deliver
+
+1. Read the flow:
+
+   ```bash
+   node "$SKILL_DIR/scripts/flow.mjs"
+   ```
+
+   It prints `source` (`declared` or `detected`), `flow`, `done`, `mergeMethod`, `queue`,
+   `autoMerge`, the default `branch`, and `evidence`.
+2. Decide how far to go:
+   - `source: declared` and `done: merged`: run the whole flow. Do not stop at the commit.
+   - The user asked in this session to push, open a PR, or merge: run the flow up to what they asked.
+   - Otherwise: stop after the commit and ask once, naming the flow and its evidence:
+     "Push and deliver through the `<flow>` flow?" Offer to declare the flow
+     ([Persist](#persist-to-contributingmd)). Never end the session silently with unpushed commits.
+3. Run the steps for the flow: [direct](#flow-direct), [pull-request](#flow-pull-request),
+   or [merge-queue](#flow-merge-queue).
+4. Report the result: the pushed SHA, the PR URL and merge commit, or where it stopped and why.
+
+Commit only the files of this change. Leave unrelated working-tree changes alone.
+
+## Flow: direct
+
+1. Run the repo's local checks (the test, lint, and build commands `CONTRIBUTING.md` or `AGENTS.md`
+   names). Fix failures before pushing.
+2. `git pull --rebase origin <branch>`. Rerun the checks if the rebase brought in changes.
+3. `git push origin HEAD:<branch>`. On a rejected push, pull with rebase and push once more; then report.
+4. Never force-push.
+
+## Flow: pull-request
+
+1. If you committed on the default branch, move the commits to a branch: `git fetch origin`,
+   `git switch -c <type>/<short-slug>`, then `git branch -f <branch> origin/<branch>`.
+2. `git push -u origin HEAD`.
+3. `gh pr create --fill`, ready for review, not draft. Add `Closes #<n>` when the change resolves an issue.
+   - Stack repo (`mergify-hooks/` in the git hooks dir; the pre-push hook says "Use 'mergify stack
+     push'"): replace steps 2–3 with the `mergify` skill's `scripts/stack-push.mjs`. Put
+     `Closes #<n>` in the commit message. Never `--no-verify`.
+4. Wait for the checks: `gh pr checks --watch --required --fail-fast`.
+   - "no required checks": run it again without `--required`.
+   - "no checks reported": wait 30 seconds and retry; after 5 minutes with none, the repo has no CI
+     for this PR. Continue.
+   - Red: go to [Fix a red check](#fix-a-red-check).
+5. Merge once green: `gh pr merge --<mergeMethod> --delete-branch`, adding `--auto` when
+   `autoMerge: true`. On a refusal for review, go to [Stop at a human gate](#stop-at-a-human-gate).
+6. Confirm `gh pr view --json state,mergeCommit` shows `MERGED`, then
+   `git switch <branch> && git pull --ff-only`.
+
+## Flow: merge-queue
+
+1. Run steps 1–4 of [pull-request](#flow-pull-request).
+2. Enqueue:
+   - `queue: mergify`: load the `mergify` skill. Enqueue as its watch contract says, then run its
+     `scripts/watch-pr-delivery.mjs` to a verdict. Enqueue several ready PRs together.
+   - `queue: github`: `gh pr merge --auto` with no merge method; the queue sets it.
+3. Dequeued: with Mergify, follow its dequeue-reason table. Re-enqueue only after the cause is fixed.
+4. Confirm the merge and update the local default branch as in pull-request step 6.
+
+## Fix a red check
+
+1. Read the failure: `gh run view <run-id> --log-failed`.
+2. Caused by this change: fix, commit, push. In a stack repo, amend the PR's commit and push with
+   `stack-push.mjs`; a new commit opens a new PR. Stop after three rounds and report.
+3. Not caused by this change (flake, infrastructure, unrelated code): rerun once with
+   `gh run rerun <run-id> --failed`. Still red: report it; do not edit unrelated code.
+4. Never skip, disable, or weaken a check to turn it green.
+5. A push to a queued PR dequeues it. Re-enqueue after the new run is green.
+
+## Stop at a human gate
+
+Stop and report when a merge needs what only a human gives: a required approval, a code-owner
+review, a `CHANGES_REQUESTED` review, or a fix outside this change. Never approve your own PR,
+merge with `--admin`, or bypass a rule. Pushing to the default branch is allowed only in the
+`direct` flow.
+
+## Persist to CONTRIBUTING.md
+
+Only when the user asks, or accepts the offer in [Deliver](#deliver) step 2. From the target
+repo's root:
+
+```bash
+node "$SKILL_DIR/scripts/persist-conventions.mjs" --flow <direct|pull-request|merge-queue> \
+  [--done merged|committed] [--merge-method squash|merge|rebase] [--delivery-only]   # preview
+node "$SKILL_DIR/scripts/persist-conventions.mjs" --flow <flow> ... --write             # write
+```
+
+- Writes [references/ci-conventions.md](references/ci-conventions.md) as `## CI conventions` and the
+  flow as `## Delivery`, each between `conventions:<id>` markers; a re-run replaces only those blocks.
+- `--done` defaults to `merged`; `--merge-method` (default `squash`) applies to `pull-request`.
+- Pass `--delivery-only` for a repo without GitHub Actions workflows. Without `--flow`, writes CI
+  conventions only.
+- Adds a pointer to `AGENTS.md` unless it names `CONTRIBUTING.md`; creates missing files.
+- Creates a missing `CLAUDE.md` as a symlink to `AGENTS.md`. Adds the pointer to a regular
+  `CLAUDE.md` that names neither file. Leaves a symlinked `CLAUDE.md` alone.
+- Report each file's result line. Committing the files is a change of its own: deliver it with this skill.
+
+## Related skills
+
+- `github-actions`: write and debug workflow YAML, the one required check, CI speed.
+- `mergify`: queue config, branch rulesets, the delivery watcher, stuck or dequeued PRs.
+- `resolve-issues` and `rush-issues` deliver their own PRs; do not run this skill inside them.

package/skills/cicd/github-flow/references/ci-conventions.md

@@ -0,0 +1,14 @@
+## CI conventions
+
+1. Deploy only from Cloud Build; use workflows to verify.
+2. Require one `gate` job (`if: always()`) per lane and nothing else.
+3. Never put `paths:` or `paths-ignore:` on a workflow that reports a required check.
+4. Keep PR checks under 10 minutes, run heavy suites in the merge queue, and test the deployed revision after deploy.
+5. Keep the PR and queue lanes in one `ci.yml`; put repeated setup in a local composite action.
+6. Set `timeout-minutes` on every job; cancel superseded runs on PRs only.
+7. Set `permissions: contents: read`, SHA-pin third-party actions, and pass `${{ }}` through `env:`, never inline in `run:`.
+8. Fail on a missing secret; never set `continue-on-error` on tests.
+9. Fork-guard self-hosted jobs, set `persist-credentials: false`, and remove started containers in `if: always()`.
+10. Alert on failed scheduled runs.
+11. Never make an AI review the only gate or pass it on timeout.
+12. Lint workflows with `actionlint`; don't write tests that read workflow files.

package/skills/cicd/github-flow/release-check.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path, fallback = {}) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function frontmatterValue(text, key) {
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
+  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
+}
+
+function repositoryOf(source) {
+  const value = String(source ?? '').trim();
+  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function stableVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function newer(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+  } catch { /* A read-only cache must not block skill use. */ }
+}
+
+function main(now = Date.now()) {
+  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
+  const name = frontmatterValue(skill, 'name');
+  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
+  if (!name || !localVersion) return;
+
+  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
+  const entry = lock.skills?.[name];
+  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
+  if (!repository) return;
+
+  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
+  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
+  const all = readJson(cachePath);
+  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
+
+  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
+    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+    });
+    cache.lastCheck = now;
+    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
+    else delete cache.latestTag;
+    all[repository] = cache;
+    writeCache(cachePath, all);
+  }
+
+  const latestVersion = stableVersion(cache.latestTag);
+  if (!latestVersion || !newer(latestVersion, localVersion)) return;
+  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
+
+  cache.notifiedTag = cache.latestTag;
+  cache.notifiedAt = now;
+  all[repository] = cache;
+  writeCache(cachePath, all);
+  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
+  process.stdout.write(
+    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
+      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
+      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
+  );
+}
+
+try { main(); } catch { /* Update checks are advisory and always fail silent. */ }

package/skills/cicd/github-flow/scripts/flow-core.mjs

@@ -0,0 +1,105 @@
+// flow-core — the delivery declaration and the flow guess. Pure and import-only:
+// flow.mjs gathers the facts (CONTRIBUTING.md, git history, GitHub settings) and
+// persist-conventions.mjs writes the section.
+
+export const FLOWS = ['direct', 'pull-request', 'merge-queue']
+export const DONE = ['merged', 'committed']
+export const MERGE_METHODS = ['squash', 'merge', 'rebase']
+
+const PR_MERGE_SUBJECT = /^Merge pull request #\d+/
+const SQUASH_SUBJECT = /\(#\d+\)\s*$/
+const HISTORY_PR_SHARE = 0.5
+const RECENT = 5
+
+const STEPS = {
+  direct: (_method) => 'run the local checks, `git pull --rebase` onto `main`, and push to `main`. Never force-push.',
+  'pull-request': (method) => `push a branch, open a ready PR, wait for the required checks, merge with \`${method}\`, and confirm the merge.`,
+  'merge-queue': (_method) => 'push a branch, open a ready PR, wait for the checks, enqueue it with the `mergify` skill, and run its watcher to a verdict.',
+}
+
+export function validateDelivery({ flow, done = 'merged', mergeMethod = 'squash' }) {
+  const errors = []
+  if (!FLOWS.includes(flow)) errors.push(`flow must be one of ${FLOWS.join(', ')}`)
+  if (!DONE.includes(done)) errors.push(`done must be one of ${DONE.join(', ')}`)
+  if (!MERGE_METHODS.includes(mergeMethod)) errors.push(`merge-method must be one of ${MERGE_METHODS.join(', ')}`)
+  return errors
+}
+
+// The `## Delivery` section body that persist-conventions writes.
+export function renderDelivery({ flow, done = 'merged', mergeMethod = 'squash' }) {
+  const lines = ['## Delivery', '', `- flow: ${flow}`, `- done: ${done}`]
+  if (flow === 'pull-request') lines.push(`- merge-method: ${mergeMethod}`)
+  lines.push('')
+  const steps = STEPS[flow](mergeMethod)
+  lines.push(done === 'merged'
+    ? `After committing, deliver with the \`github-flow\` skill: ${steps} Do not stop at the commit.`
+    : `After committing, ask before pushing. Once approved, deliver with the \`github-flow\` skill: ${steps}`)
+  return `${lines.join('\n')}\n`
+}
+
+// Read the declaration from CONTRIBUTING.md text: the `## Delivery` section,
+// written by persist-conventions or by hand. Null when absent or without a valid flow.
+export function parseDelivery(text) {
+  if (typeof text !== 'string') return null
+  const start = text.search(/^## Delivery\s*$/m)
+  if (start === -1) return null
+  const rest = text.slice(start).split('\n').slice(1)
+  const end = rest.findIndex((line) => /^#{1,2} /.test(line))
+  const body = (end === -1 ? rest : rest.slice(0, end)).join('\n')
+  const field = (name) => body.match(new RegExp(`^\\s*[-*]?\\s*${name}:\\s*([\\w-]+)`, 'm'))?.[1]
+  const flow = field('flow')
+  if (!FLOWS.includes(flow)) return null
+  const done = DONE.includes(field('done')) ? field('done') : 'committed'
+  const mergeMethod = MERGE_METHODS.includes(field('merge-method')) ? field('merge-method') : 'squash'
+  return { flow, done, mergeMethod }
+}
+
+// Guess the flow from facts when nothing is declared. `done` is always
+// `committed`: an undeclared repo asks before pushing.
+//
+// facts: {
+//   mergifyConfig: boolean,           a Mergify config file in the repo
+//   ruleTypes: string[] | null,       rule types on the default branch; null = unreadable
+//   autoMerge: boolean | null,        repo allows auto-merge; null = unreadable
+//   allowedMethods: string[] | null,  merge methods the repo allows; null = unreadable
+//   subjects: string[],               first-parent commit subjects on the default branch, newest first
+// }
+export function guessFlow(facts) {
+  const ruleTypes = facts.ruleTypes ?? []
+  const subjects = facts.subjects ?? []
+  const evidence = []
+  const merges = subjects.filter((s) => PR_MERGE_SUBJECT.test(s)).length
+  const squashes = subjects.filter((s) => SQUASH_SUBJECT.test(s)).length
+  const fromPr = (s) => PR_MERGE_SUBJECT.test(s) || SQUASH_SUBJECT.test(s)
+  const recent = subjects.slice(0, RECENT)
+  const recentShare = recent.length ? recent.filter(fromPr).length / recent.length : 0
+  if (facts.ruleTypes == null) evidence.push('GitHub branch rules unreadable')
+  else evidence.push(`branch rules: ${ruleTypes.length ? ruleTypes.join(', ') : 'none'}`)
+  evidence.push(`${merges + squashes} of the last ${subjects.length} commits on the default branch came from PRs, ${recent.filter(fromPr).length} of the last ${recent.length}`)
+
+  let flow
+  let queue = null
+  if (facts.mergifyConfig) {
+    flow = 'merge-queue'
+    queue = 'mergify'
+    evidence.push('Mergify config present')
+  } else if (ruleTypes.includes('merge_queue')) {
+    flow = 'merge-queue'
+    queue = 'github'
+    evidence.push('GitHub merge queue rule present')
+  } else if (ruleTypes.includes('required_status_checks')) {
+    flow = 'pull-request'
+    evidence.push('required status checks on the default branch')
+  } else {
+    flow = recentShare >= HISTORY_PR_SHARE ? 'pull-request' : 'direct'
+    if (flow === 'direct' && ruleTypes.includes('pull_request')) {
+      evidence.push('a PR rule exists, but history shows direct pushes (bypass)')
+    }
+  }
+
+  const allowed = (facts.allowedMethods ?? MERGE_METHODS).filter((m) => MERGE_METHODS.includes(m))
+  const fromHistory = merges > squashes ? 'merge' : squashes > 0 ? 'squash' : null
+  const mergeMethod = fromHistory && allowed.includes(fromHistory) ? fromHistory : (allowed[0] ?? 'squash')
+
+  return { source: 'detected', flow, done: 'committed', mergeMethod, queue, autoMerge: facts.autoMerge ?? null, evidence }
+}

package/skills/cicd/github-flow/scripts/flow.mjs

@@ -0,0 +1,81 @@
+// flow — print the repo's delivery flow as JSON: the declaration from
+// CONTRIBUTING.md (`source: declared`), or a guess from GitHub settings and
+// history (`source: detected`). Read-only.
+//
+//   node flow.mjs [--repo-root <dir>]
+//
+// Exit 0 with the JSON; 2 on a usage error or when the directory is not a git repo.
+import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { guessFlow, parseDelivery } from './flow-core.mjs'
+
+const MERGIFY_FILES = ['.mergify.yml', '.mergify/config.yml', '.github/mergify.yml']
+const HISTORY_DEPTH = 20
+
+function sh(cmd, args, cwd) {
+  try {
+    return execFileSync(cmd, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+  } catch {
+    return null
+  }
+}
+
+function ghJson(args, cwd) {
+  const out = sh('gh', args, cwd)
+  if (out == null) return null
+  try {
+    return JSON.parse(out)
+  } catch {
+    return null
+  }
+}
+
+const argv = process.argv.slice(2)
+let root = process.cwd()
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i] === '--repo-root' && argv[i + 1]) root = path.resolve(argv[++i])
+  else {
+    console.error(`flow: unknown argument ${argv[i]}`)
+    process.exit(2)
+  }
+}
+const top = sh('git', ['rev-parse', '--show-toplevel'], root)
+if (!top) {
+  console.error(`flow: not a git repository: ${root}`)
+  process.exit(2)
+}
+
+const contributing = path.join(top, 'CONTRIBUTING.md')
+const mergifyConfig = MERGIFY_FILES.some((f) => fs.existsSync(path.join(top, f)))
+const localBranch = sh('git', ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], top)?.replace(/^origin\//, '') ?? null
+const declared = parseDelivery(fs.existsSync(contributing) ? fs.readFileSync(contributing, 'utf8') : null)
+
+const github = declared?.flow === 'direct' ? null : ghJson(['repo', 'view', '--json', 'nameWithOwner,defaultBranchRef'], top)
+const repo = github?.nameWithOwner ?? null
+const branch = github?.defaultBranchRef?.name ?? localBranch ?? 'main'
+const settings = repo ? ghJson(['api', `repos/${repo}`], top) : null
+const autoMerge = settings ? Boolean(settings.allow_auto_merge) : null
+
+if (declared) {
+  const queue = declared.flow === 'merge-queue' ? (mergifyConfig ? 'mergify' : 'github') : null
+  console.log(JSON.stringify({ repo, branch, source: 'declared', ...declared, queue, autoMerge }, null, 2))
+  process.exit(0)
+}
+
+const rules = repo ? ghJson(['api', `repos/${repo}/rules/branches/${branch}`], top) : null
+const log = sh('git', ['log', '--first-parent', `-${HISTORY_DEPTH}`, '--format=%s', `origin/${branch}`], top)
+  ?? sh('git', ['log', '--first-parent', `-${HISTORY_DEPTH}`, '--format=%s', branch], top)
+
+const allowedMethods = settings
+  ? [settings.allow_squash_merge && 'squash', settings.allow_merge_commit && 'merge', settings.allow_rebase_merge && 'rebase'].filter(Boolean)
+  : null
+
+const guess = guessFlow({
+  mergifyConfig,
+  ruleTypes: Array.isArray(rules) ? [...new Set(rules.map((r) => r.type))] : null,
+  autoMerge,
+  allowedMethods,
+  subjects: log ? log.split('\n').filter(Boolean) : [],
+})
+console.log(JSON.stringify({ repo, branch, ...guess }, null, 2))

package/skills/cicd/github-flow/scripts/flow.test.mjs

@@ -0,0 +1,114 @@
+// Tests for the delivery declaration and the flow guess. The guess fixtures are
+// the facts read from four real repos on 2026-10-04, each with the flow its owner
+// says it uses.
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { spawnSync } from 'node:child_process'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { guessFlow, parseDelivery, renderDelivery, validateDelivery } from './flow-core.mjs'
+
+const CLI = fileURLToPath(new URL('./flow.mjs', import.meta.url))
+const direct = (n) => Array.from({ length: n }, (_, i) => `docs: note ${i}`)
+const merged = (n) => Array.from({ length: n }, (_, i) => `Merge pull request #${100 + i} from 1aboveio/topic-${i}`)
+const squashed = (n) => Array.from({ length: n }, (_, i) => `fix: thing ${i} (#${200 + i})`)
+
+test('proxy-cache: a PR rule everyone bypasses, direct history -> direct', () => {
+  const guess = guessFlow({ mergifyConfig: false, ruleTypes: ['pull_request'], autoMerge: false, allowedMethods: ['squash', 'merge', 'rebase'], subjects: direct(20) })
+  assert.equal(guess.flow, 'direct')
+  assert.equal(guess.done, 'committed')
+  assert.ok(guess.evidence.some((e) => /bypass/.test(e)))
+})
+
+test('github-runner: recent PR merges after older direct pushes -> pull-request with merge commits', () => {
+  const subjects = [...merged(5), ...direct(13), ...merged(2)]
+  const guess = guessFlow({ mergifyConfig: false, ruleTypes: ['pull_request'], autoMerge: false, allowedMethods: ['squash', 'merge', 'rebase'], subjects })
+  assert.equal(guess.flow, 'pull-request')
+  assert.equal(guess.mergeMethod, 'merge')
+})
+
+test('pi-better-harness: required checks and auto-merge -> pull-request, squash, auto-merge', () => {
+  const guess = guessFlow({ mergifyConfig: false, ruleTypes: ['pull_request', 'deletion', 'non_fast_forward', 'required_status_checks'], autoMerge: true, allowedMethods: ['squash', 'merge', 'rebase'], subjects: squashed(20) })
+  assert.deepEqual([guess.flow, guess.mergeMethod, guess.autoMerge, guess.queue], ['pull-request', 'squash', true, null])
+})
+
+test('ai: a Mergify config -> merge-queue through mergify', () => {
+  const guess = guessFlow({ mergifyConfig: true, ruleTypes: ['pull_request', 'required_status_checks', 'update'], autoMerge: true, allowedMethods: ['squash', 'merge'], subjects: merged(20) })
+  assert.deepEqual([guess.flow, guess.queue], ['merge-queue', 'mergify'])
+})
+
+test('a GitHub merge_queue rule -> merge-queue through github', () => {
+  const guess = guessFlow({ mergifyConfig: false, ruleTypes: ['merge_queue', 'pull_request'], autoMerge: true, allowedMethods: ['squash'], subjects: squashed(3) })
+  assert.deepEqual([guess.flow, guess.queue], ['merge-queue', 'github'])
+})
+
+test('unreadable GitHub settings still guess from history and say so', () => {
+  const guess = guessFlow({ mergifyConfig: false, ruleTypes: null, autoMerge: null, allowedMethods: null, subjects: direct(4) })
+  assert.equal(guess.flow, 'direct')
+  assert.ok(guess.evidence.includes('GitHub branch rules unreadable'))
+})
+
+test('the history merge method is used only when the repo allows it', () => {
+  const guess = guessFlow({ mergifyConfig: false, ruleTypes: ['required_status_checks'], autoMerge: false, allowedMethods: ['rebase'], subjects: merged(5) })
+  assert.equal(guess.mergeMethod, 'rebase')
+})
+
+test('every rendered declaration parses back to the same values', () => {
+  for (const flow of ['direct', 'pull-request', 'merge-queue']) {
+    for (const done of ['merged', 'committed']) {
+      for (const mergeMethod of ['squash', 'merge', 'rebase']) {
+        const text = `# Contributing\n\n${renderDelivery({ flow, done, mergeMethod })}\n## Next\n- flow: direct\n`
+        const parsed = parseDelivery(text)
+        assert.deepEqual(parsed, { flow, done, mergeMethod: flow === 'pull-request' ? mergeMethod : 'squash' })
+      }
+    }
+  }
+})
+
+test('the rendered section tells the agent not to stop at the commit only when done is merged', () => {
+  assert.match(renderDelivery({ flow: 'direct', done: 'merged' }), /Do not stop at the commit/)
+  assert.match(renderDelivery({ flow: 'direct', done: 'committed' }), /ask before pushing/)
+  assert.doesNotMatch(renderDelivery({ flow: 'direct', done: 'committed' }), /Do not stop/)
+})
+
+test('a hand-written section is read; a missing or unknown flow is not a declaration', () => {
+  assert.deepEqual(parseDelivery('## Delivery\n\nflow: merge-queue\ndone: merged\n'), { flow: 'merge-queue', done: 'merged', mergeMethod: 'squash' })
+  assert.equal(parseDelivery('## Delivery\n\n- done: merged\n'), null)
+  assert.equal(parseDelivery('## Delivery\n\n- flow: trunk\n'), null)
+  assert.equal(parseDelivery('## Other\n\n- flow: direct\n'), null)
+  assert.equal(parseDelivery(null), null)
+  assert.equal(parseDelivery('## Delivery\n\n- flow: direct\n').done, 'committed')
+})
+
+test('validateDelivery rejects unknown values', () => {
+  assert.deepEqual(validateDelivery({ flow: 'direct' }), [])
+  assert.equal(validateDelivery({ flow: 'gitflow', done: 'shipped', mergeMethod: 'ff' }).length, 3)
+})
+
+test('the CLI prints the declared flow without calling GitHub', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'github-flow-'))
+  try {
+    spawnSync('git', ['init', '-q', dir])
+    writeFileSync(join(dir, 'CONTRIBUTING.md'), `# Contributing\n\n${renderDelivery({ flow: 'pull-request', mergeMethod: 'merge' })}`)
+    writeFileSync(join(dir, '.mergify.yml'), 'queue_rules: []\n')
+    const res = spawnSync(process.execPath, [CLI, '--repo-root', dir], { encoding: 'utf8', env: { ...process.env, PATH: '/usr/bin:/bin' } })
+    assert.equal(res.status, 0, res.stderr)
+    const out = JSON.parse(res.stdout)
+    assert.deepEqual([out.source, out.flow, out.done, out.mergeMethod, out.queue], ['declared', 'pull-request', 'merged', 'merge', null])
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test('the CLI fails with exit 2 outside a git repo and on an unknown argument', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'github-flow-'))
+  try {
+    assert.equal(spawnSync(process.execPath, [CLI, '--repo-root', dir], { encoding: 'utf8', env: { ...process.env, GIT_CEILING_DIRECTORIES: tmpdir() } }).status, 2)
+    assert.equal(spawnSync(process.execPath, [CLI, '--wat'], { encoding: 'utf8' }).status, 2)
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})

package/skills/cicd/github-flow/scripts/persist-conventions-core.mjs

@@ -0,0 +1,117 @@
+// persist-conventions-core — write one skill's section into a repo's
+// CONTRIBUTING.md, point AGENTS.md at the file, and make CLAUDE.md a symlink to
+// AGENTS.md (Claude Code reads CLAUDE.md, not AGENTS.md). Import-only: each skill's
+// `persist-conventions.mjs` is the always-running CLI wrapper that names its
+// section, so no main-module guard here.
+//
+// Byte-identical copies live in test-quality (Testing conventions), github-flow
+// (CI conventions, Delivery) and data-catalog (Data catalog conventions);
+// skills/conventions-sections.test.mjs keeps them identical and proves the sections
+// coexist in one file.
+//
+// A section sits between `conventions:<id>` markers, so a re-run replaces only
+// that block and keeps everything else, including other skills' sections.
+// Nothing is written without --write: the user triggers the write, not an agent.
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+export const CONTRIBUTING_FILE = 'CONTRIBUTING.md'
+const MENTIONS_CONTRIBUTING = /(?:^|[^\w-])CONTRIBUTING\.md/
+
+export const AGENTS_SECTION = [
+  '## Contributing',
+  '',
+  `Follow [${CONTRIBUTING_FILE}](${CONTRIBUTING_FILE}) when writing, reviewing, or delivering code: tests, CI, data definitions, and what to do after each commit.`,
+  '',
+].join('\n')
+
+export function markers(id) {
+  return [`<!-- conventions:${id}:start -->`, `<!-- conventions:${id}:end -->`]
+}
+
+export function sectionBlock({ id, owner, body }) {
+  const [start, end] = markers(id)
+  const note = `<!-- Written by the ${owner} skill: re-run its persist-conventions.mjs --write to update; edit outside these markers. -->`
+  return `${start}\n${note}\n\n${body.trim()}\n${end}\n`
+}
+
+// Pure: the new CONTRIBUTING.md text given the current one (or null).
+export function renderConventions(current, id, block) {
+  if (current == null) return `# Contributing\n\n${block}`
+  const [start, end] = markers(id)
+  const from = current.indexOf(start)
+  const to = current.indexOf(end)
+  if (from !== -1 && to > from) {
+    const after = current.slice(to + end.length).replace(/^\r?\n/, '')
+    return current.slice(0, from) + block + after
+  }
+  return `${current.replace(/\s*$/, '')}\n\n${block}`
+}
+
+// Pure: the new AGENTS.md text given the current one (or null).
+export function renderAgents(current) {
+  if (current == null) return `# AGENTS.md\n\n${AGENTS_SECTION}`
+  if (MENTIONS_CONTRIBUTING.test(current)) return current
+  return `${current.replace(/\s*$/, '')}\n\n${AGENTS_SECTION}`
+}
+
+// A missing CLAUDE.md becomes a symlink to AGENTS.md.
+export const LINK_TO_AGENTS = Symbol('link CLAUDE.md to AGENTS.md')
+
+// Pure: the new CLAUDE.md text given the current one (or null). A missing file
+// becomes LINK_TO_AGENTS; a regular file keeps its content and gains the pointer
+// unless it already names AGENTS.md or CONTRIBUTING.md.
+export function renderClaude(current) {
+  if (current == null) return LINK_TO_AGENTS
+  if (/(?:^|[^\w-])(?:AGENTS|CONTRIBUTING)\.md/.test(current)) return current
+  return `${current.replace(/\s*$/, '')}\n\n${AGENTS_SECTION}`
+}
+
+export function persist(repoRoot, section, { write = false } = {}) {
+  const block = sectionBlock(section)
+  const plan = [
+    [CONTRIBUTING_FILE, (text) => renderConventions(text, section.id, block)],
+    ['AGENTS.md', renderAgents],
+    ['CLAUDE.md', renderClaude],
+  ]
+  return plan.map(([name, render]) => {
+    const file = path.join(repoRoot, name)
+    if (fs.lstatSync(file, { throwIfNoEntry: false })?.isSymbolicLink()) return { file: name, action: 'unchanged' }
+    const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null
+    const next = render(current)
+    const action = current == null ? 'create' : next === current ? 'unchanged' : 'update'
+    if (next === LINK_TO_AGENTS) {
+      if (write) fs.symlinkSync('AGENTS.md', file)
+      return { file: name, action: 'link' }
+    }
+    if (write && action !== 'unchanged') fs.writeFileSync(file, next)
+    return { file: name, action }
+  })
+}
+
+// `section` = { id, owner, title, body }. Exit 0 on success, 2 on a usage error.
+export function runCli(argv, section, { cwd = process.cwd(), log = console.log } = {}) {
+  let repoRoot = cwd
+  let write = false
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--write') write = true
+    else if (argv[i] === '--repo-root' && argv[i + 1]) repoRoot = path.resolve(cwd, argv[++i])
+    else {
+      log(`persist-conventions: unknown argument ${argv[i]}`)
+      return 2
+    }
+  }
+  if (!fs.statSync(repoRoot, { throwIfNoEntry: false })?.isDirectory()) {
+    log(`persist-conventions: not a directory: ${repoRoot}`)
+    return 2
+  }
+  const results = persist(repoRoot, section, { write })
+  const done = { create: 'created', link: 'linked to AGENTS.md', update: 'updated', unchanged: 'unchanged' }
+  for (const r of results) log(`  ${r.file}: ${write || r.action === 'unchanged' ? done[r.action] : `would ${r.action}`}`)
+  const changed = results.filter((r) => r.action !== 'unchanged').length
+  log(write
+    ? `persist-conventions: ${section.title}: ${changed} file(s) written, ${results.length - changed} unchanged`
+    : `persist-conventions: ${section.title}: preview only, ${changed} file(s) would change; re-run with --write to write`)
+  return 0
+}