opencode-gbuild 0.9.1 → 0.10.0

package/README.md

@@ -1,18 +1,21 @@
 # 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.
+Graph-native task planning and execution: design a feature with the human, plan it 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:
+Design the feature first — `/gbuild:design` when the work needs shaping before it can be charted,
+conversation (your agent's normal plan mode) when it doesn't — then hand it to gbuild:
 
-1. `/gbuild:plan <the plan>` — chart it as a dependency graph
-2. `/gbuild:run <slug>` — run it, once; it starts each node the moment its dependencies complete, 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>`
+1. `/gbuild:design <the feature>` — shape it with the human into committed design artifacts (`docs/design/<slug>/`) on the feature branch in its own worktree; it ends only when you call the design good, and re-invoking with the slug resumes from the commits
+2. `/gbuild:plan <the plan>` — chart it as a dependency graph
+3. `/gbuild:run <slug>` — run it, once; it starts each node the moment its dependencies complete, until the graph completes (re-invoke only to resume an interrupted run)
+4. `/gbuild:review <slug>` — audit the accumulated branch
+5. Issues? `/gbuild:plan <slug> --add "<fix>"`, then `/gbuild:run` again. Clean? `/gbuild:pr <slug>`
 
-The feature branch lives in its own git worktree (created by `plan`) — your checkout never changes
+The feature branch lives in its own git worktree (created by `design` or `plan`) — your checkout never changes
 branches, your uncommitted work is never in the way, and several features can be in flight in parallel
 without racing each other's `HEAD`.
 
@@ -45,9 +48,9 @@ claude --plugin-dir ./plugins/gbuild
 ### OpenCode
 
 The same directory is also an OpenCode (V2) plugin, published to npm as
-[`opencode-gbuild`](https://www.npmjs.com/package/opencode-gbuild) — `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.
+[`opencode-gbuild`](https://www.npmjs.com/package/opencode-gbuild) — `index.ts` registers the six
+skills and six slash commands (`/gbuild-design`, `/gbuild-plan`, `/gbuild-run`, `/gbuild-status`,
+`/gbuild-review`, `/gbuild-pr`) from the same markdown the Claude plugin uses.
 
 ```bash
 opencode plugin add opencode-gbuild
@@ -83,6 +86,7 @@ prompt. The review is still a fresh, isolated agent — never the implementer.
 Claude Code:
 
 ```
+/gbuild:design add OAuth login with GitHub
 /gbuild:plan add OAuth login with GitHub
 /gbuild:run add-oauth-login-with-github
 /gbuild:status add-oauth-login-with-github
@@ -93,6 +97,7 @@ Claude Code:
 OpenCode (same order, kebab-case names):
 
 ```
+/gbuild-design add OAuth login with GitHub
 /gbuild-plan add OAuth login with GitHub
 /gbuild-run add-oauth-login-with-github
 /gbuild-status add-oauth-login-with-github
@@ -100,7 +105,17 @@ OpenCode (same order, kebab-case names):
 /gbuild-pr add-oauth-login-with-github
 ```
 
-- **`plan`** creates the feature branch in its own git worktree and charts the feature into a
+- **`design`** shapes a feature with the human before `plan` charts it — for when the destination
+  still has options, the moving parts aren't named, or the trade-offs are unmade. It analyses the
+  codebase, drives the discussion in batched question rounds (the destination first, one line), and
+  commits each settled piece to `docs/design/<slug>/` on the feature branch in its own worktree —
+  `design.md` carries the destination, scope, decisions with their ruled-out alternatives, and the
+  open questions. It ends only when the human calls the design good — never on its own judgement —
+  writes no implementation (unknowns that need code become open questions for `plan` to chart as
+  `research` nodes), and runs without `cypherlite` or a store; re-invoking with the slug resumes
+  from the committed artifacts.
+- **`plan`** creates the feature branch in its own worktree (reusing the one `design` left, when
+  there is one) and charts the feature into a
   machine-local CypherLite graph store (`<git-common-dir>/gbuild/<feature>/db`) — `Feature`,
   `Acceptance`, and `GbuildNode` nodes, each node's contract as `INPUT`/`OUTPUT` `Field` nodes, and
   `FROM` edges carrying data from one node's output to the next node's input. Every dependency edge
@@ -263,7 +278,7 @@ plugins/gbuild/
   reference/                  # graph-format.md (normative model), cypher.md (how to talk to the store), queries.md (ad-hoc recipes); shapes/failure-policies/cost-model/checklist inform plan
   cypher/                     # schema, validate, progress/attention/status/node/feature reads, run's dispatch/record/set-status, and brief/check-result/symbols for its agents
   templates/example.cypher    # a worked 4-node diamond, written the way plan writes a feature
-  skills/{plan,run,status,review,pr}/
+  skills/{design,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")
   cypher.test.ts              # node --test contract tests for the Cypher layer (repo-root `npm test`)
@@ -276,7 +291,7 @@ It holds the plan, every node's status and output values, the full review histor
 reviewer's checklist), and the notes and symbols agents left; CypherLite checkpoints the store on exit,
 so `db/graph.json` is just the engine's local snapshot. All of a feature's worktrees live under
 `.git/gbuild/<feature>/` — never in `git status`: `tree/` is the feature worktree itself, created by
-`plan` and kept until the feature is done, and during a run each file-touching node gets a `<node>/`
+`design` or `plan` and kept until the feature is done, and during a run each file-touching node gets a `<node>/`
 worktree that is removed the moment its node is accepted (merged into the feature branch, in `tree/`)
 or terminally failed (discarded). Beside them, `inbox/` holds the run's hand-off files (`<slug>.json`,
 `<slug>.review.json`), emptied when a run starts and cleared for each node once it is recorded.

package/index.ts

@@ -19,7 +19,7 @@ import type { Plugin } from "@opencode/plugin"
 
 const root = dirname(fileURLToPath(import.meta.url))
 
-const SLUGS = ["plan", "run", "status", "review", "pr"] as const
+const SLUGS = ["design", "plan", "run", "status", "review", "pr"] as const
 type Slug = (typeof SLUGS)[number]
 
 const OPENCODE_NOTES = `
@@ -61,10 +61,15 @@ const frontmatter = (raw: string): { description: string; body: string } => {
   return { description, body: match[2] ?? "" }
 }
 
+// `/gbuild:<slug>` → `/gbuild-<slug>`, derived from SLUGS so the alternation
+// can never drift from the registered skills (a "/" needs no escaping in the
+// string form a RegExp constructor takes).
+const SLUG_REF_RE = new RegExp(`/gbuild:(${SLUGS.join("|")})\\b`, "g")
+
 const translate = (text: string): string =>
   text
     .replaceAll("${CLAUDE_PLUGIN_ROOT}", root)
-    .replace(/\/gbuild:(plan|run|status|review|pr)\b/g, "/gbuild-$1")
+    .replace(SLUG_REF_RE, "/gbuild-$1")
 
 interface LoadedSkill {
   readonly slug: Slug

package/package.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-gbuild",
-  "version": "0.9.1",
-  "description": "OpenCode plugin for gbuild — graph-native task planning and execution with concurrent fan-out, per-node review, and durable checkpoints.",
+  "version": "0.10.0",
+  "description": "OpenCode plugin for gbuild — design a feature with the human, plan it as a dependency graph, run it with concurrent fan-out, per-node review, and durable checkpoints.",
   "type": "module",
   "license": "MIT",
   "author": {

package/skills/design/SKILL.md

@@ -0,0 +1,125 @@
+---
+description: Designs a feature with the human — the design step before /gbuild:plan charts it: analyses the codebase, drives the discussion in batched question rounds, and commits the design artifacts (docs/design/<slug>/, entry doc design.md) to the feature branch in its own git worktree, never touching the main checkout. Ends only when the human calls the design good; re-invoking with the slug resumes from the committed artifacts. Runs without cypherlite and without a store — use when the work needs shaping before it can be charted.
+---
+
+Design the feature described by `$ARGUMENTS` — with the human, before `/gbuild:plan` charts it.
+
+`plan` decomposes a feature that already makes sense: a one-line destination, a scope with edges,
+constraints it can verify against. When the work isn't there yet — the destination still has
+options, the moving parts aren't named, the trade-offs are unmade — this skill shapes it into
+committed artifacts first. It writes the design onto the feature branch and stops: no graph, no
+store, no implementation. The committed artifacts are the design's whole state, so re-invoking
+`/gbuild:design <slug>` resumes exactly where the commits left off. After it, `/gbuild:plan <slug>`
+has a design to decompose instead of a guess.
+
+## Mode
+
+| arguments                                                 | mode                                                |
+| --------------------------------------------------------- | --------------------------------------------------- |
+| a description, link, or file path                         | **Design** — new feature                            |
+| a slug with a feature worktree or branch, and no store    | **Resume** — continue the committed artifacts      |
+| a slug whose store already exists                         | **Redirect** — `/gbuild:plan <slug> --add "<req>"`  |
+
+`$ARGUMENTS` is slug-shaped only if it is one kebab-case token. Then, in order: a store at
+`<git-common-dir>/gbuild/<slug>/db` (its `graph.json` present) means `plan` already charted the
+feature — don't design a charted feature; say so and point at `/gbuild:plan <slug> --add
+"<requirement>"`, which is how a charted feature takes new work. A feature worktree or a branch
+named `<slug>` or ending `/<slug>`, with no store, means a design started here and wasn't charted —
+resume it. Anything else is a description — design it.
+
+## Design
+
+### 1. Slug, branch, and feature worktree
+
+Derive the feature slug from `$ARGUMENTS`: kebab-case, ≤4 words, names the outcome not the mechanism
+(`oauth-device-flow`, not `add-some-auth-stuff`). It names the artifact home below and the
+`gbuild/<slug>/` directory `plan` later creates — immutable once the design is committed.
+
+If the derived slug's store already exists (`<git-common-dir>/gbuild/<slug>/db`), stop: the feature
+is charted, and new work goes to `/gbuild:plan <slug> --add`. Resolve `FT` (the feature worktree)
+exactly as `/gbuild:plan`'s Chart step 1 describes (`${CLAUDE_PLUGIN_ROOT}/skills/plan/SKILL.md`) —
+reuse the registered worktree, attach a branch checked out nowhere, or create branch and worktree
+forked from the current HEAD. Report the branch and `FT`; everything below happens in `FT`. If
+`docs/design/<slug>/` on that branch already has committed artifacts, this is a resume that arrived
+as a description — read them (Resume below) instead of writing over them.
+
+### 2. Analyse the codebase
+
+Read the project manifest(s), directory structure, `README.md`, and the code the feature touches.
+Resolve file paths or URLs in `$ARGUMENTS`; if a reference fails to load, say so and ask. For
+related in-flight work — best-effort, never required: when `cypherlite` is on PATH, read the
+`Feature` of every existing store (`feature.cypher` with `--read-only` against each
+`<git-common-dir>/gbuild/*/db`, one at a time); when it isn't, skip — this skill needs neither
+`cypherlite` nor a store, and never installs or creates either.
+
+### 3. Fix the artifact home
+
+The design artifacts live at `docs/design/<slug>/` on the feature branch; the entry doc is
+`design.md`, and everything else hangs off it. Before writing anything, look at how the repo already
+documents work — `docs/` layout, ADR or decision-record folders, README patterns — and follow an
+existing convention when one is present: supporting docs take the repo's naming and format; only
+the home and the entry doc are fixed here.
+
+### 4. The design loop
+
+The design is written by discussing it, one settled piece at a time. The loop runs until the human
+calls the design good — never less, and never on your own judgement of when it's good enough.
+
+1. **Open with what the analysis found.** A few lines: the pieces that exist, the gap, the
+   constraints — grounding, not a report. End with the first batch of questions.
+2. **Ask in batches.** Put the round's open questions to the human in one message — cap at ~5. The
+   destination comes first, and it must end up one line, the thing that is true once this is done;
+   everything past it is scope to defend or cut. Then what the destination needs decided: scope
+   edges, naming, the trade-offs with real alternatives, the risks worth stating. Never one question
+   at a time, and never 20 questions — a round with more than ~5 open questions hasn't converged:
+   settle what the last answers gave you, and batch the rest into the next round.
+3. **Settle as they solidify.** Fold each round's answers into the artifacts the moment they're
+   agreed, and commit — message `docs(design/<slug>): <what settled>` — so an interruption costs
+   nothing that had settled. `design.md` carries the state: the destination (one line), the scope
+   and out-of-scope, what the analysis found, each decision with its rationale and the alternatives
+   it ruled out, and the open questions still in play. Supporting docs — whatever this design
+   needs: diagrams, data shapes, interface sketches — follow the repo's convention (step 3).
+4. **An unknown that needs code is an open question, not a prototype.** Design writes no
+   implementation — no scaffolding, no probes, no spike branches. A question the analysis can't
+   answer by reading goes into `design.md`'s open questions for `/gbuild:plan` to chart as a
+   `research` node.
+
+### 5. Report and hand over
+
+Only after the human has called the design good: ask nothing more, write and commit the last of it,
+then report the artifacts (every file under `docs/design/<slug>/`), the branch, and `FT`. The feature
+worktree stays — `plan` reuses it. Then both exits, the human's to pick:
+
+- **Continue into gbuild** — `next: /gbuild:plan <slug>`.
+- **A design review on a PR** — ask the agent to open it directly with `gh` from `FT` (push the
+  branch, `gh pr create`): `/gbuild:pr` can't, it needs a graph store, and a design isn't charted.
+
+## Resume
+
+Re-invoking `/gbuild:design <slug>` continues a design the feature worktree or branch already holds —
+the mode table routed you here:
+
+0. Resolve `FT` exactly as step 1 describes — reuse the registered worktree, attach the branch if
+   it's checked out nowhere. Never into the user's main checkout unless that's where the feature
+   branch already lives (a legacy feature).
+1. Read the committed artifacts at `docs/design/<slug>/` in `FT`. `design.md` says what's decided
+   and what's open; the commit log says what settled when. Anything the loop left uncommitted never
+   settled — start that piece over.
+2. Continue the loop (step 4) from the open questions. A settled decision reopens only on new
+   information, said out loud — not on a fresh context's second thoughts.
+
+## Rules
+
+- **Design, don't build.** Nothing lands on the branch but the artifacts under
+  `docs/design/<slug>/` — no implementation, no scaffolding, no probes. Unknowns that need code
+  become open questions for `plan` to chart as `research` nodes.
+- **The human closes the design.** The loop ends on the human calling it good, never on your own
+  judgement; the closing report follows that word and nothing before it.
+- **Commit as work solidifies.** Everything agreed is written and committed in the round it was
+  agreed in — the branch is the state, there is no store, and an interrupted design must resume
+  having lost nothing that had settled.
+- **No cypherlite, no store.** This skill runs without either and never installs or creates
+  either: a store's existence only routes the mode, and sibling stores are read best-effort
+  (step 2), only when `cypherlite` is already on PATH.
+- **The user's checkout never changes branch.** Every edit, commit, and check happens in `FT`; the
+  main tree is never touched.

package/skills/plan/SKILL.md

@@ -6,10 +6,11 @@ Plan the work described in `$ARGUMENTS` as a graph.
 
 ## The loop
 
-The intended workflow: plan in ordinary conversation first, then chart that plan here. After this
-skill: `/gbuild:run <slug>` once — it starts each node as its dependencies complete, until the graph
-completes. Then `/gbuild:review <slug>`; if it finds issues, reopen with
-`/gbuild:plan <slug> --add "<fix>"` and `/gbuild:run` again; if clean, `/gbuild:pr <slug>`.
+The intended workflow: `/gbuild:design <slug>` when the work needs shaping, ordinary conversation
+when it doesn't, then chart it here. After this skill: `/gbuild:run <slug>` once — it starts each
+node as its dependencies complete, until the graph completes. Then `/gbuild:review <slug>`; if it
+finds issues, reopen with `/gbuild:plan <slug> --add "<fix>"` and `/gbuild:run` again; if clean,
+`/gbuild:pr <slug>`.
 
 Read `${CLAUDE_PLUGIN_ROOT}/reference/graph-format.md` (the normative graph model) and
 `${CLAUDE_PLUGIN_ROOT}/reference/cypher.md` (how to talk to the store) before doing anything, and run
@@ -63,7 +64,13 @@ Report the branch and `FT`. Everything below happens in `FT`; `DB` below is `WT/
 Read the project manifest(s), directory structure, `README.md`, and — for related in-flight work — the
 `Feature` of every existing store (`feature.cypher` with `--read-only` against each `GC/gbuild/*/db`,
 one at a time). Resolve
-file paths or URLs in `$ARGUMENTS`; if a reference fails to load, say so and ask.
+file paths or URLs in `$ARGUMENTS`; if a reference fails to load, say so and ask. When `FT` holds the
+feature's design artifacts — committed by `/gbuild:design` at `docs/design/<slug>/`, entry doc
+`design.md`, everything else hanging off it — read all of them first: they are the design context the
+graph is charted from; its settled decisions are facts to decompose, not questions to reopen. When
+no design is at `docs/design/<slug>/` in `FT`, check `docs/design/*` in `FT` before charting
+fresh: a re-described feature — the same work, described again under a different slug — still
+finds its committed design that way, and it is read exactly as above.
 
 ### 3. Validate and explore