diff --git a/AGENTS.md b/AGENTS.md index 968f012c..cc40fd17 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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/.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/.md` note. ## Maintenance workflow diff --git a/docs/notes/docs-fold-single-writer.md b/docs/notes/docs-fold-single-writer.md new file mode 100644 index 00000000..c689fc9e --- /dev/null +++ b/docs/notes/docs-fold-single-writer.md @@ -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/.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. diff --git a/examples/README.md b/examples/README.md index 30b4e478..636b07bb 100644 --- a/examples/README.md +++ b/examples/README.md @@ -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/.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 `# ` section is retained verbatim as evidence. The diff --git a/examples/catalog.go b/examples/catalog.go index 5070bcda..150c9f97 100644 --- a/examples/catalog.go +++ b/examples/catalog.go @@ -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 { diff --git a/examples/catalog_test.go b/examples/catalog_test.go index ba0e8a23..6b690b3f 100644 --- a/examples/catalog_test.go +++ b/examples/catalog_test.go @@ -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] diff --git a/examples/docs-fold.md b/examples/docs-fold.md new file mode 100644 index 00000000..a7200acf --- /dev/null +++ b/examples/docs-fold.md @@ -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 `# ` 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 `# ` 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 +``` diff --git a/examples/task.md b/examples/task.md index 9395a751..428a5365 100644 --- a/examples/task.md +++ b/examples/task.md @@ -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/.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 diff --git a/examples/three-stage.md b/examples/three-stage.md index f23e25f6..7cd154c2 100644 --- a/examples/three-stage.md +++ b/examples/three-stage.md @@ -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/.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 diff --git a/internal/author/skill/references/format.md b/internal/author/skill/references/format.md index 0e101011..a1f129a4 100644 --- a/internal/author/skill/references/format.md +++ b/internal/author/skill/references/format.md @@ -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/.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 diff --git a/internal/author/skill/references/orchestration.md b/internal/author/skill/references/orchestration.md index d92bb6d5..66f5f2d2 100644 --- a/internal/author/skill/references/orchestration.md +++ b/internal/author/skill/references/orchestration.md @@ -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/.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; . +never push; record a documentation note in `docs/notes/.md` rather than editing +a shared document; . ``` 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/.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/.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 +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/.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 diff --git a/internal/server/templates_test.go b/internal/server/templates_test.go index 6d7910e8..6471d34e 100644 --- a/internal/server/templates_test.go +++ b/internal/server/templates_test.go @@ -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) diff --git a/scripts/smoke-first-install.py b/scripts/smoke-first-install.py index e13ec5b3..f19e7779 100644 --- a/scripts/smoke-first-install.py +++ b/scripts/smoke-first-install.py @@ -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__":