From a Shared Repository to a Working AI Harness

For Tencent’s TeamAI, the execution layer is the point where a team’s intention becomes behavior an AI agent can actually load. This chapter follows one resource from local authorship to review, repository state, native tool configuration, and session-start activation. The goal is to make a practical distinction clear: TeamAI does not distribute one universal agent configuration. It maintains a team-level representation, governs changes through Git, and compiles that representation into the different runtimes where agents work.

That distinction explains both the project’s reach and its complexity. A team may want a skill that describes a release procedure, a rule that constrains code review, an agent definition for a specialized task, a document that explains an internal system, a hook that runs at a lifecycle event, or an MCP server that gives an agent another capability. These resources have different meanings even when they are all stored as text or configuration. Treating them as undifferentiated files would make it difficult to review intent, preserve local settings, or know what should happen when a tool does not support a capability.

One representation, many native runtimes

The TeamAI repository is the durable source for team-owned resources and their policies. Its configuration describes the team repository, provider, sharing behavior, optional role and project controls, and the paths used by each supported agent. The resource model groups the things a team may govern into behavioral resources such as skills, rules, and agents; reference material such as docs; and operational channels such as hooks, environment data, MCP servers, and packages.

This is more than an inventory. TeamAI’s resource handlers give each category a common lifecycle—scan local sources, scan the team repository, push a selected item, pull it into local tool directories, and remove it without confusing team-owned content with personal content. The shared repository is authoritative for the team version, but the deployed copy belongs to a particular agent runtime. That separation allows the same team rule to have different filenames or frontmatter where a host requires it, while keeping the team’s meaning in one place.

Skills show why this separation matters. TeamAI can scan across the configured tool directories and compare local content with the repository version. When a skill is pushed without complete metadata, the CLI can add a name and description derived from the skill directory and its content. That is not just cosmetic: metadata helps the skill remain discoverable and usable when it is rendered for another tool. The scanner also avoids letting a stale nested copy silently outrank a shallower, authoritative copy.

Rules make the translation problem even clearer. The team repository stores a Markdown rule, but Cursor-compatible tools expect .mdc files with their own frontmatter. TeamAI derives the native frontmatter during pull. When a user edits a Cursor rule and pushes it back, the system sends the Markdown body while preserving the team rule’s own scope metadata. Otherwise, a tool-specific round trip could accidentally turn a path-scoped rule into an always-on rule for everyone.

Agent definitions use a similar canonical pattern. A team can keep a YAML specification and render it into the format expected by each target tool. If a member edits a native rendering, TeamAI can reverse-parse the edit and merge it with the canonical specification. When two tools produce conflicting values, the safer result is to skip the update rather than silently choose one and overwrite the team definition. This is an important operating principle: translation should expose ambiguity, not hide it behind a successful-looking sync.

Environment data and MCP servers expose a different boundary because they can affect the machine beyond the agent’s instructions. TeamAI validates the environment schema, writes shell-safe values, and can source a generated environment file from the user’s shell profile. MCP servers are declared in a tool-neutral form and rendered into each tool’s native configuration, with transport requirements, command or host restrictions, ownership records, and collision handling. The result is convenient central administration, but it is not risk-free portability. A resolved credential can be written literally into a local MCP configuration, so the project warns users to keep such files out of version control and to put only non-secret values in shared environment data.

The same principle governs what TeamAI does not do. A configured tool is not automatically treated as installed: resource and hook deployment checks for the tool’s local root before creating files. A tool with no supported path for a resource is skipped rather than receiving a guessed configuration. This reduces the chance that an administrator’s team-wide declaration creates unexplained directories or inert files on every member’s machine.

The push–review–pull control flow

The lifecycle below shows how a resource crosses the boundary from a member’s workspace into another agent’s session.

sequenceDiagram participant D as Developer or local agent participant P as TeamAI push participant G as Git provider participant V as Reviewer participant R as Team repository participant H as SessionStart hook participant L as TeamAI pull participant A as Native agent config D->>P: Author or edit a team resource P->>R: Scan and stage selected change P->>G: Push branch and open PR/MR G-->>V: Present change for review V->>G: Approve and merge G->>R: Update default branch H->>L: Start session and invoke pull L->>R: Refresh merged team state L->>A: Render resource for installed tool A-->>H: Agent loads the team harness alt PR/MR creation unavailable P-->>D: Keep pushed branch for manual review end

The first transition is intentionally local. teamai push scans configured AI-tool directories for resources that are new or changed relative to the team repository. Team members can select which items belong in the change. Before scanning, TeamAI synchronizes teammates’ updates into the local view so a change that arrived from the repository is not mistaken for a member’s new edit. In single-repo mode, the scanner also considers the committed knowledge tree because that tree is itself the team resource source.

Selected resources are copied into the team repository’s working tree and placed on a branch. The branch is then sent to the configured Git provider for a pull request or merge request. TeamAI records the resources associated with an open branch. If the member runs push again while the request is still waiting for review, retaining the resource in the selection updates that existing request rather than creating a duplicate. If only part of the original group is selected, TeamAI keeps the selected changes separate, because review boundaries are part of the meaning of the change.

This flow also has deliberate failure behavior. TeamAI skips a branch when there are no substantive changes, including changes that contain only recognized timestamps. If a later step fails after resources were copied into the local team clone, it rolls those copies back so the next scan does not report a phantom difference. If the provider cannot create the PR or MR, the branch remains pushed and the user is told that it can be reviewed manually. The repository’s desired governance path is therefore not confused with the provider’s ability to automate every step.

Provider abstraction determines how much of that path can be automated. GitHub, TGit, CNB, GitLab, and GitCode have platform-specific authentication and repository or PR operations. GitLab and GitCode use REST APIs with different URL and authentication dialects; GitHub and CNB can rely on their platform CLIs. The generic Git provider delegates credentials to the system’s SSH configuration or credential helper. It can clone, pull, and push, but it cannot create a repository or PR/MR on an arbitrary host. A team using such a host still gets the Git source of truth, but the review handoff may be manual.

The current implementation also makes provider details a version-sensitive subject. The provider guide contains an older warning that GitHub push behavior is hard-coded to master, while the current Git helper resolves origin/HEAD and then checks main and master. The code is the stronger evidence for the retained snapshot, but the discrepancy is useful: teams should verify the behavior of the installed CLI and their repository rather than assume that documentation and implementation evolve in lockstep.

After review and merge, teamai pull is the distribution side of the loop. It refreshes the dedicated team-repository clone, reads the current revision, and uses local state to avoid redeploying ordinary resources when nothing relevant has changed. That optimization is conditional. A newly installed tool, a changed submodule tree, or another condition that makes the local target set different causes a sync rather than a blind fast-path skip.

Pull then scans the current team resources and applies role, project, tag, and exclusion decisions where those controls are active. It copies or renders resources only to installed and permitted tools. It also cleans up tombstoned resources and inactive selections, but deletion is conservative: a deployed skill is removed only when TeamAI can verify that it matches the team source and contains no extra local work or nested version-control history. A local copy that differs is kept with a warning, because “no longer selected” is not proof that deleting it is safe.

Hooks are handled as a control plane rather than as ordinary content. TeamAI’s built-in hooks cover session start, post-tool use, prompt submission, and stop, and the current implementation routes them through a unified hook-dispatch command. Optional team hooks are reconciled alongside them, but are kept in a separate identity namespace so a team rule does not get mistaken for a built-in operational hook. Pull reconciles these hooks outside the ordinary “repository revision unchanged” shortcut. That means a CLI upgrade can repair or add a built-in hook, and a change to the team hook declaration can take effect, even when the team repository’s content revision would otherwise cause resource deployment to be skipped.

The hook path is native at its final boundary. Claude-style settings, Cursor hook files, Codex hook files, ZCode configuration, and the OpenCode plugin model do not share one on-disk format. TeamAI renders each form and preserves unrelated user entries. It also checks whether the target tool exists before injecting settings. This makes session-start automation possible without requiring every agent to behave identically, but it leaves host-specific conditions visible: JoyCode currently requires manual synchronization, and public Codex may require a user to trust newly written hooks before they run.

A team-declared hook is especially consequential because it is an arbitrary shell execution surface. The project therefore supports a local kill switch for team hooks, an optional requirement that commands point into a managed scripts directory, tool-specific filtering, project-directory gating, and an autoApply setting that can turn automatic application into an explicit user action. These controls do not make a shared hook harmless; they make its authority legible and give the user a way to refuse or delay it.

HTTP onboarding changes the lifecycle rather than merely replacing the clone URL. A read-only consumer can initialize against an HTTP endpoint with an API key and receive resource commands through a report/sync/ack protocol. They do not need Git access or a local team-repository clone, but they also cannot use push, contribute, or remove. This is a useful trade: lower participation and credential friction in exchange for less control and no ordinary Git review path.

The execution layer is therefore best understood as a controlled compilation pipeline. Git supplies durable ownership and review; TeamAI supplies the resource model, diffing, rendering, cleanup, and hook reconciliation; the provider supplies hosting operations; and the agent supplies the final runtime. A failure or mismatch at any boundary should remain visible instead of being hidden by a generic “sync succeeded” message.

That architecture solves one major problem—getting reviewed team intent into the tools people actually use—but it introduces the next one. A shared repository can reach many agents only if the system can decide which workspace, project, role, and machine should receive which part of it. Scope is therefore not an installation detail; it is the boundary that determines what “shared” means.

References