Team Manager

Team Manager

Intro

TeamMembers are the persistent participants in the project — humans, named AI personas, and services — that accumulate identity, personality, and tiered memory over time. This skill owns their lifecycle: creation, memory tree scaffolding, a curated international name pool, A2A-compatible Agent Cards, export/import bundles, and 10 consistency checks.

Unlike ephemeral worker invocations (role+seniority dispatches resolved on the fly and never persisted), TeamMembers live as directory trees on disk: persona.md + card.json + team-member.md (entity) + tiered memory subdirectories + optional private/ (gitignored).

MCP server. This skill ships a self-contained MCP server at mcp/server.py (PEP 723 script — requires uv and Python ≥ 3.10 on PATH). Agent harnesses reach its tools by reading a single MCP config file at startup, so the contents of mcp/mcp-config.json must be merged into the harness's MCP config and placed at the harness-specific path before this skill is usable.

Overview

Invocation surface

This skill is not a CLI; it is reached entirely via MCP tools served by mcp/server.py. Fifteen tools cluster into five capability groups (lifecycle, name pool, memory scaffolding, export/import, consistency). Every write tool logs an event-log entry and updates the SQLite index automatically — callers do not log or reindex by hand. Read tools (get_team_member, list_team_members, list_available_names, suggest_name, check_consistency) are side-effect-free and safe to call from any agent context.

Capability groups

Common workflows

Adding a human contributor. create_team_member(type="human", slug="alice-chen", ...) → init_memory_tree(slug) → optionally seed persona.md and a starter relations/ file. No name-pool interaction; humans use any valid kebab-case slug.

Adding a named AI persona. suggest_name(kind="neutral") → create_team_member(type="ai-agent", slug=<name>, ...) (auto-reserves the name) → init_memory_tree(slug) → write persona.md and the A2A-compliant card.json. The name is now drawn from the pool and must remain in data/name-pool.yaml until released.

Retiring a persona. deactivate_team_member(slug, reason) (sets active: false; preserves history) → optionally release_name(name) to return the slug to the pool. To bring the persona back, call reactivate_team_member(slug).

Migrating a persona between projects. export_team_member(slug) → ship the tarball → at the destination import_team_member(tarball_path). Schema and Agent Card are re-validated on import; signature presence is required (crypto verification is deferred).

Pre-release audit. check_all_consistency() → triage findings by severity. Errors block release; warnings are advisory.

Mental model

A TeamMember is a directory tree on disk, not a row in a database. The entity file (team-member.md / team-member.yaml frontmatter) is the SQLite-indexed object; persona.md, card.json, and the six tier subdirectories live alongside it as durable, human-editable context. Humans/services have no name-pool requirement; AI personas do. TeamMembers are distinct from ephemeral worker invocations — those are resolved on the fly by task-router against role+seniority and never persist as TeamMembers.

Pointers to the full reference

The ## Full reference section below covers the MCP tool contract, the SQLite-index schema fields, the data/name-pool.yaml document format, the consistency check codes in greater detail, the export bundle layout, the migration path from actor-profile (DEC-20260422_0233-SpryTulip), and the corner cases for memory sensitivity tagging. Read it before extending the skill or changing any tool's contract.

ID convention

TeamMember IDs follow a single shape:

TEAMMEMBER-<slug>

where <slug> is the team-member's canonical kebab-case name (e.g. atlas, alice-chen, thrifty-otter). The slug starts with a letter and uses only [a-z0-9-]. It is also the directory name under context/team-members/<slug>/.

For type=ai-agent, the slug must be drawn from the team-manager name pool (see Name pool below). For type=human and type=service, any valid kebab-case slug is accepted.

TeamMember types

Do not promote every mention of a person into a TeamMember. And do not create a named AI persona for a one-off dispatch — use an ephemeral role+seniority invocation instead.

Memory tiers

Every team-member directory contains six tier subdirectories under context/team-members/<slug>/:

Plus private/ (optional, developer-local, gitignored) and three top-level files: persona.md (identity + personality prompt), card.json (A2A Agent Card), team-member.md (the entity itself).

Every memory file under a tier subdirectory must carry a frontmatter block validated against assets/memory-file-header.schema.json — required keys: tier, source, sensitivity, created.

Name pool & international naming policy

The name pool lives at data/name-pool.yaml (managed by this skill). It contains three gender-bucket lists (feminine, masculine, neutral) of international, short, human-friendly first names — ~60 total. Names from the pool are the canonical identifier source for AI personas.

Reservation lifecycle

• suggest_name(kind?) — pick a random available name, optionally filtered by gender bucket. Does not reserve.
• reserve_name(name, team_member_slug) — mark a name taken by a specific slug. Writes to data/name-pool.yaml atomically.
• release_name(name) — remove the reservation (e.g. on team-member deletion or re-export).
• list_available_names(kind?) — enumerate non-reserved names.

For create_team_member(type="ai-agent", ...), the slug must correspond to a name currently in the pool. The tool auto-reserves on success.

Consistency checks

check_consistency(slug) returns findings for a single team-member; check_all_consistency() aggregates across every team-member.

Each finding is {severity, code, team_member, path, message}. Codes:

Export / import

export_team_member(slug, output_path?) builds a tar.gz bundle at <slug>-export-<YYYY-MM-DD>.tar.gz containing:

• persona.md
• card.json (A2A Agent Card, conforms to assets/agent-card.schema.json)
• team-member.md (the entity)
• knowledge/, skills/, lessons/

Excludes journal/, relations/, private/ by default. During the memory-file walk, any file whose frontmatter declares sensitivity: confidential or sensitivity: pii is redacted (skipped).

import_team_member(tarball_path) extracts to a temp dir, validates the team-member.yaml against SCHEMA-team-member, validates card.json against the A2A Agent Card schema, and checks that a signature field is present on the card (crypto verification is deferred — signature field presence is a hand-off marker for future work). On success it copies the tree into context/team-members/<slug>/ and logs team_member.imported.

Deprecation note

This skill replaces actor-profile (DEC-20260422_0233-SpryTulip). The ACTOR-<slug> ID class and the create_actor/get_actor/etc. tools are deprecated in v0.19.0. A migration on context/actors/ runs in a separate phase; do not modify actor-profile from here.

Gotchas

• Creating a TeamMember for every mention. Reserved for persistent participants — the same rule as Actor. If they have no upcoming WorkItem/Binding/decision, don't promote them.
• Drawing an AI persona name outside the pool. team.name.off_pool will warn. Use suggest_name or list_available_names first.
• Putting confidential info outside private/. team.sensitivity.leak_risk catches it. The tier subdirectories are git-tracked; only private/ is safe for developer-local sensitive context.
• Hand-editing data/name-pool.yaml. Use reserve_name/ release_name — the tool preserves the document frontmatter and writes atomically.
• Forgetting init_memory_tree after create. create_team_member writes the entity but does not scaffold the tier subdirectories. Call init_memory_tree(slug) right after (or pass init_memory=True at create time, if implemented).
• Putting role+seniority dispatches here. Ephemeral worker invocations are NOT TeamMembers — they are resolved on the fly via task-router. Only persistent personas live in team-members/.

Full reference

MCP tool contract

All fifteen tools are served by mcp/server.py. Their tool annotations follow the processkit convention checked by release-audit.mcp_annotations:

mcp/SERVER.md documents each tool's full input/output schema including the JSON shape of create_team_member (slug, type, default_role, name, gender_kind, …) and the Finding schema for consistency checks ({severity, code, team_member, path, message}).

Entity schema

The TeamMember frontmatter is validated against SCHEMA-team-member (registered in context/schemas/). Required fields:

Optional fields used by templates: card_path (relative path to card.json), persona_path (relative path to persona.md), memory_root (relative path; defaults to the directory itself).

data/name-pool.yaml document format

---
schema: name-pool.v1
managed_by: SKILL-team-manager
updated: <ISO8601>
---
feminine:
  - name: aria
    reserved_by: TEAMMEMBER-aria   # null if available
    reserved_at: <ISO8601>         # null if available
masculine:
  - name: atlas
    reserved_by: null
    reserved_at: null
neutral:
  - name: kai
    reserved_by: null
    reserved_at: null

Atomic writes are produced by scripts/name_pool.py using a write-then-rename pattern; the document frontmatter (schema, managed_by, updated) is always preserved on round-trip. Hand edits silently break atomicity guarantees and are caught only by the next consistency check.

Memory tier directory layout

context/team-members/<slug>/
├── persona.md                   # Identity + personality prompt
├── card.json                    # A2A Agent Card (assets/agent-card.schema.json)
├── team-member.md               # Entity file (frontmatter is the schema target)
├── working/                     # Ephemeral, task-local
├── journal/                     # Daily entries; consolidated weekly → knowledge/
├── knowledge/                   # Stable semantic facts
├── skills/                      # Procedural recipes / patterns
├── relations/                   # One file per known teammate slug
├── lessons/                     # A-MemGuard-style consensus lessons
└── private/                     # Optional, gitignored, developer-local

Every memory file under journal/, knowledge/, skills/, relations/, lessons/, or private/ carries a frontmatter block validated by assets/memory-file-header.schema.json. Required keys: tier, source, sensitivity, created. Allowed sensitivity values: public, internal, confidential, pii. Files tagged confidential or pii outside private/ raise team.sensitivity.leak_risk.

Consistency check matrix (recap)

The 10 codes are split between hard errors (block release) and warnings (advisory). The corresponding implementation lives in scripts/consistency.py:

check_all_consistency() aggregates over list_team_members(active=true) and returns {summary: {errors, warnings}, findings: [...]}. Use the summary for CI gating; iterate findings for human-readable triage.

Export bundle layout

<slug>-export-<YYYY-MM-DD>.tar.gz
└── <slug>/
    ├── persona.md
    ├── card.json
    ├── team-member.md
    ├── knowledge/
    ├── skills/
    └── lessons/

Excludes working/, journal/, relations/, private/. During the memory walk, any file with frontmatter sensitivity: confidential or sensitivity: pii is skipped (redacted) regardless of which exported tier it lives in. Implementation: scripts/export_import.py::export_bundle().

Import contract

import_team_member(tarball_path):

1. Extract to a temp dir (cleaned on failure).
2. Validate team-member.yaml against SCHEMA-team-member.
3. Validate card.json against assets/agent-card.schema.json.
4. Require a signature field on the card (presence-only; cryptographic verification is a future-work hand-off marker).
5. Require the slug to be free locally (no collision with an existing TeamMember entity or active name-pool reservation).
6. Copy the tree to context/team-members/<slug>/.
7. For type=ai-agent, reserve_name(name, slug) is called as part of step 6.
8. Log team_member.imported via event-log.

Failures at any step abort cleanly — the temp dir is removed and no target-side state is mutated.

Migration from actor-profile (DEC-20260422_0233-SpryTulip)

actor-profile is deprecated as of v0.19.0; it is replaced by this skill. Do NOT modify actor-profile from here. The migration strategy is:

1. New write traffic targets create_team_member exclusively.
2. Existing ACTOR-<slug> IDs continue to be readable via the actor-profile MCP tools through the deprecation window.
3. A separate migration phase (tracked by its own MIG-* entity) converts each Actor under context/actors/ into a TeamMember under context/team-members/<slug>/, preserving ID history via replaces cross-references.
4. After the migration completes, the actor-profile skill is removed entirely; release-audit will then start flagging any remaining ACTOR-* references as dangling.

The frontmatter replaces: [SKILL-actor-profile] records the relationship; downstream skills should depend on team-manager, not actor-profile, in their uses: blocks.

Referenced source files

Extension points

• New TeamMember type. Add a new value to the type enum in SCHEMA-team-member, ship a template under assets/, extend the name-pool policy if a curated slug source is needed, and update the team.name.off_pool check to skip the new type if no curated pool applies.
• New memory tier. Add the directory to init_memory_tree, document it in the Memory tiers table, and extend check_orphans to recognise it. Decide whether export should include or redact it.
• New consistency check. Add a function in scripts/consistency.py returning list[Finding], register it in the dispatcher, and document the code + severity in the matrix above. CI surfaces it on the next release-audit run.

Corner cases

• Slug collision on import. Hard error; the importer never overwrites an existing TeamMember directory or reservation. To re-key a persona on import, rename the export tarball's inner directory + team-member.md slug field before importing.
• Name reserved with no TeamMember. Possible if a previous create_team_member failed after reserve_name but before entity write. Surfaced by check_all_consistency() as team.drift.dangling_ref against the pool. Resolve by release_name (manual triage, not auto-cleanup).
• private/ not gitignored. team.private.not_ignored warning. Add context/team-members/<slug>/private/ (or a glob parent) to .gitignore. The skill never writes .gitignore automatically — the warning is the action prompt.
• Card / entity drift. team.card.stale warning when card.json's name / role / seniority no longer match team-member.md frontmatter. Re-export and re-import is the blunt fix; targeted re-write of card.json is the surgical fix.
• Reactivating a deactivated member whose name was released. reactivate_team_member will re-reserve the name if it is still free; if another persona has taken it, the call errors and the caller must pick a new slug (or wait for the colliding persona to be deactivated).