werkguide 0.0.1

Layered READ_FIRST templates and a merge tool for LLM-assisted development, grown from real project findings.

werkguide

Layered READ_FIRST templates and a merge tool for LLM-assisted development, grown from real project findings.

How it works

Fully autonomous agent chains produce code faster than a human can review it. Quality drifts when nobody reviews the intermediate steps. This workflow keeps a human at every gate. The model delivers each change as reviewable blocks and the human runs them and pastes the results back.

Each block contains a patch script with an integrated dry-run that validates anchors and syntax and writes nothing. The user pastes the block into a terminal and reads the dry-run verdict. Only then does the user run the apply, which chains the smoke test and the commit. The pasted-back terminal output is the model's only ground truth, so every mutation passes a human gate by construction. The workflow works with any model in any chat interface, in the browser or local.

A session, start to finish

The user opens a fresh chat and pastes the project's READ_FIRST.md together with the latest handoff note, usually joined by the roadmap and a concept doc. Then the user runs the session-start script (preflight.sh) and pastes its output. The script commits leftover work, removes stale backups and asserts the project's claimed state against the repository, so the session starts from verified ground instead of from memory.

The handoff note is called the baton. The previous session wrote it as its last act. It names the current frontier, the open decisions and the few files worth opening and it is treated as a claim. When the preflight output contradicts it, the disk wins and fixing the baton becomes the first task.

Then the work happens, one patch at a time. Every patch gets its dry-run, its apply, its smoke test and its own commit before the next one starts. While working, the model writes down what it learns. An insight, a trap, a deferred idea lands in the project's notes file mid-session through a small block the user runs like any other. Nothing worth keeping has to survive until the end of the session in anyone's memory.

The session ends with a checkout. The model appends a patch-log entry per patch, each one a greppable block naming the root cause, the fix, the anchor and the lesson. It updates the roadmap, distributes the collected notes to their homes and writes a fresh baton. The next session picks that baton up.

The documents

A project keeps its working state in a werk/ folder next to the code. READ_FIRST.md is the merged working agreement the model loads every session. The baton carries the handoff between sessions. A roadmap holds the plan of record and a concepts folder holds the design docs, the reasoning behind the architecture that a one-line rule cannot carry. NOTES.md is the model's own notebook and USER_TODO.md is the user's inbox, the place for ideas that come up between sessions. The patches folder keeps every delivered patch script, numbered and the patch log records what each one did and why.

The template system

Every READ_FIRST.md is merged from layers and each rule has exactly one home.

• layers/core.md holds the process itself. It covers the delivery format, the dry-run gates, the verdict conventions, commit discipline, the session checkout, the baton format and around 80 universal findings.
• layers/python.md, svelte.md, react.md and qt.md hold the stack-specific findings and the reconcile asserts for their stack.
• merge/ASSEMBLE.md defines which layers merge into which project and the curation guards a finding must pass.
• preflight/preflight_core.sh is the skeleton every project fills into its own preflight.sh.

A finding is one hard-won rule. It consists of a one-line imperative, the mechanism behind it and the incident it cost. A "be careful" without a mechanism gets deleted.

The feedback loop

The notes are where the system grows. A project-specific lesson stays in the project's own facts section. A universal lesson or a stack trap moves at checkout into a shared notebook that queues findings for the template layers. A review session goes through that queue, checks every finding against the curation guards and merges the accepted ones into core or into their language layer. Every project receives the new findings at its next re-merge, including the projects where the bug never occurred. A mistake paid for once is paid for everywhere.

Install and use

Requires Python 3.9 or newer and git. The same commands work on Linux, macOS and Windows.

git clone https://github.com/zPirx/werkguide.git
python werkguide/werkguide.py init ~/path/to/your/project --layers core+python
python werkguide/werkguide.py merge ~/path/to/your/project

init creates the werk/ folder with a session-start script, a notes file, a todo inbox and a first baton. merge builds werk/READ_FIRST.md from the chosen layers and stamps it with the werkguide version it was built from. The [ADAPT] slots in the merged file hold the project facts and filling them is the first session's work. A re-merge preserves the project-facts section and refreshes everything else.

status reports whether the merge is stale against werkguide, whether [ADAPT] slots remain unfilled and whether exactly one baton exists. Layer choices: any of core, python, svelte, react and qt joined with +.

Projects on this workflow

project	layers	what it is
crowd-eye	core + python + svelte	crowd counting from images
rldeck	core + python + react	RL training and experiment deck
craftwerk	core + python + qt	desktop host for the agentkern engine
agentkern	core + python	agentic-context engine
qtflex	(none - small lib)	responsive width adaptation for Qt

The projects are private and will be published soon.

Why

Many AI-assisted projects ship with unpolished results. The reason: a generated concept goes to an autonomous agent, the agent delegates to sub-agents and no human monitors or reviews the steps in between.

I built this workflow around the missing step: a human who controls every single step and keeps the model busy with questions.

Over months of daily sessions I collect what each session teaches, condense it and load it at the start of the next one. This way the model gets a detailed and custom guideline.

The transition from chat windows to autonomous agents happened fast. The craft of communicating with a model and refining one's own workflow got skipped. These templates are that craft, condensed and written down.

AI use

AI use in these projects is disclosed in AI_POLICY.md.