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:

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

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

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

Ensure .claude/ directory exists:

mkdir -p [project_root]/.claude

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] }

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

Phase 7: Create Todos Directory Structure (if needed)

If creating new Todos directory:

Create directory structure:

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

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/

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:

• 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:

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