apd-github
/apd-github
Synchronizuje zadania pipeline'u APD z tablicą GitHub Projects skonfigurowaną w CLAUDE.md: tworzy zgłoszenia dla specyfikacji, przesuwa karty między kolumnami i zamyka je przy commicie.
- Autor
- zstevovich ↗
- Repozytorium
- claude-apd ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 11.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 4
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 11.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Synchronizuje zadania pipeline'u APD z tablicą GitHub Projects skonfigurowaną w CLAUDE.md: tworzy zgłoszenia dla specyfikacji, przesuwa karty między kolumnami i zamyka je przy commicie.
Wyzwalacze z opisu
Oryginalny opis (EN)
Use when the project has GitHub Projects configured (GITHUB_PROJECTS_URL in CLAUDE.md) and APD pipeline tasks need to sync with the board. Creates issues for specs, moves cards through columns (todo → in-progress → review → done), closes on commit. Triggers on "GitHub Projects", "issue", "board", "card", "sync", "kanban", "project board", any APD pipeline phase transition when a board URL is configured.
Jak działa
- When to use / When to skip
- Automation — gh-sync
- Prerequisite
- Pipeline → column mapping
- Procedure
- Automation
- Metrics from GitHub Projects
- Board setup recommendation
- Anti-patterns
- Examples
Podgląd SKILL.md
---
name: apd-github
description: Use when the project has GitHub Projects configured (GITHUB_PROJECTS_URL in CLAUDE.md) and APD pipeline tasks need to sync with the board. Creates issues for specs, moves cards through columns (todo → in-progress → review → done), closes on commit. Triggers on "GitHub Projects", "issue", "board", "card", "sync", "kanban", "project board", any APD pipeline phase transition when a board URL is configured.
effort: high
allowed-tools: Read Bash
---
# GitHub Projects — APD Pipeline Tracking
Maps APD pipeline phases to GitHub Projects v2 columns. Each task becomes an issue with the spec-card.md content embedded, and pipeline progress is reflected on the board.
## When to use / When to skip
**Use when:**
- The project has a GitHub Projects v2 board configured (`GITHUB_PROJECTS_URL` in CLAUDE.md)
- A pipeline phase just transitioned — sync the column
- Spec was just approved — create the issue
- Pipeline just committed — close the issue with the commit reference
**Skip when:**
- No GitHub Projects board is configured for the project
- The repo is not on GitHub (Gitlab/Bitbucket/local)
- `gh` CLI is not authenticated — escalate, don't silently skip
- The user is in a hotfix flow that bypasses the pipeline (no issue to track)
## Automation — gh-sync
Instead of manually calling `gh issue create` and `gh issue close`, use the `gh-sync` wrapper:
```bash
# Instead of manually:
bash ${CLAUDE_PLUGIN_ROOT}/plugins/apd/bin/core/gh-sync spec "User login" # creates issue + starts pipeline spec
bash ${CLAUDE_PLUGIN_ROOT}/plugins/apd/bin/core/gh-sync builder # comments on issue + starts pipeline builder
bash ${CLAUDE_PLUGIN_ROOT}/plugins/apd/bin/core/gh-sync reviewer # comments + starts reviewer
bash ${CLAUDE_PLUGIN_ROOT}/plugins/apd/bin/core/gh-sync verifier # comments + starts verifier
bash ${CLAUDE_PLUGIN_ROOT}/plugins/apd/bin/core/gh-sync done 42 abc1234 # closes issue with commit reference
bash ${CLAUDE_PLUGIN_ROOT}/plugins/apd/bin/core/gh-sync skip 42 "Hotfix" # closes with apd-skip label
bash ${CLAUDE_PLUGIN_ROOT}/plugins/apd/bin/core/gh-sync status # shows active issue
```
`gh-sync` automatically tracks the issue number for the current pipeline — you don't need to pass it at every step.
## Prerequisite
- GitHub MCP server configured in `.mcp.json`
- GitHub Projects v2 created with columns: **Spec**, **In Progress**, **Review**, **Testing**, **Done**
- `gh` CLI authenticated (`gh auth login`)
## Pipeline → column mapping
| APD step | GitHub Projects column | Action |
|----------|----------------------|--------|
| `pipeline-advance spec "Task"` | **Spec** | Create issue with spec-card.md content, add to board |
| `pipeline-advance builder` | **In Progress** | Move issue to In Progress |
| `pipeline-advance reviewer` | **Review** | Move issue to Review |
| `pipeline-advance verifier` | **Testing** | Move issue to Testing |
| Commit (successful) | **Done** | Close issue, link commit, move to Done |
| `pipeline-advance skip` | **Done** | Close issue with `skip` label |
## Procedure
### 1. Creating an issue for a new task (Spec phase)
When the orchestrator writes spec-card.md, also create a GitHub issue:
```bash
gh issue create \
--title "[APD] Task name" \
--body "$(cat <<'EOF'
## Spec card
**Goal:** One sentence.
**Effort:** max | high
**Out of scope:** What we are NOT doing.
**Acceptance criteria:**
- [ ] Criterion 1
- [ ] Criterion 2
**Affected modules:** files/layers
**Risks:** what can go wrong
**Rollback:** how to revert
---
_APD Pipeline Task — do not close manually_
EOF
)" \
--label "apd-pipeline" \
--project "{PROJECT_NAME}"
```
### 2. Moving cards through columns
Use the GitHub MCP server to move items on the board:
```
Orchestrator: Move issue #42 to the "In Progress" column on the GitHub Projects board.
```
The GitHub MCP server supports `update_project_item` for changing status.
### 3. Closing the issue on completion
After a successful commit:
```bash
gh issue close ISSUE_NUMBER --comment "Completed through APD pipeline. Commit: COMMIT_HASH"
```
### 4. Skip label
If the pipeline was skipped (hotfix):
```bash
gh issue close ISSUE_NUMBER --comment "Pipeline skipped (hotfix): REASON"
gh issue edit ISSUE_NUMBER --add-label "apd-skip"
```
## Automation
The orchestrator can automate the entire flow:
1. **On spec** → create issue + add to board in the Spec column
2. **On each `pipeline-advance` step** → move issue to the corresponding column
3. **On commit** → close issue with commit reference
4. **On skip** → close with skip label
### Example flow
```
User: Implement user login
Orchestrator:
1. Writes spec-card.md
2. → gh issue create --title "[APD] User login" --project "MyProject"
3. → pipeline-advance spec "User login"
4. Dispatches backend-builder
5. → moves issue #42 to "In Progress"
6. → pipeline-advance builder
7. Starts reviewer
8. → moves issue #42 to "Review"
9. → pipeline-advance reviewer
10. Starts verifier
11. → moves issue #42 to "Testing"
12. → pipeline-advance verifier
13. Commits
14. → gh issue close 42 --comment "Commit: abc1234"
15. → issue moves to "Done"
```
## Metrics from GitHub Projects
GitHub Projects stores card movement history. This enables:
- **Cycle time** — how long an issue takes from Spec to Done
- **Bottleneck detection** — which column holds cards the longest
- **Throughput** — how many issues are closed per day/week
This data is complementary to `pipeline-advance metrics` — GitHub provides a board-level view, pipeline provides per-step timing.
## Board setup recommendation
Create a GitHub Projects v2 board with the following columns:
| Column | Description |
|--------|-------------|
| **Backlog** | Planned tasks (not in the pipeline) |
| **Spec** | Spec card created, awaiting approval |
| **In Progress** | Builder working |
| **Review** | Reviewer examining |
| **Testing** | Verifier testing |
| **Done** | Committed and pushed |
Labels:
- `apd-pipeline` — all APD tasks
- `apd-skip` — tasks with skipped pipeline
- `human-gate` — tasks requiring approval
## Anti-patterns
- **Don't** call `gh issue create` directly when `gh-sync spec` is available **→ Do** use `gh-sync` so the issue number is tracked through the pipeline
- **Don't** open a new issue for each pipeline phase **→ Do** create one issue at spec, move it through columns, close at commit
- **Don't** silently swallow `gh` auth failures **→ Do** escalate with `gh auth login` instructions
- **Don't** close the issue with a generic "done" comment **→ Do** include the commit hash so the board links back to code
- **Don't** pull labels/columns from a hard-coded list **→ Do** read the project's column names dynamically (project owners customise them)
## Examples
**Example 1 — Full happy-path lifecycle.**
*Input:* User asks to implement "User login". No active issue; pipeline starts at spec phase.
*Output:* On each `pipeline-advance`, run the matching `gh-sync` step:
```
spec → gh-sync spec "User login" → opens #42, board column = Spec
builder → gh-sync builder → moves #42 to In Progress
reviewer → gh-sync reviewer → moves #42 to Review
verifier → gh-sync verifier → moves #42 to Testing
commit → gh-sync done 42 abc1234 → closes #42 with "Commit: abc1234"
board column = Done
```
The orchestrator never passes the issue number — `gh-sync` reads it from `.apd/pipeline/gh-issue`.
**Example 2 — Hotfix bypasses the pipeline.**
*Input:* Production incident — pipeline is skipped via `pipeline-advance skip`. Issue #57 is open in the Spec column but the work is going straight to commit.
*Output:* Close with skip label, do not move through the in-progress columns:
```
gh-sync skip 57 "Hotfix: payment processor 5xx"
→ #57 closed with comment "Pipeline skipped (hotfix): Hotfix: payment processor 5xx"
→ label `apd-skip` added
→ board column = Done
```
Cycle-time metrics still capture the skip — the board reflects reality, not the pipeline.
**Example 3 — Drift detected → escalate, don't auto-correct.**
*Input:* Orchestrator runs `gh-sync status` after a builder dispatch. Output reports issue #42 in column "Done" while the pipeline is in `builder` phase.
*Output:* Stop and escalate to the user:
```
GitHub Projects board out of sync:
- Pipeline phase: builder
- Issue #42 column: Done
Likely cause: someone closed the issue manually.
Action: confirm with user whether to reopen #42 or open a fresh issue —
do NOT silently move the card back.
```
## Exit criteria
You're done when:
- The active issue's column reflects the current pipeline phase
- On commit: issue is closed with the commit hash in the closing comment
- On skip: issue closed with `apd-skip` label and the skip reason
- The board's column-history reflects every pipeline transition (cycle-time data is preserved)
- No orphan issues — every `[APD]` issue maps to a real pipeline task or has been triaged
## Hand-off
- This skill is **complementary**, not a gate — pipeline progress is authoritative; board is the projection
- Called by orchestrator on every `pipeline-advance` step (workflow), not by humans directly
- If `gh-sync` reports an inconsistency (issue out of sync with pipeline state) → escalate to user; don't auto-correct
Pliki w paczce (4)
- SKILL.md 9 KB
- evals/01-full-lifecycle.json 1 KB
- evals/02-hotfix-skip.json 1 KB
- evals/03-drift-detected.json 1 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · zstevovich/claude-apd | 100 | MIT |
| zstevovich/claude-apd | 100 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki 59d7c7850caf (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100apd-miro
Aktualizuje tablicę Miro z pulpitem pipeline'u APD skonfigurowaną w CLAUDE.md: bieżący status, ukończone zadania, ostatnie metryki i aktywne karty specyfikacji. - 100apd-miro
Aktualizuje tablicę Miro z pulpitem pipeline'u APD w projekcie na Codex: bieżący status, ukończone zadania, ostatnie metryki i aktywne karty specyfikacji. - 90project
Zarządza tablicą kanban projektu w GitHub Projects lub Linear: tworzy karty, wybiera następne zadanie i sprawdza zgodność z kodem. - 100gh-project-sync
Uzgadnia tablicę GitHub Project (v2) z ujednoliconym plikiem tasks.yml agenta zadań: przenosi karty Todo do kolejki zadań i odsyła ukończone zadania na tablicę. - 87auto-board-task
Przerabia najwyżej położoną kartę Do zrobienia na tablicy GitHub Project: otwiera pull request, synchronizuje go z kartą i stosuje poprawki z recenzji Copilota. - 90super-board
Prowadzi autonomiczny potok z tablicy GitHub Project: od pustej tablicy do opróżnionej, przez etapy Build, QA, Review i Done.