|
| 1 | +--- |
| 2 | +name: issue-workflow |
| 3 | +description: Drive a single GitHub issue from "open on main" through branch → commits → PR → CI green → squash-merge → issue closed → main synced. Replaces the old scripts/issue-workflow.sh. Use when the user says "work on issue #N", "implement issue #N", "finish issue #N", "next issue", or asks to start a feature/fix branch tied to a specific issue number. |
| 4 | +--- |
| 5 | + |
| 6 | +# issue-workflow |
| 7 | + |
| 8 | +Drive one GitHub issue through the full branch → PR → merge → cleanup |
| 9 | +loop. This skill is the AI-equivalent of the old `scripts/issue-workflow.sh` |
| 10 | +shell script: instead of imperative bash, it produces a tracked list of |
| 11 | +tasks the assistant walks through one at a time. |
| 12 | + |
| 13 | +The skill encodes the project conventions in [`CONTRIBUTING.md`](../../CONTRIBUTING.md): |
| 14 | +- branch off `main`, keep `main` clean |
| 15 | +- one logical change per PR |
| 16 | +- Conventional Commits (`type(scope): subject`) |
| 17 | +- squash-merge, source branch deleted on merge |
| 18 | +- PR title = first commit subject |
| 19 | +- allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert` |
| 20 | +- allowed scopes: `detector`, `manager`, `packages`, `node`, `config`, `ui`, `platform`, `cli`, `deps`, `release`, `ci`, `docs`, `lint` |
| 21 | +- every PR body must reference its source issue via `Closes #N` or `Refs #N` |
| 22 | + |
| 23 | +## When to invoke |
| 24 | + |
| 25 | +The user explicitly asks to work on an issue by number, or says |
| 26 | +"next issue" / "finish the open issue" / "implement #N". Do not invoke |
| 27 | +this skill for ad-hoc exploratory work or for changes that don't have |
| 28 | +a tracking issue — open an issue first. |
| 29 | + |
| 30 | +## Inputs to collect up front |
| 31 | + |
| 32 | +Before doing anything, ask the user (use `AskUserQuestion` if more than |
| 33 | +one is ambiguous): |
| 34 | + |
| 35 | +1. **Issue number** — the only required input. If the user says "next |
| 36 | + issue", find the lowest-numbered open issue via `gh issue list |
| 37 | + --state open --limit 1 --json number,title`. |
| 38 | +2. **Type / scope / slug** — for branching. Try to derive these from |
| 39 | + the issue title (it should follow `type(scope): subject` per |
| 40 | + CONTRIBUTING.md). If the title doesn't match, ask the user to |
| 41 | + rename it OR to pass the three explicitly. |
| 42 | + |
| 43 | + Slug rules: lowercase, non-alnum → `-`, trim leading/trailing `-`. |
| 44 | + Branch name is `<type>/<scope>/<slug>`. |
| 45 | + |
| 46 | +## Workflow (in order) |
| 47 | + |
| 48 | +Create one `TaskCreate` per step below, mark `in_progress` when you |
| 49 | +start it, `completed` when done. Don't skip steps. If a step fails, |
| 50 | +stop and surface the failure to the user — do not paper over it. |
| 51 | + |
| 52 | +### 1. Inspect the issue |
| 53 | + |
| 54 | +`gh issue view <N> --json title,state,labels,body,number` |
| 55 | + |
| 56 | +Confirm `state == OPEN`. If closed, tell the user and stop. Skim the |
| 57 | +body for scope, linked issues, and any "Out of scope" notes. |
| 58 | + |
| 59 | +### 2. Sync local main |
| 60 | + |
| 61 | +``` |
| 62 | +git fetch origin main --quiet |
| 63 | +git checkout main |
| 64 | +git pull --ff-only origin main |
| 65 | +``` |
| 66 | + |
| 67 | +If `git pull` refuses (non-fast-forward), stop and tell the user — do |
| 68 | +not force. |
| 69 | + |
| 70 | +### 3. Create the feature branch |
| 71 | + |
| 72 | +`git checkout -b <type>/<scope>/<slug> origin/main` |
| 73 | + |
| 74 | +Verify with `git rev-parse --abbrev-ref HEAD` that you're on the new |
| 75 | +branch. |
| 76 | + |
| 77 | +### 4. Plan the work |
| 78 | + |
| 79 | +Before writing any code, read enough of the codebase to know: |
| 80 | +- which files this issue touches (use `Glob`/`Grep`) |
| 81 | +- what the change shape looks like (one paragraph mental summary) |
| 82 | +- what tests need to be added or updated |
| 83 | +- what docs/CHANGELOG need updating |
| 84 | + |
| 85 | +If the change is larger than ~200 lines or spans 3+ packages, surface |
| 86 | +that to the user — `CONTRIBUTING.md` says "one logical change per PR" |
| 87 | +and a too-large PR may need to be split into multiple issues. |
| 88 | + |
| 89 | +### 5. Implement + test + lint loop |
| 90 | + |
| 91 | +For each logical chunk of work: |
| 92 | +- write the change |
| 93 | +- `go build ./...` |
| 94 | +- `go vet ./...` |
| 95 | +- `go test ./...` (or scoped to the package) |
| 96 | +- `gofmt -l .` (no diffs) |
| 97 | +- commit with a Conventional Commits subject that matches the PR |
| 98 | + title the user wants |
| 99 | + |
| 100 | +Subject must match `^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-z]+\))?!?: .{1,100}$`. |
| 101 | +Body lines ≤100 cols. Footer for `Refs #N` / `BREAKING CHANGE:` etc. |
| 102 | + |
| 103 | +Commit author should be the assistant's Co-Authored-By line per the |
| 104 | +project's commit style. |
| 105 | + |
| 106 | +### 6. Run `make ci` |
| 107 | + |
| 108 | +`make ci` runs `tidy` + `vet` + `test` + `golangci-lint`. Must be green |
| 109 | +before opening the PR. If `golangci-lint` complains, fix the lint |
| 110 | +issues — don't suppress. |
| 111 | + |
| 112 | +### 7. Generate the PR body |
| 113 | + |
| 114 | +Use the template at `.github/PULL_REQUEST_TEMPLATE.md`. Fill in: |
| 115 | +- `## Summary` — one or two sentences, end with `Closes #N` |
| 116 | +- `## Linked issues` — `Closes #N` |
| 117 | +- `## Type of change` — check the matching box |
| 118 | +- `## Checklist` — leave unchecked only the ones the user hasn't done |
| 119 | +- `## Scope notes` — anything intentionally left out |
| 120 | +- `## Screenshots / output` — if user-facing output changed |
| 121 | + |
| 122 | +### 8. Push and open the PR |
| 123 | + |
| 124 | +``` |
| 125 | +git push -u origin <branch> |
| 126 | +gh pr create --base main --head <branch> \ |
| 127 | + --title "<first commit subject>" \ |
| 128 | + --body-file /tmp/pr-body-<N>.md |
| 129 | +``` |
| 130 | + |
| 131 | +Capture the PR number from the output. |
| 132 | + |
| 133 | +### 9. Watch CI |
| 134 | + |
| 135 | +`gh pr checks <N> --watch --fail-fast --interval 30` |
| 136 | + |
| 137 | +Don't poll in a loop. Don't run multiple `gh pr checks` in parallel. |
| 138 | +If a check fails, read the failure log, fix it, push an amendment, |
| 139 | +re-run. |
| 140 | + |
| 141 | +### 10. Address review comments |
| 142 | + |
| 143 | +If a reviewer (human or bot like Copilot) leaves comments on the PR, |
| 144 | +read each one, decide whether to apply the fix or push back with a |
| 145 | +rationale. Don't blindly accept suggestions — apply the ones that |
| 146 | +improve the code, push back on the ones that don't. |
| 147 | + |
| 148 | +### 11. Squash-merge |
| 149 | + |
| 150 | +``` |
| 151 | +gh pr merge <N> --squash --delete-branch |
| 152 | +``` |
| 153 | + |
| 154 | +If the repo's branch policy refuses, retry with `--admin` and tell |
| 155 | +the user you used admin override. |
| 156 | + |
| 157 | +### 12. Verify the issue closed |
| 158 | + |
| 159 | +`gh issue view <N> --json state,stateReason` |
| 160 | + |
| 161 | +If `stateReason == COMPLETED` and the linked PR shows in |
| 162 | +`closedByPullRequestReferences`, you're done. If the issue is still |
| 163 | +open, the PR body is missing `Closes #N` — fix the PR description |
| 164 | +with `gh pr edit <N> --body-file ...` and re-check. |
| 165 | + |
| 166 | +### 13. Sync local main and clean up |
| 167 | + |
| 168 | +``` |
| 169 | +git checkout main |
| 170 | +git pull --ff-only origin main |
| 171 | +git branch -d <branch> # local cleanup |
| 172 | +``` |
| 173 | + |
| 174 | +If `git branch -d` refuses (branch not fully merged), the squash-merge |
| 175 | +didn't actually merge — go back to step 11. |
| 176 | + |
| 177 | +### 14. Recurse to the next open issue |
| 178 | + |
| 179 | +Find the next open issue (lowest number that is still OPEN and not |
| 180 | +blocked). Tell the user what the next issue is and ask whether to |
| 181 | +continue. |
| 182 | + |
| 183 | +## Failure modes to handle |
| 184 | + |
| 185 | +| Symptom | What to do | |
| 186 | +|---|---| |
| 187 | +| Issue title doesn't match `type(scope): …` | Ask user to rename it, OR pass `--type/--scope/--slug` explicitly | |
| 188 | +| `git pull --ff-only` fails | Stop — `main` has diverged. Tell user. | |
| 189 | +| `golangci-lint` reports a finding | Fix the code, don't suppress | |
| 190 | +| `gh pr create` errors about base branch policy | The repo requires admin merge — use `--admin` on step 11 | |
| 191 | +| Reviewer comment is wrong or out-of-scope | Push back politely with rationale in a reply | |
| 192 | +| Squash-merge silently fails | Check `gh pr view <N> --json state` — likely blocked by CI | |
| 193 | +| Issue didn't auto-close | PR body missing `Closes #N`. Edit with `gh pr edit`. | |
| 194 | +| `git branch -d` says branch not fully merged | Squash-merge didn't actually merge — investigate | |
| 195 | + |
| 196 | +## Output expectations |
| 197 | + |
| 198 | +When the skill completes successfully, summarize in one short message: |
| 199 | + |
| 200 | +``` |
| 201 | +Issue #N closed via PR #M. |
| 202 | +Branch: <branch> |
| 203 | +Squash-merge: <short-sha> |
| 204 | +Next open issue: #<next> — <title> |
| 205 | +Want me to start on it? |
| 206 | +``` |
| 207 | + |
| 208 | +## Why this is a skill and not a bash script |
| 209 | + |
| 210 | +The old `scripts/issue-workflow.sh` was 265 lines of bash that: |
| 211 | +- parsed Conventional Commits titles with bash regex (fragile) |
| 212 | +- called `gh` directly (coupled contributor machines to GitHub auth) |
| 213 | +- embedded `gh pr checks --watch` in a `sleep 600; kill $watch_pid` |
| 214 | + pattern that crashed the IDE when paged output interleaved with |
| 215 | + other terminal tabs |
| 216 | +- made every contributor's shell the orchestration layer |
| 217 | + |
| 218 | +This skill moves orchestration into the AI: the assistant reads the |
| 219 | +issue, plans the change, edits files, runs validation, opens the PR, |
| 220 | +reads review comments, and merges. No contributor shell needed. |
| 221 | +The shell is just the place commands execute, not the place workflows |
| 222 | +are encoded. |
0 commit comments