Christian Nennemann
d94688ca1b
Remove verbose YAML examples, bash pseudo-code, tutorial prose, and motivational content from configuration/integration skills while preserving all operational protocols, reference tables, and rules. Skills trimmed: domains, colette-bridge, multi-project, cost-tracking, git-integration, custom-archetypes, workflow-design, templates, autonomous-mode, progress, presence.
144 lines
5.0 KiB
Markdown
144 lines
5.0 KiB
Markdown
---
|
|
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.
|