Build Pipeline Skill

Your build orchestration workflow: parse → spawn research workers + Builder in parallel → wait for research → feed research to Builder → wait for result → report.

Pipeline Overview

1. 1. Create Build — Initialize build record (shared/builds/{build-id}/build.yaml)
2. Parse — Extract domain, classify complexity, apply smart defaults, write parse-report.yaml
3. Parallel Spawn — Spawn all research workers AND Builder simultaneously
4. Wait for Research — Poll until all expected research partials exist in INLINECODE1
5. Feed Research to Builder — Send Builder phase 2 task with research findings via INLINECODE2
6. Wait for Builder — Poll for INLINECODE3
7. Report — Read builder-result.yaml and report success or failure to the user

User-Facing Progress Contract (Required)

You must communicate pipeline progress with structured stepper events, not technical narration.

Event rules

1. 1. At start: emit status.changed = running.
2. For each pipeline step, emit progress.step.started.
3. When moving to the next step, emit progress.step.completed for the previous step first.
4. Then emit progress.step.started for the next step.
5. Do not emit phase.changed for new builds.
6. Do not send repetitive assistant text on each transition; rely on stepper events.

Step IDs + friendly copy

Prohibited user-facing language

Do not output internal-engineering narration such as:

• - "Now I'll spawn all research workers."
• "Spawning the Builder agent now."
• "Waiting for Builder to complete."

Always translate internal work into friendly progress copy from the table above.

Spawning Rules

1. 1. Research workers MUST read their SKILL.md — Don't summarize instructions in the task. Tell them to read the file.
2. Research workers use agentId: null — they have no workspace, just task prompts.
3. Builder uses agentId: "builder" — it has a workspace at workspace_builder/.
4. Never pass streamTo="parent" for any subagent.
5. Parallel spawn: Research workers and Builder are spawned in the same function call block; do not wait between spawns.
6. Use stronger models for complex workers — gpt-4o for api-scout, tools-catalog, skills-finder. Haiku for domain-researcher.
7. Add readable labels — Format: {worker-type}-{build-id} (e.g., api-scout-8bc5666a).

Critical Sub-Agent Pattern

Sub-agents must:

1. 1. Read their SKILL.md file first
2. Follow ALL instructions in the file
3. Write output to YAML file (not chat back)
4. Exit silently after writing

If a sub-agent reports findings in chat instead of writing the file, it failed.

Task Prompt Template

CODEBLOCK0

Step 1: Create Build Record

Write to: INLINECODE31

Set status: "initiated".

Build Record Schema

CODEBLOCK1

Step 2: Parse

Analyze user prompt. Write parse report to: INLINECODE33

If confidence < 0.20, ask user for clarity. Do not proceed. Confidence >= 0.7 to proceed normally.

Channel Connection Policy (v1)

• - Default all builds to channel_type: local.
• Do not ask users which channel to connect during parse.
• Only capture channel intent if the prompt explicitly requests it (e.g. Telegram/WhatsApp/Discord).

Parse Report Schema

CODEBLOCK2

Step 3: Parallel Spawn (Research Workers + Builder)

After successful parse, spawn all research workers and Builder simultaneously in a single spawn block.

3a. Create Research Partials Directory

CODEBLOCK3

3b. Spawn All Research Workers + Builder

Use a single sessions_spawn block with multiple calls. Do not wait between spawns.

Research Worker Registry (Updated):

Note: Use gpt-4o (not mini) for complex evaluation tasks (api-scout, tools-catalog, skills-finder).

Spawn pattern — tell workers to read their SKILL.md:

CODEBLOCK4

Spawn Builder in the same block:

CODEBLOCK5

Rules:

• - All research workers spawn simultaneously
• Builder spawns in the same block as workers
• Do not wait for workers or Builder init to complete before proceeding to Step 4
• Store Builder's sessionKey for later use in Step 5

Step 4: Wait for Research Workers to Complete

Poll the research-partials/ directory until all expected partial files exist.

Expected files:

• - domain_model.yaml ✓
• INLINECODE59 ✓
• INLINECODE60 ✓
• INLINECODE61 (if spawned) ✓
• INLINECODE62 (if spawned) ✓

Poll behavior:

• - Check every 5 seconds
• Timeout per worker: 300 seconds
• If a worker times out: continue with partial research; Builder will design with what exists
• User message if timeout: "I'll proceed with the research we have so far."

Step 5: Feed Research to Builder (Phase 2 Task)

Once all expected research partials exist, send Phase 2 task to Builder via sessions_send:

CODEBLOCK6

Step 6: Wait for Builder Result

Poll for: INLINECODE64

Poll behavior:

• - Check every 10 seconds
• Timeout: 700 seconds
• If file appears: read it and proceed to Step 7
• If timeout: report failure to user with last known status from INLINECODE65

Step 7: Report

Read builder-result.yaml.

Success Path

Failure Path

The build encountered an issue:

Error: {builder_result.error.message}
Phase: {builder_result.error.phase}

Would you like to:
1. Retry the build
2. Start fresh with a new idea
3. Adjust the scope and try again

Multiple Builds

Each build gets its own {build-id} directory with independent research and builder outputs.

If a build is in progress: "You have a build in progress ([domain]). Start a new one, or finish that first?"

Error Handling

Research worker timeout (>300s):

• - Continue with partial research found so far
• User message: "I'll proceed with the research we have so far."

Builder timeout (>700s):

• - User message: "The build is taking longer than expected. Let me check what happened."
• Read build.yaml for last known status
• Report to user with context
• Offer retry or fresh start

Builder reports failure:

• - Read builder_result.error field
• Translate to user-friendly message
• Offer to retry or start fresh

Retry Strategy

1. 1. First failure → Tell user. Retry automatically (resend phase 2 task).
2. Second failure → Tell user exactly what happened. Offer options.
3. Third attempt → Give up. Report to user. No more retries.

Builder Result Schema (builder-result.yaml)

CODEBLOCK9