The Boundary Problem: Scope, Projects, Roles, and Worktrees

In TeamAI, the difficult scope question is not simply where to install a skill. It is what “shared” should mean for a particular person, workspace, project, and agent. This chapter separates TeamAI’s three physical locations and three distribution dimensions so readers can choose a scope deliberately and predict what a worktree or member will receive. The distinction matters because confusing a logical project with a machine-data partition can expose the wrong knowledge, write resources into the wrong checkout, or cause one project to clean up another project’s files.

The preceding execution model showed a repository being rendered into native agent configurations. That model left an important variable implicit: a repository may be shared by several workspaces, a person may work in more than one logical project, and a team may want common rules without sharing every project-specific learning. TeamAI addresses these cases by separating physical placement from logical selection.

Three locations that must not be collapsed

The first location is team knowledge: the assets that have an ownership relationship with the team repository. In a standalone Git installation, these assets are available through the local team-repository clone. In single-repo mode, they live under the business repository’s .teamai directory and travel with the repository’s main branch. Skills, rules, docs, learnings, and team configuration belong to this knowledge side of the model.

The second location is resource landing: the place where an AI tool looks for project or user resources. A project-scoped installation writes into the current workspace root—the repository checkout in which the agent is running. A user-scoped installation writes under the user’s home directory. This is not a minor path choice. AI tools generally discover project resources by walking upward from the directory where they were launched; they do not follow Git’s internal common directory back to a main checkout. A linked worktree therefore needs its own project resource files even when it shares the same underlying repository history.

The third location is machine-local TeamAI data. It includes configuration and state, synchronization caches, search indexes, environment backups, and ownership manifests. For project installs in a Git repository, current TeamAI keys this data to the shared main-worktree identity, called the projectAnchor, and stores it in a per-project partition under the user’s TeamAI home. The current checkout, called the workspaceRoot, remains the place where project resources land.

That split solves two apparently conflicting requirements. The partition is shared by linked worktrees of one repository, so they can coordinate machine-local state and the cached team repository. The resource landing is still distinct per worktree, so an agent launched in a feature checkout does not accidentally load project files from the main checkout. One physical identity answers “which project’s machine data is this?”; the other answers “which checkout should the AI tool scan right now?”

The partition name is derived from a safe project basename plus a hash of the normalized anchor rather than from a raw path. The human-readable prefix helps inspection, while the hash distinguishes two repositories with the same basename without exposing the entire directory structure. An anchor file provides the reverse lookup needed by commands such as status --all. This is a system-level trade-off: machine data can be stable across worktrees without making the business repository carry caches, indexes, or local credentials.

User scope and project scope apply this model differently. User scope is appropriate for conventions that should follow a person across projects. Its resources and machine data live under the user’s home-level TeamAI installation. Project scope, which is the default when initializing from an ordinary project directory, is appropriate when the team’s skills and rules are tied to one workspace. TeamAI detects project configuration from the current Git workspace, including when a command runs from a subdirectory or linked worktree.

Project scope is isolated from user scope by default. If a project explicitly enables inheritance, TeamAI can refresh safe user resources and search user knowledge in addition to the project resources. It does not silently merge the control plane: user environment data, MCP definitions, external sources, reporting, and remote writes remain isolated, while hooks follow their own carefully gated placement rules. This is a useful boundary because an organization-wide coding convention is not automatically the same thing as an organization-wide executable command or credential-bearing server configuration.

HTTP mode is a different boundary again. It serves users or agents that only consume skills and rules through a report/sync/ack lifecycle. They do not need Git access or a clone, but push, contribute, and remove are unavailable. The mode lowers the participation requirement rather than pretending that read-only delivery provides the same ownership and review capabilities as Git.

Single-repo mode makes the ownership distinction visible. Here the business repository is also the team repository. Durable knowledge remains under .teamai on the main line because it is intended to travel with a clone. Machine-local data is kept in the per-project partition. Noisy reports—members, sessions, votes, and stats—are written to a teamai-reports orphan branch through a dedicated worktree, so they do not pollute the business history. Knowledge changes use a temporary worktree as well; TeamAI can create branches and perform cleanup there without switching or hard-resetting the developer’s active checkout.

A fresh clone can recognize the mode: self marker and bootstrap its machine-side configuration when the user can authenticate with the relevant Git provider. The clone carries knowledge and hooks, but the local machine still owns its partition and resource landing. This is why “clone = initialized” does not mean “clone contains everyone’s machine state.” It means the repository carries enough team knowledge and startup behavior for the local side to be reconstructed safely.

classDiagram class Knowledge class ResourceLanding class MachineData class Role class LogicalProject class Tags class MainWorktree class LinkedWorktree class HTTPConsumer Knowledge --> ResourceLanding : rendered into MainWorktree --> Knowledge : self mode on main MainWorktree --> MachineData : shared anchor partition LinkedWorktree --> MachineData : same repository partition LinkedWorktree --> ResourceLanding : own workspace root Role --> ResourceLanding : selects knowledge and skills LogicalProject --> ResourceLanding : adds namespaces LogicalProject --> Knowledge : selects learnings Tags --> ResourceLanding : local skill and rule filter HTTPConsumer ..> ResourceLanding : read-only delivery

The diagram is deliberately not a directory tree. It shows the relationships that matter operationally: knowledge is rendered into a landing area; worktrees share a machine-data identity but not a project-resource root; and role, logical project, and tag decisions enter at the selection boundary rather than changing what the team repository is.

Three distribution questions: role, project, and interest

Physical scope answers where data lives. Logical distribution answers which part of the team’s knowledge should cross into that location. TeamAI uses roles, logical projects, and tags for different questions.

A role answers, “What kind of work does this member do?” An administrator defines roles in a manifest and maps each role to namespaces for skills and knowledge. A member may have a primary role and additional roles; TeamAI takes their union. A developer who also supports operations can therefore receive both sets of namespaces without one role silently overriding the other. Role configuration is about job function, not about which business project the person happens to open today.

A logical project answers, “Which team-defined project does this workspace belong to?” A project manifest maps a logical id to namespaces for skills, knowledge, and learnings. A directory can activate one or more logical projects, and those namespaces are unioned with the active role namespaces. The two dimensions are additive: a person can need general engineering skills from a role and project-specific knowledge from a logical project.

This distinction matters most for learnings. Roles deliberately do not own learning isolation. Markdown files at the root of learnings/ remain shared with the whole team, preserving a simple home for cross-project experience. Project-specific learning can live under a project-selected namespace and is indexed only for directories whose active projects include that namespace. A person’s job role does not, by itself, grant access to every project’s private learning.

TeamAI does not resolve a collision between a role namespace and a project namespace by choosing a winner at runtime. If the same skill name appears in two active namespaces, the configuration is treated as an administrative duplicate that should be disambiguated. This is preferable to an invisible precedence rule: the team fixes the ambiguous identity at the manifest boundary instead of asking each member’s local pull to guess which resource was intended.

A project is also not automatically activated merely because a team repository defines one. The working directory provides the external basis for project identity, but a user may legitimately work with only shared resources. Automatically selecting a lone project would risk exposing project-private learnings to someone who needs only common infrastructure guidance. TeamAI’s explicit project activation keeps that choice visible.

teamai projects set is a local correction mechanism. It changes the active logical projects for the current directory and invalidates the pull cache so that the next pull can install newly selected resources and clean up resources from projects that are no longer active. That cleanup is not the same as erasing team knowledge; it changes the local projection of the repository.

The member roster has a different meaning from the directory configuration. A local projects setting describes what one directory currently syncs. The member file records every project in which that user has participated, appending and deduplicating across directories. One is an active view; the other is a team-side history of membership. Treating them as the same list would either lose historical participation or incorrectly install every historical project into every current workspace.

A tag answers a third question: “Which topics do I want to receive?” Tags are a personal subscription over skills and rules. An administrator associates tags with those resources; a member subscribes locally. A subscription does not assert project membership, and it does not isolate learnings or docs. Resources without tags remain universal, so adding a tag system does not unexpectedly make existing team resources disappear. Unsubscribing tells the next pull to remove filtered-out resources where the local copy is safe to delete.

This gives the three mechanisms a compact interpretation:

  • a role represents a work function;
  • a logical project represents a team-defined work context;
  • a tag represents local interest in a subset of skills or rules.

They can coexist because they operate on different relationships. The role and logical project namespaces are unioned when selecting skills and knowledge. The logical project alone controls project-private learning namespaces. Tags refine skills and rules after the broader role/project decisions. None of these mechanisms changes the underlying authority of the team repository.

The final boundary is deletion. When a role or project is changed, TeamAI may discover a deployed resource that is no longer desired. It does not assume that absence from the desired set proves the local copy is disposable. For a skill, the deployed directory must match the team source, contain no extra files, and have no nested version-control metadata before automatic removal is allowed. If a member edited the skill, added a script, or placed another repository inside it, TeamAI keeps the copy and warns them to back it up or push it before deleting it manually.

Tombstones handle a related case: an explicit team removal should not be undone just because a stale local copy is still visible to the push scanner. But even an upstream tombstone does not justify deleting a nested Git repository with possible unpushed history. The system favors a visible stale file over silent loss. That choice has a cost—local directories may require manual cleanup—but it makes the cleanup boundary legible.

Concurrency adds another reason to keep the boundaries precise. A project’s team-repository clone may be reachable from the main checkout and every linked worktree. Pull and push operations therefore coordinate shared clone access with a project-level lock. A pull that finds the lock held skips that scope and can retry later; a push reports contention rather than pretending it accepted a member’s changes. In single-repo mode, the reports branch has its own lock and retry path because several members can update the shared branch at nearly the same time, even though each normally writes their own user file.

The practical result is a more exact definition of isolation. Isolation does not mean that every project has a completely separate universe. A repository can share common skills, a partition can be shared across worktrees, and a user can deliberately inherit safe resources. Isolation means that each crossing is explicit: knowledge versus machine data, current workspace versus main anchor, role versus project, interest versus membership, and readable resource versus executable control plane.

Once those boundaries are in place, TeamAI can answer a more useful question than “Where is the file?” It can ask whether a piece of experience belongs to everyone, to a project, to a role, or only to the local machine—and then build a searchable context that respects that answer. That is the boundary the recall system must preserve when it turns team experience into something an agent can use.

References