Backlog External — Generic External Service Implementation

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

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):

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):

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:

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:

# 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