API Reference — AgentTeamsModule

Public API for the agentteams package. Each module corresponds to a stage in the pipeline or a support capability.

This reference defines the supported public API surface (documented modules and symbols). Modules and symbols not documented here are considered internal and may change without notice. Behavioral details may evolve between releases; check CHANGELOG.md for compatibility notes.

---

Pipeline Modules

Module	Role
ingest	Load and normalize project description files
analyze	Classify project type, select archetypes (including contextual post-production selection), build team manifest
analyze_tools	Tool importance classification + tool/reference-doc detection (carved from analyze)
tool_version_source	Tool versions read from the target project's pin file (tools[].version_source)
manifest_format	Manifest field derivation/formatting helpers (format/default/collect*) — carved from analyze
render	Resolve templates and produce rendered agent file content
emit	Write rendered agent files to disk safely
fences	Section-fencing internals (regexes, MergeResult, fenced merge, shrink detection) — carved from emit
fence_twins	Drops an unfenced pre-fencing copy of a fenced section only on proof (git-derived lineage corpus or the fenced copy); keeps and flags the rest
fence_twin_acks	Operator ledger that acknowledges a kept twin: it turns that twin's fleet REVIEW into a notice, is bound to the twin's exact text and never drops anything
whole_body_migration	Retires a legacy whole-body content fence beside the fences the render still has, keeping or flagging non-template text; reports a section present twice

Core Support Modules

Module	Role
convert	Direct format migration between framework outputs
interop	Canonical Agent Interface (CAI) interop pipeline
bridge	Lightweight runtime compatibility bridge artifacts
team_package	Portable team package: a durable canonical directory plus its generic bridge, zipped for a repo with zero agentteams integration
cli	CLI package decomposition — which module owns which stage (flags live in the CLI Reference)
output-plan	Plans which files a manifest produces, before anything renders
update-report	update.report.md — durable record of an --update run's decisions
fleet	Multi-workspace --update --merge (--fleet DIR) with git snapshot + diff audit
drift	Detect template-to-instance drift for incremental updates
behavioral-drift	Detect behavioral divergence in agent runs vs. specification

Audit & Security Support

Module	Role
scan	Proactive security scan for generated agent files
scan-operational	Which pipeline-written JSON (incl. listed memory-index shards) the scanner exempts; integrity-pinned
env_hygiene	.env files are gitignored and kept out of Docker build contexts (audit + append-only --fix)
redteam	The agentteams/redteam/ package — audit internals + corpus coverage/density (F2). The model-scoring + attack-generation scripts are in the Red-Team Model Scoring & Attack Generation guide
session_scan	Repo at-large issue scan (CHANGELOG Known Issues, plan-steps pending/blocked, git status) for orchestrator closeout
audit	Post-generation static and AI-powered audit
integrity	Hash manifest over the modules that enforce the constitution itself
feature_audit	Verifies features documented in Feature Inventory still function, via the machine-readable feature registry
living-doc	Living-document conformance (Rule 7) over unfenced agent prose
remediate	Auto-correct audit findings via standalone Copilot CLI
security-refs	Build live security intelligence placeholders for templates
framework-research	Detect upstream framework drift; transmit via --update --merge; supervised-PR auto-update path
framework-conformance	Standard ≤24h agent-infra conformance check — route @framework-adapters-expert on real drift (agentteams --agent-check)
framework-freshness	Cross-framework render-staleness scan — report which provider renders lag the current templates (--framework-freshness)

Enhancement & Enrichment

Module	Role
enrich	Default-value audit and context-aware placeholder enrichment
memory-index	Lexical (BM25) search index for work summaries and documentation
memory-index-incremental	In-place single-document index patching; declines conservatively to a full rebuild
memory-index-store	On-disk layout of the committed index: compact lines, size-capped native shards read without reassembly
fence-inject	Inject and extract fenced-region content from agent files
code-index	Code & API index over repository scripts and the external APIs they use (gitignored local cache)
code-sources	Source resolution and partitioning for the code & API index

Agent & Team Analysis

Module	Role
graph	Directed graph inference for agent team topology
architecture	Module-dependency map of a repository's own Python package, built from its imports
git-hooks	Commit-triggered refresh of the topology and architecture maps (--install-git-hooks); blocking env-file guard
model-routing	Framework-neutral model-routing contracts for cost/capability tiering
eval_suite	Build behavioral evaluation specs for agent team runs
eval-adapters	Convert neutral eval-suite contracts into Inspect AI and OpenAI Evals artifacts

Manifest & Documentation

Module	Role
frameworks	Per-framework adapter classes
man	Generate and validate the project man-page source
handoff_payloads	Typed handoff payload substrate for plan .steps.csv artifacts
plan_steps	Tolerant reader for plan .steps.csv artifacts
plan_steps_todo	TodoWrite projection of plan .steps.csv (CSV is canonical; TodoWrite is the projection)
liaison_logs	Cross-repository coordination logs and artifacts
mcp_need	Agent MCP-need protocol under the orchestrator-only switch: the procedure reference and the need register
mcp_catalog	The catalogue of foundational MCP servers (agentteams/templates/mcp/) and its expansion into mcp_servers
governance_logs	Well-formedness check (--verify-integrity) and the validated, append-only append_row for the governance CSV logs
mcp_servers	--serve-mcp: the first-party read-only servers recall and gitread
mcp_need_report	--mcp-need-report: read-only per-agent summary of the runner ledger and the need register (protocol phase N3)
control_plane_io	Write-if-absent sandbox roster stubs and the in-sandbox write preflight
signing_switch	The one writer of references/agent-privilege.json: an owned switch tracks the description, an unclear one is kept, a relax is a fleet REVIEW
projection_marker	The origin: "interop" team marker an interop / multi_sync projection writes, control plane first
team_dir_advisories	Generation-time advisories for planted team markers and planted Codex config keys (detection only)
prompt_roots	Prompt-root change detection: per-fence hashes in the build-log, PROMPT-ROOT CHANGED warning, --strict-prompt-roots (detection only)
parallel_plan	Parallelisation analysis over a plan's depends_on column
feature_inventory	Generated inventory of the shipped feature surface
front_matter_reconcile	Report (and optionally apply) template-vs-deployed YAML front-matter divergence
front_matter_baseline	The three-way front-matter merge's baseline (what agentteams authored, version 2) and the guard that restores dropped hand-written handoffs
template_pins	Trust root for installed template digests (--pin-templates)

Host Features & Bridge Emission

Module	Role
host_features	Parse / validate <ns>:<feature> opt-in subselector tokens for emission gating
Workspace Privilege Scoping	Opt-in privilege_profile / claude:sandbox — emit Claude Code's OS-level write-confinement sandbox (feature page)
rank_conformance	AP-2 rank-conformance validator — an agent's declared tools: must not exceed what its taxonomy rank (orchestrator / governance / domain / expert) permits (C-3)
baseline	Deterministic SHA-256 emission baselines (capture / diff) used by regression tests
bridge_subagents	Per-agent Claude subagent stub emitter (bridge:copilot-vscode-to-claude:subagents)
proposals	Orchestrator-only-writes pilot (P1): apply typed change proposals and run typed command requests under per-agent policy; hash-chained ledger
confinement	Orchestrator-only-writes pilot (P4b): run the runner's commands and gates in a Seatbelt/bwrap sandbox built from confined_programs
proposal_policy	Orchestrator-only-writes pilot: the registered policy (brief validation and lint), re-exported by proposals
mcp_direct_grants	Operator-signed direct-write grants: the only way an agent's MCP writes skip the orchestrator's approval (R5)
interop_write_policy	--interop-from --description: an import carries the brief's write_policy and mcp_grants, so adopted bespoke agents get the runner (M6)
interop_grant_check	--interop-from per-agent checks: a projection never widens a source grant, refuses a narrow grant on a surface that can't enforce it (unless --interop-allow-cooperative), and refuses an oversized Copilot body
runner_mcp	The agentteams_runner MCP server: how granted agents write and execute through the runner (R4)
proposal_staging	Staged and direct agent writes through the runner, and the orchestrator's approvals (R3)
proposal_run	The command-request half of proposals: validates, runs and checks one allowlisted, agent-requested command (carved out at R2)
proposal_runner	Orchestrator-only-writes pilot (P4a): the out-of-session runner that alone holds the ledger key and serves the orchestrator's queue
sealed_result	Seals the orchestrator's runner results (in the session-readable .agentteams-status/ tree) to the process that queued each request
git_exec	The one git core: argv, run, and the read-only hardening against repo-planted config
source_provenance	Which agentteams code is running (kind, commit, branch, dirty), recorded in build-log.json and printed by --version
user_regions	The user-editable Notes/Rules regions of generated files, carried across --overwrite (P5a)
write_policy	Orchestrator-only-writes pilot (P3): narrow generated non-orchestrator agents to read-only tools and add the proposal sections
adopted_agents	--adopt-orphans routing rows: adopted agents reach every orchestrator body (Claude included)
orphan_advisory	--update orphan-agent-file advisory: orphaned / bespoke-keep / bridge-managed-keep buckets
bridge_subagents_goose	Per-agent Goose stub-recipe emitter (bridge:<src>-to-goose:subagents)
bridge_sources	Source-team inventory, file collection, hashing + bridge-freshness check (framework-aware)
hooks_emit	Claude hooks settings + recursion-bounded guard emitter (bridge:copilot-vscode-to-claude:hooks)
instructions_split	Cache-aware CLAUDE.md layout: preamble + boundary + dynamic stanza (bridge:copilot-vscode-to-claude:cache-split)
schedule_emit	/schedule routine spec emitter (bridge:copilot-vscode-to-claude:schedule)
goose_config	Locate + safely mutate Goose's config.yaml for source/model switching (no key handling)
mcp_detect	Detect MCP server configuration available to the target host
mcp_emit	Emit MCP server wiring into generated teams
codex_mcp_emit	MCP server emission into Codex's .codex/config.toml
grok_config_emit	The agentteams-managed block in Grok Build's .grok/config.toml ([mcp_servers], control-plane [permission])
toml_write	Minimal hand-rolled TOML serializer bounded to what Codex's MCP config tables need
bridge_pair_docs	Prose renderers for the bridge's framework-agnostic pair-dir artifacts (carved out of bridge)
bridge_skills	Claude skill bodies emitted by the bridge (carved out of bridge)

Multi-Framework Pinned Sync

Module	Role
multi_sync	Pinned-sync orchestrator: keeps every agentic interface in sync through the canonical hub, pin authoritative on conflict
sync_pin	The pinned-source contract for multi-framework sync
sync_baseline	Real-content baseline snapshot writer for native ↔ canonical synchronization
sync_classifier	Generalized three-way classifier for native ↔ canonical synchronization
canonical	Durable exploded on-disk canonical agent format — the hub multi_sync reconciles through
capability_map	Canonical tool-scope vocabulary and framework ↔ canonical capability mapping, shared by interop and this family
agent_doc_sync	--sync-agent-docs: propagates each agent's AGENTTEAMS-LEARNED block across its .github/.claude/.goose copies (three-way baseline outside the project, content gates, no file creation)
learned_blocks	Pure-text parse/compose/verify of the learned block in markdown agent files and goose recipes
branch_inventory	--branch-inventory: read-only branch classification (ancestry, Merged-by-PR via the GitHub API, holds) and a leased deletion plan
project_notes	The USER-EDITABLE Project-Specific Notes section of agent personas (carved from emit)
shrink_allow	--shrink-allow: operator-reviewed per-section overrides of the shrink guard (template retirements vs enrichment)
branch_cleanup	--branch-cleanup / --branch-post-merge: guarded deletion under a plan-bound @security clearance or an operator Ed25519 branch-delete grant; hash-chained deletion ledger

Standalone Modules

Module	Role
pr_management	Recipient registry, gh-CLI wrappers, stale-PR scan, end-of-task three-way disposition prompt
research	Optional agentteams[research] extra: search, reputability scoring, claim verification

---

Typical Pipeline Usage

from pathlib import Path
from agentteams import ingest, analyze, render, emit
from agentteams.frameworks.copilot_vscode import CopilotVSCodeAdapter

description = ingest.load("brief.json")
manifest = analyze.build_manifest(description, framework="copilot-vscode")
rendered = render.render_all(manifest, templates_dir=Path("templates"))

# render_all() returns framework-agnostic content; adapters add framework-specific
# wrappers and metadata before emit.
adapter = CopilotVSCodeAdapter()
final = [(p, adapter.render_agent_file(c, Path(p).stem, manifest))
         for p, c in rendered]

result = emit.emit_all(final, output_dir=Path(".github/agents"), dry_run=False)
emit.print_summary(result, manifest)

render.render_all() does not apply framework-specific post-processing on its own. Use the appropriate adapter from agentteams.frameworks to convert rendered content into the final framework format before passing it to emit.emit_all().

---

Interoperability API Family

The interoperability feature family has four approaches, each a dedicated module or module group:

1. convert for format migration.
2. interop for CAI normalization and transfer.
3. bridge for lightweight, one-directional source-canonical runtime bridging.
4. Multi-Framework Pinned Sync (multi_sync and peers) for continuous, bidirectional multi-framework consistency through a canonical hub, rather than a one-directional mirror of a single source.

Bridge and pinned-sync solve related but different problems and are not layered on each other — pick bridge for a lightweight, one-directional mirror of one canonical source into another framework's directory (re-running to pick up source changes is a normal, supported workflow — see bridge.md's own Mode Selection Guidance); pick pinned-sync when every framework is a peer that needs to stay reconciled as any of them changes. For bridge's own workflow-level usage and mode selection, see the Interoperability page (which does not yet cover pinned-sync).

---

Coverage gaps

This index does not cover every module. 22 top-level public modules have no API page, listed here rather than left to be discovered:

advisory, ai_bad_habits, atomicio, audit_agent_contract, audit_types, backup, budget, capability_hints, errors, front_matter_merge, graph_inputs, interop_helpers, provenance, recipe_fields, security_feed_render, stale_detector, stale_remediate, svg_render, tool_metadata_catalog, unfenced, vscode_tasks, yaml_frontmatter.

The count is a ratchet, not a target: tests/test_module_doc_ratchet.py fails if a new module arrives without a page, and fails equally if a listed module gains one and is not removed from the baseline. It has ratcheted 22 → 20 → 22 — the drop as pages landed, the return as the interop_helpers and provenance carve-outs were baselined with a recorded reason (a documented deferral, never a silent one — provenance is a small stdlib stamp helper documented at each consumer's sidecar, not yet warranting its own page). Most of the growth came from CH-07 carves splitting documented modules — unfenced out of fences, audit_types out of audit, graph_inputs out of graph.

Four exceed 400 lines (stale_detector 739, vscode_tasks 854, backup 486, svg_render 470) and are the highest-value additions. backup's public API is partially documented inside emit, which re-exports it.

They are listed rather than written because a thin page that misdescribes a module is worse than a missing one — a reader trusts what is written. The pages added on 2026-07-29 (living-doc, update-report, output-plan, memory-index-incremental, cli) were scoped to modules whose behaviour was established first-hand rather than inferred.

What is mechanically guaranteed: every documented signature matches the code, and the feature summary's total equals its addends — tests/test_api_doc_signatures.py. Coverage is a known gap; accuracy is enforced.