Manages persistent file-based todos in .planning/todos/. Add descriptions as MD files with themes/priorities, list by theme, complete tasks via /todo subcommands; survives sessions.
From pbrnpx claudepluginhub sienklogic/plan-build-run --plugin pbrThis skill is limited to using the following tools:
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Guides agentic engineering workflows: eval-first loops, 15-min task decomposition, model routing (Haiku/Sonnet/Opus), AI code reviews, and cost tracking.
STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.
Before ANY tool calls, display this banner:
╔══════════════════════════════════════════════════════════════╗
║ PLAN-BUILD-RUN ► TODO ║
╚══════════════════════════════════════════════════════════════╝
Then proceed to Step 1.
Native Claude Code Tasks are session-scoped — they vanish when the conversation ends. Plan-Build-Run todos are individual .md files in .planning/todos/ that persist across sessions, context resets, and compactions.
Parse $ARGUMENTS to determine the subcommand:
add <description>.planning/todos/pending/ directory exists.planning/todos/pending/ and .planning/todos/done/ for the highest existing number, then increment by 1 (zero-padded to 3 digits)add-rate-limiting-login).planning/todos/pending/{NNN}-{slug}.md:---
title: "{description}"
status: pending
priority: P2
source: conversation
created: {YYYY-MM-DD}
theme: {inferred-theme}
---
## Goal
{description expanded into a clear goal statement}
## Scope
{any relevant context from the current conversation, or bullet points of what's in/out of scope}
## Acceptance Criteria
- [ ] {primary acceptance criterion derived from description}
Update STATE.md Pending Todos section
If the Write fails, display:
╔══════════════════════════════════════════════════════════════╗
║ ERROR ║
╚══════════════════════════════════════════════════════════════╝
Failed to write todo file.
**To fix:** Check that `.planning/todos/pending/` exists and is writable.
Confirm with branded output:
╔══════════════════════════════════════════════════════════════╗
║ PLAN-BUILD-RUN ► TODO ADDED ✓ ║
╚══════════════════════════════════════════════════════════════╝
**Todo {NNN}:** {description}
╔══════════════════════════════════════════════════════════════╗
║ ▶ NEXT UP ║
╚══════════════════════════════════════════════════════════════╝
**Work on it now** or see your task list
`/pbr:quick`
<sub>`/clear` first → fresh context window</sub>
**Also available:**
- `/pbr:todo list` — see all pending todos
- `/pbr:status` — see project status
list [theme].planning/todos/pending/Pending Todos:
| # | Title | Priority | Theme | Created |
|---|-------|----------|-------|---------|
| 074 | Status-line customization options | P2 | capability | 2026-02-10 |
| 075 | Add WebSearch/WebFetch/Context7 to researcher | P2 | capability | 2026-02-10 |
╔══════════════════════════════════════════════════════════════╗
║ ▶ NEXT UP ║
╚══════════════════════════════════════════════════════════════╝
**Pick a todo** — mark one done or start working
`/pbr:todo work <NNN>` — start working on a todo
`/pbr:todo done <NNN>` — mark a todo as complete
**Also available:**
- `/pbr:status` — see project status
done <NNN>.planning/todos/pending/{NNN}-*.md (match by number prefix)╔══════════════════════════════════════════════════════════════╗
║ ERROR ║
╚══════════════════════════════════════════════════════════════╝
Todo {NNN} not found in pending todos.
**To fix:** Run `/pbr:todo list` to see available numbers.
.planning/todos/done/ directory exists (create if needed)status: done and add completed: {YYYY-MM-DD}CRITICAL: Write to done/ FIRST, verify it exists, THEN delete from pending/. Do NOT delete pending before confirming done/ write succeeded.
.planning/todos/done/{NNN}-{slug}.md.planning/todos/done/{NNN}-{slug}.md exists and has content (use ls or Glob)
╔══════════════════════════════════════════════════════════════╗
║ ERROR ║
╚══════════════════════════════════════════════════════════════╝
Failed to write to done/. Pending file preserved.
**To fix:** Check that `.planning/todos/done/` exists and is writable.
Do NOT proceed to delete the pending file..planning/todos/pending/ (use rm via Bash)╔══════════════════════════════════════════════════════════════╗
║ PLAN-BUILD-RUN ► TODO COMPLETED ✓ ║
╚══════════════════════════════════════════════════════════════╝
**Todo {NNN}:** {title}
╔══════════════════════════════════════════════════════════════╗
║ ▶ NEXT UP ║
╚══════════════════════════════════════════════════════════════╝
**See remaining tasks**
`/pbr:todo list`
<sub>`/clear` first → fresh context window</sub>
**Also available:**
- `/pbr:continue` — execute next logical step
- `/pbr:status` — see project status
work <NNN>Find .planning/todos/pending/{NNN}-*.md (match by number prefix)
If not found, display the same error block as done — suggest /pbr:todo list
Read the todo file content (frontmatter + body)
Extract the title from frontmatter and the full body (Goal, Scope, Acceptance Criteria sections)
Assess complexity to choose the right skill. Evaluate the todo content against these criteria:
| Signal | Route to |
|---|---|
| Single file change, small fix, simple addition | /pbr:quick |
| Multiple acceptance criteria, multi-file scope, architectural decisions, needs research | /pbr:plan (requires an active phase) |
| Investigation needed, unclear root cause | /pbr:debug |
| Open-ended exploration, no clear deliverable | /pbr:explore |
If unsure, ask the user via AskUserQuestion:
Todo {NNN} could be handled as a quick task or may need full planning.
Which approach?
- Quick task (/pbr:quick) — single executor, atomic commit
- Full planning (/pbr:plan) — research, plan, build cycle
- Debug (/pbr:debug) — systematic investigation
- Explore (/pbr:explore) — open-ended investigation
╔══════════════════════════════════════════════════════════════╗
║ PLAN-BUILD-RUN ► WORKING ON TODO {NNN} ║
╚══════════════════════════════════════════════════════════════╝
**Todo {NNN}:** {title}
**Routing to:** /pbr:{chosen-skill}
{title}
Context from todo {NNN}:
{body content — Goal, Scope, Acceptance Criteria sections}
For /pbr:plan, if no phase exists for this work yet, suggest the user run /pbr:plan add first to create one, then re-run /pbr:todo work {NNN}.
╔══════════════════════════════════════════════════════════════╗
║ ▶ NEXT UP ║
╚══════════════════════════════════════════════════════════════╝
**Mark this todo as done if the work is complete**
`/pbr:todo done {NNN}`
Show a brief summary: count of pending todos, grouped by theme, plus usage hint.
After any todo operation, update the "Pending Todos" section of STATE.md with the current count and list.
Reference: skills/shared/commit-planning-docs.md for the standard commit pattern.
If planning.commit_docs: true in config, commit todo changes:
docs(planning): add todo {NNN}docs(planning): complete todo {NNN}