Back to Details

multi-repo

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Multi-Repository Orchestration Skill

多仓库编排Skill

Purpose

用途

Coordinate atomic changes across multiple repositories when features span repo boundaries. Track dependencies, manage linked PRs, and detect breaking changes before they propagate.
当功能跨越仓库边界时，协调多个仓库间的原子变更。跟踪依赖关系、管理关联PR，并在破坏性变更扩散前检测到它们。

When to Use This Skill

适用场景

USE FOR:
  • Changes that require coordinated updates across multiple repositories
  • Managing repository dependency graphs
  • Creating linked PRs that should merge together or in sequence
  • Detecting breaking changes that affect dependent repositories
  • Microservices or monorepo-alternative architectures
AVOID FOR:
  • Single-repository changes (use default workflow)
  • Forking/syncing operations (use git directly)
  • Documentation-only changes
  • Changes with no cross-repo dependencies
适用情况：
  • 需要跨多个仓库协同更新的变更
  • 管理仓库依赖关系图
  • 创建需要一起或按顺序合并的关联PR
  • 检测会影响依赖仓库的破坏性变更
  • 微服务或单体仓库替代架构
避免使用：
  • 单仓库变更（使用默认工作流）
  • 分支/同步操作（直接使用git）
  • 仅文档变更
  • 无跨仓库依赖的变更

Storage Location

存储位置

All multi-repo data is stored in 
~/.amplihack/.claude/data/multi-repo/
:
  • dependencies.yaml
    - Repository dependency graph
  • linked-prs.yaml
    - Currently active linked PR sets
  • breaking-changes.log
    - History of detected breaking changes
所有多仓库数据存储在
~/.amplihack/.claude/data/multi-repo/
：
  • dependencies.yaml
    - 仓库依赖关系图
  • linked-prs.yaml
    - 当前活跃的关联PR集合
  • breaking-changes.log
    - 已检测到的破坏性变更历史

Dependency Graph Format

依赖关系图格式

The dependency graph uses simple YAML:
yaml
undefined
依赖关系图采用简单的YAML格式：
yaml
undefined

.claude/data/multi-repo/dependencies.yaml

.claude/data/multi-repo/dependencies.yaml

version: "1.0" repositories: my-org/api-server: depends_on: [] exposes: - type: api name: REST API v2 contract: openapi.yaml
my-org/web-client: depends_on: - repo: my-org/api-server type: api version: ">=2.0" exposes: []
my-org/mobile-app: depends_on: - repo: my-org/api-server type: api version: ">=2.0" exposes: []
undefined
version: "1.0" repositories: my-org/api-server: depends_on: [] exposes: - type: api name: REST API v2 contract: openapi.yaml
my-org/web-client: depends_on: - repo: my-org/api-server type: api version: ">=2.0" exposes: []
my-org/mobile-app: depends_on: - repo: my-org/api-server type: api version: ">=2.0" exposes: []
undefined

Core Operations

核心操作

Operation 1: Initialize Dependency Graph

操作1：初始化依赖关系图

When: Setting up multi-repo tracking for the first time
Process:
  1. Create 
    ~/.amplihack/.claude/data/multi-repo/
    directory if not exists
  2. Create initial 
    dependencies.yaml
    with current repository
  3. Prompt for known dependencies (repos this one depends on)
  4. Prompt for known dependents (repos that depend on this one)
  5. Save and display the graph
Command: "Initialize multi-repo dependencies"
时机： 首次设置多仓库跟踪时
流程：
  1. 若不存在则创建
    ~/.amplihack/.claude/data/multi-repo/
    目录
  2. 使用当前仓库创建初始
    dependencies.yaml
  3. 提示输入已知依赖项（当前仓库所依赖的仓库）
  4. 提示输入已知依赖方（依赖当前仓库的仓库）
  5. 保存并显示依赖关系图
命令： "初始化多仓库依赖"

Operation 2: Add Repository Dependency

操作2：添加仓库依赖

When: Registering a new dependency relationship
Process:
  1. Read current 
    dependencies.yaml
  2. Validate both repositories exist (via gh CLI)
  3. Add dependency entry with type and version constraint
  4. Update dependent repo's entry
  5. Save changes
Example:
"Add dependency: my-org/web-client depends on my-org/api-server for REST API"
时机： 注册新的依赖关系时
流程：
  1. 读取当前
    dependencies.yaml
  2. 验证两个仓库是否存在（通过gh CLI）
  3. 添加包含类型和版本约束的依赖条目
  4. 更新依赖方仓库的条目
  5. 保存更改
示例：
"添加依赖：my-org/web-client 依赖 my-org/api-server 的 REST API"

Operation 3: Detect Breaking Changes

操作3：检测破坏性变更

When: Before creating a PR that modifies a public interface
Process:
  1. Identify changed files in current branch
  2. Check if changes touch exposed contracts (API specs, schemas, exports)
  3. Look up dependents in dependency graph
  4. For each dependent:
    • Clone/fetch latest (use worktree if local)
    • Check if dependent uses affected interface
    • Report potential breakage
  5. Generate impact report
Output:
Breaking Change Impact Report
=============================
Changed: my-org/api-server/openapi.yaml
  - Removed endpoint: DELETE /users/{id}
  - Modified field: User.email now required

Affected Dependents:
  - my-org/web-client (uses DELETE /users/{id})
  - my-org/mobile-app (no impact detected)

Recommendation: Coordinate changes with my-org/web-client
时机： 在创建修改公共接口的PR之前
流程：
  1. 识别当前分支中已更改的文件
  2. 检查变更是否涉及对外暴露的契约（API规范、 schema、导出内容）
  3. 在依赖关系图中查找依赖方
  4. 针对每个依赖方：
    • 克隆/拉取最新代码（本地仓库使用worktree）
    • 检查依赖方是否使用受影响的接口
    • 报告潜在的破坏情况
  5. 生成影响报告
输出：
破坏性变更影响报告
=============================
变更文件：my-org/api-server/openapi.yaml
  - 移除端点：DELETE /users/{id}
  - 修改字段：User.email 现在为必填项

受影响的依赖方：
  - my-org/web-client（使用 DELETE /users/{id}）
  - my-org/mobile-app（未检测到影响）

建议：与 my-org/web-client 协调变更

Operation 4: Create Linked PRs

操作4：创建关联PR

When: Making atomic changes across multiple repositories
Process:
  1. User specifies the set of repos to update
  2. For each repo in order (respecting dependency graph):
    • Create worktree or navigate to repo
    • Create feature branch with common prefix
    • Make changes
    • Create PR with links to other PRs in set
  3. Track linked PRs in 
    linked-prs.yaml
  4. Add cross-references in PR descriptions
Linked PR Format:
yaml
undefined
时机： 在多个仓库中进行原子变更时
流程：
  1. 用户指定要更新的仓库集合
  2. 按照依赖关系图的顺序处理每个仓库：
    • 创建worktree或导航到仓库
    • 创建带有通用前缀的功能分支
    • 进行变更
    • 创建PR并在描述中关联集合内的其他PR
  3. 在
    linked-prs.yaml
    中跟踪关联PR
  4. 在PR描述中添加交叉引用
关联PR格式：
yaml
undefined

.claude/data/multi-repo/linked-prs.yaml

.claude/data/multi-repo/linked-prs.yaml

linked_sets:
  • id: "auth-v2-migration" created: "2025-11-25T10:00:00Z" status: "pending" prs:
    • repo: my-org/api-server pr: 123 status: "merged" merge_order: 1
    • repo: my-org/web-client pr: 456 status: "approved" merge_order: 2
    • repo: my-org/mobile-app pr: 789 status: "open" merge_order: 3
undefined
linked_sets:
  • id: "auth-v2-migration" created: "2025-11-25T10:00:00Z" status: "pending" prs:
    • repo: my-org/api-server pr: 123 status: "merged" merge_order: 1
    • repo: my-org/web-client pr: 456 status: "approved" merge_order: 2
    • repo: my-org/mobile-app pr: 789 status: "open" merge_order: 3
undefined

Operation 5: Coordinate Merge Sequence

操作5：协调合并顺序

When: Merging a linked PR set
Process:
  1. Read linked PR set from 
    linked-prs.yaml
  2. Verify all PRs are approved/ready
  3. Merge in dependency order (upstream first)
  4. Wait for CI to pass after each merge
  5. Update linked-prs status
  6. Report completion
Merge Order Logic:
  1. Repos with no dependencies merge first
  2. Repos with dependencies merge after their dependencies
  3. Circular dependencies: Error (should not exist in healthy graph)
时机： 合并关联PR集合时
流程：
  1. 从
    linked-prs.yaml
    中读取关联PR集合
  2. 验证所有PR已获批/准备就绪
  3. 按照依赖顺序合并（上游仓库优先）
  4. 每次合并后等待CI完成
  5. 更新关联PR的状态
  6. 报告完成情况
合并顺序逻辑：
  1. 无依赖的仓库优先合并
  2. 有依赖的仓库在其依赖仓库合并后再合并
  3. 循环依赖：报错（健康的依赖图中不应存在）

Integration with Worktree Manager

与Worktree Manager的集成

When working across local repositories, leverage the worktree-manager agent:
  1. For each local repo in dependency graph:
    • Use 
      git worktree add
      to create isolated workspace
    • Worktrees go in 
      ./worktrees/{repo-name}-{branch}/
  2. Make coordinated changes across worktrees
  3. Commit and push from each worktree
  4. Clean up worktrees after PRs merged
在本地仓库间工作时，可借助worktree-manager agent：
  1. 针对依赖关系图中的每个本地仓库：
    • 使用
      git worktree add
      创建独立工作区
    • Worktree 存储在
      ./worktrees/{repo-name}-{branch}/
  2. 在多个worktree间进行协同变更
  3. 从每个worktree提交并推送变更
  4. PR合并后清理worktree

Integration with PM Architect

与PM Architect的集成

For complex multi-repo projects:
  1. Use backlog-curator to track cross-repo items
  2. Use workstream-coordinator for multi-repo workstreams
  3. Linked PRs map to single workstream items
  4. Breaking change detection feeds into roadmap planning
针对复杂的多仓库项目：
  1. 使用backlog-curator跟踪跨仓库事项
  2. 使用workstream-coordinator管理多仓库工作流
  3. 关联PR映射到单个工作流事项
  4. 破坏性变更检测结果可用于路线图规划

Philosophy Alignment

设计理念

Ruthless Simplicity:
  • YAML-based dependency graph (no database required)
  • Leverage existing git and gh CLI tools
  • Minimal skill surface area
Zero-BS Implementation:
  • All operations are functional from day one
  • No "planned" features - only what works now
  • Breaking change detection actually checks code
Modular Design:
  • Skill is self-contained
  • Data stored in simple files
  • Can be used independently or with PM Architect
极致简洁：
  • 基于YAML的依赖关系图（无需数据库）
  • 利用现有的git和gh CLI工具
  • 最小化Skill的功能范围
务实实现：
  • 所有操作从第一天起即可使用
  • 无“规划中”功能，仅提供当前可用功能
  • 破坏性变更检测会实际检查代码
模块化设计：
  • Skill是独立的
  • 数据存储在简单文件中
  • 可独立使用或与PM Architect配合使用

Examples

示例

Example 1: API Breaking Change

示例1：API破坏性变更

Scenario: Updating API endpoint signature
User: "I need to change the /users endpoint from GET to POST"

Skill Response:
1. Detected change to api-server/openapi.yaml
2. Scanned dependents:
   - web-client: Uses GET /users in 3 locations
   - mobile-app: Uses GET /users in 2 locations
3. Impact: HIGH - 5 usages across 2 repositories

Recommended approach:
1. Add POST /users endpoint (non-breaking)
2. Create linked PRs to update web-client and mobile-app
3. Deprecate GET /users with sunset date
4. Remove GET /users after clients migrate
场景： 更新API端点签名
用户：“我需要将 /users 端点从 GET 改为 POST”

Skill响应：
1. 检测到对api-server/openapi.yaml的变更
2. 扫描依赖方：
   - web-client：在3个位置使用GET /users
   - mobile-app：在2个位置使用GET /users
3. 影响程度：高 - 2个仓库中共有5处使用

推荐方案：
1. 添加POST /users端点（非破坏性）
2. 创建关联PR以更新web-client和mobile-app
3. 标记GET /users为已弃用并设置停用日期
4. 客户端迁移完成后移除GET /users

Example 2: Coordinated Feature Release

示例2：协同功能发布

Scenario: New authentication flow spanning 3 repos
User: "Implement OAuth2 across api-server, web-client, and mobile-app"

Skill Response:
1. Created linked PR set: "oauth2-implementation"
2. Dependency order: api-server -> web-client, mobile-app (parallel)
3. Created branches:
   - api-server: feat/oauth2-backend
   - web-client: feat/oauth2-frontend
   - mobile-app: feat/oauth2-mobile
4. PRs created with cross-references:
   - api-server#123 (merge first)
   - web-client#456 (after #123)
   - mobile-app#789 (after #123)
场景： 跨3个仓库实现新的认证流程
用户：“在api-server、web-client和mobile-app中实现OAuth2”

Skill响应：
1. 创建关联PR集合：“oauth2-implementation”
2. 依赖顺序：api-server -> web-client、mobile-app（并行）
3. 创建分支：
   - api-server: feat/oauth2-backend
   - web-client: feat/oauth2-frontend
   - mobile-app: feat/oauth2-mobile
4. 创建带有交叉引用的PR：
   - api-server#123（优先合并）
   - web-client#456（在#123之后合并）
   - mobile-app#789（在#123之后合并）

Limitations

局限性

  • Dependency graph is per-workspace (not centralized)
  • Requires gh CLI authenticated for PR operations
  • Breaking change detection is heuristic (may miss runtime changes)
  • Circular dependencies are not supported (and shouldn't exist)
  • 依赖关系图是每个工作区独立的（非集中式）
  • PR操作需要已认证的gh CLI
  • 破坏性变更检测是启发式的（可能遗漏运行时变更）
  • 不支持循环依赖（健康的依赖图中也不应存在）

Success Criteria

成功标准

  • Changes across repos are coordinated atomically
  • Breaking changes are detected before they cause production issues
  • PRs merge in correct dependency order
  • Teams have visibility into cross-repo impacts
  • 跨仓库的变更可原子化协同
  • 破坏性变更在引发生产问题前被检测到
  • PR按正确的依赖顺序合并
  • 团队可了解跨仓库变更的影响