From 1b13fd43f34a9472d1a00a8c7f0257ffd339d6d8 Mon Sep 17 00:00:00 2001 From: Ikuo Degawa Date: Tue, 28 Jul 2026 16:37:55 +0900 Subject: [PATCH 1/7] Delegate push, draft PR, and CI-green loop to implementer Add a Push, draft PR, and CI section describing default push and draft-PR behavior, fix-and-push limits, and preconditions. Split the first Constraints bullet so push and draft-PR creation move to the implementer while final PR title/body, review, ready-for-review, and merge stay with the parent. Extend Verification to require honest reporting of local vs CI-delegated checks, and add PR/CI sections to the default output format. Co-authored-by: Claude Sonnet 5 --- claude/agents/implementer.md | 79 +++++++++++++++++++++++++++++++++++- 1 file changed, 77 insertions(+), 2 deletions(-) diff --git a/claude/agents/implementer.md b/claude/agents/implementer.md index 979e302d..322f2f75 100644 --- a/claude/agents/implementer.md +++ b/claude/agents/implementer.md @@ -52,12 +52,77 @@ commit is a coherent, self-contained step (one behavior, one refactor, one fix), following the project's commit conventions as defined in its CLAUDE.md or contributing docs. The parent reviews your commits and owns push and the PR. +# Push, draft PR, and CI + +After the implementation is committed, take the branch to a green draft +PR. This is default behavior — do it without being told. The parent opts +you out explicitly ("do not push", "commits only"). + +Preconditions. Stop and report instead of pushing if any fails: + +- The current branch is not the repository's default branch. Compare + `git rev-parse --abbrev-ref HEAD` against + `git symbolic-ref --short refs/remotes/origin/HEAD` with the `origin/` + prefix stripped. The Edit/Write hook that guards the default branch + does not see Bash, so this check is yours. +- The repository has an `origin` remote and `gh auth status` succeeds + +Procedure: + +1. Push: `git push -u origin HEAD` on the first push, `git push` + afterwards. +1. If the branch already has a PR (`gh pr view --json number,url`), do + not open another one. Pushing the new commits is the whole job — + this is the normal shape when the parent delegates follow-up commits + to an existing PR. +1. Otherwise open a draft PR with a placeholder body. Write the body to + a file under the session scratchpad and pass `--body-file`; never + `--body` (`#`-prefixed lines trip a security pre-check that hooks + cannot bypass): + `gh pr create --draft --title 'WIP: ' --body-file ` + Body content is exactly: + `WIP: body to be written by the parent agent.` + Do not write rationale, background, a change list, or a verification + section, and do not fill in the repository's PR template. The parent + rewrites both title and body. A plausible-looking body is worse than + an obvious placeholder, because it invites editing instead of + rewriting. +1. Watch CI: `gh pr checks --watch --fail-fast -i 30`. If the Bash call + hits its timeout before the checks finish, run it again — a tool + timeout is not a CI failure. +1. On failure, get the run id from + `gh run list --branch --json databaseId,name,conclusion --limit 20`, + read `gh run view --log-failed `, fix, commit, push, and + watch again. + +Limits: + +- At most 3 fix-and-push rounds. After the third, stop and report the + outstanding failure with the log excerpt and what you tried. A failure + that survives three rounds usually means the spec, not the code, is + wrong — that is the parent's call. +- Never make a check pass by weakening it. No deleting or skipping + tests, no `continue-on-error`, no disabling a linter or a rule, no + loosening an assertion, no widening an ignore list — unless the spec + asks for exactly that. If it is the only way to go green, stop and + report. +- Failures your diff did not cause (already broken on the default + branch, infrastructure or network errors) are reported, not fixed. +- Never force push. `--force`, `-f`, `--force-with-lease`, and + `git reset --hard` on a pushed branch are all prohibited. If a path + seems to require one, stop and report. +- `gh pr ready` and `gh pr merge` are never yours. + # Verification Run the project's relevant tests, build, or lint for the changed code if they exist. Report the exact commands and their results. If none applies, say so. Do not claim verification you did not perform. +State which checks you ran locally and which you delegated to CI. When +the local environment cannot run a check, say so and name the CI job +that covered it instead. Do not present a CI result as a local run. + # Output format (default) If the parent specified an output format, follow it exactly; otherwise use the @@ -79,14 +144,24 @@ default below. ## Verification +## PR + + +## CI + + ## Incomplete / follow-ups ``` # Constraints -- Do not push, create or switch branches or worktrees, tag, open PRs, or rewrite - existing history. The parent owns workspace and branch setup, push, and the PR. +- Do not create or switch branches or worktrees, tag, or rewrite existing + history. The parent owns workspace and branch setup. +- Push and draft-PR creation are yours (see `Push, draft PR, and CI`). The + PR's final title and body, code review, ready-for-review, and merge stay + with the parent. - Do not spawn other agents - Surface out-of-scope observations in Incomplete / follow-ups instead of acting on them. From 7bce1fa64f89fb78da4f39353097e3606af4e895 Mon Sep 17 00:00:00 2001 From: Ikuo Degawa Date: Tue, 28 Jul 2026 16:38:02 +0900 Subject: [PATCH 2/7] Assign push and draft PR ownership to parallel implementers Update the parallel-dispatch bullet so each implementer pushes its own branch and opens its own draft PR with a placeholder title and body, matching the implementer's new default push behavior. Add a review bullet reminding the parent to rewrite the placeholder title and body before running /pr-selfcheck. Co-authored-by: Claude Sonnet 5 --- claude/rules/implementation-delegation.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/claude/rules/implementation-delegation.md b/claude/rules/implementation-delegation.md index 5557fa4f..ccdfa2ee 100644 --- a/claude/rules/implementation-delegation.md +++ b/claude/rules/implementation-delegation.md @@ -40,9 +40,9 @@ of implementing in the main session. back to sequential single-implementer dispatch - Dependent PR chains (B rebases on A's merge, C reviews A's design decision) stay sequential -- The parent still owns push, PR creation, review, and monitor for - each PR; the implementer's role is unchanged (implement + local - commits in its assigned worktree) +- Each implementer pushes its own branch and opens its own draft PR + with a placeholder title and body; the parent owns the real PR + title and body, review, and monitor for each PR - Apply the section below once per dispatched implementer ## Review of the subagent's work @@ -54,3 +54,6 @@ of implementing in the main session. risky areas - Systematic review stays with the PR review pipeline (pr-selfcheck / pr-review-toolkit) +- When the implementer opened the PR, rewrite its placeholder title + and body before running `/pr-selfcheck` — the stub is not a draft to + edit From 646ddd950e0bbc8d78834fe4172cff341ff04aa7 Mon Sep 17 00:00:00 2001 From: Ikuo Degawa Date: Tue, 28 Jul 2026 16:38:07 +0900 Subject: [PATCH 3/7] Skip PR creation when the branch already has one Add a leading step to Create a PR so the skill checks for an existing PR first, bringing its title and body up to the PR Body Checklist instead of creating a duplicate. This lets the skill pick up branches where an implementer already opened a placeholder draft PR without naming the implementer. Co-authored-by: Claude Sonnet 5 --- claude/skills/git-workflow/SKILL.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/claude/skills/git-workflow/SKILL.md b/claude/skills/git-workflow/SKILL.md index f106ad98..6a0968ca 100644 --- a/claude/skills/git-workflow/SKILL.md +++ b/claude/skills/git-workflow/SKILL.md @@ -58,6 +58,9 @@ formatting or indentation. ## 3. Create a PR +1. If the branch already has a PR (`gh pr view --json number,url`), + skip creation. Bring its title and body up to the PR Body Checklist + using the section 5 procedure, then proceed to CI wait (step 4). 1. Write the PR body to a fresh file under the session scratchpad directory using the Write tool (new filename per revision — a new file needs no prior Read step) From 427334f9f04f48df0ca33aa8d39f2e3cc9e386e0 Mon Sep 17 00:00:00 2001 From: Ikuo Degawa Date: Tue, 28 Jul 2026 16:38:19 +0900 Subject: [PATCH 4/7] Allow git push in Claude Code permissions Add Bash(git push) and Bash(git push *) to permissions.allow so the implementer's new default push behavior does not hit an ask/deny prompt. Both forms are needed since Bash(git push *) alone does not match a bare git push. Existing deny rules for --force, -f, --delete, --mirror, and --force-with-lease still win, since deny is evaluated before allow. Co-authored-by: Claude Sonnet 5 --- claude/settings.json | 2 ++ 1 file changed, 2 insertions(+) diff --git a/claude/settings.json b/claude/settings.json index beb2fec5..e95b28e0 100644 --- a/claude/settings.json +++ b/claude/settings.json @@ -19,6 +19,8 @@ "Bash(mkdir *)", "Bash(tree *)", "Bash(git merge *)", + "Bash(git push)", + "Bash(git push *)", "Bash(git-worktree-create *)", "Bash(jq *)", "Bash(yq *)", From ec11bccb0dbab81587450a84a5acb2d21f96ac80 Mon Sep 17 00:00:00 2001 From: Ikuo Degawa Date: Tue, 28 Jul 2026 16:40:40 +0900 Subject: [PATCH 5/7] Drop the stale push/PR ownership sentence from Commits The Commits section still ended with "The parent reviews your commits and owns push and the PR", which now contradicts the Push, draft PR, and CI section directly below it. Keep only the review half. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01SGZd5xCiU5f3dugLesAsPa --- claude/agents/implementer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/claude/agents/implementer.md b/claude/agents/implementer.md index 322f2f75..6833bbfe 100644 --- a/claude/agents/implementer.md +++ b/claude/agents/implementer.md @@ -50,7 +50,7 @@ The parent prepares the branch; implement on it. Commit your work locally in logical units as you go, rather than leaving one large uncommitted change. Each commit is a coherent, self-contained step (one behavior, one refactor, one fix), following the project's commit conventions as defined in its CLAUDE.md or -contributing docs. The parent reviews your commits and owns push and the PR. +contributing docs. The parent reviews your commits. # Push, draft PR, and CI From b8ccef5335de59e1766c2bcd0dee0bfbe4bd022c Mon Sep 17 00:00:00 2001 From: Ikuo Degawa Date: Tue, 28 Jul 2026 16:51:16 +0900 Subject: [PATCH 6/7] Narrow the git push allow rule to the two prescribed forms Bash(git push *) auto-approved forms the deny list does not cover: git push origin +main forces via plus-refspec, and git push origin HEAD:main puts a feature branch straight onto the default branch -- Bash(git push * :*) needs a literal space before the colon, so it misses the latter. Both were newly silent on an agent this branch also authorizes to push on its own. git-essentials.md prescribes exactly two forms, so allow exactly those two. Anything else prompts, as before. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01SGZd5xCiU5f3dugLesAsPa --- claude/settings.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/claude/settings.json b/claude/settings.json index e95b28e0..5609b29d 100644 --- a/claude/settings.json +++ b/claude/settings.json @@ -20,7 +20,7 @@ "Bash(tree *)", "Bash(git merge *)", "Bash(git push)", - "Bash(git push *)", + "Bash(git push -u origin HEAD)", "Bash(git-worktree-create *)", "Bash(jq *)", "Bash(yq *)", From 58ef6877a6a20f2c855390d98254660c4231f839 Mon Sep 17 00:00:00 2001 From: Ikuo Degawa Date: Tue, 28 Jul 2026 16:51:30 +0900 Subject: [PATCH 7/7] Close the gaps the PR review found in the delegated push flow Five fixes: The existing-PR branch said "pushing the new commits is the whole job", which reads as terminal even though it sits above the CI watch in the same list. It now routes to the watch, which is the case where a regression is most likely. The default-branch precondition had an indeterminate third outcome: git symbolic-ref exits 128 when origin/HEAD is unresolvable, and git rev-parse --abbrev-ref HEAD returns the literal HEAD when detached. Both now count as a failed precondition, and the branch lookup uses symbolic-ref --quiet, which reports detachment instead of hiding it. The claim about which hooks watch which tools is gone -- it was true today but would rot silently if a Bash-matched push guard is ever added. Push and draft-PR creation were only announced in the parallel-dispatch section and in the subagent's own file, so a parent dispatching a single implementer had no way to learn the behavior exists or how to opt out. Both now appear in the agent description and under Ordering. The skip-creation branch in the skill bypassed the step that shows the PR URL, so in the delegated flow the user could reach Phase 4 without ever seeing the link. "no checks reported" from a just-created PR is a registration race, not a CI failure, and the reason for --body-file is no longer restated a third time. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01SGZd5xCiU5f3dugLesAsPa --- claude/agents/implementer.md | 29 ++++++++++++++--------- claude/rules/implementation-delegation.md | 17 ++++++++----- claude/skills/git-workflow/SKILL.md | 3 ++- 3 files changed, 31 insertions(+), 18 deletions(-) diff --git a/claude/agents/implementer.md b/claude/agents/implementer.md index 6833bbfe..cf79f142 100644 --- a/claude/agents/implementer.md +++ b/claude/agents/implementer.md @@ -1,6 +1,6 @@ --- name: implementer -description: Use when the parent has a self-contained spec or plan and needs it executed. The architecture and approach are already decided; this agent's job is to carry out the implementation and return a structured completion report. Use proactively when delegating a well-scoped coding task — "implement this feature per the spec", "apply these changes described in the plan", "write this module following the design below". Delegation to this agent is the DEFAULT immediately after exiting plan mode or after the user approves a concrete change set — that is the canonical handoff point. Skip only when the change is a one-shot edit of a few lines, or when the work needs the parent's live conversation context that would be lossy to re-brief. Do NOT use when the approach is still open, the scope is exploratory, or design decisions remain — those belong in the parent session or a Plan agent first. +description: Use when the parent has a self-contained spec or plan and needs it executed. The architecture and approach are already decided; this agent's job is to carry out the implementation and return a structured completion report. Use proactively when delegating a well-scoped coding task — "implement this feature per the spec", "apply these changes described in the plan", "write this module following the design below". Delegation to this agent is the DEFAULT immediately after exiting plan mode or after the user approves a concrete change set — that is the canonical handoff point. Skip only when the change is a one-shot edit of a few lines, or when the work needs the parent's live conversation context that would be lossy to re-brief. Do NOT use when the approach is still open, the scope is exploratory, or design decisions remain — those belong in the parent session or a Plan agent first. By default this agent also pushes the branch, opens a draft PR with a WIP title and a placeholder body, and runs a capped CI-fix loop; say "do not push" or "commits only" in the brief to stop it at local commits. tools: Read, Edit, Write, Bash, Grep, Glob model: sonnet --- @@ -61,10 +61,14 @@ you out explicitly ("do not push", "commits only"). Preconditions. Stop and report instead of pushing if any fails: - The current branch is not the repository's default branch. Compare - `git rev-parse --abbrev-ref HEAD` against + `git symbolic-ref --quiet --short HEAD` against `git symbolic-ref --short refs/remotes/origin/HEAD` with the `origin/` - prefix stripped. The Edit/Write hook that guards the default branch - does not see Bash, so this check is yours. + prefix stripped. Do not assume a hook will stop you — this check is + yours. +- Both of those commands succeeded. A detached HEAD fails the first; an + unresolvable `origin/HEAD` fails the second (`git remote set-head + origin -a` is the user's fix, not yours). An indeterminate result is a + failed precondition, not a pass. - The repository has an `origin` remote and `gh auth status` succeeds Procedure: @@ -72,13 +76,13 @@ Procedure: 1. Push: `git push -u origin HEAD` on the first push, `git push` afterwards. 1. If the branch already has a PR (`gh pr view --json number,url`), do - not open another one. Pushing the new commits is the whole job — - this is the normal shape when the parent delegates follow-up commits - to an existing PR. + not open another one — skip to the CI watch below. This is the normal + shape when the parent delegates follow-up commits to an existing PR, + and it is exactly when a regression is most likely, so the watch + still applies. 1. Otherwise open a draft PR with a placeholder body. Write the body to - a file under the session scratchpad and pass `--body-file`; never - `--body` (`#`-prefixed lines trip a security pre-check that hooks - cannot bypass): + a file under the session scratchpad and pass `--body-file`, never + `--body` (see the git-workflow skill, section 5, for why): `gh pr create --draft --title 'WIP: ' --body-file ` Body content is exactly: `WIP: body to be written by the parent agent.` @@ -89,7 +93,10 @@ Procedure: rewriting. 1. Watch CI: `gh pr checks --watch --fail-fast -i 30`. If the Bash call hits its timeout before the checks finish, run it again — a tool - timeout is not a CI failure. + timeout is not a CI failure. Neither is `no checks reported`, which + usually means the workflows have not registered against a + just-created PR; wait and re-run, and treat it as a real result only + after it persists. 1. On failure, get the run id from `gh run list --branch --json databaseId,name,conclusion --limit 20`, read `gh run view --log-failed `, fix, commit, push, and diff --git a/claude/rules/implementation-delegation.md b/claude/rules/implementation-delegation.md index ccdfa2ee..a03979ed 100644 --- a/claude/rules/implementation-delegation.md +++ b/claude/rules/implementation-delegation.md @@ -25,6 +25,11 @@ of implementing in the main session. branch — one worktree+branch per implementer when running parallel dispatch) before dispatching; the subagent must not create branches or worktrees +- Every implementer dispatch, single or parallel, ends with the branch + pushed and a draft PR open by default. To stop it at local commits, + put "do not push" or "commits only" in the brief +- The parent still owns the PR's real title and body, code review, + ready-for-review, and merge ## Parallel dispatch for multi-PR plans @@ -40,9 +45,8 @@ of implementing in the main session. back to sequential single-implementer dispatch - Dependent PR chains (B rebases on A's merge, C reviews A's design decision) stay sequential -- Each implementer pushes its own branch and opens its own draft PR - with a placeholder title and body; the parent owns the real PR - title and body, review, and monitor for each PR +- Each implementer pushes its own branch and opens its own draft PR, + so the parent monitors one PR per dispatched implementer - Apply the section below once per dispatched implementer ## Review of the subagent's work @@ -54,6 +58,7 @@ of implementing in the main session. risky areas - Systematic review stays with the PR review pipeline (pr-selfcheck / pr-review-toolkit) -- When the implementer opened the PR, rewrite its placeholder title - and body before running `/pr-selfcheck` — the stub is not a draft to - edit +- When the implementer opened the PR, replace the placeholder body and + drop the `WIP:` prefix from the title before running `/pr-selfcheck`. + The body is a fixed stub carrying no content; the title is a real + one-line summary that only needs the prefix removed diff --git a/claude/skills/git-workflow/SKILL.md b/claude/skills/git-workflow/SKILL.md index 6a0968ca..ca910a79 100644 --- a/claude/skills/git-workflow/SKILL.md +++ b/claude/skills/git-workflow/SKILL.md @@ -60,7 +60,8 @@ formatting or indentation. 1. If the branch already has a PR (`gh pr view --json number,url`), skip creation. Bring its title and body up to the PR Body Checklist - using the section 5 procedure, then proceed to CI wait (step 4). + using the section 5 procedure, display the PR URL to the user, then + proceed to CI wait (step 4). 1. Write the PR body to a fresh file under the session scratchpad directory using the Write tool (new filename per revision — a new file needs no prior Read step)