
workflow
Planning and execution workflows: plans, subagents, git worktrees, branch completion
- version
- 1.0.0
Install
/plugin install workflow@dot-claudeRun it inside Claude Code after adding the marketplace with /plugin marketplace add pproenca/dot-claude-old.
Contents
Discovered from sourceSkills 6
Executing Plans
Overview
Load plan, review critically, execute tasks in batches, report for review between batches.
Core principle: Batch execution with checkpoints for architect review.
Announce at start: "I'm using the executing-plans skill to implement this plan."
The Process
Step 0: Verify Isolation Context
Before loading plan:
-
Check current git context:
git branch --show-current git worktree list -
If on main/master without worktree: Use AskUserQuestion:
Question: "You're on the main branch. Plans should execute in isolated worktrees to protect main." Header: "Isolation" Options: - "Set up worktree": Create isolated workspace first (recommended) - "Continue on main": I understand the risk, proceed anyway -
If "Set up worktree": Use workflow:git-worktrees skill first
-
If "Continue on main": Proceed with warning logged
-
If already in worktree or feature branch: Proceed normally
Step 1: Load and Review Plan
- Read plan file
- Review critically - identify any questions or concerns about the plan
- If concerns: Raise them with your human partner before starting
- If no concerns: Create TodoWrite with:
- All tasks from the plan
- MANDATORY FINAL TODO: "Complete development (finish-branch)" - this ensures finish-branch is invoked after all tasks complete
Step 2: Execute Batch
Default: First 3 tasks
For each task, check its Complexity tag and execute accordingly:
TRIVIAL Tasks (delete, rename, typo, config)
- Mark as in_progress
- Execute the change directly (no TDD - nothing to test)
- Verify with
git diffthat change is correct - Mark as completed
- Skip code review - parent agent verifies git diff directly
Rationale: TDD/review overhead exceeds task value for trivial changes.
SIMPLE Tasks (small refactor, single-file)
- Mark as in_progress
- If modifying production code: Use core:tdd skill (write test first)
- If config/docs only: Skip TDD
- Run verifications as specified
- Mark as completed
- Lightweight review: Check git diff, no subagent needed
MODERATE Tasks (features, bug fixes)
- Mark as in_progress
- Use core:tdd skill - Write failing test FIRST, then implement
- Follow each step exactly
- Run verifications as specified
- Use core:verification skill - Verify tests pass
- Mark as completed
- Dispatch code-reviewer (Sonnet model)
COMPLEX Tasks (multi-file, architectural)
- Mark as in_progress
- Use core:tdd skill - Write failing test FIRST, then implement
- Follow each step exactly
- Run verifications as specified
- Use core:verification skill - Verify tests pass
- Mark as completed
- Dispatch code-reviewer (Opus model for thorough review)
IMPORTANT: Match execution overhead to task complexity. TRIVIAL tasks should complete in 2-3 tool uses, not 11.
Step 3: Code Review After Batch
Review strategy based on batch complexity:
Batches with TRIVIAL/SIMPLE tasks only
- Parent agent reviews git diff directly
- Verify changes match plan requirements
- No subagent dispatch needed
git diff --stat [BASE_SHA]..[HEAD_SHA]
git diff [BASE_SHA]..[HEAD_SHA]
Check: Does the diff match what was requested? Any unintended changes?
Batches with MODERATE/COMPLEX tasks
Dispatch code-reviewer subagent:
Use template at plugins/methodology/review/templates/code-reviewer-dispatch.md.
Task tool (review:code-reviewer):
description: "Review Batch [N] implementation"
prompt: |
Review the implementation against requirements.
## Context
- **What Was Implemented:** [Summary of tasks completed in this batch]
- **Requirements/Plan:** Tasks [N-M] from [plan-file]
- **Description:** Batch [N] - [brief summary of work]
## Git Range
- **Base:** [commit before batch started]
- **Head:** [current commit after batch]
First run: git diff --stat [BASE_SHA]..[HEAD_SHA]
Then review against plugins/methodology/review/references/code-review-standards.md
Code reviewer returns: Strengths, Issues (Critical/Important/Minor), Assessment
Mixed batches
Review at the level of the most complex task in the batch.
If Critical or Important issues found:
- Address issues before proceeding
- Re-run verification after fixes
- Do NOT proceed to user feedback until resolved
If only Minor issues:
- Note for later
- Proceed to Step 4
Step 4: Report and Request Feedback
After code review passes:
- Show what was implemented
- Show verification output
- Show code review summary (issues found and resolved)
- Use the AskUserQuestion tool (do NOT output as plain text):
Question: "Batch [N] complete. How should I proceed?" Header: "Next step" Options:
- Continue: Proceed to next batch
- Review changes: Show diffs or re-explain what was done
- Make adjustments: Apply corrections before continuing multiSelect: false
Wait for user response before proceeding.
Step 5: Continue
Based on feedback:
- Apply changes if needed
- Execute next batch
- Repeat until complete
Step 6: Complete Development
After all plan tasks complete and verified:
- Mark the "Complete development (finish-branch)" todo as in_progress
- Announce: "I'm using the finish-branch skill to complete this work."
- REQUIRED: Use
Skill("workflow:finish-branch") - Follow that skill to verify tests, present options, execute choice
- Mark the "Complete development (finish-branch)" todo as completed
This step is NOT optional. The mandatory final todo ensures this step is visible throughout execution.
When to Stop and Ask for Help
STOP executing immediately when:
- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
- Plan has critical gaps preventing starting
- You don't understand an instruction
- Verification fails repeatedly
Ask for clarification rather than guessing.
When to Revisit Earlier Steps
Return to Review (Step 1) when:
- Partner updates the plan based on your feedback
- Fundamental approach needs rethinking
Don't force through blockers - stop and ask.
Remember
- Review plan critically first
- Follow plan steps exactly
- Don't skip verifications
- Reference skills when plan says to
- Between batches: use AskUserQuestion to get explicit feedback
- Stop when blocked, don't guess
Integration
Required skills for task execution:
- tdd - REQUIRED: Use core:tdd for each task (write test first)
- verification - REQUIRED: Use core:verification before marking tasks complete
Required workflow skills:
- git-worktrees - Use workflow:git-worktrees for isolation when on main/master (see Step 0)
- code-review - Use review:code-review after each batch (see Step 3)
- finish-branch - REQUIRED: Use workflow:finish-branch after all tasks (see Step 6)
Alternative workflow:
- subagent-dev - Use for same-session execution with fresh subagents per task
Finishing a Development Branch
Overview
Guide completion of development work by presenting clear options and handling chosen workflow.
Core principle: Verify tests → Present options → Execute choice → Clean up.
Announce at start: "I'm using the finish-branch skill to complete this work."
The Process
Step 1: Verify Tests
Before presenting options, verify tests pass:
# Run project's test suite
npm test / cargo test / pytest / go test ./...
If tests fail:
Tests failing (<N> failures). Must fix before completing:
[Show failures]
Cannot proceed with merge/PR until tests pass.
Stop. Don't proceed to Step 2.
If tests pass: Continue to Step 2.
Step 2: Determine Base Branch
# Try common base branches
git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
Or ask: "This branch split from main - is that correct?"
Step 3: Present Options
Present exactly these 4 options:
Implementation complete. What would you like to do?
1. Merge back to <base-branch> locally
2. Push and create a Pull Request
3. Keep the branch as-is (I'll handle it later)
4. Discard this work
Which option?
Don't add explanation - keep options concise.
Step 4: Execute Choice
Option 1: Merge Locally
# Switch to base branch
git checkout <base-branch>
# Pull latest
git pull
# Merge feature branch
git merge <feature-branch>
# Verify tests on merged result
<test command>
Then: Cleanup worktree and branch (Step 5)
Option 2: Push and Create PR
# Push branch
git push -u origin <feature-branch>
# Create PR
gh pr create --title "<title>" --body "$(cat <<'EOF'
## Summary
<2-3 bullets of what changed>
## Test Plan
- [ ] <verification steps>
EOF
)"
Then: Cleanup worktree (Step 5)
Option 3: Keep As-Is
Report: "Keeping branch . Worktree preserved at ."
Don't cleanup worktree.
Option 4: Discard
Confirm first:
This will permanently delete:
- Branch <name>
- All commits: <commit-list>
- Worktree at <path>
Type 'discard' to confirm.
Wait for exact confirmation.
If confirmed:
git checkout <base-branch>
git branch -D <feature-branch>
Then: Cleanup worktree (Step 5)
Step 5: Cleanup Worktree
For Options 1, 2, 4:
CRITICAL: Follow this exact sequence to avoid errors.
5a. Detect if in worktree
# Check if current directory is inside a worktree
worktree_path=$(git rev-parse --show-toplevel)
main_repo=$(git rev-parse --path-format=absolute --git-common-dir | sed 's|/\.git$||')
# If worktree_path != main_repo, we're in a worktree
5b. Leave worktree FIRST (mandatory)
Cannot remove a worktree while standing in it (causes "Permission denied").
# Change to main repository BEFORE attempting removal
cd "$main_repo"
5c. Remove worktree
# Now safe to remove worktree
git worktree remove "$worktree_path"
If worktree removal fails with "not a working tree":
# Directory may have been manually deleted - prune stale entries
git worktree prune
5d. Delete branch (after worktree is gone)
Cannot delete a branch while it's checked out in any worktree.
# For merged branches (Options 1, 2)
git branch -d <feature-branch>
# For discarded branches (Option 4)
git branch -D <feature-branch>
If branch deletion fails with "used by worktree":
# Worktree removal may not have completed - verify state
git worktree list
# If worktree still listed, force prune then retry
git worktree prune
git branch -d <feature-branch>
Complete Cleanup Script
For reference, the full safe cleanup sequence:
# 1. Capture paths while still in worktree
worktree_path=$(git rev-parse --show-toplevel)
main_repo=$(git rev-parse --path-format=absolute --git-common-dir | sed 's|/\.git$||')
branch_name=$(git branch --show-current)
# 2. Leave worktree (CRITICAL - must do before removal)
cd "$main_repo"
# 3. Remove worktree
git worktree remove "$worktree_path" || git worktree prune
# 4. Delete branch (only after worktree gone)
git branch -d "$branch_name" # or -D for force delete
For Option 3: Keep worktree - skip this entire step.
Quick Reference
| Option | Merge | Push | Keep Worktree | Cleanup Branch |
|---|---|---|---|---|
| 1. Merge locally | ✓ | - | - | ✓ |
| 2. Create PR | - | ✓ | ✓ | - |
| 3. Keep as-is | - | - | ✓ | - |
| 4. Discard | - | - | - | ✓ (force) |
Common Mistakes
Skipping test verification
- Problem: Merge broken code, create failing PR
- Fix: Always verify tests before offering options
Open-ended questions
- Problem: "What should I do next?" → ambiguous
- Fix: Present exactly 4 structured options
Automatic worktree cleanup
- Problem: Remove worktree when might need it (Option 2, 3)
- Fix: Only cleanup for Options 1 and 4
No confirmation for discard
- Problem: Accidentally delete work
- Fix: Require typed "discard" confirmation
Wrong cleanup sequence (deleting branch before worktree)
- Problem:
git branch -dfails with "used by worktree" - Fix: Always remove worktree FIRST, then delete branch
Removing worktree while standing in it
- Problem:
git worktree removefails with "Permission denied" - Fix:
cdto main repository BEFORE removing worktree
Inconsistent worktree state after partial failures
- Problem: "not a working tree" errors after failed removal attempts
- Fix: Run
git worktree pruneto clean up stale entries
Red Flags
Never:
- Proceed with failing tests
- Merge without verifying tests on result
- Delete work without confirmation
- Force-push without explicit request
- Delete branch while worktree exists (wrong order)
- Remove worktree while cwd is inside it
Always:
- Verify tests before offering options
- Present exactly 4 options
- Get typed confirmation for Option 4
- Clean up worktree for Options 1 & 4 only
- Leave worktree directory before removing it
- Follow cleanup sequence: cd out → remove worktree → delete branch
Integration
Called by:
- subagent-dev (Step 7) - After all tasks complete
- executing-plans (Step 5) - After all batches complete
Pairs with:
- workflow:git-worktrees - Cleans up worktree created by that skill
Using Git Worktrees
Overview
Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.
Core principle: Systematic directory selection + safety verification = reliable isolation.
Announce at start: "I'm using the git-worktrees skill to set up an isolated workspace."
Directory Selection Process
Follow this priority order:
1. Check Existing Directories
# Check in priority order
ls -d .worktrees 2>/dev/null # Preferred (hidden)
ls -d worktrees 2>/dev/null # Alternative
If found: Use that directory. If both exist, .worktrees wins.
2. Check CLAUDE.md
grep -i "worktree.*director" CLAUDE.md 2>/dev/null
If preference specified: Use it without asking.
3. Ask User
If no directory exists and no CLAUDE.md preference, use AskUserQuestion tool:
Question: "No worktree directory found. Where should I create worktrees?" Header: "Location" Options:
- .worktrees/ (project-local): Hidden directory within project, ignored by git
- Global (~/.config/superpowers/worktrees//): Outside project, shared across machines multiSelect: false
Safety Verification
For Project-Local Directories (.worktrees or worktrees)
MUST verify .gitignore before creating worktree:
# Check if directory pattern in .gitignore
grep -q "^\.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore
If NOT in .gitignore:
Per Jesse's rule "Fix broken things immediately":
- Add appropriate line to .gitignore
- Commit the change
- Proceed with worktree creation
Why critical: Prevents accidentally committing worktree contents to repository.
For Global Directory (~/.config/superpowers/worktrees)
No .gitignore verification needed - outside project entirely.
Creation Steps
1. Detect Project Name
project=$(basename "$(git rev-parse --show-toplevel)")
2. Create Worktree
# Determine full path
case $LOCATION in
.worktrees|worktrees)
path="$LOCATION/$BRANCH_NAME"
;;
~/.config/superpowers/worktrees/*)
path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
;;
esac
# Create worktree with new branch
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"
3. Run Project Setup
Auto-detect and run appropriate setup:
# Node.js
if [ -f package.json ]; then npm install; fi
# Rust
if [ -f Cargo.toml ]; then cargo build; fi
# Python (prefer uv)
if [ -f pyproject.toml ]; then uv sync; elif [ -f requirements.txt ]; then uv pip install -r requirements.txt; fi
# Go
if [ -f go.mod ]; then go mod download; fi
4. Verify Clean Baseline
Run tests to ensure worktree starts clean:
# Examples - use project-appropriate command
npm test
cargo test
pytest
go test ./...
If tests fail: Report failures, ask whether to proceed or investigate.
If tests pass: Report ready.
5. Report Location
Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>
Quick Reference
| Situation | Action |
|---|---|
.worktrees/ exists | Use it (verify .gitignore) |
worktrees/ exists | Use it (verify .gitignore) |
| Both exist | Use .worktrees/ |
| Neither exists | Check CLAUDE.md → Ask user |
| Directory not in .gitignore | Add it immediately + commit |
| Tests fail during baseline | Report failures + ask |
| No package.json/Cargo.toml | Skip dependency install |
Common Mistakes
Skipping .gitignore verification
- Problem: Worktree contents get tracked, pollute git status
- Fix: Always grep .gitignore before creating project-local worktree
Assuming directory location
- Problem: Creates inconsistency, violates project conventions
- Fix: Follow priority: existing > CLAUDE.md > ask
Proceeding with failing tests
- Problem: Can't distinguish new bugs from pre-existing issues
- Fix: Report failures, get explicit permission to proceed
Hardcoding setup commands
- Problem: Breaks on projects using different tools
- Fix: Auto-detect from project files (package.json, etc.)
Example Workflow
You: I'm using the git-worktrees skill to set up an isolated workspace.
[Check .worktrees/ - exists]
[Verify .gitignore - contains .worktrees/]
[Create worktree: git worktree add .worktrees/auth -b feature/auth]
[Run npm install]
[Run npm test - 47 passing]
Worktree ready at /Users/jesse/myproject/.worktrees/auth
Tests passing (47 tests, 0 failures)
Ready to implement auth feature
Red Flags
Never:
- Create worktree without .gitignore verification (project-local)
- Skip baseline test verification
- Proceed with failing tests without asking
- Assume directory location when ambiguous
- Skip CLAUDE.md check
Always:
- Follow directory priority: existing > CLAUDE.md > ask
- Verify .gitignore for project-local
- Auto-detect and run project setup
- Verify clean test baseline
Integration
Called by:
- brainstorming (Phase 4) - REQUIRED SUB-SKILL: Use core:brainstorming when design is approved and implementation follows
- Any skill needing isolated workspace
Pairs with:
- finish-branch - REQUIRED SUB-SKILL: Use workflow:finish-branch for cleanup after work complete
- executing-plans or subagent-dev - Work happens in this worktree
Dispatching Parallel Agents
Overview
When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
Core principle: Dispatch one agent per independent problem domain. Let them work concurrently.
When to Use
digraph when_to_use {
"Multiple failures?" [shape=diamond];
"Are they independent?" [shape=diamond];
"Single agent investigates all" [shape=box];
"One agent per problem domain" [shape=box];
"Can they work in parallel?" [shape=diamond];
"Sequential agents" [shape=box];
"Parallel dispatch" [shape=box];
"Multiple failures?" -> "Are they independent?" [label="yes"];
"Are they independent?" -> "Single agent investigates all" [label="no - related"];
"Are they independent?" -> "Can they work in parallel?" [label="yes"];
"Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
"Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
}
Use when:
- 3+ test files failing with different root causes
- Multiple subsystems broken independently
- Each problem can be understood without context from others
- No shared state between investigations
Don't use when:
- Failures are related (fix one might fix others)
- Need to understand full system state
- Agents would interfere with each other
The Pattern
1. Identify Independent Domains
Group failures by what's broken:
- File A tests: Tool approval flow
- File B tests: Batch completion behavior
- File C tests: Abort functionality
Each domain is independent - fixing tool approval doesn't affect abort tests.
2. Create Focused Agent Tasks
Each agent gets:
- Specific scope: One test file or subsystem
- Clear goal: Make these tests pass
- Constraints: Don't change other code
- Expected output: Summary of what you found and fixed
3. Dispatch in Parallel
// In Claude Code / AI environment
Task("Fix agent-tool-abort.test.ts failures")
Task("Fix batch-completion-behavior.test.ts failures")
Task("Fix tool-approval-race-conditions.test.ts failures")
// All three run concurrently
4. Review and Integrate
When agents return:
- Read each summary
- Verify fixes don't conflict
- Run full test suite
- Integrate all changes
Agent Prompt Structure
Good agent prompts are:
- Focused - One clear problem domain
- Self-contained - All context needed to understand the problem
- Specific about output - What should the agent return?
Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:
1. "should abort tool with partial output capture" - expects 'interrupted at' in message
2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
3. "should properly track pendingToolCount" - expects 3 results but gets 0
These are timing/race condition issues. Your task:
1. Read the test file and understand what each test verifies
2. Identify root cause - timing issues or actual bugs?
3. Fix by:
- Replacing arbitrary timeouts with event-based waiting
- Fixing bugs in abort implementation if found
- Adjusting test expectations if testing changed behavior
Do NOT just increase timeouts - find the real issue.
Return: Summary of what you found and what you fixed.
Common Mistakes
❌ Too broad: "Fix all the tests" - agent gets lost ✅ Specific: "Fix agent-tool-abort.test.ts" - focused scope
❌ No context: "Fix the race condition" - agent doesn't know where ✅ Context: Paste the error messages and test names
❌ No constraints: Agent might refactor everything ✅ Constraints: "Do NOT change production code" or "Fix tests only"
❌ Vague output: "Fix it" - you don't know what changed ✅ Specific: "Return summary of root cause and changes"
When NOT to Use
Related failures: Fixing one might fix others - investigate together first Need full context: Understanding requires seeing entire system Exploratory debugging: You don't know what's broken yet Shared state: Agents would interfere (editing same files, using same resources)
Real Example from Session
Scenario: 6 test failures across 3 files after major refactoring
Failures:
- agent-tool-abort.test.ts: 3 failures (timing issues)
- batch-completion-behavior.test.ts: 2 failures (tools not executing)
- tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)
Decision: Independent domains - abort logic separate from batch completion separate from race conditions
Dispatch:
Agent 1 → Fix agent-tool-abort.test.ts
Agent 2 → Fix batch-completion-behavior.test.ts
Agent 3 → Fix tool-approval-race-conditions.test.ts
Results:
- Agent 1: Replaced timeouts with event-based waiting
- Agent 2: Fixed event structure bug (threadId in wrong place)
- Agent 3: Added wait for async tool execution to complete
Integration: All fixes independent, no conflicts, full suite green
Time saved: 3 problems solved in parallel vs sequentially
Key Benefits
- Parallelization - Multiple investigations happen simultaneously
- Focus - Each agent has narrow scope, less context to track
- Independence - Agents don't interfere with each other
- Speed - 3 problems solved in time of 1
Verification
After agents return:
- Review each summary - Understand what changed
- Check for conflicts - Did agents edit same code?
- Run full suite - Verify all fixes work together
- Spot check - Agents can make systematic errors
Real-World Impact
From debugging session (2025-10-03):
- 6 failures across 3 files
- 3 agents dispatched in parallel
- All investigations completed concurrently
- All fixes integrated successfully
- Zero conflicts between agent changes
Integration
Tool usage:
- Uses
Tasktool to dispatch parallel subagents - Each Task call creates an independent agent with its own context
Pairs with:
- debug:systematic - Use for initial problem identification before parallel dispatch
- review:code-review - Review combined changes after all agents complete
Subagent-Driven Development
Execute plan by dispatching fresh subagent per task, with code review after each.
Core principle: Fresh subagent per task + review between tasks = high quality, fast iteration
Overview
vs. Executing Plans (parallel session):
- Same session (no context switch)
- Fresh subagent per task (no context pollution)
- Code review after each task (catch issues early)
- Faster iteration (no human-in-loop between tasks)
When to use:
- Staying in this session
- Tasks are mostly independent
- Want continuous progress with quality gates
When NOT to use:
- Need to review plan first (use executing-plans)
- Tasks are tightly coupled (manual execution better)
- Plan needs revision (brainstorm first)
Efficiency Targets
| Complexity | Target Tool Uses | Target Tokens |
|---|---|---|
| TRIVIAL | 2-3 | <3k |
| SIMPLE | 4-6 | <8k |
| MODERATE | 8-15 | <20k |
| COMPLEX | No hard limit | Reasonable |
Why this matters: A "Remove orphaned file" task should NOT use 11 tools and 27k tokens.
The Process
Step 0: Verify Isolation Context
Before loading plan:
-
Check current git context:
git branch --show-current git worktree list -
If on main/master without worktree: Use AskUserQuestion:
Question: "You're on the main branch. Subagents should work in an isolated worktree to protect main." Header: "Isolation" Options: - "Set up worktree": Create isolated workspace first (recommended) - "Continue on main": I understand the risk, proceed anyway -
If "Set up worktree": Use workflow:git-worktrees skill first
-
If "Continue on main": Proceed with warning logged
-
If already in worktree or feature branch: Proceed normally
1. Load Plan
Read plan file, create TodoWrite with:
- All tasks from the plan
- MANDATORY FINAL TODO: "Complete development (finish-branch)" - this ensures finish-branch is invoked after all tasks complete
2. Execute Task with Subagent
Check task Complexity tag before dispatching:
TRIVIAL Tasks
Do NOT dispatch a subagent. Execute directly as parent agent:
- Read task from plan
- Execute the change (Bash, Edit, Write as needed)
- Verify with
git diff - Commit
- Mark complete
Rationale: Subagent overhead (context loading, skill loading) exceeds task value.
SIMPLE Tasks
Dispatch lightweight subagent:
Task tool (general-purpose):
model: haiku
description: "Implement Task N: [task name]"
prompt: |
You are implementing Task N from [plan-file]. This is a SIMPLE task.
Work efficiently:
1. Read the task
2. If modifying code: write a simple test first
3. Make the change
4. Verify tests pass
5. Commit
6. Report back briefly
EFFICIENCY TARGET: 4-6 tool uses maximum.
Skip skill loading unless absolutely necessary.
ANTI-PATTERNS TO AVOID:
- Reading files not mentioned in task
- Using Glob/Grep to "verify" obvious facts
- Loading skills you don't need
- Re-reading the plan file multiple times
Work from: [directory]
MODERATE Tasks
Dispatch standard subagent:
Task tool (general-purpose):
model: sonnet
description: "Implement Task N: [task name]"
prompt: |
You are implementing Task N from [plan-file].
Read that task carefully. Your job is to:
1. Use core:tdd skill - write failing test FIRST, then implement
2. Implement exactly what the task specifies
3. Use core:verification skill - verify all tests pass
4. Commit your work
5. Report back
EFFICIENCY TARGET: 8-15 tool uses.
ANTI-PATTERNS TO AVOID:
- Reading files not mentioned in task
- Using Glob/Grep to "verify" obvious facts
- Loading skills you don't need
- Re-reading the plan file multiple times
Work from: [directory]
Report: What you implemented, test results, files changed
COMPLEX Tasks
Dispatch thorough subagent:
Task tool (general-purpose):
model: sonnet
description: "Implement Task N: [task name]"
prompt: |
You are implementing Task N from [plan-file]. This is a COMPLEX task.
Read that task carefully. Your job is to:
1. Use core:tdd skill - write failing test FIRST, then implement
2. Implement exactly what the task specifies
3. Use core:verification skill - verify all tests pass with actual output
4. Consider edge cases and error handling
5. Commit your work
6. Report back thoroughly
IMPORTANT:
- You MUST use core:tdd. Write the test first, see it fail.
- You MUST use core:verification before reporting completion.
Work from: [directory]
Report: What you implemented, what you tested, test results (with output),
files changed, any issues or concerns
Subagent reports back with summary of work.
Note: Subagents implement individual tasks only. The parent (you) handles finish-branch after ALL tasks complete.
3. Review Subagent's Work
Review strategy based on task complexity:
TRIVIAL tasks
No review needed - parent already verified git diff during execution.
SIMPLE tasks
Parent reviews subagent report + git diff. No code-reviewer dispatch.
git diff --stat [BASE_SHA]..[HEAD_SHA]
Check: Does the change match the task? Any unintended changes?
MODERATE tasks
Dispatch code-reviewer subagent:
Use template at plugins/methodology/review/templates/code-reviewer-dispatch.md.
Task tool (review:code-reviewer):
description: "Review Task N implementation"
prompt: |
Review the implementation against requirements.
## Context
- **What Was Implemented:** [from subagent's report]
- **Requirements/Plan:** Task N from [plan-file]
- **Description:** [task summary]
## Git Range
- **Base:** [commit before task]
- **Head:** [current commit]
First run: git diff --stat [BASE_SHA]..[HEAD_SHA]
Then review against plugins/methodology/review/references/code-review-standards.md
COMPLEX tasks
Dispatch thorough code-reviewer subagent with model: opus for critical analysis.
Code reviewer returns: Strengths, Issues (Critical/Important/Minor), Assessment
4. Apply Review Feedback
If issues found:
- Fix Critical issues immediately
- Fix Important issues before next task
- Note Minor issues
Dispatch follow-up subagent if needed:
"Fix issues from code review: [list issues]"
5. Mark Complete, Next Task
- Mark task as completed in TodoWrite
- Move to next task
- Repeat steps 2-5
6. Final Review
After all tasks complete, dispatch final code-reviewer:
- Reviews entire implementation
- Checks all plan requirements met
- Validates overall architecture
7. Complete Development
After final review passes:
- Mark the "Complete development (finish-branch)" todo as in_progress
- Announce: "I'm using the finish-branch skill to complete this work."
- REQUIRED: Use
Skill("workflow:finish-branch") - Follow that skill to verify tests, present options, execute choice
- Mark the "Complete development (finish-branch)" todo as completed
This step is NOT optional. The mandatory final todo ensures this step is visible throughout execution.
Example Workflow
You: I'm using Subagent-Driven Development to execute this plan.
[Check git context: on main branch, no worktree]
[AskUserQuestion: "You're on the main branch. Subagents should work in an isolated worktree to protect main."]
User: "Set up worktree"
[Use workflow:git-worktrees skill to create feature/my-feature worktree]
[Load plan, create TodoWrite with tasks + "Complete development (finish-branch)"]
Task 1: Hook installation script
[Dispatch implementation subagent]
Subagent: Implemented install-hook with tests, 5/5 passing
[Get git SHAs, dispatch code-reviewer]
Reviewer: Strengths: Good test coverage. Issues: None. Ready.
[Mark Task 1 complete]
Task 2: Recovery modes
[Dispatch implementation subagent]
Subagent: Added verify/repair, 8/8 tests passing
[Dispatch code-reviewer]
Reviewer: Strengths: Solid. Issues (Important): Missing progress reporting
[Dispatch fix subagent]
Fix subagent: Added progress every 100 conversations
[Verify fix, mark Task 2 complete]
...
[After all tasks]
[Dispatch final code-reviewer]
Final reviewer: All requirements met, ready to merge
[Mark "Complete development (finish-branch)" as in_progress]
You: I'm using the finish-branch skill to complete this work.
[Use Skill("workflow:finish-branch")]
[Present 4 options: merge, PR, keep, discard]
[User chooses option, execute it]
[Mark "Complete development (finish-branch)" as completed]
Done!
Advantages
vs. Manual execution:
- Subagents follow TDD naturally
- Fresh context per task (no confusion)
- Parallel-safe (subagents don't interfere)
vs. Executing Plans:
- Same session (no handoff)
- Continuous progress (no waiting)
- Review checkpoints automatic
Cost:
- More subagent invocations
- But catches issues early (cheaper than debugging later)
Red Flags
Never:
- Skip code review between tasks
- Proceed with unfixed Critical issues
- Dispatch multiple implementation subagents in parallel (conflicts)
- Implement without reading plan task
If subagent fails task:
- Dispatch fix subagent with specific instructions
- Don't try to fix manually (context pollution)
Integration
Required workflow skills:
- git-worktrees - Use workflow:git-worktrees for isolation when on main/master (see Step 0)
- writing-plans - Use workflow:writing-plans to create the plan that this skill executes
- code-review - Use review:code-review for review after each task (see Step 3)
- finish-branch - REQUIRED: Use workflow:finish-branch to complete development after all tasks (see Step 7)
Subagents must use:
- tdd - REQUIRED: Use core:tdd for TDD in each task
- verification - REQUIRED: Use core:verification before reporting completion
Alternative workflow:
- executing-plans - Use for parallel session instead of same-session execution
Templates:
- Code reviewer dispatch:
plugins/methodology/review/templates/code-reviewer-dispatch.md
Writing Plans
External Documentation Search (First Step)
Before researching the codebase, offer to search external documentation for the latest API references using Context7 MCP.
Step 0: Check Context7 Availability
First, check if Context7 MCP tools are available by looking for mcp__context7__ tools in your available tools list.
If Context7 is NOT available:
- Skip this entire section silently
- Proceed directly to Python Project Detection
- Do NOT ask the user about documentation search
If Context7 IS available:
- Continue with Step 1
Step 1: Ask About Documentation
Use AskUserQuestion:
Question: "Would you like me to search external documentation before planning?"
Header: "Docs"
multiSelect: false
Options:
- Yes, let me specify: I'll enter which libraries/frameworks to search
- Auto-detect from task: Analyze the task and search relevant libraries automatically
- No, skip: Proceed with planning without external docs
Step 2: Get Library Names
If user selected "Yes, let me specify":
- Ask follow-up: "Which libraries/frameworks should I search? (comma-separated, e.g., 'fastapi, pydantic, sqlalchemy')"
If user selected "Auto-detect from task":
- Extract technology keywords from the task description
- Present detected libraries for confirmation: "I detected these technologies: [list]. Should I search docs for these?"
If user selected "No, skip":
- Proceed directly to Python Project Detection
Step 3: Fetch Documentation
For each library the user confirms:
-
Resolve library ID:
mcp__context7__resolve-library-id(libraryName: "library-name")Select the most relevant match based on description and documentation coverage.
-
Fetch relevant docs:
mcp__context7__get-library-docs( context7CompatibleLibraryID: "/org/project", topic: "[relevant topic from task]", mode: "code" )Use
mode: "info"for architectural/conceptual questions. -
Use for context only: Keep documentation in working memory to inform plan tasks. Do NOT include raw docs in the plan document.
If tool call fails: Inform user that Context7 couldn't fetch docs for that library and continue with available information.
Step 4: Continue to Planning
After documentation is loaded (or skipped), proceed to Python Project Detection with documentation context available.
Overview
Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
Announce at start: "I'm using the writing-plans skill to create the implementation plan."
Python Project Detection
Before writing a plan, detect if this is a Python project and what framework it uses:
Detection signals:
pyproject.tomlorsetup.py→ Python projectfastapiin dependencies → FastAPI projectdjangoin dependencies → Django projectasyncioimports orasync def→ Async code.python-versionoruv.lock→ Uses uv package manager
When Python detected:
- Use Skill tool to load
python:python-testing - Use Skill tool to load
python:python-project - Use patterns from loaded skills in plan tasks
- Use
uv runprefix for all Python commands
When async/performance code detected:
- Use Skill tool to load
python:python-performance
When FastAPI/Django detected:
- Dispatch
python:python-expertagent for framework-specific patterns
Optional: Track Plan Writing Phases
For complex plans (5+ tasks), use TodoWrite to track progress:
- Research existing architecture
- Define high-level approach
- Break down into tasks
- Add code examples
- Generate diagrams (if applicable)
- Execution handoff
Context: This should be run in a dedicated worktree (created by brainstorming skill).
Save plans to: docs/plans/YYYY-MM-DD-<feature-name>.md
Bite-Sized Task Granularity
Each step is one action (2-5 minutes):
- "Write the failing test" - step
- "Run it to make sure it fails" - step
- "Implement the minimal code to make the test pass" - step
- "Run the tests and make sure they pass" - step
- "Commit" - step
Task Complexity Classification
Every task MUST include a complexity tag. This enables efficient execution.
| Complexity | Examples | TDD? | Code Review? |
|---|---|---|---|
| TRIVIAL | Delete file, rename, typo fix, config update | No | Parent verifies git diff |
| SIMPLE | Small refactor, single-file change, add comment | If code changes | Haiku (optional) |
| MODERATE | Feature implementation, bug fix with tests | Yes | Sonnet |
| COMPLEX | Multi-file feature, architectural change | Yes | Opus |
Classification heuristics:
- TRIVIAL: No new logic, no tests needed, <10 lines changed
- SIMPLE: Minor logic changes, one test file, <50 lines changed
- MODERATE: New functionality, multiple test cases, 50-200 lines
- COMPLEX: Multiple files, architectural decisions, >200 lines or high risk
Plan Document Header
Every plan MUST start with this header:
# [Feature Name] Implementation Plan
> **For Claude:** REQUIRED SUB-SKILL: Use workflow:executing-plans to implement this plan task-by-task.
**Goal:** [One sentence describing what this builds]
**Architecture:** [2-3 sentences about approach]
**Tech Stack:** [Key technologies/libraries]
---
Task Structure
### Task N: [Component Name]
**Complexity:** [TRIVIAL | SIMPLE | MODERATE | COMPLEX]
**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`
**Step 1: Write the failing test**
```python
def test_specific_behavior():
result = function(input)
assert result == expected
Step 2: Run test to verify it fails
Run: uv run pytest tests/path/test.py::test_name -v
Expected: FAIL with "function not defined"
Step 3: Write minimal implementation
def function(input):
return expected
Step 4: Run test to verify it passes
Run: uv run pytest tests/path/test.py::test_name -v
Expected: PASS
Step 5: Commit
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
## Remember
- Exact file paths always
- Complete code in plan (not "add validation")
- Exact commands with expected output
- Reference relevant skills with @ syntax
- DRY, YAGNI, TDD, frequent commits
## Python-Specific Patterns
When Python detected, load patterns from the python plugin instead of duplicating them here.
**Step 1: Load relevant skill**
Use Skill tool: python:python-testing
**Step 2: Copy patterns into plan tasks**
- Fixtures from skill → conftest.py setup task
- Parameterized tests from skill → test task examples
- Mocking patterns from skill → integration test examples
**For async/performance code detected:**
Use Skill tool: python:python-performance
**For FastAPI/Django detected:**
Task tool (python:python-expert): prompt: "Provide [framework] test patterns for [feature]"
## Diagram Generation Phase
Diagrams help Claude understand complex plans during execution. They're not just for humans - they serve as a reference that helps Claude maintain context during multi-step implementations.
### Step 1: Ask About Diagrams
Use AskUserQuestion:
Question: "Should I generate diagrams to help with plan execution?" Header: "Diagrams" multiSelect: false Options:
- Auto-detect: Let Claude decide what diagrams (if any) would help execution
- Task Dependencies: Show task order, parallelization, and blockers
- Architecture: Show system components, layers, and boundaries
- Sequence: Show API flows, service calls, and message passing
- State: Show status transitions and lifecycle stages
- Data Model: Show database schema and entity relationships
- No diagrams: Skip diagram generation entirely
**Default to "Auto-detect"** for complex plans. Only skip diagrams for trivial changes.
### Step 2: Generate Diagrams
If user selects "Auto-detect" or specific types, dispatch diagram-generator agent:
Task tool (doc:diagram-generator): description: "Generate Mermaid diagrams for plan" prompt: | See template at plugins/methodology/workflow/templates/diagram-prompt.md
MODE: [auto-detect | specific]
DIAGRAM_TYPES: [user's selection or "auto"]
PLAN_CONTENT: [full plan text]
**For auto-detect mode**, the agent will:
1. Analyze plan complexity and structure
2. Decide IF any diagrams would help Claude execute
3. Select the most useful diagram type(s)
4. Skip if plan is simple enough that diagrams add no value
### Step 3: Insert Diagrams
Add `## Diagrams` section to the plan document after the header block, before first task:
```markdown
# [Feature Name] Implementation Plan
> **For Claude:** REQUIRED SUB-SKILL...
**Goal:** ...
**Architecture:** ...
**Tech Stack:** ...
---
## Diagrams
[Insert agent output here]
---
### Task 1: ...
When to Skip the Question Entirely
Don't even ask about diagrams when:
- Plan has < 3 tasks with purely linear sequence
- Single-file changes (bug fix, refactor)
- Configuration-only changes
In these cases, just skip to execution handoff.
Execution Handoff
After saving the plan, use the AskUserQuestion tool (do NOT output as plain text):
Question: "Plan saved. How would you like to execute it?" Header: "Execute" Options:
- Subagent-Driven: Execute in this session with fresh subagent per task, code review between tasks
- Parallel Session: Open new session in worktree, batch execution with checkpoints
- Skip: I'll execute manually later multiSelect: false
If Subagent-Driven chosen:
- REQUIRED SUB-SKILL: Use Skill tool:
workflow:subagent-dev - Stay in this session
- Fresh subagent per task + code review between tasks
If Parallel Session chosen:
- Guide them to open new session in worktree
- REQUIRED SUB-SKILL: Use Skill tool:
workflow:executing-plans
If Skip chosen:
- Confirm the plan file location
- End the planning workflow
Workflow Integration
Python Development Skills
When writing Python plans, integrate these python plugin skills:
| Skill | When to Reference | What It Provides |
|---|---|---|
python:python-testing | All Python test code | Fixtures, mocking, parameterized tests, markers |
python:python-project | Python commands, dependencies, packaging | uv run, uv add, pyproject.toml, publishing |
python:python-performance | Async or performance code | asyncio, profiling, caching, optimization patterns |
Agent Dispatch
For complex Python plans, dispatch specialized agents:
Task tool (python:python-expert):
description: "Get FastAPI/Django patterns for [feature]"
prompt: "Analyze [feature requirements] and provide:
1. Framework-specific implementation pattern
2. Test fixtures and patterns
3. Common pitfalls to avoid"
Plan Header with Python Context
For Python projects, enhance the header:
# [Feature Name] Implementation Plan
> **For Claude:** REQUIRED SUB-SKILL: Use workflow:executing-plans to implement this plan task-by-task.
> **Python Skills:** Reference python:python-testing for tests, python:python-project for uv commands.
**Goal:** [One sentence describing what this builds]
**Architecture:** [2-3 sentences about approach]
**Tech Stack:** Python 3.12+, pytest, [framework if applicable]
**Commands:** All Python commands use `uv run` prefix
---
Commands 3
Use and follow the brainstorming skill exactly as written
Use the executing-plans skill exactly as written
Use the writing-plans skill exactly as written
Hooks 1
Sponsors
Details
- Marketplace
- pproenca/dot-claude-old
- Source
- plugins/methodology/workflow
- Category
- Community
- License
- MIT
- Keywords
- planning, execution, subagents, worktrees, workflow