hermes-skills/build-pipeline-coordination/SKILL.md

---
name: build-pipeline-coordination
description: Orchestrate multi-piece builds with peer agents — dispatch builder, validate, research issues, fix, repeat until clean. Coordinates kimi-c (builder), ask-dev (validator), deep-research/better-search (issue research), and ask-claude (final review).
version: 1.0.0
author: Hermes Agent
metadata:
  hermes:
    tags: [build, pipeline, coordination, orchestration, peer-agents, validation]
    related_skills: [ask-kimi-c, ask-dev, ask-claude, deep-research, better-search]
---

# build-pipeline-coordination — Multi-Piece Build Orchestration

## Overview

Coordinates multi-piece builds where a primary build agent (kimi-c) executes pieces on a remote target, a validator (ask-dev) reviews each piece, and the coordinator drives the fix loop until clean. Designed for infrastructure builds (ComfyUI pipelines, service deployments, model installations) where each piece builds on the last.

## Roles

| Role | Agent | Responsibility |
|------|-------|---------------|
| Builder | kimi-c | Executes build tasks on target via SSH |
| Validator | ask-dev | Reviews build output, finds issues |
| Researcher | deep-research / better-search | Investigates issues thoroughly before fixing |
| Final Review | ask-claude | Adversarial review before proceeding to next piece |
| Coordinator | You | Orchestrates the loop, reviews findings, dispatches |

## Validation Loop (per piece)

```
1. Write build task file (e.g., /tmp/kimi-build-N.txt)
2. If task file contains tool-specific API details (node names, parameter values, scheduler names, step configs): dispatch better-search to validate them BEFORE sending kimi-c
3. Patch task file with any corrections from research
4. PRE-STEP VALIDATION GATE: Dispatch kimi-c to review the step before executing. Check for correctness, model paths, node compatibility, VRAM estimates, parameter values. Apply corrections. Only then execute.
5. Dispatch kimi-c to execute the piece
6. ask-dev validates the build
7. Coordinator reviews findings — only apply accurate fixes, push back on wrong ones
8. If issues found: better-search/deep-research to investigate → patch task file → kimi-c applies fixes → re-validate
9. Repeat until ask-dev says CLEAN
10. ask-claude for final adversarial review
11. USER REVIEW GATE: Present the output path. Let the user review before proceeding to next piece. Do NOT re-render or continue until the user confirms.
12. Proceed to next piece
```

## Issue Resolution: Deep Research First (MANDATORY)

**When issues arise during validation — ask-dev finds problems, kimi-c hits errors, unexpected behavior occurs:**

- Dispatch `deep-research` (or `better-search` for medium-depth) to investigate thoroughly BEFORE applying fixes
- Do NOT just do a quick `mcp_searxng_searxng_web_search` — the operator wants trail-following, exhaustive research
- The research result file becomes the authoritative reference for the fix
- **After research returns: patch the build task file with corrections, THEN re-dispatch kimi-c.** The fix must be in the task file so kimi-c has the corrected instructions. Do NOT tell kimi-c to "apply the fix" from memory — it has no context of the research findings.
- Only after the task file is patched should kimi-c be re-dispatched

**Rationale:** Quick web searches produce shallow fixes that often need re-fixing. Deep research finds root causes and correct solutions the first time. The operator's standing directive: "if issues do deep search to resolve."

**Routing:**

| Issue depth | Tool |
|---|---|
| Single factual lookup (version, config key) | `searxng-smart-search` (inline MCP) |
| "Look into why X is failing" | `better-search` |
| Complex multi-source investigation, root cause analysis | `deep-research` |

### Pre-Dispatch Task File Validation

**Before dispatching kimi-c with a build task file, validate tool-specific API details against research.** Task files written from memory or prior sessions can contain bugs in:

- Tool-specific parameter names and values (e.g., `start_step`/`end_step` semantics, scheduler names)
- Node chains and their required connections
- Version-specific API changes (custom node updates, model loader behavior)

If the task file contains tool-specific API details you're not 100% certain about, dispatch `better-search` to verify them before sending kimi-c. A 3-loop better-search costs ~2 minutes and prevents a failed render that wastes 10+ minutes. Real example: the Lightning LoRA task file had `start_step: 0, end_step: 1` (only 1 step) when it should have been `start_step: 0, end_step: 2` (2 steps, end_step is exclusive). It also had `scheduler: dpm++_sde` which the community reports as "mid/fail" for Lightning LoRA — the correct value is `euler`.

## Continue Until Done (NON-NEGOTIABLE)

**When the operator says "continue until done," "don't stop," "go until complete," or "I am not going to be at the PC" — you do NOT stop between pieces.** Chain them: dispatch piece N, wait for completion, immediately dispatch piece N+1. Do not pause for user confirmation. Do not report "ready for next direction." Do not kill a running process and wait for the next instruction. The operator is not at the PC and wants the pipeline built end-to-end without intervention.

- Do not stop after one fix attempt if validation still shows issues
- Loop: build → validate → research → fix → validate → ... until CLEAN
- Only move to the next piece when the current piece passes validation
- If you kill a process (user says "stop"), immediately re-dispatch — do not wait for the next instruction
- **If the operator previously said "don't stop" and you stopped anyway, that's a failure. Re-dispatch immediately.**
- The operator's directive: "Continue until done and working."

## Build Task File Format

Each piece gets a self-contained build task file at `/tmp/kimi-build-N.txt`:

```
BUILD TASK — Piece N: <title>
TARGET: <IP/hostname> (SSH user@host, credentials)
PURPOSE: <what this piece achieves>
CRITICAL CONTEXT: <pitfalls, required config, known issues from prior pieces>
MODELS/PATHS: <exact paths on target>
STEPS: <numbered, exact commands>
EXPECTED OUTPUT: <what success looks like>
```

## Pre-Step Validation Gate (MANDATORY)

**Before executing any build step, ask kimi-c to validate it.** The user's directive: "ask kimi c to validate each step before you perform it." This means:

1. Write the step (script, workflow, config change)
2. Dispatch kimi-c to review it: check for correctness, model paths, node compatibility, VRAM estimates, parameter values
3. Apply kimi-c's corrections
4. Only then execute

This prevents: wrong model paths, incompatible node types, OOM renders, and parameter errors that waste 10+ minutes of GPU time.

## Crash Recovery Documentation (MANDATORY)

**Keep the plan updated as you go with a checklist.** The user's directive: "first update the plan as you go. Build a checklist. KEEP EVERYTHING documented. In case we crash again."

- Update the plan file after every completed step — don't batch updates
- Use `[x]` checkboxes for completed items, `[ ]` for pending
- Mirror all scripts/workflows to local workspace (not just /tmp on remote)
- The plan file is the crash-recovery artifact — a new session should be able to resume from it

## Pitfalls

1. **Don't fix before researching.** When ask-dev flags an issue, the impulse is to apply the obvious fix immediately. Resist. Dispatch deep-research first. The obvious fix is often wrong.
2. **Don't accept all validator findings blindly.** ask-dev can flag things as BROKEN that are actually correct. Review each finding yourself before dispatching fixes.
3. **Don't skip the adversarial review.** ask-claude catches things both the builder and validator miss. Always run it before moving to the next piece.
4. **One piece at a time.** Don't dispatch the next piece while the current one is still in the fix loop. Each piece builds on the last — a broken foundation breaks everything above it.
5. **Build task files must be self-contained.** kimi-c has no memory of prior pieces. Include all critical context, paths, and pitfalls in the task file.
6. **Task files can contain bugs in tool-specific API details.** Parameter names, enum values, step semantics, and scheduler names written from memory are often wrong. If the task file contains tool-specific API details you're not 100% certain about, validate them with better-search before dispatching. A 3-loop better-search costs ~2 minutes and prevents a failed render that wastes 10+ minutes. Real example: `start_step: 0, end_step: 1` should have been `start_step: 0, end_step: 2` (end_step is exclusive); `scheduler: dpm++_sde` should have been `euler` (dpm++_sde fails with Lightning LoRA).
7. **After research, patch the task file before re-dispatching.** kimi-c has no context of the research findings. The corrected instructions must be in the task file itself. Do NOT tell kimi-c to "apply the fix from the research" — it can't read the research result file unless you give it the path explicitly, and even then it may misinterpret the findings.
8. **Verify Claude's tool-specific API claims before applying.** Claude is thorough at finding gaps but can be wrong about tool-specific details (scheduler names, parameter semantics, node chains, version compatibility). After Claude's review, identify any claims about tool-specific APIs and dispatch `better-search` to verify against primary sources (official workflows, GitHub issues, community guides). Only apply Claude's API claims that research confirms. Real example (Piece 8c, July 2026): Claude recommended `flowmatch_distill` scheduler for Lightning LoRA. Better-search confirmed the official LightX2V I2V workflow uses `euler`, and `flowmatch_distill` has an open color-shift bug (GitHub Issue #782). Applying Claude's recommendation without verification would have introduced a known bug.

9. **When the peer hits the turn limit, the coordinator finishes mechanical steps directly.** If the peer reports "Reached maximum iterations" but the remaining work is mechanical (calculations, file concatenation, ffmpeg commands, scene plan generation), the coordinator should finish those steps directly rather than re-dispatching. Re-dispatching wastes turns re-establishing context and the peer may hit the limit again. Only re-dispatch when the remaining work requires reasoning or decision-making. Real examples (July 2026): Piece 10 (F5-TTS) — peer generated all 8 audio files but hit the 30-turn limit before calculating scene frame counts and concatenating audio. Coordinator finished both steps directly via SSH. Piece 8c fixes — peer installed SageAttention and submitted the render but hit the 30-turn limit before the render completed. Coordinator monitored the render directly.

10. **Service restarts after package installs in remote venvs.** When a package is installed in a running service's venv (e.g., `pip install sageattention` in ComfyUI's venv), the service must be restarted — not just the workflow re-submitted. Python imports are cached at process start. The peer may install the package and re-submit, see it fail, and not understand why. The coordinator should verify the service was restarted after the install. Real example (Piece 8c, July 2026): SageAttention installed successfully but ComfyUI was started before the install; the `attention.py` import check ran at startup and cached the failure. Restarting ComfyUI fixed it.

11. **VRAM limits on 24GB cards for LTX Director.** 60s at 512×512 with fp8 model OOMs (~20.5GB allocated, needs 2.1GB more). Solutions in order of preference: (a) split into 2×30s batches with ffmpeg concat, (b) use GGUF Q4 model (~17GB), (c) reduce resolution. The split+concat approach preserves quality and is reliable. Real example (July 2026): 60s Director render OOM'd twice (fp8 then GGUF Q4). Splitting into 2×30s batches worked — each batch used ~16GB, ffmpeg concat produced seamless 60s output.

12. **Spatial upscaler inflates output resolution.** The LTX Director example workflow includes a spatial upscaler (x2) that bumps 512×512 to 1536×1024. This is applied automatically and increases file size. If you want 512×512 output, remove the upscaler nodes from the workflow.

13. **LTX Director timeline_data segment format.** The Director node parses `timeline_data` JSON for image segments. Segments MUST have `"type": "image"` and `"imageFile"` (filename in ComfyUI's input directory) or `"imageB64"` (base64). The field `"image"` with an absolute path is IGNORED — the code only checks `seg.get("imageFile")` and `seg.get("imageB64")`. If no valid image segments are found, the Director falls back to the global_prompt for all scenes, producing identical output for every batch. See `references/ltx-director-timeline-format.md` for the exact JSON schema.

14. **Stop at the first error — ask the user.** When the agent hits an error, block, or unexpected result, it must STOP and ask the user for advice before trying workarounds or alternative approaches. Do not iterate through multiple fixes autonomously — pause at the first real obstacle and ask. The user's directive: "When you run into some errors. You stop and ask for my advice. Always."