re_struct/docs/superpowers/plans/2026-03-21-batch-orchestrator.md

# Batch Orchestrator Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Implement the batch orchestrator for re:struct — a `/project:run-batch` command that semi-autonomously processes planned tasks from task.md using subagents.

**Architecture:** A command file (`.claude/commands/run-batch.md`) encodes the orchestrator flow as a Claude prompt instruction. A rules file (`rules/batch-orchestration.md`) codifies the constraints. Both are markdown — no application code. The orchestrator leverages Claude Code's native Agent tool for subagent dispatch.

**Tech Stack:** Claude Code commands (markdown prompts), Claude Code Agent tool, project rules system

**Spec:** `docs/superpowers/specs/2026-03-21-batch-orchestrator-design.md`

---

## File Structure

| File | Action | Responsibility |
|------|--------|----------------|
| `rules/batch-orchestration.md` | Create | Orchestrator/subagent contract rules, loaded via CLAUDE.md |
| `.claude/commands/run-batch.md` | Create | The orchestrator command — full flow from parsing to consolidation |
| `.claude/settings.json` | Create | Project-level permissions for batch execution |
| `CLAUDE.md` | Modify | Reference new rule, add run-batch to Workflow-Commands |

---

### Task 1: Create `rules/batch-orchestration.md`

**Files:**
- Create: `rules/batch-orchestration.md`

This file defines the hard constraints that apply during any batch orchestration run.
It is referenced from CLAUDE.md and automatically loaded into context.

- [ ] **Step 1: Write the rules file**

```markdown
# Batch Orchestration Rules

## Orchestrator Constraints
- The orchestrator only reads task.md and subagent summaries — never full output files
- The orchestrator only processes tasks from the active phase (defined in CLAUDE.md "Aktiver Scope")
- Shared state files (status.md, decisions-log.md, task.md) are only written by the orchestrator, never by subagents
- Phase-specific shared artifacts (e.g., capabilities-inventory.md) are updated only by the orchestrator during consolidation
- The orchestrator never triggers /project:phase-transition or starts tasks from the next phase
- When all DoD items of the active phase are complete: hard stop, inform user
- Missing batch parameters (items, checkpoint mode) are always queried interactively before starting

## Subagent Constraints
- Each subagent writes only its own assigned output file
- Subagents never write to task.md, status.md, decisions-log.md, or CLAUDE.md
- Each subagent returns a 2-3 sentence summary as its return value

## Task Parsing
- The orchestrator parses the first section in task.md that contains ### sub-headings with - [ ] checkboxes (the work section)
- Flat checkbox lists without sub-headings are treated as Definition of Done and ignored for dispatching
- Tasks under the same ### heading form a parallelization group (can run concurrently)
- Tasks under different ### headings are sequential (Group N+1 starts after Group N completes and checkpoint passes)

## Context Loading
- Base context (always): project rules of active phase + status.md
- Phase-specific context: follow phase rules if they define context requirements (e.g., discovery-waves.md)
- Task-specific context: if task declares (context: file1, file2), load those; otherwise load output files from prior groups
- Prefer condensed documents over raw sources

## Checkpoint Modes
- after-each (default): pause after each group, show summaries, wait for user input
- after-batch:N: run N groups, then pause
- at-end: run all groups, consolidated review at end
- Phase boundary: always a hard stop regardless of selected mode

## Error Handling
- On subagent failure: mark task as failed in checkpoint summary, do not block other parallel tasks in the same group
- Failed tasks stay - [ ] in task.md (not marked as completed)
- Failures are reported at the next checkpoint with the error details
```

- [ ] **Step 2: Verify the rules file covers all spec constraints**

Cross-check against spec sections:
- Orchestrator Flow (steps 1-5) ✓
- Subagent Contract (boundaries) ✓
- Task Parsing (conventions) ✓
- Context Loading Strategy ✓
- Checkpoint Modes ✓
- Phase Protection ✓
- Error Handling ✓

- [ ] **Step 3: Commit**

```bash
git add rules/batch-orchestration.md
git commit -m "feat: add batch orchestration rules"
```

---

### Task 2: Create `.claude/commands/run-batch.md`

**Files:**
- Create: `.claude/commands/run-batch.md`

This is the main orchestrator command. It's a Claude prompt instruction that encodes
the complete flow. When invoked, Claude follows these instructions step by step.

**Important:** This file must be self-contained enough that Claude can follow it without
having seen the spec. The rules file provides the constraints; this file provides the procedure.

- [ ] **Step 1: Write the command file — Preamble and Phase Detection**

The command file starts with reading CLAUDE.md and determining the active phase:

```markdown
Du bist der Batch-Orchestrator. Führe die folgenden Schritte der Reihe nach aus.

Beachte dabei strikt die Regeln aus @rules/batch-orchestration.md

## Schritt 1 — Phase und Tasks erkennen

1. Lies CLAUDE.md und bestimme die aktive Phase und das Arbeitsverzeichnis
2. Lies die task.md der aktiven Phase
3. Finde den Arbeitsabschnitt: den ersten Abschnitt mit ### Unterüberschriften und - [ ] Checkboxen
4. Ignoriere flache Checkbox-Listen ohne Unterüberschriften (das ist die Definition of Done)
5. Erstelle eine nummerierte Liste aller offenen Tasks (- [ ]) mit:
   - Nummer
   - Task-Beschreibung
   - Gruppenname (### Überschrift)
   - Output-Pfad (falls im Text erkennbar)
```

- [ ] **Step 2: Write the command file — Permission Check**

```markdown
## Schritt 1.5 — Berechtigungen prüfen

Prüfe ob die folgenden Tools ohne Nachfrage verfügbar sind: Read, Write, Edit, Glob, Grep, Agent.

Falls Berechtigungen fehlen, zeige dem User:
> ⚠ Für den Batch-Modus werden folgende Berechtigungen benötigt: [Liste]
> Bitte konfiguriere sie in `.claude/settings.json` oder `.claude/settings.local.json`:
> ```json
> { "permissions": { "allow": ["Read", "Write", "Edit", "Glob", "Grep", "Agent"] } }
> ```

Brich dann ab. Starte den Batch NICHT ohne bestätigte Berechtigungen.
```

- [ ] **Step 3: Write the command file — Parameter Query**

```markdown
## Schritt 2 — Parameter abfragen

Falls der User beim Aufruf keine Parameter angegeben hat, oder Parameter fehlen, frage interaktiv:

Zeige die Task-Liste aus Schritt 1 und frage:

> Ich sehe N offene Tasks in Phase X:
> [nummerierte Liste mit Gruppenname]
>
> **Welche Tasks?** (alle / Nummern z.B. 1-3 / Gruppenname z.B. wave-3)
> **Checkpoint-Modus?** (after-each / after-batch:N / at-end)

Warte auf die Antworten des Users.

Zeige dann eine Zusammenfassung des geplanten Batch-Laufs:
> **Batch-Plan:**
> - Tasks: [ausgewählte Tasks]
> - Gruppen: [Gruppenreihenfolge, parallele Tasks markiert]
> - Checkpoint: [gewählter Modus]
> - Phase: [aktive Phase]
>
> Soll ich starten?

Warte auf Bestätigung.
```

- [ ] **Step 4: Write the command file — Group Processing Loop**

```markdown
## Schritt 3 — Gruppen abarbeiten

Arbeite die Gruppen in der Reihenfolge ihrer ### Überschriften ab.

### Für jede Gruppe:

**Context bestimmen:**
- Basis: rules der aktiven Phase + status.md
- Phasen-spezifisch: falls Phase-Rules Context definieren (z.B. discovery-waves.md), folge diesen
- Task-spezifisch: falls der Task (context: datei1, datei2) deklariert, lade diese
- Fallback: alle existierenden Output-Dateien vorheriger Gruppen im aktuellen Batch

**Tasks dispatchen:**
- Falls die Gruppe nur einen Task hat: dispatche einen Subagent
- Falls die Gruppe mehrere Tasks hat: dispatche alle als parallele Subagents

Für jeden Subagent verwende das Agent-Tool mit folgendem Prompt-Muster:

> Du bist ein Subagent im re:struct Framework.
>
> **Dein Auftrag:** [Task-Beschreibung aus task.md]
> **Output-Datei:** [Pfad]
> **Context-Dateien zum Lesen:** [Liste der Context-Dateien]
> **Regeln:** Beachte @rules/framework-constraints.md und @rules/language-conventions.md
>
> Schreibe dein Ergebnis in die Output-Datei.
> Gib am Ende eine Zusammenfassung in 2-3 Sätzen zurück (NUR die Zusammenfassung als Return-Value, nicht in die Datei).

**Auf Abschluss warten:**
- Warte bis alle Subagents der Gruppe fertig sind
- Sammle die Summaries und eventuelle Fehler

**Fehlerbehandlung:**
- Falls ein Subagent fehlschlägt: notiere den Fehler, blockiere aber nicht andere parallele Tasks
- Fehlgeschlagene Tasks werden beim Checkpoint gemeldet
```

- [ ] **Step 5: Write the command file — Checkpoint Handling**

```markdown
### Checkpoint-Logik

Nach jeder abgeschlossenen Gruppe: prüfe ob ein Checkpoint fällig ist.

**after-each:** Immer Checkpoint nach jeder Gruppe.
**after-batch:N:** Checkpoint nach jeder N-ten Gruppe. Zähler beginnt bei 1.
**at-end:** Kein Checkpoint bis alle Gruppen fertig sind.

**Bei einem Checkpoint:**

Zeige dem User:
> **Checkpoint — Gruppe "[Gruppenname]" abgeschlossen**
>
> | Task | Output | Status | Summary |
> |------|--------|--------|---------|
> | [Name] | [Dateipfad] | ✅ / ❌ | [2-3 Sätze] |
>
> **Befehle:** `weiter` | `stopp` | `zeig mir [datei]`

- Bei `weiter`: nächste Gruppe starten
- Bei `stopp`: gehe zu Schritt 4 (Konsolidierung)
- Bei `zeig mir [datei]`: Datei lesen und anzeigen, dann erneut fragen

**Phasen-Checkpoint (immer aktiv):**
Prüfe nach jeder Gruppe ob alle offenen Tasks der Phase erledigt sind (prüfe die DoD-Sektion).
Falls ja: STOPP, unabhängig vom Checkpoint-Modus:
> **Alle Tasks dieser Phase sind abgeschlossen.**
> Ein Phasenwechsel ist möglich. Nutze `/project:phase-transition` wenn du bereit bist.

Gehe dann zu Schritt 4.
```

- [ ] **Step 6: Write the command file — Consolidation**

```markdown
## Schritt 4 — Konsolidierung

Führe die folgenden Updates durch (nur der Orchestrator, nie Subagents):

1. **task.md aktualisieren:**
   - Markiere erfolgreich abgeschlossene Tasks mit [x]
   - Fehlgeschlagene Tasks bleiben [ ]

2. **status.md aktualisieren:**
   - Aktuellen Stand in 2-3 Sätzen
   - Liste der abgeschlossenen Tasks
   - Falls Fehler auftraten: dokumentiere sie
   - Nächste Schritte (verbleibende offene Tasks)

3. **decisions-log.md:**
   - Falls während des Batch Entscheidungen relevant wurden: Einträge erstellen
   - Format: siehe docs/templates/decisions-log-entry.md

4. **Phasen-spezifische Shared Artifacts:**
   - Falls die Phase geteilte Dokumente hat (z.B. capabilities-inventory.md in Discovery):
     aktualisiere sie mit den konsolidierten Ergebnissen aus den Subagent-Summaries

## Schritt 5 — Commit-Vorschlag

Zeige dem User:
> **Batch abgeschlossen.** Zusammenfassung:
> - [N] Tasks erfolgreich, [M] fehlgeschlagen
> - Aktualisiert: task.md, status.md [, decisions-log.md] [, weitere]
> - Output-Dateien: [Liste der neuen Dateien]
>
> Soll ich einen Commit erstellen?

Falls ja: erstelle einen Commit mit einer Nachricht die den Batch beschreibt,
z.B. `feat: complete Wave 2 entry-points analysis`
```

- [ ] **Step 7: Assemble the complete command file**

Combine Steps 1-6 into the final `.claude/commands/run-batch.md` file.
Ensure the flow is continuous and there are no gaps between sections.

- [ ] **Step 8: Verify the command file against the spec**

Cross-check every section of the spec against the command file:
- [ ] Task parsing (work section vs DoD) — Schritt 1
- [ ] Permission check — Schritt 1.5
- [ ] Interactive parameter query — Schritt 2
- [ ] Group processing with parallelization — Schritt 3
- [ ] Subagent contract (input/output/boundaries) — Subagent prompt template
- [ ] Context loading strategy (base/phase/task) — Context bestimmen
- [ ] Checkpoint modes (after-each, after-batch:N, at-end) — Checkpoint-Logik
- [ ] Phase protection (hard stop) — Phasen-Checkpoint
- [ ] Error handling (failed tasks) — Fehlerbehandlung
- [ ] Consolidation (task.md, status.md, decisions-log, shared artifacts) — Schritt 4
- [ ] Commit proposal — Schritt 5
- [ ] session-start/end replacement — implicitly handled (no reference to session-start needed)

- [ ] **Step 9: Commit**

```bash
git add .claude/commands/run-batch.md
git commit -m "feat: add run-batch orchestrator command"
```

---

### Task 3: Create `.claude/settings.json`

**Files:**
- Create: `.claude/settings.json`

Project-level permissions that ensure the batch orchestrator and its subagents
can operate without permission prompts. This file is separate from the existing
`.claude/settings.local.json` (which contains user-specific permissions).

- [ ] **Step 1: Write settings.json**

```json
{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Edit",
      "Write",
      "Agent"
    ]
  }
}
```

- [ ] **Step 2: Verify no conflict with settings.local.json**

Read `.claude/settings.local.json` and confirm the two files don't conflict.
`settings.local.json` has specific Bash and Skill permissions; `settings.json`
adds the core tool permissions. These are additive, no conflict expected.

- [ ] **Step 3: Commit**

```bash
git add .claude/settings.json
git commit -m "feat: add project-level permissions for batch orchestration"
```

---

### Task 4: Update CLAUDE.md

**Files:**
- Modify: `CLAUDE.md` (two sections)

- [ ] **Step 1: Add batch-orchestration rule reference**

In the `## Regeln` section, add:
```
@rules/batch-orchestration.md
```

- [ ] **Step 2: Add run-batch to Workflow-Commands**

In the `## Workflow-Commands` section, add:
```
- `/project:run-batch` — Batch von geplanten Tasks semi-autonom abarbeiten (Checkpoints, Parallelisierung)
```

- [ ] **Step 3: Verify CLAUDE.md is consistent**

Read the updated CLAUDE.md and verify:
- The rule reference is in the Regeln section alongside existing rules
- The command is listed alongside existing commands
- No other sections need updating

- [ ] **Step 4: Commit**

```bash
git add CLAUDE.md
git commit -m "docs: reference batch orchestration rule and command in CLAUDE.md"
```

---

### Task 5: Verification Dry-Run

**Files:**
- Read-only: all created/modified files

- [ ] **Step 1: Verify file structure**

Confirm all expected files exist:
```
rules/batch-orchestration.md        ✓
.claude/commands/run-batch.md       ✓
.claude/settings.json               ✓
CLAUDE.md (updated)                 ✓
```

- [ ] **Step 2: Verify rules are loadable**

Read CLAUDE.md and confirm `@rules/batch-orchestration.md` resolves correctly
(the file exists at the referenced path).

- [ ] **Step 3: Verify command is invocable**

Confirm `.claude/commands/run-batch.md` exists in the commands directory
alongside the existing commands (session-start, session-end, decision, etc.).

- [ ] **Step 4: Read through the complete command file end-to-end**

Read `run-batch.md` as if you were Claude encountering it for the first time.
Check for:
- Is the flow unambiguous? Can every step be followed without guessing?
- Are there references to files or concepts that aren't explained?
- Is the subagent prompt template complete?
- Are all checkpoint modes handled?

- [ ] **Step 5: Trace through an example scenario**

Mentally trace through this scenario:
- Phase 1 Discovery is active
- task.md has Wave 1 (1 task), Wave 2 (1 task), Wave 3 (3 parallel tasks)
- User says: `/project:run-batch items:all checkpoint:after-each`

Verify the command file produces this behavior:
1. Reads task.md, finds 5 tasks in 3 groups
2. Checks permissions
3. Shows task list, asks for confirmation
4. Dispatches Wave 1 subagent → checkpoint → user says "weiter"
5. Dispatches Wave 2 subagent → checkpoint → user says "weiter"
6. Dispatches 3 Wave 3 subagents in parallel → checkpoint
7. All tasks done → phase checkpoint → hard stop
8. Consolidation → commit proposal

- [ ] **Step 6: Final commit (if any fixes were needed)**

```bash
git add -A
git commit -m "fix: adjustments from dry-run verification"
```