A software factory methodology

Stop babysitting agents.Hire a foreman.

Works through your tickets overnight without drifting: every job starts fresh from files. A cheap model does the heavy coding, so your Claude Code limit lasts far longer.

Install ↓View on GitHub ↗

No driftA fresh session for every job. The plan, the steps, the reviews and the notes for next time are files, not chat memory.
CheaperThe builder does the token-heavy work. The foreman only plans, checks and decides.
ProofEvery job ends with what was asked, what was built, what was tested and what was found.

Watch one jobYour part, and the AI’s part, from ticket to merge.

Three ways to run a job:

With youYou give each word: go, open the PR, merge.Autonomous runOne /goal line takes one job to the merge.Night shiftOne line before bed: several jobs in a row.

1Plan

Pick a ticket, then say go.In a fresh session, one line: /goal autonomous run: <opener>, until done or stoppedBefore bed, one line: /goal night shift: jobs 13, 17, until done or stopped

Reads the ticket and your code, and writes a plan.Plans, and answers its own planning questions with its recommended pick.A shift manager opens a fresh AI session for each job and starts it for you.

2Build

Nothing, if Orca links the panes. Otherwise paste one line per step.Nothing: Orca passes each step to the builder.Nothing: Orca passes each step to the builder.

Splits the plan into small steps. A cheaper model builds each one, tests first.Splits the plan into small steps. A cheaper model builds each one, tests first.Splits the plan into small steps. A cheaper model builds each one, tests first.

3Check

Nothing. It carries on.Nothing. It carries on.Nothing. It carries on.

Two separate reviews, then checks every requirement has proof.Two reviews, then the proof check. Anything that fails gets fixed, not a stop.Two reviews, then the proof check. Anything that fails gets fixed, not a stop.

4Your OKCovered by your goalCovered by your goal

Open the PR, then merge when you’re happy with the proof.Nothing to say: your goal covers the PR, up to three automated reviews, and the merge.Covered by each job’s goal.

Opens the pull request. Say greploop and it runs up to three automated reviews.Opens the PR, runs the reviews, merges.Opens the PR, runs the reviews, merges.

5Merged

OK the next ticket.Read the PR and the report: every answer it gave itself is listed, so you can reverse it.Read the morning report.

Closes the job, saves what it learned, suggests the next ticket.Closes the job, saves the records, and stops. It never starts the next job.Closes the job, and the next one starts. Several jobs done by morning.

Topped outEach merged job adds a floor. When the whole goal is built, the building tops out.

AIThe report

When the whole goal is built: a record of what was done and what’s left, plus three to five ideas for the next goal.

Idea 1
Idea 2
Idea 3
Idea 4

YouYou pick one

Whenever you’re ready. In every mode, the AI stops when the goal is built and never picks the next one itself.

AIA new board

A fresh board for the new goal, and the job loop starts again.

Every word is yours. Nothing passes go, open the PR, greploop or merge without you, and the next ticket waits for your yes.

It moves on without you only on an explicit grant: an autonomous run for one job, or a night shift. Any other standing goal grants nothing.

It asks you only where a step is yours: the ones listed in RULES.md, putting something off, the next ticket. Technical choices it makes itself, on evidence, and writes down what it turned down.

It still stops and waits, one line saying why, on: the same check still failing after two fixes; a security problem or an unresolved critical finding; the automated review under 5/5 after three rounds; spend reaching your cap. After a stop it goes on only on your word.

Your goal never covers tracker moves, messages, edits outside the ticket’s files, migrations, a force push, a fourth automated review, spend over the cap, or starting the next job.

The shift ends at any stop in a job, when the whole goal is built, at the spend cap, or when a job passes 16 hours. The night shift, in full ↓

Foreman: Claude Code. Plans and checks; never writes product code.
Builder: A cheaper model. Builds; never makes design decisions.
Inspectors: Other AI models. Find problems; never fix them.
Owner: you: OKs each merge, or the whole night at once.

Install

Get the package. Needs git, Node and Python.

git clone https://github.com/kaithoughtarchitect/toppingout

Then, in Claude Code, in your repo:

Read <path to the package>/skills/f-setup/SKILL.md and follow it

/f-setup installs what’s missing, profiles your repo and asks only what it can’t find. It never overwrites or commits.

kaithoughtarchitect/toppingoutOpen source on GitHub · MIT

Why Topping Out

Site ruleDo not distract the builder. It only builds what’s drawn.

Named for the day a building's last beam goes on. Here, it's the day every job on a board is done: the project tops out, and the next one starts from it.

Build only what is drawn

Cheaper

The foreman decides, so a cheap model can build.

Inspection zone

Checked end to end

Two separate reviews and a checklist. “Done” has to be proven.

Works continue overnight

Runs the night shift

Hand it a list at night. Wake up to merged jobs.

Site diary kept at all times

Nothing forgotten

A new session picks up where the last one stopped.

Order of works

CautionInspectors on site. Do not feed.

Once per project: plan it, check it, cut it into tickets

01Shape the ideaForeman/f-sketch /f-survey
02Write the planForeman/f-blueprint
03Check the planInspectors/f-plancheck
04Cut into ticketsForeman/f-schedule

Night shift: job after job, until the list is done

Then, for every ticket: one job, one branch, one PR

05Start the shiftForemanYour wordor your /goal/f-shift
06BuildBuilderone small step at a time, test first; the foreman checks each one
07InspectInspectorsautomated checks first, then two reviews/f-inspect /pack-review /xreview /adjudicate
08Open the PRForemanYour wordor your /goal
09Review the PRForemanYour wordor your /goalGreptile reviews it, three rounds at most/f-greploop
10MergeForemanYour wordor your /goal
11CloseForemanYour wordor your /goala day report, the next job picked and researched, the handover written/f-signoff /f-board

← Next job: a fresh foreman starts here

NowEvery detail: the Order of works page →

01 Shape the idea

Your idea becomes clear decisions.

RuleNo question left open.

02 Write the plan

The whole plan, before any code.

RuleEvery decision made first.

03 Check the plan

Other AI models check the plan.

RuleIt passes before it is split.

04 Cut into tickets

The plan becomes jobs, in order.

RuleNothing written until you say go.

05 Start the shift

A fresh foreman reads the notes, then the code.

RuleWhere they disagree, the code wins.

06 Build

One small task at a time, test first.

RuleA test that breaks stops the work.

07 Inspect

Two reviews: a fresh AI session, then an AI from another company.

RuleBoth run, always.

08 Open the PR

The work goes up as a pull request.

RuleOnly on your word, or your /goal.

09 Review the PR

Greptile reviews it; findings get fixed.

RuleThree rounds at most.

10 Merge

Merged, then checked against what was reviewed.

RuleOnly on your word, or your /goal.

11 Close

Every requirement checked, notes left for the next job.

RuleNothing left for later.

30 skills, 13 agents: every one has its own page →

The night shift

NoticeSorry for the noise. We’re building your app while you sleep.

List the jobs before bed. Wake up to merged work.

22:30 · Before bedYou type one line/goal night shift: jobs 11, 12, 13

07:00 · Morning3 jobs mergedThe links, and anything only you can decide.

A failed check stops the shift, so nothing broken merges. Name the jobs, or say 3 jobs, auto-pick and it picks them. How it works →

Night shift rulesAll workers · every night

Any problem stops the whole shift, with one line saying why. A usage limit only pauses it.
Done means merged in the repo, never "done" in the chat.
Nothing outside the ticket: no messages, migrations, force pushes or spend over the cap.
Start small: two or three jobs a night.

Nothing is lost

Site recordLessons forgotten on this site000

Sessions forget. Topping Out writes down what each job learned and where it stopped, and the next session starts there.

or tap any outlined part to see what it keeps and who reads it

Lasts: the job1 / 12

J12, being built

the job file

The plan, the decisions and the work orders, kept current as the job runs.

Written by: The foreman, all through the job.
Read by: /f-signoff, to write the cards and the handover.

Lasts: one session2 / 12

The handover

foreman/handovers/

Where the job ended, what is owed, and a short quiz.

Written by: /f-signoff, every job.
Read by: The next foreman, which answers the quiz cold.

Lasts: one session3 / 12

The next opener

foreman/handovers/OPENER-JOB-<N>.txt

Six lines that start the next job.

Written by: /f-signoff, every job.
Read by: A fresh session: you paste it, or the night shift does.

Lasts: the project4 / 12

The board

foreman/projects/<slug>/BOARD.json

Every job's state, and which job comes next.

Written by: /f-board, one event at a time.
Read by: You, on board.html; each close, to pick the next job.

How a card is made5 / 12

From lesson to card

skills/f-card/ and /f-signoff step 3.2

A lesson is found, checked for a twin, shown to you, then filed.

Who: /f-card any time; /f-signoff at the close.
Never: Filed without your yes.

1MineThe job's key discoveries, its work-order reviews, its inspections and the dev report's learnings. Or one lesson, mid-job.
2Type itINSIGHT for a gotcha or principle, METHOD for a repeatable procedure, BUILD for a record of what was built. Each has its template.
3Check for a twinSearch the Logbook for the same lesson. Over 80% overlap: the evidence goes on the old card instead.
4Score itEvery section filled, the evidence, a concrete example. Confidence from evidence: one instance 75%, two or more 85%, measured 95%. Under 75 of 100, it goes back.
5Show youThe whole card as a preview. Nothing is written until you say yes.
6File itThe card file, a row in the index, its links, and the counts recounted from the files.

Lasts: the project6 / 12

The Logbook

foreman/logbook/

Every lasting lesson as a card, with its evidence.

Written by: /f-card any time; /f-signoff at the close.
Read by: /f-shift at every job start; /f-search any time.

logbook_index.md every live card: its type, summary, impact and clusterlogbook_links.md the typed links between them

Past 250 cards, /f-archive keeps the best-linked and most recent cards live, so the faded ones go first. An example, not a real Logbook.

A Logbook tool7 / 12

/f-search

skills/f-search/

Finds the cards on a topic.

When: Any time.
Note: Current cards only. For older ones: /f-archive-search.

A Logbook tool8 / 12

/f-context

skills/f-context/

A cold read of a repo, with its matching cards.

When: New to a repo, or before re-planning.
Note: /f-shift already does this for each job.

A Logbook tool9 / 12

/f-catchup

skills/f-catchup/

Writes cards for past jobs that never got any.

When: Once, or after a gap.
Note: Waits for your yes.

A Logbook tool10 / 12

/f-dream

skills/f-dream/

Merges repeated lessons and spots repeat mistakes.

When: Now and then.
Note: Each change needs your yes and can be undone.

Lasts: for good11 / 12

The foundations

AGENTS.md or CLAUDE.md, and RULES.md

Lessons that keep coming back, made firm rules.

Written by: /f-distill, with your approval.
Read by: Every session, before any work.

Lasts: for good, out of the way12 / 12

The archive

foreman/logbook/archived/

Old cards moved aside, with an index to find them.

Written by: /f-archive, by itself past 250 cards.
Read by: /f-archive-search, when a search finds nothing.

The Logbook in full: the cards, their life, the tools, the files →

But why not just…?

Not accepted“Trust me, it’s done” is not a test result.

Site officeQuery 01 of 09

Why not one agent for everything?

The agent that made a mistake would be the one judging it.

ProofSo an AI from another company checks the work cold. It once caught a race condition the foreman had passed.

Source: Foreman Playbook, "The one idea"

Site officeQuery 02 of 09

Why not just write better prompts?

A prompt asks. A check proves.

ProofEach test must fail before the code and pass after it, and every requirement needs evidence before the job closes.

Source: METHOD.md sections 7 and 10

Site officeQuery 03 of 09

Why does it need my OK?

Merging and pushing reach beyond your machine.

ProofThey wait for you. On a night shift, your /goal line is the OK, for those jobs only.

Source: RULES.md, "Acts that need the owner's exact word"

Site officeQuery 04 of 09

Isn't it slow and costly?

More steps per job. Less of your time.

ProofA cheap model on a flat subscription does the building, the checks catch problems first, and jobs run while you sleep.

Source: the Requirements page; the night shift above

Site officeQuery 05 of 09

Am I locked in?

No. It is plain text files in your own repo.

ProofStop using it, and the plans, the lessons and the board stay.

Source: SETUP.md, "What Topping Out adds to your repo"

Site officeQuery 06 of 09

What if it breaks at night?

The shift stops, and says why.

ProofA red check, a failed walkthrough or a security finding halts it.

Source: the night shift above

Site officeQuery 07 of 09

What if the builder cuts corners?

Its report is never taken on its word.

ProofEvery requirement needs a pass with evidence, or the job does not close.

Source: METHOD.md section 10, the acceptance ledger

Site officeQuery 08 of 09

Will it fit my project?

Yes. It adds files and overwrites nothing.

ProofSetup adds one foreman/ folder and a short profile of your project.

Source: SETUP.md section 1

Site officeQuery 09 of 09

Does it work on Mac or Linux?

Expected to, not yet verified.

ProofIt is tested on Windows 11. The installer and checks are Node and Python, and the work orders are Bash.

Source: SETUP.md section 9, "Tested setup"

Requirements

Site accessAuthorised plant only. Bring your own, and you maintain it.

My own setup, shared as it is. I can only support what I use.

My setup Inspected, in use

Windows 11the machine
Git Bashthe shell
PowerShellthe other shell
Claude Codethe foreman
Pithe builder's agent
Orcathe workspace
GLM 5.3the builder, by Z.ai
GPT-6.1 Solthe builder, by OpenAI
GPT-6.1 Terrathe builder, by OpenAI
Greptilethe review rounds
OpenRouterthe key
Gitthe records
GitHub and ghthe merge
Nodethe installer
Python 3the board

Tested on

Windows 11, with Claude Code as the foreman. macOS and Linux are expected to work, not yet verified.

ComingA cloud option.

Make it yours

It’s all plain text. Fork it, swap any part, and it’s your setup.

Fork it on GitHub ↗

Every tool, in detailWhat each one does here, and the builders I’ve used

/f-setup

Update later: replaces the files your repo didn't adapt and lists the ones it did; it waits while a job is open.

Prefer to copy the files by hand?

This is the installer from SETUP.md section 1, the same on Windows, macOS and Linux. Fill in the two paths, run the dry run, then the install. It copies only what is missing and writes an install receipt.

PKG="<path to the Topping Out package>"; REPO="<path to your records repo>"
node "$PKG/skills/f-setup/install.mjs" --repo "$REPO" --dry-run   # what it would copy, and what it keeps
node "$PKG/skills/f-setup/install.mjs" --repo "$REPO"             # copy what's missing, never overwrite

Then write the repo profile (templates/REPO-PROFILE.md) and the test adapter, and check the install:

python .claude/skills/f-board/test_render_board.py

Every folder it adds, and where a job's files go →

Optional add-on

Deep Agents

Only for an AI agent built on LangChain, LangGraph or Deep Agents. /f-setup asks first, and installs it only on yes. Topping Out itself needs none of it.

Needs

Python 3.11+Deep Agents requires it.

Installed for you on yes

Version 0.7.29, pinned.
Comes with Deep Agents.
Comes with LangChain. The skeleton adds its SQLite and Postgres checkpoints.

Optional

A free account for tracing and LangGraph Studio; paid hosting later. The add-on needs none of it.

Works with LangChain’s open-source tools. The logos are LangChain’s own, shown as supplied; no partnership or endorsement is implied. The docs and the package the add-on cites are fetched at install, not shipped.

Enforced, or only instructed from the README

Most of the method is instructions the agents follow; a few checks are scripts that refuse.

Gated acts (push, merge, messages) wait for your wordinstruction
What it doesn’t stop
(RULES.md), plus your coding tool's own permission prompts. The package ships no hook
An agent with push rights and pre-allowed commands can push; nothing in the package blocks it technically. SETUP.md §5 suggests a hook for migrations only, and SETUP.md §7 asks you to pre-allow git push, gh pr create and gh pr merge for an autonomous run.
What merged is what was revieweda check the foreman runs
What it doesn’t stop
The merged commit's tree must equal the reviewed and tested tree (METHOD.md §10 step 3), and skills/f-signoff/endgame.mjs verify-merge refuses a close whose merge isn't on the main branch
The tree comparison is not scripted, and verify-merge checks only that the merge commit is on main (and runs because /f-signoff calls it); an edit after the final re-run invalidates the acceptance and is caught only if the foreman re-runs, as the rules require.
Nothing new starts until a closed job's end game is donea script the skills run
What it doesn’t stop
endgame.mjs keeps a lock file; the planning skills and work order 1 run its check and stop while it exists
An agent that skips the check call isn't stopped.
The review is independenta script, when used
What it doesn’t stop
scripts/cross-review-dispatch.mjs seats the reviewer on another vendor's CLI, in a separate process, from a brief (/pack-review)
The foreman writes the brief, so it chooses what the reviewer is pointed at and told (the reviewer can also read the checkout, read-only); seats exist only for Claude and codex foremen; this is separation, not adversarial isolation.
The whole ask is doneinstruction plus a record
What it doesn’t stop
The acceptance ledger lists every requirement and check with its evidence, and /f-signoff refuses unless every row is PASS. A change to the ask is recorded in the owner's own words (METHOD.md §2)
The ledger is written and checked by agents; a wrong PASS is caught only by the reviews or by you.
Builder names stay out of the recordsa script the foreman runs
What it doesn’t stop
skills/f-signoff/names-check.mjs checks every staged record at the records push and exits non-zero on a hit
It runs only when the foreman calls it at the records push; it checks only the names in your names file, and skips allowed contexts and rendered board pages.