Appearance

Team Meta-Repo — Shared Roles, Skills & Crews (Increment 1) ​

Status: EXPERIMENTAL (Increment 1). The team tier is opt-in and default-OFF — without --team nothing about your existing setup changes.

The team meta-repo feature lets a group of people share a single git repository of agents-fleet artifacts (roles, skills, crews, workflows, and project context/) and have every member's CLI compose them automatically. It adds a new team artifact tier that sits between your personal (user) tier and a code repo's (project) tier.

1. What it is ​

agents-fleet already loads artifacts from three tiers, in increasing priority:

bundled  <  user  <  project
  • bundled — the artifacts shipped inside the CLI (src/skills/bundled/).
  • user — your personal artifacts in ~/.fleet/.
  • project — a code repo's .fleet/ directory.

Increment 1 inserts a fourth tier — team — sourced from a shared git "meta-repo":

bundled  <  user  <  team(main)  <  team(member)  <  project

A code repo opts into a team by committing a small pointer file at .fleet/team.toml. When you launch with --team (and trust the meta-repo once), the CLI clones that meta-repo, loads its roles/ skills/ crews/ workflows/ into the team tier, and overlays any per-member personalization on top.

The whole path is gated: when --team is absent (or the meta-repo has not been trusted), the registry loads the legacy three tiers only and behavior is byte-identical to today (src/skills/SkillRegistry.ts:266, src/commands/resolveTeam.ts:48).

2. How it works ​

2.1 Tier precedence ​

Artifacts are keyed by kind:name and merged last-write-wins (src/skills/SkillRegistry.ts:258-268). The load order produces this effective precedence (lowest → highest):

TierSourceNotes
bundledCLI internalsalways loads
user~/.fleet/always loads
team(main)meta-repo main branchloaded only when enabled + trusted
team(member)meta-repo members/<name> branchoverlays team(main)
project<repo>/.fleet/still wins over everything

Two key consequences:

  • The member overlay overrides team-main with no special merge logic: both passes carry source: 'team', and the member branch loads second, so a same-named member artifact replaces the main one (src/skills/SkillRegistry.ts:260-268).
  • Project still wins. The project tier loads last, so a repo can always override a team artifact locally.

The team tier is V2-only — it loads *.role.md, *.skill.md, *.crew.md, and *.workflow.md from roles/ skills/ crews/ workflows/ (src/skills/SkillRegistry.ts:464-482); legacy v1 files in the meta-repo are ignored (src/skills/SkillRegistry.ts:486-489).

2.2 Clone & sync ​

The TeamSyncEngine (src/teams/TeamSyncEngine.ts) maintains a content-addressed checkout under ~/.fleet/teams/<sha256(repoUrl)[:12]>/:

  • main/ — the main (or configured source.ref) branch.
  • members/<name>/ — your own overlay branch, when a [member] is configured.

It clones with git clone --single-branch --branch <ref> and refreshes with git fetch origin <ref> + git checkout <ref> + git pull --ff-only (src/teams/TeamSyncEngine.ts:140-155). It only ever fetches main and yourmembers/<name> branch — never sibling member branches — so a meta-repo with N members never causes any one member to fetch O(N) branches (src/teams/TeamSyncEngine.ts:50-55).

Sync is offline-tolerant: any git/network failure is non-fatal — the engine logs a dim warning and falls back to the last cached clone (offline: true), never throwing, so startup can't be blocked by a transient error (src/teams/TeamSyncEngine.ts:115-121).

2.3 Trust model (TOFU) ​

A meta-repo is remote, shared code — its artifacts are composed into worker prompts. Before the team tier ever loads, the CLI requires a one-time Trust-On-First-Use (TOFU) assertion (src/teams/teamTrustStore.ts:8-37):

  • On first use you must pass --trust-team (or AGENTS_FLEET_TRUST_TEAM=1).
  • A fingerprint is then pinned on disk at ~/.fleet/teams/<hash>/.trust as { repo, fingerprint: sha256(repoUrl), trustedAt } (src/teams/teamTrustStore.ts:86-124).
  • Later runs auto-trust the same repo without the flag (src/teams/teamTrustStore.ts:144-147).
  • If the configured repo URL later diverges from the pinned fingerprint, the tier is blocked until you re-assert --trust-team (src/teams/teamTrustStore.ts:149-157).

Trust binds to the source URL, not a fetched HEAD sha — so legitimate upstream commits don't force a re-confirm (src/teams/teamTrustStore.ts:29-36). When enabled but untrusted, a dim one-line warning is printed and the tier simply does not load (src/commands/resolveTeam.ts:119-131).

3. Setting up a meta-repo ​

A team meta-repo is an ordinary git repository with this layout on its main branch:

acme-fleet-meta/
├── team.toml          # describes the repo to itself (optional but conventional)
├── roles/             # *.role.md
├── skills/            # *.skill.md
├── crews/             # *.crew.md
├── workflows/         # *.workflow.md
└── context/           # shared project-context files (markdown/data)

Branch model ​

BranchPurpose
mainthe canonical, reviewed team artifacts (team(main) tier)
members/<name>one branch per member, holding personal overlays

main is everyone's shared baseline. Each member works on their own members/<name> branch, which overlays main. Promotions flow members/<name> → main via pull request (see /team-repo promote).

Worked example: agents-fleet-meta ​

A real example lives at vriveras/agents-fleet-meta (private). Its main branch carries team.toml plus roles/ skills/ crews/ workflows/ context/, and a members/alice branch carries Alice's overlay.

The team.toml schema ​

team.toml is a flat TOML file with three sections. Only [source].repo is required — everything else has a default (src/teams/teamPointer.ts:74-131):

toml
[source]
# REQUIRED — the meta-repo URL (ssh, https, or file://).
repo = "https://github.com/vriveras/agents-fleet-meta.git"
# Optional — branch/ref for the shared baseline. Default: "main".
ref = "main"
# Optional — sub-path within the repo to load artifacts from.
# Default: ".". Any ".." segment is rejected for traversal-safety.
path = "."

[sync]
# Optional — whether the tier syncs on launch. Default: true.
autoSync = true
# Optional — minimum minutes between background syncs. Default: 0.
intervalMinutes = 0

[member]
# Optional — your overlay branch (members/<name>). Omit for read-only use.
name = "alice"
FieldSectionRequiredDefaultSource
repo[source]yes—teamPointer.ts:97-101
ref[source]no"main"teamPointer.ts:103-104
path[source]no"." (rejects ..)teamPointer.ts:106-112
autoSync[sync]notrueteamPointer.ts:114-116
intervalMinutes[sync]no0teamPointer.ts:117-118
name[member]no(none → read-only)teamPointer.ts:125-128

When [member] is omitted the pointer is read-only — you consume the shared main artifacts but publish nothing.

4. Using it in a code repo ​

4.1 Add the pointer ​

In the code repo you want the team artifacts available in, create .fleet/team.toml. The fastest way is /team-repo init (below). Commit it so every teammate inherits the same pointer.

4.2 Enable the tier ​

The team tier is opt-in and requires two things on first use:

  1. Enable — --team flag, or AGENTS_FLEET_TEAM=1 (src/index.ts:164, src/commands/resolveTeam.ts:42-46).
  2. Trust — --trust-team, or AGENTS_FLEET_TRUST_TEAM=1, the first time (src/index.ts:165, src/commands/resolveTrustTeam.ts:30-34).
bash
# First launch — enable + trust the meta-repo (TOFU is pinned after this)
agents-fleet --team --trust-team

# Subsequent launches — trust is remembered for the same repo
agents-fleet --team

Both env vars require the strict literal 1 (e.g. 'true' is ignored) (src/commands/resolveTrustTeam.ts:13-15).

Advanced / air-gapped: you can bypass clone + TOFU entirely by pointing at already-local checkouts via AGENTS_FLEET_TEAM_DIR (and AGENTS_FLEET_TEAM_MEMBER_DIR). When set, the sync and trust gate are skipped (src/commands/resolveTeam.ts:52-54, :97-98).

4.3 The /team-repo command ​

/team-repo (alias /meta) manages the meta-repo from inside a session (src/commands/teamRepoCommand.ts:160-186). All mutating subcommands refuse to run unless the team feature is enabled and the repo is trusted.

/team-repo [init|sync|push|promote|status] [args]

init ​

Writes .fleet/team.toml in the current repo. Errors if the file exists unless --force is passed (src/commands/teamRepoCommand.ts:189-250).

/team-repo init https://github.com/vriveras/agents-fleet-meta.git --member alice
/team-repo init <repo-url> [--member <name>] [--ref <ref>] [--path <subpath>] [--force]
  • --member <name> — also writes a [member] section.
  • --ref <ref> — source.ref (default main).
  • --path <subpath> — source.path (default .).
  • --force — overwrite an existing team.toml.

status ​

Shows the feature flag state, the parsed pointer, trust state, and whether the clone is present on disk. Works even when the feature is disabled (src/commands/teamRepoCommand.ts:253-294).

/team-repo status

sync ​

Clones (or fetches + fast-forwards) the meta-repo and reports the resolved main / member checkout dirs. Offline failures fall back to the cached clone (src/commands/teamRepoCommand.ts:297-333). Requires the feature enabled and the repo trusted.

/team-repo sync

push ​

Commits your local team-tier edits in the members/<name> checkout and pushes them to your members/<name> branch (src/commands/teamRepoCommand.ts:336-398). Requires a [member] to be configured and a prior sync.

/team-repo push -m "Add alice-coder role"
/team-repo push [-m "<message>"]

If no message is given it defaults to team-tier update <timestamp>.

promote ​

Opens a pull request from members/<name> → main (your source.ref) using the gh CLI. If gh is unavailable it prints the manual PR instructions instead (src/commands/teamRepoCommand.ts:401-471).

/team-repo promote --title "Promote alice-coder to the team"
/team-repo promote [--title "<title>"]

5. Member overlays ​

A members/<name> branch lets you personalize or override the shared baseline without touching main. Because the member pass loads after team-main and before project, your overlay:

  • overrides a same-named main artifact (e.g. tweak team-conventions), and
  • adds new artifacts visible only to you (e.g. an alice-coder role),

while the project tier can still override your overlay locally.

Worked example — Alice ​

Alice's members/alice branch in agents-fleet-meta does two things:

  1. Overrides team-conventions — she ships a skills/team-conventions.skill.md on her branch. Because her overlay loads after main, her version wins for her sessions; teammates still see the main version.
  2. Adds alice-coder — a personal roles/alice-coder.role.md that only exists on her branch.

Her workflow:

bash
# .fleet/team.toml has [member] name = "alice"
agents-fleet --team --trust-team
/team-repo sync                 # clones main + members/alice
# …edit roles/alice-coder.role.md, skills/team-conventions.skill.md in the member checkout…
/team-repo push -m "Add alice-coder; tweak team-conventions"
/team-repo promote --title "Promote alice-coder to the team"   # when ready to share

After promote merges to main, the artifact graduates from Alice's overlay to everyone's shared baseline.

6. Bundles V3 ​

Bundles (export/import of artifact sets) gained a V3 manifest to complement the meta-repo flow (src/skills/bundle.ts:52-58):

  • crew is now optional — a bundle may carry standalone roles/skills with no owning crew (src/skills/bundle.ts:55, :173-225).
  • New context artifact kind — opaque project-context files (markdown/data) travel in context/<name>. They have no frontmatter parser; import writes the bytes verbatim after verifying the per-artifact sha256 (src/skills/bundle.ts:43-58, :202-204).

V2 back-compat is preserved. validateManifest dispatches on bundleVersion and accepts both "2" and "3"; existing V2 bundles import unchanged (src/skills/bundle.ts:88-122).

7. Backward compatibility & migration ​

No migration is required. The team tier is opt-in and default-OFF:

  • Without --team / AGENTS_FLEET_TEAM=1, resolveTeam returns { trustTeam: false } and the registry loads the legacy three tiers — behavior is byte-identical to before (src/commands/resolveTeam.ts:48-50, src/skills/SkillRegistry.ts:266).
  • Even with --team, the tier loads only when a .fleet/team.toml pointer exists and the meta-repo is trusted; otherwise it is silently skipped (src/commands/resolveTeam.ts:95-131).
  • A repo with no team.toml is completely unaffected.

8. Security notes ​

The team tier treats a meta-repo as untrusted remote code and constrains it accordingly:

  • TOFU trust gate — the tier never loads until you explicitly assert --trust-team once; the binding is pinned and re-checked every run (src/teams/teamTrustStore.ts:139-157). A divergent repo URL re-blocks the tier until re-confirmed.
  • Private repos use ambient git credentials — the engine shells out to your local git, so cloning a private meta-repo relies on whatever credentials (SSH keys / credential helper) git already has. agents-fleet stores no meta-repo secrets (src/teams/TeamSyncEngine.ts:140-155).
  • SEC-4 privilege clamp — team roles are not in the trusted set. Like project roles, a team role may only narrow (or keep) an agent's privileges, never escalate them (src/fleet/permissions.ts:36-46).
  • Path-traversal safety — a source.path containing any .. segment is rejected and reset to . so a hostile pointer can't escape the checkout root (src/teams/teamPointer.ts:108-112).

See also ​