@tekyzinc/gsd-t 2.6.0 → 2.8.1

package/README.md

@@ -18,7 +18,7 @@ A methodology for reliable, parallelizable development using Claude Code with op
 npx @tekyzinc/gsd-t install
 ```
 
-This installs 24 GSD-T commands + 3 utility commands to `~/.claude/commands/` and the global CLAUDE.md to `~/.claude/CLAUDE.md`. Works on Windows, Mac, and Linux.
+This installs 31 GSD-T commands + 3 utility commands to `~/.claude/commands/` and the global CLAUDE.md to `~/.claude/CLAUDE.md`. Works on Windows, Mac, and Linux.
 
 ### Start Using It
 
@@ -66,8 +66,10 @@ GSD-T reads all state files and tells you exactly where you left off.
 
 ```bash
 npx @tekyzinc/gsd-t install        # Install commands + global CLAUDE.md
-npx @tekyzinc/gsd-t update         # Update to latest (backs up customizations)
-npx @tekyzinc/gsd-t init [name]    # Scaffold GSD-T project in current directory
+npx @tekyzinc/gsd-t update         # Update global commands + CLAUDE.md
+npx @tekyzinc/gsd-t update-all     # Update globally + all registered project CLAUDE.md files
+npx @tekyzinc/gsd-t init [name]    # Scaffold GSD-T project (auto-registers)
+npx @tekyzinc/gsd-t register       # Register current directory as a GSD-T project
 npx @tekyzinc/gsd-t status         # Check installation + version
 npx @tekyzinc/gsd-t doctor         # Diagnose common issues
 npx @tekyzinc/gsd-t uninstall      # Remove commands (keeps project files)
@@ -131,6 +133,18 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 | `/user:gsd-t-quick` | Fast task with GSD-T guarantees |
 | `/user:gsd-t-debug` | Systematic debugging with state |
 
+### Backlog Management
+
+| Command | Purpose |
+|---------|---------|
+| `/user:gsd-t-backlog-add` | Capture item, auto-categorize, append to backlog |
+| `/user:gsd-t-backlog-list` | Filtered, ordered view of backlog items |
+| `/user:gsd-t-backlog-move` | Reorder items by position (priority) |
+| `/user:gsd-t-backlog-edit` | Modify backlog entry fields |
+| `/user:gsd-t-backlog-remove` | Drop item with optional reason |
+| `/user:gsd-t-backlog-promote` | Refine, classify, launch GSD-T workflow |
+| `/user:gsd-t-backlog-settings` | Manage types, apps, categories, defaults |
+
 ### Git Helpers
 
 | Command | Purpose |
@@ -180,6 +194,8 @@ your-project/
 │   └── infrastructure.md             # Dev setup, DB, cloud, deployment
 ├── .gsd-t/
 │   ├── progress.md                    # Master state file
+│   ├── backlog.md                    # Captured backlog items (priority ordered)
+│   ├── backlog-settings.md           # Types, apps, categories, defaults
 │   ├── roadmap.md                     # Milestone roadmap
 │   ├── techdebt.md                    # Technical debt register
 │   ├── verify-report.md               # Latest verification results
@@ -252,8 +268,8 @@ get-stuff-done-teams/
 ├── LICENSE
 ├── bin/
 │   └── gsd-t.js                       # CLI installer
-├── commands/                          # 27 slash commands
-│   ├── gsd-t-*.md                     # 24 GSD-T workflow commands
+├── commands/                          # 34 slash commands
+│   ├── gsd-t-*.md                     # 31 GSD-T workflow commands
 │   ├── branch.md                      # Git branch helper
 │   ├── checkin.md                     # Auto-version + commit/push helper
 │   └── Claude-md.md                   # Reload CLAUDE.md directives
@@ -264,7 +280,9 @@ get-stuff-done-teams/
 │   ├── architecture.md
 │   ├── workflows.md
 │   ├── infrastructure.md
-│   └── progress.md
+│   ├── progress.md
+│   ├── backlog.md
+│   └── backlog-settings.md
 ├── examples/
 │   ├── settings.json
 │   └── .gsd-t/

package/bin/gsd-t.js

@@ -6,7 +6,9 @@
  * Usage:
  *   npx @tekyzinc/gsd-t install     — Install commands + global CLAUDE.md
  *   npx @tekyzinc/gsd-t update      — Update commands + global CLAUDE.md (preserves customizations)
- *   npx @tekyzinc/gsd-t init [name] — Initialize a new project with GSD-T structure
+ *   npx @tekyzinc/gsd-t update-all  — Update globally + all registered project CLAUDE.md files
+ *   npx @tekyzinc/gsd-t init [name] — Initialize a new project with GSD-T structure (auto-registers)
+ *   npx @tekyzinc/gsd-t register    — Register current directory as a GSD-T project
  *   npx @tekyzinc/gsd-t status      — Show what's installed and check for updates
  *   npx @tekyzinc/gsd-t uninstall   — Remove GSD-T commands (leaves project files alone)
  *   npx @tekyzinc/gsd-t doctor      — Diagnose common issues
@@ -23,6 +25,7 @@ const COMMANDS_DIR = path.join(CLAUDE_DIR, "commands");
 const GLOBAL_CLAUDE_MD = path.join(CLAUDE_DIR, "CLAUDE.md");
 const SETTINGS_JSON = path.join(CLAUDE_DIR, "settings.json");
 const VERSION_FILE = path.join(CLAUDE_DIR, ".gsd-t-version");
+const PROJECTS_FILE = path.join(CLAUDE_DIR, ".gsd-t-projects");
 
 // Where our package files live (relative to this script)
 const PKG_ROOT = path.resolve(__dirname, "..");
@@ -87,6 +90,25 @@ function saveInstalledVersion() {
   fs.writeFileSync(VERSION_FILE, PKG_VERSION);
 }
 
+function getRegisteredProjects() {
+  try {
+    const content = fs.readFileSync(PROJECTS_FILE, "utf8").trim();
+    if (!content) return [];
+    return content.split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("#"));
+  } catch {
+    return [];
+  }
+}
+
+function registerProject(projectDir) {
+  const resolved = path.resolve(projectDir);
+  const projects = getRegisteredProjects();
+  if (projects.includes(resolved)) return false;
+  projects.push(resolved);
+  fs.writeFileSync(PROJECTS_FILE, projects.join("\n") + "\n");
+  return true;
+}
+
 function getCommandFiles() {
   // All .md files in our commands/ directory (gsd-t-* plus utilities like branch, checkin, Claude-md)
   return fs
@@ -315,7 +337,12 @@ function doInit(projectName) {
     success(".gsd-t/progress.md");
   }
 
-  // 4. Summary
+  // 4. Register in project index
+  if (registerProject(projectDir)) {
+    success("Registered in ~/.claude/.gsd-t-projects");
+  }
+
+  // 5. Summary
   heading("Project Initialized!");
   log("");
   log(`  ${projectDir}/`);
@@ -469,6 +496,122 @@ function doUninstall() {
   log("");
 }
 
+function doUpdateAll() {
+  // First, run the normal global update
+  const installedVersion = getInstalledVersion();
+  if (installedVersion !== PKG_VERSION) {
+    doInstall({ update: true });
+  } else {
+    heading(`GSD-T v${PKG_VERSION}`);
+    success("Global commands already up to date");
+  }
+
+  // Read project registry
+  heading("Updating registered projects...");
+  log("");
+
+  const projects = getRegisteredProjects();
+
+  if (projects.length === 0) {
+    info("No projects registered");
+    log("");
+    log("  Projects are registered automatically when you run:");
+    log(`  ${DIM}$${RESET} npx @tekyzinc/gsd-t init`);
+    log("");
+    log("  Or register an existing project manually:");
+    log(`  ${DIM}$${RESET} npx @tekyzinc/gsd-t register`);
+    log("");
+    return;
+  }
+
+  let updated = 0;
+  let skipped = 0;
+  let missing = 0;
+
+  for (const projectDir of projects) {
+    const projectName = path.basename(projectDir);
+    const claudeMd = path.join(projectDir, "CLAUDE.md");
+
+    // Check project still exists
+    if (!fs.existsSync(projectDir)) {
+      warn(`${projectName} — directory not found (${projectDir})`);
+      missing++;
+      continue;
+    }
+
+    if (!fs.existsSync(claudeMd)) {
+      warn(`${projectName} — no CLAUDE.md found`);
+      skipped++;
+      continue;
+    }
+
+    const content = fs.readFileSync(claudeMd, "utf8");
+
+    // Check if the project CLAUDE.md needs the Destructive Action Guard
+    if (content.includes("Destructive Action Guard")) {
+      info(`${projectName} — already up to date`);
+      skipped++;
+      continue;
+    }
+
+    // Add the Destructive Action Guard section
+    const guardSection = [
+      "",
+      "",
+      "# Destructive Action Guard (MANDATORY)",
+      "",
+      "**NEVER perform destructive or structural changes without explicit user approval.** This applies at ALL autonomy levels.",
+      "",
+      "Before any of these actions, STOP and ask the user:",
+      "- DROP TABLE, DROP COLUMN, DROP INDEX, TRUNCATE, DELETE without WHERE",
+      "- Renaming or removing database tables or columns",
+      "- Schema migrations that lose data or break existing queries",
+      "- Replacing an existing architecture pattern (e.g., normalized → denormalized)",
+      "- Removing or replacing existing files/modules that contain working functionality",
+      "- Changing ORM models in ways that conflict with the existing database schema",
+      "- Removing API endpoints or changing response shapes that existing clients depend on",
+      "- Any change that would require other parts of the system to be rewritten",
+      "",
+      '**Rule: "Adapt new code to existing structures, not the other way around."**',
+      "",
+    ].join("\n");
+
+    let newContent;
+    // Match headings at any level (# or ## or ###)
+    const preCommitMatch = content.match(/\n(#{1,3} Pre-Commit Gate)/);
+    const dontDoMatch = content.match(/\n(#{1,3} Don't Do These Things)/);
+
+    if (preCommitMatch) {
+      newContent = content.replace(
+        "\n" + preCommitMatch[1],
+        guardSection + "\n" + preCommitMatch[1]
+      );
+    } else if (dontDoMatch) {
+      newContent = content.replace(
+        "\n" + dontDoMatch[1],
+        guardSection + "\n" + dontDoMatch[1]
+      );
+    } else {
+      newContent = content + guardSection;
+    }
+
+    fs.writeFileSync(claudeMd, newContent);
+    success(`${projectName} — updated CLAUDE.md`);
+    updated++;
+  }
+
+  // Summary
+  log("");
+  heading("Update All Complete");
+  log(`  Projects registered: ${projects.length}`);
+  log(`  Updated:             ${updated}`);
+  log(`  Already current:     ${skipped}`);
+  if (missing > 0) {
+    log(`  Not found:           ${missing}`);
+  }
+  log("");
+}
+
 function doDoctor() {
   heading("GSD-T Doctor");
   log("");
@@ -572,6 +715,37 @@ function doDoctor() {
   log("");
 }
 
+function doRegister() {
+  const projectDir = process.cwd();
+  const gsdtDir = path.join(projectDir, ".gsd-t");
+
+  if (!fs.existsSync(gsdtDir)) {
+    error("Not a GSD-T project (no .gsd-t/ directory found)");
+    info("Run 'npx @tekyzinc/gsd-t init' to initialize this project first");
+    return;
+  }
+
+  if (registerProject(projectDir)) {
+    success(`Registered: ${projectDir}`);
+  } else {
+    info("Already registered");
+  }
+
+  // Show all registered projects
+  const projects = getRegisteredProjects();
+  log("");
+  heading("Registered Projects");
+  for (const p of projects) {
+    const exists = fs.existsSync(p);
+    if (exists) {
+      log(`  ${GREEN}✓${RESET} ${p}`);
+    } else {
+      log(`  ${RED}✗${RESET} ${p} ${DIM}(not found)${RESET}`);
+    }
+  }
+  log("");
+}
+
 function showHelp() {
   log("");
   log(`${BOLD}GSD-T${RESET} — Contract-Driven Development for Claude Code`);
@@ -581,8 +755,10 @@ function showHelp() {
   log("");
   log(`${BOLD}Commands:${RESET}`);
   log(`  ${CYAN}install${RESET}        Install slash commands + global CLAUDE.md`);
-  log(`  ${CYAN}update${RESET}         Update to latest (backs up customizations)`);
-  log(`  ${CYAN}init${RESET} [name]    Scaffold GSD-T project in current directory`);
+  log(`  ${CYAN}update${RESET}         Update global commands + CLAUDE.md`);
+  log(`  ${CYAN}update-all${RESET}     Update globally + all registered project CLAUDE.md files`);
+  log(`  ${CYAN}init${RESET} [name]    Scaffold GSD-T project (auto-registers)`);
+  log(`  ${CYAN}register${RESET}       Register current directory as a GSD-T project`);
   log(`  ${CYAN}status${RESET}         Show installation status + check for updates`);
   log(`  ${CYAN}uninstall${RESET}      Remove GSD-T commands (keeps project files)`);
   log(`  ${CYAN}doctor${RESET}         Diagnose common issues`);
@@ -613,9 +789,15 @@ switch (command) {
   case "update":
     doUpdate();
     break;
+  case "update-all":
+    doUpdateAll();
+    break;
   case "init":
     doInit(args[1]);
     break;
+  case "register":
+    doRegister();
+    break;
   case "status":
     doStatus();
     break;

package/commands/gsd-t-backlog-add.md

@@ -0,0 +1,90 @@
+# GSD-T: Backlog Add — Capture and Categorize a Backlog Item
+
+You are adding a new item to the project backlog. The item will be auto-categorized if needed and appended to the bottom of the backlog.
+
+## Step 1: Load Settings
+
+Read `.gsd-t/backlog-settings.md` to load:
+- **Types**: The allowed type values (bug, feature, improvement, ux, architecture, etc.)
+- **Apps**: The allowed app values
+- **Categories**: The allowed category values
+- **Default App**: The fallback app when `--app` is not specified
+- **Auto-categorize**: Whether to infer missing fields from title/description
+
+If `.gsd-t/backlog-settings.md` does not exist, STOP and tell the user:
+"No backlog settings found. Run `/gsd-t-init` or create `.gsd-t/backlog-settings.md` first."
+
+## Step 2: Parse Arguments
+
+Extract from `$ARGUMENTS`:
+- **title** (required) — The quoted string at the start, e.g., `"Fix login timeout"`
+- **--desc "..."** (optional) — A longer description
+- **--type ...** (optional) — The item type (e.g., bug, feature)
+- **--app ...** (optional) — The target app
+- **--category ...** (optional) — The category
+
+If no title is provided, STOP and tell the user:
+"Usage: `/gsd-t-backlog-add \"<title>\" [--desc \"...\"] [--type ...] [--app ...] [--category ...]`"
+
+## Step 3: Auto-Categorize
+
+For any field NOT explicitly provided:
+
+1. **--app not provided**: Use the **Default App** from settings
+2. **--type not provided**: If Auto-categorize is true, infer the type from the title and description:
+   - Words like "bug", "fix", "broken", "error", "crash" → `bug`
+   - Words like "add", "new", "create", "implement" → `feature`
+   - Words like "improve", "optimize", "refactor", "clean" → `improvement`
+   - Words like "ui", "ux", "design", "layout", "style" → `ux`
+   - Words like "architecture", "structure", "pattern", "system" → `architecture`
+   - If unclear, default to `feature`
+3. **--category not provided**: If Auto-categorize is true and categories exist in settings, infer the best-matching category from the title and description. If no good match or no categories defined, leave as `general`.
+
+## Step 4: Validate
+
+Check that the resolved values exist in `.gsd-t/backlog-settings.md`:
+
+- **Type**: Must be in the Types list. If not found, warn: "Type '{value}' is not in settings. Known types: {list}. Did you mean '{closest match}'?"
+- **App**: Must be in the Apps list. If not found, warn: "App '{value}' is not in settings. Known apps: {list}. Did you mean '{closest match}'?"
+- **Category**: Must be in the Categories list (if categories are defined). If not found and categories exist, warn: "Category '{value}' is not in settings. Known categories: {list}. Did you mean '{closest match}'?"
+
+If any validation fails, STOP and show the warning. Do not add the entry until the user confirms or corrects.
+
+## Step 5: Append Entry
+
+1. Read `.gsd-t/backlog.md`
+2. Count existing entries (count `## {N}.` headings) to determine the next position number
+3. Append the new entry at the bottom of the file using this EXACT format:
+
+```
+## {N}. {title}
+- **Type:** {type} | **App:** {app} | **Category:** {category}
+- **Added:** {YYYY-MM-DD}
+- {description}
+```
+
+Where:
+- `{N}` = next sequential position number (existing count + 1)
+- `{title}` = the item title
+- `{type}`, `{app}`, `{category}` = the resolved/validated values
+- `{YYYY-MM-DD}` = today's date
+- `{description}` = the --desc value, or a brief description derived from the title if --desc was not provided
+
+Ensure there is an empty line before the new entry.
+
+4. If `.gsd-t/backlog.md` does not exist, create it with the `# Backlog` heading first, then append the entry.
+
+## Step 6: Document Ripple
+
+Update `.gsd-t/progress.md` Decision Log:
+- Add entry: `{date} — Added backlog item #{N}: "{title}" (type: {type}, app: {app}, category: {category})`
+
+## Step 7: Test Verification
+
+Verify the entry was added correctly:
+1. Re-read `.gsd-t/backlog.md`
+2. Confirm the new entry exists at the expected position
+3. Confirm the format matches the file-format contract exactly
+4. Report: "Added backlog item #{N}: **{title}** — Type: {type} | App: {app} | Category: {category}"
+
+$ARGUMENTS

package/commands/gsd-t-backlog-edit.md

@@ -0,0 +1,107 @@
+# GSD-T: Backlog Edit — Modify Entry Fields
+
+You are editing an existing backlog entry. Only the specified fields are updated — all other fields are preserved as-is.
+
+## Step 1: Read Backlog
+
+Read `.gsd-t/backlog.md` and parse all entries.
+
+Each entry follows this format:
+```
+## {position}. {title}
+- **Type:** {type} | **App:** {app} | **Category:** {category}
+- **Added:** {YYYY-MM-DD}
+- {description}
+```
+
+Count the total number of entries. If the backlog is empty (no entries), inform the user:
+"Backlog is empty. Nothing to edit."
+Stop here.
+
+## Step 2: Parse Arguments
+
+Extract from $ARGUMENTS:
+- `<position>` (required) — the position number of the entry to edit
+- `--title "..."` (optional) — new title
+- `--desc "..."` (optional) — new description
+- `--type ...` (optional) — new type
+- `--app ...` (optional) — new app
+- `--category ...` (optional) — new category
+
+If no position is provided, show usage:
+"Usage: /gsd-t-backlog-edit <position> [--title \"...\"] [--desc \"...\"] [--type ...] [--app ...] [--category ...]"
+"Example: /gsd-t-backlog-edit 3 --title \"Updated title\" --type bug"
+Stop here.
+
+If no optional flags are provided (only position given), inform the user:
+"No fields specified to edit. Use --title, --desc, --type, --app, or --category."
+Stop here.
+
+Validate that the position exists in the backlog (between 1 and total entry count). If not:
+"Position {value} is out of range. Backlog has {count} items (valid: 1-{count})."
+Stop here.
+
+## Step 3: Validate Against Settings
+
+Read `.gsd-t/backlog-settings.md` to load allowed values.
+
+For each provided field that has a constrained value set:
+- **--type**: Check against the `## Types` list. If invalid, warn: "Type '{value}' is not in settings. Available types: {list}. Did you mean '{closest match}'?"
+- **--app**: Check against the `## Apps` list. If invalid, warn: "App '{value}' is not in settings. Available apps: {list}. Did you mean '{closest match}'?"
+- **--category**: Check against the `## Categories` list. If the list is empty, accept any value. If populated and invalid, warn: "Category '{value}' is not in settings. Available categories: {list}. Did you mean '{closest match}'?"
+
+If any value is invalid, stop and ask the user whether to proceed with the invalid value or choose from the available options.
+
+**--title** and **--desc** are free-text fields — no validation needed.
+
+## Step 4: Update Entry
+
+1. Find the entry at the specified position
+2. Record the current values as "before" snapshot
+3. Update only the fields that were specified:
+   - `--title`: Update the title in the `## {position}. {title}` heading
+   - `--desc`: Update the description line (`- {description}`)
+   - `--type`: Update the Type in the metadata line
+   - `--app`: Update the App in the metadata line
+   - `--category`: Update the Category in the metadata line
+4. Preserve all unspecified fields exactly as they are
+5. Preserve the Added date — do not change it
+6. Rewrite `.gsd-t/backlog.md` with the updated entry in place
+
+## Step 5: Confirm
+
+Show the user the before and after:
+```
+Edited backlog item #{position}:
+
+Before:
+  Title: {old-title}
+  Type: {old-type} | App: {old-app} | Category: {old-category}
+  Description: {old-desc}
+
+After:
+  Title: {new-title}
+  Type: {new-type} | App: {new-app} | Category: {new-category}
+  Description: {new-desc}
+```
+
+Only highlight fields that actually changed.
+
+## Step 6: Document Ripple
+
+If `.gsd-t/progress.md` exists, log the edit in the Decision Log:
+- Date: today's date
+- Entry: "Backlog edit: updated {changed-fields} for '{title}' at position {position}"
+
+## Step 7: Test Verification
+
+Verify the rewritten `.gsd-t/backlog.md` is well-formed:
+1. Re-read the file
+2. Confirm the edited entry parses correctly (heading, metadata, date, description)
+3. Confirm all other entries are unchanged
+4. Confirm total entry count is the same as before the edit
+5. Confirm positions are still sequential (no gaps or duplicates)
+
+If any check fails, report the issue and attempt to fix (up to 2 attempts).
+
+$ARGUMENTS

package/commands/gsd-t-backlog-list.md

@@ -0,0 +1,59 @@
+# GSD-T: Backlog List — Filtered View of Backlog Items
+
+You are displaying the project backlog with optional filtering and limiting.
+
+## Step 1: Read Backlog
+
+Read `.gsd-t/backlog.md` and parse all entries.
+
+Each entry follows this format:
+```
+## {N}. {title}
+- **Type:** {type} | **App:** {app} | **Category:** {category}
+- **Added:** {YYYY-MM-DD}
+- {description}
+```
+
+If `.gsd-t/backlog.md` does not exist or contains only the `# Backlog` heading with no entries, display:
+"No backlog items. Use `/gsd-t-backlog-add` to capture ideas."
+Then STOP.
+
+## Step 2: Apply Filters
+
+Parse `$ARGUMENTS` for optional filters:
+- **--type ...** — Show only entries matching this type
+- **--app ...** — Show only entries matching this app
+- **--category ...** — Show only entries matching this category
+
+If multiple filters are specified, apply AND logic (entry must match ALL specified filters).
+
+If no filters are specified, include all entries.
+
+## Step 3: Apply Limit
+
+If **--top N** is specified, keep only the first N entries from the filtered results (by position order, which represents priority).
+
+## Step 4: Display Results
+
+Show the filtered entries in a formatted view:
+
+```
+# Backlog ({count} items{filter description})
+
+| # | Title | Type | App | Category | Added |
+|---|-------|------|-----|----------|-------|
+| 1 | {title} | {type} | {app} | {category} | {date} |
+| 2 | {title} | {type} | {app} | {category} | {date} |
+```
+
+Where:
+- `{count}` = number of entries shown
+- `{filter description}` = if filters applied, append: `, filtered by type={value}` / `app={value}` / `category={value}` as appropriate. If no filters, omit.
+- The `#` column shows the original position number from the backlog (not a re-numbered index)
+
+## Step 5: Handle Empty Results
+
+If filters were applied but no entries match, display:
+"No backlog items match the filters: {filter summary}. Use `/gsd-t-backlog-list` with no arguments to see all items."
+
+$ARGUMENTS

package/commands/gsd-t-backlog-move.md

@@ -0,0 +1,90 @@
+# GSD-T: Backlog Move — Reorder Items by Position
+
+You are reordering a backlog item from one position to another. Position in the backlog represents priority — item 1 is highest priority.
+
+## Step 1: Read Backlog
+
+Read `.gsd-t/backlog.md` and parse all entries.
+
+Each entry follows this format:
+```
+## {position}. {title}
+- **Type:** {type} | **App:** {app} | **Category:** {category}
+- **Added:** {YYYY-MM-DD}
+- {description}
+```
+
+Count the total number of entries. If the backlog is empty (no entries), inform the user:
+"Backlog is empty. Nothing to move."
+Stop here.
+
+## Step 2: Parse Arguments
+
+Extract from $ARGUMENTS:
+- `<from-position>` — the current position number of the item to move
+- `<to-position>` — the target position number to move it to
+
+Both arguments are required. If either is missing, show usage:
+"Usage: /gsd-t-backlog-move <from-position> <to-position>"
+"Example: /gsd-t-backlog-move 5 2 — moves item 5 to position 2"
+Stop here.
+
+## Step 3: Validate Positions
+
+Check that:
+1. Both `from-position` and `to-position` are positive integers
+2. Both positions exist in the backlog (between 1 and total entry count)
+3. `from-position` and `to-position` are different
+
+If any check fails, inform the user:
+- Invalid number: "Position must be a positive integer. Got: {value}"
+- Out of range: "Position {value} is out of range. Backlog has {count} items (valid: 1-{count})."
+- Same position: "From and to positions are the same. Nothing to move."
+Stop here.
+
+## Step 4: Move Item
+
+1. Remove the entry at `from-position` from the list
+2. Insert it at `to-position` in the list
+3. This shifts other entries up or down accordingly
+
+## Step 5: Renumber and Rewrite
+
+1. Renumber ALL entries sequentially starting from 1 (update the `## {N}. {title}` heading for each)
+2. Rewrite `.gsd-t/backlog.md` with the reordered entries
+3. Preserve the `# Backlog` heading at the top
+4. Preserve all entry content (metadata, date, description) — only the position number in the heading changes
+
+## Step 6: Confirm
+
+Show the user what happened:
+```
+Moved: "{title}" from position {from} to position {to}
+
+Updated backlog order (top 5):
+  1. {title}
+  2. {title}
+  3. {title}
+  4. {title}
+  5. {title}
+```
+
+If the backlog has fewer than 5 items, show all of them.
+
+## Step 7: Document Ripple
+
+If `.gsd-t/progress.md` exists, log the move in the Decision Log:
+- Date: today's date
+- Entry: "Backlog reorder: moved '{title}' from position {from} to {to}"
+
+## Step 8: Test Verification
+
+Verify the rewritten `.gsd-t/backlog.md` is well-formed:
+1. Re-read the file
+2. Confirm all entries parse correctly (heading, metadata, date, description)
+3. Confirm positions are sequential (1, 2, 3... with no gaps or duplicates)
+4. Confirm total entry count is unchanged from before the move
+
+If any check fails, report the issue and attempt to fix (up to 2 attempts).
+
+$ARGUMENTS

package/commands/gsd-t-backlog-promote.md

@@ -0,0 +1,119 @@
+# GSD-T: Backlog Promote — Refine, Classify, and Launch GSD-T Workflow
+
+You are promoting a backlog item into the GSD-T workflow. This is the bridge from a captured idea to actionable work: refine the description, classify the scope, remove it from the backlog, and hand off to the appropriate GSD-T command.
+
+## Step 1: Load Context
+
+Read:
+1. `CLAUDE.md`
+2. `.gsd-t/progress.md` (if exists)
+3. `.gsd-t/backlog.md` — the backlog file
+
+Parse $ARGUMENTS to extract:
+- `<position>` — the entry number to promote
+
+If no position is provided, show an error:
+"Usage: `/user:gsd-t-backlog-promote <position>`"
+
+## Step 2: Find and Display Entry
+
+Find the entry at the specified position in `.gsd-t/backlog.md`.
+
+If the position doesn't exist, show an error:
+"No backlog entry at position {position}. Run `/user:gsd-t-backlog-list` to see available entries."
+
+Display the entry to the user:
+```
+Promoting backlog item #{position}:
+
+  {title}
+  Type: {type} | App: {app} | Category: {category}
+  Added: {date}
+  {description}
+```
+
+## Step 3: Refine Description
+
+The backlog entry has a 1-2 sentence description. Expand it into full context:
+
+1. Read `CLAUDE.md` and relevant docs (`docs/requirements.md`, `docs/architecture.md`, `docs/workflows.md`) to understand the project context
+2. Read `.gsd-t/contracts/` to understand existing domain boundaries and interfaces
+3. Build a comprehensive refined description that includes:
+   - **What** needs to be done (concrete deliverables)
+   - **Why** it matters (business or technical motivation)
+   - **Where** in the codebase it applies (affected files, modules, or domains)
+   - **Constraints** or considerations (existing patterns to follow, things to avoid)
+
+If the original description is ambiguous or could be interpreted multiple ways, ask the user clarifying questions before proceeding.
+
+Present the refined description to the user for confirmation:
+```
+Refined description:
+{refined description}
+
+Does this capture the intent? (Adjust if needed, or confirm to proceed)
+```
+
+## Step 4: Classify
+
+Based on the refined description, determine which GSD-T workflow to create:
+
+| Classification | Criteria | Triggers |
+|---------------|----------|----------|
+| **Milestone** | Multi-file, multi-phase work that needs partitioning (complex feature, large refactor) | `gsd-t-milestone` |
+| **Quick** | Small scope, obvious implementation, can be done in one focused session | `gsd-t-quick` |
+| **Debug** | Specific broken behavior that needs diagnosis and fix | `gsd-t-debug` |
+| **Feature** | Significant new capability that needs impact assessment first | `gsd-t-feature` |
+
+Present the classification to the user with rationale:
+```
+Classification: {classification}
+
+Rationale: {why this classification fits}
+
+If you disagree, tell me the correct classification and I'll adjust.
+```
+
+Wait for user confirmation or override before proceeding.
+
+## Step 5: Remove from Backlog
+
+After classification is confirmed:
+
+1. Remove the entry at position {position} from `.gsd-t/backlog.md`
+2. Renumber all remaining entries sequentially (1, 2, 3...)
+3. Preserve all other entry content exactly as-is
+
+## Step 6: Launch Workflow
+
+Based on the classification, present the command for the user to invoke:
+
+- **Milestone**: "Run `/user:gsd-t-milestone {refined description}`"
+- **Quick**: "Run `/user:gsd-t-quick {refined description}`"
+- **Debug**: "Run `/user:gsd-t-debug {refined description}`"
+- **Feature**: "Run `/user:gsd-t-feature {refined description}`"
+
+Display the full command with the refined description ready to copy.
+
+## Step 7: Document Ripple
+
+Update affected documentation:
+
+### Always update:
+1. **`.gsd-t/progress.md`** — Add to Decision Log: "{date}: Promoted backlog item #{position} '{title}' as {classification}"
+
+### Check if affected:
+2. **`docs/requirements.md`** — If the promoted item implies a new requirement, note it
+3. **`.gsd-t/techdebt.md`** — If this was a debt item being promoted, cross-reference it
+
+### Skip what's not affected.
+
+## Step 8: Test Verification
+
+Verify the backlog file is well-formed after removal and renumbering:
+
+1. **Check format**: Confirm `.gsd-t/backlog.md` follows the file-format-contract (sequential numbering, correct entry structure)
+2. **Check integrity**: Verify no entries were lost or corrupted during renumbering
+3. **Check empty state**: If all entries were removed, verify file contains only the `# Backlog` heading
+
+$ARGUMENTS

package/commands/gsd-t-backlog-remove.md

@@ -0,0 +1,82 @@
+# GSD-T: Backlog Remove — Drop Item with Optional Reason
+
+You are removing an entry from the backlog. This deletes the item, renumbers remaining entries, and logs the removal.
+
+## Step 1: Read Backlog
+
+Read `.gsd-t/backlog.md` and parse all entries.
+
+Find the entry at the specified position from $ARGUMENTS.
+
+If the file doesn't exist or has no entries:
+- "No backlog found. Nothing to remove."
+- Stop.
+
+If the position doesn't exist (out of range or invalid):
+- "Position {N} not found. The backlog has {count} entries."
+- Stop.
+
+## Step 2: Confirm Removal
+
+Display the entry details to the user:
+
+```
+Remove this backlog item?
+
+  ## {position}. {title}
+  - Type: {type} | App: {app} | Category: {category}
+  - Added: {date}
+  - {description}
+
+Confirm removal? (y/n)
+```
+
+Wait for user confirmation before proceeding. If the user declines, stop.
+
+## Step 3: Remove Entry
+
+Delete the entry from `.gsd-t/backlog.md`.
+
+## Step 4: Renumber Entries
+
+Renumber ALL remaining entries sequentially starting from 1.
+
+Each entry heading must follow the format: `## {position}. {title}`
+
+Rewrite `.gsd-t/backlog.md` with the updated entries. If no entries remain, the file should contain only the `# Backlog` heading.
+
+## Step 5: Log Removal
+
+Parse $ARGUMENTS for the optional `--reason "..."` flag.
+
+Add a Decision Log entry in `.gsd-t/progress.md`:
+
+```
+| {YYYY-MM-DD} | Removed backlog item "{title}"{reason_suffix} |
+```
+
+Where `{reason_suffix}` is ` — Reason: {reason}` if `--reason` was provided, or empty if not.
+
+## Step 6: Document Ripple
+
+If `.gsd-t/progress.md` exists, update:
+
+### Always update:
+1. **`.gsd-t/progress.md`** — Decision Log entry for the removal (done in Step 5)
+
+### Check if affected:
+2. **`.gsd-t/techdebt.md`** — If the removed item was related to tracked debt, note its removal
+
+### Skip what's not affected — most removals only touch progress.md.
+
+## Step 7: Test Verification
+
+Verify the backlog file is well-formed after removal:
+
+1. Read `.gsd-t/backlog.md` and confirm:
+   - Entries are numbered sequentially (1, 2, 3...) with no gaps
+   - Each entry follows the format: `## {N}. {title}` + metadata line + date line + description
+   - No orphaned content or broken formatting
+2. If any issues found, fix them before finishing
+
+$ARGUMENTS

package/commands/gsd-t-backlog-settings.md

@@ -0,0 +1,154 @@
+# GSD-T: Backlog Settings — Manage Types, Apps, Categories, and Defaults
+
+You are managing the backlog settings file. This controls the allowed values for types, apps, and categories used by backlog entries, and the default app assignment.
+
+## Step 1: Read Settings
+
+Read `.gsd-t/backlog-settings.md` and parse current settings:
+- **Types** section — list of allowed type values
+- **Apps** section — list of allowed app values
+- **Categories** section — list of allowed category values
+- **Defaults** section — Default App and Auto-categorize values
+
+If the file doesn't exist:
+- "No backlog settings found. Run `/gsd-t-init` with backlog support to create settings."
+- Stop.
+
+## Step 2: Parse Subcommand
+
+Parse $ARGUMENTS to identify the subcommand and its arguments.
+
+Valid subcommands:
+- `list` — no additional args
+- `add-type <name>` — requires a name
+- `remove-type <name>` — requires a name
+- `add-app <name>` — requires a name
+- `remove-app <name>` — requires a name
+- `add-category <name>` — requires a name
+- `remove-category <name>` — requires a name
+- `default-app <name>` — requires a name
+
+If no subcommand or an invalid subcommand is provided:
+- Show usage: "Usage: `/gsd-t-backlog-settings <subcommand> [args]`"
+- List available subcommands with brief descriptions
+- Stop.
+
+If a subcommand requires a name argument and none is provided:
+- "Missing argument. Usage: `/gsd-t-backlog-settings {subcommand} <name>`"
+- Stop.
+
+## Step 3: Validate
+
+Perform validation based on the subcommand:
+
+- **add-type/add-app/add-category**: Convert name to lowercase. Check the appropriate section for duplicates. If the value already exists: "'{name}' already exists in {section}." — Stop.
+- **remove-type/remove-app/remove-category**: Check the appropriate section for existence. If the value doesn't exist: "'{name}' not found in {section}." — Stop.
+- **default-app**: Convert name to lowercase. Check that the name exists in the Apps section. If not: "'{name}' is not in the Apps list. Add it first with `add-app {name}`." — Stop.
+
+## Step 4: Execute Subcommand
+
+### `list`
+
+Display all current settings in a formatted view:
+
+```
+Backlog Settings:
+
+Types: bug, feature, improvement, ux, architecture
+Apps: {app1}, {app2}
+Categories: {cat1}, {cat2}
+
+Defaults:
+  Default App: {app}
+  Auto-categorize: true
+```
+
+Stop after displaying. No file modifications needed.
+
+### `add-type`, `add-app`, `add-category`
+
+Append the new value (lowercase) to the appropriate section in `.gsd-t/backlog-settings.md`.
+
+Format: `- {name}` added as the last item in the section's list.
+
+Confirm: "Added '{name}' to {section}."
+
+### `remove-type`, `remove-app`, `remove-category`
+
+Before removing, read `.gsd-t/backlog.md` and check if any existing entries use this value.
+
+If entries use this value:
+- Warn: "'{name}' is currently used by {count} backlog entry/entries: {titles}."
+- Ask for confirmation: "Remove anyway? (y/n)"
+- If user declines, stop.
+
+Remove the value from the appropriate section in `.gsd-t/backlog-settings.md`.
+
+Confirm: "Removed '{name}' from {section}."
+
+### `default-app`
+
+Update the `- **Default App:** {value}` line in the Defaults section of `.gsd-t/backlog-settings.md`.
+
+Confirm: "Default app changed to '{name}'."
+
+## Step 5: Rewrite Settings File
+
+Skip this step for the `list` subcommand.
+
+Rewrite `.gsd-t/backlog-settings.md` with the updated settings, preserving the file format:
+
+```markdown
+# Backlog Settings
+
+## Types
+- {type1}
+- {type2}
+...
+
+## Apps
+- {app1}
+- {app2}
+...
+
+## Categories
+- {cat1}
+- {cat2}
+...
+
+## Defaults
+- **Default App:** {app}
+- **Auto-categorize:** true
+```
+
+## Step 6: Document Ripple
+
+Skip this step for the `list` subcommand.
+
+If `.gsd-t/progress.md` exists, update:
+
+### Always update:
+1. **`.gsd-t/progress.md`** — Log the settings change in the Decision Log:
+   - For add: `"Added '{name}' to backlog {section}"`
+   - For remove: `"Removed '{name}' from backlog {section}"`
+   - For default-app: `"Changed default app to '{name}'"`
+
+### Check if affected:
+2. **`.gsd-t/contracts/file-format-contract.md`** — If this change affects the documented settings format, flag it (should be rare)
+
+### Skip what's not affected — most settings changes only touch progress.md.
+
+## Step 7: Test Verification
+
+Skip this step for the `list` subcommand.
+
+Verify the settings file is well-formed after update:
+
+1. Read `.gsd-t/backlog-settings.md` and confirm:
+   - All four sections exist: Types, Apps, Categories, Defaults
+   - Each section's items are `- {value}` format, lowercase
+   - Defaults section has `- **Default App:** {value}` and `- **Auto-categorize:** {value}`
+   - No empty lines within a section's list, no orphaned content
+2. If any issues found, fix them before finishing
+
+$ARGUMENTS

package/commands/gsd-t-help.md

@@ -46,6 +46,16 @@ UTILITIES
   promote-debt        Convert techdebt items to milestones
   populate            Auto-populate docs from existing codebase
 
+BACKLOG
+───────────────────────────────────────────────────────────────────────────────
+  backlog-add         Capture item, auto-categorize, append to backlog
+  backlog-list        Filtered, ordered view of backlog items
+  backlog-move        Reorder items by position (priority)
+  backlog-edit        Modify entry fields (title, type, app, category)
+  backlog-remove      Drop item with optional reason
+  backlog-promote     Refine, classify, and launch GSD-T workflow
+  backlog-settings    Manage types, apps, categories, and defaults
+
 ───────────────────────────────────────────────────────────────────────────────
 Type /user:gsd-t-help {command} for detailed help on any command.
 Example: /user:gsd-t-help impact
@@ -247,6 +257,48 @@ Use these when user asks for help on a specific command:
 - **Updates**: `docs/requirements.md`, `docs/architecture.md`, `docs/workflows.md`, `docs/infrastructure.md`, `.gsd-t/progress.md`
 - **Use when**: You have an existing codebase and want to fill docs with real findings instead of placeholders
 
+### backlog-add
+- **Summary**: Capture a new backlog item with auto-categorization
+- **Auto-invoked**: No
+- **Files**: `.gsd-t/backlog.md`, `.gsd-t/backlog-settings.md`
+- **Use when**: You have an idea, bug, or improvement to capture for later
+
+### backlog-list
+- **Summary**: Display backlog with optional filtering by type, app, or category
+- **Auto-invoked**: No
+- **Files**: `.gsd-t/backlog.md` (read-only)
+- **Use when**: Reviewing the backlog to see what's queued up
+
+### backlog-move
+- **Summary**: Reorder a backlog item to change its priority
+- **Auto-invoked**: No
+- **Files**: `.gsd-t/backlog.md`
+- **Use when**: Reprioritizing items in the backlog
+
+### backlog-edit
+- **Summary**: Modify fields of an existing backlog entry
+- **Auto-invoked**: No
+- **Files**: `.gsd-t/backlog.md`, `.gsd-t/backlog-settings.md`
+- **Use when**: Updating details of a captured backlog item
+
+### backlog-remove
+- **Summary**: Remove a backlog item with optional reason
+- **Auto-invoked**: No
+- **Files**: `.gsd-t/backlog.md`
+- **Use when**: Dropping an item that's no longer relevant
+
+### backlog-promote
+- **Summary**: Refine a backlog item and launch the appropriate GSD-T workflow
+- **Auto-invoked**: No
+- **Files**: `.gsd-t/backlog.md`, `.gsd-t/progress.md`
+- **Use when**: Ready to act on a backlog item — promotes to milestone, quick, debug, or feature
+
+### backlog-settings
+- **Summary**: Manage allowed types, apps, categories, and default settings
+- **Auto-invoked**: No
+- **Files**: `.gsd-t/backlog-settings.md`
+- **Use when**: Customizing the classification dimensions for your project
+
 ## Unknown Command
 
 If user asks for help on unrecognized command:

package/commands/gsd-t-init.md

@@ -26,9 +26,26 @@ If yes, read `.gsd/` state and create equivalent `.gsd-t/` structure.
 │   └── .gitkeep
 ├── domains/
 │   └── .gitkeep
+├── backlog.md
+├── backlog-settings.md
 └── progress.md
 ```
 
+## Step 2.5: Initialize Backlog
+
+Create the backlog files from templates:
+1. Copy `templates/backlog.md` → `.gsd-t/backlog.md`
+2. Copy `templates/backlog-settings.md` → `.gsd-t/backlog-settings.md`
+
+### Category Derivation
+
+Read the project's `CLAUDE.md` (if it exists) to auto-populate backlog settings:
+
+1. **Apps**: Scan for app names, service names, or product names (look for headings, "Tech Stack" sections, or named components). Populate the `## Apps` section in `backlog-settings.md` with discovered names (lowercase).
+2. **Categories**: Scan for domain concepts, module names, and technical areas (e.g., "authentication", "payments", "api", "database"). Populate the `## Categories` section.
+3. **Default App**: Set `**Default App:**` to the most prominent app found (the one mentioned most, or the first one). If only one app is found, use it.
+4. **If nothing found**: Leave the placeholder values from the template — the user can configure later via `/user:gsd-t-backlog-settings`.
+
 ## Step 3: Initialize Progress File
 
 Create `.gsd-t/progress.md`:
@@ -85,6 +102,9 @@ Create a starter template:
 ## Conventions
 - {Coding style, naming patterns — fill this in}
 
+## Workflow Preferences
+<!-- Override global defaults. Delete what you don't need to override. -->
+
 ## GSD-T Workflow
 This project uses contract-driven development.
 - State: .gsd-t/progress.md
@@ -155,9 +175,10 @@ After initialization:
 ## Step 8: Report
 
 Tell the user:
-1. What was created
+1. What was created (including backlog files: `.gsd-t/backlog.md` and `.gsd-t/backlog-settings.md`)
 2. What they should fill in (CLAUDE.md details, requirements)
-3. Recommended next step:
+3. Backlog settings status: whether apps/categories were auto-derived from CLAUDE.md or need manual configuration via `/user:gsd-t-backlog-settings`
+4. Recommended next step:
    - New project: "Define your milestone, then run /user:gsd-t-partition"
    - Existing code: "I've mapped the codebase. Ready for /user:gsd-t-partition {milestone}"
 

package/commands/gsd-t-status.md

@@ -21,6 +21,11 @@ Domains:
   {domain-2}: {completed}/{total} tasks {✅ done | 🔄 in progress | ⏳ blocked}
   {domain-3}: {completed}/{total} tasks {✅ done | 🔄 in progress | ⏳ blocked}
 
+Backlog: {N} items
+  1. {title} ({type})
+  2. {title} ({type})
+  3. {title} ({type})
+
 Next checkpoint: {description} — waiting on {domain} Task {N}
 Next action: {what should happen next}
 
@@ -28,6 +33,10 @@ Recent decisions:
   - {latest decision from Decision Log}
 ```
 
+### Backlog Section
+
+If `.gsd-t/backlog.md` exists, read and parse it. Show total count and top 3 items (position, title, type). If no backlog file exists, skip the Backlog section entirely. If the backlog file exists but is empty (no entries), show `Backlog: No items`.
+
 If there are blockers or issues, highlight them.
 If the user provides $ARGUMENTS, focus the status on that specific domain or aspect.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.6.0",
-  "description": "GSD-T: Contract-Driven Development for Claude Code — 27 slash commands with impact analysis, test sync, and milestone archival",
+  "version": "2.8.1",
+  "description": "GSD-T: Contract-Driven Development for Claude Code — 34 slash commands with backlog management, impact analysis, test sync, and milestone archival",
   "author": "Tekyz, Inc.",
   "license": "MIT",
   "repository": {

package/templates/CLAUDE-global.md

@@ -51,6 +51,13 @@ PROJECT or FEATURE or SCAN
 | `/user:gsd-t-quick` | Fast task, respects contracts |
 | `/user:gsd-t-populate` | Auto-populate docs from existing codebase |
 | `/user:gsd-t-resume` | Restore context, continue |
+| `/user:gsd-t-backlog-add` | Capture item, auto-categorize, append to backlog |
+| `/user:gsd-t-backlog-list` | Filtered, ordered view of backlog items |
+| `/user:gsd-t-backlog-move` | Reorder items by position (priority) |
+| `/user:gsd-t-backlog-edit` | Modify backlog entry fields |
+| `/user:gsd-t-backlog-remove` | Drop item with optional reason |
+| `/user:gsd-t-backlog-promote` | Refine, classify, launch GSD-T workflow |
+| `/user:gsd-t-backlog-settings` | Manage types, apps, categories, defaults |
 | `/user:branch` | Create and switch to a new git branch |
 | `/user:checkin` | Auto-bump version, stage, commit, and push |
 | `/user:Claude-md` | Reload and apply CLAUDE.md directives |
@@ -210,6 +217,31 @@ Projects can specify an autonomy level in their project CLAUDE.md:
 
 If not specified, use Level 2.
 
+## Workflow Preferences (Defaults — override in project CLAUDE.md)
+
+### Research Policy
+Before planning a phase, evaluate whether research is needed:
+
+**Run research when:**
+- Phase involves unfamiliar libraries, APIs, or services
+- Architectural decisions are required
+- Integrating external systems
+- Phase scope is ambiguous or complex
+
+**Skip research when:**
+- Patterns are already established from earlier phases
+- Straightforward CRUD, UI, or config work
+- Domain is well understood
+- Phase builds directly on existing code patterns
+
+If in doubt, skip research and proceed — research if execution reveals gaps.
+
+### Phase Flow
+- Upon completing a phase, automatically proceed to the next phase
+- ONLY run Discussion phase if truly required (clear path → skip to Plan)
+- ALWAYS self-verify work by running verification commands
+- NEVER pause to show verification steps — execute them
+
 
 # Don't Do These Things
 

package/templates/CLAUDE-project.md

@@ -36,6 +36,20 @@ This project uses contract-driven development.
 - Contracts: .gsd-t/contracts/
 - Domains: .gsd-t/domains/
 
+## Workflow Preferences
+<!-- Override global defaults from ~/.claude/CLAUDE.md -->
+<!-- Delete lines you don't need to override — globals apply automatically -->
+
+### Research Policy
+<!-- Example overrides: -->
+<!-- "Always research — this project uses cutting-edge APIs" -->
+<!-- "Skip research — well-understood CRUD app" -->
+
+### Phase Flow
+<!-- Example overrides: -->
+<!-- "ALWAYS run Discussion — architecture decisions are critical" -->
+<!-- "Skip discuss unless truly required" -->
+
 ## Project-Specific Conventions
 <!-- Add conventions that override or extend the global CLAUDE.md -->
 

package/templates/backlog-settings.md

@@ -0,0 +1,18 @@
+# Backlog Settings
+
+## Types
+- bug
+- feature
+- improvement
+- ux
+- architecture
+
+## Apps
+- {app1}
+- {app2}
+
+## Categories
+
+## Defaults
+- **Default App:** {app}
+- **Auto-categorize:** true

package/templates/backlog.md

@@ -0,0 +1 @@
+# Backlog