One change spans multiple repos?

Keep one thread across repository-bounded agents

Link a shared change to repo-local tasks while your existing agent tools do the work.

Starting state

One umbrella. Two real child repositories.

Coordinate an OAuth redirect contract across backend and frontend without moving execution artifacts into one root.

+The umbrella contains backend and frontend child Git repositories.
+Root and repo-local AGENTS.md files are user-authored instructions for external agents.
+The public DevSpecs v1.3.0 release provides experimental workspace records and repo-local task links.
+Agent spawning and implementation remain outside DevSpecs.

Release source: devspecs-cli v1.3.0
Commit: 7fd88d55
DevSpecs: v1.3

DevSpecs entry

$ds workspace init .

DeveloperDevSpecsCoding agent

Advanced workflow

One shared reason. Repo-local execution.

DevSpecs links the change and lifecycle records. Your existing agent tools run each repository's work.

Experimental in v1.3

Human

Shared goal

Protect the OAuth redirect contract across API and web.

DevSpecs writes

Umbrella records

workspace.yaml + DEVSPECS-C001 change + repo links

Repository-local

backend

External agent A

AGENTS.md: user-authored boundaries
Task: devspecs-c001-backend / A01
State: validated / promote

source + testsplan + resultcheckpoint

The external agent edits and tests only this repository.

Repository-local

frontend

External agent B

AGENTS.md: user-authored boundaries
Task: devspecs-c001-frontend / A01
State: blocked / ruled out

source + testsplan + resultdecision

The external agent edits and tests only this repository.

DevSpecs trace

Known change, linked repo states

backend completed + frontend blocked = required repos resolved

Human

Re-enter and review

Inspect each repo. Trace is not merge approval.

Repo layoutowns source, tests, commits

AGENTS.mduser-authored agent rules

Agent toolsrun edits and tests

DevSpecslinks tasks and decisions

Workflow

STEP 1 OF 4

Register the real child repositories

Developer

Initialize the umbrella after the backend and frontend Git roots exist. DevSpecs records their aliases and paths.

Command

$ds workspace init . --json

CLI output

Workspace/workspace

Repobackend -> ./backend

Repofrontend -> ./frontend

Index statusnot_indexed

What this tells you

The manifest knows the two repository roots. It does not combine their source indexes or create an agent process.

Continue with

Create one shared change and name the required repositories.

Output verified against the pinned run

This receipt is the capture file used to check the excerpt. You do not need it to follow the workflow.

Public v1.3.0 fixture audit · docs/growth/umbrella-repository-support-audit.md

STEP 2 OF 4

Link one change to repo-local tasks

DevSpecs

Keep the cross-repo reason at the umbrella root while each implementation plan and result stays inside its owning repository.

Command

$ds workspace change create "OAuth redirect contract across API and web" --workspace . --repos backend,frontend
ds workspace slice create DEVSPECS-C001 --workspace . --repo backend --name "Validate backend redirect contract" --no-refresh --index=false
ds workspace slice create DEVSPECS-C001 --workspace . --repo frontend --name "Validate frontend redirect handling" --no-refresh --index=false

CLI output

Changedevspecs/changes/DEVSPECS-C001-*.md

Backendbackend/devspecs/tasks/devspecs-c001-backend/A01-*-plan.md

Frontendfrontend/devspecs/tasks/devspecs-c001-frontend/A01-*-plan.md

Linksworkspace_id + parent_change + repo_alias

What this tells you

The umbrella owns the shared reason and links. Each child repo owns its task lifecycle and evidence.

Continue with

Use the repo-aware handoff with the external agent assigned to each repo.

Output verified against the pinned run

This receipt is the capture file used to check the excerpt. You do not need it to follow the workflow.

Public v1.3.0 fixture audit · docs/growth/umbrella-repository-support-audit.md

STEP 3 OF 4

Run each repository's bounded handoff

Coding agent

Your existing coding tools open the repo-local prompt, edit that repository, run its tests, and return evidence for a checkpoint.

Command

$ds apply devspecs-c001-backend --repo ./backend
ds apply devspecs-c001-frontend --repo ./frontend

CLI output

Backend targetA01 only

Frontend targetA01 only

Checkpoint commands preserve --repo boundaries

DevSpecs does not spawn or observe either agent

What this tells you

Agent parallelism comes from Codex, Claude, Cursor, or another runner. DevSpecs supplies durable boundaries and receipts.

Continue with

Checkpoint each repo result, including blocked or ruled-out work.

STEP 4 OF 4

Return to one trace, then inspect each repo

Developer

Trace the known change ID to recover repo-local lifecycle states without mistaking the aggregate for merge approval.

Command

$ds workspace trace DEVSPECS-C001 --workspace . --json

CLI output

BackendA01 completed / promote

FrontendA01 blocked / ruled out

Workspace tracecomplete

Index statusindex_missing

What this tells you

Every required repo is resolved, so trace reports complete. One slice is blocked; the human still reviews both repositories and decides what ships.

Continue with

Inspect the backend diff and the frontend blocker before opening a follow-up or approving any merge.

Output verified against the pinned run

This receipt is the capture file used to check the excerpt. You do not need it to follow the workflow.

Public v1.3.0 fixture audit · docs/growth/umbrella-repository-support-audit.md

Result

The developer recovered one shared change, one completed backend slice, and one explicitly blocked frontend slice. Plans, results, checkpoints, source, and tests remained inside the owning repositories; the workspace trace did not approve either merge.

umbrella/devspecs/workspace.yaml + workspace.md
umbrella/devspecs/changes/DEVSPECS-C001-*.md
backend/devspecs/tasks/devspecs-c001-backend/**
frontend/devspecs/tasks/devspecs-c001-frontend/**

Common failure

Treating workspace records as an agent orchestrator

DevSpecs v1.3.0 links a shared change to repo-local tasks. It does not launch agents, watch their edits, enforce AGENTS.md, or build a unified cross-repo search index.

Use your existing agent runner for repo-local work, checkpoint observed evidence, and use workspace trace only to recover known linked lifecycle state.