Skip to content

task

Core data types for tasks in the agentrelay architecture.

This module defines frozen specifications for units of work in a task graph, configuration types for agents and reviews, and enums for roles.

Classes:

Name Description
Task

A frozen specification of work to be done in the task graph.
TaskPaths

File paths a task operates on (source, test, supplementary spec).
AgentConfig

Framework and model configuration for executing an agent.
ReviewConfig

Configuration for self-review before task completion.
Enums

AgentRole: The type of work a task performs. AgentFramework: The AI framework/platform executing an agent. AgentVerbosity: The detail level of Architecture Decision Records (ADRs).

See also

environments: AgentEnvironment (type alias) and environment-specific types. task_runtime: TaskStatus (execution state) and mutable runtime types. workstream: WorkstreamSpec for grouping related task execution.

AgentVerbosity

Bases: str, Enum

Level of detail for Architecture Decision Records (ADRs) produced by agents.

Attributes:

Name Type Description
NONE

No ADR produced.
STANDARD

Basic ADR with key decisions.
DETAILED

Comprehensive ADR with rationale and alternatives.
EDUCATIONAL

Detailed ADR with educational explanations.
Source code in src/agentrelay/task.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
class AgentVerbosity(str, Enum):
    """Level of detail for Architecture Decision Records (ADRs) produced by agents.

    Attributes:
        NONE: No ADR produced.
        STANDARD: Basic ADR with key decisions.
        DETAILED: Comprehensive ADR with rationale and alternatives.
        EDUCATIONAL: Detailed ADR with educational explanations.
    """

    NONE = "none"
    STANDARD = "standard"
    DETAILED = "detailed"
    EDUCATIONAL = "educational"

AgentFramework

Bases: str, Enum

AI framework or platform that executes an agent.

Attributes:

Name Type Description
CLAUDE_CODE

Claude Code (Anthropic's official CLI).

Future frameworks (e.g., CODEX, COPILOT) can be added as needed.

Source code in src/agentrelay/task.py 
49
50
51
52
53
54
55
56
57
58
class AgentFramework(str, Enum):
    """AI framework or platform that executes an agent.

    Attributes:
        CLAUDE_CODE: Claude Code (Anthropic's official CLI).

    Future frameworks (e.g., CODEX, COPILOT) can be added as needed.
    """

    CLAUDE_CODE = "claude_code"

AgentRole

Bases: str, Enum

Type of work a task performs in the orchestration workflow.

Attributes:

Name Type Description
SPEC_WRITER

Writes specifications for source files.
TEST_WRITER

Writes test cases for source files.
TEST_REVIEWER

Reviews tests written by test writers.
IMPLEMENTER

Implements source code based on specs and tests.
GENERIC

General-purpose task with no specific role.
Note

MERGER is handled at the graph level, not as a task role.

Source code in src/agentrelay/task.py 
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
class AgentRole(str, Enum):
    """Type of work a task performs in the orchestration workflow.

    Attributes:
        SPEC_WRITER: Writes specifications for source files.
        TEST_WRITER: Writes test cases for source files.
        TEST_REVIEWER: Reviews tests written by test writers.
        IMPLEMENTER: Implements source code based on specs and tests.
        GENERIC: General-purpose task with no specific role.

    Note:
        MERGER is handled at the graph level, not as a task role.
    """

    SPEC_WRITER = "spec_writer"
    TEST_WRITER = "test_writer"
    TEST_REVIEWER = "test_reviewer"
    IMPLEMENTER = "implementer"
    GENERIC = "generic"

TaskPaths dataclass

File paths a task operates on.

Attributes:

Name Type Description
src tuple[Path, ...]

Tuple of source file paths to create or modify. Defaults to empty.
test tuple[Path, ...]

Tuple of test file paths to create or modify. Defaults to empty.
spec Optional[Path]

Path to supplementary specification file, or None if not applicable.
Source code in src/agentrelay/task.py 
87
88
89
90
91
92
93
94
95
96
97
98
99
@dataclass(frozen=True)
class TaskPaths:
    """File paths a task operates on.

    Attributes:
        src: Tuple of source file paths to create or modify. Defaults to empty.
        test: Tuple of test file paths to create or modify. Defaults to empty.
        spec: Path to supplementary specification file, or None if not applicable.
    """

    src: tuple[Path, ...] = ()
    test: tuple[Path, ...] = ()
    spec: Optional[Path] = None

AgentConfig dataclass

Framework and model configuration for executing an agent.

This configuration specifies which AI framework and model to use for executing an agent, where to run it, and how verbosely to document decisions. It is used for primary agents, review agents, and merger agents.

Attributes:

Name Type Description
framework AgentFramework

The AI framework to use. Defaults to CLAUDE_CODE.
model Optional[str]

The model identifier (e.g., "claude-opus-4-6"), or None to use the framework's default model.
adr_verbosity AgentVerbosity

Level of detail for Architecture Decision Records produced by the agent. Defaults to NONE (no ADR produced).
environment AgentEnvironment

Execution environment configuration (tmux, cloud, etc.). Defaults to TmuxEnvironment.
Source code in src/agentrelay/task.py 
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
@dataclass(frozen=True)
class AgentConfig:
    """Framework and model configuration for executing an agent.

    This configuration specifies which AI framework and model to use for
    executing an agent, where to run it, and how verbosely to document decisions.
    It is used for primary agents, review agents, and merger agents.

    Attributes:
        framework: The AI framework to use. Defaults to CLAUDE_CODE.
        model: The model identifier (e.g., "claude-opus-4-6"), or None to use
            the framework's default model.
        adr_verbosity: Level of detail for Architecture Decision Records produced
            by the agent. Defaults to NONE (no ADR produced).
        environment: Execution environment configuration (tmux, cloud, etc.).
            Defaults to TmuxEnvironment.
    """

    framework: AgentFramework = AgentFramework.CLAUDE_CODE
    model: Optional[str] = None
    adr_verbosity: AgentVerbosity = AgentVerbosity.NONE
    environment: AgentEnvironment = field(default_factory=TmuxEnvironment)

ReviewConfig dataclass

Configuration for agent self-review before task completion.

When specified, the agent will self-review its work before signaling task completion, starting from a specified attempt number.

Attributes:

Name Type Description
agent AgentConfig

AgentConfig specifying which framework and model performs the review.
review_on_attempt int

The attempt number at which to begin self-review. Defaults to 1 (review on first attempt).
Source code in src/agentrelay/task.py 
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
@dataclass(frozen=True)
class ReviewConfig:
    """Configuration for agent self-review before task completion.

    When specified, the agent will self-review its work before signaling
    task completion, starting from a specified attempt number.

    Attributes:
        agent: AgentConfig specifying which framework and model performs the review.
        review_on_attempt: The attempt number at which to begin self-review.
            Defaults to 1 (review on first attempt).
    """

    agent: AgentConfig
    review_on_attempt: int = 1

Task dataclass

Frozen specification of a unit of work in the task graph.

A Task defines WHAT work needs doing (role, paths, description). It does NOT track HOW the work is executed (Agent responsibility) or WHEN it runs (Orchestrator responsibility).

Tasks are immutable and hashable, making them safe for use in dependency tuples and as dictionary keys.

Attributes:

Name Type Description
id str

Unique identifier for this task within the graph.
role AgentRole

The type of work this task performs (AgentRole enum).
description Optional[str]

Optional human-readable description of the task.
paths TaskPaths

File paths the task operates on (source, test, spec). Defaults to empty paths.
dependencies tuple[str, ...]

Tuple of dependency task IDs that must complete before this task can run. Defaults to empty tuple.
completion_gate Optional[str]

Optional shell command (exit code 0 = success) that determines if the task is complete. None = no gate.
max_gate_attempts Optional[int]

Maximum number of gate execution attempts before the task fails. None = inherit from orchestrator.
primary_agent AgentConfig

AgentConfig specifying which framework and model executes this task. Defaults to CLAUDE_CODE.
review Optional[ReviewConfig]

Optional ReviewConfig for self-review before completion. None = no self-review.
workstream_id str

Identifier of the workstream this task belongs to. Defaults to "default" for backward compatibility.
Source code in src/agentrelay/task.py 
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
@dataclass(frozen=True)
class Task:
    """Frozen specification of a unit of work in the task graph.

    A Task defines WHAT work needs doing (role, paths, description).
    It does NOT track HOW the work is executed (Agent responsibility)
    or WHEN it runs (Orchestrator responsibility).

    Tasks are immutable and hashable, making them safe for use in
    dependency tuples and as dictionary keys.

    Attributes:
        id: Unique identifier for this task within the graph.
        role: The type of work this task performs (AgentRole enum).
        description: Optional human-readable description of the task.
        paths: File paths the task operates on (source, test, spec).
            Defaults to empty paths.
        dependencies: Tuple of dependency task IDs that must complete before
            this task can run. Defaults to empty tuple.
        completion_gate: Optional shell command (exit code 0 = success)
            that determines if the task is complete. None = no gate.
        max_gate_attempts: Maximum number of gate execution attempts
            before the task fails. None = inherit from orchestrator.
        primary_agent: AgentConfig specifying which framework and model
            executes this task. Defaults to CLAUDE_CODE.
        review: Optional ReviewConfig for self-review before completion.
            None = no self-review.
        workstream_id: Identifier of the workstream this task belongs to.
            Defaults to ``"default"`` for backward compatibility.
    """

    id: str
    role: AgentRole
    description: Optional[str] = None
    paths: TaskPaths = field(default_factory=TaskPaths)
    dependencies: tuple[str, ...] = ()
    completion_gate: Optional[str] = None
    max_gate_attempts: Optional[int] = None
    primary_agent: AgentConfig = field(default_factory=AgentConfig)
    review: Optional[ReviewConfig] = None
    workstream_id: str = "default"