todo-init

Set up the agent todos configuration for this project. Creates .agent-todos.local.json in the project root and initializes the todo store directory.

The default todo store is docs/agent-todos/ inside the project. Users with Obsidian can point todosRoot to a vault path instead.

Workflow

Step 1: Check for Existing Config

Read .agent-todos.local.json in the project root, if it exists.

If a config file is found, show the current settings and ask the user whether to reconfigure or abort.

Upgrade path — missing projectName : If the existing config is kept (user chooses not to reconfigure) but projectName is absent, ask: "Would you like to add a projectName to your config? This value is included in the projects: frontmatter of every new todo (e.g. [[my-project]] )." If yes, ask for the value and write it to the config file.

Upgrade path — missing CLAUDE.md section: If the existing config is kept but no ## Agent Todos section exists in CLAUDE.md , proceed to Step 6 to add it.

Step 2: Determine Todo Store Path

Ask the user where to store todos:

• Default — docs/agent-todos/ inside the project (works everywhere, no external tools needed)

• Custom path — any absolute path, e.g. a path inside an Obsidian vault

Use AskUserQuestion to let the user choose.

Step 2b: Determine Project Name (optional)

After the todo store path is set, ask the user whether they want to associate todos with a project name:

Would you like to add a projectName to tag every new todo? This is included in the projects: frontmatter field (e.g. [[my-project]] for Obsidian task-notes integration). Leave blank to skip.

This field is optional. If the user provides a value, include it in the config.

Step 3: Write Config File

Create .agent-todos.local.json in the project root:

{ "todosRoot": "<todos_root>" }

If the user provided a projectName , include it:

{ "todosRoot": "<todos_root>", "projectName": "<project_name>" }

All paths should use ~ for the home directory when applicable.

Step 4: Create Todo Store Directory

Create the todosRoot directory if it does not already exist:

mkdir -p "<todos_root>"

Step 5: Ask for Initial Categories

Ask the user which category subdirectories to create (multi-select). Suggest common ones:

• misc/ — Miscellaneous tasks

• data/ — Data-related tasks

• content/ — Content creation and editing tasks

Create the selected subdirectories inside todosRoot .

Step 6: Add Agent Todos Section to CLAUDE.md

Check whether a CLAUDE.md file exists in the project root and whether it already contains an ## Agent Todos section:

grep -q "## Agent Todos" CLAUDE.md 2>/dev/null && echo "exists" || echo "missing"

If the section is missing, append the following reference block to CLAUDE.md . Replace <todosRoot> with the actual configured path:

Agent Todos

This project uses the agent-todos plugin to manage tasks as structured Markdown files.

IMPORTANT: Always read .agent-todos.local.json before any todo operation. It defines todosRoot — the actual directory where todo files are stored. Do not fall back to docs/agent-todos/ when this file is present.

Current todo store: <todosRoot>

Skills:

• /todo-creation [category] [title] — create a new todo file
• /todo-processing [category/number] — pick up and work on a todo
• /todo-gh-issue-import [category] — import GitHub issues as todos
• /todo-moving — renumber or move todos between categories

If CLAUDE.md does not exist, create it with only this section.

If the section already exists, skip this step.

Notes

• .agent-todos.local.json is project-specific and should be added to .gitignore when todosRoot points outside the project

• If todosRoot is inside the project (e.g. docs/agent-todos ), it can be checked in

• All todo skills (/todo-creation , /todo-processing , etc.) read this config automatically

• To use a different store later, re-run /todo-init or edit .agent-todos.local.json directly

• Without .agent-todos.local.json , all skills fall back to docs/agent-todos/ in the project root