RFC: Workspace-level orchestration — shared scaffolding, governance, and knowledge across repositories

[sonupreetam]

Summary

Today, uf init operates at the single-repo level: it scaffolds agents, commands,
convention packs, and Dewey sources into one repository. For organizations with
multiple related repos (e.g., a product repo, shared libraries, infrastructure),
this means duplicated configuration, per-repo constitutions, and repeated setup.

This RFC proposes a workspace abstraction — a parent-level concept that spans
multiple repositories, enabling shared governance, shared agents, unified knowledge,
and single-command setup across an entire project constellation.

Motivation

1. Duplicated scaffolding — Running uf init in 5 repos produces 5 copies of
   the same agents, commands, and convention packs. Customizing one requires
   manually syncing to the others.

2. Fragmented knowledge — Dewey already indexes sibling repos via sources.yaml
   relative paths, but this is configured per-repo with no workspace-level awareness.
   Each repo's Dewey instance is independent.

3. No constitution inheritance — Each repo has its own constitution. There's no
   mechanism for an org-level constitution to cascade to project repos while allowing
   local overrides.

4. Per-repo setup overhead — uf setup and uf doctor operate on one directory.
   Verifying a whole environment (5 repos + tools) requires running doctor in each.

5. Agent context boundaries — Agents working in one repo cannot easily reference
   specifications, decisions, or patterns from related repos without manual context
   injection.

Prior Art & Landscape

Several tools are innovating in this space:

Tool	Approach	Notable Feature
Cursor 3.2	Multi-root workspaces	Single agent session spans multiple folders; /multitask for parallel subagents
OpenCode	workspace config field (proposed, #19515)	Explicit multi-directory indexing without affecting git/snapshots
Hive	Multi-repo agent orchestrator	Connects multiple repositories so one session has full-stack context
AllAgents	Separate workspace repo	AI configuration lives in its own repo, shared across projects via git
Swarm (ApiariTools)	Rust TUI multiplexer	Multi-repo workspaces with auto-managed environment linking
DreamSwarm	Background daemon (KAIROS)	3-layer memory architecture, proactive debt detection across repos
Taskplane	Web dashboard + orchestrator	Dependency graphing across mono- and polyrepo projects
Scion (Google Cloud)	Container-per-agent	Each deep agent gets its own container + worktree + credentials
Swarm Orchestrator	Governance layer	Evidence-based quality gates across parallel agent executions

Common patterns across all solutions:

• Git worktrees for isolation
• Shared knowledge/memory layers
• Explicit multi-directory configuration
• Separation of agent config from application code

Proposed Design

Workspace Definition

A workspace is defined by a uf-workspace.yaml file placed in a parent directory:

# ~/GitHub/uf-workspace.yaml
name: complytime-ecosystem
repos:
  - complytime-providers
  - complytime
  - gemara-mcp
  - complybeacon

constitution: ./constitution.md   # org-level, cascades to all repos

shared:
  agents: ./.uf-workspace/agents/       # shared agent definitions
  commands: ./.uf-workspace/commands/    # shared commands
  packs: ./.uf-workspace/packs/         # shared convention packs

Layered Resolution

Configuration resolves with increasing specificity:

1. Workspace level — shared agents, commands, constitution
2. Repo level — per-repo overrides, local agents, local constitution additions
3. Branch/worktree level — experimental overrides (existing behavior)

Unified Commands

• uf workspace init — scaffold workspace config, link repos
• uf workspace doctor — health check all repos + shared infra
• uf workspace sync — push shared config changes to all repos
• uf init (in a repo) — inherits workspace-level config, adds only repo-specific files

Dewey Integration

• Single Dewey instance per workspace (not per repo)
• sources.yaml generated from workspace definition
• Embeddings computed once, shared across all repos
• Eliminates the "hangs on indexing" problem (index at workspace level, not per-init)

Constitution Inheritance

workspace constitution (highest authority)
  └── repo constitution (extends, cannot contradict)
       └── branch-local overrides (experimental only)

Alignment with Existing Principles

• Autonomous Collaboration: Repos remain independently functional; workspace is additive
• Composability First: Each repo still works with uf init alone; workspace is optional
• Observable Quality: Workspace-level doctor provides holistic health
• Testability: Shared config testable in isolation via workspace repo

Open Questions

1. Should the workspace definition live in its own repo (like AllAgents) or in a parent directory?
2. How does this interact with uf sandbox (container-level isolation)?
3. Should Replicator's work tracking be workspace-scoped or remain per-repo?
4. How do workspace-level agents interact with per-repo MCP server configs?

Next Steps

Looking for feedback on:

• Is this the right abstraction level?
• Which subset would provide the most immediate value?
• Are there architectural constraints that make this difficult?