Planning and execution workflows: plans, subagents, git worktrees, branch completion

version
1.0.0

Install

/plugin install workflow@dot-claude

Run it inside Claude Code after adding the marketplace with /plugin marketplace add pproenca/dot-claude-old.

Contents

Discovered from source

Skills 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:

  1. Check current git context:

    git branch --show-current
    git worktree list
    
  2. 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
    
  3. If "Set up worktree": Use workflow:git-worktrees skill first

  4. If "Continue on main": Proceed with warning logged

  5. If already in worktree or feature branch: Proceed normally

Step 1: Load and Review Plan

  1. Read plan file
  2. Review critically - identify any questions or concerns about the plan
  3. If concerns: Raise them with your human partner before starting
  4. 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)
  1. Mark as in_progress
  2. Execute the change directly (no TDD - nothing to test)
  3. Verify with git diff that change is correct
  4. Mark as completed
  5. 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)
  1. Mark as in_progress
  2. If modifying production code: Use core:tdd skill (write test first)
  3. If config/docs only: Skip TDD
  4. Run verifications as specified
  5. Mark as completed
  6. Lightweight review: Check git diff, no subagent needed
MODERATE Tasks (features, bug fixes)
  1. Mark as in_progress
  2. Use core:tdd skill - Write failing test FIRST, then implement
  3. Follow each step exactly
  4. Run verifications as specified
  5. Use core:verification skill - Verify tests pass
  6. Mark as completed
  7. Dispatch code-reviewer (Sonnet model)
COMPLEX Tasks (multi-file, architectural)
  1. Mark as in_progress
  2. Use core:tdd skill - Write failing test FIRST, then implement
  3. Follow each step exactly
  4. Run verifications as specified
  5. Use core:verification skill - Verify tests pass
  6. Mark as completed
  7. 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:

  1. Address issues before proceeding
  2. Re-run verification after fixes
  3. 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:

  1. Mark the "Complete development (finish-branch)" todo as in_progress
  2. Announce: "I'm using the finish-branch skill to complete this work."
  3. REQUIRED: Use Skill("workflow:finish-branch")
  4. Follow that skill to verify tests, present options, execute choice
  5. 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

OptionMergePushKeep WorktreeCleanup 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 -d fails with "used by worktree"
  • Fix: Always remove worktree FIRST, then delete branch

Removing worktree while standing in it

  • Problem: git worktree remove fails with "Permission denied"
  • Fix: cd to 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 prune to 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":

  1. Add appropriate line to .gitignore
  2. Commit the change
  3. 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

SituationAction
.worktrees/ existsUse it (verify .gitignore)
worktrees/ existsUse it (verify .gitignore)
Both existUse .worktrees/
Neither existsCheck CLAUDE.md → Ask user
Directory not in .gitignoreAdd it immediately + commit
Tests fail during baselineReport failures + ask
No package.json/Cargo.tomlSkip 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:

  1. Focused - One clear problem domain
  2. Self-contained - All context needed to understand the problem
  3. 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

  1. Parallelization - Multiple investigations happen simultaneously
  2. Focus - Each agent has narrow scope, less context to track
  3. Independence - Agents don't interfere with each other
  4. Speed - 3 problems solved in time of 1

Verification

After agents return:

  1. Review each summary - Understand what changed
  2. Check for conflicts - Did agents edit same code?
  3. Run full suite - Verify all fixes work together
  4. 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 Task tool 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

ComplexityTarget Tool UsesTarget Tokens
TRIVIAL2-3<3k
SIMPLE4-6<8k
MODERATE8-15<20k
COMPLEXNo hard limitReasonable

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:

  1. Check current git context:

    git branch --show-current
    git worktree list
    
  2. 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
    
  3. If "Set up worktree": Use workflow:git-worktrees skill first

  4. If "Continue on main": Proceed with warning logged

  5. 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:

  1. Read task from plan
  2. Execute the change (Bash, Edit, Write as needed)
  3. Verify with git diff
  4. Commit
  5. 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:

  1. Mark the "Complete development (finish-branch)" todo as in_progress
  2. Announce: "I'm using the finish-branch skill to complete this work."
  3. REQUIRED: Use Skill("workflow:finish-branch")
  4. Follow that skill to verify tests, present options, execute choice
  5. 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:

  1. Resolve library ID:

    mcp__context7__resolve-library-id(libraryName: "library-name")
    

    Select the most relevant match based on description and documentation coverage.

  2. 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.

  3. 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.toml or setup.py → Python project
  • fastapi in dependencies → FastAPI project
  • django in dependencies → Django project
  • asyncio imports or async def → Async code
  • .python-version or uv.lock → Uses uv package manager

When Python detected:

  1. Use Skill tool to load python:python-testing
  2. Use Skill tool to load python:python-project
  3. Use patterns from loaded skills in plan tasks
  4. Use uv run prefix for all Python commands

When async/performance code detected:

  • Use Skill tool to load python:python-performance

When FastAPI/Django detected:

  • Dispatch python:python-expert agent 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.

ComplexityExamplesTDD?Code Review?
TRIVIALDelete file, rename, typo fix, config updateNoParent verifies git diff
SIMPLESmall refactor, single-file change, add commentIf code changesHaiku (optional)
MODERATEFeature implementation, bug fix with testsYesSonnet
COMPLEXMulti-file feature, architectural changeYesOpus

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:

SkillWhen to ReferenceWhat It Provides
python:python-testingAll Python test codeFixtures, mocking, parameterized tests, markers
python:python-projectPython commands, dependencies, packaginguv run, uv add, pyproject.toml, publishing
python:python-performanceAsync or performance codeasyncio, 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

More from pproenca/dot-claude-old

All 12