Plan Mode Mastery

// EXTEND the existing KafkaMessagesConsumer — don't recreate it!
// The consumer already caches rates in FxRatesCache.
// Add rate change detection BEFORE updating the cache.

@Component
@RequiredArgsConstructor
public class RateChangeDetector {

    private static final double SIGNIFICANT_CHANGE_THRESHOLD = 0.01; // 1%
    private final FxRatesCache fxRatesCache;
    private final KafkaTemplate<String, RateChangeAlert> alertTemplate;

    /**
     * Call this from the existing consumer BEFORE updating the cache.
     * Compare incoming rate with cached rate to detect significant movements.
     */
    public void detectAndAlert(CurrencyPair pair, FxExchangeRate newRate) {
        FxExchangeRate cachedRate = fxRatesCache.getRate(pair);
        if (cachedRate == null) return; // First rate for this pair, no comparison

        double changePercent = calculateChangePercent(cachedRate, newRate);
        if (Math.abs(changePercent) > SIGNIFICANT_CHANGE_THRESHOLD) {
            var alert = new RateChangeAlert(
                pair, cachedRate, newRate, changePercent, Instant.now()
            );
            log.info("Significant rate change detected",
                kv("pair", pair),
                kv("change", String.format("%.4f%%", changePercent * 100)));
            alertTemplate.send("rate-alerts", pair.toString(), alert);
        }
    }

    private double calculateChangePercent(FxExchangeRate old, FxExchangeRate current) {
        return (current.value().doubleValue() - old.value().doubleValue())
               / old.value().doubleValue();
    }
}

# .claude/agents/backend-dev.md
---
description: Backend development specialist
isolation: worktree
background: true
tools: Read, Write, Edit, Bash
# disallowedTools: WebSearch, WebFetch
# permissionMode: default | plan | bypassPermissions
# skills: code-review, refactor
# mcpServers: my-server
# hooks: onStart, onComplete
# memory: project | user | local
# maxTurns: 50
---

You are a backend development specialist.
Focus on implementing service layer code,
database queries, and API endpoints.

# .claude/agents/test-writer.md
---
description: Test writing specialist
isolation: worktree
background: true
tools: Read, Write, Edit, Bash
---

You are a test writing specialist.
Write comprehensive unit and integration tests
following the project's testing patterns.

# Supported frontmatter fields:
# description, isolation, background, tools,
# disallowedTools, permissionMode, skills,
# mcpServers, hooks, memory, maxTurns

Plan Mode Workflow
==================

1. Enter Plan Mode (Shift+Tab)
   - Claude explores but doesn't edit
   - Safe to investigate the codebase

2. Design Phase (still in Plan Mode)
   - Ask Claude to plan the implementation
   - Review and refine the plan
   - Approve or adjust

3. Exit Plan Mode (Shift+Tab)
   - Claude can now make edits
   - "Implement the plan"

4. Verify
   - "Run the tests"
   - "Show me what changed"

5. Safety Net: /rewind
   - If implementation doesn't match the plan,
     use /rewind to restore code AND conversation
     to a previous checkpoint
   - Checkpoints are created automatically
   - Pick any prior turn to roll back to

Subagents:
  Plan Mode spawns subagents for:
  - Parallel file exploration
  - Independent analysis tasks
  - Background test running

  Built-in subagent types:
  - Explore: uses Haiku, read-only tools only
  - Plan: inherits current model, read-only
  - General-purpose: all tools available

  Use Agent(agent_type) in agent defs to restrict
  which subagent types can be spawned.

  memory frontmatter field enables cross-session
  learning with scopes: user, project, local
  Agents remember patterns across conversations.

Managing Agents:
  /agents — interactive command for managing subagents
  claude agents — lists all configured agents
  (from .claude/agents/*.md files)

Agent Teams:
  Multi-agent coordination for large tasks.
  Enable: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude
  Or: claude --agent-teams
  - Lead agent delegates to specialist agents
  - Agents work in parallel on subtasks
  - Automatic message delivery between agents
  - Worktree isolation: each agent gets its own branch
  - Proof: 16-agent team wrote 100K+ line Rust C compiler

Worktree Isolation:
  ┌─ main branch ──────────────────────────┐
  │                                         │
  │  ┌─ agent-1 worktree (implement) ──┐   │
  │  │  isolated copy of repo          │   │
  │  └─────────────────────────────────┘   │
  │                                         │
  │  ┌─ agent-2 worktree (test) ───────┐   │
  │  │  isolated copy of repo          │   │
  │  └─────────────────────────────────┘   │
  │                                         │
  └─────────────────────────────────────────┘
  Flags: --worktree / -w (CLI)
         isolation: "worktree" (agent defs)
  Hook events: WorktreeCreate, WorktreeRemove

  Status line hooks include a "worktree" field with:
    name, path, branch, and original repo directory
    (available when running in a --worktree session)

Agent Hook Metadata:
  Hook events now include:
  - agent_id: identifies the subagent
  - agent_type: present for subagents and --agent
  Enables tracking and automation of agent workflows.

VS Code Plan View:
  Plans now render as full markdown documents in VS Code.
  Add comments directly on plan steps for feedback.

Background Agents:
  background: true in agent definitions
  Ctrl+F to kill background agents

CLI --agents flag:
  claude --agents '[{"name":"dev",...}]'
  Provide dynamic JSON agent definitions at runtime
  (overrides .claude/agents/ files for that session)