W1MER — Only one Writer, Many Explorers Read
An orchestration paradigm for long-running autonomous agent teams working on
a shared codebase, built for compiled languages (Rust, C++, ...) where
the compiler is a shared, exclusive bottleneck.
Two hard constraints drive everything:
- One writer at a time. A single implementer owns compilation and commits
(compile exclusivity). No two agents build or write code concurrently.
- Many readers in parallel. Explorers and reviewers are read-only and run
in parallel batches — investigation and review never wait for the compiler.
When to use
- Running multiple agents on a compiled project.
- You want autonomous long-running development (YOLO mode) without agents
fighting over the compiler.
- You need cheap, token-efficient coordination documents.
Roles
| Role | Duty | Reads | Writes |
|---|
| Reviewer | Re-reviews the task completed last batch, based on git-committed code (never working-tree half-done work) | code, git history | review docs |
| Implementer | Completes the current task; compiles & commits | code, plans | code, commits |
| Explorer | Investigates the next task (read-only, writes a plan) | code, docs | plan docs |
| Fixer | Fixes issues from review / finishes half-done work (sub-batch only) | code, review docs | code, commits |
Scheduling loop
Main batch (normal operation) — three agents in parallel, each at a
different pipeline stage:
Reviewer re-reviews last batch's committed task (read-only)
Implementer completes the current task (only writer)
Explorer investigates the next task (read-only)
Sub batch (on problems) — a single Fixer replaces the implementer:
- Reviewer found issues → Fixer fixes them, updates the review doc.
- Implementer interrupted mid-way → Fixer finishes the half-done work.
- Return to main batch; the next Reviewer reviews the Fixer's committed fixes.
- Sub batches can nest when a fix introduces a new problem.
Interrupt recovery — an agent that exits abnormally / returns empty is an
unfinished stage:
- Explorer / Reviewer → relaunch.
- Implementer, working tree clean ( shows no half-done work) →
relaunch the Implementer to redo the task.
- Implementer, working tree dirty / Fixer → dispatch a Fixer to finish the
half-done work (a repair job stays a Fixer's job).
Batch lifecycle — batch boundaries are recorded in
by
the CLI, not by the orchestrator's memory (this is what keeps the protocol
intact when the orchestrator is compacted):
- The orchestrator runs before launching the batch
and after the batch's commits.
- Every sub-agent runs +
w1mer role-join <task> <role>
on startup (idempotent — does on the orchestrator's behalf if
it was compacted).
- gates completeness: it refuses to leave a task whose expected
roles did not join — a dropped implementer is exposed at the next boundary.
- reads the committed diff / file content at an endpoint
from git objects, so readers never see the implementer's in-flight edits.
- Batch boundary ritual: → re-prioritize where judgment
is needed (
set task <id> --section <s>
) → pick the row from
; skipped open tasks are recorded with —
every skip is a promotion step, so nothing defers forever.
Full protocol in
(Batch lifecycle).
Task IDs
Tasks use
unbounded rolling hierarchical IDs:
,
,
, ...
Any node can branch deeper on demand (e.g. a reviewer finding follow-up
problems appends
,
) without touching parent IDs — keeping
cross-references stable. Ordering is pre-order traversal (parent first,
children right behind).
Document archive
Planning documents use a
single-index + many-detail-files pattern,
managed by a lightweight CLI (
). Agents operate through the CLI, never
by hand-editing indexes:
sh
w1mer init # scaffold the planning directory
w1mer new <type> [--parent <id>] [--title "..."] # create an entry
w1mer set <type> <id> --state <state> # update state
w1mer batch-start <task> # record batch boundary (STATE.json)
w1mer show <task> # committed diff / file at an endpoint
w1mer list [--type <type>] [--all|--todo/--done/--issue/--reviewed]
# task default: todo+issue
w1mer defer <task> # a task was skipped (promotion step)
w1mer re-rank # re-sort sections by (defer desc, id asc)
w1mer build # regenerate all INDEX files
w1mer sync [--apply] # compact deltas into per-module codebase docs
The type registry lives in
(directory, file-naming pattern,
state machine). An optional
block pre-sets subcommand flags
(command line always wins). States live in YAML frontmatter of content files —
content is the source of truth; INDEX files are build artifacts (single-direction
sync).
Layered codebase docs
Codebase docs split into two layers for provider context-cache friendliness:
- Stable layer (): overview docs
STACK → STRUCTURE → CONVENTIONS
(fixed read order — a stable prompt prefix that hits caches)
- one doc per module (), read on demand for the module
touched.
- Dynamic layer (recent changes, field details): isolated, never inserted
into the stable prefix; read on demand via the CLI.
Writes are throttled: the Reviewer records a short architecture-impact note
in its review doc; a periodic compact merges deltas into the target
module doc and clears the changelog.
Map codebase
Initialize or refresh
with a
map-reduce flow: the
orchestrator does the cheap global scan (overview docs + module registry),
then spawns
one read-only mapper per module (parallel) — each reads only
its module, writes
, and returns a short contract
report; the orchestrator assembles the cross-module flow in
from the reports. No mapper ever reads the whole codebase.
Run after
and after major refactors (re-map affected modules
only). Full spec in
references/map-codebase.md
.
Details
Full operating specs live in
— read them before your first
orchestration, then as needed:
- — role capabilities, validation, commit discipline.
- — batch lifecycle, interrupt recovery, context.
- — CLI reference, type registry, ID rules.
- — layered docs, compact flow, cache strategy.
references/map-codebase.md
— map-reduce per-module mapping.
Host-specific agent definitions live in
(opencode, claude-code,
codex), shipped inside the skill. Install the skill (e.g.
npx skills add <owner>/w1mer -a opencode -g
or copy this directory), then register host
agents and the CLI:
sh
python3 <skill-dir>/scripts/w1mer.py install [--host opencode|claude-code|codex|all]
[--link] [--bin-dir <dir>]
copies each host's agent definitions to its agent directory
(opencode →
~/.config/opencode/agents/
, claude-code →
,
codex →
) and puts a
launcher on PATH (symlink the
skill script with
).
prints the target locations
without changing anything. Codex reads agents as TOML files and picks up the
skill itself from
automatically.