Assistant Teams Module

The Teams module is a bolt-on system for ad-hoc, collaborative agent teams assembled for specific missions — research, audits, development, analysis, and content creation.

Overview

Teams follow the same architectural pattern as AntFarm (project workers) and Business Hive (corporate hierarchy), using the TeamManager agent as the orchestration layer. Unlike the other systems, Teams are designed for:

Ad-hoc assembly: Create teams on-demand for any purpose
Flexible duration: Temporary (one-off) or permanent (ongoing) teams
Mission-focused: Each team has a specific mission statement
Heartbeat wake: Permanent teams can be woken periodically to execute default tasks

Team Types

Type	Behavior	Use Case
Permanent	Persists on disk, archived when disbanded, can be reactivated. Supports `default_task` for heartbeat wake.	Ongoing monitoring teams (SOC, NOC), content teams (YouTube), recurring audits
Temporary	Fully deleted when disbanded. No heartbeat wake.	One-off research, single audits, event-specific tasks

Team Modes

Mode	Behavior	Member Personas
Execution	Members execute assigned tasks in parallel, report progress, submit findings	contributor, auditor
Research	Members investigate independently, compile findings, synthesize report	researcher, analyst

Member Personas

Each team member is assigned an agent persona that defines their behavior:

Persona	Purpose	Default Model
researcher	Information gathering and synthesis	`openrouter/z-ai/glm-4.7`
analyst	Data analysis and trend identification	`openrouter/z-ai/glm-4.7`
auditor	Security and compliance analysis	`openrouter/z-ai/glm-4.7`
reviewer	Quality assurance and peer review	`openrouter/z-ai/glm-4.7`
contributor	General-purpose task execution	`openrouter/z-ai/glm-4.7`

Tool Access

Team members have access to:

Category	Tools
Team Tools	`tm_report_status`, `tm_submit_finding`, `tm_shell`, `tm_write_file`, `tm_read_file`
Shared Tools	`brave_web_search`, `scrape`, `manage_notes`, `get_weather`, etc.
Skill-Injected	Any tools specified in `required_tools` of assigned skill (cross-hive bypass)

Heartbeat Integration

Permanent teams can be woken by the system heartbeat to execute periodic tasks:

Every 3 hours:
  triggerTeamHeartbeat()
    → Scans all permanent teams with status=active
    → For each member with a default_task defined:
        → Spawns session if not already active
        → Executes default_task
        → Member submits findings via tm_submit_finding

This enables "always-on" monitoring teams without manual intervention.

Logging Architecture

Teams use a three-tier logging system:

Tier	Location	Format
stdout	Console	`[TEAM]` prefixed logs
Daily Log	`logs/teams/teams_YYYY-MM-DD.log`	JSON with metadata
Team Log	`teams/{user}/{teamID}/execution_log.md`	Markdown, human-readable
Observability	SQLite ObservabilityDB	Structured events (if available)

Component Diagram

graph TD
    User([User Request]) --> Nikki[Nikki/Planner]
    Nikki --> TM[TeamManager Agent]
    
    TM --> Create[tm_create_team]
    Create --> Add[tm_add_member]
    Add --> Assign[tm_assign_task]
    
    subgraph "Team Members"
        Assign --> M1[Researcher Session]
        Assign --> M2[Analyst Session]
        Assign --> M3[Auditor Session]
    end
    
    M1 --> Findings[tm_submit_finding]
    M2 --> Findings
    M3 --> Findings
    
    Findings --> Collect[tm_collect_findings]
    Collect --> Synth[tm_synthesize]
    Synth --> Result([Final Report])
    
    subgraph "Heartbeat (Permanent Teams)"
        HB[System Heartbeat] --> Wake[triggerTeamHeartbeat]
        Wake --> M1
    end

Persistence

Teams are stored per-user on disk:

teams/
├── {user}/
│   ├── {teamID}/
│   │   ├── team.json           # Team metadata
│   │   ├── execution_log.md    # Markdown execution log
│   │   ├── workspace/          # Team member files
│   │   └── state/
│   │       └── actions.jsonl   # Audit trail

Key Files

File	Purpose
`assistant/teams.go`	Core data structures, lifecycle, persistence, tool handlers
`assistant/heartbeat.go`	`triggerTeamHeartbeat()` for permanent team wake
`assistant/prompts/agent/teammanager.md`	TeamManager agent persona
`assistant/prompts/tools/teammanager/*.md`	TeamManager tool definitions
`assistant/prompts/tools/team/*.md`	Team member tool definitions
`assistant/TEAMS.md`	Architecture design document

Related Systems

System	Purpose	Comparison
AntFarm	Project-based swarm execution	Workers assigned to project workspaces, Queen orchestrates
Business Hive	Corporate hierarchy management	CEO/Director/Worker structure, ticket tracking, approvals
Teams	Ad-hoc mission-focused collaboration	Flexible, mission-driven, supports temporary teams

Pre-Seeded Teams

The system comes with three pre-configured permanent teams:

Team	Members	Heartbeat	Purpose
Security Posture Monitor	3	Every 3h	UniFi IDS/IPS, SSH logs, firewall monitoring
Content Production Team	3	None	YouTube content creation (on-demand only)
Company Security Audit Team	4	Every 3h	CVE scans, patch compliance, config audits

See Pre-Seeded Teams for full documentation.