Przejdź do treści
Biblioteka skilli
Zarządzanie i produkt · Integracja z narzędziem

backlog-external

/backlog-external

Obsługuje zewnętrzny backlog w GitHub Issues, Linear, JIRA lub YouTrack, gdy stack.md wskazuje backlog external z sekcją backlog_config.

Repozytorium
virtual-team ↗
Licencja
MIT
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
1
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Obsługuje zewnętrzny backlog w GitHub Issues, Linear, JIRA lub YouTrack, gdy stack.md wskazuje backlog external z sekcją backlog_config.

Oryginalny opis (EN)

External service backlog implementation (GitHub Issues, Linear, JIRA, YouTrack). Used when stack.md has backlog external with a backlog_config section.

Jak działa

  1. Prerequisites
  2. Configuration in stack.md
  3. How It Works — The Hybrid Model
  4. Operation Implementations
  5. Error Handling
  6. Migration: Local → External
Sekcje z nagłówków SKILL.md, w oryginale · 264 linii, 1 624 słów
Podgląd SKILL.md
---
name: backlog-external
description: External service backlog implementation (GitHub Issues, Linear, JIRA, YouTrack). Used when stack.md has backlog external with a backlog_config section.
---

# Backlog External — Generic External Service Implementation

```yaml
implements: backlog
stack: external
```

This skill implements the backlog interface using an external project management service (GitHub Issues, Linear, Jira, YouTrack, etc.). It reads the service type and state mappings from `stack.md`.

**Design principle:** Local is the source of truth for documents (specs, plans, contracts). The external service is the source of truth for item status and priority ordering. This skill bridges both.

## Prerequisites

- An MCP connector for the configured service (Linear, Jira, YouTrack) **OR** the `gh` CLI for GitHub Issues
- The `backlog_config` section in `stack.md` properly configured

## Configuration in `stack.md`

```yaml
backlog: external

backlog_config:
  service: github-issues     # github-issues | linear | jira | youtrack
  project: my-org/my-repo    # GitHub: owner/repo, Linear: project slug, Jira: project key, YouTrack: project short name (e.g. WEB)
  states:
    ready: "Backlog"          # Service-specific state name for each workflow status
    doing: "In Progress"
    implemented: "In Review"
    done: "Done"
  labels:
    feature_prefix: "feat:"   # Label prefix for feature grouping (e.g., "feat:FEAT-005")
    service_prefix: "svc:"    # Label prefix for service tagging (e.g., "svc:be")
    group_prefix: "group:"    # Label prefix for story groups
  issue_type: "Story"         # Jira/YouTrack: issue type for stories (YouTrack: the "Type" field value)
```

**YouTrack example** (`states` are the values of the project's **State** field; `project` is the short name that prefixes issue IDs like `WEB-132`):

```yaml
backlog: external

backlog_config:
  service: youtrack
  project: WEB               # YouTrack project short name — issues are WEB-1, WEB-2, ...
  states:
    ready: "Open"
    doing: "In Progress"
    implemented: "In Review"
    done: "Done"
  labels:                    # YouTrack has no "labels" — these prefixes become tags via manage_issue_tags
    feature_prefix: "feat:"
    service_prefix: "svc:"
    group_prefix: "group:"
  issue_type: "Story"        # Value of the YouTrack "Type" field
```

> **YouTrack requires a connected MCP server.** JetBrains ships a built-in **Remote MCP Server** at `https://{your-instance}.youtrack.cloud/mcp` (YouTrack 2025.3+, Cloud or Server). Add it as an MCP connector (OAuth or a permanent token, `Authorization: Bearer <token>`). Its predefined tools run under **your** account permissions.

## How It Works — The Hybrid Model

**External service manages:** Item status, priority ordering, team comments/feedback, assignment, labels, sprint planning.

**Local files manage:** Document references (spec paths, plan paths).

**The bridge:** Each backlog item has an external issue ID AND a local story ID. The external issue links to the local spec file. Local operations update the external service after each status change.

---

## Operation Implementations

### General Approach

For every operation, the AI:
1. Reads `stack.md` to get the `backlog_config`
2. Determines which tools to use based on `service`:
   - **github-issues:** Use `gh` CLI commands (already available, no MCP needed)
   - **linear:** Use the Linear MCP connector tools
   - **jira:** Use the Jira MCP connector tools
   - **youtrack:** Use the YouTrack MCP connector tools
3. Translates the operation's intent into the appropriate tool call
4. The skill describes WHAT to do, not WHICH specific tool to call — the AI maps to available tools at runtime

**YouTrack tool map (JetBrains predefined MCP tools):**

| Operation intent | YouTrack MCP tool |
|---|---|
| Search / list issues | `search_issues` (YouTrack query, e.g. `project: WEB State: {Open} tag: feat:FEAT-005`) |
| Read one issue | `get_issue` |
| Discover custom field values | `get_issue_fields_schema` |
| Create issue | `create_issue` (set project short name, summary, `State`, `Type` fields) |
| Update fields / **change state** | `update_issue` (set the `State` field to the mapped value) |
| Assign | `change_issue_assignee` |
| Add tags (feature/service/group) | `manage_issue_tags` |
| Read / add comments | `get_issue_comments` / `add_issue_comment` |
| Link epic ↔ story | `link_issues` (use the `subtask` link type) |
| Log time | `log_work` |
| Find project | `find_projects` / `get_project` |

**YouTrack specifics to respect:**
- State is a **custom field**, not a separate status API — change it with `update_issue` by setting the `State` field to the value configured in `backlog_config.states`. Call `get_issue_fields_schema` first if unsure of the exact field/value names.
- YouTrack has **tags**, not labels — the `labels.*_prefix` values become tag names applied via `manage_issue_tags`.
- The external issue ID is the readable ID (e.g. `WEB-132`); use it in `docs/backlog-index.md`.

### list(filter)

**Intent:** Get items from the external service matching the filter.

- Query the external service for issues in the configured project
- Filter by state mapping (e.g., `status: ready` → query for issues in the state configured as `backlog_config.states.ready`)
- Filter by labels for feature, service, and group (using configured prefixes)
- Parse results into the standard item format: id, title, status, feature, group, order, service

**For GitHub Issues:**
```bash
gh issue list --repo {project} --state open --label "{label}" --json number,title,state,labels
```

**For Linear/Jira:** Use the appropriate MCP tool to list/search issues with the matching state and labels.

**For YouTrack:** Use `search_issues` with a YouTrack query, e.g. `project: {project} State: {states.ready} tag: {feature_prefix}{FEAT-ID}`.

**Priority ordering:** The external service's ordering is authoritative. Items are returned in the order the service provides them.

### get(id)

**Intent:** Get a single item with full metadata.

- Fetch the issue from the external service by ID
- Return metadata: title, status, labels, comments, spec path from labels/description

### get_feature_progress(feature_id)

**Intent:** Count items per status for a feature.

- Query the external service for all issues with the feature label (e.g., `feat:FEAT-005`)
- Count by state mapping
- Return counts

### next_id()

**Intent:** Generate the next story ID.

- Query the external service for all issues with story ID labels (or scan issue titles for `S-NNN` pattern)
- Return `S-{max+1}`

---

### create(items)

**Intent:** Create new issues in the external service for each backlog item.

For each item:
1. Create an issue in the external service:
   - Title: `{id}: {title}`
   - State: configured `ready` state
   - Labels: feature label, service label, group label, order label
   - Description/body: Link to the local spec file — `Spec: {spec_path}`
2. Record the external issue ID mapping (add it as a tag in the description or use labels)

**Do NOT create local `docs/backlog.md` entries.** The external service IS the backlog. However, maintain a lightweight local index file at `docs/backlog-index.md` that maps story IDs to external issue IDs for quick reference:
```markdown
# Backlog Index
| Story | External | Feature | Status |
|---|---|---|---|
| S-010 | #42 | FEAT-005 | ready |
| S-011 | #43 | FEAT-005 | ready |
```

### link_plan(ids, plan_path)

**Intent:** Record which implementation plan covers a set of items.

- Add `Plan: {plan_path}` to each issue's description, next to the spec link (replace an earlier one)

### start(id)

**Intent:** Move an item from ready to doing.

- Move the issue to the `doing` state in the external service
- Add a comment: "Started"
- Update `docs/backlog-index.md` status column

### mark_implemented(id)

**Intent:** Mark an item as code-complete, pending PR.

- Move the issue to the `implemented` state in the external service
- Add comment: "Implementation complete, pending PR"
- Update local index

### complete(id, reference)

**Intent:** Mark an item as done.

- Move the issue to the `done` state in the external service
- Add comment with PR reference: "Completed — PR #{number}" or "Completed on main"
- Update local index
- Update the parent document: if all stories for the feature are done, set the feature spec to `status: done`; for a bug item, set the bug report to `status: fixed`
- Close the plan: if every item linked to the same plan is done, set that plan to `status: done` (no plan link: close the spec's plan together with the spec)

---

### Sync Operations

These are ACTIVE for external backends:

### push_status(id, status, reference)

Update the issue status in the external service. Map the workflow status to the configured state name.

**Already called inline by start(), complete(), etc.** — this operation exists for cases where the status needs to be updated separately (e.g., fixing a stale status).

### push_summary(feature_id, title, spec_link)

Create or update a parent issue/epic in the external service:
- Title: `{feature_id}: {title}`
- Description: Link to the local spec file
- If the service supports parent-child relationships (Linear, Jira, YouTrack), set this as the parent of all story issues. For YouTrack, create the epic with `create_issue` and connect each story with `link_issues` using the `subtask` link type.

### push_stories(feature_id, items)

Same as create(items) but specifically for syncing after `/virtual-team:feature` creates stories.

### pull_comments(id)

Retrieve comments from the external issue. Present them to the AI as context:
```
Team feedback on {id}:
- [{author}] ({date}): {comment text}
- [{author}] ({date}): {comment text}
```

**Called by `/virtual-team:implement` before starting a story** — ensures the AI sees any QA feedback, PO notes, or team discussion.

### pull_priorities()

Retrieve the current issue ordering from the external service. This overrides any local ordering:
- The external service's priority/position is authoritative
- If the team reordered issues in Linear/Jira/YouTrack, that's the new priority

---

## Error Handling

- **MCP connector not available:** STOP and report: "The {service} connector is not available. Install it or switch to `backlog: local` in stack.md."
- **Authentication failure:** STOP and report: "Authentication failed for {service}. Re-authenticate the connector."
- **Issue not found:** Report and suggest creating it: "Issue {id} not found in {service}. Run `/virtual-team:contracts sync` or create it manually."
- **Rate limit:** Report and suggest waiting or switching to local temporarily.

**Never fall back to local silently.** If the external service is unavailable, tell the user explicitly. Using local as a silent fallback would cause the two sources to diverge.

---

## Migration: Local → External

To migrate from `backlog: local` to `backlog: external`:

1. Configure `backlog_config` in `stack.md`
2. Run a one-time sync: for each item in `docs/backlog.md`, create an issue in the external service
3. Generate `docs/backlog-index.md` from the sync
4. Optionally keep `docs/backlog.md` as a read-only archive (rename to `docs/backlog-archive.md`)
5. Change `stack.md` to `backlog: external`

Wersje

W bazie nie ma innych skilli o nazwie backlog-external.

Migawka bazy z 13.11.2026 · wersja paczki 7f68bb2eecc5 (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

  • 90using-tracker
    Obsługuje zgłoszenia, zadania i backlog w Linear, Jira, GitHub Issues lub lokalnych plikach, w tym tworzenie i aktualizację.
  • 100project-manager
    Obsługuje zewnętrzne narzędzia do zgłoszeń i zarządzania projektami, takie jak Linear, Jira i GitHub Issues: czyta, tworzy i aktualizuje zgłoszenia, tablice, sprinty, statusy, etykiety i kamienie milowe.
  • 100plan-backlog
    Zamienia pomysł w backlog z epikami, historyjkami z kryteriami akceptacji i podzadaniami, a po akceptacji tworzy go w trackerze, jak Jira, Linear czy GitHub Issues.
  • 90Backlog Management
    Prowadzi backlog projektu w pliku BACKLOG.md: dodaje pozycje, aktualizuje je, sprawdza i ustala priorytety.
  • 100issues-deduplication
    Usuwa duplikaty zgłoszeń w YouTrack: porządkuje trackera, łączy powiązane zgłoszenia błędów i konsoliduje je.
  • 100backlog-plan
    Planuje backlog w trybie tylko do odczytu dla Azure DevOps, GitHub i Jira: odkrywanie zadań, triaż, planowanie sprintu i wznawianie pracy bez zmian w trackerze.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.