# Gh Issue

> Fetch a GitHub issue, create a branch, implement with TDD, and open a PR

- **Type:** Skill
- **Install:** `agentstack add skill-chemaclass-agnostic-ai-gh-issue`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Chemaclass](https://agentstack.voostack.com/s/chemaclass)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Chemaclass](https://github.com/Chemaclass)
- **Source:** https://github.com/Chemaclass/agnostic-ai/tree/main/.agnostic-ai/skills/gh-issue
- **Website:** https://chemaclass.github.io/agnostic-ai/

## Install

```sh
agentstack add skill-chemaclass-agnostic-ai-gh-issue
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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).

2. **Assign yourself if unassigned**:
   ```bash
   gh issue edit  --add-assignee @me
   ```

3. **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

4. **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).

5. **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

6. **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).

7. **Run full test suite**:
   ```bash
   go test ./...
   ```
   Fix ALL failures before proceeding.

8. **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

9. **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.

10. **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`.

11. **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.

12. **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.

13. **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

14. **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.

15. **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.

16. **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](https://github.com/Chemaclass)
- **Source:** [Chemaclass/agnostic-ai](https://github.com/Chemaclass/agnostic-ai)
- **License:** MIT
- **Homepage:** https://chemaclass.github.io/agnostic-ai/

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-chemaclass-agnostic-ai-gh-issue
- Seller: https://agentstack.voostack.com/s/chemaclass
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.