Skip to content

task

View module diagram

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.
TaggedPath

A file path annotated with a semantic category.
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. AdrVerbosity: 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.

AdrVerbosity

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 
34
35
36
37
38
39
40
41
42
43
44
45
46
47
class AdrVerbosity(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 
50
51
52
53
54
55
56
57
58
59
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 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
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"

TaggedPath dataclass

A file path annotated with a semantic category.

Attributes:

Name Type Description
path Path

File path (relative to the repository root).
category str

Semantic role of the file (e.g., "src", "test", "spec"). Free-form string; not restricted to a fixed set.
Source code in src/agentrelay/task.py 
88
89
90
91
92
93
94
95
96
97
98
99
@dataclass(frozen=True)
class TaggedPath:
    """A file path annotated with a semantic category.

    Attributes:
        path: File path (relative to the repository root).
        category: Semantic role of the file (e.g., ``"src"``, ``"test"``,
            ``"spec"``).  Free-form string; not restricted to a fixed set.
    """

    path: Path
    category: str

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 AdrVerbosity

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
124
@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: AdrVerbosity = AdrVerbosity.NONE
    environment: AgentEnvironment = field(default_factory=TmuxEnvironment)
    isolation: Optional[IsolationConfig] = None

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 
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
@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

InputFrom dataclass

A reference to an upstream task's outputs for input resolution.

At prepare time, the orchestrator reads the referenced task's outputs.json, optionally filters by category, and places the resolved file paths in the downstream task's manifest.

Attributes:

Name Type Description
task str

Upstream task ID whose output manifest to consume.
category Optional[str]

Optional category filter. When None, all outputs from the upstream task are included.
Source code in src/agentrelay/task.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
@dataclass(frozen=True)
class InputFrom:
    """A reference to an upstream task's outputs for input resolution.

    At prepare time, the orchestrator reads the referenced task's
    ``outputs.json``, optionally filters by category, and places the
    resolved file paths in the downstream task's manifest.

    Attributes:
        task: Upstream task ID whose output manifest to consume.
        category: Optional category filter.  When ``None``, all outputs
            from the upstream task are included.
    """

    task: str
    category: Optional[str] = None

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.
tagged_paths tuple[TaggedPath, ...]

Category-tagged file paths the task operates on. Defaults to empty tuple.
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 
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
@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.
        tagged_paths: Category-tagged file paths the task operates on.
            Defaults to empty tuple.
        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
    tagged_paths: tuple[TaggedPath, ...] = ()
    dependencies: tuple[str, ...] = ()
    inputs_from: tuple[InputFrom, ...] = ()
    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"
    isolation: Optional[IsolationConfig] = None