GitHub Issue Workflow
Context
Read both the issue body and every comment as requirements input. Maintainer follow-ups frequently add scope, edge cases, or override the original description; when a later comment conflicts with the body, prefer the comment.
!gh issue view ${ARGUMENTS#\#} --json number,url,title,body,labels,assignees,state,comments 2>/dev/null || echo "Provide an issue number"
Instructions
Phase 1: Setup
Parse the issue number from $ARGUMENTS (strip # if present)
Assign yourself if unassigned:
gh issue edit <number> --add-assignee @me
Create a branch from main based on the issue type:
Determine the branch prefix from labels:
bug → fix/
enhancement → feat/
documentation → docs/
- No label →
feat/ (default)
Branch name format: <prefix><issue-number>-<slug>
git checkout main && git pull
git checkout -b <branch-name>
Phase 2: Plan
Enter Plan Mode to design the implementation:
- Explore the codebase to understand affected areas
- Identify files that need changes
- Consider the module rule from
.claude/rules/plugin-architecture.md: a module's
entry points live at its root, its internals in subfolders. Registered classes go at
the root of the module that owns them.
- Plan the TDD approach (what tests to write first): unit tests under
src/test/kotlin/org/phellang/unit/, integration under .../integration/
Create implementation plan with:
- Summary of what the issue requires
- List of files to create/modify
- Test strategy (unit, integration)
- Step-by-step implementation order
Phase 3: Implement
After plan approval, implement following TDD:
- Write failing tests first
- Implement minimum code to pass
- Refactor while keeping tests green
Run full test suite:
./gradlew test
Fix ALL errors before proceeding. If .flex / .bnf changed, run
./gradlew generatePhelLexer generatePhelParser and commit the regenerated
src/main/gen/ sources. If NamespaceConfig.kt changed, run ./gradlew updatePhelRegistry.
Note: the integration suite is nondeterministically flaky. A failure that does not
reproduce in an isolated targeted run is not a real failure — confirm before chasing it.
Phase 4: Ship
Update CHANGELOG.md — add entry under ## Unreleased, only if the file exists.
It does not exist yet in this repo (that is issue #213); skip this step until it does.
Commit changes:
git add <specific-files>
git commit -m "<type>(<scope>): <description>
Related to #<issue-number>"
Final refactor commit (mandatory, last commit before PR):
Re-review every file touched by this change. Look for:
- duplication introduced by the new code (extract or reuse)
- dead branches, unused params, leftover debug
- naming drift vs. surrounding module conventions
- violations of
.claude/rules/plugin-architecture.md (module rule, package
boundaries enforced by ArchitectureBoundaryTest), lexer-parser.md,
completion-registry.md, testing.md
- over-engineering: speculative abstractions, premature interfaces
Apply fixes. Re-run ./gradlew test. Commit as a separate ref(...) commit — must be the final commit on the branch before PR:
git commit -m "ref(<scope>): polish <area> after #<issue-number>
Related to #<issue-number>"
If review surfaces zero changes, record that fact in the PR body instead of skipping silently.
Create PR. Push with tracking, then open it with a summary and test plan.
Per .claude/rules/git-workflow.md: assign JesusValeraDev, add the label matching
the issue, and use Closes #<issue-number> so the issue auto-closes on merge.
git push -u origin <branch-name>
gh pr create \
--assignee JesusValeraDev \
--label <label-from-issue> \
--title "<type>: <description>" \
--body "<summary>
## Test plan
<verification steps>
Closes #<issue-number>"
Never reference an AI assistant in the PR title, body, or trailers.
Phase 5: Verify & Merge
Wait for CI green on the PR:
gh pr checks <pr-number-or-branch> --watch
Fix red checks on the branch (push fixes; re-watch). Do not proceed while any required check is failing.
Merge with mandatory approval bypass when possible:
Once every required check is green, merge via admin bypass to satisfy the mandatory-approval rule:
gh pr merge <pr-number> --squash --admin --delete-branch
If --admin is rejected (token lacks admin, branch protection blocks bypass), fall back to --auto --squash --delete-branch and surface that the PR is awaiting human approval. Never --no-verify past a failing required check.
Sync local main after merge:
git checkout main && git fetch origin main && git reset --hard origin/main
Checklist
1---2name: gh-issue-23description: Fetch a GitHub issue, create a branch, implement with TDD, and open a PR4---56<!-- Generated by agnostic-ai -->78# GitHub Issue Workflow910## Context1112Read both the issue body **and every comment** as requirements input. Maintainer follow-ups frequently add scope, edge cases, or override the original description; when a later comment conflicts with the body, prefer the comment.1314!`gh issue view ${ARGUMENTS#\#} --json number,url,title,body,labels,assignees,state,comments 2>/dev/null || echo "Provide an issue number"`1516## Instructions1718### Phase 1: Setup19201. **Parse the issue number** from `$ARGUMENTS` (strip `#` if present)21222. **Assign yourself if unassigned**:23 ```bash24 gh issue edit <number> --add-assignee @me25 ```26273. **Create a branch** from `main` based on the issue type:2829 Determine the branch prefix from labels:30 - `bug` → `fix/`31 - `enhancement` → `feat/`32 - `documentation` → `docs/`33 - No label → `feat/` (default)3435 Branch name format: `<prefix><issue-number>-<slug>`3637 ```bash38 git checkout main && git pull39 git checkout -b <branch-name>40 ```4142### Phase 2: Plan43444. **Enter Plan Mode** to design the implementation:45 - Explore the codebase to understand affected areas46 - Identify files that need changes47 - Consider the module rule from `.claude/rules/plugin-architecture.md`: a module's48 entry points live at its root, its internals in subfolders. Registered classes go at49 the root of the module that owns them.50 - Plan the TDD approach (what tests to write first): unit tests under51 `src/test/kotlin/org/phellang/unit/`, integration under `.../integration/`52535. **Create implementation plan** with:54 - Summary of what the issue requires55 - List of files to create/modify56 - Test strategy (unit, integration)57 - Step-by-step implementation order5859### Phase 3: Implement60616. **After plan approval**, implement following TDD:62 - Write failing tests first63 - Implement minimum code to pass64 - Refactor while keeping tests green65667. **Run full test suite**:67 ```bash68 ./gradlew test69 ```70 Fix ALL errors before proceeding. If `.flex` / `.bnf` changed, run71 `./gradlew generatePhelLexer generatePhelParser` and commit the regenerated72 `src/main/gen/` sources. If `NamespaceConfig.kt` changed, run `./gradlew updatePhelRegistry`.7374 Note: the integration suite is nondeterministically flaky. A failure that does not75 reproduce in an isolated targeted run is not a real failure — confirm before chasing it.7677### Phase 4: Ship78798. **Update CHANGELOG.md** — add entry under `## Unreleased`, **only if the file exists**.80 It does not exist yet in this repo (that is issue #213); skip this step until it does.81829. **Commit changes**:83 ```bash84 git add <specific-files>85 git commit -m "<type>(<scope>): <description>8687 Related to #<issue-number>"88 ```899010. **Final refactor commit (mandatory, last commit before PR)**:91 Re-review every file touched by this change. Look for:92 - duplication introduced by the new code (extract or reuse)93 - dead branches, unused params, leftover debug94 - naming drift vs. surrounding module conventions95 - violations of `.claude/rules/plugin-architecture.md` (module rule, package96 boundaries enforced by `ArchitectureBoundaryTest`), `lexer-parser.md`,97 `completion-registry.md`, `testing.md`98 - over-engineering: speculative abstractions, premature interfaces99100 Apply fixes. Re-run `./gradlew test`. Commit as a separate `ref(...)` commit — must be the final commit on the branch before PR:101 ```bash102 git commit -m "ref(<scope>): polish <area> after #<issue-number>103104 Related to #<issue-number>"105 ```106 If review surfaces zero changes, record that fact in the PR body instead of skipping silently.10710811. **Create PR**. Push with tracking, then open it with a summary and test plan.109 Per `.claude/rules/git-workflow.md`: assign `JesusValeraDev`, add the label matching110 the issue, and use `Closes #<issue-number>` so the issue auto-closes on merge.111 ```bash112 git push -u origin <branch-name>113 gh pr create \114 --assignee JesusValeraDev \115 --label <label-from-issue> \116 --title "<type>: <description>" \117 --body "<summary>118119 ## Test plan120 <verification steps>121122 Closes #<issue-number>"123 ```124 Never reference an AI assistant in the PR title, body, or trailers.125126### Phase 5: Verify & Merge12712812. **Wait for CI green** on the PR:129 ```bash130 gh pr checks <pr-number-or-branch> --watch131 ```132 Fix red checks on the branch (push fixes; re-watch). Do not proceed while any required check is failing.13313413. **Merge with mandatory approval bypass when possible**:135 Once every required check is green, merge via admin bypass to satisfy the mandatory-approval rule:136 ```bash137 gh pr merge <pr-number> --squash --admin --delete-branch138 ```139 If `--admin` is rejected (token lacks admin, branch protection blocks bypass), fall back to `--auto --squash --delete-branch` and surface that the PR is awaiting human approval. Never `--no-verify` past a failing required check.14014114. **Sync local main** after merge:142 ```bash143 git checkout main && git fetch origin main && git reset --hard origin/main144 ```145146## Checklist147- [ ] Issue fetched and understood148- [ ] Self-assigned149- [ ] Branch created from fresh `origin/main`150- [ ] Plan created and approved151- [ ] Tests written first (TDD)152- [ ] Implementation complete153- [ ] `./gradlew test` passes154- [ ] New/moved plugin features registered in `src/main/resources/META-INF/plugin.xml`155- [ ] `src/main/gen/` regenerated and committed if `.flex` / `.bnf` changed156- [ ] Changelog updated (skip while `CHANGELOG.md` does not exist)157- [ ] Feature commit with issue reference158- [ ] Final refactor commit (last commit on branch, separate `ref(...)`)159- [ ] PR created with assignee, label, and `Closes #X`160- [ ] CI green (`gh pr checks --watch`)161- [ ] PR merged via `--admin --squash` (or `--auto` fallback if admin blocked)162- [ ] Local `main` synced to `origin/main`