[Phase 4] Agent role system with specialized prompts

[frankbria]

Summary

Implement specialized agent roles (Backend, Frontend, Test, Review) with role-specific system prompts and tool access.

Proposed Solution

Agent Roles

• Backend Agent: Python/API focus, database access, server-side logic
• Frontend Agent: React/TypeScript focus, UI components, styling
• Test Agent: Test writing, coverage analysis, test execution
• Review Agent: Code review, quality checks, security scanning

Role Configuration

• Role-specific system prompts
• Tool access restrictions per role
• Automatic task-to-agent matching based on task content

Implementation

• codeframe/core/agent_roles.py - Role definitions and prompts
• codeframe/core/agent.py - Role-aware execution
• Task metadata for role hints

Acceptance Criteria

• 4+ specialized agent roles defined
• Each role has tailored system prompt
• Automatic role selection from task content
• Role can be overridden via CLI flag

Related

• [Phase 4] Evaluate Subagent Context Isolation per Task #68: Subagent context isolation
• [Phase 4] Evaluate Task-Scoped Context vs. Agent-Level Context Tiers #72: Task-scoped vs agent-level context
• Prerequisite for multi-agent parallel execution

[traycerai]

Plan

Observations

The codebase already has a solid foundation for specialized agents with BackendWorkerAgent, FrontendWorkerAgent, TestWorkerAgent, and ReviewWorkerAgent classes. Each has basic system prompts via _build_system_prompt() methods. There's a SimpleAgentAssigner for keyword-based task-to-agent matching, and an AgentFactory that loads from YAML definitions (though no YAML files exist yet). The CLI has extensive work commands but lacks a role override flag. The core Agent orchestrator in file:codeframe/core/agent.py handles execution but doesn't have role-specific behavior.

Approach

The implementation will create a centralized role system in file:codeframe/core/agent_roles.py that defines specialized prompts, capabilities, and tool restrictions for each agent role. This will enhance the existing worker agents by providing richer, role-specific system prompts while maintaining backward compatibility. The SimpleAgentAssigner already provides automatic task-to-agent matching, so we'll integrate it with the new role system. A CLI flag --role will be added to codeframe work start to allow manual role override. The approach leverages existing infrastructure (AgentFactory, worker agents, SimpleAgentAssigner) rather than rebuilding from scratch.

Implementation Steps

1. Create Agent Role System (file:codeframe/core/agent_roles.py)

Define a comprehensive role system with:

Role Enumeration:

• Create AgentRole enum with values: BACKEND, FRONTEND, TEST, REVIEW
• Each role maps to existing worker agent types

Role Definitions:

• Create RoleDefinition dataclass containing:
  • name: Role identifier
  • display_name: Human-readable name
  • system_prompt: Comprehensive role-specific prompt
  • capabilities: List of role capabilities
  • tool_restrictions: Optional list of allowed/denied tools
  • focus_areas: List of technical focus areas
  • keywords: Keywords for automatic assignment (integrate with SimpleAgentAssigner)

Specialized System Prompts:

For Backend Agent:

• Focus: Python/FastAPI, database design, API development, server-side logic
• Capabilities: RESTful APIs, GraphQL, database migrations, ORM usage, authentication/authorization
• Tool access: Database tools, API testing tools, migration tools
• Prompt emphasizes: Clean architecture, SOLID principles, async/await patterns, error handling, security best practices

For Frontend Agent:

• Focus: React/TypeScript, UI components, responsive design, accessibility
• Capabilities: Component architecture, state management, CSS/Tailwind, form handling, client-side routing
• Tool access: Component generators, style linters, accessibility checkers
• Prompt emphasizes: Component reusability, TypeScript typing, accessibility (WCAG), responsive design, performance optimization

For Test Agent:

• Focus: pytest, test coverage, TDD, integration testing
• Capabilities: Unit tests, integration tests, mocking, fixtures, parametrized tests, coverage analysis
• Tool access: Test runners, coverage tools, mock generators
• Prompt emphasizes: Arrange-Act-Assert pattern, test independence, edge cases, meaningful assertions, test maintainability

For Review Agent:

• Focus: Code quality, security scanning, complexity analysis, best practices
• Capabilities: Static analysis, security patterns (OWASP), complexity metrics, style enforcement
• Tool access: Linters, security scanners, complexity analyzers
• Prompt emphasizes: Security vulnerabilities, code smells, performance issues, maintainability, documentation quality

Helper Functions:

• get_role_definition(role: AgentRole) -> RoleDefinition: Retrieve role configuration
• get_role_by_name(name: str) -> AgentRole: Parse role from string
• get_role_for_task(task: dict) -> AgentRole: Automatic role selection using SimpleAgentAssigner keywords
• get_all_roles() -> List[RoleDefinition]: List all available roles

2. Enhance Worker Agent System Prompts

Update each worker agent to use the new role system:

Modify file:codeframe/agents/backend_worker_agent.py:

• Import get_role_definition, AgentRole from agent_roles
• Update _build_system_prompt() to call get_role_definition(AgentRole.BACKEND).system_prompt
• Add role metadata to agent instance for introspection

Modify file:codeframe/agents/frontend_worker_agent.py:

• Import role system
• Update _build_system_prompt() to use AgentRole.FRONTEND definition
• Preserve existing Tailwind/React-specific guidance

Modify file:codeframe/agents/test_worker_agent.py:

• Import role system
• Update _build_system_prompt() to use AgentRole.TEST definition
• Maintain pytest-specific conventions

Modify file:codeframe/agents/review_worker_agent.py:

• Import role system
• Update _build_system_prompt() to use AgentRole.REVIEW definition
• Keep existing scoring thresholds and quality metrics

3. Integrate Role System with Task Assignment

Enhance file:codeframe/agents/simple_assignment.py:

• Import AgentRole and role definitions
• Add method assign_agent_role(task: dict) -> AgentRole that returns role enum instead of string
• Map existing keyword patterns to AgentRole enum values
• Maintain backward compatibility with assign_agent_type() for string-based assignment
• Add get_role_explanation(task: dict, role: AgentRole) -> str for debugging

Update file:codeframe/agents/factory.py:

• Add method create_agent_by_role(role: AgentRole, agent_id: str, **kwargs) -> WorkerAgent
• Map AgentRole enum to concrete worker agent classes
• Inject role-specific system prompt from role definitions
• Preserve existing YAML-based factory methods

4. Add CLI Role Override Flag

Modify file:codeframe/cli/app.py - work_start command:

Add new option parameter:

role: Optional[str] = typer.Option(
    None,
    "--role",
    "-r",
    help="Override agent role (backend, frontend, test, review)"
)

Implementation logic:

• Parse role string to AgentRole enum using get_role_by_name()
• If role provided, use it to select agent type instead of automatic assignment
• Pass role to runtime.execute_agent() via new parameter
• Display selected role in console output
• Validate role string and show helpful error if invalid

Update file:codeframe/core/runtime.py - execute_agent function:

• Add optional role: Optional[AgentRole] = None parameter
• If role provided, use it to determine agent type
• Otherwise, use automatic assignment via SimpleAgentAssigner
• Pass role information to Agent constructor for context

5. Implement Tool Access Restrictions (Optional Enhancement)

Create file:codeframe/core/tool_registry.py:

• Define available tools/capabilities per role
• Backend: database_query, api_call, migration_runner
• Frontend: component_generator, style_validator, accessibility_checker
• Test: test_runner, coverage_analyzer, mock_generator
• Review: linter, security_scanner, complexity_analyzer

Add tool validation in file:codeframe/core/agent.py:

• Check tool access before execution based on agent role
• Log warning if agent attempts to use restricted tool
• Optionally block or allow with warning based on configuration

6. Update Documentation and Tests

Create file:docs/AGENT_ROLES.md:

• Document each role's purpose, capabilities, and focus areas
• Provide examples of tasks suited for each role
• Explain automatic assignment algorithm
• Show CLI usage examples with --role flag

Add tests in file:tests/core/test_agent_roles.py:

• Test role definition retrieval
• Test automatic role assignment for various task types
• Test role override via CLI parameter
• Test system prompt generation for each role

Add tests in file:tests/cli/test_work_commands.py:

• Test work start with --role flag
• Test invalid role handling
• Test role override vs automatic assignment

Update file:tests/agents/test_simple_assignment.py:

• Test integration with new role system
• Verify keyword matching produces correct roles

7. Integration Points

Sequence of role selection:

sequenceDiagram
    participant CLI as CLI (work start)
    participant Runtime as Runtime
    participant RoleSystem as AgentRoles
    participant Assigner as SimpleAgentAssigner
    participant Factory as AgentFactory
    participant Agent as Worker Agent

    CLI->>Runtime: execute_agent(task, role=override)
    alt Role Override Provided
        Runtime->>RoleSystem: get_role_definition(override)
        RoleSystem-->>Runtime: RoleDefinition
    else Automatic Assignment
        Runtime->>Assigner: assign_agent_role(task)
        Assigner->>RoleSystem: match keywords to role
        RoleSystem-->>Assigner: AgentRole
        Assigner-->>Runtime: AgentRole
        Runtime->>RoleSystem: get_role_definition(role)
        RoleSystem-->>Runtime: RoleDefinition
    end
    Runtime->>Factory: create_agent_by_role(role, agent_id)
    Factory->>RoleSystem: get_role_definition(role)
    RoleSystem-->>Factory: system_prompt, capabilities
    Factory->>Agent: __init__(system_prompt=...)
    Agent-->>Factory: agent instance
    Factory-->>Runtime: agent
    Runtime->>Agent: run(task_id)

Loading

File modification summary:

• New: file:codeframe/core/agent_roles.py (role definitions)
• New: file:codeframe/core/tool_registry.py (optional)
• New: file:docs/AGENT_ROLES.md (documentation)
• New: file:tests/core/test_agent_roles.py (tests)
• Modified: file:codeframe/agents/backend_worker_agent.py (use role prompts)
• Modified: file:codeframe/agents/frontend_worker_agent.py (use role prompts)
• Modified: file:codeframe/agents/test_worker_agent.py (use role prompts)
• Modified: file:codeframe/agents/review_worker_agent.py (use role prompts)
• Modified: file:codeframe/agents/simple_assignment.py (role enum integration)
• Modified: file:codeframe/agents/factory.py (role-based creation)
• Modified: file:codeframe/cli/app.py (add --role flag)
• Modified: file:codeframe/core/runtime.py (role parameter)
• Modified: file:tests/agents/test_simple_assignment.py (role tests)
• Modified: file:tests/cli/test_work_commands.py (CLI tests)

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase already has a solid foundation for specialized agents with BackendWorkerAgent, FrontendWorkerAgent, TestWorkerAgent, and ReviewWorkerAgent classes. Each has basic system prompts via `_build_system_prompt()` methods. There's a SimpleAgentAssigner for keyword-based task-to-agent matching, and an AgentFactory that loads from YAML definitions (though no YAML files exist yet). The CLI has extensive work commands but lacks a role override flag. The core Agent orchestrator in `file:codeframe/core/agent.py` handles execution but doesn't have role-specific behavior.

## Approach

The implementation will create a centralized role system in `file:codeframe/core/agent_roles.py` that defines specialized prompts, capabilities, and tool restrictions for each agent role. This will enhance the existing worker agents by providing richer, role-specific system prompts while maintaining backward compatibility. The SimpleAgentAssigner already provides automatic task-to-agent matching, so we'll integrate it with the new role system. A CLI flag `--role` will be added to `codeframe work start` to allow manual role override. The approach leverages existing infrastructure (AgentFactory, worker agents, SimpleAgentAssigner) rather than rebuilding from scratch.

## Implementation Steps

### 1. Create Agent Role System (`file:codeframe/core/agent_roles.py`)

Define a comprehensive role system with:

**Role Enumeration:**
- Create `AgentRole` enum with values: BACKEND, FRONTEND, TEST, REVIEW
- Each role maps to existing worker agent types

**Role Definitions:**
- Create `RoleDefinition` dataclass containing:
  - `name`: Role identifier
  - `display_name`: Human-readable name
  - `system_prompt`: Comprehensive role-specific prompt
  - `capabilities`: List of role capabilities
  - `tool_restrictions`: Optional list of allowed/denied tools
  - `focus_areas`: List of technical focus areas
  - `keywords`: Keywords for automatic assignment (integrate with SimpleAgentAssigner)

**Specialized System Prompts:**

For **Backend Agent**:
- Focus: Python/FastAPI, database design, API development, server-side logic
- Capabilities: RESTful APIs, GraphQL, database migrations, ORM usage, authentication/authorization
- Tool access: Database tools, API testing tools, migration tools
- Prompt emphasizes: Clean architecture, SOLID principles, async/await patterns, error handling, security best practices

For **Frontend Agent**:
- Focus: React/TypeScript, UI components, responsive design, accessibility
- Capabilities: Component architecture, state management, CSS/Tailwind, form handling, client-side routing
- Tool access: Component generators, style linters, accessibility checkers
- Prompt emphasizes: Component reusability, TypeScript typing, accessibility (WCAG), responsive design, performance optimization

For **Test Agent**:
- Focus: pytest, test coverage, TDD, integration testing
- Capabilities: Unit tests, integration tests, mocking, fixtures, parametrized tests, coverage analysis
- Tool access: Test runners, coverage tools, mock generators
- Prompt emphasizes: Arrange-Act-Assert pattern, test independence, edge cases, meaningful assertions, test maintainability

For **Review Agent**:
- Focus: Code quality, security scanning, complexity analysis, best practices
- Capabilities: Static analysis, security patterns (OWASP), complexity metrics, style enforcement
- Tool access: Linters, security scanners, complexity analyzers
- Prompt emphasizes: Security vulnerabilities, code smells, performance issues, maintainability, documentation quality

**Helper Functions:**
- `get_role_definition(role: AgentRole) -> RoleDefinition`: Retrieve role configuration
- `get_role_by_name(name: str) -> AgentRole`: Parse role from string
- `get_role_for_task(task: dict) -> AgentRole`: Automatic role selection using SimpleAgentAssigner keywords
- `get_all_roles() -> List[RoleDefinition]`: List all available roles

### 2. Enhance Worker Agent System Prompts

Update each worker agent to use the new role system:

**Modify `file:codeframe/agents/backend_worker_agent.py`:**
- Import `get_role_definition, AgentRole` from `agent_roles`
- Update `_build_system_prompt()` to call `get_role_definition(AgentRole.BACKEND).system_prompt`
- Add role metadata to agent instance for introspection

**Modify `file:codeframe/agents/frontend_worker_agent.py`:**
- Import role system
- Update `_build_system_prompt()` to use `AgentRole.FRONTEND` definition
- Preserve existing Tailwind/React-specific guidance

**Modify `file:codeframe/agents/test_worker_agent.py`:**
- Import role system
- Update `_build_system_prompt()` to use `AgentRole.TEST` definition
- Maintain pytest-specific conventions

**Modify `file:codeframe/agents/review_worker_agent.py`:**
- Import role system
- Update `_build_system_prompt()` to use `AgentRole.REVIEW` definition
- Keep existing scoring thresholds and quality metrics

### 3. Integrate Role System with Task Assignment

**Enhance `file:codeframe/agents/simple_assignment.py`:**
- Import `AgentRole` and role definitions
- Add method `assign_agent_role(task: dict) -> AgentRole` that returns role enum instead of string
- Map existing keyword patterns to `AgentRole` enum values
- Maintain backward compatibility with `assign_agent_type()` for string-based assignment
- Add `get_role_explanation(task: dict, role: AgentRole) -> str` for debugging

**Update `file:codeframe/agents/factory.py`:**
- Add method `create_agent_by_role(role: AgentRole, agent_id: str, **kwargs) -> WorkerAgent`
- Map `AgentRole` enum to concrete worker agent classes
- Inject role-specific system prompt from role definitions
- Preserve existing YAML-based factory methods

### 4. Add CLI Role Override Flag

**Modify `file:codeframe/cli/app.py` - `work_start` command:**

Add new option parameter:
```python
role: Optional[str] = typer.Option(
    None,
    "--role",
    "-r",
    help="Override agent role (backend, frontend, test, review)"
)
```

**Implementation logic:**
- Parse role string to `AgentRole` enum using `get_role_by_name()`
- If role provided, use it to select agent type instead of automatic assignment
- Pass role to `runtime.execute_agent()` via new parameter
- Display selected role in console output
- Validate role string and show helpful error if invalid

**Update `file:codeframe/core/runtime.py` - `execute_agent` function:**
- Add optional `role: Optional[AgentRole] = None` parameter
- If role provided, use it to determine agent type
- Otherwise, use automatic assignment via SimpleAgentAssigner
- Pass role information to Agent constructor for context

### 5. Implement Tool Access Restrictions (Optional Enhancement)

**Create `file:codeframe/core/tool_registry.py`:**
- Define available tools/capabilities per role
- Backend: database_query, api_call, migration_runner
- Frontend: component_generator, style_validator, accessibility_checker
- Test: test_runner, coverage_analyzer, mock_generator
- Review: linter, security_scanner, complexity_analyzer

**Add tool validation in `file:codeframe/core/agent.py`:**
- Check tool access before execution based on agent role
- Log warning if agent attempts to use restricted tool
- Optionally block or allow with warning based on configuration

### 6. Update Documentation and Tests

**Create `file:docs/AGENT_ROLES.md`:**
- Document each role's purpose, capabilities, and focus areas
- Provide examples of tasks suited for each role
- Explain automatic assignment algorithm
- Show CLI usage examples with `--role` flag

**Add tests in `file:tests/core/test_agent_roles.py`:**
- Test role definition retrieval
- Test automatic role assignment for various task types
- Test role override via CLI parameter
- Test system prompt generation for each role

**Add tests in `file:tests/cli/test_work_commands.py`:**
- Test `work start` with `--role` flag
- Test invalid role handling
- Test role override vs automatic assignment

**Update `file:tests/agents/test_simple_assignment.py`:**
- Test integration with new role system
- Verify keyword matching produces correct roles

### 7. Integration Points

**Sequence of role selection:**

```mermaid
sequenceDiagram
    participant CLI as CLI (work start)
    participant Runtime as Runtime
    participant RoleSystem as AgentRoles
    participant Assigner as SimpleAgentAssigner
    participant Factory as AgentFactory
    participant Agent as Worker Agent

    CLI->>Runtime: execute_agent(task, role=override)
    alt Role Override Provided
        Runtime->>RoleSystem: get_role_definition(override)
        RoleSystem-->>Runtime: RoleDefinition
    else Automatic Assignment
        Runtime->>Assigner: assign_agent_role(task)
        Assigner->>RoleSystem: match keywords to role
        RoleSystem-->>Assigner: AgentRole
        Assigner-->>Runtime: AgentRole
        Runtime->>RoleSystem: get_role_definition(role)
        RoleSystem-->>Runtime: RoleDefinition
    end
    Runtime->>Factory: create_agent_by_role(role, agent_id)
    Factory->>RoleSystem: get_role_definition(role)
    RoleSystem-->>Factory: system_prompt, capabilities
    Factory->>Agent: __init__(system_prompt=...)
    Agent-->>Factory: agent instance
    Factory-->>Runtime: agent
    Runtime->>Agent: run(task_id)
```

**File modification summary:**
- New: `file:codeframe/core/agent_roles.py` (role definitions)
- New: `file:codeframe/core/tool_registry.py` (optional)
- New: `file:docs/AGENT_ROLES.md` (documentation)
- New: `file:tests/core/test_agent_roles.py` (tests)
- Modified: `file:codeframe/agents/backend_worker_agent.py` (use role prompts)
- Modified: `file:codeframe/agents/frontend_worker_agent.py` (use role prompts)
- Modified: `file:codeframe/agents/test_worker_agent.py` (use role prompts)
- Modified: `file:codeframe/agents/review_worker_agent.py` (use role prompts)
- Modified: `file:codeframe/agents/simple_assignment.py` (role enum integration)
- Modified: `file:codeframe/agents/factory.py` (role-based creation)
- Modified: `file:codeframe/cli/app.py` (add --role flag)
- Modified: `file:codeframe/core/runtime.py` (role parameter)
- Modified: `file:tests/agents/test_simple_assignment.py` (role tests)
- Modified: `file:tests/cli/test_work_commands.py` (CLI tests)

---

Execution Information

Branch: main
Commit: e768c1d

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#37 - feat: Multi-agent per project architecture (Phases 1-5) [merged]
#125 - Implement WorkerAgent execute_task method [merged]
#151 - Integrate QualityTracker with workflow system [merged]
#152 - Implement agent maturity level system [merged]
#246 - feat(agents): trigger multi-agent execution after task approval [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!