This chapter is for architects and for people who speak IT. The question is simple: how does one person ship software with AI agents without losing control? My answer is not a model. It is the tooling around the models, which we call krizaka-agents. It is private: I show the pieces, how they talk to each other and a few details of how they work, not the code.
In chapter 31, I promised diagrams drawn from a model rather than by hand. Here they are. They come from one model written in LikeC4, the notation of the C4 model, checked like every system of the organisation. The last section explains how.
Three rules
Everything else follows from them.
- GitHub is the source. Issues, the board, pull requests, required checks, the merge queue: everything lives on GitHub. What we keep locally is a copy, to show and to warn. We never decide on a copy.
- No model where the answer must be certain. The launcher, the guards, the trains and the watchdog are plain code. A model decides what it writes, never what merges: asked the same question twice, it can give two answers.
- Agents do not talk to each other. A session writes what it has to say somewhere that stays: a commit, a pull request, a state file, a row in a database. It can be read again and replayed.
The context
The drawing in words
Elements
- Founder: Decides the direction and the money. A second app approves pull requests and the train merges them.
- AI agents: One session per lane, one pull request per issue, under the agents rules.
- Krizaka platform: How the org works: shared CI and standards, the agents tooling, the infrastructure as code, the templates.
- Agents tooling (Python, Node): Lanes, trains, guards and skills; runs on the founder machine.
- GitHub: Code, issues, pull requests, CI, the merge queue and the tags.
- Model providers: The AI models the products and the agents run on, local or hosted.
- Cloud hosting: The app and static site hosting, the managed databases.
Relations
- Founder → Agents tooling: instructs the CTO session, watches the cockpit
- AI agents → Agents tooling: run as its sessions
- Founder → GitHub: writes the tickets
- Agents tooling → GitHub: opens, lands and watches pull requests
- GitHub → Cloud hosting: deploys main
- Agents tooling → Model providers: every session runs on a hosted model
Two kinds of actors. Me: I write the issues, give my instructions to the CTO session and watch the cockpit. The AI agents: they do the rest, always as sessions of the tooling. An agent has no other way into a repository.
For the work, the tooling talks to GitHub only: it opens pull requests, sends them through the merge queue and reads the checks. Deploying is not its job: when main moves, the repository's pipeline deploys.
The other dependency is the model. The CTO session and the team sessions run in Claude Code, on Anthropic's hosted models. It is the one piece we cannot replace with plain code. So it is the piece we cap (below, “The budget”).
The containers
The drawing in words
Elements
- Founder: Decides the direction and the money. A second app approves pull requests and the train merges them.
- Agents tooling (Python, Node): Lanes, trains, guards and skills; runs on the founder machine.
- CTO session (Claude Code): An agent in conversation with the founder. Validates and splits the work, writes each brief, launches the teams, reads the alerts first.
- Cockpit (Next.js): The founder screen: teams, trains, alerts, the architecture. It reads; it never writes to GitHub, the alerts or the board.
- Watchdog (Python, cron): No model. Local checks every 15 minutes, GitHub read at most once an hour. Raises alerts; never writes to GitHub.
- Launcher (Python): Plain code, no model. Builds every headless session the same way: isolated, pinned, checked at start, capped in turns, budget and minutes.
- Team sessions (Claude Code): Headless, one per ticket, each in its own worktree: the teams, the repair session, the acceptance check.
- Rules and skills (Markdown): The rules, the skills and the preamble every session reads. Versioned and reviewed like code.
- Guards (Hooks, Python): Hooks around every tool call, at commit and at push, the local precheck, the ratchets. They refuse; they never fix by themselves.
- Trains (Python, shell): One ordered queue per repository. A runner carries the head through GitHub merge queue; a red PR is skipped with its reason.
- Operations database (SQLite): Local SQLite files, a projection: alerts, events, trains, live sessions; the board copy in a file of its own. Never a source: GitHub wins.
- GitHub: Code, issues, pull requests, CI, the merge queue and the tags.
Relations
- Founder → CTO session: instructs, decides
- Founder → Cockpit: watches
- CTO session → Launcher: launches a team with a brief
- CTO session → Operations database: reads the open alerts first
- Launcher → Team sessions: builds: isolated, pinned, checked
- Launcher → Operations database: records starts and ends
- Team sessions → Rules and skills: read
- Team sessions → Guards: commit and push through
- Team sessions → Trains: queue a pull request
- Trains → Operations database: record events
- Watchdog → Operations database: raises alerts
- Cockpit → Operations database: reads
- CTO session → GitHub: reads the board, writes the tickets
- Team sessions → GitHub: open pull requests
- Trains → GitHub: update, approve, enqueue
- Watchdog → GitHub: reads, at most hourly
- Operations database → GitHub: asks only for what changed
Nine containers, one job each. One question matters to an architect: where the model is, and where it is not.
| Container | What it does | A model? |
|---|---|---|
| CTO session | validates a task, splits it into issues, writes one brief per issue | yes |
| Launcher | builds every session the same way, with its caps | no |
| Team sessions | one issue, one worktree, one pull request | yes |
| Rules and skills | what every session reads: versioned Markdown, reviewed by pull request | no |
| Guards | refuse, with the reason | no |
| Trains | send green pull requests through the merge queue, one at a time | no |
| Watchdog | reads the machine and GitHub, raises alerts | no |
| Operations database | alerts, events, trains, live sessions | no |
| Cockpit | my screen: every figure with its date | no |
Two of nine have a model. The other seven cost no token and answer the same way every time.
The launcher and the team sessions
The CTO session does not start a team itself. It hands the brief to the launcher, code without a model. A team session has no screen and nobody to answer its questions: it has an issue, a brief and its caps. The launcher makes it identical at every start (chapter 27):
- isolated: the index of our code and the tools its team declares, nothing of the founder's accounts or personal settings;
- pinned: the version of Claude Code and of our plugins is written in the config and only moves by pull request;
- checked twice: the machine before the start, then what the session really loaded, at its first message. One difference, and it stops with the reason.
A session gets three sources, no more: the code index (a hook refuses to read a code file until the index has been queried), a web search that cites its sources for public facts, and our skills. When it does not know, it looks in two places, and both leave a trace.
The same launcher starts the repair session (the crack) and the acceptance session. There is no second path.
Teams are kept apart by a simple rule: one worktree per issue, and a pull request refused at opening when it touches a file that another open pull request already touches. We also have a richer coordinator, with leases and a scope reserved per task (the coordinator); it runs on one local repository, and no GitHub repository is under it yet.
The guards
A guard refuses and says why. It does not fix things silently (formatting aside): a silent fix hides the cause, and the error comes back with the next session.
| When | What is checked |
|---|---|
| Before and after every tool call | a hook refuses: a secrets file printed, a GitHub write without an app's identity, code read before the index; the edited file is formatted and linted on its own, in a few seconds |
| At commit and push | secrets and the author's identity; at push, the format and the workflow checkers |
| The pre-check, before the push | the repository's fast loop on what changed: lint, types, tests of the touched packages, generators, coverage of new code |
| In CI | the repository's required checks, plus two about the method: a fix must change a guard, and the ratchets |
The pre-check follows shift-left: what can be seen on the machine does not wait for CI. The reason is measured in chapter 29: of 4 pull requests red in CI, 3 failed on a check that existed locally and had not run.
A ratchet is a count of debt (lint warnings, duplicated code, exceptions to the architecture rules) written in a file that CI lets go down, never up. A new rule applies the same day; the old cases are counted and can only shrink.
Every refusal of a gate (opening a pull request, creating an issue, starting a session, entering a train) is written to one log. A rule stays when its count shows an effect; it is reviewed when it only makes noise.
The train and the merge queue
A session never merges. It opens its pull request with one tool, which carries the issue's “Done when” lines and refuses beyond five open pull requests per lane in the repository. Then it puts the pull request in the repository's train.
The train is a queue per repository and a script that empties it. fix pull requests go first, then the oldest. The script takes the head, rebases it on main, waits for the required checks and sends it into GitHub's merge queue, which runs the checks again on the real mix with main. A red head is skipped with its reason, and the next one goes. A red main freezes the repository's merges, not the opening of pull requests, until a fix lands.
A script waits for free; a session waiting a quarter of an hour of merge queue burns its budget. The story is in chapters 19 and 23.
The watchdog
The watchdog has no model. Every 15 minutes, it runs its local checks: scheduled jobs that fail or go silent, sessions that are stuck or loop. At most once an hour, it reads GitHub: a red main, a red pull request without an owner for an hour, a frozen repository. It never writes to GitHub. It raises alerts: one row per subject, open, taken with a note, or resolved with a proof.
The operations database and the cockpit
A local SQLite database keeps what I need to list and show: alerts, events, trains, live sessions. The copy of the board is in a second SQLite file, with its own tool. Everything that reads them runs on this machine, and a file needs no server.
- A projection, not a source. When a fact differs, GitHub is right. Nothing is merged, closed or declared done on the database's word alone.
- Rebuildable. The board and the state of pull requests are read again from GitHub. The database can be emptied without losing the work.
- The machine's own state (the alerts, who is alive and since when) is the only part GitHub does not know. The environment reports of session starts go through a journal and replay into an empty database; the history of alerts is not replayed yet.
The cockpit reads this database and GitHub, and shows every figure with its date. It can run a short, fixed list of local commands (reindex the code, refresh a view), only from the machine itself. It never writes to GitHub.
The budget: every session has its limits
A model costs at every turn, and a machine has one processor. So we bound both before a session starts, then while it runs. These are the gates a launch passes, in order:
- Validated size (S: 60 turns, M: 120)The CTO gives every task a size. Under the coordinator, a session never gets more turns than its task. Bigger work is split; it does not get more turns.
- Load brake (5-min load < 60)While the machine's 5-minute load average is at 60 or more, no session starts. No exception, and an unreadable load refuses too.
- Check before the start (binary, plugins, index)The pinned binary, every plugin at the marketplace's version, the code index, the preamble readable, the browser when the team needs one. The index must sync within a minute, or there is no start.
- The runner's caps (turns, dollars, minutes)The runner gives the session its turn cap and its dollar cap, and counts the minutes itself. When the time is up, it kills the process group. A session with no activity for 15 minutes is stopped too.
- First message (loaded = expected)What the session really loaded is compared with what the launcher expected. One difference, and it stops.
- At work (one issue, one pull request)The session works in its worktree, until its pull request or until it reaches its first cap.
The values are in the code, not in a document:
| Limit | Value | Where |
|---|---|---|
| Turns and minutes per team session | 150 turns, 180 minutes for most teams; 250 and 240 for Sovkora; 200 and 240 for the registry team; 300 and 300 for marketing; 60 and 30 for the log audit | tools/teams.json, caps |
| Dollar cap per session | one per team, next to the turns and the minutes | tools/teams.json, caps |
| Turns by the task's size | S: 60 at most, M: 120 at most; bigger, we split | tools/team-session.py |
| Load brake | no start at a 5-minute load of 60 or more | tools/teams.json, tools/session_env.py |
| Check before the start | a refusal before the first turn, with the reason | tools/session_env.py |
| Crack: sessions at once | 2 at most | tools/crack.py |
| Crack: sessions per 24 hours | 4 at most | tools/crack.py |
| Crack: each session | 80 turns, 90 minutes, a dollar cap | tools/crack.py |
The crack is the repair session that starts by itself when a call (a repository blocked by a red pull request) stays unclaimed for 15 minutes. Nobody launches it: so its limits are tighter than a team's.
The life of a pull request
The drawing in words
Elements
- Founder: Decides the direction and the money. A second app approves pull requests and the train merges them.
- CTO session (Claude Code): An agent in conversation with the founder. Validates and splits the work, writes each brief, launches the teams, reads the alerts first.
- GitHub: Code, issues, pull requests, CI, the merge queue and the tags.
- Launcher (Python): Plain code, no model. Builds every headless session the same way: isolated, pinned, checked at start, capped in turns, budget and minutes.
- Team sessions (Claude Code): Headless, one per ticket, each in its own worktree: the teams, the repair session, the acceptance check.
- Rules and skills (Markdown): The rules, the skills and the preamble every session reads. Versioned and reviewed like code.
- Guards (Hooks, Python): Hooks around every tool call, at commit and at push, the local precheck, the ratchets. They refuse; they never fix by themselves.
- Trains (Python, shell): One ordered queue per repository. A runner carries the head through GitHub merge queue; a red PR is skipped with its reason.
- Cloud hosting: The app and static site hosting, the managed databases.
- Cockpit (Next.js): The founder screen: teams, trains, alerts, the architecture. It reads; it never writes to GitHub, the alerts or the board.
- Operations database (SQLite): Local SQLite files, a projection: alerts, events, trains, live sessions; the board copy in a file of its own. Never a source: GitHub wins.
Steps, in order
- Founder → GitHub: writes the ticket and its « Done when »
- CTO session → GitHub: validates and sizes the ticket
- CTO session → Launcher: launches a team with the brief
- Launcher → Team sessions: starts it in a fresh worktree
- Team sessions → Rules and skills: reads the rules and the skills
- Team sessions → Guards: commits and pushes through the hooks
- Team sessions → GitHub: opens the PR, mirrors « Done when »
- Team sessions → Trains: queues the PR
- Trains → GitHub: updates, waits for CI, enqueues
- GitHub → Cloud hosting: merges and deploys main
- Trains → Operations database: records the landing
- Cockpit → Operations database: reads it for the founder
Follow the numbers. The one moment an agent is taken at its word is when it reads its own diff, and that reading decides nothing alone. The rest is checked: the issue says what “done” means, the session works in its worktree, the guards refuse early, the pull request carries the issue's lines with their proofs, the train only moves what is green, GitHub runs the checks again before the merge, and the merge is written to the database.
The review GitHub requires is given by a second app of ours, once per head commit, after the session has read its diff. Nobody reads a diff before the merge: what stands between a change and main is the checks, run again by the merge queue. A check can be tested and counted; that is why we chose it.
The life of an alert
The drawing in words
Elements
- Watchdog (Python, cron): No model. Local checks every 15 minutes, GitHub read at most once an hour. Raises alerts; never writes to GitHub.
- GitHub: Code, issues, pull requests, CI, the merge queue and the tags.
- Cockpit (Next.js): The founder screen: teams, trains, alerts, the architecture. It reads; it never writes to GitHub, the alerts or the board.
- CTO session (Claude Code): An agent in conversation with the founder. Validates and splits the work, writes each brief, launches the teams, reads the alerts first.
- Operations database (SQLite): Local SQLite files, a projection: alerts, events, trains, live sessions; the board copy in a file of its own. Never a source: GitHub wins.
- Team sessions (Claude Code): Headless, one per ticket, each in its own worktree: the teams, the repair session, the acceptance check.
Steps, in order
- Watchdog → GitHub: reads the checks and the pull requests, at most hourly
- Watchdog → Operations database: raises an alert: one row per subject, open
- Cockpit → Operations database: reads it for the founder
- CTO session → Operations database: reads the open alerts before any new work
- CTO session → Operations database: acknowledges it with a note: who looked, what was decided
- CTO session → Team sessions: launches a team on the cause, with a brief
- Team sessions → GitHub: opens the fix; the train lands it through the merge queue
- Watchdog → GitHub: sees the check green again, on a complete read
- Watchdog → Operations database: resolves the row, with the passing read as proof
An alert is a row with a state, not a message. The watchdog raises it. The CTO session reads the open alerts before any new work, takes one with a note (who looked, what was decided) and launches a team on the cause. Taking an alert does not close it. The watchdog resolves it itself when its next complete read no longer sees the problem, and keeps that read as the proof. A read that could not reach a repository proves nothing about it: it resolves nothing. The database refuses a resolution without a proof, whoever asks.
How the database follows GitHub
The drawing in words
Elements
- CTO session (Claude Code): An agent in conversation with the founder. Validates and splits the work, writes each brief, launches the teams, reads the alerts first.
- Cockpit (Next.js): The founder screen: teams, trains, alerts, the architecture. It reads; it never writes to GitHub, the alerts or the board.
- Operations database (SQLite): Local SQLite files, a projection: alerts, events, trains, live sessions; the board copy in a file of its own. Never a source: GitHub wins.
- GitHub: Code, issues, pull requests, CI, the merge queue and the tags.
Steps, in order
- CTO session → Operations database: a reader asks for the board copy
- Operations database → GitHub: if stale: asks only for what changed since the last read
- GitHub → Operations database: answers with the changed issues and pull requests, upserted
- CTO session → GitHub: a move is written on GitHub first
- CTO session → Operations database: then the cached card follows
- Cockpit → Operations database: reads the copy, no network call
No clock refreshes it. A reader that finds the copy too old triggers a read of what changed since the last one: one bounded query, then the board's cards, written at once. Ten readers at the same time wait on one lock, and GitHub is read once. A move on the board is written to GitHub first; the copy follows. At worst, a stale copy shows an old fact: every decision is checked again on GitHub.
What the audits measure
Two read-only audits, of the machine's logs and databases. The first covers 48 hours, from 13 November 19:00 to 15 November 19:10 (UTC):
- The environment: 340
env-ok, 0env-driftfor 332 launches (teams, crack, recette). - The caps: no run over its USD budget or its minutes.
- Session ends: 331
session-end+ 11stopfor 349 launches (7 alive), no duplicate end. - The trains: 92 landed, 37 skipped, each skip with its reason.
The second audit compared every local database with the logs and with GitHub, on 16 November: GitHub counts 814 pull requests merged across the organisation since 12 November. Both audits are internal issues, with their queries and their raw data.
Our trade-offs
Who decides a merge?
- Set aside
- the session itself
- Chosen
- the train and the merge queue Why: code that reads checks answers the same way every time. What it costs: a hole in a check is a hole in the review.
How to keep teams apart?
- Set aside
- a reservation service per task
- Chosen
- one worktree per issue, a refusal on files already touched Why: needs no running service. What it costs: two changes through different files only meet in CI.
Where to keep state?
- Set aside
- a server database
- Chosen
- SQLite on the machine, GitHub as the source Why: everything that reads it runs here; it rebuilds. What it costs: the history of alerts exists only here.
Where to see an error?
- Set aside
- in CI
- Chosen
- on the machine, before the push Why: a loop of a few seconds instead of a CI round trip. What it costs: a pre-check to keep fast.
Which skills to load?
- Set aside
- the whole account
- Chosen
- our 19 skills, pinned Why: the same context at every start, and a smaller one. What it costs: every skill is ours to maintain.
The skills our sessions load
Our rules and our trades are packaged as skills, in Claude Code's official format. A skill is a folder with a SKILL.md file: a name, a description of when to use it, then the instructions. A plugin bundles skills and subagents into one installable unit, and a marketplace is a catalogue of plugins with their versions. Anthropic also publishes its own skills in a public repository. We take the format, not their skills.
krizaka-ops
- Version
- 0.9.5
- Skills
- 3: session, issue, landing
krizaka-engineering
- Version
- 0.9.4
- Skills
- 11: the code standard and the rules per language
krizaka-design
- Version
- 0.8.0
- Skills
- 4: the Cahier style, product design, 3D pages, the design intervention
krizaka-growth
- Version
- 0.5.0
- Skills
- 1: honest technical posts
That makes 19 skills, plus a few subagents. At every start, the launcher turns off every plugin that is not ours. Before, a team session inherited the whole account: 252 skills and about 190,000 tokens of context from its first turn. Today it starts with 52 skills, our 19 among them, and about 47,000 tokens. The tool's built-in plugins stay: they are part of the tool.
The other databases
| Database | What it holds | How it is rebuilt |
|---|---|---|
| Each product's PostgreSQL | the data of Folioviv, Verikora and Sovkora, the only customer data; no foreign key between two contexts | schema in code, versioned migrations |
| One test database per worktree | one database per test file, on a real PostgreSQL, never a mock; a journey that creates a user deletes it | created by the test |
| The development databases | a cast of fictional characters | dropped and migrated from zero, compared with the schema snapshot; a nightly check opens an issue when they differ |
| The media | pictures, clips, books, pull request screenshots, on object storage behind a CDN | every file has a hash: it is replaced, never edited |
Sovkora at work: a photo in, a short video out
Sovkora is the product we build with this tooling. In the Video Studio, you pick a photo, write the movement in one sentence, and press Run.
How this was made
- Model
- Wan 2.2 TI2V 5B
- Engine
- Sovkora Video Studio, on a rented GPU switched off after the run
- Machine
- hosted by the provider (not our machine)
- Through
- screen of the studio, taken from the full-flow film
- Size
- 450×800 · 24 fps, 10.3 s
- Time
- not recorded
- Cost
- not recorded
- Sovkora run
- not recorded
- Note
- The Studio part of our own film of the full flow (15.5 s of it), sped up 1.5×, muted; not a new run.
Behind the button, from the code:
- A model is a row of data, not a branch of code. Each row of the catalogue names a model and the provider that serves it. The worker picks its adapter by the provider, never by the model, and refuses a provider nobody declared.
- Three places can make a video: a model the worker runs on a GPU machine, a hosted inference service, or a public GPU billed by the second. What stays ours in every case: the run, its seed, its measurement, the sealed file and its provenance.
- A failure stays a failure. A failed job, a timeout or an unsafe link raises an error; never a stand-in clip. The price of a hosted clip is reserved before the call.
- Pictures and voice run on our machines, with open models served locally. No hosted voice provider is wired into Sovkora.
How this was made
- Model
- Wan 2.2 TI2V 5B
- Engine
- Sovkora Video Studio, on a rented GPU switched off after the run
- Machine
- hosted by the provider (not our machine)
- Through
- screen of the studio, taken from the full-flow film
- Size
- 720×1280
- Time
- not recorded
- Cost
- not recorded
- Sovkora run
- not recorded
- Note
- A screen of Sovkora's Video Studio (development version, a fictional demo workshop), taken from our own film of the full flow; not a new run.
The run of our film, a vertical 704 by 1280 shot made from a photo with Wan 2.2 TI2V 5B, took 230 seconds from the click to the result, on a GPU rented for the run and turned off after. It is one run shown in a film, not a benchmark.
For our brand films, we also use two hosted generation services, one for pictures and clips, the other for voice and music. They are the team's tools: nothing in the product calls them. The film's credits say so.
How these diagrams are made
The model is a LikeC4 file in this blog's repository, written on the organisation's base (the kinds of elements, the people, GitHub, the cloud, the platform). It adds nothing at the top level: it only details the “Agents tooling” container.
A script runs layoutViews of @krizaka/architecture on it, the same check as for every repository's model: the file reads with the base, has no specification of its own, and every element it adds lives inside the one system it details. Verdict: “ok”, 9 elements added, the five views covered. The script keeps the layout with the model's hash, and the blog's tests fail if the model changes without it. The page draws it with ArchitectureDiagram of @krizaka/ui, in both themes, with the text version below.
The check proves that every box exists in the organisation's model. The arrows come from our documentation: we read them one by one, without measuring them.
Frequently asked questions
Is krizaka-agents open source?
No. The scripts, the rules and the skills that run our agents are private. This chapter shows the architecture, not the code.
Why do the agents not merge their own pull requests?
Because a merge needs a certain answer. The train is code that reads the required checks, and GitHub's merge queue runs them again on the real mix with main. A model writes the change; it does not decide that it is safe.
How does a session stay within its budget?
It has three caps, in turns, dollars and minutes, written per team in tools/teams.json. The runner applies them and kills the session when its time is up. A task validated S or M gets fewer turns still, and no session starts when the machine is too loaded.
Can the operations database be lost?
It can be emptied without losing the work: issues, pull requests and checks are on GitHub. What exists only locally, like the history of alerts, has an issue to replay it from journals.
