From 3787f50ea67ee8bf234364e4d3164a0ddfc1345a Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Sun, 11 Jan 2026 11:46:01 -0600 Subject: [PATCH] feat: add todo capture system for mid-session ideas Adds /gsd:add-todo and /gsd:check-todos commands for capturing ideas during work sessions without losing context. Features: - Capture todos from conversation context or explicit description - Structured frontmatter (created, title, area, files) - Area inference from file paths for grouping - Duplicate detection before creating - Filter todos by area - Route to appropriate action (work now, add to phase, brainstorm) - Git commits on capture and when starting work Closes #48 Co-Authored-By: Claude Opus 4.5 --- README.md | 3 + commands/gsd/add-todo.md | 182 ++++++++++++++++++++++++++ commands/gsd/check-todos.md | 217 +++++++++++++++++++++++++++++++ commands/gsd/help.md | 38 ++++++ commands/gsd/progress.md | 4 + get-shit-done/templates/state.md | 11 ++ 6 files changed, 455 insertions(+) create mode 100644 commands/gsd/add-todo.md create mode 100644 commands/gsd/check-todos.md diff --git a/README.md b/README.md index 81fea5606..0b082f4ee 100644 --- a/README.md +++ b/README.md @@ -243,6 +243,7 @@ GSD handles it for you: | `PLAN.md` | Atomic task with XML structure, verification steps | | `SUMMARY.md` | What happened, what changed, committed to history | | `ISSUES.md` | Deferred enhancements tracked across sessions | +| `todos/` | Captured ideas and tasks for later work | Size limits based on where Claude's quality degrades. Stay under, get consistent excellence. @@ -332,6 +333,8 @@ You're never locked in. The system adapts. | `/gsd:resume-work` | Restore from last session | | `/gsd:resume-task [id]` | Resume interrupted subagent execution | | `/gsd:consider-issues` | Review deferred issues, close resolved, identify urgent | +| `/gsd:add-todo [desc]` | Capture idea or task from conversation for later | +| `/gsd:check-todos [area]` | List pending todos, select one to work on | | `/gsd:help` | Show all commands and usage guide | ¹ Contributed by reddit user OracleGreyBeard diff --git a/commands/gsd/add-todo.md b/commands/gsd/add-todo.md new file mode 100644 index 000000000..6dfef9031 --- /dev/null +++ b/commands/gsd/add-todo.md @@ -0,0 +1,182 @@ +--- +name: gsd:add-todo +description: Capture idea or task as todo from current conversation context +argument-hint: [optional description] +allowed-tools: + - Read + - Write + - Bash + - Glob +--- + + +Capture an idea, task, or issue that surfaces during a GSD session as a structured todo for later work. + +Enables "thought → capture → continue" flow without losing context or derailing current work. + + + +@.planning/STATE.md + + + + + +```bash +mkdir -p .planning/todos/pending .planning/todos/done +``` + + + +```bash +ls .planning/todos/pending/*.md 2>/dev/null | xargs -I {} grep "^area:" {} 2>/dev/null | cut -d' ' -f2 | sort -u +``` + +Note existing areas for consistency in infer_area step. + + + +**With arguments:** Use as the title/focus. +- `/gsd:add-todo Add auth token refresh` → title = "Add auth token refresh" + +**Without arguments:** Analyze recent conversation to extract: +- The specific problem, idea, or task discussed +- Relevant file paths mentioned +- Technical details (error messages, line numbers, constraints) + +Formulate: +- `title`: 3-10 word descriptive title (action verb preferred) +- `problem`: What's wrong or why this is needed +- `solution`: Approach hints or "TBD" if just an idea +- `files`: Relevant paths with line numbers from conversation + + + +Infer area from file paths: + +| Path pattern | Area | +|--------------|------| +| `src/api/*`, `api/*` | `api` | +| `src/components/*`, `src/ui/*` | `ui` | +| `src/auth/*`, `auth/*` | `auth` | +| `src/db/*`, `database/*` | `database` | +| `tests/*`, `__tests__/*` | `testing` | +| `docs/*` | `docs` | +| `.planning/*` | `planning` | +| `scripts/*`, `bin/*` | `tooling` | +| No files or unclear | `general` | + +Use existing area from step 2 if similar match exists. + + + +```bash +grep -l -i "[key words from title]" .planning/todos/pending/*.md 2>/dev/null +``` + +If potential duplicate found: +1. Read the existing todo +2. Compare scope + +If overlapping, use AskUserQuestion: +- header: "Duplicate?" +- question: "Similar todo exists: [title]. What would you like to do?" +- options: + - "Skip" — keep existing todo + - "Replace" — update existing with new context + - "Add anyway" — create as separate todo + + + +```bash +timestamp=$(date "+%Y-%m-%dT%H:%M") +date_prefix=$(date "+%Y-%m-%d") +``` + +Generate slug from title (lowercase, hyphens, no special chars). + +Write to `.planning/todos/pending/${date_prefix}-${slug}.md`: + +```markdown +--- +created: [timestamp] +title: [title] +area: [area] +files: + - [file:lines] +--- + +## Problem + +[problem description - enough context for future Claude to understand weeks later] + +## Solution + +[approach hints or "TBD"] +``` + + + +If `.planning/STATE.md` exists: + +1. Count todos: `ls .planning/todos/pending/*.md 2>/dev/null | wc -l` +2. Update "### Pending Todos" under "## Accumulated Context" + + + +Commit the todo and any updated state: + +```bash +git add .planning/todos/pending/[filename] +[ -f .planning/STATE.md ] && git add .planning/STATE.md +git commit -m "$(cat <<'EOF' +docs: capture todo - [title] + +Area: [area] +EOF +)" +``` + +Confirm: "Committed: docs: capture todo - [title]" + + + +``` +Todo saved: .planning/todos/pending/[filename] + + [title] + Area: [area] + Files: [count] referenced + +--- + +Would you like to: + +1. Continue with current work +2. Add another todo +3. View all todos (/gsd:check-todos) +``` + + + + + +- `.planning/todos/pending/[date]-[slug].md` +- Updated `.planning/STATE.md` (if exists) + + + +- Don't create todos for work in current plan (that's deviation rule territory) +- Don't create elaborate solution sections — captures ideas, not plans +- Don't block on missing information — "TBD" is fine + + + +- [ ] Directory structure exists +- [ ] Todo file created with valid frontmatter +- [ ] Problem section has enough context for future Claude +- [ ] No duplicates (checked and resolved) +- [ ] Area consistent with existing todos +- [ ] STATE.md updated if exists +- [ ] Todo and state committed to git + diff --git a/commands/gsd/check-todos.md b/commands/gsd/check-todos.md new file mode 100644 index 000000000..c89b93a1f --- /dev/null +++ b/commands/gsd/check-todos.md @@ -0,0 +1,217 @@ +--- +name: gsd:check-todos +description: List pending todos and select one to work on +argument-hint: [area filter] +allowed-tools: + - Read + - Write + - Bash + - Glob + - AskUserQuestion +--- + + +List all pending todos, allow selection, load full context for the selected todo, and route to appropriate action. + +Enables reviewing captured ideas and deciding what to work on next. + + + +@.planning/STATE.md +@.planning/ROADMAP.md + + + + + +```bash +TODO_COUNT=$(ls .planning/todos/pending/*.md 2>/dev/null | wc -l | tr -d ' ') +echo "Pending todos: $TODO_COUNT" +``` + +If count is 0: +``` +No pending todos. + +Todos are captured during work sessions with /gsd:add-todo. + +--- + +Would you like to: + +1. Continue with current phase (/gsd:progress) +2. Add a todo now (/gsd:add-todo) +``` + +Exit. + + + +Check for area filter in arguments: +- `/gsd:check-todos` → show all +- `/gsd:check-todos api` → filter to area:api only + + + +```bash +for file in .planning/todos/pending/*.md; do + created=$(grep "^created:" "$file" | cut -d' ' -f2) + title=$(grep "^title:" "$file" | cut -d':' -f2- | xargs) + area=$(grep "^area:" "$file" | cut -d' ' -f2) + echo "$created|$title|$area|$file" +done | sort +``` + +Apply area filter if specified. Display as numbered list: + +``` +Pending Todos: + +1. Add auth token refresh (api, 2d ago) +2. Fix modal z-index issue (ui, 1d ago) +3. Refactor database connection pool (database, 5h ago) + +--- + +Reply with a number to view details, or: +- `/gsd:check-todos [area]` to filter by area +- `q` to exit +``` + +Format age as relative time. + + + +Wait for user to reply with a number. + +If valid: load selected todo, proceed. +If invalid: "Invalid selection. Reply with a number (1-[N]) or `q` to exit." + + + +Read the todo file completely. Display: + +``` +## [title] + +**Area:** [area] +**Created:** [date] ([relative time] ago) +**Files:** [list or "None"] + +### Problem +[problem section content] + +### Solution +[solution section content] +``` + +If `files` field has entries, read and briefly summarize each. + + + +```bash +ls .planning/ROADMAP.md 2>/dev/null && echo "Roadmap exists" +``` + +If roadmap exists: +1. Check if todo's area matches an upcoming phase +2. Check if todo's files overlap with a phase's scope +3. Note any match for action options + + + +**If todo maps to a roadmap phase:** + +Use AskUserQuestion: +- header: "Action" +- question: "This todo relates to Phase [N]: [name]. What would you like to do?" +- options: + - "Work on it now" — move to done, start working + - "Add to phase plan" — include when planning Phase [N] + - "Brainstorm approach" — think through before deciding + - "Put it back" — return to list + +**If no roadmap match:** + +Use AskUserQuestion: +- header: "Action" +- question: "What would you like to do with this todo?" +- options: + - "Work on it now" — move to done, start working + - "Create a phase" — /gsd:add-phase with this scope + - "Brainstorm approach" — think through before deciding + - "Put it back" — return to list + + + +**Work on it now:** +```bash +mv ".planning/todos/pending/[filename]" ".planning/todos/done/" +``` +Update STATE.md todo count. Present problem/solution context. Begin work or ask how to proceed. + +**Add to phase plan:** +Note todo reference in phase planning notes. Keep in pending. Return to list or exit. + +**Create a phase:** +Display: `/gsd:add-phase [description from todo]` +Keep in pending. User runs command in fresh context. + +**Brainstorm approach:** +Keep in pending. Start discussion about problem and approaches. + +**Put it back:** +Return to list_todos step. + + + +After any action that changes todo count: + +```bash +ls .planning/todos/pending/*.md 2>/dev/null | wc -l +``` + +Update STATE.md "### Pending Todos" section if exists. + + + +If todo was moved to done/, commit the change: + +```bash +git add .planning/todos/done/[filename] +git rm --cached .planning/todos/pending/[filename] 2>/dev/null || true +[ -f .planning/STATE.md ] && git add .planning/STATE.md +git commit -m "$(cat <<'EOF' +docs: start work on todo - [title] + +Moved to done/, beginning implementation. +EOF +)" +``` + +Confirm: "Committed: docs: start work on todo - [title]" + + + + + +- Moved todo to `.planning/todos/done/` (if "Work on it now") +- Updated `.planning/STATE.md` (if todo count changed) + + + +- Don't delete todos — move to done/ when work begins +- Don't start work without moving to done/ first +- Don't create plans from this command — route to /gsd:plan-phase or /gsd:add-phase + + + +- [ ] All pending todos listed with title, area, age +- [ ] Area filter applied if specified +- [ ] Selected todo's full context loaded +- [ ] Roadmap context checked for phase match +- [ ] Appropriate actions offered +- [ ] Selected action executed +- [ ] STATE.md updated if todo count changed +- [ ] Changes committed to git (if todo moved to done/) + diff --git a/commands/gsd/help.md b/commands/gsd/help.md index e4b8ce0c0..2b6fafefe 100644 --- a/commands/gsd/help.md +++ b/commands/gsd/help.md @@ -225,6 +225,32 @@ Review deferred issues with codebase context. Usage: `/gsd:consider-issues` +### Todo Management + +**`/gsd:add-todo [description]`** +Capture idea or task as todo from current conversation. + +- Extracts context from conversation (or uses provided description) +- Creates structured todo file in `.planning/todos/pending/` +- Infers area from file paths for grouping +- Checks for duplicates before creating +- Updates STATE.md todo count + +Usage: `/gsd:add-todo` (infers from conversation) +Usage: `/gsd:add-todo Add auth token refresh` + +**`/gsd:check-todos [area]`** +List pending todos and select one to work on. + +- Lists all pending todos with title, area, age +- Optional area filter (e.g., `/gsd:check-todos api`) +- Loads full context for selected todo +- Routes to appropriate action (work now, add to phase, brainstorm) +- Moves todo to done/ when work begins + +Usage: `/gsd:check-todos` +Usage: `/gsd:check-todos api` + ### Utility Commands **`/gsd:help`** @@ -239,6 +265,9 @@ Show this command reference. ├── STATE.md # Project memory & context ├── ISSUES.md # Deferred enhancements (created when needed) ├── config.json # Workflow mode & gates +├── todos/ # Captured ideas and tasks +│ ├── pending/ # Todos waiting to be worked on +│ └── done/ # Completed todos ├── codebase/ # Codebase map (brownfield projects) │ ├── STACK.md # Languages, frameworks, dependencies │ ├── ARCHITECTURE.md # Patterns, layers, data flow @@ -306,6 +335,15 @@ Change anytime by editing `.planning/config.json` /gsd:new-project # Start next milestone ``` +**Capturing ideas during work:** + +``` +/gsd:add-todo # Capture from conversation context +/gsd:add-todo Fix modal z-index # Capture with explicit description +/gsd:check-todos # Review and work on todos +/gsd:check-todos api # Filter by area +``` + ## Getting Help - Read `.planning/PROJECT.md` for project vision diff --git a/commands/gsd/progress.md b/commands/gsd/progress.md index 5f0c628fe..fa02103cc 100644 --- a/commands/gsd/progress.md +++ b/commands/gsd/progress.md @@ -57,6 +57,7 @@ If missing STATE.md or ROADMAP.md: inform what's missing, suggest running `/gsd: - Calculate: total plans, completed plans, remaining plans - Note any blockers, concerns, or deferred issues - Check for CONTEXT.md: For phases without PLAN.md files, check if `{phase}-CONTEXT.md` exists in phase directory +- Count pending todos: `ls .planning/todos/pending/*.md 2>/dev/null | wc -l` @@ -83,6 +84,9 @@ CONTEXT: [✓ if CONTEXT.md exists | - if not] ## Open Issues - [any deferred issues or blockers] +## Pending Todos +- [count] pending — /gsd:check-todos to review + ## What's Next [Next phase/plan objective from ROADMAP] ``` diff --git a/get-shit-done/templates/state.md b/get-shit-done/templates/state.md index 3796cd1a2..1e270f62c 100644 --- a/get-shit-done/templates/state.md +++ b/get-shit-done/templates/state.md @@ -60,6 +60,12 @@ Recent decisions affecting current work: None yet. +### Pending Todos + +[From .planning/todos/pending/ — ideas captured during sessions] + +None yet. + ### Blockers/Concerns [Issues that affect future work] @@ -152,6 +158,11 @@ Updated after each plan completion. - Effort estimate if known - Helps phase planning identify what to address +**Pending Todos:** Ideas captured via /gsd:add-todo +- Count of pending todos +- Reference to .planning/todos/pending/ +- Brief list if few, count if many (e.g., "5 pending todos — see /gsd:check-todos") + **Blockers/Concerns:** From "Next Phase Readiness" sections - Issues that affect future work - Prefix with originating phase