Feature: Multi-Project Workspace Mode for Cross-Repository Planning and Execution

[hoangsonww]

Summary

Add a multi-project workspace mode that lets Forge reason about, plan across, and safely execute tasks spanning multiple repositories while preserving per-project sandbox, permission, memory, and persistence boundaries.

Problem / Opportunity

Forge currently has strong local-first project semantics: project roots are discovered, paths are confined, tasks and conversations are stored per project, and memory indexing is scoped to a project root. Many real engineering tasks are multi-repository by nature:

• Update a CLI package and matching docs site.
• Change an SDK and a sample app together.
• Coordinate a backend API change with a frontend consumer.
• Audit shared configuration across several checked-out repositories.
• Apply a migration plan across a monorepo-like workspace that is not a single Git root.

Without explicit workspace support, users must run separate Forge tasks and manually keep context synchronized.

Proposed Feature

Introduce a workspace abstraction that can include multiple project roots and provide:

• forge workspace init, forge workspace add, forge workspace list, and forge workspace run commands.
• Per-project permission scopes and sandbox boundaries inside a single workspace task.
• Cross-project planning where the planner can produce a DAG with project-qualified steps.
• Memory retrieval that can search selected projects while preserving source attribution.
• Dashboard support for workspace task timelines grouped by project.
• Workspace-level summaries, but project-level durable task/session/conversation records.

Scope

Expected implementation areas:

• src/config/loader.ts and src/config/paths.ts for workspace config and path resolution.
• src/core/orchestrator.ts, src/core/loop.ts, and src/scheduler/dag.ts for project-qualified steps.
• src/sandbox/fs.ts for multi-root confinement without weakening realpath protections.
• src/permissions/manager.ts for project-specific grants during workspace execution.
• src/memory/retrieval.ts, src/memory/cold.ts, and index persistence for scoped multi-project search.
• src/cli/commands/ and src/ui/server.ts for workspace commands and views.
• Documentation in docs/ARCHITECTURE.md, docs/SETUP.md, and docs/CLI-REFERENCE.md.

Acceptance Criteria

• Users can define a workspace with two or more project roots using CLI commands.
• Workspace tasks produce project-qualified plan steps and preserve each project's sandbox boundary.
• File/tool actions cannot cross from one project root into another unless the target project is explicitly part of the workspace.
• Permission grants are evaluated with the correct project id and never silently become global.
• Memory search can query all workspace projects or a selected subset with clear source attribution.
• The dashboard can show a workspace task grouped by project, including status and recent events.
• Tests cover cross-root path confinement, permission scoping, and workspace DAG execution.
• Documentation includes examples for multi-repo app/API changes and migration-style workflows.

Non-Goals

• Replacing Git submodules or package manager workspaces.
• Allowing arbitrary filesystem roots outside explicit workspace membership.
• Implementing distributed execution across machines.
• Automatically committing or pushing changes across repositories.

Dependencies / Risks

• This feature touches core invariants around project root discovery and sandbox confinement.
• Existing task state transitions in src/persistence/tasks.ts must remain legal and explicit.
• UI and CLI need consistent vocabulary for workspace, project, task, and step identifiers.
• Memory indexing could become expensive if workspace searches are not bounded.

Open Questions

• Should workspace definitions live in a project-local file, global config, or both?
• Should workspace tasks have a top-level id in addition to per-project task ids?
• How should forge resume behave for a partially completed workspace task?
• Should the first version support nested repositories inside a parent repository?