In practice#

Read this the day you try it. Nothing is to be prepared beforehand. The rule is simple: a prerequisite the agent can resolve is not a prerequisite. The runtime the checks need is verified by the agent, which offers to install it. It is required of nobody in advance. The rest — installing git, understanding a command, choosing between two ways of doing something — is already part of ordinary agent use.

Installing it#

Five steps. Once.

1. An empty folder. This will be the root. You put it wherever you like, its name is read by nobody, and nothing is ever looked for in it.

2. The archive unpacked inside it. That is the latest published version: the method, plus your instance — profile, transverse conventions, notebooks — arriving empty. Here is your disk at that point:

projects/                   the root — you choose it, nothing is read from it
└── _workshop/              the method as received + your instance. Private in full

One thing only is not free: the name of that folder does not matter, its position does. Directly inside the root, never within anything else: everything resolves from there. The archive arrives with no .git, so with no origin repository. Nothing you write in your instance can travel back to ours, including by mistake.

3. Your agent’s access to that root. This is the only hard prerequisite of the method: it must be able to read and write the files of a folder you point it at. A chat window you paste text into does not do.

How that folder is declared depends on the tool — an editor workspace, a launch directory, a list of allowed paths — and every tool has one. Here it is Claude Code inside VS Code; others do just as well. The method asks only that the folders be declared, and that the path of the entry point be named by hand at the opening of every session.

4. Your first conversation. Two lines, stating the real state of the disk:

Hello — I have just unpacked Workshop here, there is nothing else yet.
Entry point: projects/_workshop/method/organization.md

The agent reads the map, sees that no profile exists, and offers to build one: ten minutes or so of questions, then the two files every later session reads. It is an offer, not a compulsory step.

5. Your first workshop. “Create the workshop Ledger, with the repositories ledger.api and ledger.web.” A product spread across several repositories, or a single library: either way, a workshop. Its framing lives outside every code repository. It therefore cannot ride along in a code commit.

projects/                   the root
├── _workshop/              the method as received + your instance
├── Ledger/                 A WORKSHOP
│   ├── ledger.api/           a code repository
│   ├── ledger.web/           another repository, same workshop, same framing
│   └── _workspace/           THE FRAMING, outside every code repository
└── TinyParse/              ANOTHER WORKSHOP — a single library is one too

The installer lays that skeleton down and stops there. It migrates nothing, does not open the workshop and does not work in it. What it creates matches every workshop you create afterwards, including the one six months from now.

After that, one sentence is enough to open each session. It is the only gesture that repeats. The method adds no account, no service, no configuration to maintain: files, and two scripts to run — the installer and the checks.

Updating means copying a newer method/ over yours; your instance and your workshops do not move. Since 0.4.0, workshop-lint.py --check-updates can also say whether a newer version exists. It is a warning only, opt-in, and the only check that reads a remote. Watching Releases only on the public repository is still another way to be told, without asking anything of your copy.

The manual — what you have to say#

If you read one section only, read this one. Everything the method expects of you is here. Two sentences recur in the normal life of a session; five others appear only in specific cases. None of them is a command or a keyword. They are simply the facts no document can know: which workshop, that a session was cut, that one is being closed. Everything else fires because a condition was read.

Hello — we are working on Ledger today.
Entry point: projects/_workshop/method/organization.md

Let's close the session.

The inventory has authority in the repository readme, in English.

The corpus builds itself as you go#

What precedes repeats every session. What follows builds over time: the corpus that carries what holds everywhere is your instance. It arrives empty, and fills one file at a time. Nothing is to be written in advance: writing a rule before it was needed means guessing what will serve.

A file is born from a remark. You correct the agent on a point that has nothing to do with the day’s task: a way of naming things, a format, a rule you apply everywhere without thinking. The fact that the remark overflows the current subject is exactly what makes it transverse. The agent picks it up and offers to write it down.

Writing it is two gestures, and the agent does both. First the text, and above all the condition that fires it in the file’s header — “read only if…”. Then, in the same movement, the index line that declares it. Without that line the file exists but is read by nobody: that is exactly the case of the conventions that never arrive, described on the front page.

Upkeep follows the same logic. A corpus that grows gets re-cut: when the condition in a file’s header becomes narrower than its contents, whoever reads it pays for pages that do not concern them, and the file splits. Those reorganisations are mechanical, the agent carries them out, and the checks verify that no citation was left behind.

What is not mechanical falls to you: deciding that a remark becomes a rule. Not everything said in a session is meant to end up in a file, and a passing preference written up as a convention soon becomes a useless constraint.

The rest — the start, the reflexes imposed on the agent, the closing protocol — is described in detail, to be read while working.