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 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
@@ -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 |
|
||||
|
||||
<sup>¹ Contributed by reddit user OracleGreyBeard</sup>
|
||||
|
||||
182
commands/gsd/add-todo.md
Normal file
182
commands/gsd/add-todo.md
Normal file
@@ -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
|
||||
---
|
||||
|
||||
<objective>
|
||||
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.
|
||||
</objective>
|
||||
|
||||
<context>
|
||||
@.planning/STATE.md
|
||||
</context>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="ensure_directory">
|
||||
```bash
|
||||
mkdir -p .planning/todos/pending .planning/todos/done
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="check_existing_areas">
|
||||
```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.
|
||||
</step>
|
||||
|
||||
<step name="extract_content">
|
||||
**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
|
||||
</step>
|
||||
|
||||
<step name="infer_area">
|
||||
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.
|
||||
</step>
|
||||
|
||||
<step name="check_duplicates">
|
||||
```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
|
||||
</step>
|
||||
|
||||
<step name="create_file">
|
||||
```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"]
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="update_state">
|
||||
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"
|
||||
</step>
|
||||
|
||||
<step name="git_commit">
|
||||
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]"
|
||||
</step>
|
||||
|
||||
<step name="confirm">
|
||||
```
|
||||
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)
|
||||
```
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<output>
|
||||
- `.planning/todos/pending/[date]-[slug].md`
|
||||
- Updated `.planning/STATE.md` (if exists)
|
||||
</output>
|
||||
|
||||
<anti_patterns>
|
||||
- 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
|
||||
</anti_patterns>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] 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
|
||||
</success_criteria>
|
||||
217
commands/gsd/check-todos.md
Normal file
217
commands/gsd/check-todos.md
Normal file
@@ -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
|
||||
---
|
||||
|
||||
<objective>
|
||||
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.
|
||||
</objective>
|
||||
|
||||
<context>
|
||||
@.planning/STATE.md
|
||||
@.planning/ROADMAP.md
|
||||
</context>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="check_exist">
|
||||
```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.
|
||||
</step>
|
||||
|
||||
<step name="parse_filter">
|
||||
Check for area filter in arguments:
|
||||
- `/gsd:check-todos` → show all
|
||||
- `/gsd:check-todos api` → filter to area:api only
|
||||
</step>
|
||||
|
||||
<step name="list_todos">
|
||||
```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.
|
||||
</step>
|
||||
|
||||
<step name="handle_selection">
|
||||
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."
|
||||
</step>
|
||||
|
||||
<step name="load_context">
|
||||
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.
|
||||
</step>
|
||||
|
||||
<step name="check_roadmap">
|
||||
```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
|
||||
</step>
|
||||
|
||||
<step name="offer_actions">
|
||||
**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
|
||||
</step>
|
||||
|
||||
<step name="execute_action">
|
||||
**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.
|
||||
</step>
|
||||
|
||||
<step name="update_state">
|
||||
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.
|
||||
</step>
|
||||
|
||||
<step name="git_commit">
|
||||
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]"
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<output>
|
||||
- Moved todo to `.planning/todos/done/` (if "Work on it now")
|
||||
- Updated `.planning/STATE.md` (if todo count changed)
|
||||
</output>
|
||||
|
||||
<anti_patterns>
|
||||
- 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
|
||||
</anti_patterns>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] 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/)
|
||||
</success_criteria>
|
||||
@@ -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
|
||||
|
||||
@@ -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`
|
||||
</step>
|
||||
|
||||
<step name="report">
|
||||
@@ -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]
|
||||
```
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user