AI-Native Team Workspace (Meta-Repo Architecture)

Metadata

ID: RA-003-AI-NATIVE-META-REPO
DOI:
Status: Production-Validated · Enterprise Scale
Author: Ivan Baha (ORCID: 0009-0005-7024-7724)
Published Date: 2026-04-03
Tags: #meta-repo #ai-agents #workspace #architecture #developer-experience
Repository: github.com/ivanbaha/team-workspace

1. Context & Problem Statement

Modern enterprise projects often distribute code across many isolated repositories — separate repos for frontend, backend microservices, shared libraries, and infrastructure manifests. This separation supports independent deployment cycles but creates a hard boundary for AI coding agents such as GitHub Copilot Workspace, Cursor, Kiro, or Claude Code. An agent working within a single repository lacks awareness of the broader system. It cannot trace a business rule from the database schema through the service layer to the frontend component, resulting in shallow, context-poor suggestions that require significant human correction.

The traditional solution — migrating to a true monorepo using Nx or Turborepo — is costly and risky for established codebases. It can halt feature development for months, require changes to the toolchain, and may not be suitable for polyglot stacks. Teams also face inconsistent AI guidelines, repeated context setup, and uneven developer experiences across different tools.

This document outlines a lighter alternative that resolves the agent-context issue without requiring any restructuring of the underlying repository.

2. Solution

A Virtual Workspace Meta-Repo acts as a centralized routing and scaffolding layer. It clones all isolated project repositories into a single logical directory tree, giving AI agents a unified view of the full system — without moving or modifying any of the underlying repos.

The meta-repo itself contains no application code. It holds configuration, shared documentation, automation scripts, AI skill definitions, and external connectors. All nested repos retain their own Git histories, CI/CD pipelines, and deployment lifecycles entirely unchanged.

3. Architectural Implementation

3.1 Virtual Directory Structure

After running yarn setup, the workspace resolves to the following layout. Entries marked (cloned) are managed by the automation scripts; all others are native to the meta-repo.

team-workspace/
├── .vscode/                  ← Shared editor settings (committed)
├── .ai/                      ← Agent-agnostic SKILLs & Connectors
│   ├── skills/
│   └── connectors/
├── configs/
│   └── workspace-repos.json  ← Registry of all ecosystem repos
├── docs/                     ← Architecture overview & API contracts
├── scripts/
│   ├── setup-workspace.mjs   ← First-time clone + hook install
│   └── update-workspace.mjs  ← Pull updates across all nested repos
├── .githooks/post-merge      ← Auto-runs yarn update after git pull
├── backend/
│   ├── products-service/     ← (cloned) Products REST API
│   └── users-service/        ← (cloned) Users REST API
├── frontend/
│   ├── host-frontend/        ← (cloned) React host app
│   ├── users-frontend/       ← (cloned) Users microfrontend
│   └── products-frontend/    ← (cloned) Products microfrontend
├── infra/
│   └── git-ops/              ← (cloned) Kubernetes GitOps manifests
└── libs/
    ├── tw-common-frontend/   ← (cloned) Shared React hooks & UI, primitives
    ├── tw-api-client/        ← (cloned) Typed HTTP client wrappers
    ├── tw-common-backend/    ← (cloned) Express middleware & JWT utils
    └── tw-config/            ← (cloned) Env var loader & schema validation

3.2 Configuration & Automation

A single JSON registry in configs/workspace-repos.json lists all repositories in the ecosystem. Automation scripts read this file to clone missing repos and synchronise existing ones.

// configs/workspace-repos.json
{
  "backends": [
    {
      "name": "users-service",
      "description": "REST API — Users domain",
      "git": "git@github.com:ivanbaha/tw-users-service.git",
      "path": "./backend"
    }
  ]
}

Two scripts cover the full repo-management lifecycle:

setup-workspace.mjs — clones all repos listed in the registry and installs the post-merge Git hook. Run once per machine during onboarding.
update-workspace.mjs — pulls the latest changes in every cloned repo and clones any that are missing. Invoked as yarn update, or automatically by the post-merge hook after every git pull on the meta-repo.

The scripts are written in Node.js for this reference implementation, but the orchestration pattern is language-agnostic. Teams can rewrite them in Python or Bash to avoid introducing a new runtime dependency.

AI agents navigate the workspace through a mandatory README.md file at every directory level. The root README is automatically attached to the agent's context window. It contains a structured list of links to every nested directory with concise descriptions, allowing the agent to traverse the full system without requiring vector search or RAG indexing.

This approach is polyglot by design. Node.js services, React frontends, and Terraform configurations coexist in the same tree without build-tool conflicts, because the meta-repo makes no attempt to unify their build systems.

Commit discipline is preserved: engineers push application-level changes directly from within the relevant nested repo directory, maintaining their existing Git workflow. The AI skill definitions automatically reinforce this boundary.

3.4 Editor Optimisation

One VS Code setting is strongly recommended for any machine running this workspace:

"git.detectSubmodules": false

Without this flag, VS Code continuously scans every cloned sub-repository in the background. In workspaces with many nested repos, this causes a noticeable performance decrease and floods the Source Control panel with unrelated repo statuses. Disabling it does not affect Git functionality — it simply stops the background scanning. This is the one setting every team member should keep active when working within the meta-repo.

The reference repo includes a committed .vscode/settings.json with this flag enabled, along with other configs that affect performance, like "jest.enable": false. These additional flags reflect the conventions of the reference project — not universal rules. Whether your team commits a shared settings file, keeps individual local settings, or agrees on specific flags on a case-by-case basis depends entirely on the team. The only critical for performance config is source control scan.

.vscode/settings.json on GitHub

3.5 Centralised, Agent-Agnostic SKILLs

Different AI tools use incompatible formats for custom instructions. The .ai/skills/ directory stores canonical, tool-neutral Markdown skill files. Each AI tool receives a thin wrapper that does nothing but point to the canonical file.

Canonical skills — stored in .ai/skills/<skill-name>/SKILL.md. Full authoritative instructions in plain Markdown, decoupled from any proprietary syntax.
Thin wrappers — stored in tool-specific directories (.claude/commands/, .github/skills/, .kiro/skills/, .agents/skills/). Each wrapper contains only a redirect to the canonical file.

This means a skill is written and maintained exactly once. Supporting a new AI tool requires only a new thin wrapper — not a duplication of the skill logic.

## // .claude/commands/debug-and-report.md

description: Debug a production/test issue using logs and
codebase analysis, then optionally create a Jira bug ticket

---

# Debug & Report

You are starting a debugging session.
The user's initial description (if provided): $ARGUMENTS

Read and follow the full instructions in
`.ai/skills/debug-and-report/SKILL.md` from Step 1.

3.6 Secure External Connectors

AI agents frequently need to query external systems (Jira, Grafana, MongoDB) to complete tasks such as debugging or ticket creation. The .ai/connectors/ directory provides standalone, zero-dependency Node.js scripts that act as local proxy executables for these systems.

Canonical skills instruct the agent to invoke these scripts via its terminal (e.g., node .ai/connectors/grafana/search-logs.mjs). Authentication logic and API complexity stay entirely out of the prompt.

Credentials are loaded from a local .ai/connectors/env.json file that is git-ignored. This file must be created manually on each machine during onboarding (see docs/onboarding.md). It is recommended to add a pre-commit hook that prevents accidental commits of this file.

Available connectors in the reference implementation:

Grafana Loki (search-logs.mjs) — structured log search by service, time range, trace ID, or keyword.
Jira — create and query tickets with team-assignment conventions and evidence-structured descriptions.
Grafana log search connector on GitHub

3.7 Team-Scoped MCP Server

An alternative to file-based connectors is a custom MCP (Model Context Protocol) server built specifically for the team. Rather than invoking standalone scripts, the AI agent connects to the MCP server at session start and all registered tools become immediately available throughout the conversation — no skill invocation, no manual wiring per workflow.

Building a team MCP is straightforward: define a small set of tools that cover everyday needs (search Grafana logs, get and update Jira tasks, query MongoDB in read-only mode, list deployed services, etc.) and expose them through a single server file that lives in the repo like any other. The coding agent spins it up automatically from the workspace config — there is nothing to deploy or host. The agent then picks up the right tool based on context, without the user needing to specify it.

This approach works best when the tool surface is deliberately kept small. Each registered tool consumes a portion of the model’s context window regardless of whether it is used in a given turn. A lean, well-curated MCP of 8–15 tools has negligible context overhead and gives the agent a reliable, always-on capability. A bloated one with 40+ tools begins to crowd out the actual conversation.

The real trade-off compared to connectors is purely the integration model. Both approaches are zero-infrastructure scripts living in the repo. The difference is that MCP tools are auto-discovered and always available throughout the session, whereas connectors are invoked explicitly — either referenced by the user mid-conversation or triggered by a skill. MCP requires writing a small server registration layer; connectors require no registration at all.

3.8 Combining MCP and Connectors

The most effective setup in practice combines both approaches, with each addressing a different layer of the team’s tooling requirements. The team MCP manages universal, high-frequency operations that any engineer or agent session requires, regardless of workflow: fetching logs, checking task status, querying the database. These tools are always accessible without any instruction overhead.

Connectors manage workflow-specific, lower-frequency operations: a multi-step debugging sequence that correlates trace IDs across three services, a release preparation script that validates infrastructure manifests against current service versions, and a data migration dry-run with specific safety guardrails. These are complemented by a canonical SKILL.md (see 3.5) that instructs the agent when and how to invoke them.

In practice, this means:

A developer asking “why is the checkout service throwing 500s in staging?” gets answered using MCP tools automatically — no setup required.
A developer triggering the debug-and-report skill receives a structured, multi-step investigation that combines MCP tools for live log access with connector scripts for deeper environment analysis, resulting in a Jira ticket at the end.

The boundary between what belongs in the MCP and what should be a connector is a team decision. A helpful guideline: if a tool would be useful in more than half of all AI sessions, it belongs in the MCP. If it is only relevant within a specific workflow, it should be a connector paired with a skill.

4. Use Cases

Product & Business Analysis: PMs, BAs, and POs draft technical tasks with the AI using actual codebase context. The agent can identify feature injection points, surface architectural constraints, flag inconsistencies between a request and the existing code, and provide realistic effort estimates rather than abstract guesses.
Cross-Service Development: Developers implement features spanning multiple services in a single session. The agent holds the complete domain context across frontend, backend, and shared libraries, and can generate cross-boundary integration tests, enforce shared code styles, and apply workspace SKILLs consistently.
Advanced Debugging: The agent simultaneously references application code, infrastructure configuration, and live environment logs via the Grafana connector. It correlates distributed trace IDs, identifies root causes across service boundaries, and produces a structured Jira ticket with log evidence and a fix direction — ready for the engineer to review and file.
DevOps & QA: Operations staff configure environment variables and GitOps manifests with immediate access to the relevant application logic, reducing the risk of misconfiguration. QA engineers develop automated cross-boundary test scenarios and manage test environments directly using local connector scripts.

5. Consequences

The table below captures expected benefits, known risks, and their mitigations. This pattern is production-validated but not risk-free.

Positive	Risks & Mitigations
Comprehensive cross-boundary context: agents trace business logic from DB schemas to frontend components natively.	Nested repo drift: cloned repos can fall out of sync if engineers skip `yarn update`. Mitigated by the post-merge hook; optionally enforce via CI.
Zero-friction integration: all nested repos keep their own CI/CD pipelines and Git histories unchanged — no migration required.	Onboarding friction: the meta-repo pattern is unfamiliar to new contributors. Mitigated by `docs/onboarding.md` and a single `yarn setup` command.
Standardised developer experience: unified AI guidelines, automation, and debugging procedures across all disciplines, with no tool lock-in.	Credential management: `env.json` is git-ignored but relies on team discipline. Add a pre-commit hook to prevent accidental commits and document setup in `onboarding.md`.
Accelerated velocity: reduces onboarding time for new hires and maximises AI reasoning across legacy systems without a monorepo migration.	IDE performance with many repos: VS Code sub-module scanning can slow the editor. Fully mitigated by the committed `.vscode/settings.json` (`git.detectSubmodules: false`).

6. Getting Started

# 1. Clone the meta-repo
git clone git@github.com:ivanbaha/team-workspace.git && cd team-workspace

# 2. Clone all nested repos and install the post-merge Git hook
yarn setup

# 3. Install workspace-level dependencies
yarn install

# 4. Start developing
yarn dev:host          # Frontend host app
yarn dev:users-be      # Users backend service
yarn dev:products-be   # Products backend service

# Sync all nested repos at any time
yarn update

After yarn setup completes, the post-merge hook is active. Every subsequent git pull on the meta-repo automatically calls yarn update to keep all nested repos in sync.

Full onboarding instructions, including credential setup for the external connectors, are in docs/onboarding.md.

1. Context & Problem Statement​

2. Solution​

3. Architectural Implementation​

3.1 Virtual Directory Structure​

3.2 Configuration & Automation​

3.3 Cross-Boundary Navigation via README Hierarchy​

3.4 Editor Optimisation​

3.5 Centralised, Agent-Agnostic SKILLs​

3.6 Secure External Connectors​

3.7 Team-Scoped MCP Server​

3.8 Combining MCP and Connectors​

4. Use Cases​

5. Consequences​

6. Getting Started​