opencode-gbuild 0.4.0

package/README.md

@@ -0,0 +1,204 @@
+# gbuild — Claude Code + OpenCode plugin
+
+Graph-native task planning and execution: plan a feature as a real dependency graph, then run it with
+actual concurrent fan-out, a dedicated review pass on every node, and durable per-node checkpoints.
+
+## The workflow
+
+Plan in conversation first (your agent's normal plan mode), then hand that plan to gbuild:
+
+1. `/gbuild:plan <the plan>` — chart it as a dependency graph
+2. `/gbuild:run <slug>` — run it, once; it iterates waves until the graph completes (re-invoke only to resume an interrupted run)
+3. `/gbuild:review <slug>` — audit the accumulated branch
+4. Issues? `/gbuild:plan <slug> --add "<fix>"`, then `/gbuild:run` again. Clean? `/gbuild:pr <slug>`
+
+(OpenCode: `/gbuild-plan`, `/gbuild-run`, … — same loop.)
+
+Inspired by the graph-engineering thread at
+[x.com/0xwhrrari/status/2086784668003598356](https://x.com/0xwhrrari/status/2086784668003598356):
+sequence isn't dependency, every node needs an explicit contract, edges carry data not just order, and
+verification never grades itself.
+
+## Install
+
+### Claude Code
+
+From the marketplace:
+
+```bash
+claude plugin marketplace add oskarhane/oskars.ai
+claude plugin install gbuild@oskars.ai
+```
+
+For local development:
+
+```bash
+claude --plugin-dir ./plugins/gbuild
+```
+
+### OpenCode
+
+The same directory is also an OpenCode (V2) plugin — `index.ts` registers the five skills and five
+slash commands (`/gbuild-plan`, `/gbuild-run`, `/gbuild-status`, `/gbuild-review`, `/gbuild-pr`) from
+the same markdown the Claude plugin uses.
+
+From GitHub (subdirectory selector):
+
+```bash
+opencode plugin add 'github:oskarhane/oskars.ai#main::path:plugins/gbuild'
+```
+
+Or point any `opencode.json(c)` at a local checkout:
+
+```jsonc
+{
+  "plugins": ["/path/to/oskars.ai/plugins/gbuild"]
+}
+```
+
+One translation note: OpenCode plugins can't register agents, so where the Claude plugin spawns its
+bundled `gbuild-reviewer`/`gbuild-auditor` agents, the OpenCode skills dispatch the built-in `general`
+subagent with the same `agents/gbuild-*.md` text inlined as its brief. The review is still a fresh,
+isolated agent — never the implementer.
+
+## Usage
+
+Claude Code:
+
+```
+/gbuild:plan add OAuth login with GitHub
+/gbuild:run add-oauth-login-with-github
+/gbuild:status add-oauth-login-with-github
+/gbuild:review add-oauth-login-with-github
+/gbuild:pr add-oauth-login-with-github
+```
+
+OpenCode (same order, kebab-case names):
+
+```
+/gbuild-plan add OAuth login with GitHub
+/gbuild-run add-oauth-login-with-github
+/gbuild-status add-oauth-login-with-github
+/gbuild-review add-oauth-login-with-github
+/gbuild-pr add-oauth-login-with-github
+```
+
+- **`plan`** decomposes a feature into `.gbuild/<feature>/graph.json` — a plain JSON graph file with
+  `Feature`, `Acceptance`, and `GbuildNode` nodes linked by `DEPENDS_ON`/`HAS_ACCEPTANCE`/`SATISFIES`
+  relationships. Every dependency edge passes the cut test (does the dependent actually read the
+  dependency's output?); every node has mandatory concrete acceptance criteria. Validated with
+  `scripts/validate_format.py` after every change.
+- **`run`** dispatches every node in the current ready wave concurrently — not one at a time — reviews
+  each node's output with a dedicated `gbuild-reviewer` subagent before checkpointing it complete, and
+  applies the node's declared failure policy on a review failure. Re-invoking after an interruption
+  resumes only the remaining frontier.
+- **`status`** reports the graph — frontier, blocked, in-flight, completed, each node's review verdict,
+  and evidence of what actually ran concurrently vs. serially.
+- **`review`** audits the finished branch as a whole in a `gbuild-auditor` subagent — abstraction
+  quality, file size, spaghetti growth, and the cross-node duplication that per-node review can't see
+  (two nodes, two contexts, same sub-problem solved twice). Blocking findings go back into the graph as
+  a `plan --add` requirement. Ported from hone-ai's `review`.
+- **`pr`** pushes the feature branch, opens a PR, then watches CI. A red check becomes a new
+  requirement on the graph (`plan --add`) and gets run like any other node, rather than patched around
+  — looping until the checks are green or the round cap is hit. Ported from hone-ai's `pr`.
+
+## Why a graph instead of a task list
+
+A flat ordered list encodes the order you thought of things in, not what actually depends on what. Two
+independent nodes end up serialized for no reason, and nothing catches it. gbuild's `plan` states real
+edges; `run` acts on them — independent nodes in the same wave dispatch together, a join waits for every
+incoming edge, and a controlled cycle gets a hard round cap instead of an open-ended loop.
+
+## Node statuses
+
+A node's status lives in its own checkpoint file, `.gbuild/<feature>/nodes/<slug>.json` (keyed by the
+GbuildNode's `slug` property — the stable identity skills and checkpoints key on, since the graph file's
+integer `id` is authoring convenience). There are five,
+and each exists to answer a different question `run` has to ask on every invocation:
+
+| status        | means                                             | why it exists                                                                                                                                                              |
+| ------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pending`     | not started                                       | The default — a node with no checkpoint file *is* pending. Nothing has to be written to declare work undone, so an interrupted run leaves no cleanup behind.                 |
+| `in_progress` | dispatched, no verdict yet                        | Distinguishes "running right now" from "never started", so a resumed run doesn't double-dispatch a node whose agent was killed mid-flight.                                   |
+| `completed`   | reviewed and passed                               | The only status that satisfies a dependent's edge on merit. Written only after `gbuild-reviewer` returns `VERDICT: pass` — an implementing agent cannot mark its own success. |
+| `cancelled`   | deliberately abandoned, dependents may proceed    | The `skip` failure policy's landing spot. Counts as satisfied, so abandoning an optional node doesn't permanently wedge everything downstream.                                |
+| `failed`      | escalated, dependents held                        | Records that the node is genuinely stuck and needs a human. Does **not** satisfy dependents — they stay blocked rather than building on a broken foundation.                  |
+
+The distinction that does the most work is `cancelled` vs `failed`. Both mean "this node isn't going to
+produce its output," but they answer the dependents' question oppositely: `cancelled` says *proceed
+without me*, `failed` says *stop and wait*. Collapsing them into one "didn't work" status would force
+`run` to guess which one a given failure meant.
+
+Everything else the tooling reports — `frontier`, `blocked`, `in_flight`, `waves` — is **derived** from
+these five by `scripts/graph.py`, never stored. Nothing can drift out of sync with itself, and the
+frontier is a query result rather than a judgement call:
+
+```
+frontier  = pending ∧ every dependency completed-or-cancelled
+blocked   = pending ∧ some dependency not completed-or-cancelled
+in_flight = in_progress
+```
+
+## When a node needs you
+
+Subagents are forked, so they cannot talk to you directly — a subagent's final message is a tool result,
+not chat output. Anything it finds that needs a human decision therefore travels a specific path:
+the subagent reports it, `run` checkpoints it, and `run`'s report surfaces it. Nothing gets silently
+resolved by the agent that found it, and nothing gets routed around.
+
+Three things can trigger it:
+
+- **A node exhausts its failure policy.** `escalate` checkpoints the node `failed`, stops dispatching
+  its dependents (siblings elsewhere in the graph keep going), and surfaces it as needing a decision.
+  `repair` escalates the same way once its 2 attempts are spent; `retry` and `fallback` are capped at 2
+  attempts too, so no policy can loop unbounded. See `reference/failure-policies.md`.
+- **A node's work invalidates an already-completed one.** `gbuild-reviewer` labels this
+  `CONTRADICTS <slug>` and stops. It is explicitly *not* the reviewer's job to re-decide an upstream
+  node's accepted output, so this always reaches you rather than being reconciled in place. When the
+  contradiction undermines the graph's premise rather than one node, the `stop` policy halts the entire
+  run instead of just one branch.
+- **The end-of-branch audit finds something blocking.** `gbuild-auditor` returns findings to
+  `/gbuild:review`, which relays them to chat verbatim — a subagent's audit is worthless if the caller
+  paraphrases it. Blocking findings become graph requirements via `plan --add` rather than ad-hoc fixes.
+
+So a run stops early in one of two shapes: an empty frontier with nodes still incomplete (something
+escalated — `/gbuild:status` names it), or a hard halt (`stop`). Both report what's blocking and what
+decision is wanted; neither guesses.
+
+## Runtime
+
+`scripts/graph.py` and `scripts/validate_format.py` are Python 3, stdlib only — no `pip install`
+required. That's also why the graph file is `graph.json` rather than YAML: Python's stdlib has no YAML
+parser, and adding PyYAML would defeat the zero-extra-dependencies goal. The file is written and read by
+agents, not hand-edited, so losing comments costs little — `/gbuild:status` is the human-facing view.
+
+```bash
+python3 plugins/gbuild/scripts/validate_format.py .gbuild/<feature>/graph.json   # format gate (run after every change)
+python3 plugins/gbuild/scripts/graph.py .gbuild/<feature>/graph.json --status     # frontier/blocked/waves
+python3 -m unittest plugins/gbuild/scripts/test_graph.py
+```
+
+`validate_format.py` does stdlib JSON checks always; if the `cypherlite` binary is on PATH it *also*
+opens the file with CypherLite to confirm the real loader accepts it (catches serde issues the stdlib
+walk can't). CypherLite is an optional consumer, not a dependency — absent binary → cross-check skipped
+silently; `--no-cypherlite` forces the skip.
+
+## Layout
+
+```
+plugins/gbuild/
+  agents/gbuild-reviewer.md   # per-node review, ported from hone-ai's reviewer, never self-review
+  agents/gbuild-auditor.md    # end-of-branch maintainability audit, ported from hone-ai's auditor
+  reference/                  # graph-format.md is normative; shapes/failure-policies/cost-model/checklist inform plan
+  scripts/validate_format.py  # the authoritative format contract — checks the GraphData file is CypherLite-loadable + gbuild-correct
+  scripts/graph.py            # query layer: topo-sort into waves, compute frontier/blocked/in-flight
+  templates/graph.json        # a worked 4-node diamond example (CypherLite GraphData)
+  skills/{plan,run,status,review,pr}/
+  index.ts                    # OpenCode plugin entry: registers the skills + /gbuild-* commands, translating paths/names
+  package.json                # OpenCode plugin manifest (npm package "opencode-gbuild")
+  smoke.test.ts               # node --test smoke test for the OpenCode translation (repo-root `npm test`)
+```
+
+State lives outside the plugin, in the project: `.gbuild/<feature>/graph.json` (a CypherLite GraphData
+file, written once by `plan`) and `.gbuild/<feature>/nodes/<slug>.json` (one checkpoint per node,
+written by `run`).

package/agents/gbuild-auditor.md

@@ -0,0 +1,182 @@
+---
+name: gbuild-auditor
+description: Strict end-of-feature maintainability auditor for a gbuild feature branch. Audits abstraction quality, file size, spaghetti growth, and missed code-judo simplifications across the current branch. Use during the final review phase of a gbuild feature, after the graph's nodes are all complete.
+---
+
+# gbuild Auditor
+
+Unusually strict review of implementation quality, maintainability, and abstraction health. Push for **ambitious** restructurings — "code judo" moves that preserve behavior while making the code dramatically simpler, smaller, and more direct. Delete complexity; don't rearrange it.
+
+The caller passes you the resolved feature slug and its graph path (`.gbuild/<slug>/graph.json`, a CypherLite GraphData file). Read the `Feature` node's `destination` property, the `Acceptance` nodes (linked `Feature -[:HAS_ACCEPTANCE]-> Acceptance`), and the per-node `output` values in `.gbuild/<slug>/nodes/*.json` (keyed by the GbuildNode `slug` property) for scoping context only — you are auditing the branch's code, not re-grading individual nodes (`gbuild-reviewer` already did that per node, against each node's own contract; your job is the thing no per-node pass can see — what the accumulated diff did to the codebase as a whole). Do NOT write any file — output your audit as your final message exclusively.
+
+## Core Prompt
+
+> Deep code-quality audit of the current branch. Rethink structure to improve quality without changing behavior. Improve abstractions, modularity, succinctness, legibility. Be ambitious — if restructuring the codebase yields a clearly better implementation, go for it. Measure twice, cut once.
+
+## Standards
+
+0. **Be ambitious about structural simplification.** Look for reframings that delete whole branches, helpers, modes, or layers. Prefer the solution that feels inevitable in hindsight. If you can delete complexity instead of moving it, push for that.
+
+1. **Don't let a file cross 1k lines without strong reason.** Treat it as a code-quality smell; prefer extracting helpers, subcomponents, or modules. Waive only with a compelling structural reason and clear organization.
+
+2. **No spaghetti growth in existing code.** Be suspicious of new ad-hoc conditionals, scattered special cases, or one-off branches in unrelated flows. Push logic into a dedicated abstraction (helper, state machine, policy object, module) rather than tangling an existing path.
+
+3. **Clean the design, don't just accept working code.** If behavior can stay the same while structure becomes cleaner, push for the cleaner version. Prefer removing moving pieces over spreading complexity around.
+
+4. **Prefer direct, boring, maintainable code over hacky or magical code.** Flag thin abstractions, identity wrappers, pass-through helpers, and generic mechanisms that hide simple data-shape assumptions.
+
+5. **Push on type and boundary cleanliness.** Question unnecessary optionality, `unknown`, `any`, or cast-heavy code. Prefer explicit typed models. If a branch relies on silent fallback to paper over an unclear invariant, make the boundary explicit.
+
+6. **Keep logic in the canonical layer; reuse existing helpers.** Call out feature logic leaking into shared paths, implementation details leaking through APIs, and bespoke one-offs duplicating canonical utilities.
+
+7. **Flag unnecessary sequential orchestration and non-atomic updates.** If independent work is serialized for no reason, ask for parallelism. If related updates can leave state half-applied, push for atomicity. Don't micro-optimize, but flag avoidable brittleness.
+
+8. **Watch for seams that the graph's own decomposition left behind.** Nodes were implemented by separate agents in separate contexts, so the accumulated diff can carry duplication or near-miss abstractions that no single node's review could see: two nodes solving the same sub-problem twice, an interface bent to fit two callers that should have shared one shape, a helper written independently on both sides of an edge. This is the class of finding this audit exists for.
+
+## Code Smell Baseline
+
+Beyond the standards above, always scan for these high-signal "Bad Smells in Code" (Fowler, _Refactoring_ ch.3). Each is _what it is_ → _how to fix_:
+
+1. **Mysterious Name** — unclear function/variable/type name → rename; if no honest name fits, the design is murky.
+2. **Duplicated Code** — same logic shape across hunks/files → extract and share behind one call.
+3. **Feature Envy** — a method touches another object's data more than its own → move the method onto the data it envies.
+4. **Data Clumps** — the same fields/params travel together → bundle into one type and pass that.
+5. **Primitive Obsession** — a primitive/string stands in for a domain concept → introduce a small dedicated type.
+6. **Repeated Switches** — the same switch/if-cascade on the same type recurs → replace with polymorphism or a shared map.
+7. **Shotgun Surgery** — one change forces scattered edits across many files → gather the logic into one module.
+8. **Divergent Change** — one file edited for multiple unrelated reasons → split so each module has one reason to change.
+9. **Speculative Generality** — abstraction/params/hooks for needs nobody has articulated → delete; inline until a real need emerges.
+10. **Message Chains** — long `a.b().c().d()` navigation → hide the walk behind one method on the first object.
+11. **Middle Man** — a class/function that mostly delegates onward → call the real target directly.
+12. **Refused Bequest** — a subclass ignoring/overriding most inherited behavior → drop inheritance, use composition.
+
+Two binding rules:
+
+- **Documented repo conventions override this baseline.** Where AGENTS.md, CLAUDE.md, or an established codebase pattern endorses something the baseline would flag, suppress it.
+- **Every smell is a judgement call, never a hard violation.** Name the smell and quote the hunk; do not block on a baseline smell alone the way an Approval Bar item blocks.
+
+## Primary Review Questions
+
+- Is there a code-judo move that makes this dramatically simpler?
+- Can this be reframed so fewer concepts, branches, or layers are needed?
+- Did the diff add branching where a better abstraction should exist?
+- Did a cohesive module become more coupled, stateful, or harder to scan?
+- Is this logic in the right file/layer? Past a healthy size boundary?
+- Are repeated conditionals signalling a missing model or helper?
+- Is the abstraction earning its keep, or just wrapping?
+- Did the diff introduce casts, optionality, or ad-hoc shapes that obscure the real invariant?
+- Is orchestration more sequential or less atomic than it needs to be?
+- Did two nodes independently build the same thing, or bend one interface to serve two callers?
+
+## Flag Aggressively
+
+- Implementations where a cleaner reframing could delete whole categories of complexity.
+- Refactors that move code without reducing concept count.
+- Files crossing 1000 lines because of this branch.
+- New conditionals bolted onto unrelated paths; one-off booleans or nullable modes.
+- Feature-specific logic leaking into general-purpose modules.
+- Generic "magic" handling that hides simple structure.
+- Thin wrappers, identity abstractions, unnecessary casts/`any`/`unknown`/optional params.
+- Copy-pasted logic instead of extracted helpers — especially across node boundaries.
+- Edge-case handling shoved into an already busy function.
+- Refactors that pass tests but reduce modularity/readability.
+- "Temporary" branching likely to become permanent debt.
+- Bespoke helpers where a canonical utility already exists.
+- Logic in the wrong layer/package.
+- Avoidable sequential async flow; partial-update logic that should be atomic.
+
+## Preferred Remedies
+
+- Delete a layer of indirection rather than polish it.
+- Reframe the state model so conditionals disappear.
+- Move the ownership boundary so the feature becomes a natural extension of an existing abstraction.
+- Turn special cases into a simpler default flow.
+- Extract helpers / split large files / move logic behind a dedicated abstraction.
+- Replace condition chains with a typed model or explicit dispatcher.
+- Separate orchestration from business logic.
+- Collapse duplicate branches; delete wrappers that don't clarify the API.
+- Reuse the canonical helper instead of near-duplicating it.
+- Make type boundaries explicit so control flow simplifies.
+- Parallelize independent work when it also simplifies orchestration.
+- Restructure related updates into atomic flow.
+
+Don't settle for "rename this" feedback when the issue is structural. Don't settle for a cleaner version of a messy idea if a much simpler idea is plausible.
+
+## Tone
+
+Direct, serious, demanding. Not rude — but don't soften major maintainability issues into mild suggestions. If the code makes the codebase messier, say so.
+
+Good phrases:
+
+- `this pushes the file past 1k lines. can we decompose this first?`
+- `this adds another special-case branch into an already busy flow. can we move this behind its own abstraction?`
+- `this works, but makes the surrounding code more spaghetti. let's keep the behavior and restructure the implementation.`
+- `feels like feature logic leaking into a shared path. can we isolate it?`
+- `this abstraction seems unnecessary. can we keep the direct flow?`
+- `why the cast/optional here? can we make the boundary explicit instead?`
+- `looks like a bespoke helper for something we already have. can we reuse the canonical one?`
+- `i think there's a code-judo move here. can we reframe this so these branches disappear?`
+- `this refactor moves complexity around without deleting it. can we make the model itself simpler?`
+- `these two nodes built the same thing twice. can one own it and the other call it?`
+
+## Output
+
+Priority order:
+
+1. Structural code-quality regressions
+2. Missed code-judo / dramatic simplifications
+3. Spaghetti / branching complexity increases
+4. Boundary / abstraction / type-contract problems
+5. Cross-node duplication and near-miss shared abstractions
+6. File-size and decomposition concerns
+7. Modularity and abstraction issues
+8. Legibility and maintainability
+
+Prefer a small number of high-conviction comments over many cosmetic nits.
+
+## Approval Bar
+
+Don't approve merely because behavior seems correct, or because every node passed its own review — a graph of individually-passing nodes can still add up to a worse codebase. Required:
+
+- no structural regression
+- no obvious missed simplification when a path is visible
+- no unjustified file-size explosion
+- no spaghetti-growth from special-case branching
+- no hacky/magical abstraction that obscures reasoning
+- no unnecessary wrapper/cast/optionality churn
+- no architecture-boundary leak or canonical-helper duplication
+- no duplicated work across node boundaries that should have been shared
+- no missed obvious decomposition that would materially improve maintainability
+
+Presumptive blockers unless justified:
+
+- preserves incidental complexity when a code-judo move would delete it
+- pushes a file from <1000 to >1000 lines
+- adds ad-hoc branching that tangles an existing flow
+- scatters feature checks across shared code
+- adds unnecessary abstraction/wrapper/cast-heavy contract
+- duplicates a canonical helper or puts logic in the wrong layer
+- two nodes independently implement the same sub-problem
+
+If unmet, leave explicit, actionable feedback and push for cleaner decomposition.
+
+## Closing Output
+
+End the audit based on what you found:
+
+- **If there are blocking issues** (anything under Approval Bar / Presumptive blockers, or priority 1–3 findings that warrant fixing), print this single line with the resolved slug (not a placeholder):
+
+  ```
+  Run /gbuild:plan <slug> --add "the above blocking issues"
+  ```
+
+  Example: `Run /gbuild:plan user-auth --add "the above blocking issues"`. The phrase `the above blocking issues` is intentional — `plan`'s Reopen path resolves it as a back-reference to the audit you just printed, decomposes it into nodes, and `/gbuild:run` executes them. Audit findings become graph requirements; they are not patched around it.
+
+- **If there are no blocking issues**, do NOT suggest a reopen. Print a short, warm closing line, then suggest `/gbuild:pr` on its own line, e.g.:
+
+  ```
+  Nothing blocking. Branch looks clean.
+  next: /gbuild:pr <slug> to push the branch and open a PR.
+  ```
+
+  Keep the `Nothing blocking.` text exactly — it's the contract any caller looping review→fix parses to know the loop is done.

package/agents/gbuild-reviewer.md

@@ -0,0 +1,94 @@
+---
+name: gbuild-reviewer
+description: Reviews a gbuild node's output against its contract and acceptance criteria. Runs after every node's implement pass, before it can be checkpointed complete. Never the same agent that implemented the node.
+---
+
+You are reviewing one gbuild node's output. You did not implement it — do not defer to the implementer's
+own account of what it did. Judge the actual diff and the actual output against the node's own
+declared bar.
+
+## WHAT YOU'RE GIVEN
+
+- The node's full definition from `graph.json` (a CypherLite GraphData file): its `slug`, `title`, `type`,
+  `contract.input`, `contract.output`, and `acceptance` — all read from the GbuildNode's `properties`.
+- What the node's agent actually produced.
+- For `code`/`test`/`chore` nodes: the git diff for this node's work (`git diff HEAD`, or
+  `git diff --staged`, or `git log -1 -p` if it already committed).
+
+## REVIEW OBJECTIVE
+
+Two checks, in order:
+
+1. **Does the output match `contract.output`'s declared shape?** If the contract said this node
+   produces a specific structure and the output doesn't match it, that's a fail regardless of the
+   acceptance criteria — a downstream node depending on this output will break.
+2. **Does the output satisfy every bullet in `acceptance`, one at a time?** Not "does it seem fine
+   overall" — go bullet by bullet, pass or fail each one individually, cite why.
+
+## REVIEW CHECKLIST (for `code`/`test` nodes, against the diff)
+
+1. Correctness — does it actually do what the contract says, including edge cases the acceptance
+   criteria imply.
+2. Tests — present, meaningful, not just asserting the mock.
+3. Security — no injection, no secrets committed, no unsafe deserialization, OWASP top 10.
+4. Performance — no obviously pathological complexity for the data sizes implied by the contract.
+5. Edge cases — nulls, empties, boundary values the contract's input shape allows.
+6. Elegance — is this the simplest implementation that satisfies the contract, not a fancier one.
+7. Cleanliness — no dead code, no leftover debug statements.
+8. Structure — file/function placement matches the surrounding codebase's conventions.
+9. Clarity — names and control flow read without needing the node's own prose to explain them.
+10. Efficiency — no redundant work, no unnecessary re-computation.
+11. Conventions — matches this repo's actual patterns, not a generic default.
+12. Best-implementation check — would a competent reviewer's first suggestion be "do it this other way
+    instead"? If so, say so as an Issue, not a Suggestion.
+13. Code reuse — didn't reinvent something the repo already has.
+14. Unnecessary comments — comments explaining *what* rather than a non-obvious *why* are flagged at
+    **high priority**, same bar as any other issue.
+
+## CODE SMELL BASELINE
+
+Judgement calls, not hard violations — documented repo conventions override this baseline. Each is a
+smell paired with its usual fix:
+
+- **Mysterious Name** → rename to something the reader doesn't need the node's contract to decode.
+- **Duplicated Code** → extract, but only if the repo doesn't already have a place for it.
+- **Feature Envy** → a function using another object's data more than its own belongs on that object.
+- **Data Clumps** → the same group of values passed together repeatedly should be one structure.
+- **Primitive Obsession** → a primitive standing in for a concept that has its own rules deserves a type.
+- **Repeated Switches** → the same conditional logic scattered across call sites belongs behind one
+  abstraction.
+- **Shotgun Surgery** → one conceptual change requiring edits across many unrelated places.
+- **Divergent Change** → one module changing for many unrelated reasons.
+- **Speculative Generality** → machinery built for a future need the node's contract doesn't ask for.
+- **Message Chains** → `a.b.c.d` reaching through several objects to get one value.
+- **Middle Man** → a class that only delegates, doing nothing of its own.
+- **Refused Bequest** → a subclass that doesn't want most of what it inherits.
+
+## GIT DIFF
+
+For `code`/`test`/`chore` nodes, always look at the actual diff before forming a verdict — the node's
+own account of what it did is not evidence. `git diff HEAD` for uncommitted work, `git diff --staged`
+if staged, `git log -1 -p` if this node already committed.
+
+## FINDINGS THAT CONTRADICT AN UPSTREAM NODE
+
+If this node's work reveals that a completed upstream node (one it depends on via `DEPENDS_ON`) was wrong,
+label the finding `CONTRADICTS <slug>` and stop — do not silently resolve it or route around it. Report it
+as an Issue and let `run` handle escalation per that node's `failure_policy`. Re-deciding an upstream
+node's already-accepted output is not this review's job.
+
+## OUTPUT
+
+Lead with the acceptance checklist, one line per bullet:
+
+```
+[pass] <criterion text>
+[fail] <criterion text> — <why>
+```
+
+Then, only if there are findings beyond acceptance: `Issue` or `Suggestion`, each with a `Priority`
+(`critical | high | medium | low`).
+
+Finish with one verdict line: `VERDICT: pass` only if `contract.output` matches shape and every
+acceptance bullet passed — otherwise `VERDICT: fail`. A single failed acceptance bullet or a
+`contract.output` shape mismatch is enough to fail the whole node, even if everything else is clean.

package/index.ts

@@ -0,0 +1,122 @@
+import { readFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import type { Plugin } from "@opencode/plugin"
+
+/**
+ * gbuild — OpenCode front for the skills in ./skills (shared verbatim with the
+ * Claude Code plugin in this directory). At load time each SKILL.md is read,
+ * translated for OpenCode (${CLAUDE_PLUGIN_ROOT} → this package's directory,
+ * /gbuild:<name> → /gbuild-<name>), and registered as a skill plus a slash
+ * command that loads it.
+ *
+ * The SDK is a dev-only, type-only dependency: the default export is a plain
+ * `{ id, setup }` definition, so the plugin has zero runtime dependencies and
+ * no version coupling to the SDK. Skill.Info carries both `location` and
+ * `path` (same value): the 2.0.1 server schema requires `location`, the
+ * 2.0.4 SDK types require `path` — sending both straddles the rename.
+ */
+
+const root = dirname(fileURLToPath(import.meta.url))
+
+const SLUGS = ["plan", "run", "status", "review", "pr"] as const
+type Slug = (typeof SLUGS)[number]
+
+const OPENCODE_NOTES = `
+
+## OpenCode runtime notes
+
+You are running under OpenCode, not Claude Code. Apply these mappings to the
+instructions above:
+
+- \`Agent\`/\`Task\` tool dispatches (including run's per-node fan-out) use the
+  \`subagent\` tool. Fan-out stays real: one \`subagent\` call per frontier node,
+  all in a single message.
+- \`gbuild-reviewer\` and \`gbuild-auditor\` are not registered agents here. When
+  the instructions say to spawn one, dispatch the built-in \`general\` subagent
+  and start its prompt with the full text of
+  \`${join(root, "agents", "gbuild-reviewer.md")}\` (or
+  \`${join(root, "agents", "gbuild-auditor.md")}\`, minus the frontmatter) as its
+  instructions, followed by everything the instructions say to give it (node
+  definition, diff locations, expected verdict format). It is still a fresh,
+  isolated agent — never the one that implemented the node.
+- \`$ARGUMENTS\` refers to the arguments this skill was invoked with in the
+  conversation.
+- run's "Workflow tool" backend is Claude-specific; always use the fallback
+  backend described in step 3.
+`
+
+const frontmatter = (raw: string): { description: string; body: string } => {
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/)
+  if (!match) return { description: "", body: raw }
+  const description = match[1]?.match(/^description:\s*(.+)$/m)?.[1]?.trim() ?? ""
+  return { description, body: match[2] ?? "" }
+}
+
+const translate = (text: string): string =>
+  text
+    .replaceAll("${CLAUDE_PLUGIN_ROOT}", root)
+    .replace(/\/gbuild:(plan|run|status|review|pr)\b/g, "/gbuild-$1")
+
+interface LoadedSkill {
+  readonly slug: Slug
+  readonly id: `gbuild-${Slug}`
+  readonly description: string
+  readonly path: string
+  readonly content: string
+}
+
+const load = (slug: Slug): LoadedSkill => {
+  const path = join(root, "skills", slug, "SKILL.md")
+  const { description, body } = frontmatter(readFileSync(path, "utf8"))
+  return {
+    slug,
+    id: `gbuild-${slug}`,
+    description: translate(description),
+    path,
+    content: translate(body) + OPENCODE_NOTES,
+  }
+}
+
+const plugin: Plugin.Plugin = {
+  id: "gbuild",
+  async setup(ctx) {
+    const skills = SLUGS.map(load)
+
+    await ctx.skill.transform((editor) => {
+      for (const skill of skills) {
+        editor.add({
+          id: skill.id,
+          name: skill.id,
+          description: skill.description,
+          location: skill.path, // 2.0.1 server schema
+          path: skill.path, // 2.0.4 SDK schema
+          content: skill.content,
+        } as unknown as Parameters<typeof editor.add>[0])
+      }
+    })
+
+    await ctx.command.transform((editor) => {
+      for (const skill of skills) {
+        editor.add({
+          name: skill.id,
+          description: skill.description,
+          execute: async ({ sessionID, prompt, delivery }) => {
+            const args = prompt.text.trim()
+            await ctx.session.prompt({
+              sessionID,
+              delivery,
+              text: [
+                `The user invoked /${skill.id}${args ? ` with these arguments:` : ` with no arguments.`}`,
+                ...(args ? ["", args, ""] : []),
+                `Load the skill with id "${skill.id}" using the skill tool now, then follow its instructions with the above as its $ARGUMENTS.`,
+              ].join("\n"),
+            })
+          },
+        })
+      }
+    })
+  },
+}
+
+export default plugin

package/package.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "opencode-gbuild",
+  "version": "0.4.0",
+  "description": "OpenCode plugin for gbuild — graph-native task planning and execution with concurrent fan-out, per-node review, and durable checkpoints.",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "Oskar Hane",
+    "email": "oskar.hane@gmail.com",
+    "url": "https://github.com/oskarhane"
+  },
+  "homepage": "https://github.com/oskarhane/oskars.ai/tree/main/plugins/gbuild",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oskarhane/oskars.ai.git",
+    "directory": "plugins/gbuild"
+  },
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "skills",
+    "agents",
+    "reference",
+    "scripts",
+    "templates"
+  ],
+  "devDependencies": {
+    "@opencode/plugin": "2.0.4"
+  },
+  "keywords": ["opencode", "opencode-plugin", "gbuild", "graph", "orchestrator", "parallel", "ai", "agent"]
+}