agent-ecosystem/docs/team-management/README.md

Team Management Feature

UI for managing AI teammate teams inside Agent Teams (Electron), including Claude, Codex, and OpenCode runtime paths.

What It Does

• Shows team members and their roles.
• Provides a Kanban board with 5 columns: TODO, IN PROGRESS, REVIEW, DONE, APPROVED.
• Sends messages to teammates through inbox files and runtime-aware delivery for OpenCode.
• Supports review flow: review requests, manual review, and direct manual approval from DONE.
• Provides live updates through the file watcher.

Documentation

File	Contents
research-inbox.md	Inbox file format, race conditions, atomic writes, message delivery
research-tasks.md	Task file format, .lock, .highwatermark, concurrent access
research-messaging.md	Comparison of inbox, SDK, and CLI approaches, and why inbox was chosen
kanban-design.md	Kanban flow, columns, review mechanism, kanban-state.json
implementation.md	Technical plan: files, steps, verification
openclaw-agent-teams-integration.md	How to connect OpenClaw or another outside AI through Agent Teams MCP and REST control API
research-worktrees.md	Git worktrees + teams, launching Claude processes from the UI (Phase 2)
task-queue-derived-agenda-plan.md	Detailed rollout plan for queue/inventory split, derived actionOwner, and phased agenda/delta sync
debugging-agent-teams.md	Runtime debugging runbook, including CLAUDE_TEAM_TEAMMATE_MODE=tmux for pane-backed teammate debug
adaptive-task-graphs-research-note.md	Research note on LATTE/AgentConductor: dynamic task graphs, frontier scheduling, selective verify, release stragglers

Key Decisions

Warning: docs/iterations/* contains historical planning notes. These files are useful for context, but they are not the source of truth for current product behavior. The current review-flow contract is documented here and in kanban-design.md.

Warning: agent-attachments-*.md files (architecture plan + phase 1-5 plans) are historical design documents for feature attachments. The actual implementation in src/features/agent-attachments/ may differ from that architecture. For current behavior, see the code in src/features/agent-attachments/core/domain/ and the tests.

1. Messaging: Inbox + Runtime Delivery

For native Claude/Codex-style teammates, the primary path is durable inbox files. Lead inbox delivery uses relayLeadInboxMessages() because the lead reads stdin. OpenCode secondary lanes do not read inboxes/{member}.json directly, so the UI first persists the message to the inbox and then delivers it through the runtime bridge with delivery proof. Details: research-messaging.md and debugging-agent-teams.md.

1.1 Roster Source: members.meta.json + inboxes

• config.json is not used as the complete member registry. It may contain only the team lead and CLI service fields.
• Member metadata source (role/color/agentType): members.meta.json.
• Runtime membership and message-addressing source: inboxes/{member}.json.

2. Kanban Storage: Dedicated File

Kanban position (REVIEW, APPROVED) is stored in kanban-state.json, not task metadata. Reason: task metadata may be overwritten by an agent during TaskUpdate. Details: kanban-design.md.

3. Review Flow: Approve / Request Changes

• Reviewers exist in the team -> automatic assignment through inbox.
• The user can also manually approve a task directly from DONE without entering REVIEW.
• No reviewers -> manual user review (Approve / Request Changes in the UI).
• Request Changes -> the user optionally describes the issue -> the task returns to its owner in pending with needsFix.

4. Atomic Write

All writes use tmp + rename to prevent corrupted JSON.

5. Sender Identity

Messages are sent with from: "user". Fallback to from: "team-lead" exists only if needed.

Final Decisions After Review

After 3 review rounds with 13 experts, the following decisions were accepted.

Inbox: Atomic Write + messageId Verify

• Atomic write (tmp + rename) prevents corrupted JSON.
• After writing, read the file back and verify that our messageId is present.
• A full CAS/retry loop is not needed for MVP. Verification on the next read is enough.
• Race condition risk with an agent is real, but probability is low.

Kanban: kanban-state.json With Safe GC

• Stale kanban-state entries are garbage-collected only after all tasks are fully loaded.
• Otherwise, startup can race: GC may delete an entry before the task file has been read.

Review Flow: Approve / Request Changes

• Buttons were renamed: Approve instead of OK, and Request Changes instead of Error.
• Request Changes comment is optional.
• Manual UI allows two valid paths:
  • DONE -> REVIEW -> APPROVED
  • DONE -> APPROVED as fast manual approval
• Request Changes removes the kanban-state entry and returns the task to pending with needsFix.
• reviewHistory and round-robin balancing are Phase 2, not MVP.

Members: Complete List Through Union

• union(members.meta.json + config members + inbox filenames + task owners) is the only way to get the complete member list.
• owner in task files is optional. An agent may not have an owner before assignment.

Graceful Degradation

• try/catch is used throughout TeamDataService; read errors return safe defaults.
• Member has 3 states: ACTIVE / IDLE / TERMINATED.
  • ACTIVE: idle < 5 minutes
  • IDLE: idle > 5 minutes
  • TERMINATED: received shutdown_response with approve: true

@dnd-kit and Review Transitions

• Transitions between review columns happen through card actions in the UI.
• @dnd-kit is currently used primarily for reordering tasks inside a column.
• Phase 2: full drag-and-drop through @dnd-kit.

---

Open Questions

• FileWatcher extension: FileWatcher.ts is already 1243 lines. Adding teams/tasks watchers is non-trivial and needs a separate spike.
• Windows atomic rename: fs.renameSync on Windows can throw EXDEV/EBUSY for cross-device rename. A wrapper is needed.
• leadSessionId integration: config.json contains leadSessionId, but integration with the session viewer (navigating to the lead session) remains open.
• Hard Interrupt: messages are delivered between turns with a 1-30 second delay. A future mechanism is needed to interrupt mid-turn.
• Archival: inbox is not cleaned automatically. An "Archive" button is needed.

Claude Code File Structure

~/.claude/
├── teams/{teamName}/
│   ├── config.json                # Team config (lead + service fields)
│   ├── members.meta.json          # Member roles/colors/types (teammates)
│   └── inboxes/{memberName}.json  # Inbox for each member
└── tasks/{teamName}/
    ├── {id}.json                  # Task file
    ├── .lock                      # Lock file (0 bytes)
    └── .highwatermark             # Latest task ID

Important:

• config.json is not the source of truth for the complete roster.
• The UI builds the complete roster from members.meta.json + inbox filenames (+ lead from config).