Refactor: Restructure Agent Architecture to Workflow-Based Modular Design

[Chethan-b13]

Overview

Restructure Mini Cursor from a monolithic agent architecture with nested subgraphs to a clean, workflow-based modular design. This will eliminate state bloat, clarify boundaries between workflows, and make the codebase easier to scale and maintain.

Current complexity: Agent state has 10+ fields, multiple overlapping routers, unclear node-to-service mapping, subgraph nesting ambiguity.

Target state: Each workflow (editing, debugging, analysis) is self-contained with its own state, routers, nodes, and prompts.

---

Problems to Solve

1. State Bloat

• AgentState contains fields for all workflow types (debug_attempts, approved, requires_changes, task_reasoning)
• Nodes only use a subset of fields; unclear which fields belong to which workflow
• No type safety across different workflow contexts

2. Subgraph Nesting Ambiguity

• editing_subgraph exists at top-level AND nested in debugging_subgraph
• Unclear if nested version runs with different tools/context
• Hard to understand execution flow

3. Router Proliferation

• Multiple routers scattered across app/graph/router.py: supervisor_router, editing_tools_router, editing_approval_router, editing_review_router
• Full workflow flow not visible in one place
• Hard to trace decision logic

4. Unclear Node-to-Service Separation

• Unclear whether logic should live in nodes or services
• supervisor_node is thin wrapper around app/services/supervisor.py
• No consistent pattern for this separation

5. Prompt Architecture Governance

• debugging_subgraph_prompts.py and editing_subgraph_prompts.py work but inconsistent
• Adding new workflows requires new prompt files with no pattern
• Prompts scattered across app/prompts/ with no clear organization

---

Proposed Solution

New Structure

app/
├── workflows/          # Each workflow is self-contained
│   ├── __init__.py
│   ├── base.py         # Shared workflow interface
│   ├── editing/
│   │   ├── __init__.py
│   │   ├── graph.py    # StateGraph definition
│   │   ├── nodes.py    # All node implementations
│   │   ├── router.py   # All routing logic
│   │   ├── state.py    # EditingState (typed, specific)
│   │   ├── prompts.py  # All editing prompts
│   │   └── tools.py    # Editing-specific tools
│   ├── debugging/
│   │   ├── __init__.py
│   │   ├── graph.py
│   │   ├── nodes.py
│   │   ├── router.py
│   │   ├── state.py
│   │   ├── prompts.py
│   │   └── tools.py
│   ├── analysis/
│   │   ├── __init__.py
│   │   ├── graph.py
│   │   ├── nodes.py
│   │   ├── router.py
│   │   ├── state.py
│   │   ├── prompts.py
│   │   └── tools.py
│   └── composition.py  # Orchestrator (replaces agent.py)
│
├── core/
│   ├── llm.py          # LLM client (unchanged)
│   ├── supervisor.py   # Task classification (moved from services/)
│   └── base_nodes.py   # Shared node utilities (optional)
│
├── services/           # Shared utilities ONLY
│   ├── codebase_indexer.py
│   ├── retrieval.py
│   └── tool_executor.py  # Centralized tool execution
│
└── [other files unchanged]

Key Benefits

• ✅ Isolation: Each workflow is independent—changes to editing don't risk debugging
• ✅ Type Safety: Workflow-specific states with IDE autocomplete
• ✅ Scalability: Add new workflows without touching existing code
• ✅ Clarity: Full workflow logic visible in one folder
• ✅ Testability: Unit test each workflow in isolation
• ✅ Onboarding: New developers can understand one workflow at a time

---

Acceptance Criteria

• All workflows (editing, debugging, analysis) moved to app/workflows/
• Each workflow has its own: graph.py, state.py, nodes.py, router.py, prompts.py, tools.py
• Workflow-specific states replace monolithic AgentState
• Workflows are independent and invoke each other (no nesting)
• app/workflows/composition.py orchestrates all workflows
• app/core/supervisor.py handles task classification only
• app/services/tool_executor.py centralizes tool execution
• All tests pass for individual workflows
• All tests pass for end-to-end flow
• Old app/graph/subgraphs/, app/prompts/, and unused files deleted
• main.py unchanged and working

---

Implementation Checklist

Phase 1: Setup

• Create app/workflows/ folder structure
• Create app/workflows/__init__.py
• Create app/workflows/base.py with shared workflow interface
• Move/create app/core/supervisor.py (extract from services if needed)

Phase 2: Editing Workflow

• Create app/workflows/editing/ folder
• Create app/workflows/editing/__init__.py
• Move app/graph/subgraphs/editing_subgraph.py → app/workflows/editing/graph.py
• Create app/workflows/editing/state.py (extract from AgentState)
• Create app/workflows/editing/nodes.py (import from app/graph/nodes/)
• Create app/workflows/editing/router.py (move from app/graph/router.py)
• Create app/workflows/editing/prompts.py (move from app/prompts/editing_subgraph_prompts.py)
• Create app/workflows/editing/tools.py (organize editing tools)
• Test editing workflow in isolation

Phase 3: Debugging Workflow

• Create app/workflows/debugging/ folder
• Create app/workflows/debugging/__init__.py
• Move debugging subgraph components
• Create app/workflows/debugging/state.py
• Import and invoke editing_workflow (no nesting)
• Test debugging workflow in isolation

Phase 4: Analysis Workflow

• Create app/workflows/analysis/ folder
• Create app/workflows/analysis/__init__.py
• Move analysis agent components
• Create app/workflows/analysis/state.py
• Create app/workflows/analysis/prompts.py
• Create app/workflows/analysis/nodes.py, router.py, graph.py
• Test analysis workflow in isolation

Phase 5: Orchestration & Composition

• Create app/workflows/composition.py with orchestrator router
• Update app/graph/agent.py to use composition (or replace entirely)
• Verify main.py unchanged
• Test composition routing

Phase 6: Cleanup

• Delete app/graph/subgraphs/ (moved to workflows)
• Delete app/prompts/ (moved to workflows)
• Delete unused nodes from app/graph/nodes/ (keep only shared utilities)
• Simplify/delete app/graph/router.py (moved to workflows)
• Consider deleting app/graph/ entirely if empty

Phase 7: Testing & Validation

• Run individual workflow tests
• Run composition routing tests
• Run end-to-end test via main.py
• Verify all imports resolve correctly
• Check for any dead code or broken references

---

Additional Context

Why This Refactoring Matters

This project is at an inflection point:

• Current architecture works for 3 workflows
• Adding a 4th workflow requires modifying 5+ files
• New developers struggle to understand the flow
• State contract is implicit, not explicit
• Testing individual workflows is difficult

The proposed structure scales to N workflows without this friction.

Notes

• This is a breaking refactor—consider doing it on a feature branch
• Commit phase-by-phase to keep git history clean
• Consider adding app/core/base_nodes.py if shared node patterns emerge
• app/schemas/ folder stays as-is (state types now in workflows)
• app/tools/ stays as-is (shared by all workflows)
• main.py should not change—composition handles routing transparently

---

Labels

• refactoring
• architecture
• enhancement
• breaking-change