docs: make docs-fold the single writer of shared documentation

Every item wrote the shared, append-only docs (android/README.md, docs/cli.md and
the packaged skill references), so every merge conflicted on prose. Keep the duty
to notice stale docs; move the writing to one deliberate place.

- Per-item note, not a shared edit. An item that makes a shared document stale
  writes docs/notes/<slug>.md - unique per item, so two items never touch the same
  file - and commits that note with its change. It never edits a README, topic doc
  or packaged skill reference itself.
- One writer. The manual-only docs-fold pipeline, bundled as the fifth starter
  examples/docs-fold.md, folds every note under docs/notes/ into the shared
  document it names and deletes the consumed notes in its own commit; an empty
  notes directory is a success no-op. Operator trigger:
  pipelines new "Docs fold" --template docs-fold --no-open; pipelines submit
  <draft.md>; pipelines run "Docs fold".
- Implemented where the convention lives: orchestration.md (brief item 5, the
  hard-constraint bullet, a "Single documentation writer" section and the
  "Pipeline choice" committer bullet), the canonical committer checklist in
  format.md (new step 6), the committer prompts in examples/task.md and
  examples/three-stage.md, the new examples/docs-fold.md with its catalog and
  README entries, and the repository guideline AGENTS.md. Test-expectation counts
  (examples/catalog_test.go, internal/server/templates_test.go,
  scripts/smoke-first-install.py) follow the fifth starter.

Reflected where it belongs: the packaged templates (examples/task.md,
examples/three-stage.md, the new examples/docs-fold.md), the packaged skill
references (orchestration.md, format.md) and the repo guideline AGENTS.md all carry
the new convention. No new reference file was added, so install.go's managed
inventory is unchanged. The shared descriptive docs were deliberately not
rewritten: this change makes README.md:191, docs/cli.md:170 and
internal/author/skill/references/operations.md:13 name four starters where there are
now five. Those stay as they are - correcting them now is exactly the per-item
shared edit this change removes - and the stale-doc note
docs/notes/docs-fold-single-writer.md records each one for the docs-fold writer to
fold. Nothing else needed updating. No new dependency; no Android, Gradle, server,
installer, Docker or published-definition change; no definition published over the
running pipelines.

Evidence: go test -count=1 ./... passed; go build ./... and go vet on the touched
packages clean; ./internal/author/... covers embedding, reference links, the managed
inventory and install/upgrade/protection; ./examples/... validates the fifth starter
and its manual-only, committer-terminated graph; ./internal/server/... covers the
served catalog. Not run: the docs-fold writer against the shared docs (nothing to
fold yet); no install or deploy.

(cherry picked from commit f29656cf084d7eee2e033f2a37a9d231d7acaaf0)
This commit is contained in:
2026-10-17 16:29:05 +01:00
parent c132e2b59e
commit a3f571d672
12 changed files with 220 additions and 23 deletions
+10 -4
View File
@@ -9,9 +9,13 @@ deploys, installs and deletions. Read-only investigation and reporting need no c
first and name exactly what would change; a request for a fix is not consent for a particular
mechanism.
When changing user-facing behavior or learning a confirmed runtime limitation,
update the relevant packaged OpenCode skill reference in
`internal/author/skill/references/` in the same change. Keep `SKILL.md` a concise,
When a change alters user-facing behavior, or you learn a confirmed runtime
limitation, record the stale documentation instead of editing the shared document in
the same change: leave a per-item note at `docs/notes/<slug>.md` naming what changed and
which packaged OpenCode skill reference in `internal/author/skill/references/`, README
or topic doc is now stale and what should change there. The manual-only `docs-fold`
pipeline folds `docs/notes/` into the shared docs and references; an item never edits a
shared document itself. Keep `SKILL.md` a concise,
task-directed index: preserve ask-first authoring and never preload every reference.
Separate current capabilities, dated verification evidence, deployment state and
unimplemented ideas. Do not turn mocked or structural checks into live claims.
@@ -21,7 +25,9 @@ Run the author package tests: they check embedding, reference links, installatio
upgrades and protection of user modifications. Never hand-edit an installed copy
as the source of truth; refresh it with the current-source `pipelines skill install`
only when installation is requested. Do not deploy runtime changes merely because
the skill is updated. Keep README/topic docs and the packaged reference consistent.
the skill is updated. Keep the shared docs and packaged references consistent through
the single `docs-fold` writer rather than editing them per item: leave a
`docs/notes/<slug>.md` note.
## Maintenance workflow
+40
View File
@@ -0,0 +1,40 @@
# docs-fold single documentation writer
## What this item changed
Per-item workflows no longer edit shared documentation themselves. The convention now
lives in `internal/author/skill/references/orchestration.md` (brief item 5, the
hard-constraint bullet, "Single documentation writer", and the "Pipeline choice"
committer bullet), the canonical committer checklist in
`internal/author/skill/references/format.md` (step 6), the bundled committer prompts in
`examples/task.md` and `examples/three-stage.md`, and the repository guideline
`AGENTS.md`.
The chosen mechanism is a **per-item note file** at `docs/notes/<slug>.md`: when a
change makes a shared document stale, the item records what changed and what should
change there, commits that note with its own change, and never edits a shared document.
The chosen **single writer** is the manual-only `docs-fold` pipeline, added as a fifth
bundled starter at `examples/docs-fold.md` and listed in `examples/catalog.go` and
`examples/README.md`. Its `fold` stage reads every note under `docs/notes/`, folds each
into the shared document it names, and deletes the consumed notes in its own commit.
## Shared documents this change makes stale
Adding the fifth starter (`docs-fold`) makes the following documents' starter counts
wrong. They were deliberately **not** edited by this item; the `docs-fold` writer should
correct them when it next folds notes.
- `README.md:191` — "To skip authoring, use **:templates**, choose one of the four
generic starters," should read "five generic starters".
- `docs/cli.md:170` — "Use `:templates` for four simple, manual-only starters: task,
review, research, and plan/implement/review." should say five starters and name
`docs-fold` (fold accumulated documentation notes, then commit locally).
- `internal/author/skill/references/operations.md:13` — "Four optional generic starters
are task, review, research and three-stage;" should read "Five optional generic
starters are task, review, research, three-stage and docs-fold;".
## Do not change
- `docs/first-version-testing.md:148` and the dated records in
`docs/installation-verification.md` describe a past fixture run at the time it ran;
they are dated evidence, not current counts, and stay as they are.
+8 -1
View File
@@ -1,6 +1,6 @@
# Simple workflow templates
Four optional, technology-neutral starters. Nothing is installed as a published
Five optional, technology-neutral starters. Nothing is installed as a published
pipeline automatically; all templates are manual-only and have at most four stages.
| Template key | Workflow | Tools |
@@ -9,6 +9,7 @@ pipeline automatically; all templates are manual-only and have at most four stag
| `review` | Read repository content and report findings | Read/glob/grep and conditional web search/fetch; no edit/shell |
| `research` | Research a topic, then write a sourced report | Web search/fetch, then none |
| `three-stage` | Plan → implement → review → commit | Planner read/glob/grep + conditional web; implementer read/glob/grep/edit/shell with no web (follows the planner's research); reviewer independent shell + conditional web; committer read/shell |
| `docs-fold` | Fold accumulated item documentation notes into the shared docs, then commit locally | Fold: read/glob/grep/edit/shell; committer: read/shell |
Every workflow that changes the repository ends in a **committer** stage that
commits locally and never pushes. The committer stages the union of the runner's
@@ -17,6 +18,12 @@ declared `changed_files` — a declared list can be incomplete — then runs the
repository's required checks before committing. `task` and `three-stage` follow this;
`review` and `research` change nothing and so do not commit.
`docs-fold` is the deliberate **single documentation writer**. A per-item workflow never
edits a shared README or topic doc: when its change makes one stale it records a note at
`docs/notes/<slug>.md`, unique per item, and commits that note with the change. Running
the manual-only `docs-fold` pipeline later folds the accumulated notes into the shared
documentation and removes them.
Model and agent stages return the line-oriented result: the first non-empty line is
the declared outcome, a `# output` section holds the JSON output map for the next
stage, and any further `# <heading>` section is retained verbatim as evidence. The
+1
View File
@@ -16,6 +16,7 @@ var starters = []protocol.Template{
{Key: "three-stage", Name: "Plan, implement, review", Description: "Plan a change, implement it, review and verify it, then commit it locally. Any language or file type."},
{Key: "review", Name: "Review a repository", Description: "One read-only stage to review repository content and report findings."},
{Key: "research", Name: "Research a topic", Description: "Research a topic on the web, then write a sourced report. Requires web search support."},
{Key: "docs-fold", Name: "Fold documentation notes", Description: "Fold the accumulated per-item documentation notes into the shared docs, then commit locally. The repository's single documentation writer; manual-only."},
}
func Catalog() []protocol.Template {
+7 -2
View File
@@ -27,11 +27,11 @@ func TestReadmeThreeStageExampleIsValid(t *testing.T) {
func TestCatalogContainsValidUnpublishedTemplates(t *testing.T) {
items := examples.Catalog()
if len(items) != 4 {
if len(items) != 5 {
t.Fatal("unexpected catalog size", len(items))
}
seen := map[string]bool{}
wantStages := map[string]int{"task": 2, "review": 1, "research": 2, "three-stage": 4}
wantStages := map[string]int{"task": 2, "review": 1, "research": 2, "three-stage": 4, "docs-fold": 2}
for _, item := range items {
if seen[item.Key] || item.Description == "" || item.Name == "" {
t.Fatal("invalid template metadata", item.Key)
@@ -104,6 +104,10 @@ var starterTools = map[string]map[string][]string{
"reviewer": {"read", "glob", "grep", "shell", "websearch", "webfetch"},
"committer": {"read", "glob", "grep", "shell"},
},
"docs-fold": {
"fold": {"read", "glob", "grep", "edit", "shell"},
"committer": {"read", "glob", "grep", "shell"},
},
}
func TestStarterRoleToolRestrictions(t *testing.T) {
@@ -182,6 +186,7 @@ func TestWorkProducingStartersEndInACommitter(t *testing.T) {
for _, tc := range []struct{ key, producer string }{
{"task", "worker"},
{"three-stage", "implementer"},
{"docs-fold", "fold"},
} {
graph := parsedCatalog(t)[tc.key]
last := graph.Stages[len(graph.Stages)-1]
+90
View File
@@ -0,0 +1,90 @@
# stage fold
```output
{ summary, changed_files, folded_notes }
```
```prompt
Fold the accumulated per-item documentation notes into the repository's shared
documentation. Read every file under `docs/notes/`; for each note, apply the change it
records to the shared document the note names - the repository's READMEs and topic docs
and the packaged skill references - then delete the consumed note. Do not edit any other
file, change behaviour, or rewrite documentation that is still true. Keep values from
their single existing sources. An empty or missing `docs/notes/` directory is a success
no-op: make no change, commit nothing, and say so. Limit inspection to the notes
directory and the documents they name; never scan filesystem or mount roots, and use
commands supported by the actual execution environment. Save any artifacts you produce
into the artifacts directory named in the runtime context. Report the notes read, the
documents changed and the notes deleted in an `# evidence` section, with the exact
commands and observed results. Return the line-oriented result: the first non-empty line
is the declared outcome, a `# output` section holds one JSON object with the output
fields named above, and any further `# <heading>` section is retained verbatim as
evidence. Return blocked if the notes directory cannot be read.
```
```tools
read
glob
grep
edit
shell
```
```configs
provider=opencode-go
model=deepseek-v4.1-flash
retries=2
timeout=1h
```
```edges
success -> committer
blocked -> #failure
error -> #failure
```
# stage committer
```output
{ committed, commit, changed_files, pre_commit_checks }
```
```prompt
Commit this run's change locally. Never push, tag, deploy or rewrite history. Select
the run's changed paths from input.server_changed_files (the runner's captured
evidence) and the fold stage's declared changed_files, and stage their union, including
the notes the fold stage deleted (stage the removal, not only surviving paths). Inspect
the staged diff before committing; never commit unrelated work, secrets or generated
artifacts. When nothing is staged - for example an empty notes directory - do not create
an empty commit; return success with a clear note. Otherwise commit with a concise
message naming this run's change and report the commit hash. If a required check fails,
do not commit; return blocked with the failing output. Return the line-oriented result:
the first non-empty line is the declared outcome, a `# output` section holds one JSON
object with the output fields named above, and any further `# <heading>` section is
retained verbatim as evidence. Never claim an unexecuted check passed or fabricate a
commit.
```
```memory
{"changed_files":"fold.changed_files","server_changed_files":"input.server_changed_files"}
```
```tools
read
glob
grep
shell
```
```configs
provider=opencode-go
model=deepseek-v4.1-flash
retries=2
timeout=1h
```
```edges
success -> #success
blocked -> #failure
error -> #failure
```
+6 -1
View File
@@ -71,7 +71,12 @@ Commit this run's change locally. Never push, tag, deploy or rewrite history.
Select the run's changed paths from input.server_changed_files (the runner's
captured evidence) and the worker's declared changed_files, and stage their union
of paths that still exist, keeping any exclusions. Inspect the staged diff before
committing; never commit unrelated work, secrets or generated artifacts. Pre-commit
committing; never commit unrelated work, secrets or generated artifacts. Follow the
documentation-note step of the committer checklist in `references/format.md`: when the
change makes a shared document stale, stage the item's own documentation note
(`docs/notes/<slug>.md`) with the change, and never edit a shared document (a README,
topic docs or the packaged skill references) here; a single documentation writer folds
notes later. Pre-commit
checklist: confirm the staged paths are this run's change; run the repository's
required checks and record the exact commands and observed results in an
`# evidence` section; do not commit if a required check fails, return blocked
+5 -1
View File
@@ -179,7 +179,11 @@ Select the run's changed paths from input.server_changed_files (the runner's
captured evidence) and the implementer's declared changed_files, and stage their
union of paths that still exist, keeping any exclusions. Inspect the staged diff
before committing; never commit unrelated work, secrets or generated artifacts.
Pre-commit checklist: confirm the staged paths are this run's change; run the
Follow the documentation-note step of the committer checklist in
`references/format.md`: when the change makes a shared document stale, stage the item's
own documentation note (`docs/notes/<slug>.md`) with the change, and never edit a shared
document (a README, topic docs or the packaged skill references) here; a single
documentation writer folds notes later. Pre-commit checklist: confirm the staged paths are this run's change; run the
repository's required checks and record the exact commands and observed results in
a `# evidence` section; do not commit if a required check fails, return
blocked with the failing output instead. If nothing is staged, do not create an
@@ -228,6 +228,15 @@ State this pre-commit checklist in the prompt:
note.
5. Commit with a concise message naming the run's change and report the commit hash;
never push, tag, rebase or amend.
6. Ensure the item's per-item documentation note (`docs/notes/<slug>.md`, written when
the change makes a shared document stale) is staged with the change. Never edit a
shared document (a README or topic doc, or a packaged skill reference) here: a single
documentation writer folds notes later (`references/orchestration.md`). An item that
staled no shared document has no note and needs no step 6.
This list is the canonical checklist. The bundled starters `task`, `three-stage` and
`docs-fold` each repeat it in their committer prompt because a template is embedded and
published on its own; keep those copies in sync with this list.
Merging is the operator's or a lane's job, not the committer's: it commits locally
and stops (`references/orchestration.md`, `references/lanes.md`). The server does
@@ -55,8 +55,11 @@ Every brief has:
output it must report, plus the screenshots the reviewer must read. Say plainly:
"report the exact commands and their observed results. Do not claim a check you
did not run."
5. **Where it belongs** — the packaged templates and the packaged skill references the change is expected to touch,
so the committer can check and update them before it commits.
5. **Documentation note** — where the change makes shared documentation stale, the item
records that in its own per-item note `docs/notes/<slug>.md`: what it changed and
which shared document (a README or topic doc, or a packaged skill reference) is now
stale and what should change there. The item writes only its note; it must not edit a
shared document. See "Single documentation writer" below.
6. **The hard constraints block** (below).
7. **Publishing rules** (`references/delivery.md`).
@@ -80,7 +83,8 @@ dependencies; do not restart, rebuild or reconfigure the Pipelines or OpenCode
server, the installer, the ntfy service or any other service - runs and lanes are
active; never install on the operator's physical device; keep geometry and values
from their single existing sources rather than new literals; commit locally only,
never push; <the item's publishing rules>.
never push; record a documentation note in `docs/notes/<slug>.md` rather than editing
a shared document; <the item's publishing rules>.
```
Requirements must be concrete and checkable. Name files, functions, commands, and
@@ -105,12 +109,36 @@ Adapt the scope and publishing lines per item; keep the rest.
- **Keep values from single sources** — geometry, tokens, sizes and constants come
from the source that already owns them, not from new literals.
- **Commit locally only, never push** — the committer stage commits, no other stage.
- **Reflect the change where it belongs** — before committing, the committer checks
that the change is reflected in the packaged templates and the packaged skill references,
updates anything stale,
and states in the commit body what it checked or that nothing needed updating.
- **Record stale documentation; do not rewrite it** — before committing, the committer
ensures the item's `docs/notes/<slug>.md` note, when the change makes a shared document
stale, is staged with the change, and states in the commit body what it checked. The
committer never edits a shared document (a README or topic doc, or a packaged skill
reference) itself; the single documentation writer folds notes later.
- **Publish rules** — WIP artefact naming and LAN URLs per `references/delivery.md`.
## Single documentation writer
Shared documentation — the repository's READMEs and topic docs (for this repository
`android/README.md` and `docs/cli.md`) and the packaged skill references in
`internal/author/skill/references/` — has exactly one writer, never an item. Each item
that makes one of these stale leaves a note at `docs/notes/<slug>.md` (item 5 above).
The note's filename is unique per item, so two items never write the same file and
never conflict on prose.
The writer is the manual-only `docs-fold` pipeline, bundled as the starter
`examples/docs-fold.md`. Its `fold` stage reads every note under `docs/notes/`, folds
each into the shared document it names, and deletes the consumed notes in its own
commit; an empty `docs/notes/` is a success no-op with no empty commit. It is never
scheduled and is never part of a per-item workflow.
The operator triggers it deliberately:
```sh
pipelines new "Docs fold" --template docs-fold --no-open
pipelines submit <draft.md>
pipelines run "Docs fold"
```
## Pipeline choice
- Use a pipeline that keeps **implementer + reviewer + ui_reviewer + committer** for
@@ -122,10 +150,11 @@ Adapt the scope and publishing lines per item; keep the rest.
`skipped` with a reason when the change has no rendered surface. Never accept a UI
change approved without the images.
- The committer is the only stage that commits, and it stages only the run's changed
files. Before committing it checks that the change is reflected in the packaged
templates and the packaged
skill references, updates anything stale, and states in the commit body what it
checked or that nothing needed updating. It must also select `input.server_changed_files`
files. Before committing it ensures the item's `docs/notes/<slug>.md` note, when the
change makes a shared document stale, is staged with the change, and states in the
commit body what it checked; it never edits a shared document (a README or topic doc,
or a packaged skill reference) itself, because a single documentation writer folds
notes later. It must also select `input.server_changed_files`
(the runner's captured evidence, `references/control.md`) alongside the implementer's
declared `changed_files` and stage their union: an implementer's declared list can be
incomplete, and a captured path it omitted is still this run's change. Its prompt carries
+2 -1
View File
@@ -2,6 +2,7 @@ package server
import (
"context"
"git.a-wan.net/alan/pipelines/examples"
"git.a-wan.net/alan/pipelines/internal/pipeline"
"git.a-wan.net/alan/pipelines/internal/protocol"
"github.com/coder/websocket"
@@ -44,7 +45,7 @@ func TestTemplatesDoNotSeedDatabaseAndCreateOnlyPreservesExisting(t *testing.T)
if err := wsjson.Read(ctx, conn, &response); err != nil {
t.Fatal(err)
}
if response.Type != protocol.Templates || len(response.Templates) != 4 {
if response.Type != protocol.Templates || len(response.Templates) != len(examples.Catalog()) {
t.Fatal("missing catalog", response.Type, len(response.Templates))
}
items, err := store.List(ctx)
+2 -2
View File
@@ -78,7 +78,7 @@ def main():
assert pong["build"] == version, "Client/server build mismatch"
assert not rpc("list").get("pipelines"), "Fresh database must be empty"
assert not rpc("runs").get("runs"), "Fresh database must have no runs"
assert len(rpc("templates")["templates"]) == 4
assert len(rpc("templates")["templates"]) == 5
draft = rpc("new", "First test", "Review the repository", "--template", "review", "--no-open", "--yes")
assert not rpc("list").get("pipelines"), "Draft creation must not publish"
rpc("validate", draft["path"])
@@ -100,7 +100,7 @@ def main():
assert not rpc("runs").get("runs"), "Smoke check must not execute a workflow"
finally:
stop(process)
print("PASS developer lifecycle fixture: isolated source binaries/skill, offline version, empty DB, four templates, draft/validate/publish, ZIP identical import, restart persistence. Not an installation option; no inference or notifications.")
print("PASS developer lifecycle fixture: isolated source binaries/skill, offline version, empty DB, five templates, draft/validate/publish, ZIP identical import, restart persistence. Not an installation option; no inference or notifications.")
if __name__ == "__main__":