If goobers validate accepts it, the daemon runs it the same way. "Stage"
is prose for what the DSL declares under the tasks: key; the two words
name the same thing.
workflow = trigger + stages + gates
See how that shape works in general on how it works. Below
are six of the eleven workflows in Goobers' own blessed reference config — real,
checked-in shapes of the primitive above, not a fixed menu. That config isn't itself a
live instance, and isn't guaranteed byte-identical to whichever deployment is dogfooding
this repo, which is maintained separately and can drift from what's checked in here.
Compose or extend any of them for your own workflows.
01
Where each workflow starts, ends, and hands off
A workflow class is defined by two things: the surfaces it runs between, and what it
does for the team. Every surface the six below read or write is on this map — the
daemon that runs each arrow, and the harness a goober calls out to, are deliberately
left off. Pick a workflow to trace its route.
Your telemetry
The shipped example reads the instance's own telemetry rollup -- the Goobers
Journal's derived telemetry.db -- not product telemetry. A
product-telemetry connector exists in manifest.yaml; no shipped
workflow reads it yet.
Goobers config
Lives inside the neighboring Instance goobers init --guided proposes by
default (or a custom durable location via --instance-path); a separate,
reviewed configuration repository is an advanced opt-in for a team, not the default.
Goobers journal
The append-only run journal, plus telemetry.db, a derived SQLite
rollup, written on every run. Both live on disk inside the instance's own root.
Running Goobers against its own repository collapses three of these panels into one:
your backlog, your repo, and goobers config are all the same GitHub repository.
Reading the graph
Token
Meaning
Deterministic task: runs a command, no model call.
Agentic task: invokes a goober through a harness.
Gate: a decision state, evaluator kind named in its label or the adjacent ledger. A long
stage id wraps at its hyphens and the diamond sizes itself around it.
Terminal: the run stops here (a phase, not a live status).
Edge: an unconditional or branch-labeled transition. The head points the way the run travels.
Repass edge: the branch loops back to an earlier state instead of advancing.
The portal's own graph legend states the underlying rule this page follows too: "the word
itself is the encoding, never color alone" (WorkflowGraphLegend.tsx).
backlog-curation
Curates a raw backlog into work that is ready to implement.
22 3,11,19 * * * · 1 concurrent · 1/hr
your backlog → your backlog embedded
Runs three times a day (03:22 / 11:22 / 19:22 local), claiming trust-labelled issues
in batches with a side read of the run record. The curator goober holds no repo
capability at all, but broad capability within issues — comment, label, edit, create
(splitting oversized items), close, and assign milestones — held safe by capability
non-injection (SEC-042/SEC-045): credentials for repo or PR capabilities are simply
never materialized into its run.
The backlog-curation workflow, drawn as an engineering schematic per BRAND.md §5.
Fully linear: no gates, no repasses.
scroll →
goobers examples show backlog-curation
work-nomination
Finds the issues nobody has filed yet.
41 6 * * * · 1 concurrent · 1/hr
goobers journal → your backlog embedded
Runs once daily at 06:41 local, aggregating a 24-hour telemetry window — stage-failure
rate, error signatures, gate noise — into evidence-backed candidate issues, deduped
against what it has already raised. Issues land unapproved; a maintainer decides.
The checked-in cadence and budget are the reference's own: this file notes explicitly
that an operator's live-tuned cadence isn't mirrored back into it.
The work-nomination workflow, drawn as an engineering schematic per BRAND.md §5.
Fully linear: gather, then nominate.
scroll →
goobers examples show work-nomination
implementation
Writes code to your standard, and proves it before asking for review.
17 8,20 * * * · 1 concurrent · 1/hr · 1 open PR
your backlog → your repo embedded
Fires twice daily (08:17 / 20:17 local); cadence times the hourly cap together give a
hard ceiling of exactly two runs a day. Picks up one approved-and-ready issue,
implements it in a fresh git worktree, and passes an agentic reviewer gate and local CI
before opening a pull request. Side effect: writes status labels back onto the backlog
issue as it moves.
The implementation workflow, drawn as an engineering schematic per BRAND.md §5:
flat ink, orthogonal routing, gates as plain diamonds. Simplified in one place:
*ci-gate's real fail branch routes to a separate remediate-ci stage,
under its own bounded budget, not directly back to implement.
scroll →
goobers examples show implementation
merge-review
Decides what actually lands, across every open PR at once.
webhook + 23 * * * * · 4 concurrent · 2/hr
your repo → your repo config-examples + reference-workflows + live instance
Reviewing requires a second identity distinct from the PR's own author — GitHub
forbids self-approval — sourced from a dedicated GOOBERS_GITHUB_REVIEW_TOKEN, a required credential upstream lists
separately from the ordinary repo token. The published-verdict gate that
follows requires that native review decision to read pass; its fail
branch is terminal. On a single-identity instance, including Goobers' own, that
separate review can't happen: apply-verdict hits GitHub's self-review
rejection and degrades to a documented comment/label handoff (#870) that
merge-pr reads instead — an operator fallback, not the designed path.
Merging is a separate per-workflow capability grant, never a default.
The merge-review workflow, drawn as an engineering schematic per BRAND.md §5.
Simplified to the core review-to-merge path.
scroll →
Takes a flagged pull request and gets it back to mergeable.
37 * * * * · 1 concurrent · 2/hr
your repo → your repo reference-workflows + live instance
Reworks a goober-authored pull request flagged as needing remediation or failing CI, on that PR's own head branch, under budgets tracked separately per failure cause.
The pr-remediation workflow, drawn as an engineering schematic per BRAND.md §5.
Simplified to its two decision points and the reused implement/review/local-ci
chain (the same chain implementation uses).
scroll →
Reads accumulated run history and proposes exactly one change: a config edit or a skill edit, never both in the same run, confined to a single declared action root. Its PR lands through the same review-and-gate policy as anyone else's change. That gate is the repo owner's to set — CODEOWNERS, required reviewers, branch protection are features of their git host, not something Goobers provides.
The tutor workflow, drawn as an engineering schematic per BRAND.md §5. A linear
pipeline of three consecutive fail-closed validation gates.
scroll →
Labels are the only channel these workflows use to pass work along — no shared
database, no direct calls. The bare goobers label comes first: it's the
hard AND-filter that scopes which issues count as this gaggle's backlog at all
(gaggle.yaml's backlog.labels) — an issue without it is
invisible to every backlog-consuming workflow below, whatever else it carries.
Within that scope, goobers:ready marks curated work;
goobers:approved is maintainer-applied only, never self-applied by a
workflow; goobers/status:in-review marks an open, CI-passed PR. The
remaining three route a problem to whoever should act next, split by whether the
answer is a status or a decision: goobers:blocked-on-sibling and
goobers:needs-remediation park mechanical status that self-heals or gets
retried without a human. Only goobers:needs-human is a decision-required
park, and only it assigns the configured human.
