temp/docs/reference/workflows/workflow_parity.md

Workflow Parity Matrix

This document maps Plandex Go workflows to CleverAgents Python modules.

Summary Statistics

• Total workflows: 15
• Go components: 51
• Python modules: 47
• Total stages: 73

Workflows by Category

Plan Lifecycle

Plan creation, building, applying, and archiving

Plan Create

Create a new plan with initial context

Stages:

1. initialization: Create plan structure and metadata
2. context_setup: Set up initial context and files
3. model_selection: Choose default model for the plan
4. persistence: Save plan to database/filesystem

Python Modules:

• cleveragents.domain.plans
• cleveragents.application.plan_service
• cleveragents.cli.commands.plan

Test Coverage:

• behave: features/plans.feature
• robot: robot/plan_lifecycle.robot
• go_tests: app/cli/cmd/plan_test.go

Notes: Must maintain backward compatibility with existing plan formats

Plan Build

Build plan by processing prompts through AI models

Stages:

1. prompt_processing: Process user prompts and context
2. model_interaction: Send to AI model and get response
3. diff_generation: Generate diffs from AI response
4. validation: Validate generated changes
5. storage: Store diffs and conversation history

Python Modules:

• cleveragents.application.build_service
• cleveragents.domain.diffs
• cleveragents.infrastructure.ai_providers
• cleveragents.cli.commands.tell

Test Coverage:

• behave: features/plan_build.feature
• robot: robot/build_workflow.robot

Notes: Streaming updates must match Go implementation timing

Plan Apply

Apply plan changes to files with review and confirmation

Stages:

1. diff_preview: Show pending changes to user
2. confirmation: Get user confirmation
3. file_updates: Apply diffs to files
4. git_operations: Optional git commit
5. cleanup: Clean up temporary files

Python Modules:

• cleveragents.application.apply_service
• cleveragents.domain.file_operations
• cleveragents.infrastructure.git_integration
• cleveragents.cli.commands.apply

Test Coverage:

• behave: features/apply.feature
• robot: robot/apply_workflow.robot

Notes: Must handle merge conflicts and rollback on failure

Context Management

Context loading, modification, and auto-detection

Context Load

Load files and directories into plan context

Stages:

1. path_resolution: Resolve file paths and globs
2. content_reading: Read file contents
3. filtering: Apply ignore patterns
4. indexing: Index content for search
5. storage: Store in context database

Python Modules:

• cleveragents.domain.context
• cleveragents.application.context_service
• cleveragents.infrastructure.file_loader
• cleveragents.cli.commands.context

Test Coverage:

• behave: features/context.feature
• robot: robot/context_management.robot

Notes: Auto-context detection must match Go heuristics

Context Auto

Automatically detect and load relevant context

Stages:

1. detection: Detect project type and structure
2. heuristics: Apply loading heuristics
3. filtering: Filter irrelevant files
4. loading: Load detected context

Python Modules:

• cleveragents.application.auto_context
• cleveragents.domain.heuristics

Test Coverage:

• behave: features/auto_context.feature
• robot: robot/auto_context.robot

Notes: Heuristics extracted in implicit behaviors discovery

Execution Flows

Command execution, auto-debug, and rollback

Exec Command

Execute commands in plan context with capture

Stages:

1. command_parsing: Parse command and arguments
2. environment_setup: Set up execution environment
3. execution: Run command with output capture
4. result_processing: Process output and errors
5. context_update: Update context with results

Python Modules:

• cleveragents.application.exec_service
• cleveragents.infrastructure.process_runner
• cleveragents.domain.exec_results

Test Coverage:

• behave: features/exec.feature
• robot: robot/execution.robot

Notes: Must support process groups and cgroup isolation

Auto Debug

Automatically debug and retry failed operations

Stages:

1. error_detection: Detect errors in output
2. error_analysis: Analyze error for fix strategy
3. fix_generation: Generate fix with AI model
4. fix_application: Apply fix and retry
5. validation: Validate fix succeeded

Python Modules:

• cleveragents.application.debug_service
• cleveragents.domain.error_analysis
• cleveragents.infrastructure.ai_debug

Test Coverage:

• behave: features/auto_debug.feature
• robot: robot/debug_workflow.robot

Notes: Retry limits and backoff must match Go implementation

Branching

Branch creation, switching, merging, and diff management

Branch Create

Create and switch plan branches

Stages:

1. validation: Validate branch name
2. creation: Create branch structure
3. copying: Copy current state to branch
4. switching: Switch to new branch
5. persistence: Save branch metadata

Python Modules:

• cleveragents.domain.branches
• cleveragents.application.branch_service
• cleveragents.cli.commands.branches

Test Coverage:

• behave: features/branches.feature
• robot: robot/branching.robot

Notes: Branch switching must preserve unsaved changes

Branch Merge

Merge branches with conflict resolution

Stages:

1. diff_comparison: Compare branch diffs
2. conflict_detection: Detect merge conflicts
3. conflict_resolution: Resolve conflicts
4. merge_application: Apply merged changes
5. cleanup: Clean up merged branch

Python Modules:

• cleveragents.application.merge_service
• cleveragents.domain.conflict_resolution

Test Coverage:

• behave: features/merge.feature
• robot: robot/merge_workflow.robot

Notes: Must support manual and automatic conflict resolution

Collaboration

Team invites, sharing, and permissions

Team Invite

Invite team members and manage permissions

Stages:

1. invite_creation: Create invite
2. notification: Send invite notification
3. acceptance: Process invite acceptance
4. permission_grant: Grant permissions
5. sync: Sync team state

Python Modules:

• cleveragents.domain.teams
• cleveragents.application.invite_service
• cleveragents.infrastructure.notifications

Test Coverage:

• behave: features/collaboration.feature
• robot: robot/team_workflow.robot

Notes: Replace cloud invites with SMTP or local alternatives

Model Management

Model selection, custom models, and provider configuration

Model Selection

Select and configure AI models

Stages:

1. model_listing: List available models
2. capability_check: Check model capabilities
3. selection: Select model
4. validation: Validate API keys
5. configuration: Save model configuration

Python Modules:

• cleveragents.domain.models
• cleveragents.application.model_service
• cleveragents.infrastructure.model_providers
• cleveragents.cli.commands.models

Test Coverage:

• behave: features/models.feature
• robot: robot/model_management.robot

Notes: Model catalog refresh must be automated

Authentication

Login, logout, session management, and API keys

Auth Login

User authentication and session establishment

Stages:

1. credential_input: Get user credentials
2. authentication: Verify credentials
3. session_creation: Create session token
4. token_storage: Store token locally
5. verification: Verify session active

Python Modules:

• cleveragents.infrastructure.auth
• cleveragents.domain.sessions
• cleveragents.cli.commands.auth

Test Coverage:

• behave: features/authentication.feature
• robot: robot/auth_workflow.robot

Notes: Must support both API key and email/password auth

Configuration

Settings, environment variables, and config files

Config Management

Manage application configuration

Stages:

1. config_loading: Load configuration files
2. env_merging: Merge environment variables
3. validation: Validate configuration
4. application: Apply configuration
5. persistence: Save configuration changes

Python Modules:

• cleveragents.infrastructure.config
• cleveragents.domain.settings
• cleveragents.cli.commands.config

Test Coverage:

• behave: features/configuration.feature
• robot: robot/config_management.robot

Notes: Must support CLEVERAGENTS_ env vars exclusively

Streaming

Real-time updates, logs, and progress tracking

Stream Updates

Stream real-time updates during operations

Stages:

1. connection: Establish streaming connection
2. buffering: Buffer incoming chunks
3. rendering: Render updates to UI
4. error_handling: Handle connection errors
5. cleanup: Clean up on completion

Python Modules:

• cleveragents.infrastructure.streaming
• cleveragents.application.stream_service
• cleveragents.cli.ui.stream_renderer

Test Coverage:

• behave: features/streaming.feature
• robot: robot/streaming.robot

Notes: Must handle reconnection and backpressure

Background Jobs

Async tasks, retries, and job scheduling

Background Jobs

Manage background tasks and job scheduling

Stages:

1. job_creation: Create job definition
2. scheduling: Schedule job execution
3. execution: Execute job task
4. retry: Retry on failure
5. completion: Mark job complete

Python Modules:

• cleveragents.infrastructure.jobs
• cleveragents.application.job_service
• cleveragents.domain.background_tasks

Test Coverage:

• behave: features/background_jobs.feature
• robot: robot/job_scheduling.robot

Notes: Use asyncio or celery for job management

Recommended Implementation Order

Based on dependency analysis:

1. team_invite - Invite team members and manage permissions
2. auth_login - User authentication and session establishment
3. model_selection - Select and configure AI models
4. background_jobs - Manage background tasks and job scheduling
5. auto_debug - Automatically debug and retry failed operations
6. config_management - Manage application configuration
7. context_load - Load files and directories into plan context
8. plan_apply - Apply plan changes to files with review and confirmation
9. branch_merge - Merge branches with conflict resolution
10. branch_create - Create and switch plan branches
11. stream_updates - Stream real-time updates during operations
12. plan_build - Build plan by processing prompts through AI models
13. plan_create - Create a new plan with initial context
14. context_auto - Automatically detect and load relevant context
15. exec_command - Execute commands in plan context with capture