gsd-review-backlog — Claude Code skill: features and install
The gsd-review-backlog Claude Code skill reviews backlog entries and offers to move them into the active milestone or delete them. It handles 999.x phases in a project.
MIT 576 installs ★ 11,761 updated 2026-11-16
npx skills add open-gsd/gsd-core --skill gsd-review-backlog -a claude-codeWhat gsd-review-backlog does
The skill gathers 999.x phase folders from .planning/phases/ and checks their entries against the ## Backlog section in .planning/ROADMAP.md. It presents each item’s description, creation date, and materials from CONTEXT.md or RESEARCH.md, then asks whether to promote, keep, or remove it.
For promoted items, the skill assigns the next phase number, moves related materials, updates the roadmap, and adds a **Depends on:** field. Removing an item deletes its phase directory and roadmap entry; the skill then runs a commit command for the changes. The project needs its planning files and an accessible gsd-tools.cjs or verified gsd_run. Command execution requires Node.js.
What it helps with
- inspect
999.xbacklog phases and their materials - move a selected backlog entry into the active phase sequence
- remove a stale phase folder and roadmap entry
- commit changes made during backlog review
Example prompts for the agent
- Review the
999.xphases and ask which ones to promote. - Remove a stale backlog entry and update the roadmap.
- Move the selected backlog item into the next phase.
How to install gsd-review-backlog
1Skills CLI (Vercel)
npx skills add open-gsd/gsd-core --skill gsd-review-backlog -a claude-code2Manually: put the files in place
~/.claude/skills/gsd-review-backlog/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/gsd-review-backlog/
1Skills CLI (Vercel)
npx skills add open-gsd/gsd-core --skill gsd-review-backlog -a codex2Manually: put the files in place
.agents/skills/gsd-review-backlog/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add open-gsd/gsd-core --skill gsd-review-backlog -a cursor2Manually: put the files in place
.cursor/skills/gsd-review-backlog/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install open-gsd/gsd-core skills/gsd-review-backlog2Manually: put the files in place
.github/skills/gsd-review-backlog/SKILL.md1Skills CLI (Vercel)
npx skills add open-gsd/gsd-core --skill gsd-review-backlog -a gemini-cli2Platform CLI
gemini skills install https://github.com/open-gsd/gsd-core --path skills/gsd-review-backlogManually: put the files in place
.devin/skills/gsd-review-backlog/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add open-gsd/gsd-core --skill gsd-review-backlog -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about gsd-review-backlog
How do I install gsd-review-backlog in Claude Code?
Run npx skills add open-gsd/gsd-core --skill gsd-review-backlog -a claude-code. The skill file is at ~/.claude/skills/gsd-review-backlog/SKILL.md.
What does gsd-review-backlog do?
It lists 999.x backlog entries with their descriptions and accumulated materials, then lets the user promote, keep, or remove each item. Changes update ROADMAP.md and are committed.
What does gsd-review-backlog need to run?
The project needs .planning/phases/ and .planning/ROADMAP.md, plus an accessible gsd-tools.cjs or verified gsd_run. Node.js is required to run commands.
Source text
SKILL.md · MIT
---
name: gsd-review-backlog
description: "Review and promote backlog items to active milestone"
allowed-tools:
- Read
- Write
- Bash
- Grep
- AskUserQuestion
---
<objective>
Review all 999.x backlog items and optionally promote them into the active
milestone sequence or remove stale entries.
</objective>
<process>
1. **List backlog items:**
```bash
_BACKLOG=( .planning/phases/999* )
if [ -e "${_BACKLOG[0]}" ]; then ls -d "${_BACKLOG[@]}"; else echo "No backlog items found"; fi
```
2. **Read ROADMAP.md** and extract all 999.x phase entries:
```bash
cat .planning/ROADMAP.md
```
Show each backlog item with its description, any accumulated context (CONTEXT.md, RESEARCH.md), and creation date.
3. **Present the list to the user** via AskUserQuestion:
- For each backlog item, show: phase number, description, accumulated artifacts
- Options per item: **Promote** (move to active), **Keep** (leave in backlog), **Remove** (delete)
4. **For items to PROMOTE:**
- Find the next sequential phase number in the active milestone
- Rename the directory from `999.x-slug` to `{new_num}-slug`:
```bash
_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; _gsd_at() { for _p; do if [ -f "$_p" ]; then GSD_TOOLS="$_p"; return 0; fi; done; return 1; }; _gsd_id_ok() { case "$("$1" runtime-identity --raw 2>/dev/null || true)" in '{"packageName":"@opengsd/gsd-core"'*'}') return 0;; *) return 1;; esac; }; _gsd_homes() { set -- "${CLAUDE_CONFIG_DIR:-$HOME/.claude}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}" "$HOME/.gemini/antigravity-ide" "$HOME/.gemini/antigravity-cli" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}" "${CLINE_CONFIG_DIR:-$HOME/.cline}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}" "${CODEX_HOME:-$HOME/.codex}" "${COPILOT_CONFIG_DIR:-${COPILOT_HOME:-$HOME/.copilot}}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}" "${HERMES_HOME:-$HOME/.hermes}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}" "${KIMI_CONFIG_DIR:-$HOME/.config/agents}" "$HOME/.agents" "${KIMI_CODE_HOME:-$HOME/.kimi-code}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}" "${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}" "${TRAE_CONFIG_DIR:-$HOME/.trae}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}" "${ZCODE_CONFIG_DIR:-$HOME/.zcode}" "${GROK_AGENTS_HOME:-$HOME/.agents}"; for _h; do _gsd_at "$_h/gsd-core/bin/${_GSD_SHIM_NAME}" && return 0; done; return 1; }; if _gsd_at "${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif _gsd_homes; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif unset -f gsd_run; _G="$(command -v gsd_run)"; [ -n "$_G" ] && _gsd_id_ok "$_G"; then GSD_TOOLS="$_G"; gsd_run() { "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and no identity-proving gsd_run is on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; GSD_IDENTITY_STATUS=unverified; _gsd_id_ok gsd_run && GSD_IDENTITY_STATUS=ok; export GSD_IDENTITY_STATUS; [ "$GSD_IDENTITY_STATUS" = ok ] || echo "WARNING: \"$GSD_TOOLS\" did not prove it is @opengsd/gsd-core - it is either a different package or an @opengsd/gsd-core older than the runtime-identity verb. See docs/how-to/diagnose-a-foreign-gsd-tools.md" >&2; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
NEW_NUM=$(gsd_run query phase.add "${DESCRIPTION}" --raw)
```
- Move accumulated artifacts to the new phase directory
- Update ROADMAP.md: move the entry from `## Backlog` section to the active phase list
- Remove `(BACKLOG)` marker
- Add appropriate `**Depends on:**` field
5. **For items to REMOVE:**
- Delete the phase directory
- Remove the entry from ROADMAP.md `## Backlog` section
6. **Commit changes:**
```bash
gsd_run query commit "docs: review backlog — promoted N, removed M" --files .planning/ROADMAP.md
```
7. **Report summary:**
```
## 📋 Backlog Review Complete
Promoted: {list of promoted items with new phase numbers}
Kept: {list of items remaining in backlog}
Removed: {list of deleted items}
```
</process>
© open-gsd · MIT · open-gsd/gsd-core