Synthesis Orchestrator

Drives the full synthesis flow: create_strategy -> run_slice (per slice) -> validate. Uses abd-story-synthesizer for instructions and validation. Supports checkpointing and stop-on-repeated-errors.

When to Apply

• User asks to run the synthesis orchestrator
• User wants to orchestrate story synthesis from source material
• User mentions "run orchestrator", "synthesis workflow", or "synthesis orchestrator"

CRITICAL: Orchestrator as Single Entry Point

When the orchestrator is active, all instructions for the synthesizer MUST go through the orchestrator to the agent.

• Do NOT create strategy.md, interaction-tree.md, or state-model.md yourself.
• Do NOT run build.py get_instructions directly and hand output to the agent.
• The orchestrator generates instructions and saves them to runs/slice-N-run-M-instructions.md (or create_strategy instructions). The agent receives those instructions from the orchestrator's output.
• Flow: Orchestrator → instructions file → Agent. Never bypass the orchestrator.

Prerequisites

• Synthesizer skill (abd-story-synthesizer) installed

• Skill space folder set to a folder that exists

  Run with --skill-space <path>: python scripts/run_orchestrator.py --skill-space C:/dev/agile_bots_demo/mm3e

Config Location (IMPORTANT)

abd-config.json MUST live in the synthesizer skill, NOT in the skill space.

Location	Contains	Config?
abd-story-synthesizer/conf/abd-config.json	Engine config (skills, context_paths, skill_space_path)	YES — config goes here
Skill space (e.g. mm3e/)	Content to synthesize (goal.md, context/, docs/)	NO — never put abd-config in the skill space

The skill space is the workspace/content root. The engine reads config from the synthesizer skill and uses skill_space_path in that config to find the workspace.

Run the Orchestrator

From abd-synthesis-orchestrator:

cd .../agilebydesign-skills/skills/abd-synthesis-orchestrator
python scripts/run_orchestrator.py --skill-space <path-to-skill-space>

Options

Option	Default	Description
--skill-space	required	Path to skill space folder; orchestrator passes to synthesizer (orchestrator does not set it)
--slice N	all	Run only slice N (1-based)
--checkpoint	stage	When to pause: never, stage, slice, run
--max-consecutive-failures	3	Stop after N consecutive validation failures
--max-inner-iterations	5	Max validate->correct->re-run iterations per slice
--stop-on-correction	off	Exit immediately on first validation failure; fix and re-run
--strategy-only	off	Stop after strategy creation (test run); skip slice runs
--test-mode	off	Stop at every step; prompt accepts N to do N runs then exit; state persisted for resume
--max-runs N	-	(test-mode) Max runs this session; then exit and save state for resume
--correct-level	run	Correction depth on failure: none, run, session, skill, all
--archive-dir	C:\dev\synchronizer_runs	Directory to archive session output at end
--no-archive	off	Skip session archival at end
--branch NAME	-	Git branch for skill version control; commits on pass, rolls back on regression
--no-rollback	off	Disable automatic rollback of skill changes when output degrades

Typical Workflow

1. Run with default checkpoint (stage): orchestrator pauses after each slice for human verification
2. At checkpoint: run agent with saved instructions in skill-space/story-synthesizer/runs/slice-N-run-M-instructions.md
3. Press Enter to continue after agent produces output
4. Use --checkpoint never for fully automated runs (e.g. CI)

Test Mode (sync run with agent tracking)

1. Run --test-mode: stops at every step (create_strategy, each run_slice, each validate)
2. At each checkpoint: run agent, then press Enter to continue 1 run, or type a number (e.g. 5) to do N runs then exit
3. State is saved to skill-space/story-synthesizer/runs/orchestrator-state.json when you exit
4. Re-run with --test-mode to resume from where you left off
5. Use --max-runs N to do N runs then exit (e.g. agent says "proceed with 3 runs" → --max-runs 3)

Self-Correction Pipeline

The orchestrator integrates with the synthesizer's three-layer correction system. Use --correct-level to control depth:

Level	What happens on validation failure
none	No correction — just log and re-run
run (default)	correct_run: capture DO/DO NOT in run log with wrong/correct examples
session	run + correct_session: fold corrections into session strategy for future runs
skill	run + session + correct_skill: promote corrections to skill rules (cross-project)
all	All three layers in one shot

Correction instructions are saved to runs/slice-N-run-M-corrections.md alongside the run instructions.

Session Archival

At the end of every session, the orchestrator copies the story-synthesizer/ output to an archive directory for history. Default: C:\dev\synchronizer_runs\<skill-space-name>\<timestamp>\.

• Use --archive-dir <path> to change the archive location
• Use --no-archive to skip archival

Skill Version Control

Use --branch <name> to enable git-based version control for the synthesizer skill:

1. On validation pass with --correct-level skill or all: skill changes are committed to the branch
2. On validation fail with --rollback-on-regression: skill changes are rolled back to the pre-correction state
3. Use --no-rollback to keep skill changes even when output degrades (for manual review)

Typical usage:

python scripts/run_orchestrator.py --skill-space C:/dev/mm3e --correct-level all --branch orchestrator

This creates a traceable history of skill evolution driven by session corrections.

Workflow (Essential Instructions)

Lifecycle stages: shaping → discovery → exploration → specification. Each slice goes through all four stages in order.

Strategy validation: (1) Does the strategy make sense from an identification perspective? (2) Does it slice to cover the full domain model? Slices must validate the entire domain (concepts, effects, attributes; commonality or diversity).

Validation flow: Run validate from the synthesizer skill (includes scanners). On failure, the correction pipeline runs automatically at the configured level (--correct-level). Correction instructions are saved for the agent.

Re-runs: When re-running the same stage, use corrections from the previous run as input.

Output storage: Per-run files in runs/; consolidated output in interaction-tree.md and state-model.md. Strategy and output are workspace-specific (skill-space); the synthesizer reads from and writes to the workspace.

Output

All output is in the skill space folder:

• Instructions: skill-space/story-synthesizer/runs/slice-N-run-M-instructions.md
• Run logs: skill-space/story-synthesizer/runs/run-N.md
• Artifacts: skill-space/story-synthesizer/interaction-tree.md, state-model.md