@gevezex/gdt 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ayhan Cicek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,375 @@
+# gdt
+
+**GitHub issues to merge-ready pull requests, with a developer, tester and reviewer agent.**
+
+> Status: early development (0.x), used daily on this repository (see
+> [docs/dogfooding.md](docs/dogfooding.md)). Background:
+> [docs/design.md](docs/design.md).
+
+gdt takes one GitHub issue and runs it through three independent agent roles
+until a single draft pull request is ready to merge, or until it needs your
+decision:
+
+- the **developer** implements the issue and opens a draft pull request;
+- the **tester** checks every acceptance criterion against the running code;
+- the **reviewer** reads the diff against the issue.
+
+A deterministic **supervisor** (plain code, no model) decides whose turn it is.
+Waiting, polling and deciding cost no model tokens; a model only runs during a
+role's turn. You drive gdt by talking to any coding agent (Claude Code, Codex,
+OpenCode, MCode, pi or omp) and can watch the roles work in
+[herdr](https://herdr.dev). **You always merge yourself**: gdt never merges,
+deploys or closes issues.
+
+## How it works
+
+### The big picture
+
+```text
+ ┌──────────┐  "pick up issue 251     ┌──────────────────────┐
+ │   you    │ ──────────────────────► │  operator agent      │  Claude Code, Codex,
+ └──────────┘   with gdt"             │  (your chat session) │  OpenCode, ...
+      ▲                               └──────────┬───────────┘
+      │                                          │ gdt start 251   (returns at once)
+      │                                          │ gdt wait 251    (background, 0 tokens)
+      │                                          ▼
+      │                     ┌──────────────────────────────────────────┐
+      │                     │ supervisor  (deterministic, no model)    │
+      │                     │  reads GitHub every poll_seconds,        │
+      │                     │  decides the next turn, enforces gates   │
+      │                     └───────┬──────────────┬──────────────┬────┘
+      │                     dispatch│      dispatch│      dispatch│
+      │                             ▼              ▼              ▼
+      │                     ┌────────────┐  ┌────────────┐  ┌────────────┐
+      │                     │ developer  │  │  tester    │  │  reviewer  │
+      │                     │  worker    │  │  worker    │  │  worker    │
+      │                     └─────┬──────┘  └─────┬──────┘  └─────┬──────┘
+      │                           │ one turn      │ one turn      │ one turn
+      │                           ▼               ▼               ▼
+      │                     ┌──────────────────────────────────────────┐
+      │                     │ GitHub: issue #251 + one draft PR        │
+      │                     │  code, commits and [gdt-*:v1] records    │
+      │                     └──────────────────────────────────────────┘
+      │
+      └──── notification + `gdt wait` returns on:
+            awaiting_human │ blocked │ failed │ ready_to_merge
+```
+
+- The **operator** is the agent you already chat with. It only runs `gdt`
+  commands and relays your words; it never writes code in the workflow.
+- The **supervisor** runs as its own process (a herdr pane or a detached
+  process), so closing or compacting your chat never stops a workflow.
+- Each **worker** waits for a dispatch without using a model, runs exactly one
+  agent turn (for example `claude -p ...`), and goes back to waiting.
+- Roles talk to each other only through **records** posted as comments on
+  GitHub (`[gdt-handoff:v1]`, `[gdt-test:v1]`, `[gdt-review:v1]`, ...). The
+  supervisor reads those records; nothing is passed by chat.
+
+### One issue, start to finish
+
+```text
+  write the issue ──► gdt check-issue 251 ──► invalid: fix the body, check again
+                             │ valid
+                             ▼
+   ┌──────────────────────────────────────────────────────────┐
+   │ gdt start 251                                            │
+   │ preflight: config valid, clean working tree, contract ok │
+   └────────┬─────────────────────────────────────────────────┘
+            ▼
+   ┌──────────────────────────────────────────────────────────┐
+   │ developer (round 0): branch, implement the ACs, tests,   │◄──────┐
+   │ draft PR with "Closes #251", post [gdt-handoff:v1]       │       │
+   └────────┬─────────────────────────────────────────────────┘       │
+            ▼                                                         │
+   ┌──────────────────────┐                                           │
+   │ tester (read-only)   │  checks every AC on the PR head           │
+   │ post [gdt-test:v1]   ├── changes_requested ──┐                   │
+   └────────┬─────────────┘                       │                   │
+            │ approved                            ▼                   │
+   ┌──────────────────────┐            ┌─────────────────────┐  yes   │
+   │ reviewer (read-only) │            │ correction rounds   ├────────┘
+   │ post [gdt-review:v1] ├── changes ►│ left?               │ developer fixes
+   └────────┬─────────────┘  requested └─────────┬───────────┘ (round 1, 2, ...)
+            │ approved                           │ no
+            ▼                                    ▼
+   ┌─────────────────────────────┐     ┌─────────────────────┐
+   │ gates                       │     │ blocked             │
+   │ - every AC passed by both   │     │ you decide:         │
+   │ - no blocking findings      │     │ gdt allow-round 251 │
+   │ - no merge conflict         │     └─────────────────────┘
+   │ - required CI checks green  │
+   └────────┬────────────────────┘
+            │ all pass
+            ▼
+   ┌─────────────────────────────┐
+   │ ready_to_merge              ├──► you review and merge the PR
+   └─────────────────────────────┘    ("Closes #251" closes the issue)
+
+  At any point a role may post [gdt-question:v1] → status awaiting_human
+  → you answer through the operator (gdt answer 251 Q1 "...") → that role resumes.
+```
+
+Evidence is bound to the exact pull request head: when the developer pushes a
+new commit, earlier test and review results no longer count and the tester and
+reviewer run again. Editing the issue body (with a Changelog entry) resets all
+evidence too.
+
+## Requirements
+
+| Tool | Why |
+|---|---|
+| 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"` |
+
+## Install
+
+```bash
+npm i -g @gevezex/gdt
+gdt --version
+```
+
+Or run it once without installing: `npx @gevezex/gdt doctor`.
+
+From source instead:
+
+```bash
+git clone https://github.com/gevezex/gdt.git
+cd gdt
+npm ci
+npm run build
+npm link          # puts `gdt` on your PATH
+```
+
+Then install the operator skill, so your coding agent knows how to drive gdt:
+
+```bash
+gdt install-skill
+```
+
+It copies `skill/SKILL.md` into the skill directory of every agent CLI it finds
+(for example `~/.claude/skills/gdt`) and is safe to run again.
+
+## Quick start
+
+### 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"
+
+[workflow]
+required_checks = ["test"]       # CI check names that must be green
+terminal = "herdr"               # or "headless"
+```
+
+Then check your setup:
+
+```bash
+gdt doctor
+```
+
+`doctor` checks `git`, `gh` and its login, the agent CLIs, herdr (when used)
+and the config, and prints a `fix:` line for every problem. It also warns when
+developer and tester use the same model vendor, because the tester is less
+independent then.
+
+### 2. Write the issue as a contract
+
+The issue body is the only specification. It needs fixed sections and numbered
+acceptance criteria, each with Given, When, Then and a concrete Example:
+
+```markdown
+## Plain language
+One paragraph for humans.
+
+## Goal
+## Context
+## Definitions
+
+## Acceptance criteria
+
+**AC-1: Short title**
+
+- Given: the starting situation
+- When: the action
+- Then: the observable result
+- Example: `gdt foo 12` prints `bar`
+
+## Non-functional
+## Out of scope
+## Assumptions
+
+## Open questions
+
+None.
+
+## Changelog
+- 2026-09-27: first version
+
+## Readiness
+```
+
+Work starts only when `Open questions` is exactly `None.` Vague phrases such as
+"robust" or "etc." are rejected. Headings come from
+[`locales/<language>.toml`](locales), so a Dutch issue uses `Acceptatiecriteria`,
+`Gegeven`, `Wanneer` and so on. Check an issue before starting:
+
+```bash
+gdt check-issue 251                    # an existing issue
+gdt check-issue --body-file body.md    # a draft, without calling GitHub
+```
+
+Your agent can help write the body with the issue-writer instructions in
+[`roles/issue-writer.md`](roles/issue-writer.md).
+
+### 3. Start it from your agent
+
+Just ask your coding agent, in your own language:
+
+> pick up issue 251 with gdt
+
+The agent runs `gdt start 251` and then `gdt wait 251` in the background. You
+get a desktop notification when something needs you. Come back to the same
+chat and ask "what's going on?".
+
+You can also run it by hand:
+
+```bash
+gdt start 251     # starts the supervisor and workers, returns immediately
+gdt wait 251      # blocks until the workflow needs attention
+gdt status 251    # one line plus the next step
+```
+
+### 4. Answer, steer, merge
+
+| Situation | What you (or your agent) run |
+|---|---|
+| A role asks a question | `gdt answer 251 Q1 "use the existing config file"` |
+| You want to guide one role | `gdt steer 251 --role developer "keep the public API unchanged"` |
+| Round budget used up | `gdt allow-round 251` |
+| A turn failed or crashed | `gdt retry 251`, then `gdt start 251` |
+| Try another model for a role | `gdt set-agent 251 tester claude/claude-opus-5-5` |
+| `ready_to_merge` | review the draft PR, mark it ready and merge it yourself |
+
+The operator only posts answers and directives in your words, or after you
+confirmed the text. Directives are guidance, not contract: a directive that
+changes product behaviour makes the role ask for the issue body to be updated.
+
+## Workflow statuses
+
+`gdt status <n>` always prints the status and the next step.
+
+| Status | Meaning | Next step |
+|---|---|---|
+| `starting` / `running` | a role turn is running | wait |
+| `waiting_for_checks` | approved; CI or mergeability pending | wait |
+| `awaiting_human` | a role asked a question | `gdt answer <n> <question-id> "<text>"` |
+| `blocked` | a gate failed or a role reported blocked; the reason says why | follow the hint, e.g. `gdt allow-round <n>` |
+| `contract_changed` | the issue body changed; evidence is reset | wait |
+| `failed` | an agent turn exited non-zero | `gdt retry <n>` |
+| `paused` / `stopped` | you paused or stopped it | `gdt resume <n>` / `gdt start <n>` |
+| `ready_to_merge` | all gates passed | review and merge the PR |
+
+## Commands
+
+Every command supports `--help`; `status` and `wait` also support `--json`.
+
+| Command | Effect |
+|---|---|
+| `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 |
+| `gdt status <n>` | Status, role, round, open findings and next step |
+| `gdt wait <n>` | Block (without tokens) until the workflow needs attention |
+| `gdt stop <n>` | Stop everything; `gdt start` resumes the same workflow |
+| `gdt pause <n>` / `gdt resume <n>` | Stop / continue dispatching new turns |
+| `gdt answer <n> <id> <text>` | Answer an open question |
+| `gdt steer <n> --role <role> <text>` | Send a directive to one role's next turn |
+| `gdt allow-round <n>` | Grant one extra correction round |
+| `gdt retry <n>` | Clear a failed or interrupted turn so it runs again |
+| `gdt set-agent <n> <role> <agent>/<model>` | Override one role's agent for this issue |
+| `gdt install-skill` | Install the operator skill into your agent CLIs |
+
+## Configuration
+
+`.gdt/config.toml` is committed; `.gdt/config.local.toml` holds machine-local
+overrides (for example another model) and is not committed.
+
+| 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 |
+
+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/
+ └──────────────┴──────────────┴──────────────┘
+   supervisor runs detached → logs/supervisor.log
+```
+
+Everything gdt keeps for an issue lives under `.git/gdt/issue-<n>/`: `state.json`
+(the workflow state), `logs/` (one log per process) and `runs/` (the prompt and
+result of every turn). It is never committed.
+
+## Principles
+
+- **The issue body is the contract.** Work starts only when there are no open questions.
+- **Independent verification.** The tester derives its checks from the contract,
+  not from the developer's claims. Evidence is bound to the exact PR head.
+- **Bounded cost.** A fixed correction-round budget; models run only on dispatched turns.
+- **Fail closed.** When a trustworthy decision is impossible, gdt stops and tells you why.
+- **Role boundaries are checked.** After a tester or reviewer turn, the supervisor
+  verifies that HEAD, branch and tracked files are unchanged.
+- **Your language on GitHub.** Issues and PR text in your configured language;
+  protocol, code and CLI output in English.
+- **Humans merge.** gdt never merges, deploys or closes issues.
+
+## Development
+
+Requires Node 24 LTS.
+
+```bash
+npm ci
+npm run build
+npm run lint
+npm test
+node dist/cli.js doctor   # run inside a repository with .gdt/config.toml
+```
+
+Rules for agents working on this repository: [AGENTS.md](AGENTS.md).
+
+## License
+
+[MIT](LICENSE)

package/dist/agents/adapter.js

@@ -0,0 +1,7 @@
+/**
+ * The vendor of a `provider/model` id: the prefix before `/`, or the id itself when it has no `/`.
+ * `"deepseek/deepseek-v4-flash"` is `deepseek`, `"sonnet"` is its own vendor.
+ */
+export function vendorFromModel(model) {
+    return model.split("/")[0] ?? model;
+}

package/dist/agents/claude.js

@@ -0,0 +1,13 @@
+/** Claude Code; see docs/agents.md. */
+export const claude = {
+    binary: "claude",
+    title: "Claude Code",
+    install: "Install Claude Code: https://docs.anthropic.com/en/docs/claude-code",
+    buildInvocation: (_role, model, promptFile) => ({
+        argv: ["claude", "-p", "--model", model, "--permission-mode", "bypassPermissions", "--no-session-persistence"],
+        env: {},
+        stdin: promptFile,
+    }),
+    vendorOf: () => "anthropic",
+    skillDir: () => "~/.claude/skills/gdt",
+};

package/dist/agents/codex.js

@@ -0,0 +1,13 @@
+/** Codex CLI; see docs/agents.md. */
+export const codex = {
+    binary: "codex",
+    title: "Codex",
+    install: "Install Codex: npm i -g @openai/codex",
+    buildInvocation: (_role, model, promptFile, cwd) => ({
+        argv: ["codex", "exec", "--model", model, "--cd", cwd, "--dangerously-bypass-approvals-and-sandbox", "--ephemeral", "-"],
+        env: {},
+        stdin: promptFile,
+    }),
+    vendorOf: () => "openai",
+    skillDir: () => "~/.codex/skills/gdt",
+};

package/dist/agents/index.js

@@ -0,0 +1,15 @@
+import { claude } from "./claude.js";
+import { codex } from "./codex.js";
+import { mcode } from "./mcode.js";
+import { omp } from "./omp.js";
+import { opencode } from "./opencode.js";
+import { pi } from "./pi.js";
+/** One adapter per agent; an agent with no entry has no unattended invocation (docs/agents.md). */
+export const ADAPTERS = { claude, codex, opencode, mcode, pi, omp };
+export function adapterFor(agent) {
+    return ADAPTERS[agent];
+}
+/** The agents gdt can actually run right now, in a stable order. */
+export function supportedAgents() {
+    return Object.keys(ADAPTERS);
+}

package/dist/agents/mcode.js

@@ -0,0 +1,14 @@
+import { vendorFromModel } from "./adapter.js";
+/** MiniMax Code; see docs/agents.md. `mcode exec --input -` reads the prompt from stdin. */
+export const mcode = {
+    binary: "mcode",
+    title: "MCode",
+    install: "Install MiniMax Code: npm i -g @minimax-ai/code",
+    buildInvocation: (_role, model, promptFile, cwd) => ({
+        argv: ["mcode", "exec", "--model", model, "--cwd", cwd, "--permission", "full", "--input", "-"],
+        env: {},
+        stdin: promptFile,
+    }),
+    vendorOf: vendorFromModel,
+    skillDir: () => "~/.minimax/skills/gdt",
+};

package/dist/agents/omp.js

@@ -0,0 +1,14 @@
+import { vendorFromModel } from "./adapter.js";
+/** omp; see docs/agents.md. `--print` reads the prompt from stdin; `--auto-approve` skips approvals. */
+export const omp = {
+    binary: "omp",
+    title: "omp",
+    install: "Install omp: https://omp.sh",
+    buildInvocation: (_role, model, promptFile) => ({
+        argv: ["omp", "--print", "--model", model, "--no-session", "--auto-approve"],
+        env: {},
+        stdin: promptFile,
+    }),
+    vendorOf: vendorFromModel,
+    skillDir: () => "~/.omp/agent/skills/gdt",
+};

package/dist/agents/opencode.js

@@ -0,0 +1,15 @@
+import { vendorFromModel } from "./adapter.js";
+export const OPENCODE_MESSAGE = "Follow the instructions in the attached file.";
+/** OpenCode; see docs/agents.md. `opencode run` documents no stdin input, so the prompt is attached as a file. */
+export const opencode = {
+    binary: "opencode",
+    title: "OpenCode",
+    install: "Install OpenCode: https://opencode.ai",
+    buildInvocation: (_role, model, promptFile) => ({
+        argv: ["opencode", "run", "--model", model, "--auto", "--file", promptFile, OPENCODE_MESSAGE],
+        env: {},
+        stdin: null,
+    }),
+    vendorOf: vendorFromModel,
+    skillDir: () => "~/.config/opencode/skills/gdt",
+};

package/dist/agents/pi.js

@@ -0,0 +1,14 @@
+import { vendorFromModel } from "./adapter.js";
+/** pi; see docs/agents.md. `--print` reads the prompt from stdin and exits after one turn. */
+export const pi = {
+    binary: "pi",
+    title: "pi",
+    install: "Install pi: npm i -g --ignore-scripts @earendil-works/pi-coding-agent",
+    buildInvocation: (_role, model, promptFile) => ({
+        argv: ["pi", "--print", "--model", model, "--no-session", "--no-approve"],
+        env: {},
+        stdin: promptFile,
+    }),
+    vendorOf: vendorFromModel,
+    skillDir: () => "~/.pi/agent/skills/gdt",
+};

package/dist/backends/backend.js

@@ -0,0 +1 @@
+export {};

package/dist/backends/headless.js

@@ -0,0 +1,55 @@
+import { spawn } from "node:child_process";
+import { mkdirSync, openSync } from "node:fs";
+import { join } from "node:path";
+import { alive } from "../state.js";
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function killGroup(pid, signal) {
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        try {
+            process.kill(pid, signal);
+        }
+        catch {
+            // Already gone.
+        }
+    }
+}
+/** Detached processes with one log file per pane under `logs`. */
+export function headless(logs, cwd, env) {
+    return {
+        ensureWorkspace: () => mkdirSync(logs, { recursive: true }),
+        spawnPane(name, argv) {
+            mkdirSync(logs, { recursive: true });
+            const out = openSync(join(logs, `${name}.log`), "a");
+            const [command, ...args] = argv;
+            if (command === undefined)
+                throw new Error("spawnPane: empty argv");
+            const child = spawn(command, args, { cwd, env, detached: true, stdio: ["ignore", out, out] });
+            child.unref();
+            if (child.pid === undefined)
+                throw new Error(`could not start ${name}`);
+            return child.pid;
+        },
+        setTitle: () => {
+            // Headless panes have no title.
+        },
+        reportState: () => {
+            // AC-7: headless mode reports no agent state.
+        },
+        alive: (pid) => alive(pid),
+        attach: () => null,
+        close(pid) {
+            killGroup(pid, "SIGTERM");
+            for (let waited = 0; waited < 5000 && alive(pid); waited += 50)
+                sleepSync(50);
+            if (alive(pid))
+                killGroup(pid, "SIGKILL");
+            for (let waited = 0; waited < 2000 && alive(pid); waited += 50)
+                sleepSync(50);
+        },
+    };
+}