Add Bridge & Staffing design for multi-project orchestration

[khaliqgant]

Introduces the "bridge" command for cross-project agent coordination:

• Architect/Principal role as orchestrator connecting multiple projects
• Leads with spawn capability to dynamically create worker agents
• Standup protocol for daily work coordination
• Multi-project dashboard visibility

[Copilot]

Pull request overview

This PR introduces a multi-project orchestration layer that enables a single "Architect" agent to coordinate work across multiple projects, each managed by a "Lead" who can dynamically spawn worker agents.

Key Changes:

• New bridge command for cross-project agent coordination via multi-socket connections
• New lead command for project leads with worker spawning capabilities
• Infrastructure for dynamic agent spawning and release via tmux

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
src/cli/index.ts	Added bridge and lead CLI commands with multi-project connection and spawn management
src/bridge/config.ts	Configuration loading and project resolution logic for bridge mode
src/bridge/multi-project-client.ts	Client for connecting to multiple project daemons simultaneously
src/bridge/spawner.ts	Agent spawning service for creating/releasing worker agents in tmux windows
src/bridge/types.ts	Type definitions for bridge, spawn, and worker management
src/bridge/utils.ts	Utility functions for shell escaping, sleep, and target parsing
src/bridge/index.ts	Module exports for bridge functionality
docs/DESIGN_BRIDGE_STAFFING.md	Comprehensive design document for the bridge and staffing feature
README.md	Updated with multi-project orchestration usage examples
.beads/issues.jsonl	Added tracking issues for remaining implementation work

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Potential error if payload.body is undefined or not a string. Add a check or default value before calling substring().

Suggested change

	console.log(`[${projectId}] ${from}: ${payload.body.substring(0, 80)}...`);
	const bodyText =
	payload && typeof payload.body === 'string'
	? payload.body
	: String(payload?.body ?? '');
	console.log(`[${projectId}] ${from}: ${bodyText.substring(0, 80)}...`);

[Copilot]

The variable name mainCommand is ambiguous as it could be confused with a system command. Consider renaming to cliTool or baseCli to clarify it represents the CLI tool portion.

Suggested change

	const [mainCommand, ...commandArgs] = cli.split(':');
	const wrapper = new TmuxWrapper({
	name,
	command: mainCommand,
	const [cliTool, ...commandArgs] = cli.split(':');
	const wrapper = new TmuxWrapper({
	name,
	command: cliTool,

[Copilot]

The shell escaping implementation may not handle all edge cases for shell injection. Consider using a well-tested library or adding single quote escaping and newline handling for more robust protection.

[Copilot]

The tmux session name is not escaped before being used in a shell command. If this.tmuxSession contains shell metacharacters, it could lead to command injection. Use proper escaping or validate the session name format.

Suggested change

	try {
	await execAsync(`tmux has-session -t ${this.tmuxSession} 2>/dev/null`);
	} catch {
	// Session doesn't exist, create it
	await execAsync(
	`tmux new-session -d -s ${this.tmuxSession} -c "${this.projectRoot}"`
	const safeSession = escapeForTmux(this.tmuxSession);
	try {
	await execAsync(`tmux has-session -t ${safeSession} 2>/dev/null`);
	} catch {
	// Session doesn't exist, create it
	await execAsync(
	`tmux new-session -d -s ${safeSession} -c "${this.projectRoot}"`

[Copilot]

Both this.tmuxSession and this.projectRoot are interpolated into shell commands without proper escaping. Use the escapeForShell utility function to prevent command injection.

[Copilot]

Another hardcoded sleep duration. Define this as a named constant (e.g., GRACEFUL_SHUTDOWN_DELAY_MS) for better maintainability.

[Copilot]

The nullish coalescing operator (??) here is unnecessary because envelope.payload as { nonce?: string } will never be null or undefined from a type cast. If the intent is to provide a default when payload is missing, check envelope.payload directly.

Suggested change

	payload: (envelope.payload as { nonce?: string }) ?? {},
	payload: envelope.payload ? (envelope.payload as { nonce?: string }) : {},

[Copilot]

The project.path is interpolated into a shell command without escaping. Use proper escaping to prevent command injection if the path contains shell metacharacters.

Suggested change

	await execAsync(`cd "${project.path}" && agent-relay up &`, {
	timeout: 5000,
	await execAsync('agent-relay up &', {
	timeout: 5000,
	cwd: project.path,

[Copilot]

Using & to background the process in a shell command passed to execAsync may not work as intended. The parent process will complete immediately, and the backgrounded process may not be properly managed. Consider using a proper process spawning mechanism or handling the async nature differently.

Suggested change

	// Start daemon in background
	await execAsync(`cd "${project.path}" && agent-relay up &`, {
	// Start daemon; let agent-relay manage its own backgrounding if needed
	await execAsync(`cd "${project.path}" && agent-relay up`, {

[Copilot]

The ASCII diagram uses inconsistent line styles (box-drawing characters). While functional, using consistent Unicode box-drawing characters throughout would improve visual consistency.