Skip to content

Commit abcca74

Browse files
dipto0321dipto0321Sonnet 4.6
authored
chore(ci): replace issue-workflow.sh shell script with an AI skill (#32)
The bash script encoded the branch -> PR -> merge -> cleanup loop imperatively. That orchestration belongs in the AI layer, not in a shell script contributors have to remember to call. Move it to .claude/skills/issue-workflow/SKILL.md so the AI drives the workflow with TaskCreate-tracked steps instead of bash. - Add .claude/skills/issue-workflow/SKILL.md: 14-step workflow (inspect issue, sync main, branch, plan, implement+test, make ci, PR body, push, watch CI, address review, squash-merge, verify issue closed, sync main, recurse). Encodes CONTRIBUTING.md conventions: branch off main, Conventional Commits allowed types/scopes, squash-merge, Closes #N in PR body. Includes a failure-mode table. - Delete scripts/issue-workflow.sh (265 lines of bash). - Update scripts/README.md to explain the directory is now empty and point contributors at the skill. - Update CONTRIBUTING.md PR-reference section to point at the skill instead of the script subcommand. - Update CLAUDE.md standing-orders section 2 to invoke the skill. - Rework Makefile's `next-issue` target: no longer shells out to the deleted script; prints a human-readable reminder of the CONTRIBUTING.md steps and points AI sessions at the skill. - Update .gitignore: was ignoring all of .claude/. Now ignores .claude/* and re-includes .claude/skills/ so the project-local skill is committable (and reachable after a fresh clone). .claude/settings.local.json remains ignored as before. CHANGELOG.md keeps the historical entry about the original bash script - accurate for that point in time. Co-authored-by: dipto0321 <dipto@local> Co-authored-by: Sonnet 4.6 <noreply@puku.sh>
1 parent e0ee47f commit abcca74

7 files changed

Lines changed: 298 additions & 297 deletions

File tree

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
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.

‎.gitignore‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,12 @@ node_modules/
4141
package-lock.json
4242

4343
# Tooling session metadata (not part of the project source tree).
44-
.claude/
45-
46-
.conversation-history
44+
# `.claude/skills/` is intentionally NOT ignored — it holds
45+
# project-local AI skills (e.g. issue-workflow) that should be
46+
# committed so any contributor/clone picks them up. Only the rest
47+
# of `.claude/` (e.g. session settings) is ignored.
48+
.claude/*
49+
!.claude/skills/
50+
51+
.conversation-history
52+
.puku-cli

‎CLAUDE.md‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,16 @@ Enforced by commitlint (`wagoid/commitlint-github-action@v5`). Violations block
8282
When the user says **"start the next issue"** (or any equivalent — "work on the next one", "what's next", "pick up the next issue"), treat the following as the **default, no-clarification-needed workflow**:
8383

8484
1. **Identify the next issue.** Run `gh issue list --state open --limit 30`. Pick the lowest-numbered open issue that is not a meta-tracking issue, unless the user says otherwise. If only meta-issues remain (e.g. Phase 6 cross-platform polish — issue #16), split the meta-issue into focused sub-issues first (one per concern, one PR each), then start the first sub-issue.
85-
2. **Always pass the issue number through `issue-workflow.sh`.** Use `./scripts/issue-workflow.sh start <issue#>` to branch, and `./scripts/issue-workflow.sh pr-body <issue#>` to render the PR body. The body includes `Closes #<issue#>` — **do not edit this out**. The `Closes` keyword is what auto-closes the issue when the PR is merged.
85+
2. **Use the `issue-workflow` skill.** Invoke
86+
[`.claude/skills/issue-workflow/SKILL.md`](./.claude/skills/issue-workflow/SKILL.md)
87+
to drive the full branch → PR → merge → cleanup loop. The skill
88+
creates one tracked `TaskCreate` per step (sync main, branch, plan,
89+
implement+test, PR body, push, watch CI, address review, merge,
90+
verify close, recurse). Don't re-implement the workflow inline —
91+
the skill exists so the orchestration is consistent and reviewable.
92+
The PR body the skill generates includes `Closes #<issue#>` —
93+
**do not edit this out**. The `Closes` keyword is what auto-closes
94+
the issue when the PR is merged.
8695
3. **Verify the linkage before merging.** After `gh pr create`, run `gh pr view <PR#> --json body | grep -E 'Closes|Fixes' #<issue#>'` to confirm the PR body references the issue. If it does not, edit the PR body via `gh pr edit <PR#> --body-file <new-body.md>` before merging. **Do not squash-merge a PR that is not linked to its source issue.**
8796
4. **Merge with admin override when needed.** This repo's `enforce_admins: false` means solo-author merges need `--admin`. The conventional sequence is:
8897
```bash
@@ -94,7 +103,10 @@ When the user says **"start the next issue"** (or any equivalent — "work on th
94103
5. **Verify the issue auto-closed.** After the merge, run `gh issue view <issue#> --json state --jq .state` and confirm `CLOSED`. If still `OPEN`, add the issue close manually with `gh issue close <issue#> -c "Closed by <PR#>"`.
95104
6. **Then recurse.** Re-run `gh issue list --state open --limit 30`. If another issue is queued, ask the user to confirm continuation or proceed (if the user already said "keep going", just proceed).
96105

97-
The `make next-issue` target wraps steps 1 and 2 for humans. AI sessions should drive the same script directly.
106+
The `make next-issue` target still works for human contributors who
107+
want a quick branch-off-main shortcut, but it now just prints the
108+
reminder to use the skill — it does not shell out to a bash
109+
orchestrator.
98110

99111
## Phase status
100112

‎CONTRIBUTING.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -83,9 +83,11 @@ config.manager=<name> explicitly, or omit the key for auto-detect.
8383
fine (use `--force-with-lease`).
8484
7. **Every PR must reference its source issue in the body** — use
8585
`Closes #N` (closing the issue on merge) or `Refs #N` (linked but
86-
not auto-closed). The `scripts/issue-workflow.sh pr-body` template
87-
fills this in automatically from the issue number; do not strip it.
88-
A PR without an issue reference will be sent back for revision.
86+
not auto-closed). The
87+
[`.claude/skills/issue-workflow`](./.claude/skills/issue-workflow/SKILL.md)
88+
skill fills this in automatically from the issue number when the
89+
AI generates the PR body; do not strip it. A PR without an issue
90+
reference will be sent back for revision.
8991

9092
## Local development
9193

‎Makefile‎

Lines changed: 18 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -96,20 +96,30 @@ verify: ci build ## Full pre-commit verification (CI + build)
9696

9797
# Drive a single GitHub issue from branch → PR → merge.
9898
# Usage: make next-issue ISSUE=16
99-
# Requires: gh authed for dipto0321/nodeup, conventional-commits commit on HEAD,
100-
# clean working tree. See scripts/issue-workflow.sh and [redacted].md
101-
# ("AI workflow — standing orders") for the full sequence.
99+
# For human contributors, this is a thin wrapper that prints the
100+
# standing-orders reminder. The actual orchestration is in the
101+
# `.claude/skills/issue-workflow/SKILL.md` skill for AI sessions,
102+
# or driven manually by following CONTRIBUTING.md for humans.
102103
.PHONY: next-issue
103-
next-issue: ## Drive the next open issue end-to-end (branch → PR → squash-merge)
104+
next-issue: ## Print the standing-orders reminder for ISSUE; humans drive the workflow from CONTRIBUTING.md
104105
@if [ -z "$(ISSUE)" ]; then \
105106
echo "usage: make next-issue ISSUE=<issue#>"; \
106107
exit 1; \
107108
fi
108-
./scripts/issue-workflow.sh start $(ISSUE)
109+
@echo "Issue #$(ISSUE) — drive the workflow per CONTRIBUTING.md:"
110+
@echo " 1. Sync main and create the branch:"
111+
@echo " git fetch origin main && git checkout main && git pull --ff-only origin main"
112+
@echo " git checkout -b <type>/<scope>/<slug> origin/main"
113+
@echo " 2. Implement + test + lint, commit with a Conventional Commits subject"
114+
@echo " make ci"
115+
@echo " 3. Push and open the PR:"
116+
@echo " git push -u origin <branch>"
117+
@echo " gh pr create --base main --head <branch> --title '<subject>' --body-file /tmp/pr-body-$(ISSUE).md"
118+
@echo " 4. Watch CI and merge:"
119+
@echo " gh pr checks <PR#> --watch --fail-fast"
120+
@echo " make finish-pr ISSUE=$(ISSUE) PR=<PR#>"
109121
@echo ""
110-
@echo "Now: edit code, then commit with a conventional-commits subject."
111-
@echo "When CI is green and you're ready to merge, run:"
112-
@echo " make finish-pr ISSUE=$(ISSUE)"
122+
@echo "AI sessions should invoke .claude/skills/issue-workflow/SKILL.md instead."
113123

114124
# Squash-merge the PR linked to ISSUE. Use after the branch is pushed
115125
# and CI is green. Uses --admin because branch protection requires 1

‎scripts/README.md‎

Lines changed: 30 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,36 @@
11
# scripts/
22

3-
Project-local automation. Currently:
3+
Project-local automation. Currently empty — the `issue-workflow.sh`
4+
shell script that used to live here was replaced by the
5+
[`.claude/skills/issue-workflow/SKILL.md`](../.claude/skills/issue-workflow/SKILL.md)
6+
skill, which drives a GitHub issue through branch → PR → merge →
7+
cleanup using AI-orchestrated tasks instead of bash.
48

5-
- `issue-workflow.sh` — drive a single GitHub issue through the full
6-
branch → PR → merge → cleanup loop. Three subcommands:
7-
- `start <issue#>` — sync `main` and create `<type>/<scope>/<slug>` off `origin/main`
8-
- `pr-body <issue#>` — print a `.github/PULL_REQUEST_TEMPLATE.md`-shaped body
9-
- `finish` — push, open PR, watch CI, squash-merge, delete branch, sync `main`
9+
## Why a skill (and not a Makefile target or a shell script)
1010

11-
Enforces the conventions in `CONTRIBUTING.md` (Conventional Commits,
12-
allowed types/scopes, one logical change per PR, squash-merge,
13-
source-branch deletion). See `./issue-workflow.sh --help` for details.
11+
The Makefile is for **build/test/lint/release** commands — anything
12+
that produces artifacts you can ship. A shell script for the
13+
branch → PR → merge loop is a poor fit because:
1414

15-
## Why a shell script (and not a Makefile target)
15+
- It needs to parse Conventional Commits titles (fragile in bash ERE).
16+
- It needs to call `gh` (couples the contributor's machine to GitHub
17+
auth).
18+
- It needs to watch CI and react to review comments — bash can't do
19+
that without complex polling that paged output will eventually
20+
break.
21+
- The puku editor crashes when interleaved `gh` output is paged in
22+
multiple terminal tabs (see `.conversation-history/.conversation-history-chunk4.md`
23+
section 17 for the full diagnosis).
1624

17-
The Makefile is for **build/test/lint/release** commands — anything
18-
that produces artifacts you can ship. `issue-workflow.sh` is a
19-
**git/GitHub plumbing** helper: it talks to `gh`, reads PR titles,
20-
force-pushes with `--force-with-lease`, and reshapes your local
21-
checkout. Mixing those into `make` would couple the build to GitHub
22-
auth and to `gh` being installed, which isn't true for every
23-
contributor's machine.
25+
A skill moves the orchestration into the AI: the assistant reads the
26+
issue, edits files, runs validation, opens the PR, reads review
27+
comments, and merges. The shell just executes commands, it doesn't
28+
encode the workflow.
29+
30+
## When new scripts are appropriate
31+
32+
Add a new `scripts/<name>.sh` only for **build/test/release plumbing**
33+
that needs to run on machines without an AI in the loop — e.g. CI
34+
helpers, release packaging steps, local bootstrap. For anything
35+
involving GitHub interaction or sequential decision-making, write a
36+
skill instead.

0 commit comments

Comments
 (0)