# Build Execution Protocol

> Systematic protocol for working through a project build queue (NEXT_TASKS.md). Use when a project has an ordered task list and you need to pick up, execute, verify, and hand off work across sessions. Triggers automatically when NEXT_TASKS.md exists in a project directory and Ray says "work on [project]", "continue the build", or "keep going". Ensures consistent quality, verification, and session handoff regardless of which session picks up the work. Mirrors the heartbeat enforcement pattern.

- Skill: `lord1egypt/build-execution-protocol` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lord1egypt/build-execution-protocol`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lord1egypt/build-execution-protocol/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: Lord1Egypt (https://skillmd.com/u/lord1egypt)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/lord1egypt/build-execution-protocol

---


# Build Execution Protocol

Repeatable, enforced process for executing a build queue across sessions. Same discipline as the heartbeat — mandatory checklists, verification gates, no shortcuts.

## Auto-Trigger

If a project has `NEXT_TASKS.md`, follow this protocol automatically. Ray only needs to say "work on [project]" or "keep going."

---

## Phase 0: Session Setup (MANDATORY — COMPLETE IN ORDER, NO EXCEPTIONS)

□ **0. Context Check (HARD STOP)**
- Run `session_status` FIRST
- **If context > 70%:** Wrap up, update files, request fresh session. STOP.
- **If context > 85%:** CRITICAL. Save state immediately, do NOT start new work.
- Log context % for reference

□ **1. Read Project State (BEFORE model selection — you need to see the work first)**
- Read `NEXT_TASKS.md` — find the first unchecked `[ ]` item
- Read `STATUS.md` (if exists) — understand current build state
- Read today's + yesterday's `memory/YYYY-MM-DD.md` — know what happened recently
- Skim the last session's work log for any warnings or half-finished items

□ **2. Model Selection (NOW that you've seen the tasks)**
- Review the upcoming tasks and select model based on what they need:
  - **Haiku:** Simple doc updates, formatting, config changes, trivial fixes
  - **Sonnet:** Standard coding, implementation, routine bug fixes, test writing
  - **Opus:** Architecture decisions, complex algorithms, hard debugging, security-critical work
- **If the session has a mix:** Start with Sonnet, switch to Opus for complex tasks, back to Sonnet after
- Switch model now if needed: `session_status(model="...")`

□ **3. Verify Previous Session's Work (DO THIS BEFORE NEW WORK)**
- Look at what the last session claimed to complete (from memory files / NEXT_TASKS.md checked items)
- **Actually verify it:** Run the code, check the output, read the files
- If anything was marked done but doesn't work → uncheck it, fix it first
- **This exists because sessions lie to themselves.** Trust but verify.

□ **4. Baseline Test Run (NON-NEGOTIABLE)**
- Run the full fast test suite BEFORE touching any code:
  ```bash
  python3 -m pytest -x -q --ignore=tests/integration
  ```
- **Record the count:** `N passed, 0 failed`
- **If tests are already failing:** Fix them FIRST using `test-suite-repair` skill
- **You must end the session with ≥ this test count**

□ **5. Git Checkpoint**
- If the project uses git: `git add -A && git commit -m "checkpoint: session start — N tests passing"`
- If no git: copy critical files to a backup location
- **Why:** If task 3 breaks something silently, you can diff back to this known-good state
- Create a new checkpoint after each completed task

□ **6. Check Jinx Status**
- `ssh -i ~/.ssh/lucky_to_mac luckyai@100.90.7.148 "curl -s http://localhost:3001/status"`
- If Jinx has completed results → review and verify them first (apply same verification standard)
- If Jinx is idle → good, we'll queue tasks as we go

□ **7. Plan the Session**
- Look at remaining unchecked tasks in NEXT_TASKS.md
- Pick 2-4 tasks you can realistically complete this session
- **WIP limit:** 1 task active at a time. Finish or park before starting another.
- **Size check:** If a task will take >45 min of coding, consider:
  - Breaking it into subtasks
  - Spawning a coding agent via `coding-agent` skill for the implementation
  - Queuing parts to Jinx

---

## Phase 1: Task Execution Loop

For EACH task, follow this loop without skipping steps:

### Step 1: Understand (2-5 minutes)

□ **Read the task description** in NEXT_TASKS.md
□ **Read the relevant source files** (use the quick reference table at bottom of NEXT_TASKS.md)
□ **Read the spec section** — find the actual requirement in the spec and **quote it**:
  ```
  SPEC REQUIREMENT: "The Judge worker evaluates 5-10 variants and selects 
  the best with a decision trace including confidence score." 
  — master_spec_full.txt, Section 4.2
  ```
  **Why:** This is how we avoid building the wrong thing. If you can't find a spec reference, ask Ray before implementing.
□ **Define "done"** — one sentence: "This task is done when ___"
□ **Jinx check:** "Can Jinx do this?" If it doesn't need live coding/testing → queue for Jinx, skip to next task

### Step 2: Implement

□ **Jinx split check:** Before coding, break the task into parts. Can any part run on Jinx?
  - **Lucky does:** Live coding, file system changes, testing, anything needing imports/execution
  - **Jinx does:** Writing docs from existing code, analyzing patterns, generating test data, reviewing logic, drafting boilerplate
  - **Split pattern:** Lucky writes the core logic → queues Jinx to write tests/docs/edge-case analysis for it
  - **Queue Jinx parts NOW** so they run in parallel while you code your parts
□ Write the code
□ **Stay focused** — one task only. Don't drift into adjacent work.
□ If you discover something broken, **note it in NEXT_TASKS.md as a new item** but don't fix it now unless it blocks you
□ **Check skills** — if this task type matches a skill (judge-worker-pattern, pipeline-debugging, ui-truth-mapping, etc.), read and follow that skill first

### Step 3: Test (MANDATORY)

□ Write tests for the new code (if the task warrants tests)
□ Run the full fast test suite:
  ```bash
  python3 -m pytest -x -q --ignore=tests/integration
  ```
□ **Must pass with 0 failures before proceeding**
□ **Test count must be ≥ baseline** — you cannot lose tests

### Step 4: Verify (NOT THE SAME AS "TESTS PASS" — USE OPUS)

This is the step that gets skipped. **Don't skip it.**

□ **Switch to Opus model** for verification: `session_status(model="opus")`
  - Opus catches things Sonnet misses — logic gaps, spec mismatches, subtle bugs
  - This is the quality gate. Use the strongest model here.
□ **Read back the code you wrote** — does it do what the task asked? Not "does it compile" — does it actually implement the requirement?
□ **Check the output** — call the function/endpoint/CLI and look at what it returns. Print it. Read it.
  ```python
  # Actually run it and look at the output
  result = the_thing_you_built(test_input)
  print(json.dumps(result, indent=2))
  ```
□ **Compare to spec** — re-read the spec requirement you quoted in Step 1. Does the output match?
□ **Edge cases** — empty input, null, unexpected types, boundary values
□ **If UI copy:** Read the copy. Does it make sense to a human who isn't a developer?
□ **Switch back to Sonnet** after verification (don't burn Opus tokens on the next task's implementation)

**Verification failures:**
- If gaps found → fix them before marking done (stay on Opus for the fix if it's complex)
- If can't fix quickly → mark task `[partial]` with notes on what's missing, add fix as new task

### Step 5: Checkpoint + Mark Done (ENFORCEMENT GATE — CANNOT SKIP)

□ **Git checkpoint:** `git add -A && git commit -m "done: [task description] — N tests passing"`
□ **Queue Jinx follow-up BEFORE marking done:** After EVERY completed task, ask "What can Jinx do now?"
  - Tests? Docs? Code review? Edge case analysis? Performance audit?
  - **Jinx should NEVER be idle when follow-up work exists**
  - **Actually submit the Jinx task via curl NOW — not "later"**
□ **Update NEXT_TASKS.md:** Check the box `[ ]` → `[x]`, add notes if needed
□ **RUN THE ENFORCEMENT GATE (MANDATORY — NO EXCEPTIONS):**
  ```bash
  ~/.openclaw/workspace/scripts/enforce.sh "<project_dir>" "<task_name>" "<memory_file>"
  ```
  - **If it exits non-zero: you are NOT DONE. Fix every failure before proceeding.**
  - **Do NOT mark the task done, do NOT move to the next task, do NOT pass Go.**
  - **This gate checks:** memory log exists with spec quote + verification + Jinx follow-up, tests pass, git clean, NEXT_TASKS.md updated
  - If the task revealed new work → add it to the appropriate priority section

### Step 6: Log (Structured Format)

Update `memory/YYYY-MM-DD.md` using this format:
```markdown
### Task: [name from NEXT_TASKS.md]
- **Status:** ✅ Done / ⚠️ Partial / ❌ Blocked
- **What was built:** [1-2 sentences]
- **Files changed:** [list]
- **Tests:** [before] → [after] (added N)
- **Verified:** [how — what you checked beyond tests]
- **Spec match:** [yes/no — quote spec if relevant]
- **Jinx queued:** [what follow-up work]
- **Surprises:** [anything unexpected, lessons learned]
```

Update `STATUS.md` if this was a significant milestone.
Log to Mission Control if available.

### Step 7: Skill Extraction Check

□ **Did this task produce a reusable pattern?**
  - New algorithm that could apply to other projects?
  - Debugging technique worth capturing?
  - Architecture pattern worth documenting?
□ If yes → note it in the Learning Capture section of today's memory
□ If it's substantial → create a skill (check existing skills first to avoid duplicates)

### Step 8: Context Check + Continue

□ Run `session_status` — check context usage
□ **If context > 60%:** 1-2 more tasks max. Be selective.
□ **If context > 70%:** Finish current task, go to Phase 3 (wrap-up). STOP new work.
□ **If context OK:** Move to next unchecked task, repeat from Step 1.

---

## Phase 2: Blocker Handling

When you hit a blocker:

□ **Classify:**
  - **Needs Ray:** Decision, approval, info only Ray has
  - **Technical:** Bug, missing dependency, unclear spec
  - **Dependency:** Task X depends on unfinished Task Y

□ **Handle by type:**
  - **Needs Ray:** Mark `[blocked: waiting on Ray — reason]` in NEXT_TASKS.md, message Ray, skip to next task
  - **Technical:** Attempt to solve (switch to Opus if complex). If stuck >15 min, mark blocked, move on.
  - **Dependency:** Skip to the dependency task first, or skip both and note the chain

□ **Never let one blocker stop all progress.**

□ **If ALL tasks blocked:**
  - Log blockers clearly
  - Check for supporting work (tests, docs, refactoring, skills)
  - Message Ray with the full blocker list and what you did instead

---

## Phase 3: Session Wrap-Up (MANDATORY)

□ **NEXT_TASKS.md current:**
  - All completed items checked `[x]`
  - New discovered items added
  - Blockers noted with reasons
  - **"Next session starts here"** marker on the first unchecked task

□ **Final test run:**
  ```bash
  python3 -m pytest -x -q --ignore=tests/integration
  ```
  - 0 failures confirmed
  - Test count ≥ starting baseline

□ **Final git checkpoint:**
  ```bash
  git add -A && git commit -m "session end: [N] tasks done, [M] tests passing"
  ```

□ **Structured handoff note** in `memory/YYYY-MM-DD.md`:
  ```markdown
  ## Session Wrap-Up [time]
  - **Tasks completed:** N (list them)
  - **Tests:** start count → end count
  - **Next task:** [first unchecked item]
  - **Blockers:** [list or "none"]  
  - **Warnings for next session:** [anything tricky, gotchas, or "none"]
  - **Jinx tasks queued:** [list or "none"]
  - **Context at wrap:** X%
  ```

□ **Update STATUS.md** with current test count and completion %

□ **Queue Jinx overnight work** if applicable

□ **DO NOT leave work half-done.** Finish or revert.

---

## Progress Reporting to Ray

**When to message Ray:**
- **After completing 3+ tasks in a session** — batch summary, not per-task spam
- **When hitting a blocker that needs Ray** — immediately, with specific question
- **When a milestone completes** (e.g., entire Priority section done) — celebration-worthy
- **When something unexpected happens** — broken assumptions, spec contradictions, major discoveries
- **At session wrap if significant progress was made**

**Don't message Ray for:** routine task completion, passing tests, minor progress. Save it for batches.

---

## Quality Gates (ENFORCEMENT)

A task is NOT done unless ALL of these are true:
- [ ] Code written and saved
- [ ] Tests written (if applicable)
- [ ] Full fast suite passes with 0 failures
- [ ] Output verified with Opus model (not just "tests pass")
- [ ] Spec requirement quoted and matched
- [ ] Git checkpoint committed
- [ ] NEXT_TASKS.md checkbox marked
- [ ] Jinx follow-up queued (if applicable)
- [ ] No regressions (test count ≥ baseline)

**Red Lines (Never Cross):**
- Never mark a task done without verification
- Never decrease test count
- Never start a new task with failing tests
- Never continue past 70% context without wrapping up
- Never leave NEXT_TASKS.md out of date
- Never implement without reading the spec requirement first
- Never skip verifying the previous session's work

---

## Learning Capture

After completing any task, write one line:
- **What worked** — technique, pattern, or approach worth reusing
- **What didn't** — mistake, false start, or wasted time
- **Skill candidate?** — if this pattern is reusable, note it for potential skill extraction

If it's worth keeping long-term → update MEMORY.md at end of day.