backlog

Files (7)

• SKILL.md
• meta.py
• project-meta.example.json
• rank.py
• graphql.md · references/
• test_meta.py
• test_rank.py

SKILL.md (first lines)

# backlog — capture + ranked work graph on GitHub

Two needs, one substrate: a frictionless **capture** inbox (loose issues labelled
`inbox`) and a typed, dependency-aware **work graph** (one user-owned Project v2
with Impact / Effort / Area / Status). The verbs below operate on both.

**Dispatch on the user's intent:**

| Intent | Verb |
|--------|------|
| "add this idea", "capture", "note this" | `capture` |
| "triage the inbox", "score these" | `triage` |
| "what's next", "ranked backlog" | `next` |
| "I'm starting #N", beginning work on an issue | `start` |
| "mark #N done", "close it out" | `land` |
| first-time board creation | `setup` |

All exact commands live in `references/graphql.md`. Board IDs come from the
**consuming project's** `.backlog/project-meta.json` (created by `setup`, found
by walking up from the current directory). That file is a **static schema
pointer** — project/field/option IDs only, *not* issue state (Impact/Effort/
Status live on the GitHub board and `rank.py` fetches them live). Because the IDs
are non-secret constants that change only on re-provision, the file is
**committed in the consuming repo** and shared across every branch/worktree;
`project-meta.example.json` is the shape reference. Reads use the existing `gh`
login; **writes need the one-time `gh auth refresh -s project`** (Projects v2 is
not in the default `repo` scope).

`<owner>`, `<repo>`, `<projectNumber>` below all come from that
`.backlog/project-meta.json`.

## Label taxonomy (capture infers, triage confirms)

Issues carry conventional repo labels alongside `inbox`. They are orthogonal to
the board's `Area` field — never derive one from the other. Apply every label
that clearly fits, typically 1–3 total; when unsure, apply fewer. Use **only**
these labels (`setup` provisions them all) — never invent new ones.

**Type — at most one:**

| Label | Apply when |
|-------|-----------|
| `bug` | Something is broken or behaves incorrectly |
| `enhancement` | New feature or improvement to existing behavior |
| `documentation` | Docs, READMEs, comments, guides |
| `question` | Open question or decision needed, not yet actionable work |

**Area — pick 0–2:**

| Label | Apply when |
|-------|-----------|
| `frontend` | UI, components, styling, client/browser behavior |
| `backend` | Server logic, APIs, data models, services |
| `infra` | Deployment, hosting, environments, tooling, build |
| `ci` | CI/CD pipelines, workflows, checks |
| `security` | Vulnerabilities, auth, permissions, hardening |
| `performance` | Speed, memory, efficiency, scalability |
| `testing` | Test coverage, test infrastructure, flaky tests |
| `dependencies` | Upgrading or managing third-party dependencies |

**Pipeline — orthogonal to Type and Area:**

Whether an issue is ready for an unattended agent to pick up, and what it
carries. `auto` and `human-required` are mutually exclusive; leave both off
when it is genuinely unclear — an unlabelled issue is simply not routed, which
is the safe default. `spec-ready` may sit alongside `auto`. Dispatchers filter
on `auto` and read `spec-ready`; nothing else reads these.

| Label | Apply when |
|-------|-----------|
| `auto` | Trivial, or close enough to previously automated work — suitable for the unattended agents pipeline |
| `human-required` | Substantial fog of war remains; needs heavy human interaction before an agent can take it |
| `spec-ready` | The issue body already carries a settled design (Problem, Solution, Implementation and Testing Decisions), typically written by `to-spec` after a grilling session — the pipeline skips its own interview and reconciles the design against current code |

## `setup` — create the board once (idempotent)

Run when `.backlog/project-meta.json` is absent or the board is being
(re)provisioned. Reconciles rather than duplicates — re-running after adding a
field is safe. Writes into the **project's** `.backlog/` directory, not the skill
dir.

1. Ensure the `project` scope: `gh auth status`; if Projects calls 403, run
   `gh auth refresh -s project`.
2. Follow `references/graphql.md` → **Setup**: create the Project, link the repo,
   add the six fields, create the `inbox` label plus the 15 taxonomy labels
   (idempotent — `--force` reconciles color/description on re-runs). On a
   brand-new board the `Area`
   single-select is created with the generic default options
   `feature,bug,infra,docs,research`. If any step reports "already exists", treat
   it as done and continue. Projects that want different Areas edit the option set
   on the board (GitHub UI) and re-run `setup` to reconcile the IDs.
3. Discover IDs: `gh project view … --format json` (project id) and
   `gh project field-list … --format json` (field + option ids).
4. Build `.backlog/project-meta.json` from that discovery using
   `meta.build_project_meta`. Run from the skill directory (so `import meta`
   resolves), writing to the project's `.backlog/` (create it if missing):

   ```bash
   mkdir -p "$PROJECT_ROOT/.backlog"
   gh project view <projectNumber> --owner <owner> --format json > /tmp/proj.json
   gh project field-list <projectNumber> --owner <owner> --format json > /tmp/fields.json
   python3 - "$PROJECT_ROOT/.backlog/project-meta.json" <<'PY'
   import json, sys, meta
   proj = json.load(open("/tmp/proj.json"))
   fields = json.load(open("/tmp/fields.json"))
   out = meta.build_project_meta(
       "<owner>", "<repo>",
       proj["number"], proj["id"], fields)
   json.dump(out, open(sys.argv[1], "w"), indent=2)
   print("wrote", sys.argv[1])
   PY
   ```

5. Confirm every field + option id in `.backlog/project-meta.json` is non-empty,
   then commit the real file (non-secret schema pointer). Report the Project URL.

6. **Built-in workflows (UI-only — no API exists; ask the user to click):**
   at `https://github.com/users/<owner>/projects/<projectNumber>/workflows`
   enable:

From jesdi/general-skills, MIT.

More from jesdi/general-skills