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)
2.5 KiB
Pipelines maintenance
Consent (hard rule)
The operator owns this system. No change to it happens without their explicit consent in the current conversation: new pipelines or versions, definition and stage-prompt edits, orchestration scripts, briefs and the conventions they carry, the packaged skill and templates, deploys, installs and deletions. Read-only investigation and reporting need no consent. Ask first and name exactly what would change; a request for a fix is not consent for a particular mechanism.
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.
For new references, update internal/author/install.go's managed file inventory.
Run the author package tests: they check embedding, reference links, installation,
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 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
Top-level agents use the configured Pipelines maintenance - plan implement review
maintenance workflow for code changes. Inspect the retained plan/implement/review
outputs and diffs, execute the checks independently, and iterate on concrete
failures rather than trusting stage summaries. An executing stage performs its own
role directly and never recursively launches a workflow. If the workflow is
unavailable, ask instead of silently bypassing it. Never hardcode a disposable
server URL as a project default; the configured endpoint is authoritative.