Skip to content
3 changes: 3 additions & 0 deletions gateway/agent_restrictions.py
Original file line number Diff line number Diff line change
Expand Up @@ -42,11 +42,14 @@ class AgentRole:
ARCHITECT = "architect"
TASK_PLANNER = "task_planner"
RISK_ANALYST = "risk_analyst"
# Refine-phase roles
REFINER = "refiner"
# Reviewer roles
REVIEWER_UNIFIED = "reviewer_unified"
REVIEWER_CODE = "reviewer_code"
REVIEWER_CONTRACT = "reviewer_contract"
REVIEWER_AGENT_DESIGN = "reviewer_agent_design"
REVIEWER_REFINE = "reviewer_refine"


@dataclass
Expand Down
63 changes: 61 additions & 2 deletions integration_tests/sdlc/test_multi_agent_orchestration.py
Original file line number Diff line number Diff line change
Expand Up @@ -35,14 +35,15 @@ class TestDependencyGraph:
def test_build_graph_all_roles(self):
"""Build graph includes all agent roles."""
graph = build_dependency_graph()
assert len(graph.nodes) == 11
assert len(graph.nodes) == 13
assert AgentRole.CODER in graph.nodes
assert AgentRole.TESTER in graph.nodes
assert AgentRole.DOCUMENTER in graph.nodes
assert AgentRole.INTEGRATOR in graph.nodes
assert AgentRole.ARCHITECT in graph.nodes
assert AgentRole.TASK_PLANNER in graph.nodes
assert AgentRole.RISK_ANALYST in graph.nodes
assert AgentRole.REFINER in graph.nodes

def test_build_graph_implement_roles(self):
"""Build graph with implement-phase roles only."""
Expand Down Expand Up @@ -544,6 +545,63 @@ def test_get_roles_with_reviewers(self):
assert AgentRole.REVIEWER_CODE in roles


class TestRefinePhaseRoles:
"""Tests for refine-phase agent roles."""

def test_get_roles_for_refine_phase(self):
"""Get roles for refine phase returns refiner."""
from egg_contracts.agent_roles import get_roles_for_phase

roles = get_roles_for_phase("refine")
assert len(roles) == 1
assert AgentRole.REFINER in roles

def test_get_refine_roles_with_reviewers(self):
"""Get refine roles with reviewers included."""
from egg_contracts.agent_roles import get_roles_for_phase

roles = get_roles_for_phase("refine", include_reviewers=True)
assert len(roles) == 3 # 1 refiner + 2 reviewers
assert AgentRole.REFINER in roles
assert AgentRole.REVIEWER_REFINE in roles
assert AgentRole.REVIEWER_AGENT_DESIGN in roles

def test_refine_phase_dependency_graph(self):
"""Refine-phase has simple single-agent dependency structure."""
from egg_contracts.agent_roles import get_roles_for_phase

roles = get_roles_for_phase("refine")
graph = build_dependency_graph(roles)

assert len(graph.nodes) == 1
waves = graph.compute_waves()

# Wave 1: refiner (no dependencies)
assert AgentRole.REFINER in waves[0]

def test_refiner_role_definition(self):
"""Refiner role has correct properties."""
from egg_contracts.agent_roles import get_role_definition

role_def = get_role_definition(AgentRole.REFINER)
assert role_def.role == AgentRole.REFINER
assert role_def.dependencies == []
assert ".egg-state/drafts/" in role_def.file_access.allowed_write
assert role_def.file_access.can_write(".egg-state/drafts/123-analysis.md")
assert not role_def.file_access.can_write("src/main.py")

def test_reviewer_refine_role_definition(self):
"""Reviewer refine role has correct properties."""
from egg_contracts.agent_roles import get_role_definition

role_def = get_role_definition(AgentRole.REVIEWER_REFINE)
assert role_def.role == AgentRole.REVIEWER_REFINE
assert AgentRole.REFINER in role_def.dependencies
assert ".egg-state/reviews/" in role_def.file_access.allowed_write
assert role_def.file_access.can_write(".egg-state/reviews/verdict.json")
assert not role_def.file_access.can_write("src/main.py")


class TestReviewerRoles:
"""Tests for reviewer agent roles."""

Expand Down Expand Up @@ -573,6 +631,7 @@ def test_reviewer_roles_read_only(self):
AgentRole.REVIEWER_CODE,
AgentRole.REVIEWER_CONTRACT,
AgentRole.REVIEWER_AGENT_DESIGN,
AgentRole.REVIEWER_REFINE,
]:
role_def = get_role_definition(role)
# Reviewers can write to reviews and agent-outputs only
Expand Down Expand Up @@ -625,7 +684,7 @@ def test_default_multi_agent_config(self):
config = MultiAgentConfig()
assert config.enabled is True
assert config.parallel_execution is True
assert len(config.roles_enabled) == 11 # All roles
assert len(config.roles_enabled) == 13 # All roles
assert len(config.phase_overrides) == 0

def test_phase_override(self):
Expand Down
3 changes: 3 additions & 0 deletions orchestrator/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -74,11 +74,14 @@ class AgentRole(StrEnum):
ARCHITECT = "architect"
TASK_PLANNER = "task_planner"
RISK_ANALYST = "risk_analyst"
# Refine-phase roles
REFINER = "refiner"
# Reviewer roles (specific subtypes)
REVIEWER_UNIFIED = "reviewer_unified"
REVIEWER_CODE = "reviewer_code"
REVIEWER_CONTRACT = "reviewer_contract"
REVIEWER_AGENT_DESIGN = "reviewer_agent_design"
REVIEWER_REFINE = "reviewer_refine"


class ReviewerType(StrEnum):
Expand Down
54 changes: 51 additions & 3 deletions orchestrator/routes/pipelines.py
Original file line number Diff line number Diff line change
Expand Up @@ -834,6 +834,36 @@ def _get_contract_review_criteria() -> str:



def _get_refine_review_criteria() -> str:
"""Return review criteria for the dedicated refine reviewer."""
return (
"### 1. Problem Understanding\n"
"- Does the analysis correctly identify the core problem or feature request?\n"
"- Is the current behavior (if applicable) accurately described?\n"
"- Are the goals and desired outcomes clear?\n\n"
"### 2. Research Quality\n"
"- Has the agent explored the relevant parts of the codebase?\n"
"- Are existing patterns and conventions identified?\n"
"- Is the technical context accurate and thorough?\n\n"
"### 3. Options Analysis\n"
"- Are the proposed options meaningfully different?\n"
"- Are trade-offs clearly articulated for each option?\n"
"- Is the reasoning logical and well-founded?\n\n"
"### 4. Constraints and Dependencies\n"
"- Are technical constraints identified (performance, compatibility, etc.)?\n"
"- Are dependencies on other code or systems noted?\n"
"- Are potential risks or complications surfaced?\n\n"
"### 5. Open Questions\n"
"- Are open questions specific enough for a human to answer?\n"
"- Do questions address genuine ambiguities?\n"
"- Are questions actionable?\n\n"
"### 6. Recommendation Quality\n"
"- Is there a clear recommended approach?\n"
"- Is the recommendation justified with specific reasons?\n"
"- Does the recommendation align with the analysis findings?\n"
)


def _get_review_criteria_for_type(reviewer_type: str, phase: str) -> str:
"""Dispatch to the correct criteria function based on reviewer type."""
if reviewer_type == "unified":
Expand All @@ -844,6 +874,8 @@ def _get_review_criteria_for_type(reviewer_type: str, phase: str) -> str:
return _get_code_review_criteria()
elif reviewer_type == "contract":
return _get_contract_review_criteria()
elif reviewer_type == "refine":
return _get_refine_review_criteria()
else:
return _get_unified_criteria(phase)

Expand Down Expand Up @@ -871,6 +903,13 @@ def _get_reviewer_scope_preamble(reviewer_type: str, phase: str) -> str:
"matches the contract and all acceptance criteria are met. Do NOT review "
"general code quality or security — other reviewers handle those."
)
elif reviewer_type == "refine":
return (
"This is a **refine phase review**. Focus on the quality and completeness "
"of the analysis produced during the refine phase. Evaluate problem "
"understanding, codebase research, options analysis, and the recommended "
"approach. Agent-mode design alignment is handled by another reviewer."
)
return ""


Expand Down Expand Up @@ -1429,8 +1468,9 @@ def _build_agent_prompt(
Returns:
Complete prompt string for the agent
"""
# CODER uses the existing phase prompt
if role_value == "coder":
# CODER and REFINER use the existing phase prompt (phase-specific
# instructions are already tailored for refine vs implement etc.)
if role_value in ("coder", "refiner"):
return _build_phase_prompt(
phase=phase,
pipeline_id=pipeline_id,
Expand Down Expand Up @@ -2583,11 +2623,19 @@ def _run_pipeline(pipeline_id: str, repo_path: Path) -> None:
phase_prompt,
]

# Use the REFINER role for the refine phase,
# CODER for all other single-agent phases.
single_agent_role = (
AgentRole.REFINER
if current_phase.value == "refine"
else AgentRole.CODER
)

try:
exit_code, container_logs = _spawn_and_wait(
spawner=spawner,
pipeline_id=pipeline_id,
agent_role=AgentRole.CODER,
agent_role=single_agent_role,
issue_number=pipeline.issue_number,
repo_volumes=repo_volumes,
gateway_mode=phase_gateway_mode,
Expand Down
4 changes: 3 additions & 1 deletion orchestrator/tests/test_models.py
Original file line number Diff line number Diff line change
Expand Up @@ -359,11 +359,13 @@ def test_all_roles(self):
assert AgentRole.ARCHITECT in roles
assert AgentRole.TASK_PLANNER in roles
assert AgentRole.RISK_ANALYST in roles
assert AgentRole.REFINER in roles
assert AgentRole.REVIEWER_UNIFIED in roles
assert AgentRole.REVIEWER_CODE in roles
assert AgentRole.REVIEWER_CONTRACT in roles
assert AgentRole.REVIEWER_AGENT_DESIGN in roles
assert len(roles) == 13
assert AgentRole.REVIEWER_REFINE in roles
assert len(roles) == 15


class TestPipelinePhase:
Expand Down
73 changes: 71 additions & 2 deletions shared/egg_contracts/agent_roles.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
- TESTER: Writes tests for the implemented changes
- DOCUMENTER: Updates documentation for the changes
- INTEGRATOR: Runs full test suite and validates integration
- REFINER: Analyzes tasks and produces structured analysis in the refine phase

The orchestrator uses these definitions to:
1. Determine execution order based on dependencies
Expand All @@ -30,7 +31,9 @@ class AgentRole(StrEnum):

Implement-phase roles: CODER, TESTER, DOCUMENTER, INTEGRATOR
Plan-phase roles: ARCHITECT, TASK_PLANNER, RISK_ANALYST
Reviewer roles: REVIEWER_UNIFIED, REVIEWER_CODE, REVIEWER_CONTRACT, REVIEWER_AGENT_DESIGN
Refine-phase roles: REFINER
Reviewer roles: REVIEWER_UNIFIED, REVIEWER_CODE, REVIEWER_CONTRACT,
REVIEWER_AGENT_DESIGN, REVIEWER_REFINE
"""

CODER = "coder"
Expand All @@ -41,11 +44,14 @@ class AgentRole(StrEnum):
ARCHITECT = "architect"
TASK_PLANNER = "task_planner"
RISK_ANALYST = "risk_analyst"
# Refine-phase roles
REFINER = "refiner"
# Reviewer roles
REVIEWER_UNIFIED = "reviewer_unified"
REVIEWER_CODE = "reviewer_code"
REVIEWER_CONTRACT = "reviewer_contract"
REVIEWER_AGENT_DESIGN = "reviewer_agent_design"
REVIEWER_REFINE = "reviewer_refine"


class AgentStatus(StrEnum):
Expand Down Expand Up @@ -411,6 +417,42 @@ def depends_on(self, other: AgentRole) -> bool:
requires_inputs=["architecture_analysis"],
)


# Refine-phase agent role definitions

REFINER_ROLE = AgentRoleDefinition(
role=AgentRole.REFINER,
description="Analyzes the task and produces a structured analysis in the refine phase",
responsibilities=[
"Understand the problem or feature request",
"Research the current codebase to understand existing patterns",
"Identify constraints and dependencies",
"Consider multiple implementation approaches",
"Recommend an approach with justification",
"Write analysis to the draft file",
],
dependencies=[], # Refiner runs first, no dependencies
file_access=FileAccessPattern(
allowed_read=[], # Can read all files
allowed_write=[
".egg-state/drafts/",
".egg-state/agent-outputs/",
],
blocked_write=[
"**/*.py",
"**/*.ts",
"**/*.tsx",
"**/*.js",
"**/*.jsx",
"**/*.go",
"**/*.java",
".egg-state/contracts/",
],
),
produces_outputs=["analysis_draft"],
requires_inputs=[],
)

# Reviewer agent role definitions
# Reviewers can only write to reviews/ and agent-outputs/ directories.
# Use directory-based blocks instead of "**/*" which breaks can_write()
Expand Down Expand Up @@ -525,6 +567,29 @@ def depends_on(self, other: AgentRole) -> bool:
requires_inputs=["integration_report"],
)

REVIEWER_REFINE_ROLE = AgentRoleDefinition(
role=AgentRole.REVIEWER_REFINE,
description="Reviews refine phase analysis quality and completeness",
responsibilities=[
"Verify the analysis correctly identifies the core problem",
"Assess research quality and codebase exploration",
"Evaluate options analysis and trade-off reasoning",
"Check that constraints and dependencies are identified",
"Validate the recommendation is justified and actionable",
],
dependencies=[AgentRole.REFINER],
file_access=FileAccessPattern(
allowed_read=[],
allowed_write=[
".egg-state/reviews/",
".egg-state/agent-outputs/",
],
blocked_write=_REVIEWER_BLOCKED_WRITE,
),
produces_outputs=["review_verdict"],
requires_inputs=["analysis_draft"],
)


# Registry of all agent roles
AGENT_ROLES: dict[AgentRole, AgentRoleDefinition] = {
Expand All @@ -537,11 +602,14 @@ def depends_on(self, other: AgentRole) -> bool:
AgentRole.ARCHITECT: ARCHITECT_ROLE,
AgentRole.TASK_PLANNER: TASK_PLANNER_ROLE,
AgentRole.RISK_ANALYST: RISK_ANALYST_ROLE,
# Refine-phase roles
AgentRole.REFINER: REFINER_ROLE,
# Reviewer roles
AgentRole.REVIEWER_UNIFIED: REVIEWER_UNIFIED_ROLE,
AgentRole.REVIEWER_CODE: REVIEWER_CODE_ROLE,
AgentRole.REVIEWER_CONTRACT: REVIEWER_CONTRACT_ROLE,
AgentRole.REVIEWER_AGENT_DESIGN: REVIEWER_AGENT_DESIGN_ROLE,
AgentRole.REVIEWER_REFINE: REVIEWER_REFINE_ROLE,
}


Expand Down Expand Up @@ -644,6 +712,7 @@ def can_retry(self, max_retries: int = 2) -> bool:
_PHASE_ROLES: dict[str, list[AgentRole]] = {
"implement": [AgentRole.CODER, AgentRole.TESTER, AgentRole.DOCUMENTER, AgentRole.INTEGRATOR],
"plan": [AgentRole.ARCHITECT, AgentRole.TASK_PLANNER, AgentRole.RISK_ANALYST],
"refine": [AgentRole.REFINER],
}

_PHASE_REVIEWERS: dict[str, list[AgentRole]] = {
Expand All @@ -658,7 +727,7 @@ def can_retry(self, max_retries: int = 2) -> bool:
AgentRole.REVIEWER_AGENT_DESIGN,
],
"refine": [
AgentRole.REVIEWER_UNIFIED,
AgentRole.REVIEWER_REFINE,
AgentRole.REVIEWER_AGENT_DESIGN,
],
}
Expand Down
3 changes: 3 additions & 0 deletions shared/egg_contracts/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -321,11 +321,14 @@ class AgentRoleType(StrEnum):
ARCHITECT = "architect"
TASK_PLANNER = "task_planner"
RISK_ANALYST = "risk_analyst"
# Refine-phase roles
REFINER = "refiner"
# Reviewer roles
REVIEWER_UNIFIED = "reviewer_unified"
REVIEWER_CODE = "reviewer_code"
REVIEWER_CONTRACT = "reviewer_contract"
REVIEWER_AGENT_DESIGN = "reviewer_agent_design"
REVIEWER_REFINE = "reviewer_refine"


class AgentExecutionModel(BaseModel):
Expand Down
Loading