claude-archeflow-plugin/skills/multi-project/SKILL.md

name, description

name

description

multi-project

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> <example>User: "archeflow:multi-project --dry-run"</example>

Multi-Project Orchestration

Coordinates ArcheFlow runs across multiple projects in a workspace. Each project gets its own PDCA run (via the standard run skill), but dependencies between projects are respected, artifacts are shared, and budget is tracked globally.

Prerequisites

Load these skills (they are referenced throughout):

• archeflow:run — single-project PDCA execution loop
• archeflow:process-log — event schema and DAG parent rules
• archeflow:artifact-routing — artifact naming, context injection, cycle archiving
• archeflow:cost-tracking — cost aggregation and budget enforcement
• archeflow:domains — domain detection per project

Invocation

archeflow:multi-project                          # Read from .archeflow/multi-run.yaml
archeflow:multi-project --config path/to.yaml    # Explicit config file
archeflow:multi-project --dry-run                # Plan phase only for all projects, show cost estimate
archeflow:multi-project --resume <multi-run-id>  # Resume a failed/paused multi-run

---

Multi-Run Definition

A multi-run is defined in YAML, either in .archeflow/multi-run.yaml or passed via --config.

name: "giesing-gschichten-v2"
description: "Write second story with improved ArcheFlow + Colette integration"

projects:
  - id: archeflow
    path: "../archeflow"          # Relative to workspace root, or absolute
    task: "Add memory injection to run skill"
    workflow: fast                # fast | standard | thorough (optional, auto-select if omitted)
    domain: code                  # Optional, auto-detected if omitted
    depends_on: []                # No dependencies — can start immediately

  - id: colette
    path: "../writing.colette"
    task: "Add story-specific voice validation command"
    workflow: standard
    domain: code
    depends_on: []                # Independent of archeflow — runs in parallel

  - id: giesing
    path: "."
    task: "Write story #2 using improved tools"
    workflow: kurzgeschichte
    domain: writing
    depends_on: [archeflow, colette]  # Waits for both to complete

budget:
  total_usd: 15.00                # Hard cap — stops all projects when exceeded
  per_project_usd: 10.00          # Soft cap — warns but does not stop

parallel: true                    # Run independent projects concurrently (default: true)

Definition Rules

• id must be unique within the multi-run.
• path is resolved relative to the directory containing the YAML file unless absolute.
• depends_on references other project id values. Cycles are rejected at validation time.
• workflow and domain are optional. If omitted, the run skill auto-selects per project.
• At least one project must have an empty depends_on (otherwise the DAG has no entry point).

---

Workspace Registry Integration

If docs/project-registry.md exists at the workspace root, the multi-project skill can:

1. Auto-discover paths: When path is omitted from a project entry, look up the project id in the registry to find its directory.
2. Validate existence: Before starting, verify that every project path exists on disk. Abort with a clear error if a path is missing.
3. Show registry status: In the progress table, include the project's current sprint goal from the registry alongside the multi-run status.
4. Update registry: After the multi-run completes, update each project's status in the registry if meaningful changes were made (new features, completed sprint goals).

---

Execution Steps

0. Validate and Initialize

0a. Parse and validate the multi-run definition:

1. Read the YAML file.
2. Validate all required fields (name, projects with id/path/task).
3. Resolve all paths to absolute paths.
4. Verify each path exists on disk.
5. Build the dependency DAG.
6. Check for cycles — abort if any detected.
7. Identify the entry-point projects (depends_on is empty).
8. Verify at least one entry-point exists.

0b. Generate multi-run ID and directory structure:

MULTI_RUN_ID="$(date -u +%Y-%m-%d)-${name}"

# Master event file
mkdir -p .archeflow/events
touch .archeflow/events/${MULTI_RUN_ID}.jsonl

# Cross-project artifact directory
mkdir -p .archeflow/artifacts/${MULTI_RUN_ID}
for project in ${PROJECT_IDS}; do
  mkdir -p .archeflow/artifacts/${MULTI_RUN_ID}/${project}
done

# Progress file
touch .archeflow/multi-progress.md

0c. Emit multi.start:

{"ts":"...","run_id":"<MULTI_RUN_ID>","seq":1,"parent":[],"type":"multi.start","phase":"init","agent":null,"data":{"name":"giesing-v2","description":"...","projects":["archeflow","colette","giesing"],"parallel":true,"budget_total_usd":15.00,"dag":{"archeflow":[],"colette":[],"giesing":["archeflow","colette"]}}}

Track state throughout the multi-run:

• MULTI_RUN_ID — unique multi-run identifier
• MULTI_SEQ — master event sequence counter
• PROJECT_STATUS — map of project_id to status (pending | running | completed | failed | blocked | skipped)
• PROJECT_RUN_IDS — map of project_id to its sub-run_id
• TOTAL_COST — running cost total across all projects
• REMAINING_BUDGET — budget minus total cost

---

1. Dependency Resolution

Build a topological sort of the project DAG. This determines execution order.

Given:
  archeflow: depends_on=[]
  colette:   depends_on=[]
  giesing:   depends_on=[archeflow, colette]

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

Algorithm:

1. Find all projects with zero unmet dependencies. These form the current layer.
2. When a project completes, remove it from the dependency lists of all downstream projects.
3. Any project whose dependency list becomes empty moves to the ready queue.
4. Repeat until all projects are complete, failed, or blocked.

Cycle detection: Before starting, verify the DAG is acyclic. Use Kahn's algorithm — if after processing all nodes the sorted list is shorter than the project list, there is a cycle. Report which projects form the cycle and abort.

---

2. Parallel Execution

For each project in the ready queue, start a sub-run. Independent projects run concurrently.

Starting a sub-run:

For each ready project:
  1. Set PROJECT_STATUS[project_id] = "running"
  2. Generate sub-run ID: MULTI_RUN_ID/project_id
     (e.g., "2026-04-03-giesing-v2/archeflow")
  3. Emit project.start to master event file
  4. cd into the project's path
  5. Invoke archeflow:run with:
     - run_id = MULTI_RUN_ID/project_id
     - workflow = project.workflow (or auto-select)
     - domain = project.domain (or auto-detect)
     - budget = min(per_project_budget, remaining_total_budget)
     - artifact_dir = .archeflow/artifacts/MULTI_RUN_ID/project_id/
  6. The sub-run emits its own events to its own JSONL file
     inside the project's directory (standard run behavior)

Concurrency model:

When parallel: true (default), spawn independent projects as parallel subagents:

Agent(
  description: "Multi-project sub-run: <project_id> — <task>",
  prompt: "Run archeflow:run in <path> with task: <task>.
    Run ID: <MULTI_RUN_ID>/<project_id>
    Workflow: <workflow>
    Domain: <domain>
    Budget: $<per_project_budget>
    Save artifacts to: .archeflow/artifacts/<MULTI_RUN_ID>/<project_id>/
    When complete, report: status, cost, artifact list, and any issues.",
  isolation: "worktree",
  mode: "bypassPermissions"
)

Launch all Layer 0 projects simultaneously. As each completes, check if any Layer 1+ projects become unblocked.

When parallel: false, run projects sequentially in topological order. Still respect dependencies — a project does not start until all its dependencies have completed.

---

3. Master Events

All multi-run-level events are written to .archeflow/events/<MULTI_RUN_ID>.jsonl. These track the overall orchestration, not individual PDCA phases (those go to each project's own event file).

Master Event Types

Event	When	Key Data
multi.start	Multi-run begins	Project list, DAG, budget
project.start	A sub-run launches	project_id, run_id, path
project.complete	A sub-run finishes successfully	project_id, status, cost, artifacts
project.failed	A sub-run fails	project_id, error, cost_so_far
project.blocked	A dependency failed, blocking this project	project_id, blocked_by
project.unblocked	All dependencies met, project can start	project_id, unblocked_by
project.skipped	User chose to skip a blocked project	project_id, reason
budget.warning	Budget threshold crossed	spent, budget, percent
budget.exceeded	Hard budget cap hit	spent, budget, halted_projects
multi.complete	All projects done (or halted)	status, projects_completed, total_cost

Example Master Event Stream

{"seq":1,"type":"multi.start","phase":"init","data":{"name":"giesing-v2","projects":["archeflow","colette","giesing"],"parallel":true,"budget_total_usd":15.00}}
{"seq":2,"type":"project.start","phase":"run","data":{"project":"archeflow","run_id":"2026-04-03-giesing-v2/archeflow","path":"/home/c/projects/archeflow"}}
{"seq":3,"type":"project.start","phase":"run","data":{"project":"colette","run_id":"2026-04-03-giesing-v2/colette","path":"/home/c/projects/writing.colette"}}
{"seq":4,"type":"project.complete","phase":"run","data":{"project":"archeflow","status":"completed","run_id":"2026-04-03-giesing-v2/archeflow","cost_usd":1.20,"artifacts":["plan-explorer.md","plan-creator.md","do-maker.md","check-guardian.md"]}}
{"seq":5,"type":"project.complete","phase":"run","data":{"project":"colette","status":"completed","run_id":"2026-04-03-giesing-v2/colette","cost_usd":1.80,"artifacts":["plan-creator.md","do-maker.md","check-guardian.md","check-sage.md"]}}
{"seq":6,"type":"project.unblocked","phase":"run","data":{"project":"giesing","unblocked_by":["archeflow","colette"]}}
{"seq":7,"type":"project.start","phase":"run","data":{"project":"giesing","run_id":"2026-04-03-giesing-v2/giesing","path":"/home/c/projects/book.giesing-gschichten"}}
{"seq":8,"type":"project.complete","phase":"run","data":{"project":"giesing","status":"completed","run_id":"2026-04-03-giesing-v2/giesing","cost_usd":3.50,"artifacts":["plan-explorer.md","plan-creator.md","do-maker.md","check-guardian.md","check-sage.md"]}}
{"seq":9,"type":"multi.complete","phase":"done","data":{"status":"completed","projects_completed":3,"projects_failed":0,"total_cost_usd":6.50,"budget_remaining_usd":8.50}}

---

4. Cross-Project Artifacts

When project B depends on project A, B's agents can access A's artifacts. This is the primary mechanism for cross-project information flow.

Artifact Directory Layout

.archeflow/artifacts/<MULTI_RUN_ID>/
├── archeflow/                  # Sub-run artifacts from archeflow
│   ├── plan-explorer.md
│   ├── plan-creator.md
│   ├── do-maker.md
│   ├── do-maker-files.txt
│   └── check-guardian.md
├── colette/                    # Sub-run artifacts from colette
│   ├── plan-creator.md
│   ├── do-maker.md
│   └── check-sage.md
└── giesing/                    # Sub-run artifacts from giesing (depends on both)
    ├── plan-explorer.md        # Explorer can reference upstream artifacts
    ├── plan-creator.md
    ├── do-maker.md
    └── check-guardian.md

Cross-Project Context Injection

When a dependent project's sub-run starts, inject upstream artifact summaries into the Explorer's prompt:

## Upstream Project Results

### archeflow (completed)
Summary: Added memory injection to run skill.
Key artifacts:
- plan-creator.md: <first 20 lines or summary section>
- do-maker.md: <implementation summary>

### colette (completed)
Summary: Added story-specific voice validation command.
Key artifacts:
- plan-creator.md: <first 20 lines or summary section>
- do-maker.md: <implementation summary>

Use these results as context. The changes from these projects are available in their
respective directories and have been committed to their branches.

Rules for cross-project injection:

• Only inject summaries, not full artifacts (keep context small).
• If an upstream artifact is large (>200 lines), extract the summary/overview section only.
• The dependent project's Explorer has filesystem access to read full upstream artifacts if needed.
• Cross-project injection happens ONLY in the Plan phase (Explorer and Creator). The Maker works from the Creator's proposal, which already incorporates upstream context.

---

5. Budget Coordination

The multi-run has a shared budget across all projects.

Budget Hierarchy

total_usd: 15.00           # Hard cap — stops ALL projects when exceeded
per_project_usd: 10.00     # Soft cap — warns but does not stop individual project

Budget Tracking

Maintain a running total across all sub-runs:

TOTAL_COST = sum of all project costs reported in project.complete events
REMAINING = total_usd - TOTAL_COST

Budget Enforcement Points

1. Before starting a sub-run:

   • Estimate the sub-run cost (based on workflow and domain).
   • If estimated cost > REMAINING: warn and ask user (attended) or halt (autonomous).

2. After each sub-run completes:

   • Update TOTAL_COST with actual cost from the sub-run.
   • If TOTAL_COST > total_usd * warn_at_percent: emit budget.warning.
   • If TOTAL_COST > total_usd: emit budget.exceeded, halt remaining projects.

3. Per-project soft cap:

   • Each sub-run receives min(per_project_usd, REMAINING) as its budget.
   • The run skill's own budget enforcement handles the per-project cap.
   • If a project exceeds per_project_usd, it warns but continues (soft cap).

Budget Events

{"seq":5,"type":"budget.warning","data":{"spent_usd":11.50,"budget_usd":15.00,"percent":77,"message":"Budget 77% consumed"}}
{"seq":8,"type":"budget.exceeded","data":{"spent_usd":15.30,"budget_usd":15.00,"halted_projects":["giesing"],"message":"Hard budget cap exceeded. Halting remaining projects."}}

---

6. Failure Handling

Failures in one project affect downstream projects but not independent ones.

Failure Scenarios

Scenario	Action
Project fails (run error, test failure, max cycles)	Mark as failed in master events. Independent projects continue.
Dependency of project X failed	Mark X as blocked. Do not start X.
Budget exceeded mid-run	Halt the current project. Mark remaining as blocked.
All entry-point projects fail	Entire multi-run fails. No downstream projects can start.

Blocked Project Resolution

When a project is blocked because a dependency failed, offer three options:

1. Skip: Mark the blocked project as skipped. Continue with other independent projects.
2. Retry: Re-run the failed dependency. If it succeeds, unblock downstream projects.
3. Abort: Stop the entire multi-run. Report what completed and what did not.

In autonomous mode, the default action is skip — blocked projects are skipped, independent projects continue, and the multi-run completes with partial results.

In attended mode, prompt the user with the options above.

Failure Events

{"seq":4,"type":"project.failed","data":{"project":"archeflow","error":"Max cycles reached with unresolved CRITICAL findings","cost_usd":2.10}}
{"seq":5,"type":"project.blocked","data":{"project":"giesing","blocked_by":["archeflow"],"reason":"Dependency 'archeflow' failed"}}

---

7. Progress Tracking

Maintain a live progress file at .archeflow/multi-progress.md. Update it after every project state change.

# Multi-Run: giesing-v2
Started: 2026-04-03T14:00:00Z

| 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
| | Amount |
|---|--------|
| Spent | $3.00 |
| Budget | $15.00 |
| Remaining | $12.00 |
| Utilization | 20% |

## Dependency Graph

archeflow ----
+---> giesing colette ------/

## Timeline
- 14:00:00 — Started archeflow, colette (parallel)
- 14:05:23 — archeflow completed ($1.20, 1 cycle)
- 14:06:10 — colette DO phase, maker drafting

Update this file after:

• A project starts
• A project changes phase (via status polling or sub-agent reporting)
• A project completes or fails
• A project becomes unblocked
• Budget threshold is crossed

---

8. Completion

When all projects are complete (or blocked/skipped with no more actionable items):

8a. Emit multi.complete:

{"seq":9,"type":"multi.complete","phase":"done","data":{"status":"completed","projects_completed":3,"projects_failed":0,"projects_skipped":0,"total_cost_usd":6.50,"budget_remaining_usd":8.50,"duration_ms":600000}}

Status values:

• completed — all projects finished successfully
• partial — some projects completed, some failed/skipped
• failed — no projects completed successfully
• halted — stopped due to budget or user abort

8b. Generate multi-run report:

# Multi-Run Report: giesing-v2

## Summary
| Metric | Value |
|--------|-------|
| Projects | 3 |
| Completed | 3 |
| Failed | 0 |
| Total cost | $6.50 / $15.00 |
| Duration | 10m 00s |

## Per-Project Results
### archeflow
- **Status:** completed
- **Task:** Add memory injection to run skill
- **Workflow:** fast (1 cycle)
- **Cost:** $1.20
- **Key artifacts:** plan-creator.md, do-maker.md

### colette
- **Status:** completed
- **Task:** Add story-specific voice validation command
- **Workflow:** standard (1 cycle)
- **Cost:** $1.80
- **Key artifacts:** plan-creator.md, do-maker.md, check-sage.md

### giesing
- **Status:** completed
- **Task:** Write story #2 using improved tools
- **Workflow:** kurzgeschichte (2 cycles)
- **Cost:** $3.50
- **Key artifacts:** plan-explorer.md, do-maker.md, check-guardian.md

## Dependency Graph Execution
archeflow (Layer 0) ----> completed
colette   (Layer 0) ----> completed
giesing   (Layer 1) ----> unblocked ----> completed

## Cost Breakdown
| Project | Plan | Do | Check | Total |
|---------|------|----|-------|-------|
| archeflow | $0.20 | $0.60 | $0.40 | $1.20 |
| colette | $0.30 | $0.80 | $0.70 | $1.80 |
| giesing | $0.50 | $2.00 | $1.00 | $3.50 |
| **Total** | **$1.00** | **$3.40** | **$2.10** | **$6.50** |

8c. Update master event index:

Append to .archeflow/events/index.jsonl:

{"run_id":"2026-04-03-giesing-v2","ts":"2026-04-03T14:10:00Z","type":"multi","task":"Write second story with improved ArcheFlow + Colette integration","status":"completed","projects":3,"total_cost_usd":6.50}

8d. Update workspace registry (if applicable):

If docs/project-registry.md exists and project statuses changed meaningfully, update the registry entries for affected projects.

---

Dry-Run Mode

When --dry-run is specified:

1. Validate the multi-run definition (DAG, paths, budget).
2. For each project (in topological order), run archeflow:run --dry-run to get a cost estimate and plan preview.
3. Display a summary:

Multi-Run Dry Run: giesing-v2
  Projects: 3
  Dependency layers: 2
  Parallel execution: yes

  Layer 0 (parallel):
    archeflow — fast workflow, code domain
      Estimated cost: $0.50-1.50
    colette — standard workflow, code domain
      Estimated cost: $1.00-3.00

  Layer 1 (after Layer 0):
    giesing — kurzgeschichte workflow, writing domain
      Estimated cost: $2.00-5.00

  Total estimated cost: $3.50-9.50
  Budget: $15.00 (sufficient)

  Proceed? [y/n]

4. Do NOT emit multi.complete. The multi-run is paused.
5. If user says yes, start the full multi-run using the validated config.

---

Resume Mode

When --resume <multi-run-id> is specified:

1. Read the master event file .archeflow/events/<multi-run-id>.jsonl.
2. Reconstruct PROJECT_STATUS from events (which projects completed, failed, are pending).
3. Identify resumable projects:
   • failed projects can be retried.
   • blocked projects whose blockers are now completed (e.g., after manual fix) can start.
   • pending projects that were never started can start if their deps are met.
4. Display current state and ask for confirmation.
5. Continue the multi-run from where it left off, appending to the existing master event file.

Resume emits a multi.resume event:

{"seq":10,"type":"multi.resume","phase":"init","data":{"resumed_from":"2026-04-03-giesing-v2","projects_completed":["archeflow"],"projects_to_run":["colette","giesing"]}}

---

Integration with Existing Skills

Skill	Integration Point
run	Each sub-run is a standard archeflow:run invocation. The multi-project skill wraps and coordinates multiple runs.
process-log	Master events follow the same schema (ts, run_id, seq, parent, type, phase, agent, data). Sub-run events use the standard event types.
artifact-routing	Each sub-run follows standard artifact routing internally. Cross-project artifacts follow the injection rules in Section 4.
cost-tracking	Per-project costs come from sub-run run.complete events. The multi-project skill aggregates them and enforces the shared budget.
domains	Each project auto-detects its domain independently. Different projects in the same multi-run can have different domains.
git-integration	Each sub-run manages its own branch. The multi-project skill does not merge across repos — each project's Act phase handles its own merge.
autonomous-mode	Multi-project runs are autonomous-mode-friendly. Budget enforcement is strict (halt, don't prompt). Blocked projects are skipped.

---

Progress Display

Throughout the multi-run, display live progress:

━━━ ArcheFlow Multi-Run: giesing-v2 ━━━━━━━━━━━━━━━━━━━
Projects: 3 | Budget: $15.00 | Parallel: yes

[archeflow]  fast/code     -> running (Plan: Creator designing...)
[colette]    standard/code -> running (Do: Maker implementing...)
[giesing]    kurzgeschichte/writing -> blocked (waiting: archeflow, colette)

Cost: $1.80 / $15.00 (12%)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Update the display when:

• A project changes state (start, phase change, complete, fail, unblock)
• Budget thresholds are crossed

---

Error Handling

Error	Response
YAML parse error	Abort before starting. Report the parse error with line number.
Dependency cycle detected	Abort. Report which projects form the cycle.
Project path does not exist	Abort. Report the missing path.
Sub-run agent fails to return	Mark project as failed (5-min timeout per the run skill). Continue independent projects.
Master event write fails	Log warning. Continue orchestration. Events are observation, not control flow.
Artifact directory creation fails	Abort the affected project. This is blocking for cross-project artifact sharing.
Budget exceeded mid-project	Halt that project immediately. Emit budget.exceeded. Skip downstream dependents.

---

Design Principles

1. Each project is autonomous. Sub-runs use the standard run skill without modification. The multi-project skill is a coordinator, not a replacement.
2. DAG over sequence. Dependencies are declared, not implied by order. Independent projects always run in parallel when possible.
3. Shared budget, independent domains. Budget is global, but each project detects its own domain, selects its own workflow, and manages its own artifacts.
4. Fail forward. A failure in one project does not halt independent projects. Only downstream dependents are blocked.
5. Artifacts are the interface. Projects communicate through saved artifacts, not shared memory or direct agent-to-agent messaging.
6. Resume over restart. Multi-runs can be resumed from any point. Master events provide enough state to reconstruct progress.
7. Registry-aware. When a workspace registry exists, use it for discovery and keep it updated. When it does not exist, everything still works.