16 KiB

Raw Permalink Blame History

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

# 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

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:

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

## 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

## 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

## 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

### 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

## 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

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

{
  "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

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

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:

Reads task.md, finds 5 tasks in 3 groups
Checks permissions
Shows task list, asks for confirmation
Dispatches Wave 1 subagent → checkpoint → user says "weiter"
Dispatches Wave 2 subagent → checkpoint → user says "weiter"
Dispatches 3 Wave 3 subagents in parallel → checkpoint
All tasks done → phase checkpoint → hard stop
Consolidation → commit proposal

Step 6: Final commit (if any fixes were needed)

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

16 KiB Raw Permalink Blame History

Batch Orchestrator Implementation Plan

File Structure

Task 1: Create rules/batch-orchestration.md

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

Task 3: Create .claude/settings.json

Task 4: Update CLAUDE.md

Task 5: Verification Dry-Run

16 KiB

Raw Permalink Blame History

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

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

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