Workflows & Practical Examples

Overview

This document provides practical examples and workflows demonstrating how to use theia AI effectively for common development tasks and custom scenarios.

Common Workflows

1. AI-Driven Code Development

Generate New Project

User: @Coder generate a React calculator app with TypeScript

Coder workflow:
1. Creates project structure
2. Generates package.json with dependencies
3. Creates src/app.tsx with calculator UI
4. Creates src/Calculator.ts with logic
5. Creates src/App.css for styling
6. Runs npm install
7. Starts dev server

Result: Running application in ~30 seconds

Iterate on Existing Code

User: @Coder add the option to skip a question in my quiz game

Coder workflow:
1. Reads existing code (game.js, ui.js)
2. Identifies relevant files
3. Proposes changes with diffs
4. Applies changes after approval
5. Tests functionality

Tip: Provide context with ${file:path/to/file}

Fix Bugs

User: @Coder fix the issue where multiplication performs division
      File: ${file:calculator.ts}

Coder workflow:
1. Reads calculator.ts
2. Locates multiplication function
3. Identifies bug: multiply() calls divide()
4. Proposes fix
5. Applies after confirmation

Best practice: Include error description and affected file

2. Testing Workflows

Full Application Testing

User: @AppTester test my calculator app running on localhost:3000

App Tester workflow:
1. Opens browser
2. Analyzes UI elements
3. Generates test cases:
   - Basic operations (+, -, ×, ÷)
   - Edge cases (0, negatives)
   - UI interactions
4. Executes each test
5. Reports results with screenshots

Duration: 2-5 minutes depending on complexity

Focused Testing

User: @AppTester test only the multiplication feature

App Tester workflow:
1. Opens application
2. Generates multiplication-specific tests:
   - Simple: 5 × 6 = 30
   - With zero: 7 × 0 = 0
   - Negative: -3 × 4 = -12
   - Large numbers: 999 × 999
3. Reports detailed results

Use when: Verifying specific feature after fix

Automated Bug Reporting

User: @AppTester test my app and report bugs to GitHub

Combined workflow:
1. App Tester runs tests
2. For each bug found:
   - Delegates to Bug Reporter agent
   - Bug Reporter creates GitHub issue with:
     • Title
     • Description
     • Steps to reproduce
     • Expected vs actual
     • Screenshot
3. App Tester continues testing

Result: Automated QA + issue tracking

3. GitHub Integration Workflows

Analyze Issues

User: @Architect analyze bug #123

Architect workflow:
1. Calls get_issue(123) via GitHub MCP
2. Reads issue description
3. Calls list_comments(123)
4. Analyzes discussion
5. Examines related code
6. Provides:
   - Root cause analysis
   - Proposed solution
   - Implementation approach

Use when: Need third-party perspective on complex bug

Code Review Assistance

User: @Architect review PR #456

Architect workflow:
1. Gets PR details
2. Fetches changed files
3. Analyzes changes for:
   - Code quality
   - Best practices
   - Potential issues
   - Performance impacts
4. Provides structured feedback

Output: Detailed review comments

Update Documentation

User: @Architect check if recent PRs need doc updates

Workflow:
1. Gets closed PRs from last 2 weeks
2. Analyzes changes
3. Checks documentation sections
4. Identifies gaps
5. Suggests updates with PR links

Automation: Regular documentation maintenance

4. Custom Agent Workflows

Blog Post Conversion

# Use case: Convert Google Doc to Hugo blog post

User: @Blogger convert ${file:draft-post.md}

Blogger workflow:
1. Reads source file
2. Examines example posts for format
3. Adds Hugo frontmatter:
   ---
   title: "..."
   date: 2024-01-01
   tags: [...]
   author: "..."
   ---
4. Fixes internal links (relative paths)
5. Embeds images correctly
6. Checks spelling/grammar
7. **STOPS** for user review
8. On approval, creates final post

Result: Production-ready blog post

Domain Model Manipulation

# Use case: Task flow designer

User: @FlowAssistant create 5 tasks for data processing

Flow Assistant workflow:
1. Creates task definitions:
   - Data ingestion
   - Data cleaning
   - Feature extraction
   - Model training
   - Result export
2. Saves to task-definitions/ folder
3. Opens in editor

User: @FlowAssistant create nodes to allocate these tasks

Flow Assistant workflow:
1. Lists existing tasks
2. Analyzes task requirements
3. Creates appropriate nodes
4. Allocates tasks to nodes
5. Generates visualization

Result: Complete task flow model

5. Project Context Workflows

Enhanced Code Generation

# Setup: Add project-info.md
# .theia/ai/project-info.md

Project: React TypeScript App
Testing: Jest + React Testing Library
- Tests in same directory as source
- Use .spec.tsx extension
- Example: Button.spec.tsx

Code Style:
- Functional components with hooks
- TypeScript strict mode
- ESLint + Prettier

# Usage:
User: @Coder create tests for Button component

Coder:
1. Reads project-info.md automatically
2. Uses correct file naming (Button.spec.tsx)
3. Places test in same directory
4. Uses Jest + RTL syntax
5. Follows code style guidelines

Benefit: Consistent with project conventions

Architecture Guidance

# project-info.md includes architecture rules

Architecture:
- Feature-based folder structure
- Services layer for business logic
- Hooks for component logic
- No direct API calls from components

User: @Coder add user authentication

Coder:
1. Creates src/features/auth/
2. Creates AuthService.ts (service layer)
3. Creates useAuth.ts (hook)
4. Creates LoginForm.tsx (component)
5. Integrates correctly per architecture

Result: Code follows established patterns

Real-World Scenarios

Scenario 1: Rapid Prototyping

Goal: Build MVP in one day

Morning:
1. @Coder generate initial project structure
2. @Coder create data models
3. @Coder implement core features
4. Manual review and adjustments

Afternoon:
5. @Coder add UI components
6. @Coder implement API integration
7. @AppTester run smoke tests
8. Fix issues found by testing

Evening:
9. @Coder add error handling
10. @Coder improve styling
11. Final testing
12. Deploy

Result: Working prototype in 8-10 hours

Scenario 2: Legacy Code Refactoring

Goal: Modernize old codebase

Phase 1: Analysis
User: @Architect analyze this legacy code and suggest refactoring
Agent: Provides modernization strategy

Phase 2: Incremental Updates
User: @Coder refactor authentication module using modern patterns
Agent: Refactors with tests

Phase 3: Testing
User: @AppTester verify authentication still works
Agent: Runs regression tests

Phase 4: Documentation
User: @Architect update documentation for new architecture
Agent: Generates updated docs

Timeline: Systematic, low-risk refactoring

Scenario 3: Bug Hunt

Goal: Find and fix all bugs before release

Day 1: Discovery
@AppTester: Comprehensive testing
- Generates 50+ test cases
- Finds 12 bugs
- Auto-reports to GitHub

Day 2: Prioritization
@Architect: Analyzes all bugs
- Categorizes by severity
- Suggests fix order
- Estimates effort

Day 3-4: Fixing
For each bug:
  @Coder: Implements fix
  @AppTester: Verifies fix
  @Architect: Reviews approach

Day 5: Verification
@AppTester: Full regression suite
Result: All bugs fixed, verified

Scenario 4: Documentation Sprint

Goal: Update all documentation

Week 1: Content Creation
For each feature:
  @Architect: Analyzes code
  @Architect: Generates doc outline
  Human: Reviews and refines
  @Coder: Creates examples
  @Blogger: Formats for publication

Week 2: Review
  @AppTester: Verifies code examples work
  @Architect: Checks completeness
  Human: Final editorial review

Week 3: Publishing
  @Blogger: Converts to final format
  Deploy to docs site

Result: Comprehensive, accurate documentation

Advanced Patterns

Multi-Agent Orchestration

# Complex workflow with multiple agents

Task: Build feature from user story

User: Implement user profile feature
  - View profile
  - Edit details
  - Upload avatar
  - Change password

Orchestration:
1. @Architect: 
   - Designs architecture
   - Creates component structure
   - Defines API contracts

2. @Coder:
   - Implements backend API
   - Creates frontend components
   - Adds validation

3. @AppTester:
   - Tests each component
   - Finds issues
   - Delegates bug reporting

4. @Architect:
   - Reviews implementation
   - Suggests improvements
   - Updates documentation

Result: Complete feature with documentation

Continuous Improvement Loop

# Ongoing quality enhancement

Daily:
- @AppTester: Runs regression suite
- @Coder: Fixes new issues
- @Architect: Reviews changes

Weekly:
- @Architect: Analyzes test coverage
- @Coder: Adds missing tests
- @AppTester: Verifies improvements

Monthly:
- @Architect: Reviews architecture
- @Coder: Refactors as needed
- @Blogger: Updates documentation

Result: Continuously improving codebase

Performance Optimization Workflows

Code Performance Review

User: @Architect analyze performance of data processing module

Architect workflow:
1. Reads code
2. Identifies bottlenecks:
   - O(n²) algorithms
   - Redundant computations
   - Memory leaks
3. Proposes optimizations
4. Estimates improvements

User: @Coder implement suggested optimizations

Coder workflow:
1. Applies optimizations
2. Adds performance tests
3. Benchmarks results
4. Documents changes

Result: 10x performance improvement

Bundle Size Optimization

User: @Architect reduce bundle size of React app

Workflow:
1. Analyzes dependencies
2. Identifies heavy packages
3. Suggests alternatives:
   - Lighter libraries
   - Code splitting
   - Lazy loading
4. @Coder implements changes
5. Measures new bundle size

Result: 40% smaller bundle

Team Collaboration Workflows

Code Handoff

Developer A:
@Coder: Implement feature X
@Architect: Document implementation

Handoff to Developer B:
@Architect: Explain feature X implementation to new developer
- Provides overview
- Shows key files
- Explains design decisions

Developer B:
@Coder: Continue with feature X extension
- Has full context
- Maintains patterns

Result: Smooth knowledge transfer

Onboarding

New Team Member:
@Architect: Explain project architecture
- System overview
- Component responsibilities
- Data flow
- Deployment process

@Architect: Where should I make changes for feature Y?
- Points to relevant files
- Explains patterns
- Provides examples

@Coder: Help me implement feature Y
- Guided implementation
- Follows project patterns
- Includes tests

Result: Productive from day 1

Tips and Tricks

1. Effective Prompting

❌ "Help me code"
✅ "@Coder implement user login with JWT authentication
    Requirements:
    - Email/password
    - Remember me option
    - Token refresh
    Files: ${file:auth.service.ts}"

❌ "Test my app"
✅ "@AppTester test checkout flow
    Focus on:
    - Cart operations
    - Payment form validation
    - Order confirmation
    URL: localhost:3000"

2. Context Management

# Provide relevant context

For new features:
- Requirements document
- Design mockups
- Example implementations

For bug fixes:
- Error logs
- Steps to reproduce
- Expected vs actual behavior

For refactoring:
- Current code
- Desired patterns
- Migration constraints

3. Iterative Development

# Build incrementally

Step 1: @Coder create basic structure
Step 2: @Coder add core functionality
Step 3: @Coder add error handling
Step 4: @Coder add tests
Step 5: @AppTester verify everything works

Benefits:
- Easier to review
- Faster feedback
- Lower risk

4. Specialized Agents

# Create agents for common tasks

@UIReviewer:
- Checks accessibility
- Validates responsive design
- Reviews UX patterns

@SecurityChecker:
- Scans for vulnerabilities
- Checks authentication
- Validates input sanitization

@PerformanceAuditor:
- Identifies bottlenecks
- Suggests optimizations
- Benchmarks improvements

5. Chaining Operations

# Combine agents for complex tasks

User: Create and test new feature

Workflow:
1. @Coder: Implement feature
2. @Coder: Add unit tests  
3. @AppTester: Run E2E tests
4. @Architect: Review implementation
5. @Blogger: Update documentation

All automated with one initial prompt

Troubleshooting Common Issues

Agent Not Understanding Context

Problem: Agent makes incorrect assumptions

Solution:

# Be explicit
❌ "Fix the bug"
✅ "Fix multiplication bug in calculator.ts
    Problem: multiply() calls divide() instead
    Expected: 5 × 6 = 30
    Actual: 5 × 6 = 0.833"

Agent Making Wrong Changes

Problem: Agent modifies wrong files

Solution:

# Specify exact files
❌ "Update the component"
✅ "Update UserProfile component
    File: ${file:src/components/UserProfile.tsx}
    Change: Add email field to form"

Tests Failing Intermittently

Problem: Flaky tests

Solution:

@AppTester use longer timeouts and retry failed tests

Configure:
{
  "playwright": {
    "timeout": 30000,
    "retries": 2,
    "waitForNetworkIdle": true
  }
}

Agent Token Usage Too High

Problem: Expensive operations

Solution:

# Optimize prompts
❌ "Analyze entire codebase"
✅ "Analyze UserService.ts for security issues"

# Use project-info.md
- Reduces repeated explanations
- Provides context efficiently

Best Practices Summary

Do's ✅

• Provide specific, clear instructions
• Include relevant context and files
• Use project-info.md for conventions
• Review AI suggestions before applying
• Iterate incrementally
• Test after changes
• Document decisions

Don'ts ❌

• Don't give vague instructions
• Don't skip testing
• Don't accept changes blindly
• Don't overload single prompt
• Don't ignore errors
• Don't forget to save work
• Don't skip documentation

Resources

Learning Path

1. Start with @Coder for simple tasks
2. Add @AppTester for quality assurance
3. Explore @Architect for design
4. Create custom agents for workflows
5. Integrate MCP for external systems

Example Projects

• Calculator app (basic generation)
• Quiz game (iterative development)
• E-commerce site (full-stack)
• Task flow designer (domain-specific)
• Blog platform (content management)

Community

• theia IDE Discord
• GitHub discussions
• Eclipse Source blog
• YouTube tutorials
• Stack Overflow

Summary

Effective workflows with theia AI:

1. Start simple - Basic code generation
2. Add testing - Automated quality checks
3. Integrate systems - GitHub, databases, APIs
4. Custom agents - Domain-specific automation
5. Multi-agent - Complex orchestration

Key principles:

• Clear communication with agents
• Incremental progress over big changes
• Verification of all changes
• Context provision for better results
• Continuous improvement of workflows

With practice, these patterns become second nature and dramatically accelerate development while maintaining high quality.