The short guide · 5-minute read

How to work with many agents and keep control

We took industry best practice in software design and shaped it into a lightweight, Agile-style way of working for teams that build with AI agents. It is a few habits, all recorded in GitHub, where your work already is. Use all of it, some of it, or none of it: the dashboards work either way.

1. Every piece of work is a GitHub issue

An issue is a numbered task in GitHub. An open issue that has not started yet (it has no stage label) is part of your backlog, the list of work still to do. Group related issues under one larger issue, which we call an initiative, using GitHub's sub-issues (issues nested inside another), so you can always answer "what is this for?"

2. One label says where it is

A label is a tag on an issue. Each issue carries exactly one stage label, written "phase:" and then the stage name, and that label is the official record. A column on the board only ever repeats it.

1. scoping: is this worth doing, and what exactly is it?
2. planning: the approach is decided and written down.
3. building: writing the code, and the small tests that check each part of it.
4. e2e (end-to-end): testing the whole thing the way a user would, until every required automated test passes on the latest version of the change.
5. review: waiting for someone to review the change, or approved and waiting to be added to your code (merged).
6. deploying: merged, but not live yet.
7. monitoring: live and being watched. Close the issue once it has behaved.

A blocked label sits beside the phase, so the board shows where the work stopped, not just that it stopped.

3. Agents say what they hold, on the issue

Before it starts, each running agent posts a short note on the issue, called a claim: this agent holds this task, on this machine, and expects to change these files. It keeps the note up to date while it works and removes it when it stops. A small script in our agent pack (the instructions and tools we give your agents) writes the claim for it.

That is how you stop asking agents what they're doing. The Agents board shows who holds what, and the collision radar warns when two agents, or two branches (separate working copies of your code), touch the same files. Shared jobs, such as releasing to your live site, can be claimed too, so only one agent runs them at a time.

4. Connect each pull request to its issue

Every piece of work starts as an issue, and GitHub gives each issue a number, such as #57. When an agent finishes the work, it opens a pull request, which asks for its changes to be added to your code. In the pull request's description, the agent writes "Closes #57". That tells GitHub which issue the change is for. KirinBoard uses this connection to show the issue, the pull request and its test results together, so you can see what each agent did and why. When the pull request is merged, GitHub marks issue #57 as closed. The work isn't finished yet, though: the issue's label changes to "deploying" until the change is live, then "monitoring" while you check it works.

5. Let the tests decide, and merged is not done

Work moves on only when every required automated test passes on the latest version of the change. After it is merged, it is deploying until it is live, then monitoring while you watch it. Teams skip this rule most often, and it is the one that most often hides work that never reached your users. Truth checks flag where the labels and what really happened disagree, such as an issue closed when its change never reached your code.

What we leave out

Sprints, story points and stand-ups (fixed two-week work cycles, effort scores and daily status meetings). Agents work in minutes and hours, not two-week blocks, and the dashboards answer "what are you working on?" all the time. We measure flow instead: how fast work moves through the stages, and where it waits. Keep any meeting your team values. Nothing in KirinBoard depends on one.

Another tracking tool. GitHub issues, labels and sub-issues are the record. Stop using KirinBoard and they still make sense.

Getting started

1. Sign in with GitHub, then connect KirinBoard to the repositories (project folders) you choose. It can only look, never change anything.
2. Add the agent pack to a repository: a file of instructions your agents follow, and the script that posts their claims. You'll find it in the Docs once you sign in.
3. Watch the dashboards fill in. Nothing is enforced unless you choose to enforce it.

The full method, with every rule and the claim format, is in the Docs after you sign in.