Team

Persistent project-level collaboration: team.json, rules.md, and team agents.

A Team is a persistent, project-level collaboration unit. Unlike a standalone agent — which is stateless and one-shot — a team keeps sessions and memory across conversations, making it the right layer for ongoing projects.

When to Use a Team

  • A project area that needs long-lived coordination across multiple roles
  • Work that must remember decisions between sessions
  • A recurring need for the same set of roles (lead + members)

Directory Layout

teams/<name>/
├── team.json     # Definition (required)
├── rules.md      # Project knowledge injected into all members
└── agents/       # Team-scoped agents (self-contained, no extends)

team.json

{
  "name": "nebflow-website",
  "description": "Nebflow website (nebflow.space) optimization and maintenance.",
  "lead": "Manager",
  "members": ["Frontend", "Designer"],
  "flows": []
}

| Field | Type | Description | |-------|------|-------------| | name | string | Unique team name | | description | string | What the team owns | | lead | string | The team lead agent — receives routed mail | | members | string[] | Member agents (may reference global agents) | | flows | string[] | Flows this team may invoke |

rules.md

Every member of the team gets rules.md injected into its system context. This is where project knowledge lives:

# Project Rules

## Tech Stack
- Backend: Scala 3, Pekko actors, http4s
- Frontend: Vanilla JS + CSS

## Routing
- Backend code → Mail "Backend"
- Frontend code → Mail "Frontend"

## Git
- Never commit to main directly
- Work on feature branches

Keep rules concise — they are loaded into every member's context on every session, so length adds cost.

rules.md vs Agent Memory

The two knowledge stores have distinct owners:

  • rules.md — written by the team owner (you). Hard rules: workflows, boundaries, standards. Changes are deliberate.
  • Agent memory (agents/<name>/memory.md) — written by the agents themselves. Factual records: what was done, key decisions, lessons learned. Evolves continuously.

Rules tell members how to behave; memory tells them what happened.

The Manager Pattern

The lead agent is a coordinator, not an implementer. Its job:

  1. Receive — mail addressed to the team name lands on the lead
  2. Decompose — break the task into member-sized pieces
  3. Dispatch — route work to members by capability via Mail
  4. Accept — review deliverables against the task's acceptance criteria
  5. Report — synthesize member results into one answer for the caller

The lead does not write code itself — implementation always goes to a member. This keeps coordination context separate from working context, so neither pollutes the other.

Emergent Collaboration

Members are not limited to talking through the lead. Within a team, members mail each other directly (short-name addressing) for:

  • Pairing — aligning on interfaces, field formats, or a shared plan
  • Handoff — delivering finished work straight downstream (e.g. implementation → QA), with acceptance conditions attached
  • Review — asking another member to independently check output, returning PASS/FAIL with evidence
  • Rejection — sending failed work back to its author with itemized issues

The lead stays informed via CC on key events (QA verdicts, unresolved disagreements, cross-cutting decisions) but does not relay every message. Cross-team collaboration goes through upper-layer routing (Nebula), not direct member-to-member mail.

Team Agents

teams/<name>/agents/ holds agents that only exist within the team. They are:

  • Self-contained — no extends; each is a full agent definition
  • Scoped — not directly delegatable outside the team
  • Context-aware — when activated, the team's rules.md and session context are injected

This keeps team-specific workers (e.g. a "release-manager" that only makes sense for this project) from polluting the global agent registry.

Activation

When a team is mounted (e.g. after a restart), Nebflow:

  1. Loads team.json and mounts the lead + members as agent sessions
  2. Injects rules.md into each member's context
  3. Restores each member's persistent session history

Members then collaborate via Mail, exactly like standalone agents, but with shared project context and durable memory.

Invoking Flows

A team lists the flows it may invoke in flows. Invoking a flow from within a team renders as an inline widget in the team card, keeping the team's workflow contained.

Team vs Agent vs Flow

| | Agent | Team | Flow | |--|-------|------|------| | State | Stateless | Persistent sessions | Fresh per run | | Scope | Global / team / flow | Project-level | Fixed pipeline | | Invocation | Mail("name", ...) | Through team | Triggered by name | | Memory | None by default | rules.md + sessions | None (input templated) |