Platform · J.1 How tools get made
How it works, step by step
DesignEvery component and each connection it makes, then one idea followed from first sighting to the catalog, and the three loops that keep it current. Drawn from the platform's data, not typed in.
J.1.21 min readLast revised November 2026
Status: Design. A specification. It describes how the component is meant to work, not something you can use on this site today. What the labels mean.
This page shows the platform as a working whole: which parts exist, what each one connects to, and what happens to an idea as it moves through them. Nothing on it is typed in by hand. The diagrams are drawn when the site is built, from the same files the rest of the site reads.
Where the design contradicts itself, the page says so instead of hiding it. Each contradiction is marked as an open question, and it stays marked until the owner decides it.
The parts and how they connect#
Eighteen components, grouped by what they do, plus the things outside the platform they talk to. Each box lists every connection that component makes. Workers only ever start a connection to Muster, except where an open question says otherwise.
Public site
- Repository clearedstack.comConnShows the catalog, the guides and the state of the factory to anyone, and takes in edit proposals.
- reads Logbook
- reads Muster
- writes Muster
The record
Code path
- Repository plainforgePlainforgeHolds the primary copy of every repository, announces each change and mirrors code outward.
- notifies Keelworks
- mirrors GitHubOpen question: Plainforge mirrors the code to GitHub, and Bellbuoy has a github-mirror sub-tool as well. Which one owns the mirror?
- Repository lazaretteLazaretteKeeps built images inside the cluster, with recent versions ready for rollback.
- Repository keelworksKeelworksTests, builds and signs an image for every change.
- reads Plainforge
- pushes Lazarette
- commits Plainforge
- Repository shipkeeperShipkeeperDeploys what was built, keeps it in its intended state and reports its health with cluster details removed.
- reads Plainforge
- reads Lazarette
- writes Muster
- Repository consortConsortKeeps the GitHub copy of every repository matched to Plainforge, brings any change made on GitHub back to Plainforge as a pull request, and reports drift.
- reads Plainforge
- reads GitHub
- commits Plainforge
- notifies Shipkeeper
Pipeline workers
- Stage 01TrawlFinds candidate tools and records each one exactly once.
Takes items in: Discovered
- leases Muster
- reads Public sources
- Stage 02SextantReads a candidate's public pages and writes down what job it does, copying nothing.
Takes items in: Recorded
- leases Muster
- reads Public sources
- Stage 03AssayScreens each candidate against the knockout gates and scores it on the rubric.
Takes items in: Observed
- leases Muster
- Stage 04CountersignHolds scored candidates and edit proposals until a person decides.
Takes items in: Scored
- leases Muster
- notifies Owner
- Stage 05WaybillCredits where an idea came from and writes the specification a tool is built from.
Takes items in: Approved
- leases Muster
- Stage 06MoldloftGenerates a tool's repository from its specification and a fixed template.
Takes items in: Approved
- leases Muster
- commits PlainforgeOpen question: Moldloft commits the generated repository to Plainforge, but workers cannot reach Plainforge. Either open that path for this worker, or have a control-plane service make the commit.
- Stage 07ShakedownChecks a built tool against the five listing conditions before it can be listed.
Takes items in: Building
- leases Muster
- Stage 08ChartroomPublishes, links, merges and retires catalog entries.
Takes items in: verifiedOpen question: Chartroom takes items in a state called verified, which is not one of the fourteen. Should Shakedown's pass be a state of its own, or should Chartroom take building items that passed?, Linked, Merged, Retired
- leases Muster
- commits PlainforgeOpen question: Chartroom writes catalog entries to the hub repository in Plainforge, but workers cannot reach Plainforge. Either open that path for this worker, or have a control-plane service make the commit.
- Stage 09TidegaugeWatches official sources, live tools and linked tools for change, and reopens whatever is affected.
Takes items in: Live, Parked, Linked
- leases Muster
- reads Public sources
- Stage 10BellbuoyTurns failures, paused items and approved edits into one piece of work in the repository that owns the fix.
Takes items in: Needs a sub-tool
- leases Muster
- commits PlainforgeOpen question: Bellbuoy commits changes and opens tasks in Plainforge, but workers cannot reach Plainforge. Either open that path for this worker, or have a control-plane service make the commit.
- notifies Owner alerts
- mirrors GitHubOpen question: Plainforge mirrors the code to GitHub, and Bellbuoy has a github-mirror sub-tool as well. Which one owns the mirror?
Outside the platform
- Public sourcesOfficial regulations, public pages and requests
- GitHubThe public copy of the code
- ReaderAnyone using the site
- OwnerThe person who decides
- Owner alertsA webhook the owner chooses
One idea, step by step#
Each step names who acts, how the idea's state changes, and the other ways it can leave that step. The highlighted names are everything that step touches. After the eleven steps come the three loops that keep a published tool current.
- Step 1A candidate turns up
Involved: Muster, Trawl, Public sources.
- Discovered → Recorded when it is given an identifier and is not a duplicate
Trawl reads public sources: SAM.gov notices, GitHub issues, scheduled sweeps of public sites and the site's own form. It cleans the address, checks for a duplicate and gives the item an identifier such as PA-0001.
Trawl connects to
- leases Muster: Takes work and reports each result
- reads Public sources: SAM.gov notices, GitHub issues, site sweeps and the site form
Other ways out
- Discovered → Rejected when the address is dead or a duplicate
- Recorded → Needs a sub-tool when the source is in a form intake has no rule for
- Step 2Observe what it does
Involved: Muster, Sextant, Public sources.
- Recorded → Observed when its public pages have been read
Sextant reads the candidate's public pages and records facts only: the job, inputs and outputs, login, tracking, license, price model and the rule it cites. Each fact is marked Seen, Stated or Unknown. The page itself goes no further.
Sextant connects to
- leases Muster: Takes work and reports each result
- reads Public sources: A candidate's public pages
Other ways out
- Observed → Needs a sub-tool when a worker has no rule for what it found
- Step 3Screen and score
Involved: Muster, Assay.
- Observed → Scored when it passes all five gates
Assay applies the five knockout gates, then the 100-point rubric, then the tie-breakers. It returns a pass or fail on each gate, a score and a recommendation. It recommends; it does not decide.
Assay connects to
- leases Muster: Takes work and reports each result
Other ways out
- Observed → Screened out when it fails any knockout gate
- Step 4A person decides
Involved: Muster, Countersign, Owner.
- Scored → Approved when the owner chooses to build
Countersign holds scored items until the owner chooses: build it, link to a tool that already does the job, merge it into another tool, park it until a blocker clears, or reject it. Overriding the recommendation needs a written reason.
Countersign connects to
- leases Muster: Takes work and reports each result
- notifies Owner: Scored candidates and proposals waiting for a decision
Other ways out
- Scored → Linked when a free, private tool already does the job
- Scored → Merged when it belongs inside another tool
- Scored → Parked when it is worth doing but blocked
- Scored → Rejected when it falls below the threshold
- Step 5Credit and specify
Involved: Muster, Waybill.
Waybill writes a credit note saying where the idea came from, then a specification built only from the official rule and its worked examples. This is the clean-room wall: no material from an existing product crosses it.
Waybill connects to
- leases Muster: Takes work and reports each result
Other ways out
- Approved → Needs a sub-tool when there is no profile for that kind of tool
- Step 6Generate the tool
Involved: Muster, Plainforge, Moldloft.
- Approved → Building when its repository is generated
Moldloft sees only the specification and one of four fixed templates: calculator, checklist, validator or decision tree. It generates the tool's own repository.
Moldloft connects to
- leases Muster: Takes work and reports each result
- commits Plainforge: The generated repositoryOpen question: Moldloft commits the generated repository to Plainforge, but workers cannot reach Plainforge. Either open that path for this worker, or have a control-plane service make the commit.
- Step 7Every push becomes a running image
Involved: Muster, Plainforge, Lazarette, Keelworks, Shipkeeper, GitHub.
This runs for every push to any repository, not only tools. Plainforge announces the push. Keelworks tests, builds and signs an image and writes its digest back. Lazarette keeps the image, with recent versions ready for rollback. Shipkeeper deploys it, keeps it in its intended state and reports its health.
Plainforge connects to
- notifies Keelworks: Announces each push
- mirrors GitHub: Outbound mirror of the codeOpen question: Plainforge mirrors the code to GitHub, and Bellbuoy has a github-mirror sub-tool as well. Which one owns the mirror?
Lazarette connects to
Keelworks connects to
- reads Plainforge: The code of each push
- pushes Lazarette: Signed images
- commits Plainforge: The new image digest
Shipkeeper connects to
- reads Plainforge: Manifests
- reads Lazarette: Image digests
- writes Muster: Health reports with cluster details removed
- Step 8Check before listing
Involved: Muster, Shakedown.
Shakedown checks the built tool against the five listing conditions before it can be listed.
Shakedown connects to
- leases Muster: Takes work and reports each result
Other ways out
- Building → Parked when the rule turns out to be unclear
- Step 9List it
Involved: Conn, Muster, Logbook, Plainforge, Chartroom.
- Building → Live when it passes all five listing conditions
Chartroom writes the catalog entry to the hub repository, and the site is rebuilt. Conn shows the catalog from Logbook's public views. Readers see three labels: approved shows as Planned, building as In development and live as Live.
Conn connects to
- reads Logbook: Public views only, with a read-only role
- reads Muster: The live update stream
- writes Muster: Edit proposals from readers
Chartroom connects to
- leases Muster: Takes work and reports each result
- commits Plainforge: Catalog entries in the hub repositoryOpen question: Chartroom writes catalog entries to the hub repository in Plainforge, but workers cannot reach Plainforge. Either open that path for this worker, or have a control-plane service make the commit.
- Step 10Watch for change
Involved: Muster, Tidegauge, Public sources.
- Live → Building when the rule it rests on changes
- Live → Retired when the rule is repealed or replaced
Tidegauge compares official sources, linked tools and live tools on a schedule. When a cited clause changes, the affected tool goes back to building in the urgent lane. A repealed rule retires it.
Tidegauge connects to
- leases Muster: Takes work and reports each result
- reads Public sources: The Federal Register, the eCFR, NIST, and linked and live tools
Other ways out
- Parked → Observed when the blocker clears
- Linked → Observed when that tool breaks or starts tracking users
- Step 11Route problems to their owner
Involved: Muster, Plainforge, Bellbuoy, GitHub, Owner alerts.
Bellbuoy turns a failure, a paused item or an approved edit into one piece of work in the repository that owns the fix, and alerts the owner.
Bellbuoy connects to
- leases Muster: Takes work and reports each result
- commits Plainforge: Changes and tasks in the repository that owns the fixOpen question: Bellbuoy commits changes and opens tasks in Plainforge, but workers cannot reach Plainforge. Either open that path for this worker, or have a control-plane service make the commit.
- notifies Owner alerts: Owner alerts
- mirrors GitHub: Its github-mirror sub-toolOpen question: Plainforge mirrors the code to GitHub, and Bellbuoy has a github-mirror sub-tool as well. Which one owns the mirror?
- ↺ LoopA case no rule covers
Involved: Muster, Logbook, Plainforge, Sextant, Bellbuoy, Public sources, GitHub, Owner alerts.
- Observed → Needs a sub-tool when a worker has no rule for what it found
- Needs a sub-tool → Observed when the rule ships and the item is run again
A worker never guesses. It pauses the item and says why, and Bellbuoy opens a task to write the missing rule. When the rule is pushed it ships like any other change, and the paused items run again in the urgent lane.
Muster connects to
- writes Logbook: Working records; the only service that does
Sextant connects to
- leases Muster: Takes work and reports each result
- reads Public sources: A candidate's public pages
Bellbuoy connects to
- leases Muster: Takes work and reports each result
- commits Plainforge: Changes and tasks in the repository that owns the fixOpen question: Bellbuoy commits changes and opens tasks in Plainforge, but workers cannot reach Plainforge. Either open that path for this worker, or have a control-plane service make the commit.
- notifies Owner alerts: Owner alerts
- mirrors GitHub: Its github-mirror sub-toolOpen question: Plainforge mirrors the code to GitHub, and Bellbuoy has a github-mirror sub-tool as well. Which one owns the mirror?
- ↺ LoopA reader proposes an edit
Involved: Conn, Muster, Logbook, Plainforge, Countersign, Bellbuoy, GitHub, Reader, Owner, Owner alerts.
A reader proposes a change on the site, with no account. Muster records it, Countersign holds it until the owner approves, and Bellbuoy commits it in the repository that owns that part. Nothing is applied before the owner approves.
Conn connects to
- reads Logbook: Public views only, with a read-only role
- reads Muster: The live update stream
- writes Muster: Edit proposals from readers
Countersign connects to
- leases Muster: Takes work and reports each result
- notifies Owner: Scored candidates and proposals waiting for a decision
Bellbuoy connects to
- leases Muster: Takes work and reports each result
- commits Plainforge: Changes and tasks in the repository that owns the fixOpen question: Bellbuoy commits changes and opens tasks in Plainforge, but workers cannot reach Plainforge. Either open that path for this worker, or have a control-plane service make the commit.
- notifies Owner alerts: Owner alerts
- mirrors GitHub: Its github-mirror sub-toolOpen question: Plainforge mirrors the code to GitHub, and Bellbuoy has a github-mirror sub-tool as well. Which one owns the mirror?
- ↺ LoopKeeping GitHub in step
Involved: Plainforge, Shipkeeper, Consort, GitHub.
Plainforge holds the primary copy and mirrors it to GitHub. Consort checks that the mirror pushed each new main commit, and brings any change made on GitHub back to Plainforge as a pull request. It never writes to a main branch.
Consort connects to
- reads Plainforge: Every repository
- reads GitHub: Every repository
- commits Plainforge: Pull requests for commits found only on GitHub
- notifies Shipkeeper: A report of each sync run
Where this comes from#
| What | Written in |
|---|---|
| Components, what each may reach and every connection | src/data/registry.json, also published as /platform/registry.json |
| The fourteen states and every move between them | src/data/lifecycle.json |
| The order of the steps on this page | src/data/walkthrough.json |
| Contradictions waiting on a decision | src/data/open-questions.json |
A check runs before every build. It fails the build when these files disagree with each other: a connection the network does not allow, a state that does not exist, a dependency with no connection behind it, or two components claiming the same job. The only way past a contradiction is to fix the data or to record it as an open question for the owner, so it cannot drift silently.
Found a mistake, or something that has gone out of date? Open an issue or write to [email protected]. This page is a text file you can read and correct: Source of this page.