Metadata-Version: 2.4
Name: werkguide
Version: 0.0.1
Summary: Layered READ_FIRST templates and a merge tool for LLM-assisted development, grown from real project findings.
Author: zPirx
License: MIT
Project-URL: Homepage, https://github.com/zPirx/werkguide
Keywords: llm,workflow,templates,read-first,ai-assisted-development
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# 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](AI_POLICY.md).
