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