Workshop#

A tracking method for working with an AI agent. Its subject is simple: what an agent must read to be useful, and what a session must leave behind so the next one starts with the right context.

Its vocabulary comes from software development — repository, commit — but the method talks only about files and reading order.

Six situations#

They look different. In practice, they are the same problem.

From one project to the next, you keep the same habits. A way of naming things, a date format, a writing rule. Nothing is written down, because it feels obvious. The agent asks again, or picks something else, and the same correction comes back.

Some rules hold for one project only. One runs on PostgreSQL, another on a local database. Types differ, migrations differ, and what was decided on one side has no reason to hold on the other. Yet it shows up there all the same, because the rule’s reach was not clear.

You stop for a fortnight. Coming back, the files are there. The reasons are not. What was already tried and dropped leaves no trace, and that is exactly what comes back.

You revisit a decision made three weeks ago. Both decisions stand up, but they do not hold together, and nothing brings them face to face. You had the whole picture; the agent did not.

You wrote your conventions down, but the agent does not read them. The file exists, it is current, it is good — but the agent never read it, and nothing told you so.

The tracking ought to be up to date, but it keeps being pushed back. The session ran long, the work is done, and the update waits until tomorrow. Tomorrow does not do it either; after a few postponements the tracking says something other than the disk, and people stop reading it.

This is not a discipline problem. It is a problem of written structure: no clear perimeter, no fixed place, no guarantee of being read, no upkeep mechanism.

Where Workshop sits#

What you do with an agent does not change: you ask, it answers, it writes, it explains. Workshop is not the agent, and it replaces none. Yours stays the one you chose. The method asks only that it can read and write the files of a folder you point it at. And if the word agent itself is still vague, how one works is described separately.

Nor does it replace your instructions file — AGENTS.md, or whatever your tool calls it. That file reread at the start is the first level. Workshop takes over when one document is no longer enough. As long as everything fits in one file, that works. Then the reading cost rises, and contradictions start to appear. The method answers by splitting, by saying when to read what, and by giving an upkeep protocol. The result is useful: the agent can see that a decision made today contradicts an older one, because it read both in the same session.

An agent is a model and its harness — general knowledge, and the program that gives it its access. Three layers stack up, each bringing what the one before lacks, and Workshop is the last:

The first two rows are the agent. Workshop is no part of it. It provides documents to read; it adds no capability. Choosing the agent is yours, and installing it states the one thing the method asks of it.

Four gaps, four mechanisms#

It all starts from one simple fact: what is not written does not exist for the agent. Your memory cannot serve as the source: it is not reachable from where the work happens. Writing is therefore necessary. But it is not enough. The four gaps below say why, and each has its mechanism.

A perimeter. Everything you write has a reach, and its location declares it. What holds across all your work — a way of naming things, technical conventions, how an agent should address you — goes in a transverse corpus. The rest belongs to a workshop, that is, a unit of work with its own framing. A session opened on a workshop reads that framing and no other. Nothing passes from one workshop to another without an explicit note.

An assigned place. What exists and works, what is open, what is volatile, what is finished: four states, four documents, and an item lives in exactly one of them. The same fact therefore does not end up in several copies that drift apart.

A guarantee of being read. One file only is read unconditionally: the map. It says what exists and in what case to read the rest — “only if you are writing SQL”, “only before closing a session”. The decision is therefore taken before a file is opened, because an opened file already costs context; the reading rules say how the map and the files answer each other. The corpus can therefore grow without weighing on every start.

Someone to carry it. The closing rules — what to record, in which file, in what order — are specific enough to run without improvisation. The agent writes, files, checks and records at the end of the work, without a whole session being spent on it. The framing is therefore maintained along the way instead of depending on an end-of-day effort. Review and decisions stay yours, and the exact split is detailed separately.

Workshop fits in that loop: locations, a map, a protocol — files your agent reads and maintains, not one more tool.

What comes on top#

Two useful effects come on top, beyond the start of a session.

What was expensive to learn is less easily lost. A guard-rail — the reason a given thing must no longer be done a given way — does not vanish with the work that produced it: it leaves the list of what is open and joins what has authority. A closed subject also keeps the account of what was tried, then dropped, and why.

Writing also helps clarify what is not yet settled. A subject whose reasoning does not fit on a line gets its own document, and it can get one before anything is decided: every long-form document carries its status, from an idea under examination to a settled decision. Putting a still-vague idea in front of an agent that has read your documents tests it: what does not hold shows, what is missing gets named, and what remains to be settled is marked as such.

What it asks of you#

The trade-offs are worth reading before adopting the method.

• Reading time at every start. It is measured and the checks report it, which keeps it from drifting. It is never zero.
• Writing. The agent does a lot of it; you review and arbitrate.
• A git repository, strongly advised. The folder holding these documents is created as a repository and the installer takes care of that: you do not need to know how to use it to benefit from it. What it brings is twofold — the history carries the factual record, which is what lets the handover file stay short, and the checks warn you for as long as nothing is saved off this machine.

The boundaries#

Two trade-offs, once it is in place#

These appear in use. They do not get fixed afterwards; they get chosen.

• Rules, not mechanisms. A rule read at the start of a session and due three hours later loses against the concrete case. Where the cost of missing one is real, a mechanism is needed — a check that fails — and it is worth knowing which of the two holds you.
• Two repositories instead of one. The framing lives outside the code repositories, which protects it from publication and denies it the same gesture as the code.

What the method does not decide#

The method declares slots; you fill them.

Your identity, how an agent should address you, your technical conventions, the layout of your repositories, your tool: none of that is imposed by the method.

The boundary is simple: that there is a corpus of transverse conventions, read on trigger before writing that kind of code is the method’s. What that corpus says is yours.

Your instance therefore has a precise place: the method decides when its files are read; their contents are yours.

Where next#

• How an agent works — what it reads, keeps and forgets. Read it if that is not already familiar.
• In practice — installing it, the manual, building the corpus. Read it the day you try it.
• In detail — the documents, the reading rules, a session, the checks. Read while working, not before.

Further reading#

The need Workshop answers is studied elsewhere. The ecosystem often cuts it into two questions: what survives from one session to the next — agent memory — and what is reloaded into the next session — context engineering. Workshop ties the two together: the four documents carry the first part, the map and its reading conditions carry the second, and the closing protocol keeps them together. Other answers exist — Cline’s Memory Bank, the AGENTS.md convention, spec-driven development. Here, Workshop rests on three choices: reach by workshop, conditional reading, and upkeep handed to the agent.

The method is published under the MIT license: github.com/SharpPyxis/SharpPyxis.Workshop. It redistributes no third-party component; the lint and the installer use the Python standard library alone.

method/organization.md is the only file to read in full and in order; every other one is reached from it when its trigger applies. Reading them all up front would spend exactly the budget the method is there to protect.

sample/ is a worked example: the framing of an invented workshop — atlas, todo, handoff and the story of a closed piece of work — naming no product and no person.

Status: under construction, already in use. The repositories it came from already run on it: several workshops, each with its own framing, reading organization.md at the start of every session from a copy laid out exactly as described above.