GitHub workflow: issues, PRs, worktrees, sub-issues

GitHub stars
17

Install

/plugin install github-workflow@dapi

Run it inside Claude Code after adding the marketplace with /plugin marketplace add dapi/claude-code-marketplace.

Contents

Discovered from source

Skills 3

GitHub Issues Management Skill

Управление GitHub issues через gh CLI с поддержкой sub-issues и атомарных операций над checkboxes.

КРИТИЧЕСКИЕ ПРАВИЛА

1. ВСЕГДА использовать gh, НИКОГДА WebFetch

# ПРАВИЛЬНО
gh issue view 123 -R owner/repo

# НЕПРАВИЛЬНО - НЕ ДЕЛАЙ ТАК!
# WebFetch для github.com/.../issues/...

2. Переименование вкладки zellij при начале работы с issue

Когда пользователь начинает работу с issue (читает issue, изучает задачу, обсуждает реализацию), переименуй вкладку zellij:

zellij-rename-tab-to-issue-number <ISSUE_NUMBER>

Скрипт безопасен: если мы не внутри zellij -- ничего не произойдёт.

Когда вызывать:

  • Пользователь просит прочитать/показать issue
  • Пользователь начинает обсуждать задачу из issue
  • Первое обращение к issue в сессии

Когда НЕ вызывать:

  • Отметка checkbox (мелкая операция)
  • Закрытие/открытие issue
  • Работа с labels

3. Атомарные операции с checkboxes (без кеша!)

ВАЖНО: При отметке checkbox ВСЕГДА выполняй атомарную операцию fetch→modify→push в ОДНОЙ команде. Это предотвращает конфликты при параллельной работе нескольких агентов.

# Атомарная отметка checkbox (fetch → modify → push) — ОДНОЙ СТРОКОЙ!
gh issue view 123 -R owner/repo --json body -q .body | sed 's/- \[ \] Точный текст пункта/- [x] Точный текст пункта/' | gh issue edit 123 -R owner/repo --body-file -

ВАЖНО: Команда должна быть в ОДНУ строку без \ переносов — иначе ошибка в zsh.

НИКОГДА не кешируй body issue! Всегда скачивай заново перед изменением.

4. Сначала отметить — потом продолжать

После выполнения любого пункта/этапа/шага:

  1. СНАЧАЛА отметить как выполненный в issue
  2. ПОТОМ переходить к следующему

Проверка зависимостей

При первом использовании проверь установленные расширения:

gh extension list

Если расширения отсутствуют — предложи установить:

# Для работы с sub-issues
gh extension install yahsan2/gh-sub-issue

# Для расширенного project management (опционально)
gh extension install rubrical-studios/gh-pmu

Команды

Чтение issue

# Полный вывод
gh issue view 123 -R owner/repo

# Только body (для парсинга checkboxes)
gh issue view 123 -R owner/repo --json body -q .body

# С комментариями
gh issue view 123 -R owner/repo --comments

# JSON со всеми полями
gh issue view 123 -R owner/repo --json title,body,state,labels

Редактирование issue

# Изменить заголовок
gh issue edit 123 -R owner/repo --title "Новый заголовок"

# Изменить body
gh issue edit 123 -R owner/repo --body "Новый текст"

# Body из файла или stdin
gh issue edit 123 -R owner/repo --body-file -

# Добавить labels
gh issue edit 123 -R owner/repo --add-label "in-progress"

Атомарная отметка checkbox

# Шаблон (ОДНОЙ СТРОКОЙ!):
gh issue view NUMBER -R owner/repo --json body -q .body | sed 's/- \[ \] ТОЧНЫЙ_ТЕКСТ/- [x] ТОЧНЫЙ_ТЕКСТ/' | gh issue edit NUMBER -R owner/repo --body-file -

Пример с реальным пунктом:

# Было: - [ ] Создать структуру базы данных → Стало: - [x] ...
gh issue view 45 -R dapi/myproject --json body -q .body | sed 's/- \[ \] Создать структуру базы данных/- [x] Создать структуру базы данных/' | gh issue edit 45 -R dapi/myproject --body-file -

Для пунктов с номерами:

# Было: - [ ] 1. Первый этап
gh issue view 45 -R owner/repo --json body -q .body | sed 's/- \[ \] 1\. Первый этап/- [x] 1. Первый этап/' | gh issue edit 45 -R owner/repo --body-file -

Sub-issues (требует gh-sub-issue)

# Список sub-issues родителя
gh sub-issue list 123 -R owner/repo

# Создать новый sub-issue
gh sub-issue create --parent 123 --title "Подзадача" -R owner/repo

# Связать существующий issue как sub-issue (ОДИН репозиторий)
gh sub-issue add 123 456 -R owner/repo

# Связать issue из РАЗНЫХ репозиториев — используй ПОЛНЫЕ URL!
# ВАЖНО: формат owner/repo#123 НЕ работает, только полные URL
gh sub-issue add https://github.com/owner/repo/issues/123 https://github.com/other-owner/other-repo/issues/456

# Удалить связь
gh sub-issue remove 123 456 -R owner/repo

Создание и закрытие

# Создать issue
gh issue create -R owner/repo --title "Заголовок" --body "Описание"

# Закрыть issue
gh issue close 123 -R owner/repo

# Открыть заново
gh issue reopen 123 -R owner/repo

Парсинг checkboxes

Для получения списка checkboxes из issue:

# Все checkboxes
gh issue view 123 -R owner/repo --json body -q .body | grep -E '^\s*- \[([ x])\]'

# Только невыполненные
gh issue view 123 -R owner/repo --json body -q .body | grep -E '^\s*- \[ \]'

# Только выполненные
gh issue view 123 -R owner/repo --json body -q .body | grep -E '^\s*- \[x\]'

Извлечение owner/repo из URL

# Из URL вида https://github.com/owner/repo/issues/123
# owner/repo = dapi/claude-code-marketplace
# number = 123

# Пример парсинга в bash:
URL="https://github.com/dapi/myrepo/issues/45"
REPO=$(echo "$URL" | sed -E 's|https://github.com/([^/]+/[^/]+)/issues/([0-9]+)|\1|')
NUMBER=$(echo "$URL" | sed -E 's|https://github.com/([^/]+/[^/]+)/issues/([0-9]+)|\2|')

Важные замечания

  1. Экранирование в sed: Если текст пункта содержит спецсимволы (/, ., *), их нужно экранировать
  2. Точное совпадение: Используй точный текст checkbox, включая пробелы
  3. Проверка результата: После изменения можно проверить gh issue view что checkbox отмечен
  4. Параллельная работа: Атомарная операция минимизирует риск конфликтов, но не исключает их полностью при одновременном редактировании одного пункта

Скачивание изображений из issue

Если в issue прикреплены изображения и нужно их скачать:

# Получить body и извлечь URL изображений, затем скачать каждое
gh api repos/OWNER/REPO/issues/123 --jq '.body' | grep -oP 'https://user-images\.githubusercontent\.com/[^)]+' | while read url; do
    curl -O "$url"
done

Примечание: Изображения хранятся на user-images.githubusercontent.com. Этот паттерн работает для стандартных вложений GitHub. Для изображений из других источников (внешние URL) может потребоваться модификация regex.

Примеры сценариев

Выполнить пункт из issue

# 1. Прочитать issue
gh issue view 123 -R owner/repo

# 2. Выполнить работу по пункту "Написать тесты"
# ... (выполняем работу)

# 3. СРАЗУ отметить как выполненный (атомарно, ОДНОЙ СТРОКОЙ!)
gh issue view 123 -R owner/repo --json body -q .body | sed 's/- \[ \] Написать тесты/- [x] Написать тесты/' | gh issue edit 123 -R owner/repo --body-file -

# 4. Только теперь переходить к следующему пункту

Работа с sub-issues

# 1. Проверить расширение
gh extension list | grep sub-issue || gh extension install yahsan2/gh-sub-issue

# 2. Посмотреть структуру
gh sub-issue list 123 -R owner/repo

# 3. Создать подзадачу для сложного пункта
gh sub-issue create --parent 123 --title "Реализовать API авторизации" -R owner/repo

# 4. Связать issue из ДРУГОГО репозитория как sub-issue
#    ВАЖНО: только полные URL работают для cross-repo!
gh sub-issue add https://github.com/owner/parent-repo/issues/123 https://github.com/owner/child-repo/issues/456

Plan to GitHub Issue

Save an implementation plan as a GitHub issue for execution in a separate Claude Code session.

Announce at start: "Saving implementation plan to GitHub issue."

Algorithm

Step 1: Find the plan file

Search from the git repository root:

REPO_ROOT=$(git rev-parse --show-toplevel)
ls -t "$REPO_ROOT"/docs/plans/*.md 2>/dev/null | head -1

If no plan files found, check if user specified a file path. If still nothing, report error: "No plan files found in docs/plans/. Please specify the plan file path."

Step 2: Read the plan

Read the plan file content using the Read tool.

Step 3: Gather context metadata

Run these commands to get repository and branch info:

# Repository (owner/repo format)
gh repo view --json nameWithOwner -q .nameWithOwner

# Current branch
git branch --show-current

# Working directory
pwd

Step 4: Compose the issue body

Structure the issue body as follows:

> **For Claude:** Use `superpowers:executing-plans` skill to implement this plan task-by-task.
> Start in the worktree directory shown below.

**Context**

| Field | Value |
|-------|-------|
| Repository | {owner/repo} |
| Branch | {branch-name} |
| Working directory | {pwd} |
| Plan file | {relative path to plan file} |

---

{Full plan file content}

Step 5: Extract title from plan

Parse the first # heading from the plan file as the issue title. If no heading found, use the filename (without date prefix and extension).

Step 6: Create the issue

Use --body-file - to handle large plans (avoids command-line length limits):

echo "$BODY" | gh issue create --title "{title}" --body-file - --label "plan"

If the "plan" label does not exist, create without labels:

echo "$BODY" | gh issue create --title "{title}" --body-file -

Step 7: Report result

Show the created issue URL and suggest how to use it:

"Plan saved to {issue_url}

To execute in a separate session:

  1. Open new Claude Code session in the worktree
  2. Tell Claude: 'Execute plan from {issue_url}'"

Error Handling

  • No plan file: Ask user to specify the path
  • No git repo: Report error, suggest running from within a repository
  • gh not authenticated: Suggest gh auth login
  • Label creation fails: Create issue without labels (non-blocking)

Important

  • Pipe body via echo "$BODY" | gh issue create --body-file - to preserve formatting
  • Do NOT modify the plan content, copy it as-is
  • Include the superpowers:executing-plans reference so the next session knows what skill to use

Worktree Init Script

Extends superpowers:using-git-worktrees -- after creating a worktree, runs ./init.sh if the script exists in the project root.

Core principle: Project-specific initialization via a single script replaces auto-detect heuristics.

When to Use

Automatically activates when:

  • using-git-worktrees is invoked
  • Project root contains executable init.sh

Integration with using-git-worktrees

Modifies step "Run Project Setup":

Instead of auto-detecting by package.json/Cargo.toml:

  1. Check for init.sh:

    [ -x ./init.sh ] && echo "init.sh found"
    
  2. If init.sh exists and is executable -- run it:

    ./init.sh
    
  3. If init.sh does not exist -- fall back to standard using-git-worktrees logic

Quick Reference

SituationAction
init.sh exists and executableRun ./init.sh
init.sh does not existStandard setup (npm/cargo/etc)
init.sh failsReport error, ask whether to continue

Template

A ready-made template is available at templates/init.sh in this plugin (mise, submodules, envrc, direnv).

Commands 1

Start Issue

Начни работу над GitHub issue.

Входные данные

  • ISSUE_URL: $ARGUMENTS (ссылка на GitHub issue)

Формат имени ветки

<тип>/<номер-задачи>-<описание>

Типы веток

ТипКогда использовать
featureНовая функциональность
fixИсправление бага
choreРефакторинг, зависимости, CI, документация

Определение типа

  1. По labels issue:

    • bug, fix → fix
    • enhancement, feature → feature
    • chore, refactor, docs, ci, dependencies → chore
  2. Если labels нет — определи по заголовку/описанию issue

Формирование описания (slug)

  • Lowercase
  • Пробелы и спецсимволы → дефисы
  • Множественные дефисы → один дефис
  • Максимум 50 символов
  • Убрать дефис в конце

Примеры:

  • feature/123-add-user-authentication
  • fix/456-null-pointer-in-parser
  • chore/789-update-eslint-config

Шаги выполнения

  1. Прочитай GitHub issue по ISSUE_URL:

    • Номер issue
    • Заголовок
    • Labels (для определения типа)
    • Описание (если нужно для понимания типа)
  2. Проверь лейбл progress:

    Если issue уже имеет лейбл progress:

    • Сообщи пользователю: ⚠️ Issue уже имеет лейбл 'progress' — возможно, над ней уже ведётся работа.
    • Спроси: продолжить или отменить?
    • Если пользователь отменяет — заверши выполнение команды
  3. Сформируй имя ветки по шаблону <тип>/<номер>-<slug>

    Slug формируй bash-командой (гарантирует отсутствие trailing hyphen):

    SLUG=$(echo "<title>" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g; s/-\{2,\}/-/g; s/^-//; s/-$//' | cut -c1-50 | sed 's/-$//')
    BRANCH_NAME="<тип>/<номер>-${SLUG}"
    
  4. Создай git worktree от текущей ветки:

    Сформируй переменные:

    • BRANCH_NAME — имя ветки из шага 3 (например fix/123-some-bug)
    • WORKTREE_NAME — имя директории: замени / на - (например fix-123-some-bug)
    • WORKTREE_PATH — полный путь: ~/worktrees/<WORKTREE_NAME>

    Выполни команды последовательно:

    mkdir -p ~/worktrees
    
    git worktree add -b "<BRANCH_NAME>" "<WORKTREE_PATH>" HEAD
    
  5. Перейди в созданный каталог:

    cd <WORKTREE_PATH>
    

    С этого момента WORKTREE_PATH — текущий рабочий каталог (CWD). Вся дальнейшая работа должна проводиться в этом каталоге.

  6. Создай init.sh (если не существует):

    Если файл init.sh не существует в каталоге, скопируй шаблон:

    cp <plugin-path>/templates/init.sh ./init.sh
    

    Где <plugin-path> — путь к плагину github-workflow.

  7. Выполни init.sh:

    ./init.sh
    
  8. Отметь issue лейблом progress:

    Добавь лейбл progress к issue:

    gh issue edit <ISSUE_NUMBER> --add-label "progress"
    

    Если лейбл не существует в репозитории, сначала создай его:

    gh label create "progress" --color "1D76DB" --description "In progress"
    
  9. Переименуй вкладку zellij:

    zellij-rename-tab-to-issue-number <ISSUE_NUMBER>
    

    Скрипт безопасен: если мы не внутри zellij — ничего не произойдёт.

  10. Выведи результат:

✅ Worktree создан: <WORKTREE_PATH>
 Issue: <ISSUE_URL>
 Ветка: <BRANCH_NAME>
  1. Приступи к реализации:

Убедись что текущий рабочий каталог (CWD) = <WORKTREE_PATH>.

Вызови Skill tool:

  • skill: "task-router:route-task"
  • args: "<ISSUE_URL> --new-session"

Флаг --new-session сообщает task router, что мы уже в выделенной сессии (новая вкладка). Task router автоматически классифицирует задачу и запустит подходящий workflow (feature-dev или subagent-driven-dev).


Завершение задачи

Когда считаешь задачу завершённой, выполни следующие шаги:

12. Commit, Push и создание PR

Используй skill commit-commands:commit-push-pr для:

  • Коммита всех изменений
  • Push в remote
  • Создания Pull Request
/commit-commands:commit-push-pr

⚠️ ВАЖНО: Формат коммитов и PR должен содержать номер issue!

Формат commit message:

<тип>: <описание> (#<номер-issue>)

[опционально: детали изменений]

Refs #<номер-issue>

Примеры:

  • feat: add user authentication (#123)
  • fix: resolve null pointer in parser (#456)
  • chore: update eslint config (#789)

Формат PR:

  • Title: <тип>: <краткое описание> (#<номер-issue>)
  • Body: Обязательно включи Closes #<номер-issue> для автоматического закрытия issue при merge

13. Параллельный запуск Code Review агентов

После создания PR ОБЯЗАТЕЛЬНО запусти review процесс используя ОБА подхода параллельно:

Вариант A — Skill для комплексного PR review:

/pr-review-toolkit:review-pr

Вариант B — Task tool с параллельными агентами: Запусти следующие агенты одновременно через Task tool:

  • pr-review-toolkit:code-reviewer — проверка кода на соответствие стандартам
  • pr-review-toolkit:pr-test-analyzer — анализ покрытия тестами
  • pr-review-toolkit:silent-failure-hunter — поиск скрытых ошибок
  • pr-review-toolkit:comment-analyzer — проверка комментариев

Пример запуска параллельных агентов:

[Task tool: subagent_type="pr-review-toolkit:code-reviewer", prompt="Review PR for code quality"]
[Task tool: subagent_type="pr-review-toolkit:pr-test-analyzer", prompt="Analyze test coverage"]
[Task tool: subagent_type="pr-review-toolkit:silent-failure-hunter", prompt="Hunt for silent failures"]
[Task tool: subagent_type="pr-review-toolkit:comment-analyzer", prompt="Review code comments"]

14. Исправление найденных проблем

Если review агенты нашли проблемы:

  1. Исправь найденные критические и важные issues
  2. Сделай дополнительный commit с фиксами
  3. Push изменения
  4. Перезапусти review (повтори шаг 13)

Повторяй цикл fix → commit → push → review пока все критические проблемы не будут устранены.

15. Финализация

После успешного прохождения review:

  • Убедись что все CI checks прошли
  • PR готов к merge

Вывод:

✅ Задача завершена!
 Issue: <ISSUE_URL>
 PR: <PR_URL>
✔️ Review: passed

Sponsors

Details

Marketplace
dapi/claude-code-marketplace
Source
github-workflow
Category
Community

More from dapi/claude-code-marketplace

All 12