Deliberate Development Bundle¶

Overview¶

The Deliberate Development bundle brings a decomposition-first philosophy to software development. Where other bundles focus on execution speed, this one insists on understanding first. Every feature, bug fix, and refactor begins with structured planning before a single line of code is written.

This bundle complements the Foundation bundle and the Superpowers workflow. While Foundation provides general-purpose development agents and Superpowers provides a TDD-driven implementation cycle, Deliberate Development adds rigorous planning discipline and anti-pattern detection.

Key Characteristics:

• Planning before action: 4-5 planning turns before any implementation begins
• Decomposition-first: Break problems into smaller pieces, explore alternatives, find generalization opportunities
• Investigation over assumption: Debug by gathering evidence, not by guessing
• Structural prevention: Catch problems through design, not runtime checks

Agents Included¶

deliberate-planner¶

The Deliberate Planner decomposes problems before anyone writes code. It spends 4-5 turns exploring the problem space, considering alternatives, and identifying generalization opportunities before producing an implementation plan.

Responsibilities: - Breaking down features into discrete, implementable pieces - Exploring alternative approaches before committing to one - Identifying opportunities to generalize solutions - Producing specifications that the implementer can execute

Best for: Starting new features, redesigning existing systems, exploring unfamiliar problem domains.

You: "Add a plan mode that restricts tool usage"

deliberate-planner:
  Turn 1: What exactly does "restricts" mean? Which tools? What triggers it?
  Turn 2: Three possible approaches -- mode flag, tool policy, or hybrid
  Turn 3: Generalization: this is really a "tool policy" system, modes are one use
  Turn 4: Spec: ToolPolicy protocol, ModeManager, policy-per-mode config
  Turn 5: Implementation plan with file paths, interfaces, test criteria

The planner doesn't write code. It produces a specification that the implementer picks up.

deliberate-implementer¶

The Deliberate Implementer builds from specifications. Give it a clear spec with file paths, interfaces, and success criteria, and it executes. Give it a vague request, and it stops to ask for clarification.

Responsibilities: - Implementing features from complete specifications - Following specified interfaces and patterns exactly - Validating implementation against success criteria - Refusing to proceed when specifications are incomplete

Best for: Executing plans from the deliberate-planner, implementing well-defined features, building from architectural specs.

Requires before starting: - Clear file paths to create or modify - Complete function signatures with types - A pattern reference or explicit design freedom - Defined success criteria

You: "Implement the CacheService from specs/cache-spec.md"

deliberate-implementer: Reads spec, implements CacheService with all
specified methods, validates against the success criteria in the spec.

If you hand it "add caching to improve performance" without a spec, it will tell you to plan first.

deliberate-debugger¶

The Deliberate Debugger follows a 6-phase investigation workflow. Instead of jumping to fixes, it gathers evidence, forms hypotheses, and tests them systematically.

The 6 Phases:

1. Reconnaissance -- Gather context about the bug without changing anything
2. Hypothesis formation -- Propose possible causes based on evidence
3. Evidence collection -- Trace code paths, check logs, compare working vs broken states
4. Hypothesis testing -- Verify or eliminate each hypothesis with targeted tests
5. Root cause identification -- Confirm the actual cause, not just a symptom
6. Fix and verify -- Apply the minimal fix, verify it resolves the issue

Best for: Intermittent bugs, complex multi-system failures, issues where the obvious fix didn't work.

You: "The synthesis pipeline throws a KeyError somewhere"

deliberate-debugger:
  Phase 1: Maps the pipeline, identifies all dict access points
  Phase 2: Hypothesizes three possible missing keys
  Phase 3: Traces data flow, finds the dict is populated conditionally
  Phase 4: Reproduces with specific input that skips population
  Phase 5: Root cause: optional enrichment step skipped, downstream assumes keys exist
  Phase 6: Adds key presence check at enrichment boundary, verifies fix

deliberate-reviewer¶

The Deliberate Reviewer catches anti-patterns that slip past standard code review. It focuses on structural issues rather than style preferences.

Anti-patterns it catches:

• Runtime detection over structural prevention: Code that checks for problems at runtime when the design could prevent them at compile time or through type constraints
• Arbitrary thresholds: Magic numbers like if retries > 3 without justification for the specific value
• Vague boundaries: Module interfaces that accept Any or dict when specific types would be clearer
• Missing specification gates: Implementation that started without a clear spec, leading to scope drift

Best for: PR review, architectural decision validation, pre-merge quality checks.

You: "Review this error handling approach"

deliberate-reviewer: "This catches TypeError at runtime and retries.
That's detection, not prevention. The real fix is constraining the
input type so TypeError can't occur. Move validation to the boundary."

Modes¶

The Deliberate Development bundle includes two modes that change how Amplifier operates during a session.

plan Mode¶

Plan mode enforces planning discipline by blocking write operations:

• Write tools are BLOCKED: No file creation, no edits, no bash commands that modify state
• Read and search tools are ALLOWED: Read files, grep, glob, LSP navigation all work
• Self-check before every tool call: The agent verifies it's not about to violate the read-only constraint
• 4-5 turn planning rule: The agent spends multiple turns decomposing before producing a plan

You: "Enter plan mode"

Amplifier: Plan mode active. I can read, search, and analyze but
won't modify any files. What should we plan?

You: "We need to add webhook support to the notification system"

Amplifier: Let me explore the current notification system first...
[reads files, traces call paths, maps dependencies -- 4-5 turns of analysis]
...here's the implementation plan with file paths and interfaces.

Exit plan mode when you're ready to implement.

research Mode¶

Research mode optimizes for deep investigation over quick answers:

• Spend tokens, go deep: Encourages thorough exploration rather than surface-level responses
• Multi-agent brainstorm FIRST: Consult multiple perspectives before diving into research
• Research SECOND: Gather evidence after forming initial hypotheses
• Iterative deepening: Start broad, then drill into the most promising areas
• Organized output: Produces one document per topic rather than a single sprawling response

You: "Enter research mode"

Amplifier: Research mode active. I'll go deep on topics, consulting
multiple perspectives and organizing findings into structured docs.

You: "Research how other frameworks handle plugin versioning"

Amplifier: [Brainstorms approaches, researches each one in depth,
produces organized findings document with comparisons]

Workflow Patterns¶

The Full Deliberate Cycle¶

The typical workflow chains the agents in sequence:

1. deliberate-planner    --> Decomposes problem, produces spec
2. deliberate-implementer --> Builds from spec
3. deliberate-reviewer    --> Reviews implementation for anti-patterns
4. deliberate-debugger    --> Investigates any issues found

Planning Then Handing Off¶

You don't have to use the full cycle. A common pattern is planning with this bundle and implementing with Foundation agents:

1. deliberate-planner    --> Produces spec
2. foundation:modular-builder --> Implements from spec
3. foundation:zen-architect   --> Reviews

Debug-Only Usage¶

For existing bugs, jump straight to the debugger:

You: "The API returns 500 on the /users endpoint after the last deploy"

deliberate-debugger: [Runs the 6-phase investigation, identifies root
cause as a missing migration, applies fix]

When to Use¶

Good Use Cases¶

• New features with unclear scope: When you're not sure exactly what to build, the planner helps you figure it out
• Bugs that resist simple fixes: When the obvious solution didn't work, the debugger's systematic approach finds the real cause
• Architectural decisions: When you need to choose between approaches, the planner explores alternatives
• Pre-merge review: When you want to catch structural anti-patterns before code ships
• Complex refactors: When touching many files, plan first to avoid mid-refactor confusion

When Other Bundles Fit Better¶

• Clear, well-defined tasks: If you already have a spec, go straight to Foundation's modular-builder
• Quick bug fixes: If the cause is obvious, Foundation's bug-hunter is faster
• Design work: Use Design Intelligence for UI/UX tasks
• Workflow automation: Use Recipes for repeatable multi-step processes

Try It Yourself¶

Plan a Feature¶

Enter plan mode. I need to add rate limiting to our API. We have
a FastAPI app with about 20 endpoints. Some should be rate-limited
per user, some per IP, and admin endpoints shouldn't be limited at all.

Watch how the planner decomposes this into configuration schema, middleware design, storage backend selection, and per-route policy.

Debug Systematically¶

My pytest test_integration.py::test_concurrent_writes is flaky.
It passes 90% of the time but occasionally fails with a deadlock.
Use the deliberate debugger to investigate.

The debugger will trace the locking order, identify the race condition, and propose a fix.

Review for Anti-Patterns¶

Review this retry logic for anti-patterns:

def fetch_with_retry(url, max_retries=3):
    for i in range(max_retries):
        try:
            return requests.get(url, timeout=5)
        except RequestException:
            if i == max_retries - 1:
                raise
            time.sleep(2 ** i)

The reviewer will identify the arbitrary threshold, magic timeout value, and suggest structural improvements.

Research a Design Decision¶

Enter research mode. I need to decide between SQLite, PostgreSQL,
and DuckDB for our analytics store. We have ~10M rows, mostly
append-only writes, with complex analytical queries run hourly.

Research mode will explore each option in depth and produce an organized comparison document.

Best Practices¶

1. Use plan mode for unfamiliar territory: When you don't fully understand the problem space, planning prevents expensive rework.

2. Let the planner finish: Resist the urge to jump to implementation after the second planning turn. The later turns often surface the best insights.

3. Feed complete specs to the implementer: The implementer works best with file paths, function signatures, and success criteria. Vague specs produce vague results.

4. Don't skip the reviewer: Anti-patterns are easiest to fix before merge. The reviewer catches issues that look fine in isolation but create problems at scale.

5. Use the debugger for repeat failures: If you've already tried the obvious fix and it didn't work, switch to the systematic 6-phase approach.

6. Combine with other bundles: Deliberate Development handles planning and review. Foundation handles execution. Use them together.

Related Resources¶

• Foundation Bundle - Core development agents for implementation
• Recipes Bundle - Declarative workflow orchestration
• Design Intelligence - UI/UX design specialists
• Bundles Guide - How bundles work together

Next Steps: - Learn about Foundation agents that implement your plans - Explore Recipes to automate the plan-implement-review cycle - See Custom Bundles to build your own agent teams