Slash Commands/Acceptpr Copy Section

---
summary: 'Land one PR end-to-end (changelog + thanks, lint, merge, back to main).'
read_when:
- You need to accept a PR: fix, lint, merge, sync main.
---

/acceptpr

Input: PR number or URL (required). Default merge mode: rebase.

0) Guardrails
- Must end on main (or repo default branch if no main).
- git status -sb clean before/after. No uncommitted changes.
- If PR is draft, has conflicts, or base branch != main: stop + ask.
- If PR is from a fork and you can’t push: stop + ask.

1) Capture context
- START_BRANCH="$(git branch --show-current)"
- gh pr view <PR> --json number,title,author,baseRefName,headRefName,isDraft,mergeable,maintainerCanModify
- Skim: gh pr view <PR> --comments and gh pr diff <PR>

2) Checkout + suggested fixes
- gh pr checkout <PR>
- Apply fixes (and tests if needed). Keep edits minimal; follow repo conventions.
- Ensure change/feature/regression is well-tested (add/extend tests, and run the smallest relevant test target until green).
- Commit with explicit paths (no git add .), then push: git push origin HEAD

3) Changelog (and thank contributor)
- Edit CHANGELOG.md (or project changelog file).
- Add entry under the top “Unreleased” section (match existing style).
- Include PR + thanks, e.g.: - <short change> (#<num>) — thanks @<author>
- Commit + push changelog if it changed.

4) Lint
- Run repo linter/gate (prefer existing scripts; fix until green).
- If there’s no obvious lint target, search: rg -n "lint|biome|eslint|swiftlint|ruff" package.json Makefile scripts -S

5) Merge (then delete PR branch)
- Prefer rebase merge: gh pr merge <PR> --rebase --delete-branch
- If rebase is disallowed, fallback to repo preference (--merge or --squash).

6) Sync main + exit clean
- git checkout main || git checkout "$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')"
- git pull --ff-only
- Verify merged: gh pr view <PR> --json mergedAt,mergeCommit
- git status -sb (clean) + ensure you’re on main.

---

Slash Commands/Fixissue Copy Section

---
summary: 'Fix an issue end-to-end (tests, changelog, commit, push, comment, close).'
read_when:
- You need a full issue fix workflow.
---

/fixissue

Purpose: fix an issue end-to-end, with tests and proper follow-through.

Do (in order):
1) Take your time, fix it properly, refactor if necessary.
2) Add regression tests and run them.
3) Add a changelog entry.
4) Commit, pull, and push.
5) Comment on the issue with what changed and close it.

If the issue URL/number isn’t provided, ask for it before the changelog/comment steps.

Location: global prompt lives in ~/.codex/prompts/fixissue.md; this file mirrors it for easy edits.

---

Slash Commands/Handoff Copy Section

---
summary: 'Codex handoff checklist for agents.'
read_when:
- Creating a /handoff prompt or refining handoff format.
---

/handoff

Purpose: package the current state so the next agent (or future you) can resume quickly.

Include (in order):
1) Scope/status: what you were doing, what’s done, what’s pending, and any blockers.
2) Working tree: git status -sb summary and whether there are local commits not pushed.
3) Branch/PR: current branch, relevant PR number/URL, CI status if known.
4) Running processes: list tmux sessions/panes and how to attach:
- Example: tmux attach -t codex-shell or tmux capture-pane -p -J -t codex-shell:0.0 -S -200
- Note dev servers, tests, debuggers, background scripts.
5) Tests/checks: which commands were run, results, and what still needs to run.
6) Next steps: ordered bullets the next agent should do first.
7) Risks/gotchas: any flaky tests, credentials, feature flags, or brittle areas.

Output format: concise bullet list; include copy/paste tmux commands for any live sessions.

Location: global prompt lives in ~/.codex/prompts/handoff.md; this file mirrors it for easy edits.

---

Slash Commands/Landpr Copy Section

---
summary: 'Land PR end-to-end (temp rebase, full gate, merge, thanks).'
description: Land PR end-to-end (temp rebase, full gate, merge, thanks).
argument-hint: <pr-number|pr-url?>
read_when:
- Landing a PR end-to-end (temp rebase, full gate, merge, thanks).
---

/landpr

Input
- PR: $1 (number or URL). If missing: use most recent PR in convo; if ambiguous: ask.

Goal
- End state: GitHub PR state = MERGED (never CLOSED).

0) Guardrails
- git status -sb clean (no local changes).
- If PR is draft, has conflicts, or you can’t push to head branch: stop + ask.
- Prefer repo default branch as base (often main).

1) Capture PR context

PR="$1"
gh pr view "$PR" --json number,title,state,isDraft,mergeable,author,baseRefName,headRefName,headRepository,maintainerCanModify --jq '{number,title,state,isDraft,mergeable,author:.author.login,base:.baseRefName,head:.headRefName,headRepo:.headRepository.nameWithOwner,maintainerCanModify}'
prnum=$(gh pr view "$PR" --json number --jq .number)
contrib=$(gh pr view "$PR" --json author --jq .author.login)
base=$(gh pr view "$PR" --json baseRefName --jq .baseRefName)
head=$(gh pr view "$PR" --json headRefName --jq .headRefName)
head_repo_url=$(gh pr view "$PR" --json headRepository --jq .headRepository.url)

2) Update base + create temp branch

git checkout "$base"
git pull --ff-only
git checkout -b "temp/landpr-$prnum"

3) Checkout PR + rebase onto temp

gh pr checkout "$PR"
git rebase "temp/landpr-$prnum"

4) Fix + tests + changelog
- Implement fixes (keep scope tight).
- Add/adjust tests (regression when it fits).
- Update CHANGELOG.md: include #$prnum + thanks @$contrib.

5) Gate (before commit)
- Run full repo gate (lint/typecheck/tests/docs). Example: pnpm lint && pnpm build && pnpm test.

6) Commit

git add CHANGELOG.md <changed files>
git commit -m "fix: <summary> (#$prnum) (thanks @$contrib)"
land_sha=$(git rev-parse HEAD)

7) Push rebased PR branch (fork-safe)

git remote add prhead "$head_repo_url.git" 2>/dev/null || git remote set-url prhead "$head_repo_url.git"
git push --force-with-lease prhead "HEAD:$head"

8) Merge PR
- Rebase: gh pr merge "$PR" --rebase
- Squash: gh pr merge "$PR" --squash
- Never gh pr close.

9) Sync base locally

git checkout "$base"
git pull --ff-only

9b) Return to main (final local state)

git checkout main
git pull --ff-only
git branch --show-current

10) Comment with SHAs + thanks

merge_sha=$(gh pr view "$PR" --json mergeCommit --jq '.mergeCommit.oid')
gh pr comment "$PR" --body "Landed via temp rebase onto $base.
- Gate: <cmds>
- Land commit: $land_sha
- Merge commit: $merge_sha
Thanks @$contrib!"

11) Verify state == MERGED

gh pr view "$PR" --json state,mergedAt --jq '.state + \" @ \" + .mergedAt'

12) Cleanup

git branch -D "temp/landpr-$prnum"

---

Slash Commands/Pickup Copy Section

---
summary: 'Codex pickup checklist when starting on a task.'
read_when:
- Creating a /pickup prompt or onboarding a new task.
---

/pickup

Purpose: rehydrate context quickly when you start work.

Steps:
1) Read AGENTS.MD pointer + relevant docs (run pnpm run docs:list if present).
2) Repo state: git status -sb; check for local commits; confirm current branch/PR.
3) CI/PR: gh pr view <num> --comments --files (or derive PR from branch) and note failing checks.
4) tmux/processes: list sessions and attach if needed:
- tmux list-sessions
- If sessions exist: tmux attach -t codex-shell or tmux capture-pane -p -J -t codex-shell:0.0 -S -200
5) Tests/checks: note what last ran (from handoff notes/CI) and what you will run first.
6) Plan next 2–3 actions as bullets and execute.

Output format: concise bullet summary; include copy/paste tmux attach/capture commands when live sessions are present.

Location: global prompt lives in ~/.codex/prompts/pickup.md; this file mirrors it for easy edits.

---

Slash Commands/Raise Copy Section

---
summary: 'Raise next patch Unreleased section in CHANGELOG.md (commit + push).'
read_when:
- You just cut a release and want to open the next patch cycle.
---

/raise

Goal: If CHANGELOG.md top release is dated (not Unreleased), create a new top section for the next patch version as Unreleased, then commit + push only CHANGELOG.md.

0) Guardrails
- Must be on main (or repo default) and git status -sb clean.
- If CHANGELOG.md already starts with ## <version> — Unreleased: stop (nothing to do).
- If the top ## version can’t be parsed as X.Y.Z: stop + ask.

1) Compute next patch
- In CHANGELOG.md, find the first header like: ## X.Y.Z — <date|Unreleased>.
- If suffix is a date (released), bump patch: X.Y.(Z+1).

2) Edit changelog
- Insert at the top (above the last released section):
- ## X.Y.(Z+1) — Unreleased
- blank line
- Do not touch any other release sections.

3) Commit + push
- git add CHANGELOG.md && git commit -m "docs(changelog): start X.Y.(Z+1) cycle"
- git push

4) Verify CI
- GH_PAGER=cat gh run list -L 5 --branch main --json status,conclusion,workflowName,displayTitle,updatedAt
- If any run fails: gh run view <id> --log, fix, commit, push, repeat.

---

Slash Commands/README Copy Section

---
summary: 'Index of slash commands (prompts) and where they live.'
read_when:
- Auditing or updating slash command docs.
---

Slash Commands

Slash commands are reusable prompt templates that live in ~/.codex/prompts/ (global) and, when present, in repo-local folders (e.g., .claude/commands/, .cursor/commands/). This folder mirrors the global set so agents can discover and edit them in-repo.

Available commands Copy Chapter

See the individual files in this directory for details.

---

Slash Commands/Sectriage Copy Section

---
summary: "Finish security advisory triage (land fix, gates, GHSA patch, ready-to-publish)."
read_when:
- After discussion, when asked to finish GHSA triage end-to-end.
argument-hint: "<ghsa-or-url?>"
---

/sectriage

Use after discussion. When you say “update this on GitHub via gh” (or you type /sectriage), that is consent for remote writes: I will patch the GHSA via gh api and verify.

Intent Copy Chapter

Default intent: land the fix on main directly (commit + push; no PR), update CHANGELOG.md, and keep the GHSA in a “ready to publish later” state. No separate/private PR workflow unless you explicitly ask.

Invocation Format (you paste, optional) Copy Chapter

Prefer minimal. If you only give ghsa (or URL), I will derive the rest from the repo + tags and only ask if something is ambiguous.

- repo: owner/name (optional; default from git remote)
- ghsa: GHSA-.... (or advisory URL)
- severity: low|medium|high|critical
- cvss: full vector string (optional; but include if we want it set/restored)
- affected: human range line for text (example: <= 2026.2.13)
- vuln_range: GitHub structured vulnerable_version_range (example: <=2026.2.13)
- patched_versions: planned fixed version (normally the version you’re about to ship next; from changelog/release prep)
- package: usually openclaw (npm)
- credits: reporter handle (example: @akhmittra)
- fix_commits: one or more full SHAs for internal evidence only (do not place SHAs, PRs, or fix mechanism in public text)
- summary: 1-liner summary (no GHSA id)
- description_md: full Markdown for advisory description (must include an “Affected Packages / Versions” section)

What I Do (execute, not suggest) Copy Chapter

1. Parse inputs. Derive repo from git remote -v if omitted. Extract GHSA id from URL if needed.
2. Preflight:
- git status --porcelain (must be clean or only expected files)
- fetch advisory via gh api …security-advisories/<GHSA> and show current structured fields
- existing fix PR scan (prefer re-use; avoid duplicate fixes):
- if advisory has private_fork.full_name: gh pr list -R <privateFork> --state open
- also search upstream: gh pr list -R <repo> --search "<GHSA>" --state all
- if there’s a credible fix PR already:
- review via gh pr view / gh pr diff
- fetch PR head branch and cherry-pick commits (avoid local branch switching): git fetch <remote> <headRef> then git cherry-pick <sha>…
- fetch latest published versions:
- npm view <pkg> version --userconfig "$(mktemp)"
- update vulnerable_version_range to include that latest version if the issue still exists on main
- fixed-version rule (optimize for “press publish only”):
- use the planned next release version from CHANGELOG.md (if present) or package.json
- set patched_versions to that planned version even if npm publish hasn’t happened yet
- this keeps the advisory ready so the only follow-up action is “Publish” after npm is out
3. Local verify (required):
- pnpm check
- pnpm exec vitest run --config vitest.gateway.config.ts
- pnpm test:fast
4. Changelog:
- ensure CHANGELOG.md has ## Unreleased + ### Fixes entry
- no GHSA id mention
- includes thanks to reporter
- ensure wording implies it ships in the next npm release (that’s the whole point: no more ticket edits)
- commit only if changelog needed changes
5. Git:
- if there are local commits ahead of origin: git pull --rebase then git push
6. Similar-issue scan (read-only):
- list other pathToFileURL( + dynamic import( callsites
- list obvious path-join/resolve callsites
- if I find a credible escape bug: stop and report (do not “surprise-fix” during /sectriage)
7. GHSA patch (remote write; invocation is consent):
- write /tmp/ghsa.desc.md from description_md
- required in description_md:
- explicit versions (latest published + affected ranges)
- fix provenance using only release version or patched-version field; no raw SHAs, PR titles/numbers, or fix-mechanism summary in public text
- “Release Process Note”: patched version is pre-set to the planned next release; once npm release is out, just publish the advisory
- write /tmp/ghsa.patch.json with summary, severity, description, and vulnerabilities[]:
- vulnerable_version_range uses latest published npm version (usually <=<npmVersion>)
- patched_versions uses the planned next release version (from changelog/package.json)
- gh api -X PATCH … --input /tmp/ghsa.patch.json
- if cvss provided: patch cvss_vector_string
8. Verify:
- re-fetch advisory, print html_url, state, vulnerabilities, cvss, updated_at
- print GHSA link

Implementation Notes (hard rules) Copy Chapter

- Avoid JSON quoting footguns:
- description_md goes to /tmp/ghsa.desc.md
- build JSON via jq -n --rawfile desc /tmp/ghsa.desc.md …
- Advisory comments endpoint may not exist via REST; update via description + structured fields.
- State transitions (accept/publish) likely UI/Publisher-only; do not attempt unless you explicitly ask.
- For public advisory text, avoid “Fixed by” / “Fix Commit(s)” sections, raw commit hashes, PR titles/numbers, and implementation summaries. Keep exact SHAs and PRs in internal notes.

---

Concurrency Copy Section

Swift Concurrency (Approachable) - RepoBar Notes

Goal Copy Chapter

Core Ideas Copy Chapter

Async/Await (Deep Cut) Copy Chapter

Tasks (Units of Work) Copy Chapter

Where Code Runs (Isolation Domains) Copy Chapter

From Threads to Isolation Copy Chapter

Approachable Concurrency Defaults Copy Chapter

Isolation Inheritance Rules Copy Chapter

Sendable (Crossing Boundaries) Copy Chapter

When to Introduce an Actor Copy Chapter

Preferred Patterns Copy Chapter

Common Mistakes Copy Chapter

Quick Reference Copy Chapter

---

Mac App Copy Section

---
summary: "Scaffold checklist for a new macOS menu bar app with Sparkle updates"
read_when:
- Scaffolding a new macOS menu bar app with Sparkle.
---

New macOS App Scaffold (Sparkle + DevID + shared release flow)

This is a practical, minimal checklist to get a new macOS (SwiftPM) menubar app ready for distribution via Sparkle and our shared release scripts.

1) Project skeleton Copy Chapter

2) Bundle identifiers & feeds Copy Chapter

3) Sparkle keys Copy Chapter

4) Packaging & signing scripts (SwiftPM) Copy Chapter

5) Appcast Copy Chapter

<?xml version="1.0" standalone="yes"?>
  <rss xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle" version="2.0">
      <channel>
          <title><AppName></title>
      </channel>
  </rss>

6) Required env vars for releases Copy Chapter

7) Release flow (shared pattern) Copy Chapter

8) Verification checklist Copy Chapter

9) Common gotchas Copy Chapter

10) Files to add in a new repo Copy Chapter

With these pieces in place, the app will align with CodexBar/Trimmy/RepoBar release hardening and shared Sparkle verification.

---

Npm Publish With 1password Copy Section

---
summary: "Publish to npm via tmux + 1Password CLI (op)"
read_when:
- "Need npm publish without copy/paste secrets."
- "Need npm OTP/TOTP from 1Password."
---

npm publish via tmux + op

Goal: publish to npm without pasting tokens/passwords into terminal logs.

Hard rule: do not run op whoami, op item list, op item get, op read, or any other
1Password CLI command directly in a normal shell for this workflow. Use the tmux
session below first, and send every op command through that tmux session. Direct
op commands can trigger repeated 1Password desktop alerts.

Prereqs Copy Chapter

- 1Password desktop app unlocked + CLI integration enabled.
- op installed.
- tmux installed.

tmux session (required) Copy Chapter

Use a persistent tmux session so op auth survives across commands.

SOCKET_DIR="${CLAWDBOT_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/clawdbot-tmux-sockets}"
mkdir -p "$SOCKET_DIR"
SOCKET="$SOCKET_DIR/op-auth.sock"
SESSION="op-auth-$(date +%Y%m%d-%H%M%S)"
tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
tmux -S "$SOCKET" send-keys -t "$SESSION":1.1 -- "op signin" Enter
tmux -S "$SOCKET" send-keys -t "$SESSION":1.1 -- "op whoami" Enter

All commands below assume that same tmux socket/session. If you need to discover
the item name or fields, do it inside tmux too, for example:

tmux -S "$SOCKET" send-keys -t "$SESSION":1.1 -- "op item list" Enter
tmux -S "$SOCKET" send-keys -t "$SESSION":1.1 -- "op item get '<Item>' --vault '<Vault>'" Enter

Preferred: granular automation token (+ optional OTP) Copy Chapter

Store a granular npm token in 1Password (item field token), plus TOTP if required.
For Peter's npm account, the 1Password item is op://Private/Npmjs.

TOKEN_REF='op://Private/Npmjs/token'
OTP_REF='op://Private/Npmjs/one-time password?attribute=otp'
tmux -S "$SOCKET" send-keys -t "$SESSION":1.1 -- "NODE_AUTH_TOKEN=\"\$(op read \"$TOKEN_REF\" | tr -d \"\\n\")\" npm publish --otp \"\$(op read \"$OTP_REF\" | tr -d \"\\n\")\"" Enter

Notes:
- tr -d "\n" avoids accidental extra submits when pasting/reading.
- Avoid printing token/OTP (no echo, no set -x, no pane capture right after OTP).

If you’re already logged in: OTP-only publish Copy Chapter

If npm whoami works, you usually only need OTP for publish:

OTP_REF='op://<Vault>/<Item>/one-time password?attribute=otp'
tmux -S "$SOCKET" send-keys -t "$SESSION":1.1 -- "npm publish --otp \"\$(op read \"$OTP_REF\" | tr -d \"\\n\")\"" Enter

Tip: unset CI tokens so you don’t accidentally override your local login:

env -u NPM_TOKEN -u NODE_AUTH_TOKEN npm whoami

Fallback: npm login using op buffers (no echo) npm login using op buffers (no echo)')" title="Copy chapter prompt for LLMs"> Copy Chapter

When password auth is unavoidable, avoid typing secrets by piping into tmux
buffers and pasting. Peter's npm account is stored in the 1Password item
Npmjs in the Private vault.

USER_REF='op://Private/Npmjs/name'
PASS_REF='op://Private/Npmjs/password'
EMAIL_REF='op://Private/Npmjs/email'
OTP_REF='op://Private/Npmjs/one-time password?attribute=otp'
load buffers (strip trailing newline)

tmux -S "$SOCKET" send-keys -t "$SESSION":1.1 -- "op read \"$USER_REF\"  | tr -d \"\\n\" | tmux -S \"$SOCKET\" load-buffer -b npm_user  -" Enter
tmux -S "$SOCKET" send-keys -t "$SESSION":1.1 -- "op read \"$PASS_REF\"  | tr -d \"\\n\" | tmux -S \"$SOCKET\" load-buffer -b npm_pass  -" Enter
tmux -S "$SOCKET" send-keys -t "$SESSION":1.1 -- "op read \"$EMAIL_REF\" | tr -d \"\\n\" | tmux -S \"$SOCKET\" load-buffer -b npm_email -" Enter
run login; paste at prompts (repeat pattern for Email/OTP)

tmux -S "$SOCKET" send-keys -t "$SESSION":1.1 -- "npm login --auth-type=legacy" Enter
tmux -S "$SOCKET" paste-buffer -t "$SESSION":1.1 -b npm_user
tmux -S "$SOCKET" send-keys    -t "$SESSION":1.1 -- Enter
tmux -S "$SOCKET" paste-buffer -t "$SESSION":1.1 -b npm_pass
tmux -S "$SOCKET" send-keys    -t "$SESSION":1.1 -- Enter
tmux -S "$SOCKET" paste-buffer -t "$SESSION":1.1 -b npm_email
tmux -S "$SOCKET" send-keys    -t "$SESSION":1.1 -- Enter
tmux -S "$SOCKET" paste-buffer -t "$SESSION":1.1 -b npm_otp
tmux -S "$SOCKET" send-keys    -t "$SESSION":1.1 -- Enter

If the item has duplicate labels, extract by field purpose/type from JSON inside
tmux instead of reading by label:

tmux -S "$SOCKET" send-keys -t "$SESSION":1.1 -- "op item get Npmjs --vault Private --format json | node -e \"let s='';process.stdin.on('data',d=>s+=d);process.stdin.on('end',()=>{const item=JSON.parse(s);const fields=item.fields||[];const pick=(fn)=>fields.find(fn)?.value||'';process.stdout.write(pick(f=>f.purpose==='USERNAME'))})\" | tmux -S \"$SOCKET\" load-buffer -b npm_user -" Enter
tmux -S "$SOCKET" send-keys -t "$SESSION":1.1 -- "op item get Npmjs --vault Private --format json | node -e \"let s='';process.stdin.on('data',d=>s+=d);process.stdin.on('end',()=>{const item=JSON.parse(s);const fields=item.fields||[];const pick=(fn)=>fields.find(fn)?.value||'';process.stdout.write(pick(f=>f.purpose==='PASSWORD'&&f.type==='CONCEALED'))})\" | tmux -S \"$SOCKET\" load-buffer -b npm_pass -" Enter
tmux -S "$SOCKET" send-keys -t "$SESSION":1.1 -- "op item get Npmjs --vault Private --format json | node -e \"let s='';process.stdin.on('data',d=>s+=d);process.stdin.on('end',()=>{const item=JSON.parse(s);const fields=item.fields||[];const pick=(fn)=>fields.find(fn)?.value||'';process.stdout.write(pick(f=>f.label==='email'))})\" | tmux -S \"$SOCKET\" load-buffer -b npm_email -" Enter

Gotchas:
- If npm says “Incorrect or missing password”, the 1Password password is stale or the paste didn’t reach the prompt.
- Don’t run tmux capture-pane after pasting OTP (it may echo); wait 30–60s if you must debug.
- Repeated reads of the password field can trigger multiple 1Password “password used/copied” alerts; OTP-only flow avoids that entirely.

Verify Copy Chapter

npm whoami
npm view <pkg> version

Cleanup Copy Chapter

tmux -S "$SOCKET" kill-session -t "$SESSION"
rm -f "$SOCKET"

---

RELEASING Copy Section

---
summary: 'Shared release guardrails (GitHub releases + changelog hygiene)'
read_when:
- Preparing a release or editing release notes.
---

Shared Release Guardrails

- Title every GitHub release as <Project> <version> — never the version alone.
- Release body = the curated changelog bullets for that version, verbatim and in order; no extra meta text.
- Attach all shipping artifacts (zips/tarballs/checksums/dSYMs as applicable) that the downstream clients expect.
- If the repo has its own release doc, follow it; otherwise adapt this guidance to the stack and add a repo-local checklist.
- When a release publishes, verify the tag, assets, and notes on GitHub before announcing; fix mismatches immediately (retitle, re-upload assets, or retag if necessary).
- NPM releases: assume login is already set up; publish may require the user’s 6-digit OTP or it will fail. If OTP/TOTP is in 1Password, prefer op (see docs/npm-publish-with-1password.md).

---

RELEASING MAC Copy Section

---
summary: 'Reusable macOS release playbook (Sparkle, notarization, GitHub releases)'
read_when:
- Shipping or debugging a macOS release.
---

Releasing macOS Apps (Sparkle + GitHub)

Reusable checklist distilled from recent VibeTunnel, Trimmy, and CodexBar releases. Adapt the script names and paths to the target repo before running anything.

Must read: this master file lives at ~/Projects/agent-scripts/docs/RELEASING-MAC.md. Open it alongside any repo-local release doc and reconcile differences before starting.

Scope & Assumptions Copy Chapter

Prerequisites Copy Chapter

Versioning Rules Copy Chapter

Prep: Review History & Changelog Copy Chapter

Pre-flight Copy Chapter

git checkout main && git pull --rebase
git status

echo test > /tmp/sparkle.txt
sign_update -f "$SPARKLE_PRIVATE_KEY_FILE" /tmp/sparkle.txt --account "${SPARKLE_ACCOUNT:-default}"
rm /tmp/sparkle.txt

for v in /Volumes/; do [[ $v == /<App>* ]] && hdiutil detach "$v" -force; done

Build, Sign, Notarize Copy Chapter

Shared release skill Copy Section

Sparkle Signing & Appcast Copy Chapter

sign_update -f "$SPARKLE_PRIVATE_KEY_FILE" path/to/<App>-<ver>.dmg --account "${SPARKLE_ACCOUNT:-default}"

GitHub Release & Tag Copy Chapter

Verification (Definition of Done) Copy Chapter

Final Sign-Off (agent handoff) Copy Chapter

Recovery / Resume Copy Chapter

One-Page Checklist Copy Chapter

---

Slash Commands Copy Section

---
summary: 'Slash commands overview and redirect to docs/slash-commands.'
read_when:
- Editing or adding slash commands.
---

Slash Commands

Moved to docs/slash-commands/. See docs/slash-commands/README.md for the index.

1. Create a markdown file in ~/.codex/prompts/:

echo "# /mycommand\n\nYour prompt instructions..." > ~/.codex/prompts/mycommand.md

2. Use the command in any Codex/Claude Code session:

/mycommand

3. The agent will execute the prompt from the file

Best Practices Copy Chapter

- Be specific: Include exact commands, safety checks, and exit conditions
- Document constraints: No destructive git, coordination rules, scope boundaries
- Make them reusable: Avoid task-specific details (dates, ticket numbers)
- Test them: Run the slash command to verify it works as expected
- Version control: Consider storing project-specific commands in .claude/commands/ (repo-local)

Project-Local Commands Copy Chapter

For project-specific workflows, you can also create commands in the repo root:

.claude/commands/ - For Claude Code
.cursor/commands/ - For Cursor AI

These are checked into version control and shared with the team.

This Project's Commands Copy Section

This repository includes the following commands in both .claude/commands/ and .cursor/commands/:

.claude/commands/          .cursor/commands/
├── automerge.md          ├── automerge.md
├── build.md              ├── build.md
├── commit.md             ├── commit.md
├── commitgroup.md        ├── commitgroup.md
├── improve.md            ├── improve.md
├── fix.md                ├── fix.md
└── massageprs.md         └── massageprs.md

Available commands:
- /automerge - Automated PR review & merge
- /build - Build validation with fixes
- /commit - Selective commit helper
- /commitgroup - Group multiple commits logically
- /cppp - Commit all changes in grouped commits and push
- /different - Post-review reflection: what would you change?
- /doit - Enter autonomous coding mode and execute the plan
- /improve - Post-ship retro helper
- /fix - Run quality checks & fix all failures
- /massageprs - Continuous PR maintenance loop

These commands work identically in both Claude Code and Cursor.

---

Subagent Copy Section

---
summary: 'Multi-agent system directives and coordination rules. Master reference for agent behavior.'
read_when:
- Coordinating subagents or running tmux-based agent sessions.
---

Claude Subagent Quickstart

CLI Basics Copy Chapter

tmux new-session -d -s claude-haiku 'claude --model haiku'
  tmux attach -t claude-haiku

Once inside the session, run /model to confirm the active alias (haiku maps to Claude 3.5 Haiku) and switch models if needed.
- Need to queue instructions without attaching? Use tmux send-keys -t <name> "your command" Enter to inject text into a running agent session.
- Always switch to the fast Haiku model upfront (claude --model haiku --dangerously-skip-permissions … or /model haiku in-session) to keep turnaround fast.
- Two modes:
- One-shot tasks (single summary, short answer): run claude --model haiku --dangerously-skip-permissions --print … in a tmux session, wait with sleep 30, then read the output buffer.
- Interactive tasks (multi-file edits, iterative prompts): start claude --model haiku --dangerously-skip-permissions in tmux, send prompts with tmux send-keys, and capture completed responses with tmux capture-pane. Expect to sleep between turns so Haiku can finish before you scrape the pane.
- A manual supervisor loop can launch Claude the same way (claude --dangerously-skip-permissions "<prompt>") to keep tmux automation flowing.

One-Shot Prompts Copy Chapter

Bulk Markdown Conversion Copy Chapter

Supervisor Loop Notes Copy Chapter

---

Update Changelog Copy Section

---
summary: 'Checklist for curating CHANGELOG.md from recent commits'
read_when:
- Updating CHANGELOG.md or drafting release notes.
---

Update CHANGELOG.md

Purpose: curate user-facing changes since the last release tag and record them in CHANGELOG.md (Unreleased section) for this repo. Derived from the /update-changelog prompt, the macOS release notes guide, and CodexBar/Trimmy AGENTS notes.

Scope & Inputs Copy Chapter

Steps Copy Chapter

git log <tag>..HEAD --oneline --reverse

Quick format example Copy Chapter

Unreleased  Copy Chapter

- Added configurable status probe refresh interval. #123
- Fixed menu bar icon dimming on sleep/wake. #128

---

Windows Copy Section

---
summary: "Windows setup notes for running agent scripts"
read_when:
- Working on Windows or PowerShell setups for agent scripts.
---

Windows notes

- Install Git for Windows and ensure git is on PATH.
- Install Bun (needed to run the Bun-based shims in bin/): irm https://bun.sh/install.ps1 | iex. The installer drops bun.exe in %USERPROFILE%\.bun\bin and adds it to the user PATH; restart shells to pick it up.
- Running the shims from PowerShell:
- bun bin/docs-list

Note: Windows may not honor the UNIX shebang line when launching shims in bin/ directly. Using bun bin/<tool> ... is the most reliable cross-shell invocation.

---

CHANGELOG Copy Section

---
summary: Timeline of guardrail helper changes mirrored from Sweetistics and related repos.
---

Changelog

Unreleased Copy Chapter

- Added headless Sparkle signing through scoped 1Password references, with public-key validation, mode-0600 temporary files, and cleanup on success or failure.
- Corrected GitHub secret provisioning to omit --body for stdin and added a skill validation guard against the literal-dash trap.
- Taught the clawsweeper-status snapshot to report queue handoff health, the ready/admissible split, backoff and parked reasons, and shed-since-reset, so exact-review items parked on retry exhaustion are no longer invisible behind a healthy verdict.
- Added the project-structure skill: a TypeScript symbol-map generator that compresses a repository into one context-loadable file with dense/skeleton/exports tiers, plugin-boundary listings, and measured token budgets.
- Removed the obsolete scoped-commit helper and returned commit recipes to standard Git now that agent work uses isolated worktrees.
- Made the million-token Codex provider and context settings an explicit atomic invariant, with a fatal preflight diagnostic for the unrecoverable openai plus 922K/700K split configuration.
- Added a fleet audit and repair action that disables Claude commit, pull-request, and session-link attribution while preserving unrelated settings and detecting higher-precedence overrides.
- Added narrow Homebrew 6 trust handling for exact third-party formulae already declared in a fleet profile.
- Made Apple-classified outdated/unusable Xcode runtimes and unavailable simulator devices required fleet drift, with a booted-device-safe audit and repair action.
- Established the SF Mini's classic OpenSSH fleet path, documented symmetric tailnet TCP 22 policy and proof rules, and recorded the MiniClaw duplicate-daemon regression and public-SSH fallback.
- Added the separately owned SF Mac Mini and distinguished its local/Tailscale names from FoundationClaw while its trusted SSH path remains pending.
- Verified FoundationClaw's provider identity, installed Tailscale and Jump Desktop Connect v10, and documented its data-preserving credential-reset escalation before GUI activation.
- Added ClawMac provider-outage triage that escalates console, NIC-link, and switch-port inspection without repeated power cycles or data-affecting recovery.
- Restored MiniClaw's canonical Homebrew Tailscale node and removed its duplicate GUI identity from fleet guidance.
- Removed obsolete Mac identities from remote fleet discovery guidance after pruning them from Tailscale.
- Reconciled the remote-Mac topology with provider purchases, including FoundationClaw's MacStadium identity and MiniClaw's canonical Tailscale identity.
- Reserved GPT-5.6's maximum output budget in codex-huge-context and moved fleet compaction to a verified 922K input window with a 700K safety threshold.
- Made codex-first treat the Gorilla-backed Clawdex endpoint as already model-routed, preventing recursive Codex delegation after the fleet proxy migration.
- Added a secret-safe Codex direct-API preflight so million-token launches fail before an unauthenticated Responses request when a machine is missing its Keychain delivery copy.
- Generalized interactive 1Password routing to select the active approval workstation within the matching personal or work-managed environment while preserving service-account isolation and safe offline fallback.

2026-07-17 — 0.12.0 Copy Chapter

Highlights Copy Section

Maintainer Orchestration Copy Section

Review and Agent Workflows Copy Section

Fleet, Release, and Remote Operations Copy Section

Credentials and Safety Copy Section

Skills and Tools Copy Section

2026-05-14 — Video Transcript Dependency Update Copy Chapter

2026-05-14 — Codex Review Finding Detection Copy Chapter

2026-05-14 — Codex Review Full Access Copy Chapter

2026-05-14 — GitHub Search Shim Guidance Copy Chapter

2026-05-14 — Codex Review Base Caveat Copy Chapter

2026-05-14 — Codex Review Loop Guidance Copy Chapter

2026-05-14 — README Skills Overview Copy Chapter

2026-05-14 — Codex Review Skill Copy Chapter

2026-05-13 — Checkout Discipline Copy Chapter

2026-05-13 — Skill Metadata Guardrails Copy Chapter

2026-05-11 — clawmac GUI Access Note Copy Chapter

2025-12-22 — Remove Custom rm Shim Copy Chapter

2025-12-17 — Remove Runner; Keep Guardrails Copy Chapter

2025-12-02 — Release Preflight Helpers Copy Chapter

2025-11-18 — Console Log Capture Copy Chapter

2025-11-22 — Search & Content Extraction Copy Chapter

2025-11-15 — Chrome Browser Tools Copy Chapter

2025-11-16 — Browser Tools Pipe Detection Copy Chapter

2025-11-14 — Compact Runner Summaries Copy Chapter

2025-11-08 — Sleep Guardrail & Git Shim Refresh Copy Chapter

2025-11-08 — Guardrail Sync & Docs Hardening Copy Chapter

2025-11-08 — Initial Toolkit Import Copy Chapter

---

README Copy Section

Agent Scripts

Shared agent instructions, skills, and small portable helpers for Peter's local workspaces.

This repo is the canonical place for:
- AGENTS.MD: shared hard rules for Codex/Claude-style agents
- skills/: reusable workflow skills, including repo-owned skills exposed by symlink
- scripts/: dependency-light helpers used across projects
- hooks/: local guardrails such as skill validation

Skills Copy Chapter

Skills are the main routing layer. Each skills/<name>/SKILL.md has YAML front matter:

---
name: skill-name
description: "Short generic trigger phrase."
---

Rules:
- Keep descriptions short and generic; optimize for routing, not documentation.
- Keep skill bodies terse and operational.
- Prefer helper scripts under skills/<name>/scripts/ when a workflow has repeatable commands.
- Validate after edits: scripts/validate-skills.
- Quote description in front matter.

Global discovery is built by scripts/sync-skills (idempotent; run on every Mac after cloning or adding skills):
- Codex scans nested dirs, so it gets whole-root links: ~/.codex/skills/agent-scripts -> ~/Projects/agent-scripts/skills, ~/.codex/skills/manager -> ~/Projects/manager/skills.
- Claude Code loads only ~/.claude/skills/<name>/SKILL.md (exactly one level deep; per-entry symlinks are followed, category subfolders are not scanned — verified on 2.1.197). It gets a flat per-skill link mirror covering both repos plus machine-local ~/.codex/skills/<name> extras.
- Name collisions resolve agent-scripts > manager > codex-local; the script prints skipped duplicates and prunes broken/stale managed links.

Shared personal skills live as real folders in skills/. Public OpenClaw shared skills live in ../agent-skills and are exposed here with tracked relative symlinks. Repo-owned skills stay canonical in their repo and are exposed here the same way, for example:

skills/autoreview -> ../../agent-skills/skills/autoreview
skills/discrawl -> ../../discrawl/.agents/skills/discrawl

Current symlinked repo-owned skills include birdclaw, discrawl, gog, imsg, slacrawl, wacli, and wacrawl.

Agent Instructions Copy Chapter

Shared hard rules live in AGENTS.MD.

Global setup (also maintained by scripts/sync-skills; Claude Code reads CLAUDE.md only, so it links to the shared AGENTS.MD):
- ~/.codex/AGENTS.md -> ~/Projects/agent-scripts/AGENTS.MD
- ~/.claude/CLAUDE.md -> ~/Projects/agent-scripts/AGENTS.MD
- ~/.claude/AGENTS.md -> ~/Projects/agent-scripts/AGENTS.MD

Downstream repos should use a pointer-style AGENTS.MD:

READ ~/Projects/agent-scripts/AGENTS.MD BEFORE ANYTHING (skip if missing).

Repo-specific rules go below that pointer. Do not copy the shared blocks into downstream repos.

Helpers Copy Chapter

scripts/sync-skills
- Builds the per-machine skill mirror: Codex whole-root links, Claude flat per-skill links, shared AGENTS.MD pointers.
- Idempotent; prints changes only, prunes broken/stale managed links, never clobbers real files.

scripts/validate-skills
- Checks every skills/*/SKILL.md.
- Verifies YAML front matter plus required name and description.
- Enable as a local hook with git config core.hooksPath hooks.

scripts/docs-list.ts
- Walks docs/.
- Enforces summary and read_when front matter.
- Prints onboarding summaries for repos that wire it in.

scripts/browser-tools.ts
- Standalone Chrome DevTools helper.
- Common commands: start --profile, nav <url>, eval '<js>', screenshot, console, network, search --content "<query>", content <url>, inspect, kill --all --force.
- Build optional binary with bun build scripts/browser-tools.ts --compile --target bun --outfile bin/browser-tools.

Syncing Copy Chapter

Treat this repo as canonical for shared agent rules and portable helper scripts.

When syncing downstream repos:
- Pull latest here first.
- Ensure each target repo starts with the pointer-style AGENTS.MD.
- Preserve repo-local rules below the pointer.
- Copy helper changes both directions only when the helper is meant to stay byte-identical.
- Keep scripts dependency-free and portable; no repo-specific imports or path aliases.

For submodules, repeat the pointer check inside each subrepo, push those changes, then bump submodule SHAs in the parent repo.

---