gh-wm

Mon, 01 Jan 0001 00:00:00 +0000

Architecture review and roadmap

This document complements architecture.md with a design review of gh-wm, a target module layout for extensibility, and a phased refactor roadmap (v2). It is the canonical place for “why we’re changing structure” decisions.

Goals (recap)

gh-aw compatibility for task Markdown + YAML frontmatter.
No compile step for workflows.
Thin GitHub coordination (issues, labels, Actions, PRs).
Safe outputs as a policy boundary between agent intent and GitHub writes.

Strengths

Clear five-phase pipeline (activation → agent → validation → safe-outputs → conclusion-defer) with deferred cleanup that survives early failures.
CLI / engine / infra split: cmd/ stays thin; internal/engine/ orchestrates; GitHub I/O is isolated behind helpers.
Per-run artifacts (prompt.md, output.jsonl, agent transcript, meta.json, result.json, optional run.json) support debugging and CI introspection.
Loop prevention is layered: workflow (concurrency, if: on actor), resolver (bot sender), and content (<!-- wm-agent: marker on wm-authored comments).
Declarative tasks keep community workflows portable.

Weaknesses (prioritized)

Engine selection was historically a single switch in runAgent; extending backends required touching multiple files. Mitigation: internal/engine/engines package with a small Engine interface.
Safe outputs were a large switch; new kinds touched parse, policy, prompt, and execution. Mitigation: output.Handler registry (one file per kind).
Frontmatter used map[string]any with ad-hoc accessors; invalid shapes surfaced late. Mitigation: internal/config/spec typed views + validation at load time.
GitHub I/O mixed gh api helpers and direct exec.Command("gh", …) calls. Mitigation: internal/gh REST client (via github.com/cli/go-gh/v2/pkg/api) with typed errors.
Global config cache (sync.Map in config.Load) is convenient for CLI but hurts long-lived processes/tests. Mitigation: documented; optional future Loader type.
Phase bookkeeping in RunTask was manual (easy to miss UpdateMeta). Mitigation: engine/pipeline helpers.
Workflow generator duplicated two large YAML templates. Mitigation: single template with an Inline flag.
Observability mixed log.Printf and stderr banners. Mitigation: log/slog with run-id attributes where wired.
timeout-minutes lived in cmd/run only; library callers of RunTask did not get the same timeout. Mitigation (v2): timeout applied inside RunTask / CLI delegates.

Current module graph

flowchart LR cmd[cmd CLI] engine[internal/engine] config[internal/config] trigger[internal/trigger] output[internal/output] gen[internal/gen] schedule[internal/schedule] antiloop[internal/antiloop] ghclient[internal/ghclient] ghapi[internal/gh] git[internal/gitbranch and gitstatus] types[internal/types] cp[internal/checkpoint] tpl[internal/templates] cmd --> engine cmd --> config cmd --> gen cmd --> tpl cmd --> ghclient engine --> config engine --> trigger engine --> output engine --> ghclient engine --> ghapi engine --> git engine --> cp engine --> types engine --> antiloop engine --> schedule output --> config output --> ghclient output --> ghapi output --> git output --> trigger output --> types trigger --> config trigger --> schedule trigger --> types gen --> config gen --> schedule

Target architecture

flowchart LR cmd[cmd] pipeline[engine pipeline helpers] engines[engine/engines] cfg[config spec plus raw] trig[trigger plus schedule] outputs[output registry] gh[internal/gh REST] antiloop[internal/antiloop] obs[slog plus metrics] gen[gen workflow] cmd --> pipeline pipeline --> engines pipeline --> cfg pipeline --> trig pipeline --> outputs pipeline --> antiloop pipeline --> obs engines --> gh outputs --> gh pipeline --> gh gen --> cfg trig --> cfg

Boundaries:

Mon, 01 Jan 0001 00:00:00 +0000

Architecture

Goals (design intent)

gh-aw format compatibility: Task files use Markdown + YAML frontmatter like Agentic Workflows (gh-aw) ; you can drop community workflows into .wm/tasks/.
No compile step: No .lock.yml, no gh aw compile.
Go + go-gh: GitHub auth follows gh auth login (see internal/ghclient for API usage from commands like assign).
Thin coordination on GitHub: Issues, labels, Actions, PRs—no extra control plane.

High-level pipeline

Each task follows trigger → resolve → run (RunTask). The run is a five-phase pipeline in-process (no gh-aw-style compile): activation (event/task validation, feature branch for PR mode, per-run artifact dir under .wm/runs/ or WM_RUN_DIR), agent (runAgent subprocess — WM_SAFE_OUTPUT_FILE set to per-run output.jsonl when a run dir exists), validation (successful exit and output size bound; context deadline surfaced as timeout), safe-outputs (internal/output — reads output.jsonl (gh wm emit) when safe-outputs: is non-empty; max: / label allowlists enforced; empty output warns and succeeds), and conclusion (defer: checkpoint comment, branch rollback on failure, result.json). RunTask returns a types.RunResult with Phase, Success, Errors, RunDir, and AgentResult; wm run logs phase= and artifacts= on stderr when a run directory is created.

Mon, 01 Jan 0001 00:00:00 +0000

CLI reference

The extension is invoked as gh wm <subcommand> when installed via gh extension install. Building from source produces a binary named gh-wm (same commands as the root Cobra app in cmd/root.go ).

Global

Root use string: gh-wm (binary name).
Short description: GitHub Workflow Manager — run gh-aw-style task markdown in CI.

`version`

Purpose: Print the installed gh-wm version (and optional Git commit line for release builds).

Usage:

gh wm version — prints gh-wm <version> on one line; if the binary was built with a commit SHA (release workflow), prints commit: <short-sha> on a second line.
gh wm --version / gh wm -v — same version string via the root Cobra flag.

Local and CI builds without linker flags report dev. Release assets built from a git tag embed the tag (without the leading v) and a short commit hash. See cmd/version.go and .github/workflows/release.yml .

Mon, 01 Jan 0001 00:00:00 +0000

Development guide

How to build, test, and extend gh-wm. Pair this with architecture.md (especially RunTask pipeline (detailed reference) for reads, writes, and persistence per phase).

Prerequisites

Go (see go.mod for version).
gh CLI for local commands that shell out (assign, status, logs, outputs).
Optional: claude CLI for default run behavior, or set WM_AGENT_CMD.

Build and run

# From repo root
go build -o gh-wm .

./gh-wm resolve --payload /path/to/event.json --event-name issues --json
./gh-wm run --task implement --payload /path/to/event.json --event-name issues

run expects a clean git working tree at --repo-root (use --allow-dirty to skip). A short banner prints to stderr (task, branch, engine), then agent output streams to stderr; a summary line prints when the run finishes.

Mon, 01 Jan 0001 00:00:00 +0000

FAQ

Short answers about how gh-wm works and why it is designed this way. For full detail, see the linked docs.

What is this and why use it?

What is gh-wm in one sentence?

gh-wm is a Go gh CLI extension that reads Markdown tasks under .wm/tasks/, matches them to a GitHub event, runs an agent subprocess with the task body as the prompt, then optionally validates and applies safe outputs (comments, labels, PRs, etc.) according to each task’s policy. The pipeline is event → resolve → run; see Architecture and the index mental model.

Mon, 01 Jan 0001 00:00:00 +0000

Task file format

Tasks live under .wm/tasks/ as *.md files. The filename without .md is the task name (e.g. implement.md → implement).

Layout

.wm/
  config.yml           # Global defaults
  tasks/
    implement.md
    code-review.md
    …

Frontmatter + body

YAML frontmatter is required: first line ---, closing ---, then the markdown body.
The body is the agent prompt (plus optional files appended per .wm/config.yml—see below).
Files named *.md.disabled are skipped (LoadTasksDir ).

Minimal example

---
description: Short summary for humans and status output.

on:
  issues:
    types: [labeled]

engine: claude
---

# Do the work

Instructions for the agent…

`.wm/config.yml` (global)

Loaded by config.Load . Struct: GlobalConfig . Machine-readable schema: global-schema.json (subset; extra keys allowed).

Mon, 01 Jan 0001 00:00:00 +0000

v2 breaking changes (planned / in progress)

This page consolidates user-visible cleanups targeted for a v2 release. Some items below are done in current main; others remain planned.

Area	Change
`engine: copilot`	Removed — use `WM_AGENT_CMD` or `claude` / `codex`.
Legacy `WM_OUTPUT_FILE` / single-file `output.json`	Removed — safe outputs are NDJSON only via `gh wm emit` → `WM_SAFE_OUTPUT_FILE`.
`safe-outputs:` keys	Prefer dash form (`add-labels`, `create-pull-request`) to match gh-aw. Underscore keys in YAML may warn; v2 may canonicalize item types separately (see task-format ).
`tools:`	v2 may require a structured shape (`allowed` / `denied`) and translate per engine (`--allowed-tools`, etc.).
`timeout-minutes`	Enforced inside `engine.RunTask` so library callers and CLI share the same deadline (parent `context` deadlines still cap the run when stricter).
Artifacts	Each run writes `run.json` (merged `meta.json` + outcome fields) alongside `meta.json` and `result.json`.
GitHub API	Default `internal/ghclient` uses the `gh` CLI subprocess (`gh api`). Set `GH_WM_REST=1` to use `go-gh` REST from `internal/gh` .

See also Architecture review for the full refactor roadmap.

gh-wm

Architecture review and roadmap

Goals (recap)

Strengths

Weaknesses (prioritized)

Current module graph

Target architecture

Architecture

Goals (design intent)

High-level pipeline

CLI reference

Global

version

Development guide

Prerequisites

Build and run

FAQ

What is this and why use it?

What is gh-wm in one sentence?

Task file format

Layout

Frontmatter + body

Minimal example

.wm/config.yml (global)

v2 breaking changes (planned / in progress)

`version`

`.wm/config.yml` (global)