Skip to content

Update and improve README.md #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Update and improve README.md #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
43550cc
Update command, improve instruction formatting, fix plural s-case
marckrenn Jul 28, 2025
bbf02ad
Update worktree command
marckrenn Jul 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,8 +55,9 @@ See also [prompt-as-code](https://mariozechner.at/posts/2025-06-02-prompts-are-c
1. Choose your workflow:
- `todo-worktree.md` for worktree-based isolation (recommended for most users)
- `todo-branch.md` for simpler single-branch workflow
2. Put your chosen file in `~/.claude/commands` (global) or `project/.claude/commands` (project)
- If you put it in your project, ensure you commit it before starting work on any todos
2. Choose a scope:
- Global use: Put the file in `~/.claude/commands`
- Project-specific use: Put the file in `.claude/commands` within your project directory. If you use this option, make sure to commit the file before starting work on any todos
3. In your project: `mkdir -p todos && echo "- add dark mode" > todos/todos.md`

### Other agents
Expand All @@ -71,7 +72,7 @@ The core idea is to load your chosen workflow as a system prompt or initial inst
In your project root directory:
```bash
# For worktree workflow
claude --dangerously-skip-permissions "/todo"
claude --dangerously-skip-permissions "/todo-worktree"

# For no-worktrees workflow
claude --dangerously-skip-permissions "/todo-branch"
Expand All @@ -92,7 +93,7 @@ The agent will guide you through the workflow.

## Caveats

**LLMS are unreliable**: LLMs occasionally ignore their programming when tasks get complex. Keep your tasks small and focused for best results.
**LLMs are unreliable**: LLMs occasionally ignore their programming when tasks get complex. Keep your tasks small and focused for best results.

**`todo-worktree.md`**: The worktree isolation lets you run agents in parallel, even across machines, but orphaned task detection only works if all agents run on the same machine.

Expand All @@ -102,4 +103,4 @@ The agent will guide you through the workflow.

**Concurrency**: Multiple humans editing `todos/todos.md` simultaneously creates perfect race conditions. In team projects, coordinate who's working on what so you don't end up with duplicate PRs for the same feature. Replacing `todos/todos.md` with one GitHub issue per vague todo is not a solution by the way. Think it through.

**Army of agents**: Distributed task management across machines would need a central server, which defeats the simplicity. Left as an exercise for distributed systems enthusiasts and their silicon assistants.
**Army of agents**: Distributed task management across machines would need a central server, which defeats the simplicity. Left as an exercise for distributed systems enthusiasts and their silicon assistants.
4 changes: 2 additions & 2 deletions todo-worktree.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@ Structured workflow to transform vague todos into implemented features using git
5. Update `task.md` with fully refined content and set `**Status**: InProgress`
6. Commit refined plan: `git add -A && git commit -m "[task-title]: Refined plan"`
7. Open editor at worktree: `[editor-command] /absolute/path/to/todos/worktrees/[timestamp]-[task-title-slug]/`
8. STOP → "Editor opened at worktree. Run `claude "/todo"` in worktree to start implementation"
8. STOP → "Editor opened at worktree. Run `claude "/todo-worktree"` in worktree to start implementation"

### IMPLEMENT
1. Execute the implementation plan checkbox by checkbox:
Expand Down Expand Up @@ -153,4 +153,4 @@ Structured workflow to transform vague todos into implemented features using git
6. Push branch to remote and create pull request using GitHub CLI
7. STOP → "PR created. Delete the worktree? (y/n)"
- If yes: `git -C "$(git rev-parse --show-toplevel)" worktree remove todos/worktrees/[timestamp]-[task-title-slug]`
- Note: If Claude was spawned in the worktree, the working directory will become invalid after removal
- Note: If Claude was spawned in the worktree, the working directory will become invalid after removal