English · Français
Governance kit for running parallel AI coding agents.
simon-pacifae-dupont.github.io/Guildwork: the same thing, on one page. (Version française of the page and of this README; the seventeen documents are in English.)
The rules on one page. Eleven working rules to paste as they are into an AI agent's instructions: RULES.md (en français). The rest of this repository says where they come from.
Not a developer? The same discipline (a contract before, a witness during, a closeout after, and a launcher that refuses to start what isn’t in order) holds a law firm, an agency or a support desk just as well. That door is on the same page.
Guildwork is the governance one person built, incident by incident, and runs every day to hold a multi-agent AI engineering team on a real product, whatever its number of seats, at twenty-five merges a day: with every mission a contract, every merge behind a named gate, every session leaving a durable record, and the human out of the message path. This repository is that system, extracted: the contracts, the forms, the vocabulary, the specification of the three tools that hold it together, and the incidents that paid for every rule.
It is meant to be read. The three tools are specified, not shipped. One page is: the board reader below, which you can open right now.
The board as it runs, on the fictional Lantern example. Eight counters, one per state, green included, each carrying how it was read; then the one decision that is the Product Owner's and nobody else's, taken on the page where it is read, with the comment it will publish shown word for word first. It never merges. Open the demonstration. Frozen, and it says so on its face.
Several AI coding agents, from different vendors and different harnesses, working on one repository at once produce four kinds of damage that no prompt cures: two agents writing the same file, with the human as the merge tool; an agent running under a model, an effort or a prompt nobody declared, with nothing recording the substitution; what an agent learned dying with its context window, so the next session re-derives it or works from a stale summary with confidence; and the human ending up carrying instructions between agents by hand, which is the one job the agents were supposed to remove.
GitHub is the source of truth, with five surfaces that each have exactly one job: the issue is the contract, the board is the queue, the worktree is the workspace, the pull request is the delivery, the journal is the session memory. A mission stated anywhere else does not exist.
A launcher reads the contract by number, validates it against the governance at the commit the mission will run on, checks seven conditions, and refuses, naming which condition fired, or creates the workspace, performs the session entry, and starts the declared harness under the declared model and effort with a first instruction generated from the issue. A session cycle opens every session by reading what the last one left and closes it with exactly one exit command whose exit code is decided by durability alone. A closeout tool refuses to remove any worktree whose material is not provably preserved, and closes contracts from their merged deliveries with four refusals of its own.
Under the tools, four principles: measured, not assumed; fail closed, and say which condition; a refusal does not prevent the mission, it moves it outside the gate; durable means reachable from a pushed ref.
Read it as a path: ten checks before a session starts (seven stable contract conditions, three guards hardened in operation), a witness and a human gate before anything lands, three exit codes decided by durability alone, a register that sends every incident back into the next contract, and a watcher drawn in two steps: what it sees, and the receive–deliver–wake route, live since 18 September 2026, that launches a mission from an armed contract and wakes the architect when the mission returns. Interactive version. Hover a block to isolate its path.
The board, read for what it owes each seat. Six counters, then three
questions in this order: what is waiting on the Product Owner's decision and
on nobody else's, what the architect merges under delegation without them,
and what fits no rule: a pull request with no Mission: line, a delivery
naming a closed mission, a lot with no workstream. Those last are counted on
the face of the board rather than filed by guesswork, and they are meant to
read zero. Every figure carries how it was obtained, because a count read in
full and a count that stopped early are different claims.
It holds no token and copies nothing: it reads the repository through the viewer's own GitHub connector. It never merges: the page is one share away from anyone, and a merge control on a shareable page is a gate anyone can pass. And it publishes what it cannot see: a session on another machine, a process that discloses no command line, an agent started by hand.
What the kit publishes today is the board reader, under
templates/board/. The host reading and the decision path shown in the
demonstration are newer, and reach the kit when they have stopped moving, which is the rule everything else here follows.
Demonstration ·
the published reader ·
en français.
docs/ seventeen documents, numbered in reading order
templates/ the files to drop into a repository: issue form, pull request template,
label recipe, role profiles, journal format, regenerable-paths manifest,
findings register, weekly review, changelog convention
examples/ one fictional mission followed end to end: issue, launcher transcript,
generated instruction, transmission report, pull request, journal entry,
closeout transcript, register
demo/ the pages the site opens: the board as it runs (demo/board/, with the
published reader under demo/board/reader/), the no-code desk
(demo/desk/) and the operating canvas (demo/canvas/); French
versions under fr/demo/
no-code/ the prompt that installs the three no-code rules (written request, sign-off,
register) in Claude, with its guardrails; French version alongside
integrations/ the guildwork extension for Spec Kit (integrations/spec-kit/): a person's
verdict, written down, before any code is
brand/ the mark, the lockups, the design system, and every image the README
and the site show, each rendered from a page in demo/, never retouched
| Document | What it settles |
|---|---|
| 00 · The operating model | the five surfaces, the seats, the lifecycle, the principles |
| 01 · The mission contract | the issue form field by field, conservative ordering, what a comment may amend |
| 02 · The delivery contract | the pull request template, the Mission: line and its three states, who disposes of what a run created |
| 03 · The label taxonomy | seventeen labels and no more; routing labels are events; workstream labels are descriptive |
| 04 · Capabilities and routing | three atoms, an enumeration that is not a ladder, unknown routes as cannot |
| 05 · The launcher | the seven conditions, and why the reference implementation refuses on ten: the governance pin, --resume, --list, the generated instruction |
| 06 · Session entry and exit | guild-hi, guild-bye, exit codes 0/2/3, the three-state declaration |
| 07 · The closeout tool | five conditions, the regenerable-paths manifest, what closes a mission |
| 08 · Continuity | source precedence, the seven failure modes, what a handover owes its successor |
| 09 · The findings register | one issue, two exits, reviewed at every sweep |
| 10 · Effort and execution parameters | the exact mapping, per-seat levels, state what ran |
| 11 · Changelog fragments | one file per mission, assembled at release |
| 12 · Incidents | every failure that paid for a rule, and the rule; the register grows |
| 13 · By the numbers | the real project's figures, domain removed |
| 14 · The adoption path | what to do in what order, and what this pack does not contain |
| 15 · A Windows workstation | two shells, three encodings, no administrator rights, the launched session's PATH, agent CLIs and browsers that do not start |
| 16 · The weekly review | a pass across the week's sessions proposes rules, skills, merges and retirements; another model reads, the human signs |
Read 00 for the shape, 12 for why it is shaped that way, and the
launcher transcript in examples/lantern/launcher-dry-run.md for what it
feels like to run. If those three earn a fourth, read 05.
git clone https://github.com/Simon-Pacifae-Dupont/Guildwork
mkdir -p your-repo/.github && cp -r Guildwork/templates/github/. your-repo/.github/
cd your-repo && sh ../Guildwork/templates/labels.sh
Three commands: the issue form and the pull request template land in
.github/ on your default branch, and the seventeen labels, the watcher:*
routes and the chantier:* workstreams are created once, by a human (on
Windows, run the gh label lines of labels.sh from PowerShell). Then open
a new issue with the AI mission form. The first contract exists. The
launcher that will read it is yours to write from 05; templates/README.md
says which value is Lantern's and what you still owe.
Guildwork is a method, not one more tool to direct agents. A terminal, a kanban, a dashboard that runs a whole team, a workflow engine: whichever one drives the agents, three things still have to be written down. What is asked, in writing, before the work starts. Who settles it, by name, before anything ships. Where each verdict is kept, so the next mistake becomes a rule instead of a repeat. Those three are what this repository specifies. The tool that runs the agents can hold them; it does not decide them.
Spec Kit decides what to build: a
specification, a plan, tasks. Guildwork decides who may deliver it, and what
the human settles. The two combine through the guildwork extension in
integrations/spec-kit/: between /speckit.tasks
and /speckit.implement, it writes the request, waits for the verdict of the
person who decides, and keeps every verdict in a register. Implementation
starts only on approved, and only while the plan stays the one that was
approved.
specify extension add guildwork --from https://github.com/Simon-Pacifae-Dupont/Guildwork/releases/download/guildwork-v0.1.0/guildwork.zip
A Windows desktop application in Python with a 13 155-test suite, measured on
8 September 2026; one human Product Owner, a Chief Architect seat held in turn by ChatGPT Work,
Claude Cowork and, since 18 September 2026, Claude Code on the developer
machine, and executing seats on Claude Code, Grok Build and Codex CLI.
In the thirteen days to 7 September 2026, 344 contracts were opened and
320 pull requests merged, twenty-five a day; 548 sessions closed with a
journal entry in the 36 days since the journal existed. docs/13-by-the-numbers.md has the full table,
and both readings of it.
Every example here is rewritten on a fictional project, Lantern, a workshop sensor dashboard with a bridge to a bench controller, so that the mechanics can be shown without describing the real product. Nothing about Lantern is load-bearing.
The kit is the part that has stopped moving. Three things are still moving
on the project it comes from, and each will reach the kit the way everything here did, once a real incident has paid for it. The board becomes the
control: not a report on the agents, but the page where the one decision
that is the Product Owner's is taken and recorded by the same click. The
watcher reads authorised GitHub events and fresh host readings every two
minutes, deduplicates them and publishes the latest reading without starting
a model; since 18 September 2026 it also receives the armed mission, delivers
the canonical contract and wakes the named existing seat, carrying a route and
never an authority. And the same seven states (running, holding the screen, next, for you, landed, broken, expired) sit on every board, whatever it follows;
the names adapt to a project, the positions and the hues do not
(brand/design-system.md).
Not a framework and not a runtime. The three tools are specified
in 05, 06 and 07 precisely enough to audit or re-implement, and they
are not shipped: installing this on a repository, adapting the vocabulary to
a team's own seats and workstreams, measuring the capability table on the
team's machines, writing the tools against the team's harnesses, and
running the first two weeks of missions alongside the team is the work, and it is the work the author does.
Simon Dupont · GitHub · LinkedIn · [email protected]. If you run, or intend to run, more than one AI coding agent on a codebase that matters, write.
MIT. See LICENSE. The Lantern project, its repository, its people and
its numbers are fictional; the figures in docs/13-by-the-numbers.md are
real; they were measured on 9 September 2026, over complete days only.