gh-workflow-manager is the subagent that owns branch, commit, push, pull request, and CI work. ~/.agents/AGENTS.md says to delegate to it by default. Three things about it are worth fixing, and one thing that looked broken is not.
Not a problem: it is version controlled
chezmoi managed does not list .config/claude/agents/, because chezmoiignore.d/common:17 ignores .config/claude. It reaches ~/.claude/agents through home/dot_claude/symlink_agents.tmpl, which points at the source tree, and git ls-files tracks the file. Recording this because reading only chezmoi managed makes it look hand-placed and unmanaged.
1. The two adapters describe the agent differently
| Adapter |
description |
home/dot_config/claude/agents/gh-workflow-manager.md |
GitHub and pull request workflow agent. |
~/.codex/agents/gh-workflow-manager.toml |
Manage isolated branches, commits, pushes, pull requests, and CI verification. |
Same agent, same shared body, two different answers to "when should this run".
2. The description is what decides delegation, and it has never been measured
Claude Code delegates on the description field:
Claude uses each subagent's description to decide when to delegate tasks.
Claude automatically delegates tasks based on the task description in your request, the description field in subagent configurations, and current context.
To encourage proactive delegation, include phrases like "use proactively" in your subagent's description field.
The Claude-side description is one clause and names no triggering condition. The body's own ## Scope section is far more specific:
Handle GitHub issue/PR investigation, branch/commit/push/PR operations, PR description upkeep, and CI verification.
Every skill in shunk031/skills has its description scrutinised and gated by trigger cases. This subagent's description has had neither, while doing the same job — deciding whether it fires.
Both adapters should say the same thing, in the shape the documentation asks for.
3. There is no adversarial review step in the workflow
Over one long session, reviewing a finished change with codex exec --model gpt-5.6-sol -c model_reasoning_effort=medium — asked only for what the change missed — produced eight findings after the change had been reported as complete. One was a regression the change itself introduced: removing scripts/agent_guidance_eval.py$ from a CI path filter removed the only scripts/ entry, so no change under scripts/ ran the test matrix, including the test runner that workflow executes.
A second review of a different change found a published-site defect that had nothing to do with that change: mkdocs.yml enabled no fence extension, so ``` blocks were parsed as Markdown and #!/usr/bin/env python3 was rendering as a heading on the live site. `--strict` passed throughout, because it checks links.
Two models found overlapping but different sets — gpt-5.5 found six, gpt-5.6-sol found five, two in common. One review is not enough either.
The step belongs in the shared body at ~/.agents/agents/gh-workflow-manager.md, before the pull request body is written. The body only loads into the subagent's context, so this costs the main agent nothing.
It should also state what to do when the session cannot delegate: some harnesses forbid launching subagents, and the procedure is the same whether or not it runs in one.
Not proposed
Putting this in a skill. A skill body loads into the main agent's context, and delegation is decided by the subagent's own description — so a skill instructing "delegate to the subagent" adds a second probabilistic hop and pollutes the context it was meant to keep clean. The subagent already fires on its own description; that is the mechanism to fix, not to wrap.
Distributing the agent through the .claude-plugin manifest in shunk031/skills is a separate question, and blocked on the fact that that manifest also declares "skills": "./skills/" — installing it would deliver the same eighteen skills a second time, alongside the ones the dotfiles allowlist already installs.
gh-workflow-manageris the subagent that owns branch, commit, push, pull request, and CI work.~/.agents/AGENTS.mdsays to delegate to it by default. Three things about it are worth fixing, and one thing that looked broken is not.Not a problem: it is version controlled
chezmoi manageddoes not list.config/claude/agents/, becausechezmoiignore.d/common:17ignores.config/claude. It reaches~/.claude/agentsthroughhome/dot_claude/symlink_agents.tmpl, which points at the source tree, andgit ls-filestracks the file. Recording this because reading onlychezmoi managedmakes it look hand-placed and unmanaged.1. The two adapters describe the agent differently
descriptionhome/dot_config/claude/agents/gh-workflow-manager.mdGitHub and pull request workflow agent.~/.codex/agents/gh-workflow-manager.tomlManage isolated branches, commits, pushes, pull requests, and CI verification.Same agent, same shared body, two different answers to "when should this run".
2. The description is what decides delegation, and it has never been measured
Claude Code delegates on the
descriptionfield:The Claude-side description is one clause and names no triggering condition. The body's own
## Scopesection is far more specific:Every skill in
shunk031/skillshas its description scrutinised and gated by trigger cases. This subagent's description has had neither, while doing the same job — deciding whether it fires.Both adapters should say the same thing, in the shape the documentation asks for.
3. There is no adversarial review step in the workflow
Over one long session, reviewing a finished change with
codex exec --model gpt-5.6-sol -c model_reasoning_effort=medium— asked only for what the change missed — produced eight findings after the change had been reported as complete. One was a regression the change itself introduced: removingscripts/agent_guidance_eval.py$from a CI path filter removed the onlyscripts/entry, so no change underscripts/ran the test matrix, including the test runner that workflow executes.A second review of a different change found a published-site defect that had nothing to do with that change:
mkdocs.ymlenabled no fence extension, so ``` blocks were parsed as Markdown and#!/usr/bin/env python3was rendering as a heading on the live site. `--strict` passed throughout, because it checks links.Two models found overlapping but different sets —
gpt-5.5found six,gpt-5.6-solfound five, two in common. One review is not enough either.The step belongs in the shared body at
~/.agents/agents/gh-workflow-manager.md, before the pull request body is written. The body only loads into the subagent's context, so this costs the main agent nothing.It should also state what to do when the session cannot delegate: some harnesses forbid launching subagents, and the procedure is the same whether or not it runs in one.
Not proposed
Putting this in a skill. A skill body loads into the main agent's context, and delegation is decided by the subagent's own description — so a skill instructing "delegate to the subagent" adds a second probabilistic hop and pollutes the context it was meant to keep clean. The subagent already fires on its own description; that is the mechanism to fix, not to wrap.
Distributing the agent through the
.claude-pluginmanifest inshunk031/skillsis a separate question, and blocked on the fact that that manifest also declares"skills": "./skills/"— installing it would deliver the same eighteen skills a second time, alongside the ones the dotfiles allowlist already installs.