Integration of AI Personas with GitHub Issue Types and Development Workflow
This document defines how Roo AI personas map to the GitHub issue types established in doc/ways-of-working.md, providing clear guidance on persona selection, workflow stages, and handoff protocols.
| Issue Type | Icon | Primary Persona | Secondary Personas | Rationale |
|---|---|---|---|---|
| Tracking Issue | 📍 | 🪃 Orchestrator | 🏗️ Architect | Coordinates multiple sub-issues, delegates work, manages dependencies |
| Enhancement | ✨ | 🏗️ Architect → 💻 Code | ❓ Ask, 🪲 Debug | Requires planning before implementation; may need debugging |
| Chore | 🛠️ | 💻 Code | 🏗️ Architect, 🪲 Debug | Direct technical work; complex chores may need architecture planning |
| Bug | 🐛 | 🪲 Debug → 💻 Code | ❓ Ask | Investigation first, then fix; may need codebase understanding |
| Discussion | 🔍 | 🏗️ Architect | ❓ Ask, 🪃 Orchestrator | Strategic planning and design; may need research or coordination |
Why Orchestrator?
When to use:
Workflow:
Orchestrator creates tracking issue
↓
Orchestrator delegates to Architect for planning sub-issues
↓
Orchestrator delegates to Code for implementation
↓
Orchestrator coordinates reviews and updates tracking issue
Why Architect first?
When to use Architect:
When to transition to Code:
Workflow:
Architect analyzes enhancement requirements
↓
Architect designs solution and creates implementation plan
↓
Architect documents approach in issue or plan file
↓
Code implements according to plan
↓
Debug (if issues arise during implementation)
Why Code primarily?
When to use Architect first:
When to use Code directly:
Workflow (Simple Chore):
Code implements technical task
↓
Code verifies completion
Workflow (Complex Chore):
Architect plans refactoring approach
↓
Code implements changes
↓
Debug (if issues arise)
Why Debug first?
When to use Debug:
When to transition to Code:
When to use Ask:
Workflow:
Debug reproduces and investigates bug
↓
Debug identifies root cause
↓
Debug documents findings in issue
↓
Code implements fix
↓
Debug verifies fix (optional)
Why Architect?
When to use Architect:
When to use Ask:
Workflow:
Ask researches current state (optional)
↓
Architect proposes solution with alternatives
↓
Architect documents impact and trade-offs
↓
Community provides feedback
↓
Architect refines proposal
stateDiagram-v2
[*] --> IssueCreated
IssueCreated --> Planning
Planning --> Implementation
Implementation --> Review
Review --> Documentation
Documentation --> Closed
Review --> Implementation: Changes needed
Implementation --> Debugging: Issues found
Debugging --> Implementation: Fix ready
note right of Planning
Orchestrator, Architect, Ask
end note
note right of Implementation
Code
end note
note right of Debugging
Debug, Ask
end note
note right of Review
Ask, Architect
end note
note right of Documentation
Ask, Code
end note
Personas: 🪃 Orchestrator, 🏗️ Architect, ❓ Ask
Activities:
Outputs:
Persona Selection:
Persona: 💻 Code
Activities:
Outputs:
When to stay in Code:
When to switch:
Persona: 🪲 Debug
Activities:
Outputs:
When to enter:
When to exit:
Personas: ❓ Ask, 🏗️ Architect
Activities:
Outputs:
Persona Selection:
Personas: ❓ Ask, 💻 Code
Activities:
Outputs:
Persona Selection:
When:
Handoff Information:
Example:
Orchestrator: "I've created tracking issue #123 for the device discovery feature.
Please use Architect mode to design the approach for enhancement #124
(Zeroconf discovery) considering the existing discovery API."
When:
Handoff Information:
Example:
Architect: "Design complete for enhancement #124. See plans/discovery-implementation.md
for the implementation approach. Please use Code mode to implement the ZeroconfDiscovery
struct in src/discovery/zeroconf_impl.rs following the plan."
When:
Handoff Information:
Example:
Code: "Implementation of #124 is failing integration tests with a connection timeout.
Please use Debug mode to investigate why the Zeroconf service discovery is timing out
in tests/discovery_tests.rs."
When:
Handoff Information:
Example:
Debug: "Root cause identified: Zeroconf service wasn't being properly initialized
in test harness. Fix needed in tests/harness/server.rs to call start_service()
before running discovery tests. Please use Code mode to implement the fix."
When:
Handoff Information:
Example:
Code: "Before implementing #124, I need to understand the existing discovery API.
Please use Ask mode to explain how src/discovery/api.rs works and how the
DiscoveryStrategy trait is intended to be used."
When:
Handoff Information:
Example:
Ask: "I've analyzed the discovery API. The DiscoveryStrategy trait provides
a clean extension point. Please use Architect mode to design how Zeroconf
discovery will implement this trait for enhancement #124."
graph TD
A[New Task] --> B{What type of work?}
B -->|Multiple related tasks| C[🪃 Orchestrator]
B -->|Single task| D{What is the goal?}
D -->|New feature| E{Is design needed?}
E -->|Yes - complex feature| F[🏗️ Architect]
E -->|No - clear implementation| G[💻 Code]
D -->|Fix a bug| H{Is cause known?}
H -->|No - needs investigation| I[🪲 Debug]
H -->|Yes - ready to fix| G
D -->|Refactor/maintenance| J{Is it complex?}
J -->|Yes - architectural impact| F
J -->|No - straightforward| G
D -->|Understand codebase| K[❓ Ask]
D -->|Design/propose changes| F
C --> L[Create tracking issue<br/>Delegate to other personas]
F --> M[Create plan<br/>Then switch to Code]
G --> N[Implement directly]
I --> O[Investigate<br/>Then switch to Code]
K --> P[Research and explain]
graph TD
A[New Feature Idea] --> B{Is it part of a larger epic?}
B -->|Yes| C[🪃 Orchestrator]
B -->|No| D{How complex is it?}
C --> E[Create tracking issue<br/>Break into enhancements]
D -->|Simple - clear implementation| F[💻 Code]
D -->|Complex - needs design| G[🏗️ Architect]
D -->|Unsure - need to understand| H[❓ Ask]
F --> I[Create enhancement issue<br/>Implement directly]
G --> J[Create enhancement issue<br/>Design solution]
J --> K[Document plan]
K --> L[Switch to Code]
H --> M[Research existing code]
M --> N{Now clear?}
N -->|Yes - simple| F
N -->|Yes - complex| G
graph TD
A[Bug Found] --> B{Can you reproduce it?}
B -->|No| C[🪲 Debug]
B -->|Yes| D{Do you know the cause?}
C --> E[Investigate and reproduce]
E --> F{Cause identified?}
F -->|Yes| G[💻 Code]
F -->|No - need help| H[❓ Ask]
D -->|No| C
D -->|Yes| I{Is fix straightforward?}
I -->|Yes| G
I -->|No - architectural issue| J[🏗️ Architect]
H --> K[Research error/codebase]
K --> C
J --> L[Design fix approach]
L --> G
G --> M[Implement fix]
graph TD
A[Refactoring Needed] --> B{What is the scope?}
B -->|Single function/module| C[💻 Code]
B -->|Multiple modules| D[🏗️ Architect]
B -->|Entire subsystem| E{Part of larger effort?}
E -->|Yes| F[🪃 Orchestrator]
E -->|No| D
C --> G[Create chore issue<br/>Refactor directly]
D --> H[Create chore issue<br/>Plan refactoring approach]
H --> I[Document changes]
I --> J[Switch to Code]
F --> K[Create tracking issue<br/>Break into chores]
K --> D
graph TD
A[Need Understanding] --> B{What is the purpose?}
B -->|Just learning| C[❓ Ask]
B -->|To implement feature| D[❓ Ask → 🏗️ Architect]
B -->|To fix bug| E[❓ Ask → 🪲 Debug]
B -->|To refactor| F[❓ Ask → 🏗️ Architect]
C --> G[Explore and explain code]
D --> H[Research existing patterns]
H --> I[Design new feature]
E --> J[Understand bug context]
J --> K[Investigate bug]
F --> L[Analyze current structure]
L --> M[Plan refactoring]
Stay in 💻 Code when:
Stay in 🪲 Debug when:
Stay in 🏗️ Architect when:
Stay in ❓ Ask when:
Stay in 🪃 Orchestrator when:
Switch from Architect to Code when:
Switch from Code to Debug when:
Switch from Debug to Code when:
Switch to Ask when:
Switch to Orchestrator when:
For Enhancements:
1. Create enhancement issue with clear goal
2. Use Architect to design solution
3. Document plan in issue or separate file
4. Switch to Code for implementation
For Tracking Issues:
1. Create tracking issue with high-level goals
2. Use Orchestrator to break down into sub-issues
3. Delegate each sub-issue to appropriate persona
4. Track progress and coordinate handoffs
Best Practices:
Best Practices:
Best Practices:
Problem:
User: "Implement Zeroconf discovery"
→ Immediately uses Code mode
→ Implementation is incomplete or wrong
→ Requires significant rework
Solution:
User: "Implement Zeroconf discovery"
→ Uses Architect to design approach
→ Creates implementation plan
→ Switches to Code with clear direction
→ Implementation is correct first time
Problem:
Debug identifies root cause
→ Continues investigating related issues
→ Spends time on tangential problems
→ Original fix is delayed
Solution:
Debug identifies root cause
→ Documents findings
→ Switches to Code to implement fix
→ Creates separate issues for related problems
Problem:
User: "Should we use trait objects or generics?"
→ Uses Code mode
→ Gets implementation-focused answer
→ Misses architectural trade-offs
Solution:
User: "Should we use trait objects or generics?"
→ Uses Architect mode
→ Gets analysis of trade-offs
→ Makes informed decision
→ Switches to Code for implementation
Problem:
User: "Implement device discovery system"
→ Uses Architect to plan everything
→ Creates massive plan
→ Implementation is overwhelming
Solution:
User: "Implement device discovery system"
→ Uses Orchestrator to break down
→ Creates tracking issue with sub-issues
→ Delegates each sub-issue appropriately
→ Manages progress incrementally
Problem:
User encounters unfamiliar code
→ Uses Code to modify it anyway
→ Breaks existing functionality
→ Requires debugging and fixes
Solution:
User encounters unfamiliar code
→ Uses Ask to understand it first
→ Learns patterns and constraints
→ Switches to Code with understanding
→ Implementation respects existing design
Issue: #124 ✨ Enhancement: Implement Zeroconf Discovery
Scenario: Add Zeroconf/mDNS service discovery to the discovery API.
User: "I need to implement Zeroconf discovery for issue #124.
The enhancement requires implementing the DiscoveryStrategy trait."
Architect:
1. Analyzes existing discovery API in src/discovery/api.rs
2. Reviews DiscoveryStrategy trait requirements
3. Researches Zeroconf/mDNS libraries (mdns-sd crate)
4. Designs ZeroconfDiscovery implementation
5. Creates plans/discovery-implementation.md with:
- Architecture overview
- Implementation steps
- Testing strategy
- Dependencies to add
6. Updates issue #124 with implementation plan
User: "Please implement the Zeroconf discovery according to the plan."
Code:
1. Adds mdns-sd dependency to Cargo.toml
2. Creates src/discovery/zeroconf_impl.rs
3. Implements ZeroconfDiscovery struct
4. Implements DiscoveryStrategy trait
5. Adds unit tests
6. Updates src/discovery/mod.rs to export new module
7. Commits changes
User: "Integration tests are failing with timeout errors."
Debug:
1. Reproduces test failure in tests/discovery_tests.rs
2. Adds diagnostic logging to ZeroconfDiscovery
3. Identifies issue: test harness not starting mDNS service
4. Documents root cause in issue #124
5. Recommends fix: update test harness initialization
User: "Please implement the fix identified by Debug."
Code:
1. Updates tests/harness/server.rs
2. Adds mDNS service initialization
3. Verifies tests now pass
4. Commits fix
User: "Please document the Zeroconf discovery feature."
Ask:
1. Adds documentation to src/discovery/zeroconf_impl.rs
2. Creates example in examples/zeroconf_discovery.rs
3. Updates README.md with Zeroconf feature
4. Updates CHANGES.md
5. Closes issue #124
Issue: #145 🐛 Bug: Connection timeout in discovery tests
Scenario: Tests intermittently fail with connection timeouts.
User: "Tests are failing intermittently with timeouts. See issue #145."
Debug:
1. Reproduces failure by running tests multiple times
2. Analyzes test logs and error messages
3. Adds diagnostic logging to discovery code
4. Identifies race condition in service initialization
5. Documents findings:
- Service starts asynchronously
- Tests don't wait for service to be ready
- Timeout occurs when test runs before service is ready
6. Recommends fix: add health check before running tests
User: "Please implement the fix for the race condition."
Code:
1. Adds health_check() method to test harness
2. Updates test setup to wait for service ready
3. Adds retry logic with exponential backoff
4. Verifies tests pass consistently (runs 100 times)
5. Commits fix
6. Closes issue #145
Issue: #156 🛠️ Chore: Refactor discovery API for better extensibility
Scenario: Current discovery API is difficult to extend with new strategies.
User: "The discovery API needs refactoring. See issue #156."
Architect:
1. Analyzes current API in src/discovery/api.rs
2. Identifies pain points:
- Tight coupling between strategies
- Difficult to add new discovery methods
- No clear lifecycle management
3. Designs improved architecture:
- Builder pattern for configuration
- Lifecycle hooks for strategies
- Better error handling
4. Creates plans/discovery-refactoring.md
5. Documents migration path for existing code
6. Updates issue #156 with plan
User: "Please implement the refactoring according to the plan."
Code:
1. Creates new builder module
2. Refactors DiscoveryStrategy trait
3. Updates existing implementations
4. Migrates tests to new API
5. Updates examples
6. Ensures backward compatibility
7. Commits changes incrementally
User: "Please document the refactored API."
Ask:
1. Updates API documentation
2. Creates migration guide
3. Updates examples with new patterns
4. Documents breaking changes in CHANGES.md
5. Closes issue #156
Issue: #100 📍 Tracking: Device Discovery System
Scenario: Implement complete device discovery system with multiple strategies.
User: "I want to implement a complete device discovery system.
This includes Zeroconf, manual configuration, and auto-discovery."
Orchestrator:
1. Creates tracking issue #100
2. Breaks down into sub-issues:
- #101 🔍 Discussion: Discovery API design
- #102 ✨ Enhancement: Core discovery API
- #103 ✨ Enhancement: Zeroconf discovery
- #104 ✨ Enhancement: Manual configuration
- #105 ✨ Enhancement: Auto-discovery
- #106 🛠️ Chore: Integration tests
- #107 🛠️ Chore: Documentation
3. Identifies dependencies:
- #101 must complete before #102
- #102 must complete before #103-105
- #103-105 can be parallel
- #106 requires #103-105
4. Updates tracking issue with task list
5. Delegates #101 to Architect
Orchestrator delegates to Architect for issue #101
Architect:
1. Creates discussion issue #101
2. Proposes discovery API design
3. Documents alternatives considered
4. Gathers feedback
5. Finalizes design
6. Closes #101
7. Reports back to Orchestrator
Orchestrator delegates to Architect for issue #102
Architect:
1. Designs core discovery API based on #101
2. Creates implementation plan
3. Switches to Code
Code:
1. Implements core API
2. Adds tests
3. Closes #102
4. Reports back to Orchestrator
Orchestrator delegates #103, #104, #105 in parallel
For each enhancement:
Architect designs approach
→ Code implements
→ Debug fixes issues (if needed)
→ Closes issue
→ Reports to Orchestrator
Orchestrator tracks progress and manages dependencies
Orchestrator delegates #106 to Code
Orchestrator delegates #107 to Ask
Code: Implements integration tests
Ask: Creates comprehensive documentation
Both report completion to Orchestrator
Orchestrator closes tracking issue #100
Issue: #178 🔍 Discussion: Should we support JSON protocol?
Scenario: Proposal to add JSON protocol support alongside XML.
User: "I want to understand if we should support JSON protocol.
What does the current protocol implementation look like?"
Ask:
1. Explains current XML protocol in src/protocol.rs
2. Shows how protocol is used in client/server
3. Identifies extension points
4. Researches JSON protocol specifications
5. Provides summary of current state
User: "Based on that research, please create a proposal for JSON support."
Architect:
1. Creates discussion issue #178
2. Proposes JSON protocol implementation:
- Protocol negotiation mechanism
- JSON message format
- Backward compatibility approach
3. Documents alternatives:
- JSON-only (breaking change)
- Dual protocol support (proposed)
- Plugin architecture
4. Analyzes impact:
- Performance implications
- Compatibility considerations
- Implementation complexity
5. Recommends dual protocol approach
6. Gathers community feedback
Community provides feedback on #178
Architect:
1. Addresses feedback
2. Refines proposal
3. Updates impact analysis
4. Creates implementation roadmap
5. Proposal is approved
``` User: “The proposal is approved. Let’s implement it.”
Orchestrator: