Proposal: a workspace mode for features that span several repos

[SaulMoro]

Today. In a microservice team, one feature often touches several repos, for example a proto repo, service A and service B (#908). Members keep those checkouts in one folder and start the agent there. TeamAI resolves one scope per directory, so the parent folder and the repos inside it don't know about each other.

ws/                    not a git repo, the agent starts here
  proto/  svc-a/  svc-b/     each set up with `teamai init <team> --project <id>`

agent in svc-a/        svc-a's skills, rules, docs and learnings     works
agent in ws/           nothing from the repos inside                  ws/ has no config, and their pulls don't run

Two setups get close today, and each has a cost:

• teamai init <team> --project proto,svc-a,svc-b in ws/ delivers all three projects there. The member keeps that list by hand. A contribute in ws/ sees three active projects, which resolve to three learnings namespaces here, and writes the learning to the shared root (src/contribute.ts:23-29).
• --scope user gives the same resources in every folder, with no separation between projects.

Proposal. A workspace mode for a project scope, turned on with a flag on init. A workspace is a project scope that also delivers what the repos inside it select. It can have a selection of its own, like any project scope, or none, and it reads the repos inside it that are already set up.

ws/          teamai init <team> --workspace [--project platform]
  svc-a/     teamai init <team> --project svc-a     unchanged
  svc-b/     teamai init <team> --project svc-b     unchanged

pull in ws/        1. runs the pull of each direct child that has a teamai config
                   2. delivers its own selection plus the union of the children's (roles, projects, tags) into ws/, for every enabled agent

agent in ws/       the workspace's own resources, plus svc-a's and svc-b's
agent in svc-a/    svc-a's resources, as today
agent in ~/        nothing new, only a folder set up with --workspace does this

• The team changes nothing. manifest/projects.yaml and manifest/roles.yaml stay as they are, and a team repo with neither works too.
• Each member's workspace follows the repos they cloned. Bob keeps proto and svc-b, gets those two projects, and has no list to maintain.
• Learnings stay with each project. recall in the workspace searches its own and every child's learnings. contribute writes to the child it runs in, and in the workspace to its own selection, or to the shared root when that is empty. contribute --namespace <ns> ([feat] contribute --namespace, to file a learning under one of the namespaces a directory reads #916) files a learning under any namespace the workspace reads, a child's or a group's, without cd.
• A child keeps working on its own.

This serves the roadmap in #647 (Team Execution: "Refine project binding, resource distribution, and switching in Projects") and builds on the project dimension from #375.

Goal. A member who starts the agent in a folder of repos gets the team resources of every project in it, and what they learn still lands in the right project.

Terms. A workspace is a folder, a git repo or not, set up with teamai init <team> --workspace. A child is a direct subfolder with its own teamai config. The workspace's own selection is the roles, projects and tags set by its init, as in any project scope, and it can be empty. Its delivered selection adds the union of its children's.

The team declares projects as it does today:

# manifest/projects.yaml in the team repo
version: 1
projects:
  - id: svc-a
    resources:
      skills:    [svc-a, payments, common]   # payments: shared by one group of services
      knowledge: [svc-a]
      learnings: [svc-a]
      docs:      [svc-a, payments]
  - id: svc-b
    resources:
      skills:    [svc-b, payments, common]
      knowledge: [svc-b]
      learnings: [svc-b]
      docs:      [svc-b, payments]
  - id: platform           # optional, for a meta repo's own scripts and docs
    resources:
      skills:    [platform, common]
      knowledge: [platform]
      learnings: [platform]
      docs:      [platform]

Skills that every project needs go in a namespace each project lists, such as common. In project mode the root skills/ is the tag catalog and is not delivered by default (docs/designs/multi-project-management.md:271). Resources that only some projects share go in a namespace those projects list, such as payments above. Every member gets them through any child of the group, whatever else their workspace holds. Group learnings are written with contribute --namespace <group> (#916).

A member sets up the workspace once, after the repos inside it:

$ cd ws && teamai init git@example.com:org/team.git --workspace --project platform
Workspace: 2 children (svc-a, svc-b), same team repo
Own projects: platform
Delivered projects: platform, svc-a, svc-b

# written by init where any project scope keeps it: the machine partition for a git repo, ws/.teamai for a plain folder
scope: project
workspace: true           # an older CLI ignores this key and serves a plain project scope
repo:
  remote: git@example.com:org/team.git
projects: [platform]      # own selection only

The children's selection is read on each pull and never written here.

What I'd put in v1.

• --workspace on init, with a team repo, with or without --role or --project, in a plain folder or in a git repo whose children are their own repos, for example ignored in its .gitignore.
• Detection through the paths a project scope already uses: the machine partition in a git repo (src/config.ts:417-452), <dir>/.teamai outside one (:450-452). Children don't look for a parent.
• pull in a workspace runs the children's pulls, then delivers the union of their selection into the workspace through the existing project-scope delivery.
• The workspace keeps its own selection in the fields a project scope already uses (primaryRole, additionalRoles, projects, subscribedTags) and adds the children's at delivery time. Its excludedSkills, enabledAgents and inheritUserScope are its own, since they describe how the member works in that folder.
• One team repo per workspace, the one given to init. A child with another team repo stays out of the union, and pull and doctor name it and say what to do.
• Session start covers the children, since it runs pull in the workspace.
• Skill usage from a workspace session is reported to its team repo, as any scope does.
• recall in the workspace reads its delivered selection, so one search covers its own resources and every child's. Every index rebuild in the workspace (pull, recall, contribute, import) uses that selection, since today each one uses the scope's own projects.
• contribute in the workspace takes --namespace <ns> ([feat] contribute --namespace, to file a learning under one of the namespaces a directory reads #916) for any namespace it reads, so a learning about one child or one group goes there from the workspace. Without the flag it writes to its own selection, as in any project scope. With no own selection, or when the team declares no learnings namespaces, it writes to the shared root, as any such scope does. When the team does declare them, the output says where the learning went and which namespaces the member could pass next time. Contributing again would publish a second copy (src/contribute.ts:248-251), so the agent picks before it writes.
• push in the workspace offers only what its own selection would deliver, and skips every item that reaches the workspace only through a child. Today's filters don't cover this. With no active role or project, skill push scans every skill (src/resources/skills.ts:315-318), and rule push has no namespace filter. In a team without manifests both sets are the same, so nothing is skipped. A child's resource is edited and pushed from the child.
• Tests for the union, the own-versus-delivered split, the skipped child, push skipping the children's items with and without an own selection, contribute --namespace for a child's and a group's namespace from the workspace, and the message, plus a real-CLI check in a folder of repos.
• teamai projects list in the workspace lists each child and its active projects. With the line [feat] contribute --namespace, to file a learning under one of the namespaces a directory reads #916 adds, it also reports the workspace's own default and, among the namespaces --namespace accepts, the children's and any group's they read.
• Docs and agent skills updated. setup covers creating a workspace. share needs no workspace case: its step 4, as [feat] contribute --namespace, to file a learning under one of the namespaces a directory reads #916 proposes it, reads the default and the accepted namespaces from teamai projects list, and in a workspace those include the children's.

What could wait.

• Children from several team repos. Config holds one team repo per scope (src/types.ts:513), and state holds one team revision (lastPullRev, src/types.ts:681-705). This needs either a schema change or each child delivering into the workspace itself, and in both cases rules for two skills with the same name.
• Children deeper than one level.
• A team repo that is optional in init --workspace, defaulting to the one the children share.
• doctor naming each child and when it last pulled.
• Running the children's pulls in parallel.

Acceptance check. Alice has ws/ with svc-a and svc-b, each set up with its project. She runs teamai init <team> --workspace in ws/ and starts her agent there. It has the skills, rules and docs of both projects. The team pushes a new skill to skills/svc-a/. Alice's next session in ws/ has it, and so does her next session in svc-a/. She runs teamai contribute in svc-a/, and the learning lands in learnings/svc-a/. In ws/, which has no own selection, the same command shares the learning with the whole team, and teamai contribute --namespace svc-a there lands in learnings/svc-a/. Hana's svc-a lists learnings: [svc-a, payments]. contribute there goes to the shared root and names both namespaces, and with --namespace payments it lands in learnings/payments/, where svc-b's recall finds it. Bob's workspace holds proto and svc-b, and his agent sees only those projects. Both get the payments skills and docs, Alice through svc-a and svc-b, Bob through svc-b. Carol adds a child that uses another team repo. pull names it and leaves it out. Dan starts his agent in his home folder, which holds ten repos set up with teamai, and nothing new happens. Erin's team uses roles instead of projects. Her svc-a is set up with --role backend and her web with --role frontend, and her agent in the workspace gets both roles' resources. Frank's workspace is a git meta repo set up with --project platform. His agent in ws/ gets platform plus his children's projects. teamai contribute in ws/ lands in learnings/platform/, and teamai push there offers only platform's items. Gina's team has no manifests. Her workspace delivers what each child delivers, and every learning goes to the shared root, as it does today.

Design notes: proposed details and open questions

Proposed:

• Why a flag and a key. A pull that ran the children's pulls in any folder that is not a git repo would also reach a home folder with dozens of repos at every session start, so the workspace is opt-in. It is a key on a project-scope config rather than a new scope value. ScopeEnum accepts only user and project (src/types.ts:57), so an older CLI could not read a scope: workspace config at all. It ignores an unknown key and keeps serving the folder as a plain project scope, without the children. An older CLI that saves the config drops the key (src/config.ts:120-123), and the folder stays a plain project scope until init --workspace runs again. The key also leaves the roughly 90 scope === ... checks in src/ as they are. The code already uses workspace for a checkout root (workspaceRoot, lastPullByWorkspace), so the implementation may want another internal name.

• Children derived, not declared. Each child already says which project it belongs to, and each member's disk says which children exist. A list in the workspace would drift from both, so two members with the same meta repo can hold different children. The own selection covers only the folder itself. TeamAI still doesn't clone or manage the member's repos.

• Own versus delivered. The config holds only the own selection. Writing uses it by default: contribute writes where the workspace itself belongs, and push offers what the workspace itself would deliver. contribute --namespace ([feat] contribute --namespace, to file a learning under one of the namespaces a directory reads #916) is the explicit exception, and it accepts any namespace the workspace reads. Delivery and reading use the delivered selection: pull, the search index and recall cover what the workspace receives. status and doctor show both.

• Delivery reuses the project scope. With one team repo, the workspace delivers what a project scope with the same roles, projects and tags delivers today. I checked that with 0.22.0 in a folder that is not a git repo, and the skills of all three projects landed there. Namespace resolution, cleanup and the protection of local edits (fix(pull): keep a skill, rule or agent you edited instead of overwriting it (#822) #865) stay as they are.

• Roles, projects, or neither. The union covers each layout the team repo can have. With no manifests, every child resolves to an unfiltered sync (src/resource-namespaces.ts:60), so the workspace delivers the same. With roles, a scope already holds a primary role and additional roles and delivers their union (src/roles.ts:244). Two roles, two projects, or a role and a project that fill one slot use the existing namespace conflict rule. With one team repo, every child is in the same mode, because the mode depends on the team's manifests. A child with no role in a team with roles.yaml and no projects.yaml resolves to an unfiltered sync, so the workspace does too, and doctor names that child. Role learnings namespaces are ignored today (src/roles.ts:22-26), so with roles a learning goes to the shared root whether it comes from a child or not. How tags combine when one child subscribes to none and another to some is for the implementation to pin down.

• A git parent. A team can keep a meta repo with scripts or compose files and ignore the service repos in its .gitignore. Each child has its own .git, so it resolves its own scope. I checked that with 0.22.0. The meta repo can have its own project, for example platform for shared scripts and docs. A committed .gitignore only affects the parent's git status. A member who clones a repo it doesn't list can hide it with .git/info/exclude.

• The same skill twice. Some agents also load skills from subfolders when they work on files there. Claude Code documents this for nested .claude/skills, and in a test it listed both svc-a-skill and svc-a:svc-a-skill. In a workspace those agents see the workspace copy and the child's copy. Both come from the same team repo and are identical. Avoiding this would need per-agent rules, or children that skip delivery inside a workspace, which would move files each time the member switches between the workspace and a child. The docs would say so.

• Pull time. The session-start pull runs detached with a 120 s budget (src/hook-handlers.ts:808-811), so the children's pulls don't delay the session. In v1 the children pull one after another, each under its own lock. A child the budget doesn't reach is pulled at the next session.

• Nothing cached. The workspace reads its children's selection on each pull, and status and doctor read it the same way, so it can't drift from the children.

• Submodules. Children kept as git submodules work. Each resolves its own scope, anchored at its git dir under .git/modules/. I checked that with 0.22.0.

• Learnings. contribute picks its namespace from the directory it runs in (src/contribute.ts:23-29). One active learnings namespace means that namespace, and none or several mean the shared root. In a child with one learnings namespace that gives the child's. With several, as in [feat] contribute --namespace, to file a learning under one of the namespaces a directory reads #916's example, it gives the shared root. In the workspace it gives the own namespace, or the shared root when the workspace has no own selection. --namespace ([feat] contribute --namespace, to file a learning under one of the namespaces a directory reads #916) picks one explicitly, and it accepts what the directory reads. Teams without learnings namespaces see no change: every learning goes to the shared root, from a child or from the workspace. That makes a workspace with no own selection the natural place for a learning that concerns the whole team. A learning for a group of projects is written with --namespace <group> ([feat] contribute --namespace, to file a learning under one of the namespaces a directory reads #916). Reading a group's learnings already works: with learnings: [svc-a, payments], recall in svc-a returned an entry from learnings/payments/ in a 0.22.0 sandbox. The contract, with the manifest above plus a child that also lists the group:

  context                                        contribute, no flag      recall reads             --namespace accepts
  child, learnings [svc-a]                       learnings/svc-a/         svc-a                    svc-a
  child, learnings [svc-a, payments]             learnings/ (root)        svc-a, payments          svc-a, payments
  child with no project, roles, or no manifest   learnings/ (root)        the root                 nothing to pass
  workspace with own project [platform]          learnings/platform/      platform and children    any namespace it reads
  workspace with no own selection                learnings/ (root)        children                 any namespace it reads
  

• Wiki recall. Code-knowledge recall is not filtered by project today ([feat] Scope teamwiki recall by project, like docs #912). That already affects each child, and the workspace doesn't change it.

• Root skills. pull removes root skills without saying so when projects take effect ([bug] pull removes root skills without a word when roles or projects take effect #911). Members moving to a workspace setup would hit it, so the setup docs point to a shared namespace.

Open questions:

• Is a workspace key on a project scope, set with init --workspace, the right shape, and is workspace the right name given its existing meaning in the code?

Feedback from teams that work across several repos would help:

• Do your members keep those repos in one folder, or in unrelated places?
• Do the repos of one feature share a team repo, or does each come from a different one?
• Does choosing the namespace with --namespace work for you when you contribute from the workspace?
• Is anything here more than a first version needs?