---
name: build-orchestrator
description: Orchestrates build/redesign tasks by creating comprehensive, self-contained build plans. MANDATORY before spawning any landing page or app UI build. Ensures subagents have ALL context embedded — no file references, no shortcuts.
---

# Build Orchestrator

**Purpose:** Create comprehensive build context and spawn tasks for landing pages and app UI builds.

## Architecture: Hybrid Approach (v2)

The build orchestrator uses a **hybrid approach** (introduced 2026-02-18):

| Component | Location | Size | Purpose |
|-----------|----------|------|---------|
| **BUILD-CONTEXT.md** | Repo (e.g., `/home/aria/projects/dinq-landing/`) | ~40KB | Static context — design system, skills, guidelines |
| **Spawn task** | `/tmp/build-task-<slug>.md` | ~2KB | Dynamic instructions — what to build, overrides |

### Why Hybrid?

1. **Static context rarely changes** — Design system, skills, quality standards are stable
2. **Dynamic instructions vary** — Each request is different (from scratch, color change, etc.)
3. **Version-controlled** — BUILD-CONTEXT.md is committed to the repo
4. **Smaller spawn tasks** — 60 lines vs 1300 lines
5. **Subagent reads the file** — Tested and proven to work reliably

## What BUILD-CONTEXT.md Contains

The orchestrator pulls from ALL relevant sources:

### Product-Specific
- `product.yaml` — Product metadata
- `design/design-system-prompt.md` — Colors, fonts, components
- `discovery/brief.md` — Product description

### Skills (Full Content)
- **frontend-design** (superdesign) — Theme patterns, animations, implementation
- **taste-protocol** — Design philosophy, specific rules, evaluation checklist, UX laws, Nielsen's heuristics
- **frontend-design-excellence** — Quality gate checklist, Senior Test, anti-patterns
- **landing-page-builder** — Section blueprints, page structure (for landing builds)
- **web-app-builder** — App-specific guidelines (for app builds)

### Standard Sections
- Technical requirements (stack, build commands)
- Verification checklist

**Total:** ~1300 lines, ~40KB of comprehensive context

## Usage

### Step 0: Generate CLAUDE.md (MANDATORY for new products)

Before any build on a new product, generate `CLAUDE.md` in the product root. This ensures all current and future subagents have full context without hand-holding.

**Check if it exists first:**
```bash
ls /home/aria/products/<slug>/CLAUDE.md
```

**If missing — generate it before spawning anything:**
```bash
bash ~/.openclaw/workspace/skills/build-orchestrator/scripts/generate-claude-md.sh "<slug>"
```

- Template: `skills/build-orchestrator/templates/CLAUDE.md.template`
- Script reads: `product.yaml`, `design/brand-guidelines.md`, `design/design-system-prompt.md`, `discovery/brief.md`
- Output: `/home/aria/products/<slug>/CLAUDE.md`

**Rules:**
- Generate ONCE when first spawning any subagent for a new product
- Regenerate after major design system changes (review diff before committing)
- The `Gotchas & Past Mistakes` section is manually maintained — never auto-overwrite it

### Step 0b: Audit CLAUDE.md Quality (MANDATORY after generation)

After generating CLAUDE.md, immediately run the `claude-md-improver` audit via Claude Code to score it against Anthropic's standard and fill any gaps.

**Quality rubric (100pts):**
- Commands/Workflows (20pts) — build, dev, lint, start commands
- Architecture Clarity (20pts) — code map, entry points, module relationships
- Non-Obvious Patterns (15pts) — gotchas, quirks, workarounds
- Conciseness (15pts) — dense content, no filler
- Currency (15pts) — reflects actual codebase
- Actionability (15pts) — copy-paste ready commands

**Run the audit:**
```bash
# Spawn Claude Code to audit + improve
claude --dangerously-skip-permissions -p "$(cat << 'EOF'
Use the claude-md-improver skill to audit /home/aria/products/<slug>/CLAUDE.md.
Score it against the rubric. Show diffs for improvements. Apply after scoring.
App is at /home/aria/projects/<slug>-landing/ (or /home/aria/products/<slug>/apps/main/)
When done: openclaw system event --text "CLAUDE.md audit complete for <slug>" --mode now
EOF
)"
```

**Target grade:** B (70+) minimum before spawning any build subagent.

**Grading:**
- A (90-100): Ship it
- B (70-89): Good, minor gaps acceptable
- C (50-69): Fix before building — subagents will drift without good context
- D/F (<50): Regenerate and re-audit

---

### Step 1: Generate Build Context + Spawn Task

```bash
bash ~/.openclaw/workspace/skills/build-orchestrator/scripts/prepare-build.sh \
  "<product_slug>" \
  "<build_type>" \
  "<user_request>"
```

**Parameters:**
- `product_slug` — Product folder name (e.g., "dinq", "clocklane")
- `build_type` — Either "landing" or "app"
- `user_request` — What to build/change

**Outputs:**
- `<repo>/BUILD-CONTEXT.md` — Comprehensive static context (saved to repo)
- `/tmp/build-task-<slug>.md` — Small spawn task

### Step 2: Add Overrides If Needed

For special instructions (color changes, from-scratch builds), prepend to the spawn task:

```bash
# Read generated task
TASK=$(cat /tmp/build-task-<slug>.md)

# Add overrides
FINAL_TASK="## CRITICAL OVERRIDES

### 1. BUILD FROM SCRATCH
\`\`\`bash
rm /path/to/page.tsx
\`\`\`

### 2. COLOR OVERRIDE — SKY BLUE
Use #0ea5e9 instead of green (#d4ff00)

---

$TASK"

# Spawn
sessions_spawn({ task: "$FINAL_TASK", label: "build-<slug>" })
```

### Step 3: Spawn

```bash
TASK=$(cat /tmp/build-task-<slug>.md)
sessions_spawn({
  task: "$TASK",
  label: "build-<slug>"
})
```

## For App UI Work (with worktree)

```bash
# Step 1: Create worktree for git isolation
WORKTREE_CTX=$(bash ~/.openclaw/workspace/skills/worktree-manager/scripts/spawn-code-task.sh \
  "<slug>" "<requester>" "<id>" "<desc>")
WORK_DIR=$(echo "$WORKTREE_CTX" | jq -r '.workDir')

# Step 2: Generate build context
bash ~/.openclaw/workspace/skills/build-orchestrator/scripts/prepare-build.sh \
  "<slug>" "app" "<request>"

# Step 3: Spawn with work directory override
TASK=$(cat /tmp/build-task-<slug>.md)
sessions_spawn({
  task: "## WORK DIRECTORY\n$WORK_DIR\n\n$TASK",
  label: "build-<slug>"
})
```

## How It Works

1. **Main session** runs `prepare-build.sh`
2. Script pulls product context + ALL skill content
3. Writes comprehensive `BUILD-CONTEXT.md` to repo
4. Generates small spawn task pointing to BUILD-CONTEXT.md
5. **Subagent** reads BUILD-CONTEXT.md first (via `cat` command)
6. Subagent follows the comprehensive guidelines
7. Subagent builds, deploys, triggers post-deploy hook

## File Structure

```
skills/build-orchestrator/
├── SKILL.md                    # This file
└── scripts/
    ├── prepare-build.sh        # Main script (hybrid approach)
    └── prepare-build-legacy.sh # Old approach (full embed)
```

## When to Use

| Task | Use build-orchestrator? |
|------|------------------------|
| Landing page build/redesign | ✅ YES |
| App UI redesign | ✅ YES |
| New app from scratch | ✅ YES |
| Bug fix (non-UI) | ❌ No |
| Backend-only changes | ❌ No |

## Policy

This skill is **MANDATORY** for all landing page and app UI builds.

**Main session responsibilities:**
1. Always run `prepare-build.sh` before spawning
2. Add overrides for special instructions (colors, from-scratch)
3. Never tell subagent to "read multiple files" — BUILD-CONTEXT.md has everything

**Policy set by Ed (Design) — 2026-02-18**

---

## Legacy Mode

If hybrid approach has issues, use the legacy script:

```bash
bash ~/.openclaw/workspace/skills/build-orchestrator/scripts/prepare-build-legacy.sh \
  "<slug>" "<build_type>" "<request>"
```

This embeds everything directly in the spawn task (~15KB) instead of saving to repo.
