UNIFIED_AGENT_TEAMS.md

Unified Agent Teams Specification v1.0

Master reference for all agent teams, their responsibilities, coordination protocols, and the lifecycle model that governs work across the project.

---

Table of Contents

1. Team Directory
2. Team Definitions
3. 5-Phase Lifecycle Model
4. Orchestration Protocol
5. State Management
6. Inter-Team Communication
7. Escalation Paths

---

Team Directory

ID	Team Name	Focus Area	Primary Scope
T1	Backend	Server-side logic & APIs	src/server/**, src/api/**
T2	Frontend	UI components & client state	src/client/**, src/components/**
T3	Data	Database, migrations, ORM	src/db/**, migrations/**
T4	Infrastructure	CI/CD, Docker, cloud config	infra/**, .github/**, docker/**
T5	Auth	Authentication & authorization	src/auth/**, src/middleware/auth*
T6	Integration	Third-party services & webhooks	src/integrations/**, src/webhooks/**
T7	Documentation	Docs, ADRs, runbooks	docs/**, *.md
T8	DevEx	Tooling, linting, DX improvements	scripts/**, tools/**, .config/**
T9	Platform	Shared libraries & core modules	src/lib/**, src/core/**
T10	Quality	Testing, coverage, benchmarks	tests/**, benchmarks/**, e2e/**

---

Team Definitions

T1 — Backend

• Focus: Server-side business logic, REST/GraphQL API endpoints, request validation, error handling, and service-layer architecture.
• Scope patterns: src/server/**, src/api/**, src/services/**
• Permissions: Read/write to backend source; read access to database schemas for reference; no direct infrastructure changes.
• Key responsibilities:
  • Endpoint design and implementation
  • Request/response validation schemas
  • Service-layer orchestration
  • Backend error handling and logging

T2 — Frontend

• Focus: User interface components, client-side state management, routing, accessibility, and responsive design.
• Scope patterns: src/client/**, src/components/**, src/styles/**
• Permissions: Read/write to frontend source; read access to API contracts.
• Key responsibilities:
  • Component architecture and implementation
  • Client-side state management
  • Accessibility compliance (WCAG 2.1 AA)
  • Responsive layout and cross-browser support

T3 — Data

• Focus: Database schema design, migrations, seed data, ORM configuration, and query optimization.
• Scope patterns: src/db/**, migrations/**, seeds/**, prisma/**
• Permissions: Read/write to database layer; must coordinate with T1 for schema changes that affect API contracts.
• Key responsibilities:
  • Schema design and evolution
  • Migration authoring and review
  • Query performance optimization
  • Data integrity constraints

T4 — Infrastructure

• Focus: CI/CD pipelines, container orchestration, cloud resource configuration, and deployment automation.
• Scope patterns: infra/**, .github/**, docker/**, terraform/**
• Permissions: Read/write to infrastructure config; deployment credentials managed through CI secrets only.
• Key responsibilities:
  • Pipeline configuration and maintenance
  • Container image optimization
  • Environment provisioning
  • Deployment strategy (blue-green, canary)

T5 — Auth

• Focus: Authentication flows, authorization policies, session management, token handling, and security middleware.
• Scope patterns: src/auth/**, src/middleware/auth*, src/policies/**
• Permissions: Read/write to auth modules; must escalate any changes to token formats or session handling to security review.
• Key responsibilities:
  • OAuth/OIDC integration
  • RBAC/ABAC policy implementation
  • Session and token lifecycle
  • Security middleware for route protection

T6 — Integration

• Focus: Third-party service connectors, webhook handlers, event-driven integrations, and external API clients.
• Scope patterns: src/integrations/**, src/webhooks/**, src/events/**
• Permissions: Read/write to integration modules; must document all external dependencies and rate limits.
• Key responsibilities:
  • External API client implementation
  • Webhook receiver and dispatcher
  • Retry and circuit-breaker logic
  • Integration testing with mocks/stubs

T7 — Documentation

• Focus: Project documentation, architecture decision records, operational runbooks, and user-facing guides.
• Scope patterns: docs/**, *.md, adr/**
• Permissions: Read/write to all documentation; read access to source for reference when documenting behavior.
• Key responsibilities:
  • ADR authoring and maintenance
  • API documentation generation
  • Operational runbook updates
  • Onboarding and contributor guides

T8 — DevEx

• Focus: Developer experience tooling, linting configuration, code formatting, local development scripts, and productivity improvements.
• Scope patterns: scripts/**, tools/**, .config/**, *.config.*
• Permissions: Read/write to tooling and configuration; changes to shared config require team-wide notification.
• Key responsibilities:
  • Linting and formatting rules
  • Git hooks and pre-commit checks
  • Local development environment scripts
  • Monorepo tooling and workspace config

T9 — Platform

• Focus: Shared libraries, core utility modules, cross-cutting concerns like logging, telemetry, and error handling frameworks.
• Scope patterns: src/lib/**, src/core/**, src/shared/**
• Permissions: Read/write to platform modules; changes here affect all teams, so require broader review.
• Key responsibilities:
  • Shared utility functions and types
  • Logging and observability framework
  • Error handling conventions
  • Cross-cutting middleware

T10 — Quality

• Focus: Test strategy, coverage enforcement, performance benchmarks, end-to-end testing, and quality gate definitions.
• Scope patterns: tests/**, benchmarks/**, e2e/**, __tests__/**
• Permissions: Read/write to test infrastructure; read access to all source for writing tests against any module.
• Key responsibilities:
  • Test framework configuration
  • Coverage threshold enforcement
  • Performance benchmark suites
  • E2E test scenario authoring

---

5-Phase Lifecycle Model

Every unit of work progresses through five phases. Each phase has entry criteria, activities, and exit criteria (quality gates).

Phase 1: Discovery

• Objective: Understand the problem space and gather requirements.
• Activities:
  • Review related issues, discussions, and prior art
  • Update docs/product/ with problem statement and user stories
  • Create or link a tracking issue
  • Identify affected teams and scope
• Exit criteria: Product docs updated, issue created, teams identified.

Phase 2: Planning

• Objective: Design the solution and get alignment.
• Activities:
  • Author ADR(s) for significant decisions
  • Complete technical specification in docs/architecture/specs/
  • Break work into tasks and assign to teams
  • Identify risks and dependencies
• Exit criteria: ADRs approved, specs complete, tasks assigned.

Phase 3: Implementation

• Objective: Build the solution.
• Activities:
  • Write code following project conventions
  • Add or update unit and integration tests
  • Run /check to validate locally
  • Commit with conventional commit messages
• Exit criteria: /check passes, tests added, code complete.

Phase 4: Validation

• Objective: Verify the solution meets requirements.
• Activities:
  • Create pull request — title MUST use Conventional Commits: type(scope): description
  • Run pnpm --dir .agentkit retort:sync if any spec files changed, and commit regenerated outputs
  • All CI checks must pass (including PR title validation and drift check)
  • Code review by relevant team members
  • Manual testing for UI or user-facing changes
• Exit criteria: PR created, all checks pass, approvals received.

Phase 5: Ship

• Objective: Deploy and document.
• Activities:
  • Merge pull request
  • Update docs/operations/ with any operational changes
  • Update CHANGELOG.md
  • Monitor deployment for regressions
• Exit criteria: Merged, operational docs updated, monitoring confirmed.

---

Orchestration Protocol

The /orchestrate command coordinates multi-team work. It follows this protocol:

Invocation

/orchestrate <task-description> [--teams T1,T3,T10] [--phase discovery]

Coordination Flow

1. Parse: Extract task description, target teams, and starting phase.
2. Plan: Generate a work breakdown structure assigning subtasks to teams.
3. Dispatch: Send each subtask to the appropriate team context.
4. Track: Update .claude/state/orchestrator.json state with task assignments and statuses.
5. Sync: Periodically check team progress and resolve blockers.
6. Complete: Aggregate results and advance to the next phase.

Conflict Resolution

When multiple teams need to modify overlapping files:

1. The orchestrator identifies the conflict during the Plan step.
2. A primary owner is designated based on scope patterns.
3. Secondary teams submit changes as suggestions to the primary owner.
4. The primary owner integrates and resolves conflicts.

---

State Management

All orchestration state is persisted in .claude/state/orchestrator.json.

Schema Structure

{
  "version": "1.0",
  "activeSession": {
    "id": "session-uuid",
    "startedAt": "ISO-8601",
    "phase": "implementation",
    "teams": {
      "T1": { "status": "active", "currentTask": "task-id", "blockers": [] },
      "T3": { "status": "waiting", "currentTask": null, "blockers": ["T1"] }
    }
  },
  "backlog": [],
  "history": []
}

State Transitions

• States: idle -> active -> waiting -> complete | blocked
• Only the orchestrator or an explicit /unlock command may transition a team from blocked back to active.
• State is checkpointed after every phase transition.

---

Inter-Team Communication

Direct Handoff

When one team's output is another team's input (e.g., T3 schema change triggers T1 API update), the completing team:

1. Updates the shared state with the deliverable reference.
2. Tags the downstream team in the task notes.
3. The orchestrator notifies the downstream team.

Broadcast

For changes that affect all teams (e.g., T9 shared library update):

1. The authoring team creates an announcement in the task log.
2. The orchestrator pauses non-critical work until teams acknowledge.
3. Each team confirms compatibility or raises blockers.

Escalation Triggers

• A team is blocked for more than one phase cycle.
• Two teams have conflicting requirements.
• A security or data-integrity concern is raised.
• A quality gate fails after two retry attempts.

---

Escalation Paths

Severity	Condition	Action
Low	Task delayed, no blockers	Log in backlog, continue
Medium	Cross-team dependency unresolved	Orchestrator mediates
High	Quality gate failure on retry	Escalate to T10 + team lead
Critical	Security issue or data loss risk	Immediate halt, escalate to T5 + T4

---

This specification is maintained by Retort. Do not edit directly. Run pnpm --dir .agentkit retort:sync to regenerate from the canonical spec.