160 lines
6.3 KiB
Markdown
160 lines
6.3 KiB
Markdown
# Pipelines
|
|
|
|
Reusable, sequential workflows for your repositories. A Go CLI/TUI and native
|
|
server reuse your OpenCode login; Docker ntfy handles phone notifications.
|
|
|
|
## Install
|
|
|
|
Requires **Go 1.27+** to install. Use your existing OpenCode for model stages;
|
|
Docker/ntfy notifications are optional.
|
|
|
|
```sh
|
|
git clone https://git.a-wan.net/alan/pipelines.git
|
|
cd pipelines
|
|
./install.sh
|
|
pipelines help
|
|
```
|
|
|
|
Go uses `GOBIN` or its normal `GOPATH/bin` default; put that directory on PATH.
|
|
`./install.sh` installs the Go binaries and the shared OpenCode `pipelines` skill.
|
|
There are no login checks, dependency installers, hardcoded install paths, or
|
|
automatic services. With plain `go install ./cmd/...`, also run `pipelines skill install`.
|
|
For system-wide use, install the binaries into your chosen system bin directory
|
|
with the appropriate permissions. Configuration and data remain per-user.
|
|
|
|
Start explicitly; fresh databases contain no pipelines:
|
|
|
|
```sh
|
|
pipelines serve # foreground server
|
|
# In another terminal:
|
|
pipelines
|
|
```
|
|
|
|
Optional autostart at login (starts the server now):
|
|
|
|
```sh
|
|
pipelines service enable
|
|
pipelines service status
|
|
```
|
|
|
|
Uses user-level systemd on Linux or launchd on macOS; no sudo. Runs use the
|
|
directory you invoke `pipelines run` from. Preview with `--print`. Stop any existing
|
|
foreground/legacy server first. Disable with `pipelines service disable` before
|
|
uninstalling. See [installation](docs/install.md) for environment and boot options.
|
|
|
|
## Uninstall
|
|
|
|
```sh
|
|
pipelines uninstall # remove Go binaries; keep history, drafts, and ntfy data
|
|
```
|
|
|
|
## A three-stage pipeline
|
|
|
|
**Plan → Implement → Review**. Each stage receives the previous stage's output;
|
|
the first receives your task prompt. One outcome selects the next stage—no
|
|
parallel branches. Definitions use Markdown `output`, `prompt`, `tools`,
|
|
`configs`, and `edges` blocks. For example:
|
|
|
|
````markdown
|
|
# stage planner
|
|
|
|
```output
|
|
{ task, plan, acceptance_checks }
|
|
```
|
|
|
|
```prompt
|
|
Turn input.prompt into a focused plan and acceptance checks.
|
|
```
|
|
|
|
```tools
|
|
```
|
|
|
|
```configs
|
|
provider=opencode-go
|
|
model=deepseek-v4.1-flash
|
|
retries=0
|
|
```
|
|
|
|
```edges
|
|
success -> implementer
|
|
error -> #failure
|
|
```
|
|
````
|
|
|
|
The [complete three-stage example](examples/three-stage.md) adds the implementer
|
|
and reviewer. Review and explicitly submit it:
|
|
|
|
```sh
|
|
pipelines validate examples/three-stage.md
|
|
pipelines submit examples/three-stage.md --name "three stage" --create-only
|
|
pipelines run "three stage"
|
|
```
|
|
|
|
Every submission is validated and creates an immutable version. Examples are
|
|
optional; nothing is imported automatically. Run from your repository directory;
|
|
stage tools are enabled automatically. Edits support any language/file type and
|
|
new files. No file list or typed RUN confirmation is required.
|
|
|
|
## Useful commands
|
|
|
|
```sh
|
|
pipelines # dashboard; b browses templates
|
|
pipelines list
|
|
pipelines run # fuzzy selection + multiline prompt
|
|
pipelines run "bug fix" "Fix the layout" # run in the current repository
|
|
pipelines new "daily digest" "Summarize changes"
|
|
pipelines edit "bug fix" "Add a review step"
|
|
pipelines drafts --json
|
|
pipelines validate /path/to/draft.md
|
|
pipelines submit /path/to/draft.md # explicit publication
|
|
pipelines runs
|
|
pipelines inspect 1
|
|
pipelines serve # foreground server; Ctrl+C stops it
|
|
pipelines ping
|
|
pipelines help edit
|
|
```
|
|
|
|
CLI `new`/`edit` open OpenCode directly with `@pipelines`. The installed skill asks
|
|
missing questions; `pipelines new` needs no preliminary questionnaire. Changes stay
|
|
as drafts by default; CLI and TUI share validation and draft storage. Most
|
|
commands support `--json` for agents and scripts.
|
|
|
|
In the TUI, press **d** (or use **:drafts**) to browse retained drafts, including
|
|
CLI-created ones. **e** reopens a draft, **v** validates it, and **s** opens explicit
|
|
submission confirmation. Drafts remain retained after submission.
|
|
|
|
From a run, press **p** / **:pipeline** to open the pipeline version it used.
|
|
Initial run input also records `pwd`. Press **r** / **:retry** on a failed run
|
|
(or `pipelines retry <run-id>`) to start a new attempt with the same original
|
|
input, directory, and pipeline version. Completed side effects are not undone.
|
|
On Home, **r** opens all recent runs; both Home panels show the shortcut.
|
|
**n / :new** and creating from a template offer a Tab-navigable, fuzzy-searchable
|
|
picker: **nvim** opens the draft Markdown file; **OpenCode** authors it with you.
|
|
Canceling the picker creates no draft and publishes nothing.
|
|
Wide terminals show runs and pipelines side by side; narrow terminals stack them.
|
|
The dashboard includes all-history usage, success rate, average completed duration,
|
|
per-pipeline usage, and a 14-day activity chart. CLI: `pipelines stats [--json]`.
|
|
Use **:status** for a scrollable server/ntfy popup with health, ports, server-computer
|
|
IPs and candidate URLs. CLI: `pipelines status [--json]`. Candidate URLs are not
|
|
verified reachable; publishing endpoints and credentials are not disclosed.
|
|
Retry is offered only after the failed run and its agent have fully stopped.
|
|
The run inspector shows its actual path above the details, using the same graph
|
|
renderer as pipeline definitions. **g** focuses the graph (arrows pan, j/k scroll).
|
|
The path and elapsed duration update while running. **a** opens the active/latest
|
|
OpenCode session's recorded tool evidence; this does not attach a live OpenCode UI.
|
|
Press **D** / **:debug** (or `pipelines debug <run-id>`) for a fresh OpenCode
|
|
conversation about that run. It uses CLI queries rather than resuming or retrying
|
|
the implementing agent. Pipeline **Edit** offers a fuzzy-searchable **nvim /
|
|
OpenCode** picker; Tab and Shift+Tab navigate it.
|
|
In the draft browser, **x** then **y** deletes the selected retained draft and
|
|
metadata. CLI: `pipelines draft-delete <draft.md>`. Published history is untouched.
|
|
|
|
Model results use native JSON-schema output where supported, precise parsing
|
|
errors, and bounded format-only repair without replaying tools. Optional stage
|
|
permissions narrow file/command access without imposing a language-specific
|
|
default. See [model result recovery and permissions](docs/model-results.md).
|
|
The run graph header shows start time and elapsed/final duration, plus finish
|
|
time for completed runs.
|
|
|
|
More: [CLI](docs/cli.md) · [installation](docs/install.md) · [pipeline format](internal/author/skill/references/format.md).
|