Gh Issue

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

1. Parse the issue number from $ARGUMENTS (strip # if present).

1. Assign yourself if unassigned:

``bash gh issue edit --add-assignee @me ``

1. Create a branch from fresh origin/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: -

``bash git checkout main && git pull --ff-only git checkout -b ``

Phase 2: Plan

1. Enter Plan Mode to design the implementation:

• Explore the codebase to understand affected areas.
• Identify files that need changes.
• Respect adapter independence: .claude/rules/no-cross-adapter-imports.md.
• Honor the adapter skeleton: .claude/rules/adapter-pattern.md.
• Plan the TDD approach (what tests to write first).

1. Create implementation plan with:

• Summary of what the issue requires.
• List of files to create/modify.
• Test strategy (unit per package, integration under tests/integration).
• Step-by-step implementation order.

Phase 3: Implement

1. After plan approval, implement following TDD:

• Write failing tests first (*_test.go next to the code under test).
• Implement minimum code to pass.
• Refactor while keeping tests green.
• Wrap returned errors per .claude/rules/error-wrapping.md.
• Follow .claude/rules/test-conventions.md (use t.TempDir(), testutil.Chdir, behavior-named tests).

1. Run full test suite:

``bash go test ./... `` Fix ALL failures before proceeding.

1. Regenerate derived artifacts when touched:

• Edited internal/config/config.go struct tags → go run ./cmd/schemagen (see .claude/skills/regen-schema/).
• Edited specs under .agnostic-ai/ or any adapter → agnostic-ai sync then ./agnostic-ai sync --check (see .claude/skills/run-sync-check/).
• Touched code reachable from cmd/agnostic-ai-wasm → rebuild the playground (see .claude/skills/playground-rebuild/).

Phase 4: Ship

1. Update CHANGELOG.md — add an entry under ## [Unreleased], grouped as Added, Changed, Fixed, or Removed per .claude/rules/docs-sync.md. Skip only for pure refactors or test-only changes.

1. Update user docs when behavior is visible:

• New or changed flag, target, or output field → docs/user/targets.md and docs/user/configuration.md.
• New or changed spec field → docs/user/spec-format.md.
• New command or capability → README.md.

1. Commit changes using Conventional Commits (.claude/rules/conventional-commits.md):

```bash git add git commit -m "():

Related to #" `` Use ref: (not refactor:`) for refactor commits. Subject under 72 chars. Body explains why, not what. Never mention AI assistance.

1. 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 package conventions.
• violations of .claude/rules/adapter-pattern.md, no-cross-adapter-imports.md, error-wrapping.md, go-style.md, plain-english.md.
• over-engineering: speculative abstractions, premature interfaces, helpers used once.

Apply fixes. Re-run go test ./.... Commit as a separate ref(...) commit — must be the final commit on the branch before PR: ```bash git commit -m "ref(): polish after #

Related to #" ``` If review surfaces zero changes, record that fact in the PR body instead of skipping silently.

1. Push and create PR:

```bash git push -u origin gh pr create \ --assignee Chemaclass \ --label "" \ --title "(): " \ --body "$(cat

## Test plan

• [ ] go test ./...
• [ ] agnostic-ai sync --check (if specs/adapters touched)

Closes # EOF )" `` Match the label to the issue type. Use Closes #` so merge auto-closes the issue.

Phase 5: Verify & Merge

1. Wait for CI green on the PR:

``bash gh pr checks --watch ` Fix red checks on the branch (push fixes; re-watch). Do not proceed while any required check is failing. Never --no-verify` past a failing required check.

1. Merge with admin bypass when possible:

Once every required check is green: ``bash gh pr merge --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.

1. Sync local main after merge:

``bash git checkout main && git fetch origin main && git reset --hard origin/main ``

Checklist

• [ ] Issue fetched and understood (body + comments)
• [ ] Self-assigned
• [ ] Branch created from fresh origin/main
• [ ] Plan created and approved
• [ ] Tests written first (TDD)
• [ ] Implementation complete
• [ ] go test ./... passes
• [ ] Derived artifacts regenerated (schema / sync / playground) when applicable
• [ ] Changelog updated under ## [Unreleased]
• [ ] User docs updated when behavior is visible
• [ ] Feature commit with Related to #
• [ ] Final ref(...) commit (last commit on branch)
• [ ] PR created with Chemaclass assignee, matching label, Closes #
• [ ] CI green (gh pr checks --watch)
• [ ] PR merged via --admin --squash (or --auto fallback if admin blocked)
• [ ] Local main synced to origin/main

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Chemaclass
• Source: Chemaclass/agnostic-ai
• License: MIT
• Homepage: https://chemaclass.github.io/agnostic-ai/

Install and usage instructions live in the source repository linked above.