@jesdi/skills 0.0.6 → 0.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jesdi/skills",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "jesdi's agent skills (content package consumed by @jesdi/skills-cli)",
   "license": "MIT",
   "repository": {

package/skills/backlog/SKILL.md

@@ -42,6 +42,35 @@ 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 |
+
 ## `setup` — create the board once (idempotent)
 
 Run when `.backlog/project-meta.json` is absent or the board is being
@@ -52,7 +81,9 @@ 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 four fields, create the `inbox` label. On a brand-new board the `Area`
+   add the six fields, create the `inbox` label plus the 12 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
@@ -126,17 +157,30 @@ Reuse the **dedup discipline** from the `file-bug-issue` skill, but take the
 2. Dedup: `gh issue list --repo <repo> --state open --search "<distinctive terms>" --json number,title,url`.
    If a genuine duplicate exists, add the new angle as a comment instead of a new
    issue and report which. Different-but-related → create new and cross-link `#N`.
-3. Otherwise create it (see `references/graphql.md` → Capture): `--label inbox`,
-   body = the idea as-is (one loose sentence is fine; no required structure).
-4. Report the new issue URL. If mid-task, treat as a side-quest and return.
+3. Otherwise infer labels from the idea text per the **Label taxonomy** above,
+   then create it (see `references/graphql.md` → Capture): `--label inbox` plus
+   one `--label` per inferred label, body = the idea as-is (one loose sentence
+   is fine; no required structure).
+4. Report the new issue URL and the labels applied. If mid-task, treat as a
+   side-quest and return.
 
 ## `triage` — turn inbox issues into scored graph nodes
 
-1. List the inbox: `gh issue list --repo <repo> --state open --label inbox --json number,title,url,body`.
-2. For each, present title + body and ask whether to promote (skip = leave in inbox).
+1. List the inbox: `gh issue list --repo <repo> --state open --label inbox --json number,title,url,body,labels`.
+2. For each, present title + body + current labels and ask whether to promote
+   (skip = leave in inbox). Offer label corrections per the **Label taxonomy**
+   above; apply via `gh issue edit N --add-label … --remove-label …`
+   (graphql.md → Triage). Labels stay independent of the board `Area` gathered
+   next.
 3. For a promoted issue, gather `Impact` (1–5), `Effort` (1–5), `Area` (**pick one
    from the options present in `.backlog/project-meta.json`** → `fields.Area.options`),
    and optional blockers.
+
+   - **Boost** (number, optional, default 0): manual priority override. Ranking is
+     band-dominant — any issue with higher Boost outranks every issue with lower
+     Boost regardless of score; score orders issues within a band. Negative values
+     sink an issue below the unboosted pack. Dispatchers set 99 for "work on this
+     next". `--json` rows carry `"boost"`.
 4. Apply, in order, the `references/graphql.md` → Triage commands:
    add to project → set Impact/Effort (`--number`) → set
    `Score` = round(Impact ÷ Effort, 1) (`--number`) → set Area +
@@ -155,7 +199,7 @@ python3 .claude/skills/backlog/rank.py          # human-readable table
 python3 .claude/skills/backlog/rank.py --json   # machine-readable rows for
                                                 # dispatchers: number, title,
                                                 # url, status, labels, blocked,
-                                                # score
+                                                # score, boost
 ```
 
 (Use whichever agent-skills path the store symlinked the skill into — e.g.
@@ -165,10 +209,11 @@ or below the repo root so `rank.py` can walk up to `.backlog/`.)
 `rank.py` pulls Project items + issue bodies via `gh`, parses `Blocked by:`
 edges, drops closed/`Done` blockers, and prints:
 
-- **Available** issues ranked by Impact÷Effort (unscored sort last, flagged
-  `[needs triage]`).
+- **Available** issues ranked boost-band first, then Impact÷Effort within a band
+  (unscored sort last within a band, flagged `[needs triage]`).
 - **Blocked** issues, unranked, annotated with what they wait on.
 
-Present the table as-is. If the user asks "why isn't #N at the top", point at its
-score or its blockers from the output. This in-memory ranking is the reason the
+Present the table as-is. If the user asks "why isn't #N at the top", check first
+whether another issue has a higher Boost band (shown as `↑n`), then its score, then
+its blockers from the output. This in-memory ranking is the reason the
 skill exists over a bare `gh issue list`.

package/skills/backlog/project-meta.example.json

@@ -11,6 +11,7 @@
     "Impact": {"id": "PVTF_REPLACE"},
     "Effort": {"id": "PVTF_REPLACE"},
     "Score": {"id": "PVTF_REPLACE"},
+    "Boost": {"id": "PVTF_REPLACE"},
     "Area": {
       "id": "PVTSSF_REPLACE",
       "options": {"feature": "...", "bug": "...", "infra": "...", "docs": "...", "research": "..."}

package/skills/backlog/rank.py

@@ -66,6 +66,7 @@ def merge_sources(project_items, issue_rows):
             "effort": _as_int(item.get("effort")),
             "area": item.get("area"),
             "labels": [l["name"] for l in row.get("labels") or []],
+            "boost": (lambda v: 0 if v is None else v)(_as_int(item.get("boost"))),
         })
     return merged
 
@@ -100,7 +101,8 @@ def score(issue):
 def _sort_key(issue):
     value = score(issue)
     return (
-        0 if value is not None else 1,   # scored issues first
+        -issue.get("boost", 0),          # band first: higher boost above everything
+        0 if value is not None else 1,   # scored issues first within a band
         -(value or 0.0),                 # higher score first
         -(issue.get("impact") or 0),     # tiebreak: higher impact
         issue["number"],                 # stable, deterministic
@@ -146,6 +148,7 @@ def to_json_rows(result):
             "labels": issue.get("labels", []),
             "blocked": blocked,
             "score": score(issue),
+            "boost": issue.get("boost", 0),
         })
     return rows
 
@@ -165,6 +168,11 @@ def render(result):
         value = score(issue)
         score_str = f"{value:.2f}" if value is not None else "  — "
         flag = "" if value is not None else "  [needs triage]"
+        boost = issue.get("boost", 0)
+        if boost > 0:
+            flag += f"  ↑{boost}"
+        elif boost < 0:
+            flag += f"  ↓{-boost}"
         label = f"#{issue['number']} {issue['title']}"[:38].ljust(38)
         area = (issue.get("area") or "-")
         lines.append(f"{idx:>4}  {score_str:>5}  {label}  {area:<10}{flag}")

package/skills/backlog/references/graphql.md

@@ -26,13 +26,27 @@ gh project field-create <projectNumber> --owner <owner> --name "Status" \
 gh project field-create <projectNumber> --owner <owner> --name "Impact" --data-type NUMBER
 gh project field-create <projectNumber> --owner <owner> --name "Effort" --data-type NUMBER
 gh project field-create <projectNumber> --owner <owner> --name "Score" --data-type NUMBER
+gh project field-create <projectNumber> --owner <owner> --name "Boost" --data-type NUMBER
 gh project field-create <projectNumber> --owner <owner> --name "Area" \
   --data-type SINGLE_SELECT \
   --single-select-options "feature,bug,infra,docs,research"
 
-# 4. Create the inbox label on the repo
-gh label create inbox --repo <repo> \
-  --description "Un-triaged capture" --color BFD4F2 || true
+# 4. Create the labels on the repo (idempotent: --force updates color/description)
+gh label create inbox --repo <repo> --description "Un-triaged capture" --color BFD4F2 --force
+# Type labels (at most one per issue)
+gh label create bug --repo <repo> --description "Something is broken or behaves incorrectly" --color d73a4a --force
+gh label create enhancement --repo <repo> --description "New feature or improvement to existing behavior" --color a2eeef --force
+gh label create documentation --repo <repo> --description "Docs, READMEs, comments, guides" --color 0075ca --force
+gh label create question --repo <repo> --description "Open question or decision needed, not yet actionable work" --color d876e3 --force
+# Area labels (0-2 per issue)
+gh label create frontend --repo <repo> --description "UI, components, styling, client/browser behavior" --color fbca04 --force
+gh label create backend --repo <repo> --description "Server logic, APIs, data models, services" --color 1d76db --force
+gh label create infra --repo <repo> --description "Deployment, hosting, environments, tooling, build" --color c2e0c6 --force
+gh label create ci --repo <repo> --description "CI/CD pipelines, workflows, checks" --color bfdadc --force
+gh label create security --repo <repo> --description "Vulnerabilities, auth, permissions, hardening" --color ee0701 --force
+gh label create performance --repo <repo> --description "Speed, memory, efficiency, scalability" --color f9d0c4 --force
+gh label create testing --repo <repo> --description "Test coverage, test infrastructure, flaky tests" --color 0e8a16 --force
+gh label create dependencies --repo <repo> --description "Upgrading or managing third-party dependencies" --color 0366d6 --force
 
 # 5. Discover IDs to build .backlog/project-meta.json
 gh project view <projectNumber> --owner <owner> --format json   # -> id (projectId)
@@ -48,7 +62,8 @@ IDs into `.backlog/project-meta.json`.
 
 ```bash
 gh issue create --repo <repo> \
-  --title "<concise idea title>" --label inbox \
+  --title "<concise idea title>" \
+  --label inbox --label "<inferred>" [--label "<inferred>" ...] \
   --body "<one loose sentence is fine>"
 ```
 
@@ -65,6 +80,9 @@ gh project item-edit --project-id <projectId> --id <itemId> \
   --field-id <fields.Effort.id> --number <1-5>
 gh project item-edit --project-id <projectId> --id <itemId> \
   --field-id <fields.Score.id> --number <round(impact/effort, 1)>
+# Optional: manual priority override (default 0; positive boosts above unboosted, negative sinks below)
+gh project item-edit --project-id <projectId> --id <itemId> \
+  --field-id <fields.Boost.id> --number <n>
 
 # Set single-selects (use the option id from .backlog/project-meta.json)
 gh project item-edit --project-id <projectId> --id <itemId> \
@@ -77,6 +95,8 @@ gh issue edit <number> --repo <repo> --body "<body>\n\nBlocked by: #<a>, #<b>"
 
 # Drop the inbox label
 gh issue edit <number> --repo <repo> --remove-label inbox
+# Correct taxonomy labels if the user adjusts them during review
+gh issue edit <number> --repo <repo> --add-label "<label>,<label>" --remove-label "<label>"
 ```
 
 ## Sub-issues (native parent/child) — GraphQL, no field IDs needed

package/skills/backlog/test_rank.py

@@ -302,7 +302,7 @@ def test_main_json_emits_machine_readable_rows(monkeypatch, capsys):
     rows = jsonlib.loads(capsys.readouterr().out)
     assert rows == [{"number": 5, "title": "Task", "url": "u/5",
                      "status": "Ready", "labels": ["auto"],
-                     "blocked": False, "score": 2.0}]
+                     "blocked": False, "score": 2.0, "boost": 0}]
 
 
 def test_project_env_absent_without_token(monkeypatch):
@@ -343,3 +343,72 @@ def test_find_project_meta_errors_clearly_when_absent(tmp_path, monkeypatch):
         rank.find_project_meta()
     assert ".backlog/project-meta.json" in str(exc.value)
     assert "backlog setup" in str(exc.value)
+
+
+def test_merge_sources_parses_boost_and_defaults_zero():
+    out = rank.merge_sources(
+        [{"content": {"number": 7, "title": "T", "url": "u/7"}, "boost": 2},
+         {"content": {"number": 8, "title": "U", "url": "u/8"}, "boost": ""},
+         {"content": {"number": 9, "title": "V", "url": "u/9"}},
+         {"content": {"number": 10, "title": "W", "url": "u/10"}, "boost": -3}],
+        [])
+    assert [i["boost"] for i in out] == [2, 0, 0, -3]
+
+
+def test_boost_band_dominates_score():
+    lo = _scored(1, 5, 1)              # score 5.0, unboosted
+    hi = _scored(2, 1, 2)              # score 0.5, boosted
+    hi["boost"] = 1
+    result = rank.rank_issues([lo, hi])
+    assert [i["number"] for i in result["available"]] == [2, 1]
+
+
+def test_score_orders_within_boost_band():
+    a = _scored(1, 2, 2)               # score 1.0
+    b = _scored(2, 5, 1)               # score 5.0
+    a["boost"] = b["boost"] = 1
+    result = rank.rank_issues([a, b])
+    assert [i["number"] for i in result["available"]] == [2, 1]
+
+
+def test_negative_boost_sinks_below_unboosted():
+    demoted = _scored(1, 9, 1)         # score 9.0 but demoted
+    demoted["boost"] = -1
+    plain = _scored(2, 1, 1)           # score 1.0
+    result = rank.rank_issues([demoted, plain])
+    assert [i["number"] for i in result["available"]] == [2, 1]
+
+
+def test_unscored_boosted_enters_band_after_scored_in_band():
+    scored_boosted = _scored(1, 2, 1)
+    scored_boosted["boost"] = 1
+    unscored_boosted = _scored(2, None, None)
+    unscored_boosted["boost"] = 1
+    scored_plain = _scored(3, 5, 1)
+    result = rank.rank_issues([scored_plain, unscored_boosted, scored_boosted])
+    assert [i["number"] for i in result["available"]] == [1, 2, 3]
+
+
+def test_json_rows_include_boost():
+    a = _scored(1, 2, 1)
+    a["boost"] = 2
+    a["labels"] = ["auto"]
+    b = _scored(2, 5, 1)
+    b["labels"] = ["auto"]
+    rows = rank.to_json_rows(rank.rank_issues([a, b]))
+    assert [(r["number"], r["boost"]) for r in rows] == [(1, 2), (2, 0)]
+
+
+def test_render_marks_boost_up_and_down():
+    up = _scored(1, 2, 1)
+    up["boost"] = 2
+    down = _scored(2, 5, 1)
+    down["boost"] = -1
+    plain = _scored(3, 1, 1)
+    text = rank.render(rank.rank_issues([up, down, plain]))
+    line_for_up = next(l for l in text.splitlines() if "#1 i1" in l)
+    assert "↑2" in line_for_up
+    line_for_down = next(l for l in text.splitlines() if "#2 i2" in l)
+    assert "↓1" in line_for_down
+    line_for_plain = next(l for l in text.splitlines() if "#3 i3" in l)
+    assert "↑" not in line_for_plain and "↓" not in line_for_plain

package/skills-manifest.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-07-23T15:49:56.550Z",
+  "generatedAt": "2026-07-29T09:24:37.867Z",
   "skills": [
     {
       "name": "backlog",
-      "version": "0.1.3",
-      "hash": "sha256-afe5ef66a86a4bbb1ce654e9ec861be80873e36e1cb45fbe132564a25dc26c1d",
+      "version": "0.1.5",
+      "hash": "sha256-427fff6fc5005849a85e750568940b52375c823a9ad26b1827890dc0cabab499",
       "description": "Manage a GitHub-Issues-backed backlog and a Projects-v2 work graph via five verbs. Use when the user wants to CAPTURE an idea/research thread (\"add to backlog\", \"capture this\", \"note this idea\", \"log a task\"), TRIAGE the inbox (\"triage the backlog\", \"score the inbox\"), see what to work on NEXT (\"what's next\", \"what should I work on\", \"ranked backlog\", \"next actionable task\"), LAND a finished item (\"mark done\", \"close out #N\"), or SETUP the board the first time. Ranks open issues by impact÷effort, respecting `Blocked by:` edges, so only actionable work surfaces."
     },
     {