@gevezex/gdt 0.2.0 → 0.4.0

package/README.md

@@ -121,8 +121,24 @@ evidence too.
 | Node 24 LTS | runs gdt |
 | `git` | the shared checkout the roles work in |
 | `gh`, logged in (`gh auth login`) | issues, pull requests, comments, checks |
-| at least one agent CLI | `claude`, `codex`, `opencode`, `mcode`, `pi` or `omp` |
-| [herdr](https://herdr.dev) 0.9.1+ (optional) | watch the roles live; otherwise use `terminal = "headless"` |
+| at least one agent CLI | `claude`, `codex`, `opencode`, `mcode`, `pi` or `omp` (see below) |
+| [herdr](https://herdr.dev) 0.9.1+ | the default way to watch the roles live, one tab per role; on machines without herdr set `workflow.terminal = "headless"` |
+
+### Agent prerequisites
+
+Before the first `gdt start`, every agent CLI you name in the user config
+(`~/.config/gdt/config.toml`) must already work on your machine with the exact
+model id you set there. For each role:
+
+1. install the agent CLI,
+2. log in or configure its API key or subscription,
+3. run it once successfully with the model id from `roles.<role>.model` (for
+   example `opencode/deepseek/deepseek-v4-flash`).
+
+gdt runs the agent CLI as is, so the agent uses its own login, tokens and
+credits. gdt stores no credentials and does not log in, choose a plan, or track
+token use or costs. `gdt doctor` only checks that the CLI is on `PATH`, not that
+its login, API key or model works.
 
 ## Install
 
@@ -156,28 +172,25 @@ It copies `skill/SKILL.md` into the skill directory of every agent CLI it finds
 
 ### 1. Configure the target repository
 
-In the repository you want gdt to work on, commit `.gdt/config.toml`:
-
-```toml
-language = "en"                  # language for issue and PR text: "en" or "nl"
-
-[roles.developer]
-agent = "opencode"
-model = "deepseek/deepseek-v4-flash"
+In the repository you want gdt to work on, create `.gdt/config.toml` with
+`gdt init` instead of writing TOML by hand. Ask your coding agent, or run it
+yourself:
 
-[roles.tester]
-agent = "claude"
-model = "claude-sonnet-5"
-
-[roles.reviewer]
-agent = "codex"
-model = "gpt-5.6-luna"
-
-[workflow]
-required_checks = ["test"]       # CI check names that must be green
-terminal = "herdr"               # or "headless"
+```bash
+gdt init --developer opencode/deepseek/deepseek-v4-flash \
+         --tester claude/claude-sonnet-5 \
+         --reviewer codex/gpt-5.6-luna
 ```
 
+`gdt init` writes the roles to your user config (`~/.config/gdt/config.toml`,
+or `$XDG_CONFIG_HOME/gdt/config.toml`), writes the project settings to
+`.gdt/config.toml`, runs `gdt doctor` and installs the operator skill. Without the
+three role options, it reuses the roles from your user config when they are all
+there; otherwise it only reports what it found (agents on `PATH`, the terminal,
+the detected CI checks) so your agent can discuss the roles with you first. It
+never overwrites an existing config without `--force`, and it requires at least
+one required check unless you pass `--allow-no-required-checks`.
+
 Then check your setup:
 
 ```bash
@@ -292,6 +305,7 @@ Every command supports `--help`; `status` and `wait` also support `--json`.
 
 | Command | Effect |
 |---|---|
+| `gdt init` | Write the roles to the user config and `.gdt/config.toml`, install the operator skill |
 | `gdt doctor` | Check tools, GitHub login, agents, herdr and `.gdt/config.toml` |
 | `gdt check-issue <n>` | Validate an issue body against the contract |
 | `gdt start <n>` | Preflight, start the supervisor and workers, return |
@@ -308,22 +322,55 @@ Every command supports `--help`; `status` and `wait` also support `--json`.
 
 ## Configuration
 
-`.gdt/config.toml` is committed; `.gdt/config.local.toml` holds machine-local
-overrides (for example another model) and is not committed.
+Roles belong to a person, not to a repository, so gdt keeps them in a per-user
+config. gdt loads three files and merges them in this order, with the later file
+winning per key:
+
+1. the **user config** — `$XDG_CONFIG_HOME/gdt/config.toml`, or
+   `~/.config/gdt/config.toml` when `XDG_CONFIG_HOME` is not set. It holds only
+   `[roles.*]`. A relative `XDG_CONFIG_HOME` is ignored.
+2. the **repository config** — `.gdt/config.toml`, committed. It holds the project
+   settings and must not contain `[roles.*]`.
+3. the **local config** — `.gdt/config.local.toml`, never committed. It overrides
+   any key, for example one role's model on this machine.
+
+`gdt init` writes the roles to the user config and the project settings to
+`.gdt/config.toml`. Ready-made files are in [`examples/`](examples/):
+[`examples/user-config.toml`](examples/user-config.toml),
+[`examples/config.toml`](examples/config.toml) and
+[`examples/config.local.toml`](examples/config.local.toml).
+
+| Key | File | Default | Meaning |
+|---|---|---|---|
+| `roles.<role>.agent` | user | required | `claude`, `codex`, `opencode`, `mcode`, `pi` or `omp` |
+| `roles.<role>.model` | user | required | Model id for that agent |
+| `language` | repository | `"en"` | Language of issue and PR text (`en`, `nl`) |
+| `workflow.required_checks` | repository | required | CI checks that must be green before `ready_to_merge` |
+| `workflow.allow_no_required_checks` | repository | `false` | Allow an empty `required_checks` list |
+| `workflow.max_correction_rounds` | repository | `2` | Correction rounds after round 0 |
+| `workflow.terminal` | repository | `"herdr"` | `"herdr"` or `"headless"` |
+| `workflow.supervisor_pane` | repository | `false` | herdr: also show the supervisor in a pane |
+| `workflow.herdr_layout` | repository | `tabs` | herdr: `"tabs"` (one tab per pane) or `"split"` (panes side by side in one tab) |
+| `workflow.poll_seconds` | repository | `30` | How often the supervisor reads GitHub |
+| `contract.max_acceptance_criteria` | repository | `8` | Maximum number of ACs per issue |
+| `contract.extra_rules` | repository | none | File with project rules added to every role prompt |
+
+### Per-role rules
+
+Each workflow role can have supplementary rules of its own, in the target repository:
+
+| File | Role |
+|---|---|
+| `.gdt/roles/developer.md` | developer |
+| `.gdt/roles/tester.md` | tester |
+| `.gdt/roles/reviewer.md` | reviewer |
 
-| Key | Default | Meaning |
-|---|---|---|
-| `language` | `"en"` | Language of issue and PR text (`en`, `nl`) |
-| `roles.<role>.agent` | required | `claude`, `codex`, `opencode`, `mcode`, `pi` or `omp` |
-| `roles.<role>.model` | required | Model id for that agent |
-| `workflow.required_checks` | required | CI checks that must be green before `ready_to_merge` |
-| `workflow.allow_no_required_checks` | `false` | Allow an empty `required_checks` list |
-| `workflow.max_correction_rounds` | `2` | Correction rounds after round 0 |
-| `workflow.terminal` | `"herdr"` | `"herdr"` or `"headless"` |
-| `workflow.supervisor_pane` | `false` | herdr: also show the supervisor in a pane |
-| `workflow.poll_seconds` | `30` | How often the supervisor reads GitHub |
-| `contract.max_acceptance_criteria` | `8` | Maximum number of ACs per issue |
-| `contract.extra_rules` | none | File with project rules added to every role prompt |
+When a file has content, gdt appends it to that role's prompt on every turn under a
+`## Role rules` heading, after `## Project rules` when `contract.extra_rules` sets one.
+An empty or missing file adds nothing and is not an error. This only adds: gdt's own role
+files in the package are never replaced, so the protocol stays intact. `gdt init` creates
+the three files empty so you can see where your rules go; commit them like
+`.gdt/config.toml`.
 
 How each agent CLI is invoked is documented in [docs/agents.md](docs/agents.md).
 
@@ -331,11 +378,12 @@ How each agent CLI is invoked is documented in [docs/agents.md](docs/agents.md).
 
 ```text
  herdr workspace "gdt-251"                        headless
- ┌──────────────┬──────────────┬──────────────┐
- │ developer ·  │ tester ·     │ reviewer ·   │   detached processes,
- │ opencode ·   │ claude ·     │ codex ·      │   one log file each in
- │ RUNNING      │ WAITING      │ WAITING      │   .git/gdt/issue-251/logs/
- └──────────────┴──────────────┴──────────────┘
+ ┌────────────┐ ┌────────────┐ ┌────────────┐
+ │ developer  │ │ tester     │ │ reviewer   │   detached processes,
+ │ opencode · │ │ claude ·   │ │ codex ·    │   one log file each in
+ │ RUNNING    │ │ WAITING    │ │ WAITING    │   .git/gdt/issue-251/logs/
+ └────────────┘ └────────────┘ └────────────┘
+   one tab per role, labelled developer, tester and reviewer
    supervisor runs detached → logs/supervisor.log
 ```
 

package/dist/agents/claude.js

@@ -3,6 +3,8 @@ export const claude = {
     binary: "claude",
     title: "Claude Code",
     install: "Install Claude Code: https://docs.anthropic.com/en/docs/claude-code",
+    modelFormat: "<model>",
+    modelExample: "claude-sonnet-5",
     buildInvocation: (_role, model, promptFile) => ({
         argv: ["claude", "-p", "--model", model, "--permission-mode", "bypassPermissions", "--no-session-persistence"],
         env: {},

package/dist/agents/codex.js

@@ -3,6 +3,8 @@ export const codex = {
     binary: "codex",
     title: "Codex",
     install: "Install Codex: npm i -g @openai/codex",
+    modelFormat: "<model>",
+    modelExample: "gpt-5.6-luna",
     buildInvocation: (_role, model, promptFile, cwd) => ({
         argv: ["codex", "exec", "--model", model, "--cd", cwd, "--dangerously-bypass-approvals-and-sandbox", "--ephemeral", "-"],
         env: {},

package/dist/agents/mcode.js

@@ -4,6 +4,8 @@ export const mcode = {
     binary: "mcode",
     title: "MCode",
     install: "Install MiniMax Code: npm i -g @minimax-ai/code",
+    modelFormat: "provider/model",
+    modelExample: "minimax/MiniMax-M3",
     buildInvocation: (_role, model, promptFile, cwd) => ({
         argv: ["mcode", "exec", "--model", model, "--cwd", cwd, "--permission", "full", "--input", "-"],
         env: {},

package/dist/agents/omp.js

@@ -4,6 +4,8 @@ export const omp = {
     binary: "omp",
     title: "omp",
     install: "Install omp: https://omp.sh",
+    modelFormat: "provider/id",
+    modelExample: "openai/gpt-5.2",
     buildInvocation: (_role, model, promptFile) => ({
         argv: ["omp", "--print", "--model", model, "--no-session", "--auto-approve"],
         env: {},

package/dist/agents/opencode.js

@@ -5,6 +5,8 @@ export const opencode = {
     binary: "opencode",
     title: "OpenCode",
     install: "Install OpenCode: https://opencode.ai",
+    modelFormat: "provider/model",
+    modelExample: "deepseek/deepseek-v4-flash",
     buildInvocation: (_role, model, promptFile) => ({
         argv: ["opencode", "run", "--model", model, "--auto", "--file", promptFile, OPENCODE_MESSAGE],
         env: {},

package/dist/agents/pi.js

@@ -4,6 +4,8 @@ export const pi = {
     binary: "pi",
     title: "pi",
     install: "Install pi: npm i -g --ignore-scripts @earendil-works/pi-coding-agent",
+    modelFormat: "provider/id",
+    modelExample: "anthropic/claude-sonnet-4",
     buildInvocation: (_role, model, promptFile) => ({
         argv: ["pi", "--print", "--model", model, "--no-session", "--no-approve"],
         env: {},

package/dist/backends/headless.js

@@ -37,6 +37,9 @@ export function headless(logs, cwd, env) {
         setTitle: () => {
             // Headless panes have no title.
         },
+        setDisplayAgent: () => {
+            // Headless panes have no agents overview.
+        },
         reportState: () => {
             // AC-7: headless mode reports no agent state.
         },

package/dist/backends/herdr.js

@@ -45,6 +45,19 @@ function reportAgent(opts, paneId, label, state) {
         throw new Error(`herdr pane report-agent: ${reason}`);
     }
 }
+/**
+ * AC-1: sets the display-only agent label of a pane. herdr 0.9.1 requires the pane id before the
+ * options here (`herdr pane report-metadata <pane> --source gdt --display-agent <label>`); with the
+ * options first it exits 2 with `unknown option: gdt`.
+ */
+function reportDisplayAgent(opts, paneId, label) {
+    const args = ["pane", "report-metadata", paneId, "--source", "gdt", "--display-agent", label];
+    const result = spawnSync(bin(opts.env), args, { cwd: opts.root, env: opts.env, encoding: "utf8" });
+    if (result.status !== 0) {
+        const reason = (result.stderr ?? "").trim() || (result.stdout ?? "").trim() || `herdr exited with ${result.status ?? result.signal}`;
+        throw new Error(`herdr pane report-metadata: ${reason}`);
+    }
+}
 /** Parses the `{ "result": ... }` envelope; a herdr `error` becomes a thrown Error. */
 function resultOf(out, command) {
     let data;
@@ -69,12 +82,59 @@ function workspaceList(opts) {
         return [];
     return list.filter((w) => isRecord(w) && typeof w.workspace_id === "string");
 }
-function paneIds(opts, workspaceId) {
+/** `pane list --workspace`, with the tab each pane currently lives in. */
+function paneLocations(opts, workspaceId) {
     const result = resultOf(call(["pane", "list", "--workspace", workspaceId], opts), "pane list");
     const list = result.panes;
     if (!Array.isArray(list))
         return [];
-    return list.flatMap((p) => (isRecord(p) && typeof p.pane_id === "string" ? [p.pane_id] : []));
+    return list.flatMap((p) => isRecord(p) && typeof p.pane_id === "string"
+        ? [{ pane_id: p.pane_id, ...(typeof p.tab_id === "string" ? { tab_id: p.tab_id } : {}) }]
+        : []);
+}
+/** `tab list --workspace`, in herdr's order. */
+function tabLocations(opts, workspaceId) {
+    const result = resultOf(call(["tab", "list", "--workspace", workspaceId], opts), "tab list");
+    const list = result.tabs;
+    if (!Array.isArray(list))
+        return [];
+    return list.flatMap((tab) => isRecord(tab) && typeof tab.tab_id === "string"
+        ? [
+            {
+                tab_id: tab.tab_id,
+                label: typeof tab.label === "string" ? tab.label : "",
+                pane_count: typeof tab.pane_count === "number" ? tab.pane_count : 0,
+            },
+        ]
+        : []);
+}
+/** AC-3: creates a tab labelled with a pane name; its root pane becomes the managed pane. */
+function createTab(opts, workspaceId, label) {
+    const args = ["tab", "create", "--workspace", workspaceId, "--cwd", opts.root, "--label", label, "--no-focus"];
+    const result = resultOf(call(args, opts), "tab create");
+    const pane = result.root_pane;
+    if (!isRecord(pane) || typeof pane.pane_id !== "string")
+        throw new Error("herdr tab create did not return a root pane");
+    return pane.pane_id;
+}
+/** AC-5: moves an existing pane into a tab of its own, labelled with the pane name. */
+function movePaneToNewTab(opts, pane, label) {
+    call(["pane", "move", pane, "--new-tab", "--label", label, "--no-focus"], opts);
+}
+/** AC-5: moves an existing pane next to `anchor` in `tab`, keeping `ratio` of the anchor's width. */
+function movePaneIntoTab(opts, pane, tab, anchor, ratio) {
+    const args = ["pane", "move", pane, "--tab", tab, "--split", "right", "--target-pane", anchor, "--ratio", ratio.toFixed(4), "--no-focus"];
+    call(args, opts);
+}
+function renameTab(opts, tab, label) {
+    call(["tab", "rename", tab, label], opts);
+}
+/** AC-5: a tab that lost its last pane during a move must not remain. */
+function closeEmptyTabs(opts, workspaceId, keep) {
+    for (const tab of tabLocations(opts, workspaceId)) {
+        if (tab.pane_count === 0 && !keep.has(tab.tab_id))
+            call(["tab", "close", tab.tab_id], opts);
+    }
 }
 function createWorkspace(opts) {
     const label = `gdt-${opts.issue}`;
@@ -110,6 +170,68 @@ function writePanes(file, state) {
 function roleTitle(role, agent, state) {
     return role === "supervisor" ? `supervisor · ${state}` : `${role} · ${agent} · ${state}`;
 }
+/**
+ * AC-4/AC-5: all managed panes in one tab, left to right in `names` order. This is a no-op when the
+ * panes already share a tab, so a workspace created in split layout is left exactly as before.
+ */
+function arrangeSplit(opts, workspaceId, names, mapping, paneTab) {
+    const paneOf = (name) => mapping[name]?.pane_id;
+    const first = names[0];
+    if (first === undefined)
+        return;
+    const targetPane = paneOf(first);
+    if (targetPane === undefined)
+        return;
+    const tabs = new Set(names.flatMap((name) => {
+        const pane = paneOf(name);
+        if (pane === undefined)
+            return [];
+        const tab = paneTab.get(pane);
+        return tab === undefined ? [] : [tab];
+    }));
+    if (tabs.size <= 1)
+        return;
+    const target = paneTab.get(targetPane);
+    if (target === undefined)
+        return;
+    let anchor = targetPane;
+    names.slice(1).forEach((name, index) => {
+        const pane = paneOf(name);
+        if (pane === undefined)
+            return;
+        if (paneTab.get(pane) !== target)
+            movePaneIntoTab(opts, pane, target, anchor, 1 / (names.length - (index + 1) + 1));
+        anchor = pane;
+    });
+}
+/** AC-3/AC-5: one tab per managed pane, labelled with the pane name, in `names` order. */
+function arrangeTabs(opts, workspaceId, names, mapping) {
+    const tabByPane = new Map();
+    const countByTab = new Map();
+    for (const pane of paneLocations(opts, workspaceId)) {
+        if (pane.tab_id === undefined)
+            continue;
+        tabByPane.set(pane.pane_id, pane.tab_id);
+        countByTab.set(pane.tab_id, (countByTab.get(pane.tab_id) ?? 0) + 1);
+    }
+    const labels = new Map(tabLocations(opts, workspaceId).map((tab) => [tab.tab_id, tab.label]));
+    const kept = new Set();
+    for (const name of names) {
+        const pane = mapping[name]?.pane_id;
+        if (pane === undefined)
+            continue;
+        const tab = tabByPane.get(pane);
+        // Keep a pane that is already alone in a tab of its own; only relabel that tab when needed.
+        if (tab !== undefined && !kept.has(tab) && countByTab.get(tab) === 1) {
+            kept.add(tab);
+            if (labels.get(tab) !== name)
+                renameTab(opts, tab, name);
+            continue;
+        }
+        movePaneToNewTab(opts, pane, name);
+    }
+    closeEmptyTabs(opts, workspaceId, kept);
+}
 /**
  * One herdr workspace per issue, with four panes for supervisor, developer, tester and reviewer.
  * Panes are reused across `start` calls; their ids live in `panes.json` so a restarted process can
@@ -145,7 +267,12 @@ export function herdr(opts) {
                 else
                     workspaceId = createWorkspace(opts).workspace_id;
             }
-            const live = new Set(paneIds(opts, workspaceId));
+            const locations = paneLocations(opts, workspaceId);
+            const live = new Set(locations.map((pane) => pane.pane_id));
+            const paneTab = new Map();
+            for (const pane of locations)
+                if (pane.tab_id !== undefined)
+                    paneTab.set(pane.pane_id, pane.tab_id);
             // AC-4: a supervisor pane from an earlier run (while `supervisor_pane` was true) is closed; its
             // entry never enters the new panes.json, so no role can adopt the pane.
             if (!opts.supervisorPane && known?.workspace_id === workspaceId) {
@@ -153,6 +280,7 @@ export function herdr(opts) {
                 if (leftover !== undefined && live.has(leftover.pane_id)) {
                     call(["pane", "close", leftover.pane_id], opts);
                     live.delete(leftover.pane_id);
+                    paneTab.delete(leftover.pane_id);
                 }
             }
             const names = paneNames(opts);
@@ -172,23 +300,41 @@ export function herdr(opts) {
                         mapping[name] = { pane_id: reuse };
                 }
             }
-            // Each new pane is split off the right of the previous one, so panes run left to right in
-            // `names` order. The anchor keeps 1/(panes still to fill), which makes a new workspace's panes
-            // equally wide.
-            const first = Object.values(mapping).flatMap((p) => (p === undefined ? [] : [p.pane_id])).find((id) => id !== "");
-            let previous;
-            names.forEach((name, index) => {
-                const record = mapping[name];
-                if (record !== undefined) {
-                    previous = record.pane_id;
-                    return;
+            // Provide a pane for every name that still lacks one, in `names` order.
+            if (opts.layout === "tabs") {
+                // AC-3: each missing pane gets its own tab, labelled with the pane name.
+                for (const name of names) {
+                    if (mapping[name] === undefined)
+                        mapping[name] = { pane_id: createTab(opts, workspaceId, name) };
                 }
-                const anchor = previous ?? first;
-                if (anchor === undefined)
-                    throw new Error(`herdr workspace ${workspaceId} has no pane to split`);
-                previous = splitPane(opts, anchor, 1 / (names.length - index + 1));
-                mapping[name] = { pane_id: previous };
-            });
+            }
+            else {
+                // AC-4: each new pane is split off the right of the previous one, so panes run left to right
+                // in `names` order. The anchor keeps 1/(panes still to fill), which makes a new workspace's
+                // panes equally wide.
+                const first = Object.values(mapping).flatMap((p) => (p === undefined ? [] : [p.pane_id])).find((id) => id !== "");
+                let previous;
+                names.forEach((name, index) => {
+                    const record = mapping[name];
+                    if (record !== undefined) {
+                        previous = record.pane_id;
+                        return;
+                    }
+                    const anchor = previous ?? first;
+                    if (anchor === undefined)
+                        throw new Error(`herdr workspace ${workspaceId} has no pane to split`);
+                    previous = splitPane(opts, anchor, 1 / (names.length - index + 1));
+                    mapping[name] = { pane_id: previous };
+                    const anchorTab = paneTab.get(anchor);
+                    if (anchorTab !== undefined)
+                        paneTab.set(previous, anchorTab);
+                });
+            }
+            // AC-3/AC-5: place the panes according to the configured layout.
+            if (opts.layout === "tabs")
+                arrangeTabs(opts, workspaceId, names, mapping);
+            else
+                arrangeSplit(opts, workspaceId, names, mapping, paneTab);
             writePanes(opts.panesFile, { workspace_id: workspaceId, panes: mapping });
             if (opts.supervisorPane)
                 rename("supervisor", roleTitle("supervisor", "", "starting"));
@@ -223,6 +369,15 @@ export function herdr(opts) {
                 return;
             rename(name, title);
         },
+        setDisplayAgent(name, label) {
+            // Without a supervisor pane there is no supervisor label to set.
+            if (name === "supervisor" && !opts.supervisorPane)
+                return;
+            const paneId = findPane(name);
+            if (paneId === null)
+                return;
+            reportDisplayAgent(opts, paneId, label);
+        },
         reportState(name, state) {
             // AC-6: without a supervisor pane no supervisor state is reported to herdr.
             if (name === "supervisor" && !opts.supervisorPane)

package/dist/backends/index.js

@@ -14,6 +14,7 @@ export function backendFor(config, root, issue, env, p) {
             logs: p.logs,
             agents,
             supervisorPane: config.workflow.supervisor_pane,
+            layout: config.workflow.herdr_layout,
         });
     }
     return headless(p.logs, root, env);