135 lines
7.4 KiB
Markdown
135 lines
7.4 KiB
Markdown
# 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](./research-inbox.md) | Inbox file format, race conditions, atomic writes, message delivery |
|
|
| [research-tasks.md](./research-tasks.md) | Task file format, .lock, .highwatermark, concurrent access |
|
|
| [research-messaging.md](./research-messaging.md) | Comparison of inbox, SDK, and CLI approaches, and why inbox was chosen |
|
|
| [kanban-design.md](./kanban-design.md) | Kanban flow, columns, review mechanism, kanban-state.json |
|
|
| [implementation.md](./implementation.md) | Technical plan: files, steps, verification |
|
|
| [openclaw-agent-teams-integration.md](./openclaw-agent-teams-integration.md) | How to connect OpenClaw or another outside AI through Agent Teams MCP and REST control API |
|
|
| [research-worktrees.md](./research-worktrees.md) | Git worktrees + teams, launching Claude processes from the UI (Phase 2) |
|
|
| [task-queue-derived-agenda-plan.md](./task-queue-derived-agenda-plan.md) | Detailed rollout plan for queue/inventory split, derived actionOwner, and phased agenda/delta sync |
|
|
| [debugging-agent-teams.md](./debugging-agent-teams.md) | Runtime debugging runbook, including `CLAUDE_TEAM_TEAMMATE_MODE=tmux` for pane-backed teammate debug |
|
|
| [adaptive-task-graphs-research-note.md](./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](./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](./research-messaging.md) and [debugging-agent-teams.md](./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](./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
|
|
|
|
```text
|
|
~/.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)`.
|