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.
- Autor
- ovargas ↗
- Repozytorium
- virtual-team ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 27.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 1
Brak sygnałów. Repozytorium zmienione 27.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
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
- Prerequisites
- Configuration in stack.md
- How It Works — The Hybrid Model
- Operation Implementations
- Error Handling
- Migration: Local → External
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.