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

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

•

If found:

json

{
  "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
}

•
If not found: Proceed to Phase 2

Phase 2: Determine Todos Directory

Ask user where to store todo files:

json

{
  "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:

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

Create new logic:

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

Phase 3: Configure Tracking Options

json

{
  "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

json

{
  "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

json

{
  "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
}

json

{
  "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

•
Ensure .claude/ directory exists:
bash
```
mkdir -p [project_root]/.claude
```

•

Generate settings file:

json

{
  "$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]
}

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

Phase 7: Create Todos Directory Structure (if needed)

If creating new Todos directory:

•

Create directory structure:

code

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

•

Create RULE.md:

markdown

# 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/

•
Create README.md files with initial content and indexes

Phase 8: Report

code

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:

code

/todo-init --quick [todos_directory]

This will:

•Create settings with all defaults
•Set the specified todos directory
•Enable tracking for all directories
•Use default patterns
•Require confirmation for todo creation

Update Mode

When updating existing configuration:

json

{
  "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

code

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

code

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

code

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

json

{
  "$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"
    }
  }
}