gsd-add-backlog

name	gsd-add-backlog
description	Add an idea to the backlog parking lot (999.x numbering)
metadata	{"short-description":"Add an idea to the backlog parking lot (999.x numbering)"}

<codex_skill_adapter>

A. Skill Invocation

• This skill is invoked by mentioning $gsd-add-backlog.
• Treat all user text after $gsd-add-backlog as {{GSD_ARGS}}.
• If no arguments are present, treat {{GSD_ARGS}} as empty.

B. AskUserQuestion → request_user_input Mapping

GSD workflows use AskUserQuestion (Claude Code syntax). Translate to Codex request_user_input:

Parameter mapping:

• header → header
• question → question
• Options formatted as "Label" — description → {label: "Label", description: "description"}
• Generate id from header: lowercase, replace spaces with underscores

Batched calls:

• AskUserQuestion([q1, q2]) → single request_user_input with multiple entries in questions[]

Multi-select workaround:

• Codex has no multiSelect. Use sequential single-selects, or present a numbered freeform list asking the user to enter comma-separated numbers.

Execute mode fallback:

• When request_user_input is rejected (Execute mode), present a plain-text numbered list and pick a reasonable default.

C. Task() → spawn_agent Mapping

GSD workflows use Task(...) (Claude Code syntax). Translate to Codex collaboration tools:

Direct mapping:

• Task(subagent_type="X", prompt="Y") → spawn_agent(agent_type="X", message="Y")
• Task(model="...") → omit (Codex uses per-role config, not inline model selection)
• fork_context: false by default — GSD agents load their own context via <files_to_read> blocks

Parallel fan-out:

• Spawn multiple agents → collect agent IDs → wait(ids) for all to complete

Result parsing:

• Look for structured markers in agent output: CHECKPOINT, PLAN COMPLETE, SUMMARY, etc.
• close_agent(id) after collecting results from each agent </codex_skill_adapter>

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.

1. Read ROADMAP.md to find existing backlog entries:

   cat .planning/ROADMAP.md
   

2. Find next backlog number:

   NEXT=$(gsd-sdk query phase.next-decimal 999 --raw)
   

   If no 999.x phases exist, start at 999.1.

3. Add to ROADMAP.md under a ## Backlog section. If the section doesn't exist, create it at the end. Write the ROADMAP entry BEFORE creating the directory — this ensures directory existence is always a reliable indicator that the phase is already registered, which prevents false duplicate detection in any hook that checks for existing 999.x directories (#2280):

   ## Backlog
   
   ### Phase {NEXT}: {description} (BACKLOG)
   
   **Goal:** [Captured for future planning]
   **Requirements:** TBD
   **Plans:** 0 plans
   
   Plans:
   - [ ] TBD (promote with $gsd-review-backlog when ready)
   

4. Create the phase directory:

   SLUG=$(gsd-sdk query generate-slug "{{GSD_ARGS}}" --raw)
   mkdir -p ".planning/phases/${NEXT}-${SLUG}"
   touch ".planning/phases/${NEXT}-${SLUG}/.gitkeep"
   

5. Commit:

   gsd-sdk query commit "docs: add backlog item ${NEXT} — ${ARGUMENTS}" .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.
   

- 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