gh-wm

README

gh-wm — Workflow Manager for personal agentic development

gh-wm is a Go gh CLI extension that runs gh-aw–compatible task files (Markdown + YAML frontmatter) from .wm/tasks/ without compiling to lockfiles, without AWF, and without enforcing gh-aw limits in safe-outputs (keys still select optional post-agent steps).

Documentation

Full docs for humans and AI agents live under docs/ (Markdown in docs/content/, Hugo in the same folder). A browsable HTML version is published at https://gh-wm.github.io/gh-wm/.

Doc	Contents
docs/content/_index.md	Index and mental model
docs/content/architecture.md	Pipelines, code map, GitHub Actions
docs/content/task-format.md	.wm/config.yml, on: semantics, gh-aw notes
docs/content/cli-reference.md	Commands, flags, environment variables
docs/content/development.md	Contributing and extending the Go codebase

Install

go install github.com/an-lee/gh-wm@latest
# or build from this repo
go build -o gh-wm .

As a gh extension (after publishing releases):

gh extension install an-lee/gh-wm

Quick start (in a repository)

gh wm init

This creates:

• .wm/config.yml — global defaults (engine, context.files, …)
• .wm/tasks/*.md — starter tasks (gh-aw–style frontmatter + markdown body = agent prompt)
• .github/workflows/wm-agent.yml — auto-generated caller workflow (do not edit by hand)

Set where reusable workflows live (default an-lee/gh-wm):

export GH_WM_REPO=your-org/gh-wm
gh wm compile

Commands

Command	Purpose
gh wm init	Scaffold .wm/, tasks, and wm-agent.yml
gh wm compile	Regenerate wm-agent.yml from tasks and .wm/config.yml
gh wm upgrade	Run gh extension upgrade for the gh-wm extension
gh wm update	Re-fetch tasks that have source: (URL or owner/repo/path)
gh wm add <…>	Add a task .md (owner/repo/task, URL, or path); runs compile after
gh wm assign <n>	Add label (default agent) to issue #n
gh wm resolve	List task names matching GITHUB_EVENT / payload
gh wm run --task <name>	Run one task (agent + optional safe-outputs)
gh wm status	List issues with agent-related labels (--all = gh search)
gh wm logs <n>	List wm-agent runs (best-effort match on #n in title)

CI entrypoints

• gh wm resolve — reads --payload or GITHUB_EVENT_PATH (if both unset, payload defaults to {}), prints JSON array of matching task names.
• gh wm run --task … — same payload resolution as resolve; requires a clean git working tree unless --allow-dirty. Streams agent output to stderr and prints a short summary when finished. Runs the agent (default: claude -p with the task body plus optional context.files from .wm/config.yml; timeout-minutes from frontmatter). Override with WM_AGENT_CMD. On success, runs safe-outputs steps (e.g. PR, comment). Use WM_CHECKPOINT=1 for checkpoint load/post.

Secrets

• ANTHROPIC_API_KEY — for Claude Code in Actions (configure in repo secrets).

Task format

Tasks are .wm/tasks/<name>.md with YAML frontmatter compatible with GitHub Agentic Workflows (on:, safe-outputs:, engine:, …) and a markdown body used as the agent prompt.

Architecture (summary)

1. One caller workflow (wm-agent.yml) listens for broad events and schedule crons.
2. Resolve job runs gh wm resolve → JSON list of matching tasks.
3. Matrix job runs gh wm run --task <name> in parallel for each match (fail-fast: false).

After changing any task’s on: triggers, run gh wm compile to refresh wm-agent.yml.

Details: docs/content/architecture.md.

License

MIT — see LICENSE.