{
  "markdown": "# gh-flow-skills\n\nOne-shot compositions that carry a GitHub issue all the way to a reviewed pull\nrequest. A single-plugin marketplace: the plugin is `gh-flow`, and it owns the\n**composition** axis of the GitHub workflow — chaining the atomic skills that\nlive in the sibling repos of this family, in the right order, with the right\nstopping rules.\n\nThese are compositions, not implementations. Each step delegates to the skill\nthat owns it (`gh-issue:implement`, `gh-pr:commit`, `gh-pr:create`,\n`gh-verify:review-all`, `gh-resolve:conflict`, `gh-resolve:outdated`). Nothing\nhere reimplements an atom, and **nothing here merges a PR** — that stays a human\ndecision. `drain --merge` is the one explicit exception, and even it only\ndelegates to `gh-pr:merge-train`, whose approval and label gates still apply.\n\n## Skills\n\n| Skill | Invoke | Starts from | What it does |\n|-------|--------|-------------|--------------|\n| `issue` | `/gh-flow:issue <N> [remote]` | An issue number | Implement, commit, open the PR, run the review gate, rebase-sync, post metrics. Stops dead at the first failing step with a resume hint. |\n| `autopilot` | `/gh-flow:autopilot <spec>` | An approved spec | One step earlier: plan, file the issue, implement, open the PR, answer review comments — no approval checkpoints. Stops at review. |\n| `issue-relay` | `/gh-flow:issue-relay <N> <remote>` | An issue on a push-blocked remote | Branch, delegate the implementation, verify it, then hand the commits to `relay-merge`. |\n| `relay-merge` | `/gh-flow:relay-merge <PR>` | Commits bound for a push-blocked remote | Probe whether push actually works; only when it is genuinely blocked, relay per-commit patches through a gist with a `git am` apply-guide. |\n| `drain` | `/gh-flow:drain [owner/repo] [remote]` | A repo's open backlog | Run the whole backlog through `issue`, one issue at a time, promoting every deferred item to a new issue. Ends only when open issues and deferred items are both zero. |\n\nPick by where you are starting and whether the destination accepts a push.\n`issue` refuses to invent a spec; `autopilot` refuses to skip one; neither relay\nskill runs when a plain `git push` works; `drain` starts from a backlog that\nalready exists and refuses to finish while anything found along the way is\nsitting in a ledger instead of an issue.\n\n### Visual guides and worked examples (GitHub Pages)\n\n- `issue` — [visual guide](https://deity719.github.io/gh-flow-skills/skill-guides/issue.html) · [usage example](https://deity719.github.io/gh-flow-skills/skill-output/issue-usage.html) (issue number to reviewed PR)\n- `autopilot` — [visual guide](https://deity719.github.io/gh-flow-skills/skill-guides/autopilot.html) · [usage example](https://deity719.github.io/gh-flow-skills/skill-output/autopilot-usage.html) (approved spec to plan, issue and PR)\n- `issue-relay` — [visual guide](https://deity719.github.io/gh-flow-skills/skill-guides/issue-relay.html) · [usage example](https://deity719.github.io/gh-flow-skills/skill-output/issue-relay-usage.html) (issue on a push-blocked remote to a relayed handoff)\n- `relay-merge` — [visual guide](https://deity719.github.io/gh-flow-skills/skill-guides/relay-merge.html) · [usage example](https://deity719.github.io/gh-flow-skills/skill-output/relay-merge-usage.html) (commit range to gist patches and an apply-guide)\n\nEach page is generated from a Markdown source under\n[`docs/skill-guides/`](docs/skill-guides) and [`docs/skill-output/`](docs/skill-output).\n\n## Requirements\n\n| Need | Why |\n|------|-----|\n| `git` | All five commit, push, or format patches. |\n| `gh`, authenticated per host | Every skill binds `TARGET_HOST` + `TARGET_REPO` from the remote URL and prefixes each API call with `GH_HOST=` (dEitY719/dotfiles#1403), so GitHub Enterprise remotes work — but only if `gh` is logged into that host. `gh` reports no error when it lands on the wrong host, so this is not optional. |\n| A dedicated worktree on a feature branch | `issue` and `autopilot` refuse to run on the repo's default branch, and neither creates the worktree for you. |\n| The atomic skill plugins | `gh-issue`, `gh-pr`, `gh-verify`, `gh-resolve`. These are compositions; the steps they call live in those repos. |\n\n## Install\n\n### Claude Code\n\n```\n/plugin marketplace add dEitY719/gh-flow-skills\n/plugin install gh-flow@gh-flow-skills\n```\n\n### Codex\n\n```\ncodex plugin install dEitY719/gh-flow-skills\n```\n\n### Kimi CLI\n\n```\nkimi plugin install dEitY719/gh-flow-skills\n```\n\n### Hermes Agent\n\n```\nhermes plugins install dEitY719/gh-flow-skills\n```\n\n### OpenCode\n\nSee [`.opencode/INSTALL.md`](.opencode/INSTALL.md).\n\n### Gemini CLI / Antigravity\n\n```\ngemini extensions install https://github.com/dEitY719/gh-flow-skills\n```\n\nAntigravity (`agy`) shares `~/.gemini`, so it inherits the install.\n\n## Harness support\n\nEvery step these skills take is `git`, `gh`, or a local file edit, so the work\nitself ports cleanly. What does not port is the thing that makes them\ncompositions: `Skill()`. `issue` and `autopilot` are ordered chains of other\nskills, and a harness without a skill-invocation tool cannot run them as\nwritten. Every gap and its workaround is documented per harness in\n[`harness-skills/references/`](https://github.com/dEitY719/harness-skills/tree/main/references);\nread the one file for the harness you are on.\n\n| Skill | Claude Code | Codex | Kimi | Gemini / Antigravity | Hermes | OpenCode |\n|-------|:-----------:|:-----:|:----:|:--------------------:|:------:|:--------:|\n| `issue` | full | manual chain | manual chain | manual chain | manual chain | manual chain |\n| `autopilot` | full | manual chain | manual chain | manual chain | manual chain | manual chain |\n| `issue-relay` | full | full, verify by hand | full | full | full | full |\n| `relay-merge` | full | full, confirm in chat | full | full (Antigravity: confirm in chat) | full, confirm in chat | full, confirm in chat |\n| `drain` | full | manual chain | manual chain | manual chain | manual chain | manual chain |\n\n*manual chain* — without a `Skill` tool, print the ordered list of atomic skills\nthe chain would have invoked, run what is plain shell, and stop at the first\nstep that genuinely needs another skill. Do not inline a reimplementation of an\natom: the atom is what owns its own safety rules.\n\n*confirm in chat* — `relay-merge` must stop and ask before relaying an oversized\npatch. Kimi (`AskUserQuestion`) and Gemini CLI (`ask_user`) have a structured\nquestion tool; Codex, Hermes, Antigravity, and OpenCode do not, so ask in the\nconversation and wait for a real reply. An auto-approve session setting is not\nthe user's answer.\n\n*verify by hand* — `issue-relay` and `autopilot` delegate implementation to a\nsubagent. Read the diff and run the repo's lint and tests yourself; a worker's\ncompletion report is not evidence.\n\n## The early-stop contract\n\n`issue` and `autopilot` share one recurring failure mode: the model writes a\n\"done so far\" summary between two chained calls, and that summary reads as a\nfinal answer, so the run ends with the chain half-finished. It has recurred\nfive times across the history of these skills.\n\nThree layered guards prevent it, and all three are load-bearing:\n\n1. `--no-next-hint` on `issue`'s first delegated call, so the sub-skill's own\n   `Next:` line never appears.\n2. Zero conversational text between the chained `Skill()` calls.\n3. A harness `Stop` / `SubagentStop` hook, which lives in\n   [`dEitY719/dotfiles`](https://github.com/dEitY719/dotfiles)\n   (`claude/hooks/gh_issue_flow_stop_guard.py`,\n   `claude/hooks/devx_autopilot_stop_guard.py`) and blocks the turn while a\n   chain is still in flight.\n\nThe consequence for anyone editing this repo: the terminal report strings and\nstep markers are a **hook contract, not prose**. `gh-flow:issue complete (#<N>)`,\n`gh-flow:issue stopped at step <i>/6`, `[step:gh-flow-autopilot/<id>] OK`,\n`[OK] gh-flow:autopilot`, `[FAIL] gh-flow:autopilot` — change one without the\nmatching hook change and the regression comes straight back.\n\nThose hooks accept **only** this repo's `gh-flow:*` namespace. The\npre-migration `gh:issue-flow` / `devx-autopilot` form was dropped in Phase 4 of\nthat repo's migration (dEitY719/dotfiles#1410) and now appears in neither hook.\n\n## Shared assets\n\nThis repo owns none. Two things belong to\n[`dEitY719/harness-skills`](https://github.com/dEitY719/harness-skills) and are\nlinked, never copied:\n\n1. **Per-harness tool mappings** — `references/*-tools.md` there. One tool\n   rename must stay one edit, not fifteen.\n2. **The reusable CI workflow** — `.github/workflows/skill-check.yml` there.\n   This repo's `validate.yml` calls it with `plugin-name: gh-flow` and nothing\n   else, so a check added upstream applies here on the next run.\n\n## Layout\n\nEvery harness manifest sits at the repo root and points at one flat `./skills/`\ndirectory:\n\n```\ngh-flow-skills/\n├── skills/\n│   ├── issue/SKILL.md        + references/ + evals/\n│   ├── autopilot/SKILL.md    + references/\n│   ├── issue-relay/SKILL.md  + references/ + evals/\n│   ├── relay-merge/SKILL.md  + references/\n│   └── drain/SKILL.md        + references/ + evals/\n├── .claude-plugin/{marketplace,plugin}.json   Claude Code\n├── .codex-plugin/plugin.json                  Codex\n├── .kimi-plugin/plugin.json                   Kimi CLI\n├── .hermes-plugin/{plugin.yaml,__init__.py}   Hermes Agent\n├── .opencode/plugins/gh-flow.js + INSTALL.md  OpenCode\n├── .agents/plugins/marketplace.json           Antigravity\n├── gemini-extension.json + GEMINI.md          Gemini CLI\n├── package.json\n├── CLAUDE.md + AGENTS.md -> CLAUDE.md\n├── README.md · LICENSE\n└── .github/workflows/validate.yml\n```\n\nOnly Claude Code understands a nested `plugins/<name>/skills/` layout. The other\nfive harnesses resolve manifests at the repo root, so nesting would silently cut\nthis plugin down to Claude-Code-only. CI fails if a `plugins/` directory exists\nat all.\n\n## CI\n\n`.github/workflows/validate.yml` calls the reusable `skill-check` workflow in\n`harness-skills` with `plugin-name: gh-flow`. It enforces, among other things:\n\n- `skills/<name>/` matches the bare `name:` in that skill's frontmatter, and\n  that name carries no `:`.\n- `SKILL.md` stays at or under 100 lines — detail belongs in `references/`.\n- Skill descriptions sum to at most 5,440 characters (Codex's context budget),\n  with a 1,024-character per-description cap.\n- Every manifest agrees on the version.\n- No emoji anywhere in tracked text.\n\n## Provenance\n\nThe original four skills were extracted from\n[`dEitY719/dotfiles`](https://github.com/dEitY719/dotfiles)\n(`claude/skills/{gh-issue-flow,devx-autopilot,gh-issue-relay-flow,gh-relay-merge}`)\nas a content snapshot at source commit\n`96c90bc8d961d51d9c3286dae730e8b928afdfc8` — no history rewriting. The dotfiles\noriginals are gone: `claude/skills/` was deleted there in Phase 4-1 of that\nrepo's migration plan (dEitY719/dotfiles#1410 NF-1 / NF-3, tracking issue\ndEitY719/dotfiles#1678).\n\nThe old prefixes were stripped on the way in: `/gh:issue-flow` became\n`/gh-flow:issue`, `/devx:autopilot` became `/gh-flow:autopilot`,\n`/gh:issue-relay-flow` became `/gh-flow:issue-relay`, and `/gh:relay-merge`\nbecame `/gh-flow:relay-merge`. The plugin name already supplies the namespace at\ninvocation time.\n\n`drain` has no dotfiles ancestor — it was written here (issue #13), after a\nsession that reached \"zero open issues\" while four unresolved items lived only\nin a closing comment.\n\n## License\n\nMIT. See [`LICENSE`](LICENSE).\n",
  "bytes": 11466,
  "sha": "644fde32e4dc975d558498dd562346cc9ad7096561c23e6b5611995a82de597b",
  "repo_slug": "deity719/gh-flow-skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_deity719_gh_flow_skills_f5e8d52e/readme"
}