Run a KORUS build

TLDR/BLUF

What this is. The build shape, with the opening prompt for each session and what to expect back. The shape comes from The KORUS framework, one operator’s account of months of Claude Code work; this page is the operating procedure for it.

Why you should care. Sessions with distinct jobs beat the same sessions all doing the same job, because the failures that cost you work come from two sessions deciding the same thing. Not for you until Quickstart is done: this page assumes the gates are installed and proven.

How to use it. Open the sessions in the order below. Each section states the goal, the prompt to paste, and what the session should do first.

The shape

A seat per job. Nothing here implements the roles: there is no seat script, no role flag, and no routing. The roles are a convention you establish in each session’s opening prompt and in your CLAUDE.md.

The ASVS monitor session is retired. It ran as a fifth session whose only job was keeping a security register current as the build sessions landed work. That seat ended on 2026-09-01.

Work too large for one context is the case this shape pays off in. An OWASP ASVS 5.0 assessment runs to several hundred requirements, more than one session can hold. Split across sessions, the cost is different unwritten rules: verdicts nobody can reconcile.

Large assessments is the method for that case.

Before you open any session

Plan on more than one account rather than treating it as a wrinkle. Set them up before you start: one desktop instance per account, and each one adds a config root the installers have to reach (Desktop accounts).

1. Open the console

The goal. One session holds the plan, so no builder has to guess what is next.

What to paste:

You are the console for this build. You plan and track; you do not write application code.

Read the backlog. Produce a build plan that breaks it into tasks sized for one session each,
and write an ADR for any decision that outlives the task that made it.

Write one disposable brief per task and open a build session on it. When a builder reports a
task blocked, its session ends: take the task back, update the backlog, and brief the next one.

Do not wait on a message from a builder. Poll for state instead.

Do not build. Do not merge.

What happens next. It reads the repository and comes back with a plan and a task breakdown. Ask it to write the backlog to a tracked file before it briefs anything, because a plan that lives only in one context dies with that context.

2. Open a build session per brief

The goal. One session per brief, each unable to silently overwrite the other.

What to paste, into each:

You are a build session. Build the task in your brief as a workflow, then stop.

If the brief leaves something open, do not guess and do not wait for an answer. Write the
question to the console, comment it on the pull request, and stop.

Before starting a task, take a claim on it with a one-line note saying what you are building:
  pwsh -NoProfile -File scripts/coord/claim.ps1 -Take "<task>" -Note "<what you are building>"

A free-text key like this is ADVISORY: peers can see it, and nothing enforces it. Only a
numbered key is enforced, by the commit-msg gate, and only when your commit subject names it.
A claim can also be refused because somebody holds it -- read the result.

Before editing a file you did not create, check who else is in it. Pass the path -- a bare
run prints the whole-repo roster and never names a file:
  pwsh -NoProfile -File scripts/coord/overlap.ps1 -File <path>

Read the exit code, not just the rows. 0 means the question was answered, including an
answer of nobody. 2 means it could not be, and silence there is not an all-clear.

Commit at logical stops. Push your own branch and open your own pull request. Do not merge:
the lander decides what enters the merge queue.

That prompt is a brief, and every brief runs out. Brief a worker session is the template for one, plus the rule that makes a worker ask rather than guess when it does.

What happens next. Each session announces itself to the peers it can reach, takes its claims, and starts building. When both reach for the same file, the second edit is normally refused rather than merged (Coordination).

“Normally” is doing work in that sentence. The gate refuses only when the peer worktree is live and holds uncommitted changes to that exact path. A peer that committed and went clean is reported and allowed.

It also fails open, and its blind spots are worth reading before you rely on it (Limits).

Why one brief per session. A session that ends when its brief is done spends nothing while it waits, where a session held open to poll pays for its whole context on every pass.

The five-hour cap is not the binding one. This shape spends a weekly window in about two days, which is why the framework page expects more than one account. That reasoning is in The KORUS framework.

Token accounting measures the other half: what one percent of a weekly window is worth, and what a month of it costs at published API rates.

3. Open the lander

The goal. One session owns the remote, so the trunk moves under a single decision-maker.

What to paste:

You are the lander. You decide what enters the merge queue and in what order, and you
merge-forward. Builders push their own branches and open their own pull requests.

Do not merge a pull request that has no reviewed label. Keep one ledger-appending pull
request in the queue at a time.

Read state rather than being told it:
  pwsh -NoProfile -File scripts/coord/presence.ps1   # who is live
  pwsh -NoProfile -File scripts/coord/overlap.ps1    # what is in flight

Decide which of two branches on the same ground lands first, and who re-syncs after.
You arbitrate and land. You do not build.

What happens next. It reads the branches rather than waiting to be told about them.

A pushed branch is the signal here, because builders push their own. The lander reads the open pull requests and takes the ones carrying a reviewed label.

Read the role page before you rely on it. The authority is not transferable, the route is absolute, and a worker that cannot reach the lander is blocked rather than promoted. Running multiple sessions owns the full role.

The daily loop

1. Ask the console what is in flight. It answers from the backlog, not from memory.
2. Check the builders have not collided. A bare overlap.ps1 gives the roster; -File <path> answers who is in one file.
3. Steer rather than wait. A session deep in the wrong approach does not see your typing until its turn ends (Steering).
4. Let the lander land. It decides the order. You approve the merge in words, once, and that approval does not carry to the next branch.
5. Prune what merged, from the primary checkout. prune-merged.ps1 refuses to run from a linked worktree, and every session here is in one. It removes worktrees that are merged and clean and unoccupied (Pruning).
6. Re-prove the gates when something surprises you. They fail byte-identically to succeeding, so a quiet week is not evidence: pwsh -NoProfile -File <tooling>/bin/ccx-doctor.ps1 -Repo <target> (Troubleshooting).

When it goes wrong

What this shape does not decide for you

Whether the work was any good. The gates refuse collisions. Nothing here reviews a change, and CI is what turns “it merged” into “it passed” (CI for leaders).

Whether you are about to run out. Usage-limit awareness is a design on this site, not a shipped hook (Usage awareness).

Who writes shared state outside git. Project memory and shared notes are last-write-wins, and the remedy is single-writer convention rather than a gate.

Related