Lifecycle

1Install

Set up

Add kerby to your agent once per machine. Then run /kerby install once in each repo. It asks before every change it makes.

First it adds one line to your agent file — CLAUDE.md, AGENTS.md, AI-CONTEXT.md or .cursorrules — so each session loads the rules. Then it shows the hooks in a table and asks: all, choose, or none. Last, it offers a git pre-commit hook, so the secret scan and other commit checks also run inside git itself.

Source: kerby README § Install; SKILL.md § install

2Load

Set up

At the start of each session, kerby picks the rulebook and reads its rules into the agent’s context.

It picks from your lock file first, then from files in your repo such as package.json. When it cannot tell, it asks you. It never picks silently. It prints one line that says what it loaded.

The line that install adds to your agent file does this for you. To load by hand, or to check later that the rules are still loaded:

rulebook: <id>@<version> (<origin>) — source: explicit | pinned | intent | detected | chosen

Source: kerby SKILL.md § Rulebooks, selection

3Read the projectInstructions only

Set up

Before any work, the agent reads what the project already knows: agent-context.yaml, the status and log in .kerby/, the knowledge base, CONTEXT.md, DESIGN.md, your agent file, and the last 20 commits.

If agent-context.yaml is missing, the agent creates it.

For UI work with no DESIGN.md at the root, it looks for a design spec in other folders and under other names before it invents any token.

How swe handles UI and design work →

Source: BOOTSTRAP.md § 2

4Grade and routePartly hook-enforced

Decide

The agent grades the task from 1 to 10 and picks a route, such as feature or bugfix.

It also says where it stopped on the decision ladder: is this needed at all, does the standard library do it, does the platform do it, does an installed package do it, can it be one line — and only then, new code. Both lines appear on every change, even a one-word fix.

A hook warns when the agent edits a high-stakes file, because those files always need the full workflow.

complexity: <N> (trigger: <≤8-word reason>) → route: <investigate | new-project | adopt-existing | feature | bugfix | quick-task>
rung: <N> — <≤8-word reason>

Source: BOOTSTRAP.md § 1b, § 2.5, § 3

5PlanInstructions only

Decide

Before the first edit, the agent names the files, the change, and how it will check the result.

From grade 4, it writes a full plan: the expected result and a table of test cases. From grade 7, it stops and waits for your approval.

plan: <files> — <change> — <check>
plan: <files> — <change> — <check> (full plan waived: user opt-out "<quoted phrase>")

Source: BOOTSTRAP.md § 4 Plan Gate

6IntentInstructions only

Decide

Before an edit that changes behavior, the agent writes three things: what the code does now, what the test or task expects, and what the docs say.

If the three disagree, it does not edit yet. It tells you which one it trusts and why. The order of trust is: your own words, then the docs, then the tests, then the current code.

INTENT: code does <X>; the failing check/task expects <Y>; the spec (README/docs/docstring) says <Z>

Source: references/intent-gate.md

7BranchPartly hook-enforced

Build

The agent never works on a protected branch: main, master, dev, develop, staging, release/*, trunk. It creates a branch with a short typed name, such as fix/null-user.

It makes a separate git worktree only when there is a reason, such as two agents working at once, and it says the reason in one line. A hook blocks any commit on a protected branch.

creating worktree at .worktrees/<branch-name> — trigger: <which>

Source: BOOTSTRAP.md § 4 Branching

8Build in small stepsInstructions only

Build

The agent works in a loop: pick one piece, do it, check it, commit it, log it, repeat. It prefers to write the test first.

When something fails, it reads the code that causes it before it changes anything, and it cites the file and line. If your request is short and unclear, it asks one question before costly actions: starting sub-agents, creating more than 3 files, editing more than 5, installing packages, or a git action that cannot be undone.

Source: workflows/feature.md § 5; BOOTSTRAP.md § 4

9CheckInstructions only

Build

Before each commit, the agent picks a quality gate from what is staged, runs it, and reads the whole output. Quick runs lint. Standard runs build, lint and test. Full adds end-to-end tests and a manual check.

Nothing checks that a gate really ran. A reminder hook points out skipped tests at commit time, but it does not stop the commit.

Source: references/quality-gates.md

10CommitPartly hook-enforced

Build

After each finished piece, the agent commits only the files it changed. The message starts with a type, one of feat fix chore docs refactor test perf build ci.

At this moment the hooks check three things: no secret is staged, the branch is not protected, and STATUS.md states no version, SHA or PR number.

Source: BOOTSTRAP.md § 4 Commit Discipline

11LogInstructions only

Build

After each commit, the agent adds an entry to .kerby/memory.log: the task, what it did, the files, the commit, and whether it is done or blocked.

It also records facts it noticed, such as a slow build or a skipped test. Facts only, no advice — you decide what to act on.

Source: BOOTSTRAP.md § 4 Commit Discipline

12ReportInstructions only

Finish

The final report always gives you steps to check the work by hand, and one line that names what the agent chose not to build.

When there was a full plan, each test case from it gets a result line. The agent stops any server it started. It never merges.

skipped: <what you did not build> — add when <trigger>
outcome: <case> — match | mismatch | not exercised

Source: workflows/feature.md § 7; BOOTSTRAP.md § 4

13Save and resumePartly hook-enforced

Finish

Before the conversation gets too long, the agent updates STATUS.md and the log and commits them, so the next session can start where this one stopped.

Long conversations get compacted, and rules read earlier can be lost. In Claude Code, if you installed kerby’s session hook, it puts the rules back after a compaction. Otherwise, reload them by hand.

Source: BOOTSTRAP.md § 6; kerby SKILL.md § Compaction