backlog-external

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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.

From ovargas/virtual-team, MIT.

More from ovargas/virtual-team