a3f571d672
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)
77 lines
4.6 KiB
Markdown
77 lines
4.6 KiB
Markdown
# Simple workflow templates
|
|
|
|
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 |
|
|
| --- | --- | --- |
|
|
| `task` | Complete a task, then commit it locally | Work: read/edit/shell and conditional web search/fetch; committer: read/shell |
|
|
| `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
|
|
server-captured changed paths (`input.server_changed_files`) and the producer's
|
|
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
|
|
legacy `{ "outcome": ..., "output": {...} }` envelope is still accepted. See
|
|
`docs/model-results.md`.
|
|
|
|
Web search/fetch is conditional: stages use it only when a task genuinely needs
|
|
external knowledge such as accepted industry approaches, framework or library
|
|
APIs, current security/compatibility guidance, or unfamiliar techniques, and they
|
|
state why when no research is needed. Trivial, fully understood local edits do not
|
|
force web access, and conditional research fails closed only when the required
|
|
reliable evidence cannot be obtained, not merely because one search failed. The
|
|
`three-stage` implementer has no web tools and works from the planner's research
|
|
with local read/edit/shell. The `three-stage` reviewer is an independent quality
|
|
gate: it receives the original task and the planner's plan/design/reuse
|
|
targets/acceptance checks, inspects the actual changed files and runs its own
|
|
checks, returns success only when the applicable acceptance checks were
|
|
independently observed passing and no unresolved substantive issue remains, and
|
|
otherwise rejects with concrete findings even when a stage reported success.
|
|
|
|
In the TUI, use `:templates`, choose a starter, and press **s** or Enter on
|
|
**Submit template**. Type a name, press Enter to save a retained draft, then
|
|
confirm publication. **e Customize** opens the editor picker instead. Canceling
|
|
the name prompt creates nothing; canceling publication keeps the saved draft.
|
|
|
|
CLI equivalent:
|
|
|
|
```sh
|
|
pipelines new "My workflow" --template task --no-open
|
|
pipelines drafts
|
|
pipelines submit /path/printed/by/new.md
|
|
```
|
|
|
|
New drafts inherit the server's configured default model. The checked-in files
|
|
contain a fallback model; direct file submission uses those configs as written.
|
|
Provider inference and search availability must be verified on your execution
|
|
server. Parsing a definition does not prove its model/tools can run.
|
|
|
|
Templates do not impose a language, framework, schedule, notification setup or
|
|
deployment, and they never push to a remote. Work-producing templates commit
|
|
locally through their committer stage; add a schedule, notifications or a
|
|
deployment step only when your own workflow requires it.
|
|
|
|
Editing these source files does not change any installed or published definition;
|
|
each starter becomes an immutable version only after explicit authoring and
|
|
publication.
|
|
|
|
Removing a template from this catalog does not delete published versions,
|
|
run history, retained drafts, or OpenCode sessions. Nested routing examples used
|
|
for renderer regression tests live in `internal/pipeline/testdata`, not this catalog.
|