Multi-Repo Hub

Local multi-repo orchestration — dispatch tickets to independent Claude sessions in VS Code terminals, each in their own repo with full plugin access.

Problem

The Local Multi-Repo Problem

Cross-Repo Delegation solves multi-repo for pipelines. But local developers need the same capability.

Multiple Repos

A user story spans frontend and backend repos. The developer has both checked out locally but dx skills only see the current repo.

Manual Repetition

Without hub mode, the developer must cd into each repo and run skills separately — losing context between repos.

No Visibility

No single view of what’s running across repos, which sessions are blocked, or what failed.

Where Hub Fits in the Three-Tier Strategy

Pipeline mode (ADO) → Hub mode (local multi-repo) → Manual handoff (single-repo fallback). Hub mode is the local developer equivalent of pipeline cross-repo delegation.

Solution

Hub Mode

A hub directory sits above your repos and dispatches work to independent Claude sessions in VS Code terminals.

Directory Layout

projects/
├── .hub/                    ← hub directory (created by /dx-hub-init)
│   ├── .ai/config.yaml      ← merged config with repos registry
│   ├── .claude/CLAUDE.md     ← hub-specific instructions
│   ├── .mcp.json             ← ADO + vscode-automator MCP servers
│   └── state/                ← dispatch tracking
│       └── <ticket>/
│           ├── raw-story.md  ← fetched ticket (copied to each repo)
│           ├── context.md    ← cross-repo context for delegates
│           └── status.json   ← per-repo status (running/done/blocked/failed)
├── Frontend-Repo/           ← sibling repo with .ai/config.yaml
└── Backend-Repo/            ← sibling repo with .ai/config.yaml

Requirements

macOS with Accessibility permission (vscode-automator uses AppleScript)
VS Code open with the hub workspace
Sibling repos with .ai/config.yaml (run /dx-init in each first)

Skills

Hub Skills

Four skills for hub lifecycle: dispatch, init, config, status.

/dx-hub-dispatch

The core skill. Fetches a ticket, detects which repos are needed, pre-seeds raw ticket files, and opens VS Code terminals with independent Claude sessions.

Usage

/dx-hub-dispatch 2471234              # auto-detect repos
/dx-hub-dispatch 2471234 repo-fe repo-be  # explicit repos
/dx-hub-dispatch 2471234 --skill /dx-req  # requirements only

/dx-hub-init

Initialize a hub directory. Discovers sibling repos with .ai/config.yaml, prompts for selection, builds merged config, registers vscode-automator MCP.

Usage

/dx-hub-init              # default: ../.hub
/dx-hub-init ~/my-hub     # custom path

/dx-hub-config

View and edit hub settings — add repos, adjust terminal startup delay.

Usage

/dx-hub-config show
/dx-hub-config add-repo ../New-Repo
/dx-hub-config terminal-delay 8

/dx-hub-status

Show dispatch status — which repos are running, done, blocked, or failed.

Usage

/dx-hub-status            # all dispatches
/dx-hub-status 2416553    # single ticket detail
/dx-hub-status --clean    # remove stale entries

How It Works

Dispatch Flow

Hub fetches the ticket, determines repos, opens terminals, and lets each repo run its own pipeline.

Hub Dispatch

From ticket to independent Claude sessions in each repo.

Fetch Ticket ADO/Jira → raw-story.md in hub state/

Detect Repos Match capabilities or user-specified

Pre-Seed Copy raw file into each repo

Launch VS Code terminals via vscode-automator

Monitor /dx-hub-status running/done/blocked

Key Design Decisions

Real Terminals, Not Headless

Each repo gets an interactive Claude session in its own VS Code terminal. Full plugin access, full MCP tools, and the user can see and intervene at any time.

Pre-Seeded Raw Tickets

Hub copies raw-story.md into each repo’s spec directory before launching. The repo’s /dx-req finds it and skips the ADO fetch — no duplicate API calls.

Hub Never Plans

Hub only fetches, routes, and launches. Each repo runs its own /dx-req + /dx-plan with its own tech-stack knowledge and codebase context.

Cross-Repo Awareness

Each delegated session receives a context.md telling it which other repos are involved. Repos can check each other’s spec directories for coordination.

Decision Tree

Condition	Action
`DX_PIPELINE_MODE=true`	Pipeline delegation (write `delegate.json`) — see Cross-Repo
`hub.enabled: true` + repos registered	Hub dispatch — open VS Code terminals via vscode-automator, one per repo
Hub not configured but multi-repo detected	Manual handoff — print “Also affects <repo> — run `/dx-agent-all` there”
Single-repo scope	Local execution — normal skill behavior

Config

Hub Configuration

Hub settings in .ai/config.yaml — generated by /dx-hub-init.

.ai/config.yaml (hub section)

hub:
enabled: true
terminal-delay: 5          # seconds to wait for Claude to start
state-ttl: 7d               # clean dispatches older than 7 days

repos:
- name: Frontend-Repo
  path: ../Frontend-Repo     # relative to hub
  base-branch: develop
  capabilities: [fe]
- name: Backend-Repo
  path: ../Backend-Repo
  base-branch: develop
  capabilities: [be]

Config Fields

Field	Default	Description
`hub.enabled`	`true`	Enable/disable hub mode
`hub.terminal-delay`	`5`	Seconds to wait for Claude to start in each terminal
`hub.state-ttl`	`7d`	Auto-clean dispatch state older than this
`repos[].name`	—	Display name (matches directory name)
`repos[].path`	—	Relative or absolute path to repo
`repos[].capabilities`	`[]`	Tags for scope routing (e.g., fe, be)

Status

Tracking Dispatches

/dx-hub-status shows what's running, done, blocked, or failed.

/dx-hub-status output

Hub Dispatch Status
───────────────────────────────────────────────────
┌──────────┬─────────────────────────┬──────────────┬──────────┐
│ Ticket   │ Title                   │ Repo         │ Status   │
├──────────┼─────────────────────────┼──────────────┼──────────┤
│ 2471234  │ Add user profile page   │ repo-fe      │ done ✓   │
│          │                         │ repo-be      │ running ⟳│
│ 2471189  │ Fix auth timeout        │ repo-be      │ blocked ⚠│
└──────────┴─────────────────────────┴──────────────┴──────────┘

State Files (V1 — Minimal)

File	Purpose
`state/<ticket>/status.json`	Per-repo status flags: running, done, blocked, failed
`state/<ticket>/raw-story.md`	Fetched ticket content (copied to each repo)
`state/<ticket>/context.md`	Cross-repo context read by each delegated session

Why Minimal Status?

The user can see all terminals live in VS Code. Complex progress tracking adds overhead without value in V1. Rich status (pipeline phases, step counts, PR links) is planned for V2 — it will read each repo’s spec directory without requiring any changes to non-hub skills.

Setup

Getting Started

Three commands to set up hub mode.

Hub Setup

From zero to multi-repo orchestration.

1. Init /dx-hub-init Discover repos

2. Open Open hub workspace in VS Code

3. Dispatch /dx-hub-dispatch 123 Launches terminals

Prerequisites

macOS with Accessibility permission for terminal automation
Sibling repos with .ai/config.yaml (run /dx-init in each first)
dx-core and dx-hub plugins installed

vs Cross-Repo

Hub vs Pipeline Delegation

Two solutions for the same problem, in different contexts.

Aspect	Hub Mode (Local)	Pipeline Delegation (ADO)
Where it runs	Developer machine (VS Code terminals)	ADO pipelines
Trigger	`/dx-hub-dispatch <ticket>`	Webhook → Lambda → pipeline
Repo discovery	Sibling directories on disk + capabilities	`CROSS_REPO_PIPELINE_MAP` env var
Dispatch mechanism	VS Code terminals via vscode-automator MCP	`delegate.json` → ADO REST API
Each repo gets	Interactive Claude with full plugins + MCP	Headless `claude -p` in pipeline
User visibility	See all terminals live, can intervene	Pipeline logs only
Tracking	`/dx-hub-status`	ADO pipeline run history
Skills	`/dx-hub-dispatch`, `/dx-hub-init`, `/dx-hub-config`, `/dx-hub-status`	Built into coordinator skills + `/auto-*`