
github-workflow
GitHub workflow: issues, PRs, worktrees, sub-issues
- GitHub stars
- 17
Install
/plugin install github-workflow@dapiRun it inside Claude Code after adding the marketplace with /plugin marketplace add dapi/claude-code-marketplace.
Contents
Discovered from sourceSkills 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. Сначала отметить — потом продолжать
После выполнения любого пункта/этапа/шага:
- СНАЧАЛА отметить как выполненный в issue
- ПОТОМ переходить к следующему
Проверка зависимостей
При первом использовании проверь установленные расширения:
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|')
Важные замечания
- Экранирование в sed: Если текст пункта содержит спецсимволы (
/,.,*), их нужно экранировать - Точное совпадение: Используй точный текст checkbox, включая пробелы
- Проверка результата: После изменения можно проверить
gh issue viewчто checkbox отмечен - Параллельная работа: Атомарная операция минимизирует риск конфликтов, но не исключает их полностью при одновременном редактировании одного пункта
Скачивание изображений из 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:
- Open new Claude Code session in the worktree
- 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-plansreference 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-worktreesis 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:
-
Check for
init.sh:[ -x ./init.sh ] && echo "init.sh found" -
If
init.shexists and is executable -- run it:./init.sh -
If
init.shdoes not exist -- fall back to standardusing-git-worktreeslogic
Quick Reference
| Situation | Action |
|---|---|
init.sh exists and executable | Run ./init.sh |
init.sh does not exist | Standard setup (npm/cargo/etc) |
init.sh fails | Report 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, документация |
Определение типа
-
По labels issue:
bug,fix→fixenhancement,feature→featurechore,refactor,docs,ci,dependencies→chore
-
Если labels нет — определи по заголовку/описанию issue
Формирование описания (slug)
- Lowercase
- Пробелы и спецсимволы → дефисы
- Множественные дефисы → один дефис
- Максимум 50 символов
- Убрать дефис в конце
Примеры:
feature/123-add-user-authenticationfix/456-null-pointer-in-parserchore/789-update-eslint-config
Шаги выполнения
-
Прочитай GitHub issue по ISSUE_URL:
- Номер issue
- Заголовок
- Labels (для определения типа)
- Описание (если нужно для понимания типа)
-
Проверь лейбл
progress:Если issue уже имеет лейбл
progress:- Сообщи пользователю:
⚠️ Issue уже имеет лейбл 'progress' — возможно, над ней уже ведётся работа. - Спроси: продолжить или отменить?
- Если пользователь отменяет — заверши выполнение команды
- Сообщи пользователю:
-
Сформируй имя ветки по шаблону
<тип>/<номер>-<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}" -
Создай git worktree от текущей ветки:
Сформируй переменные:
BRANCH_NAME— имя ветки из шага 3 (напримерfix/123-some-bug)WORKTREE_NAME— имя директории: замени/на-(напримерfix-123-some-bug)WORKTREE_PATH— полный путь:~/worktrees/<WORKTREE_NAME>
Выполни команды последовательно:
mkdir -p ~/worktreesgit worktree add -b "<BRANCH_NAME>" "<WORKTREE_PATH>" HEAD -
Перейди в созданный каталог:
cd <WORKTREE_PATH>С этого момента
WORKTREE_PATH— текущий рабочий каталог (CWD). Вся дальнейшая работа должна проводиться в этом каталоге. -
Создай init.sh (если не существует):
Если файл
init.shне существует в каталоге, скопируй шаблон:cp <plugin-path>/templates/init.sh ./init.shГде
<plugin-path>— путь к плагину github-workflow. -
Выполни init.sh:
./init.sh -
Отметь issue лейблом
progress:Добавь лейбл
progressк issue:gh issue edit <ISSUE_NUMBER> --add-label "progress"Если лейбл не существует в репозитории, сначала создай его:
gh label create "progress" --color "1D76DB" --description "In progress" -
Переименуй вкладку zellij:
zellij-rename-tab-to-issue-number <ISSUE_NUMBER>Скрипт безопасен: если мы не внутри zellij — ничего не произойдёт.
-
Выведи результат:
✅ Worktree создан: <WORKTREE_PATH>
Issue: <ISSUE_URL>
Ветка: <BRANCH_NAME>
- Приступи к реализации:
Убедись что текущий рабочий каталог (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 агенты нашли проблемы:
- Исправь найденные критические и важные issues
- Сделай дополнительный commit с фиксами
- Push изменения
- Перезапусти 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