Todo Init

Purpose

Initialize and configure todo tracking for the current project by creating or updating the .claude/todo-settings-local.json configuration file.

Execution Flow

Phase 1: Check Existing Configuration

1. Search for existing settings:

   • Look for .claude/todo-settings-local.json in current directory
   • Search parent directories up to home

2. If found:

   {
     "question": "Todo settings already exist. What would you like to do?",
     "header": "Existing Config",
     "options": [
       {"label": "View current settings", "description": "Display the current configuration"},
       {"label": "Update settings", "description": "Modify existing configuration"},
       {"label": "Reset to defaults", "description": "Overwrite with default settings"}
     ],
     "multiSelect": false
   }
   

3. If not found: Proceed to Phase 2

Phase 2: Determine Todos Directory

Ask user where to store todo files:

{
  "question": "Where should todo files be stored?",
  "header": "Todos Directory",
  "options": [
    {"label": "Auto-detect", "description": "Find existing Todos/ directory in knowledge base"},
    {"label": "Create new", "description": "Create Todos/ directory in specified location"},
    {"label": "Specify path", "description": "Enter a custom path for todos"}
  ],
  "multiSelect": false
}

Auto-detect logic:

1. Search for existing Todos/ directory with RULE.md
2. If found, use that path
3. If not found, suggest creating one

Create new logic:

1. Ask for parent directory (knowledge base root)
2. Create Todos/, Todos/active/, Todos/completed/
3. Create governance files (RULE.md, README.md for each)

Phase 3: Configure Tracking Options

{
  "question": "Which directories should be tracked for todos?",
  "header": "Tracked Dirs",
  "options": [
    {"label": "All directories", "description": "Track all file operations in the project"},
    {"label": "Knowledge base only", "description": "Only track files in the knowledge base"},
    {"label": "Specific directories", "description": "Choose specific directories to track"}
  ],
  "multiSelect": false
}

If "Specific directories" selected:

• List available directories
• Allow multi-select

Phase 4: Configure Detection Patterns

{
  "question": "Use default detection patterns or customize?",
  "header": "Patterns",
  "options": [
    {"label": "Use defaults (Recommended)", "description": "Standard patterns for requests, deadlines, and actions"},
    {"label": "Customize patterns", "description": "Add or remove detection patterns"}
  ],
  "multiSelect": false
}

Default patterns include:

• Request: "please provide", "please reply", "need you to"
• Deadline: "by EOD", "deadline", "ASAP", "urgent"
• Action: "action item", "TODO", "follow up"

If customize:

• Show current patterns by category
• Allow add/remove for each category

Phase 5: Configure Behavior

{
  "question": "Configure additional settings",
  "header": "Options",
  "options": [
    {"label": "Require confirmation", "description": "Always ask before creating todos (Recommended)"},
    {"label": "Auto-create", "description": "Create todos without asking"}
  ],
  "multiSelect": false
}

{
  "question": "Default priority for new todos?",
  "header": "Priority",
  "options": [
    {"label": "Medium (Recommended)", "description": "Standard priority unless urgency detected"},
    {"label": "High", "description": "Default to high priority"},
    {"label": "Low", "description": "Default to low priority"}
  ],
  "multiSelect": false
}

Phase 6: Create Configuration File

1. Ensure .claude/ directory exists:

   mkdir -p [project_root]/.claude
   

2. Generate settings file:

   {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "$comment": "Todo Tracker settings - managed by /todo-init",
   
     "enabled": true,
   
     "todos_directory": "[configured path]",
   
     "tracked_directories": [
       "[configured directories]"
     ],
   
     "patterns": {
       "request": ["..."],
       "deadline": ["..."],
       "action": ["..."]
     },
   
     "default_priority": "[selected priority]",
   
     "auto_due_date_detection": true,
   
     "confirmation_required": [true/false based on selection]
   }
   

3. Write to .claude/todo-settings-local.json

Phase 7: Create Todos Directory Structure (if needed)

If creating new Todos directory:

1. Create directory structure:

   [todos_directory]/
   ├── RULE.md
   ├── README.md
   ├── active/
   │   └── README.md
   └── completed/
       └── README.md
   

2. Create RULE.md:

   # Todos - Personal Task Management
   
   ## Purpose
   Centralized management of all todo items.
   
   ## Structure
   - active/: Active todos (pending, in_progress, blocked)
   - completed/: Archived completed todos
   
   ## Naming Convention
   YYYY-MM-DD_todo-title-slug.md
   
   ## Required Frontmatter
   - title: Brief description (required)
   - status: pending | in_progress | blocked | completed
   - priority: high | medium | low
   - created_at: YYYY-MM-DD
   
   ## Optional Fields
   - due_date: YYYY-MM-DD
   - source_file: Path to source file
   - source_type: email | document | meeting | manual
   - tags: List of tags
   - dependencies: List of dependent todos
   - related_files: Links to related files
   
   ## Allowed Operations
   - Create: Allowed
   - Update: Allowed (must update execution log)
   - Delete: Not allowed (archive to completed/ instead)
   - Move: Only between active/ and completed/
   

3. Create README.md files with initial content and indexes

Phase 8: Report

Todo tracking initialized successfully!

Configuration:
- Settings file: [project_root]/.claude/todo-settings-local.json
- Todos directory: [todos_directory]
- Tracked directories: [list or "all"]
- Detection patterns: [count] patterns configured
- Confirmation required: [yes/no]
- Default priority: [priority]

The system will now automatically detect potential todos in your conversations.
When actionable items are detected, you will be asked to confirm before creating todos.

Available commands:
- /todo-add    - Manually add a new todo
- /todo-list   - View all active todos
- /todo-update - Update a todo
- /todo-complete - Mark a todo as complete

Quick Setup

For users who want fast setup with defaults:

/todo-init --quick [todos_directory]

This will:

1. Create settings with all defaults
2. Set the specified todos directory
3. Enable tracking for all directories
4. Use default patterns
5. Require confirmation for todo creation

Update Mode

When updating existing configuration:

{
  "question": "What would you like to update?",
  "header": "Update",
  "options": [
    {"label": "Enable/Disable", "description": "Turn todo tracking on or off"},
    {"label": "Change directory", "description": "Update todos storage location"},
    {"label": "Update patterns", "description": "Add or remove detection patterns"},
    {"label": "Change behavior", "description": "Update confirmation and priority settings"}
  ],
  "multiSelect": true
}

Error Handling

Permission Denied

Cannot create settings file: Permission denied

Please ensure you have write access to:
[project_root]/.claude/

Or run the command from a directory where you have write permissions.

Invalid Todos Directory

Invalid todos directory: [path]

The specified path does not exist or is not accessible.
Would you like to:
1. Create the directory
2. Specify a different path

Settings Validation Failed

Settings validation failed:

- todos_directory: Path does not exist
- patterns.request: Must be an array

Please fix these issues and try again.

Configuration Schema Reference

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["enabled"],
  "properties": {
    "enabled": {
      "type": "boolean",
      "description": "Enable or disable todo tracking"
    },
    "todos_directory": {
      "type": "string",
      "description": "Path to the Todos directory"
    },
    "tracked_directories": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Directories to track for todos (empty = all)"
    },
    "patterns": {
      "type": "object",
      "properties": {
        "request": {"type": "array", "items": {"type": "string"}},
        "deadline": {"type": "array", "items": {"type": "string"}},
        "action": {"type": "array", "items": {"type": "string"}}
      }
    },
    "default_priority": {
      "type": "string",
      "enum": ["high", "medium", "low"]
    },
    "auto_due_date_detection": {
      "type": "boolean"
    },
    "confirmation_required": {
      "type": "boolean"
    }
  }
}