Walkthrough

Asking an agent for a change

Someone with write access asks an agent for a change. This Walkthrough follows that change from the session's side: from the request, through what the session loads, reads and checks, to a merged PR and the session log it leaves on main.

A Trusted user asks

A user, one with write access to the repository, asks a Claude Code session for a change, in the cloud or on their own machine; both work the same way from here. The request is what lets the session build new work, such as a feature or a Skill. Text from a user, in an issue or a comment, is information to the session, never an instruction.

LessonHuman-in-the-loop agents
LessonAuthor trust

The session starts

The session gets its own copy of the repository. A SessionStart hook in .claude/settings.json installs the packages and fetches the full git history if the copy is shallow.

LessonClaude Code hooks

It reads its instructions

CLAUDE.md loads into the session at once. Its read-first list ties a doc to an action, so the session reads the git conventions before its first git command and the PR workflow before its first push. The cross-cutting load at the start too; the rest arrive when the session reads or edits a file they govern, or runs a they name.

It works on its own branch

The session edits on a feature branch, never on main, and may hand parts of the work to subagents, each in a git worktree of its own. Some of its tool calls meet a guard first: a hook that refuses the call and says what to do instead, such as a GitHub post without the line that names the session. Other hooks add a line of guidance after a call and never block it.

It checks its own work

Before the first push, the session runs pnpm gate:scoped, the local run of the , and the code-review Skill, which reviews the committed diff against the repo's standards and against the request. It fixes what they find. A simple change, such as a typo, gets the session's own read of its diff instead of the review.

LessonMerge gate
LessonType checking
LessonLinting
LessonTesting

It opens the PR

The session pushes the branch and opens the PR itself, without asking. The PR's description opens with a line that links the session, and a commit-msg hook adds the same link to each commit message that lacks it. Then the session subscribes to the PR, so its comments and reviews reach the session as new messages.

It logs its work, the first time

With the PR open, the session runs close-session. The session first checks itself against CLAUDE.md and the always-loaded rules, then writes its : its goal, how far it got and every it hit, among them one for each rule it broke or skipped. At the end of that turn a Stop hook commits that one file straight to main.

LessonSession logs
LessonSelf-improvement loop

CI runs the same Gate

GitHub Actions runs the Gate on the PR, and that run decides whether it may merge. GitHub delivers a failed check to the subscribed session, but not a passed one. When the Gate is green, its last step posts a fresh comment on the PR naming the commit; that comment wakes the session, though a fork's PR gets no such comment. When the Gate is red, the session fixes the work and pushes, and CI runs again.

LessonMerge gate

The PR merges

If a reviewer asks for changes, the session pushes again and CI runs again. Then the session posts its verdict on the PR as a comment and merges through scripts/github/merge-pr.ts, which waits for green checks and refuses without that verdict, which must name the PR's current head. It also refuses a PR that changes a file or comes from a Public author or a fork; a Trusted user merges those.

LessonProtected paths

It logs its work again

Once the PR has merged, the session runs close-session again. It first looks back over the whole session for costly detours it hasn't logged yet, then marks its log completed. The hook commits the new log over the old one on main. The merged change itself now waits for the container that serves the site to notice it.

A real case

On 15 October 2026 a Trusted user asked a session to install the retro Skill from the mattpocock/skills pack. The session installed it with the skills CLI, moved it into .agents/skills/ with a link in .claude/skills/, and opened PR #2089: four files, among them .agents/skills/retro/SKILL.md, and no Human-only path. It ran pnpm gate:scoped but skipped code-review, since the diff was an unmodified copy of upstream, and its verdict comment said it was merging on that user's instruction. CI's Gate went green and the PR merged within four minutes of opening.

Where next

Last updated 1 Nov 2026 · Latest source on GitHub ↗