This repository provides Markdown-based workflows for managing software development tasks collaboratively with AI agents, targeting engineers who want to maintain control over their codebase. It automates the process of breaking down vague ideas into actionable implementation steps, ensuring controlled scope and efficient context usage, with options for full task isolation via Git worktrees or a simpler single-branch approach.

How It Works

The core of the project is a state machine implemented in Markdown, guiding the user and AI agent through distinct phases: INIT, SELECT, REFINE, IMPLEMENT, and COMMIT. This approach leverages pure Markdown, Git, and shell commands, offering zero dependencies, high transparency, and ease of modification without vendor lock-in. The workflows manage task isolation, context preservation, and traceable development history.

Quick Start & Requirements

• Installation: Place a chosen workflow file (todo-worktree.md or todo-branch.md) in ~/.claude/commands or project/.claude/commands.
• Prerequisites: Git, a compatible AI agent (e.g., Claude), and shell access.
• Usage: Execute claude --dangerously-skip-permissions "/todo" (for worktree) or claude --dangerously-skip-permissions "/todo-branch" (for single-branch) in the project root. Omitting the flag requires manual approval for shell commands.
• Links: Workflows are detailed in todo-worktree.md and todo-branch.md.

Highlighted Details

• Zero dependencies: pure Markdown, Git, and shell commands.
• Two workflow options: todo-worktree.md for isolation, todo-branch.md for simplicity.
• State machine pattern for guided agent-user collaboration.
• Task isolation via Git worktrees or current branch staging.
• Preserves agent analysis in analysis.md.

Maintenance & Community

No specific contributors, sponsorships, or community links (Discord/Slack) are mentioned in the README. The project appears to be a personal or small-scale initiative.

Licensing & Compatibility

The README does not explicitly state a license. Given the nature of the content (Markdown prompts), it's likely intended for personal use or under a permissive license, but this requires verification. Compatibility for commercial use or closed-source linking is not specified.

Limitations & Caveats

LLMs can be unreliable and may deviate from instructions with complex tasks. The todo-worktree.md workflow's orphaned task detection is limited to a single machine. The todo-branch.md workflow operates on the current branch with uncommitted changes, requiring a clean working tree before starting. Simultaneous editing of todos/todos.md can lead to race conditions.