# 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](KORUS.md), 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](QUICKSTART.md) 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 console writes one brief and spawns a builder for it, and that builder exits when the brief is done. Each builder gets its own worktree and its own branch. The collision gate still refuses an edit to a file a peer already holds. A pull request reaches the lander only through the reviewer, and the merge queue is what merges. A red check goes to the regulator, which sends back only the pull request's own failure. The dashed box and arrow mark machinery rather than a seat.

| Session | Owns | Must not | |---|---|---| | **Console** | The plan, the backlog, and which task gets briefed next | Write application code | | **Builder** | The change, the commit, the push, and the pull request for one brief | Guess at what the brief left open, or wait for an answer | | **Reviewer** | Reading the diff on one pull request, and the reviewed label | Merge, or label a pull request it did not read | | **Regulator** | Deciding whose failure a red is: the pull request's, the trunk's, a flake's, or the queue's | Assume it remembers an earlier red | | **Lander** | What enters the merge queue and in what order | Merge a pull request with no reviewed label | **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](https://secure-development-standards.pages.dev/ASVS-ASSESSMENT.html) is the method for that case. ## Before you open any session | Do this | Why | Where | |---|---|---| | Install and prove the gates | Roles are advisory; the gates are not | [Quickstart](QUICKSTART.md) | | Give each session its own worktree | Two sessions in one tree overwrite each other | [Worktrees](WORKTREES.md) | | Check the config root your console runs on can spawn a session | Spawning is granted per config root, not per machine, and a root without the grant refuses | [Desktop accounts](DESKTOP-ACCOUNTS.md) | | Wire the steering hook | It only takes effect in sessions started afterwards | [Steering](STEERING.md) | | Write the working agreement | It only reaches sessions that start later | [CLAUDE.md.template](https://claude-multisession.pages.dev/CLAUDE.md.template) | | Turn on Ultracode and pick Opus 5 in every session | The build shape assumes workflows and adversarial review | [The KORUS framework](KORUS.md) | | Be on Max 20x, and expect to need more than one account | This shape spends a weekly window in about two days. Check current plan terms yourself; that page dates from 2026-08 | [The KORUS framework](KORUS.md) | **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](DESKTOP-ACCOUNTS.md)). ## 1. Open the console **The goal.** One session holds the plan, so no builder has to guess what is next. **What to paste:** ```text 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: ```text 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 "" -Note "" 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 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](WORKER-BRIEF.md) 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](COORDINATION.md)). **"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](LIMITS.md#what-the-collision-gate-does-not-see)). **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](KORUS.md). [Token accounting](TOKEN-ACCOUNTING.md) 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:** ```text 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](RUNNING-MULTIPLE-SESSIONS.md) 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 ` 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](STEERING.md)). 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](PRUNING.md)). 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 /bin/ccx-doctor.ps1 -Repo ` ([Troubleshooting](TROUBLESHOOTING.md)). ## When it goes wrong | Symptom | What it actually is | Go to | |---|---|---| | Two branches built the same feature | Effort overlap. No gate can compute it | [Coordination](COORDINATION.md) | | Two records took the same number | The collision git cannot see | [Sequence allocation](SEQUENCE-ALLOC.md) | | A session is deep in the wrong approach | Your typing queues until the turn ends | [Steering](STEERING.md) | | Branches will not land | Four states with three different fixes | [PRs and merges](PR-AND-MERGE.md) | | A peer cannot be reached at all | Extension session, or another login | [Session mail](SESSION-MAIL.md) -- a design to build, not a shipped lane | | Everything is green and you cannot tell if any of it runs | Every failure here looks like success | [Limits and requirements](LIMITS.md) | ## 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](CI-FOR-LEADERS.md)). **Whether you are about to run out.** Usage-limit awareness is a design on this site, not a shipped hook ([Usage awareness](USAGE-AWARENESS.md)). **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 | For | Read | |---|---| | The template for one worker's prompt, and the rule that stops it guessing | [Brief a worker session](WORKER-BRIEF.md) | | The account of why this shape, in its author's words | [The KORUS framework](KORUS.md) | | Which surface to run the sessions on, and the channels between them | [Running multiple sessions](RUNNING-MULTIPLE-SESSIONS.md) | | The model every page here applies | [Concepts](CONCEPTS.md) | | The things that bite, in the order they bite | [Tips and tricks](TIPS-AND-TRICKS.md) |