[BUG] Cannot create working agents or multi-step commands

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Claude Code Bug Report: Fundamental Agent Execution Failures

Summary

Claude Code agents fail catastrophically on complex multi-step workflows involving JSON parsing, state management, and cross-agent communication. Despite 21 iterative attempts over multiple days to fix a PR merge automation agent, fundamental reliability issues in Claude's agent execution model make complex workflows impossible.

Status: Agent disabled and removed after complete failure
Impact: High - blocks automation of critical development workflows
Time Investment: Multiple days of debugging and refinement across 21 commits

Environment

• Claude Code Version: Latest (as of 2025-10-14)
• Model: claude-sonnet-4-5-20250929
• Platform: macOS Darwin 24.6.0
• Repository Type: Node.js/TypeScript monorepo with Yarn workspaces

Problem Description

Attempted to create a pr:merge agent to automate PR merging with the following workflow:

1. Check for uncommitted changes (auto-commit if auto-update=true parameter)
2. Identify target PR (from parameter or current branch)
3. Fetch comprehensive PR info via shared command (reviews, CI status, merge state)
4. Validate merge readiness (not merged, not draft, approved, CI passing)
5. Execute squash merge with PR description as commit message

Result: Agent consistently fails despite extensive fixes, documentation, and simplification.

Failure Modes

1. JSON Parsing Failures

Despite explicit instructions to parse JSON output from shared commands, agents:

• Ignore JSON markers (e.g., PR_SUMMARY_JSON:, PR_INFO_JSON:)
• Parse wrong fields or use placeholder syntax instead of actual values
• Display raw JSON to users instead of extracting fields internally
• Fail to extract nested JSON fields correctly

Evidence: 5 separate commits explicitly addressing JSON parsing issues:

• Standardized JSON output format across shared commands
• Improved output parsing from invoked commands
• Clarified PR summary markdown field extraction
• Simplified JSON to single-line format for parsing reliability
• Added instructions to parse JSON internally without displaying to users

Example Instructions That Failed:

- **CRITICAL**: Parse the line starting with `PR_SUMMARY_JSON:` from the command output
- **CRITICAL**: Extract the `markdown` field from the parsed JSON
- **CRITICAL**: Use the `markdown` field value, not placeholder syntax

All consistently ignored during execution.

2. State Management Failures

Agents fail to maintain state across multiple tool invocations:

• Re-fetch data already retrieved earlier in workflow
• Lose context of what was previously parsed
• Execute steps out of order despite explicit numbering
• Skip critical validation steps

Evidence: 4 commits attempting to fix state issues:

• Fixed workflow with proper validation and metadata handling
• Consolidated PR information utilities to reduce re-fetching
• Added explicit "store and use" instructions for parsed JSON
• Simplified to autonomous workflow to remove interactive state management

Example Instructions That Failed:

- **CRITICAL**: Store parsed JSON for ALL remaining steps - do NOT re-fetch
- **CRITICAL**: Wait for completion, parse JSON once, use throughout workflow

Agent still re-fetched data and lost previously parsed values.

3. Instruction Adherence Failures

Agents ignore explicit, bolded, capitalized instructions:

• "CRITICAL" markers ignored
• "DO NOT" directives violated
• Explicit step ordering (1, 2, 3, 4) not followed
• Exit conditions bypassed

Example Instructions That Failed (from final agent version):

- **CRITICAL**: If empty output (clean working tree) → proceed to step 2 immediately
- **CRITICAL**: Perform checks in this EXACT order. Exit IMMEDIATELY if any check fails.
- **EXIT IMMEDIATELY** - do not check 4b, 4c, or 4d

4a. Check if already merged
    - If true: Display "PR is already merged"
    - **EXIT IMMEDIATELY** - do not check 4b, 4c, or 4d

4b. Check if draft
    - If true: Display "Cannot merge - PR is in draft mode"
    - **EXIT IMMEDIATELY** - do not check approvals or CI
    - If false: Continue to 4c

4c. Check approvals
    - If no approvals: Display "Cannot merge - requires approval"
    - **EXIT IMMEDIATELY** - do not check CI
    - Otherwise: Continue to 4d

4d. Check CI status (ONLY reached if 4a-4c all passed)

Agent executed steps out of order and continued past exit conditions.

4. Tool Invocation Failures

Agents fail to correctly invoke other agents/commands:

• Use wrong invocation patterns despite documentation
• Pass malformed parameters
• Don't wait for command completion before using results
• Invoke commands with incorrect syntax

Evidence: 3 commits fixing invocation patterns:

• Standardized invocation pattern across all command wrappers
• Added pr-summary-generate shared utility with explicit invocation docs
• Created unified pr-info command with documented parameter format

5. Working Tree Detection Failures

Even simple git operations fail:

• git status --porcelain returns empty (clean tree)
• Agent claims uncommitted changes exist
• Conflicting results between consecutive git status calls
• Cannot reliably detect clean vs dirty working tree

Evidence: 4 commits attempting to fix:

• Improved uncommitted changes detection with explicit empty-check
• Enhanced uncommitted changes handling with retry logic
• Added git --no-optional-locks to avoid cache issues
• Made workflow autonomous to avoid interaction state problems

Instructions That Failed:

Run `git --no-optional-locks status --porcelain`

- **CRITICAL**: If empty output (clean working tree) → Display "✓ No uncommitted changes" → proceed immediately
- **CRITICAL**: If conflicting results, run again and trust most recent output

In final execution: git returned empty (clean tree), agent claimed changes existed anyway.

6. Workflow Simplification Ineffective

Attempted progressive simplifications to reduce complexity:

• Removed all interactive prompts → still failed
• Consolidated commands to reduce cross-agent calls → still failed
• Flattened directory structure → still failed
• Made agent fully autonomous → still failed
• Reduced instructions from 264 lines to 112 lines (58%) → still failed

Evidence: 9 commits attempting simplification with no success:

• Streamlined documentation (58% reduction)
• Made fully autonomous workflow (no user prompts)
• Enhanced with better error handling
• Made PR summary regeneration optional (fewer steps)
• Plus 5 additional refinement attempts

Detailed Timeline of Fix Attempts

Phase 1: Initial Implementation (5 commits)

• Created agent architecture with command wrappers
• Established invocation patterns documentation
• Added comprehensive validation workflow
• Result: Basic structure in place but execution failures

Phase 2: JSON Parsing Fixes (5 commits)

• Standardized output formats across commands
• Added explicit JSON marker parsing instructions
• Consolidated metadata fetching into single command
• Improved output parsing documentation
• Created shared pr-summary-generate utility
• Result: Still ignoring JSON markers and parsing incorrectly

Phase 3: State Management Fixes (4 commits)

• Added "store and reuse" instructions for parsed data
• Removed redundant data fetching
• Consolidated PR info into single command
• Made validation steps sequential with clear dependencies
• Result: Still re-fetching data and losing state

Phase 4: Simplification Attempts (7 commits)

• Removed all interactive prompts (fully autonomous)
• Reduced documentation by 58%
• Simplified JSON to single-line format
• Added auto-update parameter for streamlined flow
• Made every instruction explicit with CRITICAL markers
• Added --no-optional-locks to git commands
• Clarified to parse JSON internally without displaying
• Result: COMPLETE FAILURE - agent unusable

Final Attempt (Current Session)

User ran /flow:pr-merge auto-update=true on clean working tree:

• Agent claimed uncommitted changes existed (git status showed clean)
• Auto-committed and pushed a minor documentation change
• Failed to parse PR_SUMMARY_JSON output from pr-summary-generate
• Never extracted the markdown field despite explicit instructions
• User interrupted and disabled the agent entirely

Statistics

• Total Commits: 21 iterative fix attempts
• Files Changed: 36 files, +1,148 lines, -675 lines
• Commits Addressing JSON Parsing: 5
• Commits Addressing State Management: 4
• Commits Addressing Validation Flow: 6
• Commits Simplifying Workflow: 9
• Commits Fixing Tool Invocations: 3

Root Cause Analysis

Claude Code agents appear to have fundamental limitations in:

1. Complex State Tracking: Cannot maintain parsed data across multiple tool uses in same conversation
2. Instruction Following: Ignores explicit directives even when marked CRITICAL
3. JSON Parsing: Cannot reliably parse structured output from other agents/commands
4. Sequential Logic: Fails to execute numbered steps in order
5. Conditional Logic: Doesn't properly evaluate exit conditions
6. Tool Integration: Cannot reliably invoke and consume output from other agents

These failures compound in multi-step workflows, making complex automation impossible regardless of how much the workflow is simplified or documented.

Reproduction Steps

1. Create an agent that needs to:

• Parse JSON output from another command (with marker like RESULT_JSON: {...})
• Maintain state across multiple steps (store parsed data, reuse later)
• Execute conditional logic with early exits (if X then stop, else continue)
• Make decisions based on parsed data fields

1. Add explicit, bolded, CAPITALIZED instructions for each step

1. Document exit conditions with EXIT IMMEDIATELY markers

1. Test the agent with various scenarios

Expected: Agent follows instructions, parses JSON correctly, maintains state
Actual: Agent ignores instructions, fails to parse JSON, loses state, executes steps out of order

Workaround

Abandoned agent-based automation. Using manual git/gh CLI commands instead:

git status
gh pr view
gh pr merge --squash

Impact Assessment

Development Velocity: Significant negative impact

• Cannot automate repetitive PR workflows
• Manual merge process required
• Time wasted on unreliable automation (multiple days)

Developer Confidence: Severely degraded

• Complex agents cannot be trusted
• Must verify every agent action manually (defeats purpose)
• Simpler to use CLI directly

Recommended Action:

• Do not use Claude Code agents for multi-step workflows
• Limit agents to single-action tasks with no state management
• Provide clear documentation about agent limitations

Conclusion

After 21 commits and multiple days of iterative fixes, the pr:merge agent remains fundamentally broken. The failures span JSON parsing, state management, instruction adherence, and basic git operations. These are not edge cases - they are core capabilities required for any non-trivial automation.

Claude Code agents are not suitable for complex multi-step workflows in their current state.

The time investment to debug and fix these issues far exceeds the value of the automation. Manual CLI operations are faster, more reliable, and less frustrating than debugging agent failures.

Suggested Interim Solution

Until these fundamental issues are resolved, Claude Code should:

1. Document maximum recommended complexity levels
2. Provide built-in primitives for common patterns (JSON parsing, state storage, conditionals)
3. Add warnings when users attempt overly complex workflows
4. Focus agent development on single-purpose, non-stateful tasks

Complex workflows should be handled by traditional scripting tools (bash, Python) rather than Claude Code agents.

What Should Happen?

Recommendations for Claude Code Team

Critical Fixes Needed

1. Improve State Management

• Allow agents to store and reference parsed data reliably
• Provide explicit state storage mechanism across tool uses
• Don't lose context between sequential operations
• Consider adding a "variables" system where agents can store/retrieve values

1. Strengthen Instruction Adherence

• Implement "hard" directives that cannot be overridden
• Make CRITICAL markers actually enforce behavior
• Add validation layer for step ordering compliance
• Provide assertion system (e.g., ASSERT: variable X must exist before step 5)

1. Fix JSON Parsing

• Provide built-in JSON parsing tools (don't rely on LLM to parse text)
• Make structured output a first-class feature with schema validation
• Add schema validation for inter-agent communication
• Consider structured response format like <json>...</json> tags that get auto-parsed

1. Improve Debugging

• Show agent's internal state/reasoning
• Log what instructions were followed vs ignored
• Provide step-by-step execution trace
• Add "dry run" mode that shows planned steps without execution

1. Set Realistic Expectations

• Document agent limitations clearly
• Provide guidance on what complexity levels work
• Show examples of workflows that are too complex
• Add complexity metrics (e.g., "agents work well with ≤3 sequential steps")

Testing Recommendations

Create comprehensive test suite for:

• Multi-step workflows (5+ sequential steps)
• JSON parsing from other agents
• Conditional logic with early exits
• State management across tool invocations
• Sequential validation with exit conditions
• Cross-agent communication with structured data

Error Messages/Logs

included in other sections

Steps to Reproduce

Example of Failed Instructions

Here's a representative example of instructions that were completely ignored:

**Step 1: Check for uncommitted changes**

Run `git --no-optional-locks status --porcelain`

- **CRITICAL**: If empty output (clean working tree) → Display "✓ No uncommitted changes" → proceed to step 2 immediately
- **CRITICAL**: If conflicting results, run again and trust most recent output

**Step 3: Fetch and validate PR info**

- Invoke: `/flow:pr-info {target_pr_number} output-format=json`
- **CRITICAL**: Wait for completion, parse `PR_INFO_JSON:` line, extract JSON
- **CRITICAL**: Store parsed JSON for ALL remaining steps - do NOT re-fetch
- Parse: pr.number, pr.url, pr.title, pr.body, pr.state, pr.isDraft, pr.mergedAt

**Step 4: Validate merge readiness (using stored JSON from step 3)**

**CRITICAL: Perform checks in this EXACT order. Exit IMMEDIATELY if any check fails. Do NOT proceed to subsequent checks:**

4a. **Check if already merged**: pr.state="MERGED" or pr.mergedAt ≠ null
    - If true: Display "✓ PR is already merged"
    - **EXIT IMMEDIATELY** - do not check 4b, 4c, or 4d

4b. **Check if draft**: pr.isDraft=true
    - If true: Display "✗ Cannot merge - PR is in draft mode"
    - **EXIT IMMEDIATELY** - do not check approvals or CI
    - If false: Continue to 4c

Agent behavior:

• Claimed uncommitted changes when git status was empty
• Did not parse JSON from pr-info command
• Used placeholder syntax like {pr.number} instead of actual values
• Continued to step 4d even when 4b should have exited
• Re-fetched PR data multiple times instead of using stored JSON

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.0.15 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

_No response_