Evolith Tracker — BMAD Agent Assignment API Design

Bilingual Navigation: English (this document) · Versión en Español

Document Status: Draft Type: API & Interaction Contract Design (within the Governance Bounded Context) Satellite: Evolith Tracker Upstream: Evolith Core Date: 2026-06-07 Author: Architect Agent (BMAD) Resolves: GAP-009 / REM-008

1. Purpose & Scope

This document specifies the contract (not implementation) for assigning work to humans or BMAD agents across the SDLC. Per BR-008, the three interaction surfaces — REST API, CLI, MCP Server — are functionally equivalent; this document defines all three against one canonical model so there is no feature gap.

It is a design within the Governance bounded context. Domain model: Governance DDD. Strategic placement: Bounded Context Map. This closes the gap noted in TAD §23 (REST endpoints existed for the 5 gates but not for agent assignment).

Evidence base:

Source	Mandate
PRD EPIC-005	Agent assignment engine, execution mode config — Must Have
PRD §5.2 / §5.3	CLI `evolith agent assign`; MCP `tracker_get_assignment`
Governance DDD	`SDLCExecution`, `AgentAssignment`, `assignPhase()`
Product Vision §1	Convention over Configuration; default BMAD flow

This is a contract specification, not code. Request/response shapes are API contracts (the product's own Spec-as-Source artifacts), not implementation.

2. Conceptual Model (Recap)

Assignment lives on the SDLCExecution aggregate (Governance). Each SDLC phase can be delegated to a human or a BMAD agent, per tenant configuration.

Concept	Meaning
Assignee Type	`HUMAN` or `AGENT`
Agent Role	`analyst`, `pm`, `architect`, `sm`, `dev`, `qa` (BMAD personas)
Execution Mode	`manual` (human), `automated` (agentic) — per phase; no hybrid mode
Convention over Configuration	Default flow = Analyst→PM→Architect→SM→Dev→QA; tenants override per phase only when needed
Authority Principle	The Tracker assigns; an agent cannot self-assign, skip a gate, or override an upstream constraint (PRD MCP principle)

3. REST API

Base path /api/v1. All endpoints are tenant-scoped (token-derived) and permission-guarded (fail-closed, Security Spec §4).

Method	Endpoint	Description	Permission
POST	`/executions/{executionId}/assignments`	Assign a phase to a human or agent	`tracker:agent:assign`
GET	`/executions/{executionId}/assignments`	List all phase assignments for an execution	`tracker:agent:read`
GET	`/executions/{executionId}/assignments/{phase}`	Get the assignment for one phase	`tracker:agent:read`
PATCH	`/executions/{executionId}/assignments/{phase}`	Reassign a phase (human↔agent or different assignee)	`tracker:agent:assign`
DELETE	`/executions/{executionId}/assignments/{phase}`	Clear an assignment (revert to tenant default)	`tracker:agent:assign`
GET	`/agents/{agentRole}/assignments`	List active assignments for an agent role (agent self-query)	`tracker:agent:read`
GET	`/executions/{executionId}/mode`	Get per-phase execution mode (manual/automated)	`tracker:agent:read`
PUT	`/executions/{executionId}/mode`	Configure per-phase execution mode (`manual` / `automated`)	`tracker:agent:configure`

3.1 Assign — request/response contract

// POST /api/v1/executions/{executionId}/assignments
// request
{
  "phase": "design",                 // SDLC phase
  "assigneeType": "AGENT",           // HUMAN | AGENT
  "agentRole": "architect",          // required when assigneeType = AGENT
  "assigneeId": null,                // required when assigneeType = HUMAN (UMS user id)
  "mode": "automated"                // manual | automated
}
// 201 response
{
  "assignmentId": "uuid",
  "executionId": "uuid",
  "phase": "design",
  "assigneeType": "AGENT",
  "agentRole": "architect",
  "status": "ASSIGNED",
  "assignedAt": "2026-06-07T12:00:00Z",
  "assignedBy": "uuid"               // UMS user id of the human who assigned
}

3.2 Error contract (problem+json)

Status	Condition
400	Missing `agentRole` for AGENT, or `assigneeId` for HUMAN
403	Caller lacks the required permission (fail-closed)
404	Execution or phase not found
409	Phase already past (cannot reassign a completed gate)
422	Assignment violates tenant policy (e.g., gate requires human authorization)

4. CLI Surface

Per PRD §5.2, every REST capability is available via the CLI (evolith <verb> <noun>), machine-readable with --format=json.

Command	Maps to	Example
`evolith agent assign`	POST assignments	`evolith agent assign --execution=EPIC-001 --phase=design --role=architect --mode=automated`
`evolith agent list`	GET assignments	`evolith agent list --execution=EPIC-001 --format=json`
`evolith agent reassign`	PATCH assignment	`evolith agent reassign --execution=EPIC-001 --phase=design --human=alice@acme`
`evolith agent unassign`	DELETE assignment	`evolith agent unassign --execution=EPIC-001 --phase=design`
`evolith agent status`	GET agent assignments	`evolith agent status --role=architect --format=json`
`evolith mode set`	PUT mode	`evolith mode set --execution=EPIC-001 --phase=discovery --mode=manual`

CLI principles (PRD §5.2): idempotent, offline-aware (queue on disconnect), --format=json for agent consumption.

5. MCP Server Surface

Per PRD §5.3, BMAD agents interact via MCP tools without leaving their context. The Tracker remains authoritative (an agent reads its assignment; it cannot self-assign).

MCP Tool	Purpose	Maps to
`tracker_get_assignment`	Returns the current assigned task for the calling agent role	GET `/agents/{role}/assignments`
`tracker_get_gate_status`	Returns gate status for an execution/phase	GET gate status (existing)
`tracker_log_activity`	Logs agent activity to the audit trail (BR-009)	append audit
`tracker_get_upstream_constraints`	Returns active Core ADRs for the current phase	Core integration

// tracker_get_assignment — response shape
{
  "executionId": "uuid",
  "phase": "design",
  "agentRole": "architect",
  "status": "ASSIGNED",
  "specRef": "uri-to-approved-spec",
  "upstreamConstraints": ["ADR-0002", "ADR-0043"],
  "deliverableExpected": "TechnicalContract"
}

MCP authority rule (security): the MCP token carries the same scoped permissions as a human (Security Spec §4.1, MCP-1..3). tracker_get_assignment is read-only; assignment changes require tracker:agent:assign, which agents are not granted by default.

6. Execution Mode Configuration

Per PRD EPIC-005 and Product Vision §1 (Convention over Configuration):

Mode	Behavior
`manual`	All phase work assigned to humans (traditional ceremonies)
`automated`	All phase work assigned to BMAD agents (autonomous)

Only two modes exist — there is no hybrid mode. A phase is either fully human-driven or fully agent-driven.

The default is the standard BMAD flow; tenants configure the mode per phase via PUT /executions/{id}/mode.
Mode configuration requires tracker:agent:configure (a governance-level permission, stricter than assign).
Approval gates always require a human regardless of mode (BR-001, BR-003) — an automated phase still stops at a human authorization gate.

7. Authorization Summary

Permission	Grants
`tracker:agent:read`	View assignments, agent status, mode
`tracker:agent:assign`	Create/change/clear assignments
`tracker:agent:configure`	Set per-phase execution mode (`manual` / `automated`)

All resolved from UMS (fail-closed). Agents are granted read (and phase-specific deliverable permissions) but not assign/configure — preserving the Tracker-authoritative principle.

8. Domain Events

These align with the Governance DDD:

AgentAssignedEvent — a phase was assigned to a human/agent
AgentReassignedEvent — assignment changed
AgentUnassignedEvent — assignment cleared
ExecutionModeConfiguredEvent — per-phase mode set (manual / automated)
AgentActivityLoggedEvent — agent action recorded for audit (BR-009)

Cross-context: assignment events are consumed by Metrics (agent task completion rate — PRD §9 metric) and recorded by Artifacts as evidence.

9. Traceability

Capability	Source	This document
Agent assignment engine	PRD EPIC-005 (Must Have)	§3–§6
CLI parity	PRD §5.2, BR-008	§4
MCP integration	PRD §5.3, UC-008	§5
Execution mode config	PRD EPIC-005, Product Vision §1	§6
Tracker-authoritative principle	PRD §5.3 MCP principle	§5, §7
Agent audit	BR-009	§5, §8
Fail-closed authorization	Security Spec §4	§3, §7

Closes the orphaned requirement noted in Traceability Audit §3.2 (Agent Assignment API endpoints were missing from the TAD).

References

Governance DDD Model
Tracker Target Architecture (TAD) — §23 REST endpoints
Security Specification — §4 AuthZ, §4.1 MCP
PRD — EPIC-005, §5.2 CLI, §5.3 MCP
Bounded Context Map

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Evolith Tracker — BMAD Agent Assignment API Design

1. Purpose & Scope

2. Conceptual Model (Recap)

3. REST API

3.1 Assign — request/response contract

3.2 Error contract (problem+json)

4. CLI Surface

5. MCP Server Surface

6. Execution Mode Configuration

7. Authorization Summary

8. Domain Events

9. Traceability

References

FilesExpand file tree

tracker-agent-assignment-api.md

Latest commit

History

tracker-agent-assignment-api.md

File metadata and controls

Evolith Tracker — BMAD Agent Assignment API Design

1. Purpose & Scope

2. Conceptual Model (Recap)

3. REST API

3.1 Assign — request/response contract

3.2 Error contract (problem+json)

4. CLI Surface

5. MCP Server Surface

6. Execution Mode Configuration

7. Authorization Summary

8. Domain Events

9. Traceability

References