Context

Departments have an internal teams structure -- each team is a named sub-group with a lead agent and member agents, used to model reporting lines more granularly than the department level alone (e.g. Engineering → Frontend Team, Backend Team). The data model is implemented backend-side at src/synthorg/core/company.py:315 (class Team) and surfaced through Department.teams: tuple[Team, ...].

Team editing in the dashboard is explicitly deferred in the design spec (docs/design/page-structure.md:38):

Departments (card grid with CRUD and read-only teams summary; nested teams/reporting/policies editing is deferred).

The Department Edit drawer (web/src/pages/org-edit/DepartmentEditDrawer.tsx) therefore only shows a read-only list of existing teams, and shows "No teams yet. Add one from the Departments tab via the Add Team button..." when department.teams.length === 0. The "Add Team" button on DepartmentsTab opens PackSelectionDialog, which only lets the user pick from pre-built team template packs, not define or edit a team freely.

That leaves several gaps that operators hit immediately:

• No way to create a team with custom name / members / lead -- only template packs
• No way to rename, reassign, or delete an existing team -- once a team is created (via a pack or via YAML), the drawer is read-only
• No way to reassign agents between teams within a department
• No way to edit team leads -- the lead field on TeamConfig is not exposed in any UI
• No visual indication that team editing is intentionally deferred -- the drawer's "No teams yet" message is improved in the Base UI migration PR (feat: migrate web dashboard from Radix UI to Base UI + activate CSP nonce + personality trimming WS notification #1074) but still just explains the existing flow; the deferred-feature status is invisible

This issue tracks building the full in-drawer (or dedicated drawer / page) team editing experience. It is the natural follow-up to #674 (closed, "interactive org chart with department/team CRUD and detail pages") which established department CRUD but intentionally excluded team CRUD.

Proposed scope

Frontend

Read & display (builds on what already exists):

• Show teams within a department with team name, lead agent, member agents, member count, and team-level budget if configured.
• Team card / row expand-collapse for large teams.

Create:

• "Add Team" action on the department edit drawer (distinct from the existing "Add Team" pack selection button on the parent DepartmentsTab -- rename that one to "Add Team Pack" so the two do not collide).
• Team creation form: name, optional lead (dropdown of department members), members (multi-select of department agents), optional budget percent within the department's allocation.
• Validation: name unique within department, lead must be a member, at least one member required.

Edit:

• Click a team row to open an inline edit state or a nested drawer.
• Editable fields: name, lead, members (add / remove), budget allocation.
• Reassign agents: moving an agent between teams stays within the parent department; moving an agent to a different department is already covered by the Org Chart drag-drop flow.

Delete:

• Confirm dialog on team delete, with member-reassignment prompt: "The 3 members of this team will become direct reports of the department head. Continue?"
• Option to reassign members to another team in the same department instead of unassigning them.

Reorder:

• @dnd-kit sortable list inside the department drawer, matching the existing department-card reordering pattern.

Visual polish:

• Team color accent (optional, derived from name hash) so teams are visually distinguishable in the Org Chart hierarchy view.
• Team-level status rollup (all members active / some idle / all idle) shown next to the team name.

Backend

The current CompanyController has no team-level endpoints -- team mutations must go through the full Department update path, which is awkward for piecemeal team edits. Add:

• POST /api/v1/departments/{dept_name}/teams -- create team
• PATCH /api/v1/departments/{dept_name}/teams/{team_name} -- rename / edit members / change lead / update budget
• DELETE /api/v1/departments/{dept_name}/teams/{team_name} -- delete with optional reassign_to query param
• PATCH /api/v1/departments/{dept_name}/teams/reorder -- reorder teams within a department

All endpoints should:

• Guard with require_write_access.
• Validate team name uniqueness within the department.
• Validate lead membership.
• Emit WS events on agents or a new organization channel so the Org Chart / Edit views live-update across browser tabs and operators.
• Persist through the same settings store mechanism the department CRUD uses.

Org Chart integration

• Hierarchy view: teams should render as an intermediate grouping layer between the department group node and the agent nodes. The agent-level reporting edges (team lead → member) already exist in build-org-tree.ts (see the teamMemberSet map at lines 121-132), but there is no visual "team frame" -- add one via a new team ReactFlow node type analogous to the existing department group node.
• Drag-drop: support dragging an agent between teams inside the same department (new drop targets) alongside the existing department drag-drop.
• Keyboard: cursor-nav across teams and between team members.

Docs

• Update docs/design/page-structure.md:38 to drop the "nested teams/reporting/policies editing is deferred" note once this lands.
• Add a short operator guide in docs/guides/ explaining what teams are, when to use them vs just department membership, and the Add Team flow. Design-spec language only: "team is a named sub-group inside a department" is correct but the operator doc should explain why you would configure one.

Out of scope

• Cross-department teams (matrix organizations where an agent belongs to teams in multiple departments). The current model locks team membership to the department; breaking that constraint is a much larger change and should be a separate research issue.
• Reporting-line policies per team (distinct autonomy level, escalation, approval policy at the team level). The Department.ceremony_policy override already exists at the department level; extending to team-level is a follow-up.
• Team-level budgets enforced at runtime. The current Budget system tracks costs per department, not per team. Team budgets in this issue are a UI / metadata concept only; enforcing them is a separate scope.

Acceptance criteria

• Operator can create a new team inside any department via the dashboard UI with custom name, lead, and members.
• Operator can rename, edit, reorder, and delete teams without editing YAML.
• Team deletion prompts for member reassignment (unassign / reassign to another team).
• Agents can be moved between teams inside the same department via UI.
• Team edits round-trip through WebSocket so other open dashboard tabs update without a refresh.
• Org Chart hierarchy view renders teams as an intermediate grouping node between department and agents.
• DepartmentEditDrawer replaces the "team editing not yet available" message with the real editing surface.
• The docs/design/page-structure.md:38 "deferred" note is removed.
• Test coverage: backend controller unit + integration tests, frontend store + component tests, Org Chart build-tree test updates.

Related

• Design spec: docs/design/page-structure.md:38 and docs/design/organization.md:159 (Teams definition)
• Closed predecessor: feat: interactive org chart with department/team CRUD and detail pages #674 (feat: interactive org chart with department/team CRUD and detail pages) -- shipped the department-level CRUD; this issue completes the team-level CRUD gap.
• Current read-only implementation: web/src/pages/org-edit/DepartmentEditDrawer.tsx (team list, edit message), web/src/pages/org-edit/DepartmentsTab.tsx (pack selection entry point).
• Data model: src/synthorg/core/company.py:315 (Team class), web/src/api/types.ts:610 (TeamConfig interface).
• Related template-pack flow (out of scope here but will need a naming update): web/src/pages/org-edit/PackSelectionDialog.tsx.
• Observed during the Base UI migration worktree testing (PR feat: migrate web dashboard from Radix UI to Base UI + activate CSP nonce + personality trimming WS notification #1074), which improved the "No teams configured" placeholder into the current explanatory text.