backlog

Files (1)

• SKILL.md

SKILL.md (first lines)

# Backlog — Abstract Interface

This skill defines the backlog operations that commands use. It does NOT define how they're implemented — that's the job of the active backlog implementation skill (`virtual-team:backlog-local`, `virtual-team:backlog-external`, etc.), selected by the `backlog:` field in `stack.md`.

**Commands MUST reference operations from this interface, never format-specific details.** A command says "call **start(id)**" — the implementation skill decides whether that means editing a markdown file or calling an API.

## How to Load the Implementation

1. Read `stack.md` and find the `backlog:` field (default: `local` if not specified)
2. Load `skills/backlog-{value}/SKILL.md`
3. Use that skill's instructions for every backlog operation

If the `backlog:` field is missing from `stack.md`, assume `local`.

---

## Status Values

| Status | Meaning | Transition From | Transition To |
|---|---|---|---|
| **ready** | Specced and ready for work | (created) | doing |
| **doing** | Currently in progress | ready | implemented, done |
| **implemented** | Code complete, pending PR (branch flow only) | doing | done |
| **done** | Shipped | doing, implemented | (terminal) |

**Direct-to-main flow:** When working on main/master/develop, `doing` transitions directly to `done` — skip `implemented` entirely. There's no PR step.

**Branch flow:** `doing` → `implemented` → `done` (via PR merge).

---

## Read Operations

### list(filter)

Return backlog items matching the filter criteria.

**Filters:**
- `status` — one of: ready, doing, implemented, done, all
- `feature` — feature ID (e.g., `FEAT-005`)
- `service` — service tag (e.g., `be`, `fe`)
- `group` — group number within a feature
- `plan` — plan path (items linked to that plan via `link_plan`)

**Returns:** List of items, each with: id, title, status, feature, group, order, service, spec path, plan path (if linked).

### get(id)

Return a single backlog item with all metadata.

**Parameters:** `id` — story ID (e.g., `S-003`) or ticket ID (e.g., `CTR-12`)

**Returns:** Full item metadata: id, title, status, feature, group, order, service, spec path.

### get_feature_progress(feature_id)

Count items per status for a specific feature.

**Parameters:** `feature_id` — e.g., `FEAT-005`

**Returns:** Counts per status: ready, doing, implemented, done, total.

### next_id()

Generate the next available story ID (e.g., `S-016` if the highest existing is `S-015`).

**Returns:** Next sequential story ID string.

---

## Write Operations

### create(items)

Add new items to the backlog in ready status.

**Parameters:** List of items, each with: id, title, feature, group, order, service, spec path.

**Title contract:**
- `title` must be **≤ 80 characters** — implementations MUST reject longer titles and surface the error to the caller. This is part of the backlog interface, not a soft suggestion.
- `title` should be an imperative verb phrase describing the capability (e.g., `Add reviews migration`, `Wire review module factory`, `Expose review endpoints`).
- Implementation detail (file paths, schema definitions, config keys, code fragments) belongs in the spec file referenced by `spec:` — not in the title.
- Rationale: the title is the scanning surface for `list()` operations. Long titles destroy readability of `docs/backlog.md` and any external tracker UI; the spec link exists so detail has a proper home.

**Behavior:**
- Items are created in **ready** status
- Items are placed in the Ready section/state, ordered by group then order number
- This is called by `/virtual-team:feature` during story breakdown

### link_plan(ids, plan_path)

Record which implementation plan covers a set of items.

**Parameters:**
- `ids` — the story IDs the plan covers (every story of the feature, or only the group the plan was written for)
- `plan_path` — e.g., `docs/plans/2026-02-12-task-notifications.md`

**Behavior:**
- Store the plan path on each item, replacing any earlier link
- Called by `/virtual-team:plan` after approval — the caller commits the change together with the plan
- `complete()` reads this link to know when a plan has been fully executed

### start(id)

Move an item from ready to doing.

**Parameters:**
- `id` — story ID

**Behavior:**
- Change item status: ready → doing
- Commit the status change

### mark_implemented(id)

Mark an item as code-complete, pending PR. **Only used in branch flow.**

**Parameters:**
- `id` — story ID

From ovargas/virtual-team, MIT.

More from ovargas/virtual-team