The flow that carries one unit of work from Issue to merge. The details of each stage are held by a dedicated skill; here we define the order of the stages,
what is passed between stages, and how to resume only. The language- and stack-dependent parts are confined to a single "project check command", and everything else proceeds with git と gh alone.
Flow
| Stage | What to do | Skill used | What is passed to the next stage |
|---|---|---|---|
| 1 | Create an Issue, or choose an existing Issue | issue-create |
Issue number, completion criteria |
| 2 | Make the completion criteria the stopping condition | goal-prompt-crafter |
Completion criteria statement (with check command and limits) |
| 3 | Create a dedicated worktree and branch | worktree-workflow |
Worktree path, branch name |
| 4 | Implement and pass the check command | (project rules) | Check output, commit |
| 5 | Push and create a ready PR | worktree-workflow Phase 5 |
PR number |
| 6 | Respond to CI and review, and squash merge if safe | pr-autoloop / pr-maintainer |
merged / escalated / timeout |
| 7 | Clean up the worktree and branch | worktree-workflow Phase 6 |
Final report |
Do not ask "shall we continue?" between stages. The only cases where you stop are:
- The completion criteria cannot be determined (involves the user's intent, scope, or value judgment)
- Cannot proceed due to authentication, permissions, or network. Report with the actual error
pr-maintainerescalation / timeout was reached- The user specified "stop before the PR" or "leave it as a draft"
Do not use this flow for changes that the repository defines as not requiring a worktree and PR (documentation only, development tool chores. The exceptions section of git-workflow).
Identify the check command
The contents of "pass tests, lint, and type checks" differ by project. Search in the following order and use the first one found. Write the found command in the Issue's completion criteria and the PR body.
AGENTS.md/CLAUDE.mdCheck commands written in / README- Commands run by CI (
.github/workflows/*.ymlのrun:). Running the same thing locally as CI is the most reliable - Task runner definitions:
package.jsonのscripts(check/test/lint/typecheck)、Makefile/justfileの target、pyproject.tomltool settings - None of the above: note in the report that there are no checks, create a minimal runnable example yourself that verifies the changed behavior, and keep the output. Adding a checking mechanism is a separate Issue
Do not create a PR in a state where checks do not pass. Do not loosen checks to make them pass (changing settings, skips, suppression comments).
Key points for each stage
- Stage 1: If starting from an existing Issue, verify that the body has completion criteria. If not, add them to the Issue as a comment before proceeding.
- Stage 2: For small work that finishes in a single run, you may use the Issue's completion criteria as-is. When handing it to multi-turn autonomous execution,
goal-prompt-crafterAlso add an upper limit (number of turns, time) and invariants (the scope not to touch). - Stage 3: Put the Issue number in the branch name (
fix/issue-<n>/feat/issue-<n>)。 - Stage 4: In the commit message or the PR body, write
Closes #<n>so that the Issue closes on merge. - Stage 5: Do not make it a draft. In the PR body, write what you changed, the verification commands and their results, and what you have not verified.
- Stage 6: How to handle repositories with no review bot and repositories with no CI is decided by
pr-maintainer's "Review gate". - Stage 7: Delete only after confirming the merge. Also confirm that the Issue has been closed.
Resuming from an interruption
If the session was cut off midway or another agent takes over, determine the stage from the remaining artifacts , not from memory or the previous report. Do not redo completed stages.
gh issue view "$ISSUE" --json state,title,url # 段 1: Issue があるか、閉じていないか
git worktree list --porcelain # 段 3: worktree があるか
git -C "$WORKTREE" status --short # 段 4: 未 commit の変更
git -C "$WORKTREE" log --oneline "origin/$DEFAULT..HEAD" # 段 4: commit 済みの変更
git ls-remote --heads origin "$BRANCH" # 段 5: push 済みか
gh pr list --head "$BRANCH" --state all --json number,state,isDraft,mergedAt,url # 段 5-6: PR の状態
| Observed | Stage to resume |
|---|---|
| No Issue | 1 |
| Issue exists but no worktree or branch | 3 (or 2 for multi-turn autonomous execution) |
| Uncommitted changes in the worktree, or commits whose checks have not passed | 4 |
| Commits exist but no branch on the remote, or no PR | 5 |
| PR が open | 6 |
| PR is merged and the worktree remains | 7 |
| PR is merged and there is no worktree | Done. Output only the final report |
Before re-running outward operations (push, PR creation, merge, comments), use the commands above to check whether they have already been performed. Do not create the same PR or comment twice.
Final report
- Issue と PR の URL
- Last observed state: merged / escalated / timeout, or the stage where it stopped and the reason
- Verification commands executed and their results
- What has not been verified
Related
issue-create/goal-prompt-crafter/worktree-workflow/pr-maintainer/pr-autoloop- git-workflow rule: conditions and exceptions under which a worktree and PR are required