Merge pull request #1135 from trek-e/feat/backlog-and-threads-1005

feat: add backlog parking lot and persistent context threads (#1005)

commands/gsd/add-backlog.md

@@ -0,0 +1,76 @@
+---
+name: gsd:add-backlog
+description: Add an idea to the backlog parking lot (999.x numbering)
+argument-hint: <description>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Add a backlog item to the roadmap using 999.x numbering. Backlog items are
+unsequenced ideas that aren't ready for active planning — they live outside
+the normal phase sequence and accumulate context over time.
+</objective>
+
+<process>
+
+1. **Read ROADMAP.md** to find existing backlog entries:
+   ```bash
+   cat .planning/ROADMAP.md
+   ```
+
+2. **Find next backlog number:**
+   ```bash
+   NEXT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" phase next-decimal 999 --raw)
+   ```
+   If no 999.x phases exist, start at 999.1.
+
+3. **Create the phase directory:**
+   ```bash
+   SLUG=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" generate-slug "$ARGUMENTS")
+   mkdir -p ".planning/phases/${NEXT}-${SLUG}"
+   touch ".planning/phases/${NEXT}-${SLUG}/.gitkeep"
+   ```
+
+4. **Add to ROADMAP.md** under a `## Backlog` section. If the section doesn't exist, create it at the end:
+
+   ```markdown
+   ## Backlog
+
+   ### Phase {NEXT}: {description} (BACKLOG)
+
+   **Goal:** [Captured for future planning]
+   **Requirements:** TBD
+   **Plans:** 0 plans
+
+   Plans:
+   - [ ] TBD (promote with /gsd:review-backlog when ready)
+   ```
+
+5. **Commit:**
+   ```bash
+   node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: add backlog item ${NEXT} — ${ARGUMENTS}" --files .planning/ROADMAP.md ".planning/phases/${NEXT}-${SLUG}/.gitkeep"
+   ```
+
+6. **Report:**
+   ```
+   ## 📋 Backlog Item Added
+
+   Phase {NEXT}: {description}
+   Directory: .planning/phases/{NEXT}-{slug}/
+
+   This item lives in the backlog parking lot.
+   Use /gsd:discuss-phase {NEXT} to explore it further.
+   Use /gsd:review-backlog to promote items to active milestone.
+   ```
+
+</process>
+
+<notes>
+- 999.x numbering keeps backlog items out of the active phase sequence
+- Phase directories are created immediately, so /gsd:discuss-phase and /gsd:plan-phase work on them
+- No `Depends on:` field — backlog items are unsequenced by definition
+- Sparse numbering is fine (999.1, 999.3) — always uses next-decimal
+</notes>

commands/gsd/review-backlog.md

@@ -0,0 +1,61 @@
+---
+name: gsd:review-backlog
+description: Review and promote backlog items to active milestone
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<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
+   ls -d .planning/phases/999* 2>/dev/null || echo "No backlog items found"
+   ```
+
+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
+     NEW_NUM=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" 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
+   node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" 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>

commands/gsd/thread.md

@@ -0,0 +1,127 @@
+---
+name: gsd:thread
+description: Manage persistent context threads for cross-session work
+argument-hint: [name | description]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Create, list, or resume persistent context threads. Threads are lightweight
+cross-session knowledge stores for work that spans multiple sessions but
+doesn't belong to any specific phase.
+</objective>
+
+<process>
+
+**Parse $ARGUMENTS to determine mode:**
+
+<mode_list>
+**If no arguments or $ARGUMENTS is empty:**
+
+List all threads:
+```bash
+ls .planning/threads/*.md 2>/dev/null
+```
+
+For each thread, read the first few lines to show title and status:
+```
+## Active Threads
+
+| Thread | Status | Last Updated |
+|--------|--------|-------------|
+| fix-deploy-key-auth | OPEN | 2026-03-15 |
+| pasta-tcp-timeout | RESOLVED | 2026-03-12 |
+| perf-investigation | IN PROGRESS | 2026-03-17 |
+```
+
+If no threads exist, show:
+```
+No threads found. Create one with: /gsd:thread <description>
+```
+</mode_list>
+
+<mode_resume>
+**If $ARGUMENTS matches an existing thread name (file exists):**
+
+Resume the thread — load its context into the current session:
+```bash
+cat ".planning/threads/${THREAD_NAME}.md"
+```
+
+Display the thread content and ask what the user wants to work on next.
+Update the thread's status to `IN PROGRESS` if it was `OPEN`.
+</mode_resume>
+
+<mode_create>
+**If $ARGUMENTS is a new description (no matching thread file):**
+
+Create a new thread:
+
+1. Generate slug from description:
+   ```bash
+   SLUG=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" generate-slug "$ARGUMENTS")
+   ```
+
+2. Create the threads directory if needed:
+   ```bash
+   mkdir -p .planning/threads
+   ```
+
+3. Write the thread file:
+   ```bash
+   cat > ".planning/threads/${SLUG}.md" << 'EOF'
+   # Thread: {description}
+
+   ## Status: OPEN
+
+   ## Goal
+
+   {description}
+
+   ## Context
+
+   *Created from conversation on {today's date}.*
+
+   ## References
+
+   - *(add links, file paths, or issue numbers)*
+
+   ## Next Steps
+
+   - *(what the next session should do first)*
+   EOF
+   ```
+
+4. If there's relevant context in the current conversation (code snippets,
+   error messages, investigation results), extract and add it to the Context
+   section.
+
+5. Commit:
+   ```bash
+   node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs: create thread — ${ARGUMENTS}" --files ".planning/threads/${SLUG}.md"
+   ```
+
+6. Report:
+   ```
+   ## 🧵 Thread Created
+
+   Thread: {slug}
+   File: .planning/threads/{slug}.md
+
+   Resume anytime with: /gsd:thread {slug}
+   ```
+</mode_create>
+
+</process>
+
+<notes>
+- Threads are NOT phase-scoped — they exist independently of the roadmap
+- Lighter weight than /gsd:pause-work — no phase state, no plan context
+- The value is in Context and Next Steps — a cold-start session can pick up immediately
+- Threads can be promoted to phases or backlog items when they mature:
+  /gsd:add-phase or /gsd:add-backlog with context from the thread
+- Thread files live in .planning/threads/ — no collision with phases or other GSD structures
+</notes>