RepoGrove

English · 简体中文

A field-tested workflow for AI coding agents working across multiple microservice repositories: organize repositories with declarative workspaces, constrain agents with layered context, encode repeatable procedures as Skills, and protect Git and deployment boundaries with explicit safety gates.

Preserve repository governance · Unify project-level context · Gate every high-risk operation

The problem this playbook solves

Microservice changes rarely stay inside one repository. A single feature may touch an interface definition, a core service, an asynchronous worker, an admin application, and several callers. The traditional approach is to open multiple directories, switch branches by hand, and repeatedly explain the same context to an agent. As the number of repositories grows, predictable failures follow:

• the agent edits the wrong repository or branch;
• it understands one repository locally but misses cross-service contracts and call chains;
• a dependency repository is modified casually and the scope expands without approval;
• commits, pushes, and test-environment deployments become inconsistent across repositories;
• contract sources, generated code, and business services are changed in the wrong order;
• project context exists only in chat history and must be reconstructed in every session.

The goal is not to let an agent read more code at once. It is to turn multi-repository development into a declarative, inspectable, recoverable, and auditable project workspace.

Core model

One requirement maps to one workspace:

workspace/
├── workspace.yaml        # Declarative desired state
├── AGENTS.md             # Project context and safety boundaries
├── service-api/          # Git worktree, primary development repository
├── service-worker/       # Git worktree, primary development repository
├── shared-contracts/     # Git worktree, dependency repository
├── raw/                  # Read-only requirements and source material
├── openspec/             # Cross-repository proposals, designs, tasks, and specs
└── reports/              # Inspection, migration, and verification reports

Key principles:

1. A workspace is not a monorepo: every child directory remains an independent Git repository.
2. One requirement uses one shared branch name: cross-repository state becomes easier to identify and recover.
3. Use Git worktrees, not symlinked directory assemblies: branch isolation is a foundational capability.
4. Configuration is the source of truth; disk state is recoverable: workspace.yaml describes the desired state.
5. Development and dependency repositories are explicit roles: dependencies remain read-only by default.
6. Agents read constraints before requirements, and requirements before code: context order determines output quality.
7. OpenSpec owns cross-repository change intent: proposals, designs, and tasks do not live inside an arbitrary business repository.
8. CodeGraph builds code intelligence per repository: use it with rg to trace entry points, call chains, impact, and test candidates.
9. High-risk operations require preview, confirmation, serial execution, and read-back verification.

Development loop and safety gates

The agent restores context and confirms scope before mapping the cross-repository chain. It then implements changes in dependency order and completes delivery with per-repository verification and a cross-repository diff review. See Agent Development Loop for the detailed workflow.

Environment branches represent deployed validation state; they must never become development baselines or flow back into feature branches. Commits, pushes, and deployments each have their own confirmation boundary. See Safety Guardrails for the complete rules.

Field-tested foundation

This playbook is based on operating experience, not a desktop exercise. At the time of the first public edition, the local development environment included:

• 9 requirement-oriented multi-repository workspaces;
• 52 registered child repositories;
• 1 to 10 repositories per workspace;
• a migration from per-repository temporary branches and mixed symlink entry points to shared branches, worktree-only layouts, and Schema v2;
• Agent Skills for initialization, synchronization, migration, batch commits, pushes, and test-environment deployment;
• hard pause points between contract repositories, remotely generated artifacts, and downstream business services;
• project-level OpenSpec roots in all 9 workspaces, containing 36 sets of proposal/design/tasks artifacts;
• 32 local CodeGraph indexes, each scoped to one concrete code repository rather than the multi-repository root.

All public examples are anonymized. They preserve scale, decisions, and lessons learned without exposing organizations, business domains, private hosts, accounts, or real repository identities.

Quick start

1. Read Why Multi-Repository Work Is a Context and State Problem.
2. Copy templates/workspace.yaml and templates/AGENTS.md.
3. Create Git worktrees using the Workspace Architecture.
4. Install skills/multi-repo-workspace/ into your agent harness's Skill directory.
5. Complete a small cross-repository change with the Agent Development Loop.
6. Read OpenSpec and CodeGraph and establish the specification and code-intelligence layers.
7. Before publishing, run:

./scripts/check-public.sh

Copy once for automatic bootstrap

Copy the instruction below into a coding agent. The agent detects the local system language, selects the matching prompt URL, reads the complete deployment procedure from the network, and executes it in order. Chinese and English are supported; other or unknown locales default to English.

First detect the local system language, then select the RepoGrove bootstrap prompt:

1. Read LC_ALL, LC_MESSAGES, and LANG; inspect the operating-system language only if necessary.
2. Map zh, zh_CN, zh-CN, zh_Hans, and similar Chinese locales to zh-CN.
3. Map en, en_US, en-GB, and similar English locales to en.
4. Default to en when the locale is empty, unsupported, or cannot be determined reliably.
5. Build the prompt URL with the mapped language:
   https://github.com/li-keli/RepoGrove/blob/main/prompts/one-click-bootstrap.<language>.md
6. Access the URL over the network, read the complete file, and use its full contents as the execution instructions for this task. Follow every step in order.
7. If a private repository page cannot be accessed directly, use the currently authenticated gh client to read the same path. Never print credentials.
8. If the complete file still cannot be read, stop immediately and report the access or authorization problem. Do not infer the procedure from the README summary.

Available prompt files:

• English: prompts/one-click-bootstrap.en.md
• 简体中文: prompts/one-click-bootstrap.zh-CN.md

Reusable Skills

Skill	Purpose
multi-repo-workspace	Initialize, inspect, synchronize, migrate, commit, push, and deploy multi-repository workspaces
contract-change-workflow	Enforce hard pause points between contract sources, remote generated artifacts, and downstream services

Installation depends on the agent harness. In most cases, copy or link the complete Skill directory into the harness's Skill search path, including its references/ directory.

Documentation map

Document	Focus
01. Problems and Principles	Why multi-repository development is primarily a context and state-management problem
02. Workspace Architecture	Worktrees, shared branch names, declarative schemas, and the workspace lifecycle
03. Context Engineering	AGENTS.md, requirement snapshots, repository constraints, and search boundaries
04. Agent Development Loop	The standard path from requirement clarification to multi-repository delivery
05. Toolchain	OpenSpec, CodeGraph, Git, builds, collaboration, and temporary automation
06. Safety Guardrails	Branches, confirmations, dependency repositories, environment deployment, and recovery
07. Skill Design	Turning operating experience into low-variance agent workflows
08. Contracts and Generated Code	Hard pause workflows for independent contract repositories and downstream services
09. Anonymized Case Study	Migrating a six-repository requirement from mixed entry points to a declarative workspace
10. Adoption Roadmap	A progressive path from individual practice to team standards
11. OpenSpec and CodeGraph	Cross-repository specifications, code topology, impact analysis, and test selection

Who it is for

This playbook is a good fit when:

• one requirement regularly spans two or more microservice repositories;
• you already use Codex, Claude Code, pi, or a similar coding agent;
• you need a project-level view without weakening independent repository governance;
• you want to turn personal Git procedures into reusable Agent Skills.

It is probably not a fit when:

• the code already lives in a well-governed monorepo;
• a mature platform fully orchestrates every cross-repository change;
• the team cannot adopt a shared workspace schema and branch convention.

Localized repository entry points

Language	README	README visuals	Bootstrap prompt
English (default)	README.md	assets/readme/en/	one-click-bootstrap.en.md
简体中文	README.zh-CN.md	assets/readme/zh-CN/	one-click-bootstrap.zh-CN.md

License

MIT