goldengooseAI coding agent workspace

How It Works

Team Management

Run multiple agents through one persistent team with stable membership and lead semantics.

goldengoose has one persistent team shell. You add agent threads to that team, designate a lead, and coordinate the roster through one Team Comms stream.

The singleton invariant

  • The team shell exists on fresh startup even when it has no members.
  • An empty shell has no lead.
  • The first member added becomes lead automatically.
  • Every non-empty roster has exactly one lead, and that lead is a current member.
  • Removing the final member leaves the same empty shell in place.
  • There is no create, delete, list, switch, transfer, or team-selection workflow.

This is more than a UI convention. The Rust runtime owns one aggregate and the public tool and Tauri contracts never expose its private durable instance identity. Focus can move between a team member, a teamless thread, or no thread without selecting a different team.

Why teams are useful

  • Parallelism: run research, implementation, review, and docs work together.
  • Specialization: pick different providers and models for different roles.
  • Coordination: send tasks directly, broadcast shared context, and track delivery.
  • Visibility: inspect one durable roster and one Team Comms feed.

Typical workflow

  1. Add or join the first member; it becomes lead of the persistent team.
  2. Add specialist members such as a planner, frontend implementer, reviewer, or docs writer.
  3. Ask the lead to delegate with gg_message and inspect progress with gg_team status mode.
  4. Review member threads and the shared Team Comms stream.
  5. Remove members when their work is complete; the shell remains available for the next task.

Native worktree behavior

gg_team add mode accepts an optional worktree_name:

  • If the named managed worktree does not exist, gg creates it and associates the new member as owner.
  • If the named managed worktree already exists and is eligible, gg reuses it and adds the member as a consumer.
  • If no name is supplied, no native worktree create/reuse is requested.

Newly created worktrees run .agents/gg/worktree-init.sh before session creation when the script exists. Reuse and inherited-consumer paths do not run worktree init. Ambiguous ownership, unrecoverable journals, or unsafe native state fail closed rather than guessing.

For the exact bootstrap contract, see Configure: Worktree Init.

Roles and permissions

  • The lead can add or remove members.
  • Preferences can allow non-lead members to add or remove members.
  • Lead reassignment selects a current member of this roster.

Allowing non-leads to manage membership enables deep delegation while the organization remains flat and observable in one roster.

Tips for smooth coordination

  • Keep tasks small and measurable.
  • Use model presets so a role consistently starts with the expected provider and model.
  • Put repo-specific conventions in Lead Instructions.
  • Use the same worktree_name when another member should inspect an existing managed worktree.