@gevezex/gdt 0.2.0 → 0.3.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 `.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,22 @@ 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"
-
-[roles.tester]
-agent = "claude"
-model = "claude-sonnet-5"
-
-[roles.reviewer]
-agent = "codex"
-model = "gpt-5.6-luna"
+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:
 
-[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 config, runs `gdt doctor` and installs the operator skill.
+Without the three role options 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 +302,7 @@ Every command supports `--help`; `status` and `wait` also support `--json`.
 
 | Command | Effect |
 |---|---|
+| `gdt init` | Create `.gdt/config.toml` and 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 |
@@ -321,21 +332,40 @@ overrides (for example another model) and is not committed.
 | `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.herdr_layout` | `tabs` | herdr: `"tabs"` (one tab per pane) or `"split"` (panes side by side in one tab) |
 | `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 |
 
+### 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 |
+
+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).
 
 ## Watching it: herdr or headless
 
 ```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);

package/dist/cli.js

@@ -4,9 +4,10 @@ import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CONFIG_PATH, DEFAULT_LANGUAGE, DEFAULT_MAX_ACCEPTANCE_CRITERIA, loadConfig, ROLES } from "./config.js";
 import { validateContract } from "./contract.js";
-import { findRepository, runDoctor } from "./doctor.js";
-import { issueBody } from "./github.js";
-import { loadLocale } from "./locale.js";
+import { findRepository, herdrPreflight, runDoctor } from "./doctor.js";
+import { detectedChecks, issueBody } from "./github.js";
+import { createRoleRulesFiles, parseRoleSpec, proposal, serializeConfig, writeConfig } from "./init.js";
+import { loadLocale, shippedLanguages } from "./locale.js";
 import { allowRound, answer, installSkill, pause, resume, setAgent, steer } from "./steering.js";
 import { supervise } from "./supervisor.js";
 import { work } from "./worker.js";
@@ -21,6 +22,7 @@ Usage:
   gdt <command> [options]
 
 Commands:
+  init          Create .gdt/config.toml and install the operator skill
   doctor        Check tools, GitHub authentication and .gdt/config.toml
   check-issue   Validate an issue body against the issue contract
   start         Start the workflow for an issue in the background
@@ -47,6 +49,27 @@ Checks that git and gh are installed, gh is authenticated, and that
 .gdt/config.toml (merged with .gdt/config.local.toml) is valid.
 Exits with 1 when any finding has level "error".
 `;
+const INIT_HELP = `Usage: gdt init [--json]
+       gdt init --developer <agent>/<model> --tester <agent>/<model> --reviewer <agent>/<model>
+                [--language <lang>] [--terminal <herdr|headless>]
+                [--required-check <name>]... [--allow-no-required-checks] [--force]
+
+Without the three role options, reports the supported agents, whether each is on
+PATH, the usable terminal, the detected CI checks and the language, and writes
+nothing. With them, writes .gdt/config.toml, runs "gdt doctor" and installs the
+operator skill.
+
+Options:
+  --developer <agent>/<model>    Agent and model for the developer role
+  --tester <agent>/<model>       Agent and model for the tester role
+  --reviewer <agent>/<model>     Agent and model for the reviewer role
+  --language <lang>              Language for human-facing text (default en)
+  --terminal <herdr|headless>    Terminal backend (default: herdr when usable)
+  --required-check <name>        CI check that must pass; repeatable
+  --allow-no-required-checks     Accept an empty required_checks list
+  --force                        Replace an existing .gdt/config.toml
+  --json                         Machine-readable proposal output
+`;
 const CHECK_ISSUE_HELP = `Usage: gdt check-issue <issue> [--json]
        gdt check-issue --body-file <file> [--json]
 
@@ -150,6 +173,132 @@ function doctor(args, io) {
     io.stdout(json ? `${JSON.stringify(report, null, 2)}\n` : formatFindings(report.findings));
     return report.ok ? EXIT_OK : EXIT_FAILED;
 }
+function formatProposal(facts) {
+    const lines = ["agents:"];
+    for (const choice of facts.agents) {
+        lines.push(`  ${choice.agent}  ${choice.found ? "found" : "not found"}  model: ${choice.model_format}, example: ${choice.example}`);
+    }
+    lines.push(`terminal: ${facts.terminal}`, `required_checks: ${facts.required_checks.length === 0 ? "none" : facts.required_checks.join(", ")}`, `language: ${facts.language}`, "", "Next: gdt init --developer <agent>/<model> --tester <agent>/<model> --reviewer <agent>/<model>");
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * `gdt init`: without role options, reports the proposal (AC-1); with all three, writes
+ * `.gdt/config.toml` (AC-2 to AC-5), then runs doctor and installs the skill (AC-6, AC-7).
+ */
+function initCommand(args, io) {
+    let developer;
+    let tester;
+    let reviewer;
+    let language;
+    let terminal;
+    const requiredChecks = [];
+    let allowNoRequiredChecks = false;
+    let force = false;
+    let json = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i] ?? "";
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--force")
+            force = true;
+        else if (arg === "--allow-no-required-checks")
+            allowNoRequiredChecks = true;
+        else if (arg === "--help" || arg === "-h") {
+            io.stdout(INIT_HELP);
+            return EXIT_OK;
+        }
+        else if (arg === "--developer" || arg === "--tester" || arg === "--reviewer" || arg === "--language" || arg === "--terminal" || arg === "--required-check") {
+            const given = args[++i];
+            if (given === undefined)
+                return usageError(io, `Missing value for "${arg}".`, "gdt init --help");
+            if (arg === "--developer")
+                developer = given;
+            else if (arg === "--tester")
+                tester = given;
+            else if (arg === "--reviewer")
+                reviewer = given;
+            else if (arg === "--language")
+                language = given;
+            else if (arg === "--terminal") {
+                if (given !== "herdr" && given !== "headless") {
+                    return usageError(io, `Invalid terminal "${given}"; use herdr or headless.`, "gdt init --help");
+                }
+                terminal = given;
+            }
+            else
+                requiredChecks.push(given);
+        }
+        else if (arg.startsWith("-"))
+            return usageError(io, `Unknown option "${arg}" for "gdt init".`, "gdt init --help");
+        else
+            return usageError(io, `Unexpected argument "${arg}" for "gdt init".`, "gdt init --help");
+    }
+    const root = findRepository(io.cwd);
+    if (root === null) {
+        io.stderr(`${io.cwd} is not inside a Git repository. Run gdt from a checkout of the target repository.\n`);
+        return EXIT_FAILED;
+    }
+    const specs = { developer, tester, reviewer };
+    const given = ROLES.filter((role) => specs[role] !== undefined);
+    if (given.length === 0) {
+        const facts = proposal(root, io.env);
+        io.stdout(json ? `${JSON.stringify(facts, null, 2)}\n` : formatProposal(facts));
+        return EXIT_OK;
+    }
+    if (given.length < ROLES.length) {
+        const missing = ROLES.filter((role) => specs[role] === undefined)
+            .map((role) => `"--${role}"`)
+            .join(", ");
+        return usageError(io, `Missing ${missing} for "gdt init".`, "gdt init --help");
+    }
+    const roles = {};
+    for (const role of ROLES) {
+        const parsed = parseRoleSpec(specs[role] ?? "");
+        if ("error" in parsed) {
+            io.stderr(`${parsed.error}\n`);
+            return EXIT_FAILED;
+        }
+        roles[role] = parsed;
+    }
+    const languages = shippedLanguages();
+    if (language !== undefined && !languages.includes(language)) {
+        io.stderr(`No locale for language "${language}"; available languages: ${languages.join(", ")}\n`);
+        return EXIT_FAILED;
+    }
+    if (existsSync(join(root, CONFIG_PATH)) && !force) {
+        io.stderr(`${CONFIG_PATH} already exists; use --force to replace it\n`);
+        return EXIT_FAILED;
+    }
+    const resolvedTerminal = terminal ?? (herdrPreflight(io.env) === null ? "herdr" : "headless");
+    const checks = requiredChecks.length > 0 ? requiredChecks : detectedChecks(root, io.env);
+    if (checks.length === 0 && !allowNoRequiredChecks) {
+        io.stderr("No required checks detected; pass --required-check <name> for each check, or --allow-no-required-checks to accept none\n");
+        return EXIT_FAILED;
+    }
+    const text = serializeConfig({
+        roles,
+        language: language ?? DEFAULT_LANGUAGE,
+        terminal: resolvedTerminal,
+        requiredChecks: checks,
+        allowNoRequiredChecks,
+    });
+    const writeError = writeConfig(root, text);
+    if (writeError !== null) {
+        io.stderr(`${writeError}\n`);
+        return EXIT_FAILED;
+    }
+    // AC-4: the three supplementary role rules files; existing files are left unchanged.
+    for (const path of createRoleRulesFiles(root))
+        io.stdout(`created ${path}\n`);
+    // AC-7: report the new config with doctor, then install the skill; the config stays in place either way.
+    const report = runDoctor(root, io.env);
+    io.stdout(formatFindings(report.findings));
+    const installed = installSkill(io.env);
+    io.stdout(installed.stdout);
+    if (installed.stderr !== "")
+        io.stderr(installed.stderr);
+    return report.ok ? EXIT_OK : EXIT_FAILED;
+}
 function checkIssue(args, io) {
     let json = false;
     let issue;
@@ -412,6 +561,8 @@ export function run(argv, io) {
             return EXIT_OK;
         case "doctor":
             return doctor(rest, io);
+        case "init":
+            return initCommand(rest, io);
         case "check-issue":
             return checkIssue(rest, io);
         case "start":

package/dist/config.js

@@ -5,6 +5,8 @@ import { z } from "zod";
 export const AGENTS = ["claude", "codex", "opencode", "mcode", "pi", "omp"];
 export const ROLES = ["developer", "tester", "reviewer"];
 export const TERMINALS = ["herdr", "headless"];
+/** AC-2: how the herdr backend places the managed panes. */
+export const HERDR_LAYOUTS = ["split", "tabs"];
 export const CONFIG_PATH = ".gdt/config.toml";
 export const LOCAL_CONFIG_PATH = ".gdt/config.local.toml";
 export const DEFAULT_LANGUAGE = "en";
@@ -41,6 +43,8 @@ function configSchemaFor(testAgents) {
             allow_no_required_checks: z.boolean().default(false),
             terminal: z.enum(TERMINALS).default("herdr"),
             supervisor_pane: z.boolean().default(false),
+            // Default `tabs`: one tab per managed pane. `split` keeps the panes in one tab.
+            herdr_layout: z.enum(HERDR_LAYOUTS).default("tabs"),
             poll_seconds: z.number().positive().default(30),
             handoff_checks: z.int().min(1).default(5),
         }),

package/dist/github.js

@@ -65,6 +65,30 @@ export function repository(cwd, env) {
 export function viewer(cwd, env) {
     return ghJson(["api", "user"], cwd, env).login;
 }
+/**
+ * The distinct names of the check runs and commit statuses on the latest commit of the repository's
+ * default branch, sorted alphabetically. Returns `[]` when `gh` cannot read them (no remote, no
+ * authentication, no GitHub): `gdt init` then treats the repository as having no detected checks.
+ */
+export function detectedChecks(cwd, env) {
+    try {
+        const repo = ghJson(["repo", "view", "--json", "nameWithOwner,defaultBranchRef"], cwd, env);
+        const name = typeof repo.nameWithOwner === "string" ? repo.nameWithOwner : null;
+        const branch = typeof repo.defaultBranchRef?.name === "string" ? repo.defaultBranchRef.name : null;
+        if (name === null || branch === null)
+            return [];
+        const runs = ghJson(["api", `repos/${name}/commits/${branch}/check-runs`], cwd, env);
+        const statuses = ghJson(["api", `repos/${name}/commits/${branch}/status`], cwd, env);
+        const names = [
+            ...(runs.check_runs ?? []).map((run) => run.name),
+            ...(statuses.statuses ?? []).map((status) => status.context),
+        ].filter((value) => typeof value === "string" && value !== "");
+        return [...new Set(names)].sort();
+    }
+    catch {
+        return [];
+    }
+}
 /** The issue body and the open pull requests that close the issue ("Closes #n"). */
 export function issueSnapshot(issue, cwd, env) {
     const data = ghJson(["issue", "view", String(issue), "--json", "body,closedByPullRequestsReferences"], cwd, env);

package/dist/init.js

@@ -0,0 +1,92 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { adapterFor, supportedAgents } from "./agents/index.js";
+import { CONFIG_PATH, DEFAULT_LANGUAGE, ROLES } from "./config.js";
+import { herdrPreflight, which } from "./doctor.js";
+import { detectedChecks } from "./github.js";
+import { ROLE_RULES_DIR, roleRulesPath } from "./prompts.js";
+/** The proposal: one entry per supported agent, the usable terminal, detected checks and language. */
+export function proposal(root, env) {
+    const agents = supportedAgents().flatMap((agent) => {
+        const adapter = adapterFor(agent);
+        if (adapter === undefined)
+            return [];
+        return [
+            {
+                agent,
+                found: which(adapter.binary, env) !== null,
+                model_format: adapter.modelFormat,
+                example: adapter.modelExample,
+            },
+        ];
+    });
+    return {
+        agents,
+        terminal: herdrPreflight(env) === null ? "herdr" : "headless",
+        required_checks: detectedChecks(root, env),
+        language: DEFAULT_LANGUAGE,
+    };
+}
+/** Parses `<agent>/<model>` at the first `/`, the same way `gdt set-agent` does. */
+export function parseRoleSpec(spec) {
+    const slash = spec.indexOf("/");
+    const agent = slash === -1 ? spec : spec.slice(0, slash);
+    const model = slash === -1 ? "" : spec.slice(slash + 1);
+    const supported = supportedAgents();
+    if (!supported.includes(agent)) {
+        return { error: `Unsupported agent "${agent}"; supported agents: ${supported.join(", ")}` };
+    }
+    if (model.trim() === "")
+        return { error: `Missing model in "${spec}"; use <agent>/<model>` };
+    return { agent: agent, model };
+}
+/** The `.gdt/config.toml` text; a key that keeps its schema default is not written (AC-2). */
+export function serializeConfig(config) {
+    const lines = [];
+    if (config.language !== DEFAULT_LANGUAGE)
+        lines.push(`language = ${JSON.stringify(config.language)}`, "");
+    for (const role of ROLES) {
+        const { agent, model } = config.roles[role];
+        lines.push(`[roles.${role}]`, `agent = ${JSON.stringify(agent)}`, `model = ${JSON.stringify(model)}`, "");
+    }
+    lines.push("[workflow]", `required_checks = [${config.requiredChecks.map((name) => JSON.stringify(name)).join(", ")}]`);
+    if (config.allowNoRequiredChecks)
+        lines.push("allow_no_required_checks = true");
+    if (config.terminal !== "herdr")
+        lines.push(`terminal = ${JSON.stringify(config.terminal)}`);
+    lines.push("");
+    return lines.join("\n");
+}
+/** Writes the config, creating `.gdt/` when needed; returns an error message, or null on success. */
+export function writeConfig(root, text) {
+    try {
+        const path = join(root, CONFIG_PATH);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, text);
+        return null;
+    }
+    catch (err) {
+        return `Cannot write ${CONFIG_PATH}: ${err instanceof Error ? err.message : String(err)}`;
+    }
+}
+/**
+ * AC-4: creates each missing `.gdt/roles/<role>.md` as an empty file and returns its
+ * repository-relative path. An existing file is never touched, not even with `--force`.
+ */
+export function createRoleRulesFiles(root) {
+    const created = [];
+    for (const role of ROLES) {
+        const path = roleRulesPath(root, role);
+        mkdirSync(dirname(path), { recursive: true });
+        try {
+            writeFileSync(path, "", { flag: "wx" });
+            created.push(`${ROLE_RULES_DIR}/${role}.md`);
+        }
+        catch (err) {
+            // Exists already: leave it byte-for-byte unchanged.
+            if (err.code !== "EEXIST")
+                throw err;
+        }
+    }
+    return created;
+}

package/dist/prompts.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { z } from "zod";
 import { loadLocale, SECTION_KEYS } from "./locale.js";
 import { marker, schemas } from "./protocol.js";
@@ -7,9 +7,26 @@ export const ROLE_FILES = ["developer", "tester", "reviewer", "issue-writer"];
 /** The record kind each workflow role writes. */
 export const RECORD_OF = { developer: "handoff", tester: "test", reviewer: "review" };
 const ROLES_DIR = new URL("../roles/", import.meta.url);
+/** The directory, relative to a target repository's root, holding the per-role supplementary rules. */
+export const ROLE_RULES_DIR = ".gdt/roles";
 export function roleFile(name) {
     return readFileSync(new URL(`${name}.md`, ROLES_DIR), "utf8");
 }
+/** The absolute path of a workflow role's supplementary rules file in `root`. */
+export function roleRulesPath(root, role) {
+    return join(root, ROLE_RULES_DIR, `${role}.md`);
+}
+/**
+ * The role's supplementary rules, trimmed, or `null` when the file is missing or empty (whitespace
+ * only). Read on every call, so a change reaches the role's next turn without a restart (AC-3).
+ */
+export function roleRules(root, role) {
+    const path = roleRulesPath(root, role);
+    if (!existsSync(path))
+        return null;
+    const text = readFileSync(path, "utf8").trimEnd();
+    return text.trim() === "" ? null : text;
+}
 /**
  * Trusted directives for `role` posted after that role's previous dispatch, i.e. with a comment id
  * above `afterCommentId` (the highest comment id seen at that dispatch; 0 before the first one).
@@ -76,5 +93,9 @@ export function buildPrompt(role, dispatch, project) {
         if (existsSync(path))
             parts.push(["## Project rules", "", readFileSync(path, "utf8").trimEnd()].join("\n"));
     }
+    // AC-1/AC-2: a role's own supplementary rules, after the global project rules; empty adds nothing.
+    const rules = roleRules(project.root, role);
+    if (rules !== null)
+        parts.push(["## Role rules", "", rules].join("\n"));
     return `${parts.join("\n\n")}\n`;
 }

package/dist/steering.js

@@ -3,7 +3,8 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { adapterFor, supportedAgents } from "./agents/index.js";
-import { ROLES } from "./config.js";
+import { backendFor } from "./backends/index.js";
+import { loadConfig, ROLES } from "./config.js";
 import { findRepository, which } from "./doctor.js";
 import { comments, issueSnapshot, postIssueComment, postPullRequestComment, repository } from "./github.js";
 import { formatRecord, parseRecords } from "./protocol.js";
@@ -129,6 +130,17 @@ export function setAgent(issue, role, spec, cwd, env) {
     if (readState(p) === null)
         return fail(`No workflow for #${issue}. Next: gdt start ${issue}\n`);
     writeJsonAtomic(p.overrides, { ...readOverrides(p), [checked]: { agent: agent, model } });
+    // AC-1: the agents overview must name the role's new agent. Best effort: the pane may not exist
+    // yet, the terminal may be headless, or herdr may be missing; the override still applies.
+    try {
+        const { report } = loadConfig(p.root, env);
+        if (report.valid && report.workflow.terminal === "herdr") {
+            backendFor(report, p.root, issue, env, p).setDisplayAgent(checked, `${checked} · ${agent}`);
+        }
+    }
+    catch {
+        // The override is written; the label is refreshed on the next `gdt start`.
+    }
     return ok(`${checked} for #${issue} now uses ${agent} with model ${model} from its next turn.\n`);
 }
 /** `gdt install-skill`: copies `skill/SKILL.md` into every detected harness; idempotent. */

package/dist/supervisor.js

@@ -107,6 +107,18 @@ class Supervisor {
         this.backend.setTitle(role, this.roleTitle(role, state));
         this.reportState(role, ROLE_PANE_STATE[state]);
     }
+    /** AC-1: sets the display-only agent label, for example `developer · opencode` or `gdt · supervisor`. */
+    setDisplay(name, label) {
+        try {
+            this.backend.setDisplayAgent(name, label);
+        }
+        catch (err) {
+            if (this.reportWarned)
+                return;
+            this.reportWarned = true;
+            log(`warning: herdr display label failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     /** Records a status; notifies once when entering a notifying status. */
     setStatus(status, reason, extra = {}) {
         if (this.state.status !== status || this.state.reason !== reason)
@@ -128,10 +140,13 @@ class Supervisor {
     }
     startWorkers() {
         this.backend.ensureWorkspace();
+        // AC-1: the agents overview shows the role next to the agent name, once per `gdt start`.
+        this.setDisplay("supervisor", "gdt · supervisor");
         this.backend.setTitle("supervisor", "supervisor · starting");
         this.reportState("supervisor", supervisorAgentState(this.state.status));
         for (const role of ROLES) {
             this.setRoleState(role, "WAITING");
+            this.setDisplay(role, `${role} · ${this.agents[role]}`);
             if (this.backend.alive(this.state.pids.workers[role] ?? -1))
                 continue;
             this.state.pids.workers[role] = this.backend.spawnPane(role, [process.execPath, cliPath(), "_worker", String(this.issue), role]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gevezex/gdt",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "GitHub issues to merge-ready pull requests, with a developer, tester and reviewer agent.",
   "keywords": [
     "github",

package/skill/SKILL.md

@@ -3,6 +3,16 @@
 You are the operator: the user talks to you in their own language, and you run
 gdt for them. They should never have to memorise a gdt command.
 
+## First-time setup
+
+- With no `.gdt/config.toml`, run `gdt init --json`. It writes nothing and reports
+  the supported agents, which are on PATH, the terminal and the detected CI checks.
+- Present that proposal to the user and ask which agent and model each role
+  (developer, tester, reviewer) uses. Do not pick models for them.
+- Run `gdt init` with their choices, for example
+  `gdt init --developer opencode/deepseek/deepseek-v4-flash --tester claude/claude-sonnet-5 --reviewer codex/gpt-5.6-luna`.
+  It writes the config, runs `gdt doctor` and installs this skill.
+
 ## Start
 
 - `gdt start <issue>` returns immediately; the supervisor keeps running on its own.