ai-agents-process

The process the btclib-org maintainers follow with the coding agents Claude Code and Codex:

• skills/btclib-iss/SKILL.md — the /btclib-iss skill, from an issue to an open pull request, followed as its author;
• skills/btclib-pr/SKILL.md — the /btclib-pr skill, from an open pull request to the decision to approve, and to main;
• skills/btclib-pr/review-quota.md — what /btclib-pr does while the review bot's quota is exhausted, read only then;
• skills/btclib-table/SKILL.md — the /btclib-table skill, one table of every repository of the organization, which only reads;
• skills/btclib-table/measure.sh — the script /btclib-table runs to read that table;
• process/btclib-common.md — what /btclib-iss and /btclib-pr share, read whole by each;
• process/night-mode.md — what the orchestrator follows while night mode is on, read when it is turned on;
• process/load-generator.md — how a timing measurement takes every slot of the gate lock, read before running one;
• agents/writer.md — the agent that writes a change in its own worktree;
• agents/reviewer.md — the agent that reviews it at fresh context;
• agents/*.toml — the same two agents for Codex, which scripts/agents-toml.py writes from the .md files;
• hooks.json and scripts/git-c-allow.py — the hook that approves a fixed set of git -C commands;
• scripts/gate-lock.sh — the gate lock every worker of every session takes before its heavy gates;
• scripts/test-gate-lock.sh — sh scripts/test-gate-lock.sh shows sessions taking that lock's slots, and waiting while every slot is held;
• scripts/test-git-c-allow.py — the commands git-c-allow.py must approve and must refuse, run by the test-git-c-allow hook.

process/btclib-common.md's opening says how these files divide the process, and its Clients says what differs between the two agents.

Prerequisites

• Claude Code and Codex, both: a session runs in one, and its pull requests' fresh reviewer in the other (process/btclib-common.md's A pull request's rounds).
• gh, logged in (gh auth login).
• uv.
• python3 on the PATH, which runs scripts/git-c-allow.py.
• git signing your commits: commit.gpgsign = true and a key registered on GitHub. The process signs every commit it writes (process/btclib-common.md's Signed and signed off).

Setup

Clone the repository, and export its path as PROCESS, in this shell and where every later shell reads it, ~/.zshenv for zsh: each command either agent runs is a new shell, and the process finds its files through $PROCESS. The clone can sit at any absolute path without ", $, `, \, | or &, which the hook below cannot carry; ~/Git/ai-agents-process is only an example:

export PROCESS=~/Git/ai-agents-process

printf 'export PROCESS=%q\n' "${PROCESS:?}" >> ~/.zshenv

git clone https://github.com/btclib-org/ai-agents-process "${PROCESS:?}"

Then link its files where each agent reads them. Each link holds the clone's path as it was when the link was made: a clone moved later leaves the links pointing at nothing; remove them and make them again from the new path. ln -s refuses to overwrite an existing file: move any file of the same name you already have out of the way first.

Claude Code

Claude Code reads its files from $CLAUDE_CONFIG_DIR where that is set, and from ~/.claude otherwise. Run these once for each configuration directory your sessions use, with CLAUDE_CONFIG_DIR set to it:

mkdir -p "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills" \
  "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/agents"

ln -s "${PROCESS:?}/skills/btclib-iss" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/btclib-iss"

ln -s "${PROCESS:?}/skills/btclib-pr" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/btclib-pr"

ln -s "${PROCESS:?}/skills/btclib-table" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/btclib-table"

ln -s "${PROCESS:?}/agents/writer.md" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/agents/writer.md"

ln -s "${PROCESS:?}/agents/reviewer.md" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/agents/reviewer.md"

Add the hook under hooks in that directory's settings.json, with the clone's path written out for $PROCESS, since a hook's shell need not have it. Claude Code runs it before every Bash call:

"PreToolUse": [
  {
    "matcher": "Bash",
    "hooks": [
      {
        "type": "command",
        "command": "\"$PROCESS/scripts/git-c-allow.py\"",
        "timeout": 5
      }
    ]
  }
]

Check it in a new session: echo "$PROCESS" prints the clone's path, /btclib-iss, /btclib-pr and /btclib-table are listed among the skills, /agents lists writer and reviewer, and /hooks lists the PreToolUse hook.

Codex

mkdir -p ~/.agents/skills ~/.codex/agents

ln -s "${PROCESS:?}/skills/btclib-iss" ~/.agents/skills/btclib-iss

ln -s "${PROCESS:?}/skills/btclib-pr" ~/.agents/skills/btclib-pr

ln -s "${PROCESS:?}/skills/btclib-table" ~/.agents/skills/btclib-table

ln -s "${PROCESS:?}/agents/writer.toml" ~/.codex/agents/writer.toml

ln -s "${PROCESS:?}/agents/reviewer.toml" ~/.codex/agents/reviewer.toml

Codex reads its hooks from ~/.codex/hooks.json. Write it from hooks.json, with the clone's path for $PROCESS. Where the file exists already, add the PermissionRequest entry to it by hand instead. Codex runs the hook when a command needs approval, and refuses the PreToolUse answer Claude Code uses:

sed 's|\$PROCESS|'"${PROCESS:?}"'|' "${PROCESS:?}/hooks.json" > ~/.codex/hooks.json

Codex reads ~/.codex/AGENTS.md in every session. Point it at the process, so that a session started without a skill still finds it:

printf 'Work in a btclib-org repository follows %s, read whole first.\n' \
  "${PROCESS:?}/process/btclib-common.md" >> ~/.codex/AGENTS.md

Check it in a new session: echo "$PROCESS" prints the clone's path, /skills lists btclib-iss, btclib-pr and btclib-table, Codex names writer and reviewer when asked which custom agents it can spawn, and /hooks lists the PermissionRequest hook. Codex runs a hook only once you have trusted it there.

A machine set up before the skills

A machine set up before the commands became skills has links into the clone that the process no longer reads. Remove the ones it has, then make the links above. Like the links, run these once for each configuration directory your sessions use, with CLAUDE_CONFIG_DIR set to it:

rm "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/commands/btclib-iss.md" \
  "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/commands/btclib-pr.md" \
  "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/commands/btclib-table.md"

rm "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/process/btclib-common.md" \
  "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/scripts/gate-lock.sh"

A machine set up before the commands were split also has commands/btclib-org.md there:

rm "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/commands/btclib-org.md"

A hook in a settings.json that runs a copy of git-c-allow.py outside the clone is pointed at the clone's, as above.

Use

/btclib-iss <issue URLs or numbers>

takes issues to open pull requests, locally reviewed, and follows them as their author.

/btclib-pr [pull request URLs or numbers]

answers what the reviewers raised, gets CI green, and takes them to the decision to approve and to main. With no argument it sweeps the organization's open pull requests: by day it proposes which to work, at night it works them without asking, as its The sweep says.

/btclib-table

shows one table of every repository of the organization that is not archived: open issues, open pull requests, CI and README badge status, the last release, and whether a new one is due. It only reads.

In Codex each starts with $ instead of /: $btclib-iss.

/btclib-iss and /btclib-pr work in every repository of btclib-org; the shared Where you work says how the repository is named. /btclib-pr's The decision and Landing say when a session approves and when it lands, --land included.

Updating

Pull, with PROCESS exported as in Setup:

git -C "${PROCESS:?}" pull --ff-only

A skill or agent added since the machine was set up has no link yet: make it as Setup says. A machine set up before the skills says what an older machine removes. A change to hooks.json reaches Codex only once ~/.codex/hooks.json is updated from it as Setup says, and trusted again in /hooks.

The links then point at the new text. Do not edit the clone the links point at: change the process through a pull request from a worktree, reviewed by another person, like any other btclib-org repository. CONTRIBUTING.md says how.

Contributing

Development is LLM-based: humans are welcome, as long as they are comfortable with agentic development ;-). A contribution must have been read and understood by the person who submits it. CONTRIBUTING.md has the rules.

Status