@ikon85/agent-workflow-kit 0.12.0 → 0.13.0

package/.agents/skills/setup-workflow/SKILL.md

@@ -24,6 +24,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
 | `docs/agents/code-review.md` | Standards-source pointers + adjacent-review-tooling notes the `code-review` skill's Standards axis reads (Section I) |
 | `## Workflow` in CLAUDE.md **and** AGENTS.md | generic entry-point map seeded from [workflow-overview.md](./workflow-overview.md) (Section F + Write) |
 | `## Agent skills` + `## Prod` in CLAUDE.md **and** AGENTS.md | one-line pointers + deploy target (Sections C/G + Write) |
+| `.github/workflows/agent-workflow-kit-update.yml` | optional tested Kit update pull request for GitHub consumers (Section A2) |
 
 ## Idempotency contract — read before writing anything
 
@@ -68,6 +69,40 @@ Default posture: these skills were designed for GitHub. If a `git remote` points
 
 Seed `docs/agents/issue-tracker.md` from the matching template in this folder: [issue-tracker-github.md](./issue-tracker-github.md), [issue-tracker-gitlab.md](./issue-tracker-gitlab.md), [issue-tracker-local.md](./issue-tracker-local.md). For "other", write it from the user's description.
 
+### 2a. Automatic Kit update pull requests (GitHub tracker only)
+
+> A short scheduled check can keep the installed Kit current by opening one normal pull request after the candidate passes the consumer's own tests. It never merges the pull request for you.
+
+Only after the user has confirmed a **GitHub tracker**, ask in plain language: *"Should GitHub check weekly for a tested Agent Workflow Kit update and keep one update pull request ready?"* Offer these explicit choices:
+
+Before offering **Enable**, confirm the consumer has a committed `package-lock.json` and a usable `package.json` `npm test` command. The shipped workflow installs the locked dependencies with `npm ci --ignore-scripts`; without that lockfile/test contract it cannot prove the candidate in a clean checkout, so explain the prerequisite and do not create the workflow yet.
+
+Also read the repository Actions policy before enabling:
+
+```bash
+gh api repos/<owner>/<repo>/actions/permissions/workflow
+```
+
+The response must report `"can_approve_pull_request_reviews": true`; this is GitHub's **Allow GitHub Actions to create and approve pull requests** gate used by the stable PR upsert. If it is false, or the policy cannot be read, do not seed the workflow yet. Guide the user to **Settings → Actions → General → Workflow permissions**, enable that checkbox, and rerun `setup-workflow`.
+
+If the user prefers `gh`, first show the exact mutation and obtain **explicit confirmation**; never change repository settings merely because setup was invoked. After confirmation, preserve the currently reported `default_workflow_permissions` value (`read` or `write`) and set the gate with:
+
+```bash
+gh api --method PUT repos/<owner>/<repo>/actions/permissions/workflow \
+  -f default_workflow_permissions=<current-read-or-write> \
+  -F can_approve_pull_request_reviews=true
+```
+
+Read the policy back and offer **Enable** only after the field is actually true.
+
+- **Enable** — seed `.github/workflows/agent-workflow-kit-update.yml` from [assets/agent-workflow-kit-update.yml](./assets/agent-workflow-kit-update.yml).
+- **Opt out** — do not create a GitHub workflow, branch, or pull request.
+- **Ask later** — do not create a GitHub workflow, branch, or pull request; explain that re-running `setup-workflow` can offer it again.
+
+This workflow opt-in has its own file-level idempotency rule: if the destination is already present, leave it byte-for-byte unchanged and report `skipped (already present)`. On repeated setup runs, do not prompt again when it exists. The workflow consumes the scoped `@ikon85/agent-workflow-kit` release and its existing parity-checked transactional update command; do not reproduce either mechanism in setup prose or shell steps.
+
+For GitLab, local, other, or an unknown provider, give only a provider-neutral explanation that automatic updates require provider-specific CI and pull-request support; **do not create a GitHub workflow**. Setup itself never creates the update branch or pull request — only an opted-in workflow run may do that later.
+
 **Conditional board-write note (only when the GitHub tracker uses a managed board):** if Section D ends with `board-sync.md` at `mode: github-projects-v2`, add one line to `issue-tracker.md`: *"Board writes (item-add, status/wave/cluster field edits, sub-issue links) go through the board-sync helper, not bare `gh issue create`/`gh project item-*`."* Do **not** add this for GitLab, local, other, or `mode: none`.
 
 ### 3. Section B — Triage labels

package/.agents/skills/setup-workflow/assets/agent-workflow-kit-update.yml

@@ -0,0 +1,31 @@
+name: Agent Workflow Kit update
+
+on:
+  schedule:
+    - cron: '17 6 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: agent-workflow-kit-update
+  cancel-in-progress: false
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.14
+      - name: Install locked consumer dependencies
+        run: npm ci --ignore-scripts
+      - name: Verify, test, and upsert the Kit update pull request
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: npx --yes --package=@ikon85/agent-workflow-kit@latest agent-workflow-kit-update-pr

package/.claude/skills/setup-workflow/SKILL.md

@@ -24,6 +24,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
 | `docs/agents/code-review.md` | Standards-source pointers + adjacent-review-tooling notes the `code-review` skill's Standards axis reads (Section I) |
 | `## Workflow` in CLAUDE.md **and** AGENTS.md | generic entry-point map seeded from [workflow-overview.md](./workflow-overview.md) (Section F + Write) |
 | `## Agent skills` + `## Prod` in CLAUDE.md **and** AGENTS.md | one-line pointers + deploy target (Sections C/G + Write) |
+| `.github/workflows/agent-workflow-kit-update.yml` | optional tested Kit update pull request for GitHub consumers (Section A2) |
 
 ## Idempotency contract — read before writing anything
 
@@ -68,6 +69,40 @@ Default posture: these skills were designed for GitHub. If a `git remote` points
 
 Seed `docs/agents/issue-tracker.md` from the matching template in this folder: [issue-tracker-github.md](./issue-tracker-github.md), [issue-tracker-gitlab.md](./issue-tracker-gitlab.md), [issue-tracker-local.md](./issue-tracker-local.md). For "other", write it from the user's description.
 
+### 2a. Automatic Kit update pull requests (GitHub tracker only)
+
+> A short scheduled check can keep the installed Kit current by opening one normal pull request after the candidate passes the consumer's own tests. It never merges the pull request for you.
+
+Only after the user has confirmed a **GitHub tracker**, ask in plain language: *"Should GitHub check weekly for a tested Agent Workflow Kit update and keep one update pull request ready?"* Offer these explicit choices:
+
+Before offering **Enable**, confirm the consumer has a committed `package-lock.json` and a usable `package.json` `npm test` command. The shipped workflow installs the locked dependencies with `npm ci --ignore-scripts`; without that lockfile/test contract it cannot prove the candidate in a clean checkout, so explain the prerequisite and do not create the workflow yet.
+
+Also read the repository Actions policy before enabling:
+
+```bash
+gh api repos/<owner>/<repo>/actions/permissions/workflow
+```
+
+The response must report `"can_approve_pull_request_reviews": true`; this is GitHub's **Allow GitHub Actions to create and approve pull requests** gate used by the stable PR upsert. If it is false, or the policy cannot be read, do not seed the workflow yet. Guide the user to **Settings → Actions → General → Workflow permissions**, enable that checkbox, and rerun `setup-workflow`.
+
+If the user prefers `gh`, first show the exact mutation and obtain **explicit confirmation**; never change repository settings merely because setup was invoked. After confirmation, preserve the currently reported `default_workflow_permissions` value (`read` or `write`) and set the gate with:
+
+```bash
+gh api --method PUT repos/<owner>/<repo>/actions/permissions/workflow \
+  -f default_workflow_permissions=<current-read-or-write> \
+  -F can_approve_pull_request_reviews=true
+```
+
+Read the policy back and offer **Enable** only after the field is actually true.
+
+- **Enable** — seed `.github/workflows/agent-workflow-kit-update.yml` from [assets/agent-workflow-kit-update.yml](./assets/agent-workflow-kit-update.yml).
+- **Opt out** — do not create a GitHub workflow, branch, or pull request.
+- **Ask later** — do not create a GitHub workflow, branch, or pull request; explain that re-running `setup-workflow` can offer it again.
+
+This workflow opt-in has its own file-level idempotency rule: if the destination is already present, leave it byte-for-byte unchanged and report `skipped (already present)`. On repeated setup runs, do not prompt again when it exists. The workflow consumes the scoped `@ikon85/agent-workflow-kit` release and its existing parity-checked transactional update command; do not reproduce either mechanism in setup prose or shell steps.
+
+For GitLab, local, other, or an unknown provider, give only a provider-neutral explanation that automatic updates require provider-specific CI and pull-request support; **do not create a GitHub workflow**. Setup itself never creates the update branch or pull request — only an opted-in workflow run may do that later.
+
 **Conditional board-write note (only when the GitHub tracker uses a managed board):** if Section D ends with `board-sync.md` at `mode: github-projects-v2`, add one line to `issue-tracker.md`: *"Board writes (item-add, status/wave/cluster field edits, sub-issue links) go through the board-sync helper, not bare `gh issue create`/`gh project item-*`."* Do **not** add this for GitLab, local, other, or `mode: none`.
 
 ### 3. Section B — Triage labels

package/.claude/skills/setup-workflow/assets/agent-workflow-kit-update.yml

@@ -0,0 +1,31 @@
+name: Agent Workflow Kit update
+
+on:
+  schedule:
+    - cron: '17 6 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: agent-workflow-kit-update
+  cancel-in-progress: false
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.14
+      - name: Install locked consumer dependencies
+        run: npm ci --ignore-scripts
+      - name: Verify, test, and upsert the Kit update pull request
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: npx --yes --package=@ikon85/agent-workflow-kit@latest agent-workflow-kit-update-pr

package/README.md

@@ -332,6 +332,14 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## Release notes
 
+### 0.13.0
+
+- added: `.agents/skills/setup-workflow/assets/agent-workflow-kit-update.yml`
+- added: `.claude/skills/setup-workflow/assets/agent-workflow-kit-update.yml`
+- added: `scripts/kit-update-pr.mjs`
+- changed: `.agents/skills/setup-workflow/SKILL.md`
+- changed: `.claude/skills/setup-workflow/SKILL.md`
+
 ### 0.12.0
 
 - added: `.agents/skills/kit-update/SKILL.md`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.12.0",
+  "kitVersion": "0.13.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -460,6 +460,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".agents/skills/setup-workflow/assets/agent-workflow-kit-update.yml",
+      "kind": "skill",
+      "ownerSkill": "setup-workflow",
+      "surface": "codex",
+      "sha256": "d8abf995d67184b4459b9565c9062319fc42e8a685042b288b3066a07a6fda59",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".agents/skills/setup-workflow/board-sync.md",
       "kind": "skill",
@@ -528,7 +537,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "codex",
-      "sha256": "ea0b75ccd1579820a09e7c8d4c151126aa0be7a0be6b76b23599fadebb44b554",
+      "sha256": "efc7818d98158a85a79f3a652787d2e557552fa5175b32b24916c894388b9b74",
       "mode": 420,
       "origin": "kit"
     },
@@ -1433,6 +1442,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".claude/skills/setup-workflow/assets/agent-workflow-kit-update.yml",
+      "kind": "skill",
+      "ownerSkill": "setup-workflow",
+      "surface": "claude",
+      "sha256": "d8abf995d67184b4459b9565c9062319fc42e8a685042b288b3066a07a6fda59",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".claude/skills/setup-workflow/board-sync.md",
       "kind": "skill",
@@ -1501,7 +1519,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "claude",
-      "sha256": "ea0b75ccd1579820a09e7c8d4c151126aa0be7a0be6b76b23599fadebb44b554",
+      "sha256": "efc7818d98158a85a79f3a652787d2e557552fa5175b32b24916c894388b9b74",
       "mode": 420,
       "origin": "kit"
     },
@@ -1883,6 +1901,13 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": "scripts/kit-update-pr.mjs",
+      "kind": "script",
+      "sha256": "64e7818003d7c6db227eadad0b114e199399a52a96965ab2f0f496c0a1e5c79c",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": "scripts/loc_offender_core.py",
       "kind": "script",

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Portable AI-agent workflow skills (plan → execute → land → learn) for Claude Code & Codex — grilling, TDD, diagnosis, two-axis code review, cross-model Codex review, design & domain-modeling, plus a skill router (ask-matt). npx init/update/diff/uninstall.",
   "type": "module",
   "bin": {
-    "agent-workflow-kit": "src/cli.mjs"
+    "agent-workflow-kit": "src/cli.mjs",
+    "agent-workflow-kit-update-pr": "scripts/kit-update-pr.mjs"
   },
   "scripts": {
     "test": "npm run test:node && npm run test:python",

package/scripts/build-kit.test.mjs

@@ -37,6 +37,9 @@ test('current build contains post-tag public files and repository metadata', asy
     const pkg = JSON.parse(await readFile(join(dist, 'package.json'), 'utf8'));
     assert.equal(pkg.name, '@ikon85/agent-workflow-kit');
     assert.equal(pkg.repository.url, 'git+https://github.com/iKon85/agent-workflow-kit.git');
+    assert.equal(pkg.bin['agent-workflow-kit'], 'src/cli.mjs');
+    assert.equal(pkg.bin['agent-workflow-kit-update-pr'], 'scripts/kit-update-pr.mjs');
+    await readFile(join(dist, 'scripts/kit-update-pr.mjs'));
   });
 });
 
@@ -52,9 +55,31 @@ test('npm pack keeps the complete scripts tree but excludes Python caches', () =
   const files = JSON.parse(output)[0].files.map((file) => file.path);
   assert.ok(files.includes('scripts/build-kit.mjs'));
   assert.ok(files.includes('scripts/board-sync.py'));
+  assert.ok(files.includes('scripts/kit-update-pr.mjs'));
   assert.ok(files.every((path) => !path.includes('__pycache__') && !path.endsWith('.pyc')));
   const pkg = JSON.parse(execFileSync('node', ['-p', 'JSON.stringify(require("./package.json"))'], {
     cwd: REPO, encoding: 'utf8',
   }));
   assert.ok(pkg.files.includes('scripts/'), 'package must ship future script file types');
 });
+
+test('packed scoped artifact keeps the existing npx default-bin inference', async () => {
+  const destination = await mkdtemp(join(tmpdir(), 'awkit-pack-'));
+  try {
+    const packed = JSON.parse(execFileSync('npm', [
+      'pack', '--pack-destination', destination, '--json',
+    ], { cwd: REPO, encoding: 'utf8' }));
+    const output = execFileSync('npx', [
+      '--yes', '--offline', `./${packed[0].filename}`,
+    ], { cwd: destination, encoding: 'utf8' });
+    assert.match(output, /Usage: agent-workflow-kit/);
+
+    const updater = execFileSync('npm', [
+      'exec', '--yes', '--offline', `--package=./${packed[0].filename}`,
+      '--', 'agent-workflow-kit-update-pr', 'help',
+    ], { cwd: destination, encoding: 'utf8' });
+    assert.match(updater, /Usage: agent-workflow-kit-update-pr/);
+  } finally {
+    await rm(destination, { recursive: true, force: true });
+  }
+});

package/scripts/kit-update-pr.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+import { execFile } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { appendFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+
+export const UPDATE_BRANCH = 'agent-workflow-kit/update';
+export const UPDATE_TITLE = 'chore: update agent workflow kit';
+const UPDATE_BODY = [
+  'Automated, parity-verified update of `@ikon85/agent-workflow-kit`.',
+  '',
+  'The transactional update candidate passed the consumer test suite before this branch was published.',
+  '',
+  'This pull request is never merged automatically.',
+].join('\n');
+const exec = promisify(execFile);
+
+export async function orchestrateUpdatePullRequest(options) {
+  const {
+    runUpdate, hasChanges, listPullRequests, publishBranch,
+    createPullRequest, updatePullRequest, branch = UPDATE_BRANCH,
+  } = options;
+  const update = await runUpdate();
+  if (update.exitCode !== 0) {
+    return { status: update.exitCode === 2 ? 'conflicted' : 'failed', branch, update };
+  }
+  if (!await hasChanges()) return { status: 'current', branch };
+
+  const pulls = await listPullRequests(branch);
+  if (pulls.length > 1) {
+    return { status: 'failed', branch, reason: 'multiple-open-pull-requests' };
+  }
+  await publishBranch(branch);
+  const input = { title: UPDATE_TITLE, body: UPDATE_BODY, branch };
+  if (pulls.length === 1) {
+    await updatePullRequest(pulls[0].number, input);
+    return { status: 'updated', branch, pullRequest: pulls[0].number };
+  }
+  await createPullRequest(input);
+  return { status: 'created', branch };
+}
+
+export function createSystemAdapters({
+  cwd = process.cwd(), env = process.env, execute = exec,
+} = {}) {
+  const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+  const command = async (file, args) => {
+    try {
+      const result = await execute(file, args, { cwd, env, encoding: 'utf8' });
+      return { exitCode: 0, stdout: result.stdout, stderr: result.stderr };
+    } catch (error) {
+      if (typeof error.code !== 'number') throw error;
+      return { exitCode: error.code, stdout: error.stdout || '', stderr: error.stderr || '' };
+    }
+  };
+  const checked = async (file, args) => {
+    const result = await command(file, args);
+    if (result.exitCode !== 0) throw new Error(result.stderr || `${file} exited ${result.exitCode}`);
+    return result.stdout.trim();
+  };
+
+  return {
+    runUpdate: () => command(process.execPath, [join(packageRoot, 'src/cli.mjs'), 'update', '--yes']),
+    hasChanges: async () => Boolean(await checked('git', ['status', '--porcelain', '--untracked-files=all'])),
+    listPullRequests: async (branch) => JSON.parse(await checked('gh', [
+      'pr', 'list', '--state', 'open', '--head', branch, '--json', 'number,url',
+    ]) || '[]'),
+    publishBranch: async (branch) => {
+      await checked('git', ['config', 'user.name', 'agent-workflow-kit[bot]']);
+      await checked('git', ['config', 'user.email', 'agent-workflow-kit[bot]@users.noreply.github.com']);
+      await checked('git', ['add', '--all']);
+      await checked('git', ['commit', '-m', UPDATE_TITLE]);
+      const remote = await checked('git', ['ls-remote', 'origin', `refs/heads/${branch}`]);
+      const expected = remote.split(/\s+/)[0] || '';
+      await checked('git', [
+        'push', `--force-with-lease=refs/heads/${branch}:${expected}`,
+        'origin', `HEAD:refs/heads/${branch}`,
+      ]);
+    },
+    createPullRequest: ({ title, body, branch }) => checked('gh', [
+      'pr', 'create', '--head', branch, '--title', title, '--body', body,
+    ]),
+    updatePullRequest: (number, { title, body }) => checked('gh', [
+      'pr', 'edit', String(number), '--title', title, '--body', body,
+    ]),
+  };
+}
+
+export async function runCli(options = {}) {
+  let report;
+  try {
+    report = await orchestrateUpdatePullRequest(createSystemAdapters(options));
+  } catch (error) {
+    report = { status: 'failed', branch: UPDATE_BRANCH, reason: error.message };
+  }
+  const rendered = `${JSON.stringify(report, null, 2)}\n`;
+  process.stdout.write(rendered);
+  if (process.env.GITHUB_STEP_SUMMARY) {
+    await appendFile(process.env.GITHUB_STEP_SUMMARY, `## Agent Workflow Kit update\n\n\`\`\`json\n${rendered}\`\`\`\n`);
+  }
+  if (report.status === 'conflicted') process.exitCode = 2;
+  else if (report.status === 'failed') process.exitCode = 1;
+  return report;
+}
+
+const invokedPath = process.argv[1] ? realpathSync(process.argv[1]) : '';
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  if (process.argv.includes('--help') || process.argv.includes('-h') || process.argv.includes('help')) {
+    process.stdout.write('Usage: agent-workflow-kit-update-pr\n');
+  } else {
+    await runCli();
+  }
+}

package/scripts/kit-update-pr.test.mjs

@@ -0,0 +1,99 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createSystemAdapters, orchestrateUpdatePullRequest } from './kit-update-pr.mjs';
+
+function harness({ update = { exitCode: 0 }, changed = true, pulls = [] } = {}) {
+  const calls = [];
+  return {
+    calls,
+    options: {
+      runUpdate: async () => (calls.push('update'), update),
+      hasChanges: async () => (calls.push('changes'), changed),
+      listPullRequests: async (branch) => (calls.push(['list', branch]), pulls),
+      publishBranch: async (branch) => calls.push(['publish', branch]),
+      createPullRequest: async (input) => calls.push(['create', input]),
+      updatePullRequest: async (number, input) => calls.push(['upsert', number, input]),
+    },
+  };
+}
+
+test('a successful update creates one stable update pull request', async () => {
+  const h = harness();
+  const report = await orchestrateUpdatePullRequest(h.options);
+
+  assert.equal(report.status, 'created');
+  assert.equal(report.branch, 'agent-workflow-kit/update');
+  assert.deepEqual(h.calls.map((call) => Array.isArray(call) ? call[0] : call), [
+    'update', 'changes', 'list', 'publish', 'create',
+  ]);
+});
+
+test('a conflict produces a structured report without touching the stable branch', async () => {
+  const h = harness({ update: { exitCode: 2, stdout: 'conflicts: 1', stderr: '' } });
+  const report = await orchestrateUpdatePullRequest(h.options);
+
+  assert.deepEqual(report, {
+    status: 'conflicted',
+    branch: 'agent-workflow-kit/update',
+    update: { exitCode: 2, stdout: 'conflicts: 1', stderr: '' },
+  });
+  assert.deepEqual(h.calls, ['update']);
+});
+
+test('a release mismatch fails without touching the consumer update branch', async () => {
+  const h = harness({ update: { exitCode: 1, stdout: '', stderr: 'release mismatch' } });
+  const report = await orchestrateUpdatePullRequest(h.options);
+
+  assert.equal(report.status, 'failed');
+  assert.equal(report.update.stderr, 'release mismatch');
+  assert.deepEqual(h.calls, ['update']);
+});
+
+test('ambiguous existing pull requests fail before the last good branch is changed', async () => {
+  const h = harness({ pulls: [{ number: 7 }, { number: 9 }] });
+  const report = await orchestrateUpdatePullRequest(h.options);
+
+  assert.equal(report.status, 'failed');
+  assert.equal(report.reason, 'multiple-open-pull-requests');
+  assert.deepEqual(h.calls.map((call) => Array.isArray(call) ? call[0] : call), [
+    'update', 'changes', 'list',
+  ]);
+});
+
+test('an already current consumer is a no-op', async () => {
+  const h = harness({ changed: false });
+  const report = await orchestrateUpdatePullRequest(h.options);
+
+  assert.equal(report.status, 'current');
+  assert.deepEqual(h.calls, ['update', 'changes']);
+});
+
+test('a repeated run updates the one existing stable pull request', async () => {
+  const h = harness({ pulls: [{ number: 7 }] });
+  const report = await orchestrateUpdatePullRequest(h.options);
+
+  assert.equal(report.status, 'updated');
+  assert.equal(report.pullRequest, 7);
+  assert.deepEqual(h.calls.map((call) => Array.isArray(call) ? call[0] : call), [
+    'update', 'changes', 'list', 'publish', 'upsert',
+  ]);
+});
+
+test('publishing commits in place and lease-protects the stable remote branch', async () => {
+  const commands = [];
+  const execute = async (file, args) => {
+    commands.push([file, ...args]);
+    if (args[0] === 'ls-remote') return { stdout: 'abc123\trefs/heads/agent-workflow-kit/update\n', stderr: '' };
+    return { stdout: '', stderr: '' };
+  };
+  const adapter = createSystemAdapters({ cwd: '/consumer', env: {}, execute });
+
+  await adapter.publishBranch('agent-workflow-kit/update');
+
+  const gitCommands = commands.map((command) => command.slice(1));
+  assert.equal(gitCommands.some(([verb]) => ['switch', 'checkout', 'reset'].includes(verb)), false);
+  assert.deepEqual(gitCommands.at(-1), [
+    'push', '--force-with-lease=refs/heads/agent-workflow-kit/update:abc123',
+    'origin', 'HEAD:refs/heads/agent-workflow-kit/update',
+  ]);
+});

package/scripts/test_skill_setup_workflow_seeds.py

@@ -45,6 +45,16 @@ def classify(first_line, is_empty):
     return "create" if is_empty else "skip"
 
 
+def update_workflow_action(
+    provider, choice, destination_exists, prerequisites=True,
+    pull_requests_allowed=True,
+):
+    """Reference decision table for the prompt-driven setup contract."""
+    if provider != "github" or destination_exists or choice != "enable":
+        return "skip"
+    return "create" if prerequisites and pull_requests_allowed else "skip"
+
+
 class IdempotencyRule(unittest.TestCase):
     CASES = [
         # (first_line, is_empty, expected)
@@ -71,6 +81,61 @@ class IdempotencyRule(unittest.TestCase):
 
 
 class SeedTemplatesValid(unittest.TestCase):
+    def test_update_workflow_provider_and_choice_fixtures(self):
+        fixtures = [
+            ("github", "enable", False, True, True, "create"),
+            ("github", "opt-out", False, True, True, "skip"),
+            ("github", "later", False, True, True, "skip"),
+            ("github", "enable", True, True, True, "skip"),
+            ("github", "enable", False, False, True, "skip"),
+            ("github", "enable", False, True, False, "skip"),
+            ("gitlab", "enable", False, True, True, "skip"),
+            ("local", "enable", False, True, True, "skip"),
+        ]
+        for provider, choice, exists, prerequisites, allowed, expected in fixtures:
+            self.assertEqual(
+                update_workflow_action(
+                    provider, choice, exists, prerequisites, allowed,
+                ), expected,
+            )
+
+    def test_github_update_opt_in_is_provider_aware_and_idempotent(self):
+        skill = (SKILL / "SKILL.md").read_text(encoding="utf-8")
+        for token in (
+            "Automatic Kit update pull requests",
+            ".github/workflows/agent-workflow-kit-update.yml",
+            "Opt out",
+            "Ask later",
+            "GitHub tracker",
+            "skipped (already present)",
+            "package-lock.json",
+            "npm test",
+            "can_approve_pull_request_reviews",
+            "Allow GitHub Actions to create and approve pull requests",
+            "explicit confirmation",
+        ):
+            self.assertIn(token, skill)
+        self.assertIn("do not create a GitHub workflow", skill)
+
+    def test_github_update_workflow_has_safe_triggers_and_scoped_runner(self):
+        workflow = (SKILL / "assets/agent-workflow-kit-update.yml").read_text(encoding="utf-8")
+        for token in (
+            "schedule:", "workflow_dispatch:", "contents: write",
+            "pull-requests: write", "agent-workflow-kit-update-pr",
+            "@ikon85/agent-workflow-kit@latest", "fetch-depth: 0",
+            "node-version: 22.14", "npm ci --ignore-scripts",
+        ):
+            self.assertIn(token, workflow)
+        for forbidden in ("npm_token", "NPM_TOKEN", "auto-merge", "gh pr merge"):
+            self.assertNotIn(forbidden, workflow)
+
+        mirror = (REPO / ".agents/skills/setup-workflow/assets/agent-workflow-kit-update.yml")
+        self.assertEqual(workflow, mirror.read_text(encoding="utf-8"))
+
+    def test_update_pr_runner_is_an_installed_package_binary(self):
+        package = json.loads((REPO / "package.json").read_text(encoding="utf-8"))
+        self.assertEqual(package["bin"]["agent-workflow-kit-update-pr"], "scripts/kit-update-pr.mjs")
+
     def test_spec_completeness_seed_has_valid_self_critique_block(self):
         """A convention without a valid Trigger/Check/Korrektur block makes
         spec-self-critique point 8 warn — the seed must carry one (Codex R1 #14)."""

package/src/lib/bundle.mjs

@@ -47,6 +47,9 @@ export const HELPER_FILES = [
   // the parity primitive rather than growing a second registry/GitHub comparison.
   { path: 'scripts/release-parity.mjs', kind: 'script', mode: 0o644 },
   { path: 'scripts/release-state.mjs', kind: 'script', mode: 0o644 },
+  // GitHub-consumer automation: invokes the existing update command, then owns
+  // only the stable tested branch/pull-request upsert.
+  { path: 'scripts/kit-update-pr.mjs', kind: 'script', mode: 0o755 },
   // Shared hook utility imported by the shipped hooks (drift-guard,
   // sync-board-status). Library (imported, not run) → 0o644. MUST ship or those
   // hooks ImportError on arrival.