LangGraph Architecture Tuning Command

Boldly modify the graph structure of LangGraph applications to improve performance. Explore multiple improvement proposals in parallel to identify the optimal configuration.

🎯 Purpose

Optimize graph structure according to the following objectives:

$ARGUMENTS

While the fine-tune skill focuses on prompt and parameter optimization, the arch-tune command modifies the graph structure itself:

• Add/remove nodes and edges
• Introduce subgraphs
• Add parallel processing
• Change routing strategies
• Switch architectural patterns

📋 Execution Flow

Initialization: Task Registration

At the start of the arch-tune command, use the TodoWrite tool to register all Phases from the following sections as tasks. (It's recommended to include a reference to this file to avoid forgetting its contents.)

Update each Phase to in_progress at the start and completed upon completion.

Phase 1: Analysis and Proposal (arch-analysis skill)

Execution Steps:

1. Launch the arch-analysis skill
   • Verify/create evaluation program (.langgraph-architect/evaluation/)
   • Measure baseline performance (3-5 runs)
   • Analyze graph structure (using Serena MCP)
   • Identify bottlenecks
   • Consider architectural patterns
   • Generate 3-5 specific improvement proposals

Output:

• analysis/baseline_performance.json - Baseline performance (including statistics)
• analysis/analysis_report.md - Current state analysis and issues
• analysis/improvement_proposals.md - Detailed improvement proposals (Proposal 1-5)
• .langgraph-architect/evaluation/ - Evaluation program (created or verified)

→ See arch-analysis skill for detailed procedures and workflow

Phase 2: Implementation

Purpose: Implement graph structure for each improvement proposal

Execution Steps:

1. Create and Prepare Git Worktrees

   Create independent working environments for each improvement proposal:

   # Create worktree for each Proposal 1, 2, 3
   git worktree add worktree/proposal-1 -b proposal-1
   git worktree add worktree/proposal-2 -b proposal-2
   git worktree add worktree/proposal-3 -b proposal-3
   
   # Copy analysis results and .env to each worktree
   for dir in worktree/*/; do
     cp -r analysis "$dir"
     cp .env "$dir"
   done
   
   # If evaluation program is in original directory, make it executable in each worktree
   # (No copy needed if using shared .langgraph-architect/evaluation/)
   

   Directory Structure:

   project/
   ├── worktree/
   │   ├── proposal-1/          # Independent working environment 1
   │   │   ├── analysis/        # Analysis results (copy **Copy as files after creating worktree, don't commit and pass!**)
   │   │   │   ├── baseline_performance.json
   │   │   │   ├── analysis_report.md
   │   │   │   └── improvement_proposals.md
   │   │   └── [project files]
   │   ├── proposal-2/          # Independent working environment 2
   │   └── proposal-3/          # Independent working environment 3
   ├── analysis/                # Analysis results (original)
   └── [original project files]
   

2. Parallel Implementation by langgraph-engineer

   Launch langgraph-engineer agent for each Proposal:

   Working worktree: worktree/proposal-X/
   Improvement proposal: Proposal X (from analysis/improvement_proposals.md)
   Task: Implement graph structure changes and test that it works correctly (add/modify nodes, edges, subgraphs)
   
   Complete implementation as langgraph-engineer.
   See agents/langgraph-engineer.md for details.
   

   Parallel Execution Pattern:

   • Start implementation for all Proposals (1, 2, 3, ...) in parallel
   • Each langgraph-engineer agent works independently

3. Wait for All Implementations to Complete

   • Parent agent confirms completion of all implementations

Phase 3: Optimization

Purpose: Optimize prompts and parameters for implemented graphs

Execution Steps:

1. Parallel Optimization by langgraph-tuner

   After Phase 2 completion, launch langgraph-tuner agent for each worktree Proposal implementation:

   Working worktree: worktree/proposal-X/
   Improvement proposal: Proposal X (from analysis/improvement_proposals.md)
   Optimization goal: [User-specified goal]
   
   Note: Graph structure changes are completed in Phase 2. Skip Phase 2 and start from Phase 3 (testing).
   
   Result report:
   
   - Filename: `proposal_X_result.md` (save directly under worktree/proposal-X/)
   - Format: Summarize experiment results and insights concisely
   - Required items: Comparison table with baseline, improvement rate, key changes, recommendations
   
   Execute optimization workflow as langgraph-tuner.
   See agents/langgraph-tuner.md for details.
   

   Parallel Execution Pattern:

   • Start optimization for all Proposals (1, 2, 3, ...) in parallel
   • Each langgraph-tuner agent works independently

2. Wait for All Optimizations to Complete

   • Parent agent confirms completion of all optimizations and result report generation

Important:

• Use the same evaluation program across all worktrees

Phase 4: Results Comparison (proposal-comparator agent)

Purpose: Identify the best improvement proposal

Execution Steps:

Launch proposal-comparator agent:

Implementation reports: Read `proposal_X_result.md` from each worktree

- worktree/proposal-1/proposal_1_result.md
- worktree/proposal-2/proposal_2_result.md
- worktree/proposal-3/proposal_3_result.md
  Optimization goal: [User-specified goal]

Execute comparative analysis as proposal-comparator.
See agents/proposal-comparator.md for details.

Phase 5: Merge Confirmation (merge-coordinator agent)

Purpose: Merge with user approval

Execution Steps:

Launch merge-coordinator agent:

Comparison report: analysis/comparison_report.md
Worktree: worktree/proposal-\*/

Execute user approval and merge as merge-coordinator.
See agents/merge-coordinator.md for details.

🔧 Technical Details

Git Worktree Commands

Create:

git worktree add worktree/<branch-name> -b <branch-name>

List:

git worktree list

Remove:

git worktree remove worktree/<branch-name>
git branch -d <branch-name>

Parallel Execution Implementation

Claude Code automatically executes in parallel by calling multiple Task tools in a single message.

Subagent Constraints

• ❌ Subagents cannot call other subagents
• ✅ Subagents can call skills
• → Each subagent can directly execute the fine-tune skill

⚠️ Notes

Git Worktree

1. Add worktree/ to .gitignore
2. Each worktree is an independent working directory
3. No conflicts even with parallel execution

Evaluation

1. Evaluation Program Location:

   • Recommended: Place in .langgraph-architect/evaluation/ (accessible from all worktrees)
   • Each worktree references the baseline copied to analysis/

2. Unified Evaluation Conditions:

   • Use the same evaluation program across all worktrees
   • Evaluate with the same test cases
   • Share environment variables (API keys, etc.)

3. Evaluation Execution:

   • Each langgraph-tuner agent executes evaluation independently
   • Ensure statistical reliability with 3-5 iterations
   • Each agent compares against baseline

Cleanup

1. Delete unnecessary worktrees after merge
2. Delete branches as well
3. Verify worktree/ directory

🎓 Usage Examples

Basic Execution Flow

# Execute arch-tune command
/arch-tune "Improve Latency to under 2.0s and Accuracy to over 90%"

Execution Flow:

1. Phase 1: arch-analysis skill generates 3-5 improvement proposals

   • See arch-analysis skill for detailed improvement proposals

2. Phase 2: Graph Structure Implementation

   • Create independent environments with Git worktree
   • langgraph-engineer implements graph structure for each Proposal in parallel

3. Phase 3: Prompt and Parameter Optimization

   • langgraph-tuner optimizes each Proposal in parallel
   • Generate result reports (proposal_X_result.md)

4. Phase 4: Compare results and identify best proposal

   • Display all metrics in comparison table

5. Phase 5: Merge after user approval

   • Merge selected proposal to main branch
   • Clean up unnecessary worktrees

Example: See arch-analysis skill improvement_proposals section for detailed proposal examples for customer support chatbot optimization.

🔗 Related Resources

• arch-analysis skill - Analysis and proposal generation (Phase 1)
• langgraph-engineer agent - Graph structure implementation (Phase 2)
• langgraph-tuner agent - Prompt optimization and evaluation (Phase 3)
• proposal-comparator agent - Results comparison and recommendation selection (Phase 4)
• merge-coordinator agent - User approval and merge execution (Phase 5)
• fine-tune skill - Prompt optimization (used by langgraph-tuner)
• langgraph-architect skill - Architectural patterns