---
name: multi-project
description: |
  Multi-project orchestration for workspaces with 20+ repos. Builds a dependency DAG across
  projects, runs independent sub-runs in parallel, shares artifacts between dependent projects,
  and enforces a shared budget. Each sub-run uses the standard `run` skill internally.
  <example>User: "archeflow:multi-project" with a multi-run.yaml</example>
  <example>User: "Run this across archeflow, colette, and giesing"</example>
---

# Multi-Project Orchestration

Coordinates ArcheFlow runs across multiple projects. Each project gets its own PDCA run (via `run` skill), but dependencies are respected, artifacts shared, and budget tracked globally.

## Multi-Run Definition

Defined in `.archeflow/multi-run.yaml` or passed via `--config`.

```yaml
name: "giesing-gschichten-v2"
projects:
  - id: archeflow
    path: "../archeflow"
    task: "Add memory injection to run skill"
    workflow: fast
    depends_on: []
  - id: colette
    path: "../writing.colette"
    task: "Add voice validation command"
    depends_on: []
  - id: giesing
    path: "."
    task: "Write story #2"
    workflow: kurzgeschichte
    domain: writing
    depends_on: [archeflow, colette]
budget:
  total_usd: 15.00
  per_project_usd: 10.00
```

**Rules:** Unique `id` per project. `depends_on` references other `id` values. Cycles rejected at validation. At least one project must have empty `depends_on`. `workflow` and `domain` auto-select if omitted.

## Dependency Resolution

Topological sort of the project DAG determines execution order.

```
Layer 0 (immediate): [archeflow, colette]   # No deps, start now
Layer 1:             [giesing]               # Depends on Layer 0
```

Independent projects in the same layer run in parallel. When a project completes, downstream projects with all deps met move to the ready queue.

Cycle detection via Kahn's algorithm. If sorted list is shorter than project list, report the cycle and abort.

## Parallel Execution

For each ready project, start a sub-run as a parallel subagent with `isolation: "worktree"`. Each sub-run invokes `archeflow:run` with its own run_id, workflow, domain, and budget slice.

When `parallel: false`, run sequentially in topological order.

## Cross-Project Artifacts

When project B depends on A, B's Explorer receives upstream artifact summaries:
- Only summaries injected (not full artifacts)
- Large artifacts (>200 lines): extract summary section only
- Cross-project injection happens only in Plan phase
- Downstream Explorer has filesystem access to full artifacts if needed

Artifact directory: `.archeflow/artifacts/<MULTI_RUN_ID>/<project_id>/`

## Budget Coordination

| Level | Type | Behavior |
|-------|------|----------|
| `total_usd` | Hard cap | Stops ALL projects when exceeded |
| `per_project_usd` | Soft cap | Warns but continues |

**Enforcement points:**
1. Before starting a sub-run: estimate cost, halt if > remaining budget
2. After each sub-run: update total, emit `budget.warning` at threshold, emit `budget.exceeded` at cap

Each sub-run receives `min(per_project_usd, remaining_total_budget)` as its budget.

## Failure Handling

| Scenario | Action |
|----------|--------|
| Project fails | Mark `failed`. Independent projects continue. |
| Dependency failed | Mark downstream as `blocked`. Do not start. |
| Budget exceeded | Halt current project. Skip downstream. |
| All entry-points fail | Entire multi-run fails. |

**Blocked project resolution:**
- Autonomous mode: skip blocked projects, continue independent ones
- Attended mode: offer skip / retry / abort

## Progress Tracking

Live progress at `.archeflow/multi-progress.md`, updated after every project state change:

```markdown
| Project | Status | Domain | Phase | Detail |
|---------|--------|--------|-------|--------|
| archeflow | completed | code | -- | 1 cycle, $1.20 |
| colette | running | code | DO | maker drafting |
| giesing | blocked | writing | -- | waiting for colette |

Budget: $3.00 / $15.00 (20%)
```

## Master Events

Written to `.archeflow/events/<MULTI_RUN_ID>.jsonl`:

| Event | When |
|-------|------|
| `multi.start` | Multi-run begins |
| `project.start` | Sub-run launches |
| `project.complete` | Sub-run succeeds |
| `project.failed` | Sub-run fails |
| `project.blocked` | Dependency failed |
| `project.unblocked` | All deps met |
| `budget.warning` | Threshold crossed |
| `budget.exceeded` | Hard cap hit |
| `multi.complete` | All projects done |

## Dry-Run and Resume

**`--dry-run`:** Validates DAG, runs `archeflow:run --dry-run` per project, shows cost estimate. Does not execute.

**`--resume <id>`:** Reconstructs state from master events. Retries failed projects, starts pending ones with deps met.

## Workspace Registry

If `docs/project-registry.md` exists: auto-discover paths by project id, validate existence, update registry after meaningful changes.

## Completion

Status values: `completed` (all done), `partial` (some failed/skipped), `failed` (none completed), `halted` (budget/abort).

Final report includes per-project results, cost breakdown by phase, and dependency graph execution timeline.