AI coding agents drift. Different sessions, different agents and different people on one team need one durable contract for how work is shaped: how issues are written, how PRs reach merge, how plans become tracked work, and who may merge.
This repo is a plugin for Claude Code, OpenAI Codex CLI and OMP. It has a skill that holds the methodology, a small CLI called gdm that does the GitHub work in a deterministic way, and hooks that stop merges the owner has not allowed.
What's inside
| Part |
What it does |
| PR review loop |
Watches a set of reviewers (Copilot and humans) and CI against an explicit exit predicate. CI-only mode and a timeout for silent bots. |
| Merge authority |
human, scoped or autonomous. Hooks block merges the setting does not allow. |
| Lanes |
Lane 0 for bot and docs PRs, Lane 1 for one issue, Lane 2 for plans and cross-repo work. |
| Issue schema |
Native sub-issues, dependencies and issue types, plus a fixed body shape that gdm validate issues checks. |
| Plan to issues |
gdm plan sync turns a manifest into a sub-issue tree. It is idempotent. |
| Worktrees and stacked PRs |
One worktree per agent under ~/.github-dev-methodology/worktrees/. Stacks for dependent PR chains. |
| Opt-in features |
15 flags and three presets: pr-only, single-issue, full. |
gdm CLI |
Node 20 or newer, no dependencies. |
Install
The plugin is github-dev-methodology@gdm. The client keeps the plugin code in its own cache. Nothing is cloned into your repos.
Claude Code
claude plugin marketplace add ctxr-dev/github-dev-methodology#v1.0.1
claude plugin install github-dev-methodology@gdm
OMP
omp plugin marketplace add ctxr-dev/github-dev-methodology
omp plugin install github-dev-methodology@gdm
Restart the OMP session after install, because extensions load at startup.
Codex
codex plugin marketplace add ctxr-dev/github-dev-methodology --ref v1.0.1
codex plugin add github-dev-methodology@gdm
Then open /hooks once and trust the plugin hooks. Codex skips untrusted plugin hooks.
Other clients (skill only, no hooks and no rules)
npx skills add ctxr-dev/github-dev-methodology -g --skill github-dev-methodology -y
| Client |
Skill |
Session context or rule |
Merge guard |
| Claude Code |
Yes |
SessionStart hook |
PreToolUse hook: deny or ask |
| Codex |
Yes |
SessionStart hook |
PreToolUse hook: deny only, fails open, needs /hooks trust |
| OMP |
Yes |
Always-on rule |
Extension: deny or confirm |
npx skills clients |
Yes |
Repo AGENTS.md pointer only |
None |
Codex merge protection is best effort. Full details, including the GitHub token scopes: installation.md.
Set up a repo
Run once per repo, from the repo root. Your agent asks you for the preset, the org and the repo, then runs:
node <skill-dir>/scripts/gdm.mjs init --preset <pr-only|single-issue|full> --org <org> --repo <repo>
node <skill-dir>/scripts/gdm.mjs doctor
<skill-dir> is the folder of the github-dev-methodology skill in the client's plugin cache. In the docs, gdm means that full command.
gdm init creates .github-dev-methodology/config.json, .github-dev-methodology/.gitignore and one marked block in AGENTS.md. It changes nothing else, and running it again changes nothing. gdm doctor lists what is still missing. Commit the new files in a normal PR.
New installs use merge authority human: the agent never merges, and the hooks block it. Change merge.authority in the config if you want otherwise. See configuration.md.
Update and uninstall
| Client |
Update |
Uninstall |
| Claude Code |
Add the marketplace at the new tag, then claude plugin update github-dev-methodology@gdm |
claude plugin uninstall github-dev-methodology@gdm |
| OMP |
omp plugin upgrade github-dev-methodology@gdm, then restart the session |
omp plugin uninstall github-dev-methodology@gdm |
| Codex |
codex plugin marketplace upgrade, then add the plugin again |
codex plugin remove github-dev-methodology@gdm |
Third-party marketplace auto-update is off by default in Claude Code. Keep it off.
Migrate from v0
Version 0 was a git clone at .agents/ctxr-dev/github-dev-methodology/ with a markdown config. To move a repo:
- Install the plugin (above).
gdm config migrate <old.config.local.md> --write converts the config to .github-dev-methodology/config.json. Read stderr: every key that was not migrated is printed as not migrated: <heading or key>.
gdm init with the same preset, org and repo adds the AGENTS.md block.
- Remove the old clone
.agents/ctxr-dev/github-dev-methodology/ when git status inside it is clean, and delete the old config file.
gdm doctor must exit 0.
The full steps and the key mapping are in the "Migration from v0" section of configuration.md.
Where things live
~/.github-dev-methodology/
├── config.json user config (optional)
├── worktrees/<host>/<owner>/<repo>/<branch> branch worktrees
└── state/<host>/<owner>/<repo>/ plan ledgers, worktree owner records
<repo>/
├── AGENTS.md one marked block
└── .github-dev-methodology/
├── config.json committed settings
├── config.local.json personal overrides (gitignored)
└── .gitignore
A repo carries nothing else. There are no symlinks into repos, and the methodology does not edit the root .gitignore, CLAUDE.md, .mcp.json or .claude/settings.json.
Development
Needs Node 20 or newer. There are no npm dependencies.
npm test runs the unit tests. npm run check runs gdm validate release, which checks that docs, schema, template, hooks and versions agree. See AGENTS.md for the repo layout and rules. Release notes are in CHANGELOG.md.