Workflow manager for agentic development — documentation.
gh-wm documentation
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 or AWF. When safe-outputs: is set, the agent records outputs via gh wm emit (NDJSON into output.jsonl); gh-wm validates and applies them (max:, allowlists, etc.).
This documentation is the canonical reference for how the project works and how to extend it.
Published site: https://gh-wm.github.io/gh-wm/ (same Markdown, rendered with Hugo).
Who this is for
| Reader | Start here |
|---|---|
| Quick Q&A | FAQ |
| Humans | Architecture → Architecture review → v2 changes → CLI reference → Task format |
| AI coding agents | Read Architecture
, Architecture review
, and Development
before changing behavior. Use Task format
when editing .wm/tasks/*.md or explaining compatibility with gh-aw
. |
Contents
| Doc | Purpose |
|---|---|
| faq.md | Frequently asked questions: how gh-wm works, why safe-outputs and CI split, workflows, agents—links to deeper pages. |
| architecture.md | End-to-end flow: GitHub Actions → resolve → matrix run, Go packages, and RunTask pipeline (detailed reference) (reads/writes per phase). |
| architecture-review.md | Design review, target module layout, phased refactor roadmap (v2). |
| v2.md | Consolidated v2 breaking / deprecation notes (engine, safe-outputs, timeout, artifacts, GitHub transport). |
| task-format.md | .wm/config.yml, .wm/tasks/<name>.md frontmatter, on: trigger semantics, safe-outputs:. |
| cli-reference.md | Every gh wm / gh-wm subcommand, flags, and environment variables. |
| development.md | Repo layout, extension points, build/test, and conventions for contributors. |
One-sentence mental model
GitHub delivers an event → gh wm resolve lists matching task names → Actions runs gh wm run --task <name> per match; each run runs the agent (default: claude -p), then applies validated safe outputs from gh wm emit when safe-outputs: is configured.
For install and a minimal user quick start, see the repository README .