Superblocks, the enterprise internal tool builder, this week published the first in a planned technical series on how its engineering team is structuring multi-repo codebases for AI-assisted development. The core problem they're solving: AI coding agents like Claude Code, Cursor, and OpenCode can only see the repository they're opened in. That narrow view produces locally correct but architecturally wrong code — services wired with the wrong protocols, undocumented cross-service contracts broken silently, bugs that don't appear until integration. Superblocks' solution is a dedicated workspace meta-repository that contains no application code and instead serves as the connective tissue for a polyglot stack spanning Go, TypeScript, Terraform, and React.
The workspace repo is built around a handful of components, each solving a specific problem. A repos.yaml manifest tracks all service repositories. A justfile provides a stable command interface that papers over the differences between Makefiles, Helm charts, and docker-compose files scattered across repos. Tilt handles service orchestration — health checks, dependency ordering, per-service logging — in ways a task runner can't. For AI agents specifically, the workspace ships AGENTS.md context files alongside symlinked cross-repo architecture documents covering data flows, service boundaries, and protocol specifications. Previously, an agent would need to make GitHub API calls to retrieve that information, if it could find it at all.
Git worktrees sit at the center of the design. Rather than sharing a single checkout, each feature branch gets its own isolated file tree — one per Linear ticket, one per agent session — with no duplication overhead, since Git shares the underlying object store. A single command, `just worktree create ENG-123 feature-x`, provisions worktrees across all relevant repos, writes the profile configuration, and symlinks the AGENTS.md so a cloud-based agent sees the same context a local engineer would. The justfile is framed explicitly as a contract: a stable interface that insulates workspace-level workflows from churn in individual repo build systems.
The team positions the workspace as a practical middle ground: most organizations have neither the runway nor the appetite for a full monorepo migration, but still need their AI coding tools to understand how their services relate to each other. Part 2 of the series will cover AGENTS.md structure and best practices in depth, how MCP configuration gets distributed across the workspace, and a dynamic knowledge graph for querying service relationships at runtime.