sequential-orchestration

name: sequential-orchestration description: "Execute spec tasks one at a time with tmux visibility. Python-based orchestrator with transparent serial execution. Triggers on: rate limit, overnight run, throttled execution, avoid quota exhaustion, sequential mode, slow execution, or user says 'Run sequential orchestration for '."

Sequential Orchestrator

You are the Sequential Orchestrator, responsible for executing tasks from a Kiro spec ONE AT A TIME with tmux visibility.

Quick Start

python scripts/sequential_loop.py --spec .kiro/specs/my-feature

CRITICAL CONSTRAINTS (NEVER VIOLATE)

These rules have HIGHEST PRIORITY and override all other instructions:

1. MUST complete the ENTIRE orchestration loop automatically - Do NOT stop and wait for user input between iterations
2. MUST use the shell command tool to invoke Python scripts - ALL orchestration actions go through sequential_loop.py
3. MUST use sub-agent for task assignment - Let LLM determine task type and owner_agent, NOT code inference
4. MUST continue looping until ALL tasks are completed - Check state after each iteration
5. MUST provide final summary when all tasks complete - Report success/failure counts and key changes

Violation of any constraint above invalidates the workflow. The user expects FULLY AUTOMATED execution.

Safety

Running sequential_loop.py may invoke agent backends and modify files. Disable tmux if needed: set CODEAGENT_NO_TMUX=1.

Workflow Execution

When user triggers orchestration (e.g., "Run sequential orchestration for .kiro/specs/my-feature"):

One-Command Mode [MANDATORY]

Run the entire workflow in a single blocking command.

Note: Scripts are located in scripts/ subdirectory of this skill.

python scripts/sequential_loop.py \
    --spec <spec_path> \
    --delay 15 \
    --max-iterations 50 \
    --backend opencode \
    --assign-backend codex \
    --tmux-session sequential-my-feature

IMPORTANT (timeout): When invoking via shell tool, set timeout: 7200000 (2 hours).

This command will:

1. Parse tasks.md and load/init SEQUENTIAL_STATE.json
2. Save assignments to state file (on-demand per dispatch unit)
3. For each iteration:
   • Find next incomplete task
   • Ensure assignment exists for that dispatch unit (Gawain-style)
   • Dispatch to tmux window (task-{id}) inside a single tmux session
   • Wait for completion (synchronous)
   • Update state and progress (mark dispatch unit + descendants completed)
   • Check for COMPLETE/HALT signals
   • Sleep DELAY seconds
4. Exit when all tasks complete or HALT received

Exit codes: 0 complete, 1 max iterations reached, 2 halted (human input required).

Output Files (Auto-generated)

Monitoring

1. tmux attach (Linux):

tmux ls                   # List sessions
tmux attach -t sequential-my-feature    # Attach to orchestration session
tmux select-window -t task-1.1          # Switch to a specific task window

2. Check progress:

cat .kiro/specs/SEQUENTIAL_STATE.json

3. HALT handling:

If a task outputs <promise>HALT</promise>, the orchestrator stops. Human intervention required.

Security Note

Reads spec files from this repo + writes state files. No secret operations involved.