---
name: alex-build-loops
description: "Alex's lean house playbook for Hermes/Codex coding and deployed-app work: completion contracts, ticket-to-PR, UI/UX scoring, production error sweeps, fresh-clone verification, promise-to-proof, and docs drift. Use for build-profile coding tasks, app QA, PM2/nginx/VPS fixes, repo maintenance, and evidence-based handoffs."
version: 1.3.2
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [alex, build, codex, coding, qa, deployment, loops]
    related_skills: [loop-library, coding-quality-workflow, systematic-debugging, github-pr-workflow, vps-app-deployment, dogfood]
---

# Alex Build Loops

This is the lean house playbook for Alex's build profile. Use these loops before searching the full Loop Library catalog. Keep Hermes lean: do not load 42 loop descriptions by default.

## Global build contract

For Alex's app/coding work, default to:

1. Start from current state; pull latest from GitHub when working in a repo unless explicitly told not to.
2. Identify root cause or exact gap before changing code.
3. Make the smallest safe change that satisfies the request.
4. Preserve unrelated user work and avoid broad data-hiding fixes.
5. Run relevant tests/build/type checks/lints when available.
6. For deployed VPS apps, restart/deploy only the affected PM2 service and smoke verify the public or local health route.
7. Final handoff includes evidence: files changed, checks run, deploy/restart status, smoke result, and any remaining risks.

Approval boundary: ask before destructive irreversible changes, deleting data, changing credentials/secrets, broad rewrites without rollback plan, or sending external messages.

## Direct execution with one continuity watchdog

When Alex asks development to keep moving unattended, do not manufacture a fleet of worker, dispatcher, reporter, research, and recorder loops. Prefer direct implementation through one durable plan/board and one mutable integration worktree. Add only **one conditional continuity watchdog cron** when durable recovery is actually needed.

The watchdog stays silent while a real worker is healthy, dispatches one ready task when idle, reclaims only corroborated stale/dead claims, verifies suspicious completion evidence, and triggers one bounded remediation when work is falsely or prematurely marked complete. It must leave deployment, migration, paid calls, publishing, spend, destructive cleanup, and other human/live-state gates blocked. Avoid periodic reporting unless Alex explicitly requests it; report at real completion, recovery, blocker, or approval transitions.

Kanban's generic `review-required` convention can itself become an unnecessary stall when the graph already contains a downstream independent review gate. In that topology, task briefs should authorize implementers to complete coherent green commits. If a worker still blocks, independently rerun the smallest relevant check, record verified commit/test evidence, complete the task, and continue—without bypassing any true human gate.

See `references/conditional-build-continuity-watchdog.md` for the deterministic state machine, silent-output contract, semantic fallback, and concurrency safeguards.

## Delivery cadence: outcome-sized by default

For Alex’s long platform/app programs, preserve hard safety boundaries without turning every helper, schema change, or test group into its own ceremony.

Use this fast-track cadence when Alex says the work is taking too long, the plan is too detailed, or asks to move faster:

1. **Finish the coherent slice already in progress.** Do not discard or restart useful work merely to re-plan.
2. **Compress the remaining roadmap into 2–4 outcome milestones.** Each milestone should produce working end-to-end behavior, not just another internal layer.
3. **Keep only hard gates.** Examples: no real infrastructure effects before fake recovery passes; no customer migration without explicit approval; no destructive action without verified rollback.
4. **Review once per outcome milestone.** Combine specification, security, and code-quality review after the end-to-end checkpoint works. Fix critical/important findings in one bounded repair loop.
5. **Avoid ceremony-only work.** Do not create a separate plan update, commit, independent review, or Viewer/checklist update for every helper, test count, or sub-step. Update status only at milestone start, genuine blocker, approval, or completion.
6. **Parallelize genuinely independent lanes.** Separate repos or non-conflicting artifacts may proceed concurrently; do not parallel-edit the same files/worktree.
7. **Match assurance to consequence.** Fake/internal foundations still need tests and invariants, but exhaustive crash-window review belongs at the integrated recovery gate and before real effects—not repeatedly at every precursor.
8. **Move immediately after a green gate.** Start the next outcome batch rather than pausing for another planning round unless a product decision is missing.
9. **Budget the execution window.** Reserve roughly the final third of a bounded turn for collecting delegated work, resolving interface drift, running the integrated gate, and leaving a green checkpoint. Once that reserve begins, stop opening new workstreams.
10. **Delegate fewer, larger lanes.** One or two disjoint outcome-sized workers are usually faster than filling every concurrency slot. Never code the controller against guessed exports from a worker-owned contract; define the interface first or integrate after the worker returns.
11. **Batch calls and evidence.** Group independent reads, related edits, and focused checks. Use one RED and one GREEN run per coherent behavior instead of a tool call and test rerun for every small statement.
12. **Ship the user-visible slice before expanding infrastructure scope.** If a requested integration exposes a missing runtime/provider prerequisite, finish and deploy the independent product slice first when safe, then state the prerequisite boundary. Do not turn a lean feature request into an improvised runtime-image/control-plane migration in the same pass unless that migration path already has a disposable upgrade canary and rollback. Never remove a live tenant runtime to discover reconcile semantics.
13. **Treat “do not stop until done” as a scope lock, not permission to chase adjacent defects.** Freeze the accepted completion contract. Fix a newly discovered adjacent issue only when it blocks the current slice or violates a hard safety invariant; otherwise record it for a later lane and keep integrating. A useful live-service improvement is still a distraction if it consumes the integration reserve while the requested product remains uncommitted.
14. **Harvest delegated lanes before opening anything new.** Give each worker a commit/checkpoint requirement and treat its worktree as a lease. At the halfway mark and again when the final-third reserve begins, establish liveness from the real process. If no worker is alive, immediately recover the files, run the lane’s smallest gate, and commit or reject them. Never carry dead-worker modifications under an “in progress” label across a context or tool ceiling.

See [`references/lean-bounded-session-development.md`](references/lean-bounded-session-development.md) for the tool-budget split, controller/delegation contract, worker-harvest checkpoints, lean verification ladder, and the false-fast pattern where many active lanes finish nothing.

Pitfall: a technically excellent plan can still be wrong if its granularity makes progress invisible or consumes more time in reviews/docs than in integrated delivery.

Pitfall: visible activity is not throughput. If parallel workers, granular patches, commentary, and optional environment reconnaissance consume the turn before integration, the correct response is to reduce lanes and reserve completion capacity—not to produce a longer partial-status report.

Communication rules:

- If Alex says **“just answer”**, give the direct assessment without tool calls, progress narration, or an action plan unless explicitly requested.
- If Alex asks for a **short summary** after a long build/migration report, compress to at most five bullets: active/stopped state, completed outcome, current live state, genuine blockers, and next required action. Do not repeat commit/test/evidence catalogs unless asked.
- If Alex asks for a **conversational back-and-forth**, answer the current question plainly and end with one meaningful decision/question at a time rather than another comprehensive plan dump.

## Default loop picker

Use the smallest matching loop:

- **Outcome-sized fast-track loop** — a long-running plan has become too granular, review-heavy, or slow.
- **Continuous Kanban development lane** — a large approved plan should keep advancing across fresh sessions with one writer, durable dependencies, independent boundary reviews, and explicit live-state gates.
- **Codex completion-contract loop** — long/ambiguous coding tasks where partial completion could be mistaken for done.
- **Ticket-to-PR-ready loop** — bug report, feature request, customer complaint, failing behavior.
- **UI/UX Score Loop** — browser-visible app polish, onboarding, flows, responsive/mobile checks.
- **Production error sweep** — logs/PM2/nginx/runtime errors on deployed apps.
- **Fresh-clone loop** — README/setup/onboarding from scratch, repo handoff quality.
- **Promise-to-proof loop** — docs/landing/demo/AI answer claims vs real product behavior.
- **Overnight docs sweep** — code/docs drift and recurring release/doc hygiene.
- **Recent-feedback sweep** — repeated user feedback or recent failures may imply a pattern.
- **Test stabilizer loop** — flaky tests and inconsistent CI/local results.
- **Housekeeper loop** — conservative cleanup only when there is no higher-priority functional task.

If none fit, load `loop-library` and search/adapt the full catalog.

## Continuous Kanban development lane

Use when: an approved multi-milestone implementation should keep advancing across fresh sessions, especially when the main checkout is dirty or live effects must remain gated.

Prefer a clean integration worktree, dedicated build/review profiles where useful, one dependency-gated Kanban graph, and **one conditional continuity watchdog only when unattended recovery is requested**. Do not automatically add separate dispatcher, reporter, research, or recorder crons. The watchdog should remain silent while a task has a live PID/heartbeat, dispatch one ready task when idle, recover corroborated stale claims, and verify ambiguous completion handoffs. Keep one active writer per mutable worktree and end the graph at an intentionally blocked human gate for merge/deploy/live migration or external effects.

See `references/continuous-kanban-development-lanes.md` for the broader board/worktree setup, and `references/conditional-build-continuity-watchdog.md` for the corrected minimal cron topology and recovery state machine.

## Codex completion-contract loop

Use when: a task has multiple requirements, Codex/subagents are involved, or the final answer might otherwise overclaim.

Prompt:
> Define the completion contract before coding: list each requirement, proof needed, affected files/systems, and stop/approval boundaries. Work from fresh repo state. After each change, record which contract item it proves. Do not report done until every item has direct evidence from tests, build, runtime check, screenshot, log, or file inspection. If blocked or partial, say exactly which items remain.

### Timed-worker continuation and durable effects

If a coding worker times out, inspect and continue its shared-worktree changes rather than restarting reflexively. The controller must own final verification: focused gate first, exact invariant repair, then full gate and state checks.

For stateful external effects, a thrown or malformed adapter result is ambiguous (`UNKNOWN`) unless authoritative reconciliation proves `NOT_APPLIED`. Never trigger automatic compensation from an exception alone. Reconcile durable `started` claims before retry, and stop in manual recovery when uncertainty remains.

See [`references/durable-effect-recovery.md`](references/durable-effect-recovery.md) for the handoff sequence, crash-safe outcome taxonomy, regression matrix, and legacy/durable capability-mode pitfall.

## Ticket-to-PR-ready loop

Use when: fixing a bug, feature request, issue, customer complaint, or failing behavior.

Prompt:
> Reproduce or confirm the issue from fresh state, identify the root cause, make the smallest safe patch, add or update regression coverage when practical, run relevant checks, and prepare a reviewer-ready handoff. Stop when the behavior is verified fixed, no safe repro exists, or a missing decision blocks progress. Ask before destructive, broad, or production-risky actions.

## UI/UX Score Loop

Use when: app polish, onboarding, signup/login, item create/edit/share, mobile/responsive, or confusing flows.

Prompt:
> In a browser, complete one realistic user task from a fresh/appropriate state. Score each meaningful screen with the same checklist: clear purpose, obvious next action, visual polish, responsive behavior, error/recovery state, and task success. Fix the weakest confirmed issue, retest the full task, and stop when the flow passes cleanly or no safe improvement remains.

When Alex says a teaser/onboarding must use the **exact real interface**, treat renderer/component reuse as the first acceptance gate—not a late visual-polish task. Replace parallel fake DOM/CSS with shared canonical components and styles, then browser-prove the transition and responsive state. Reserve enough of the bounded session to build, browser-smoke, commit, and deploy; defer optional backend enrichment rather than ending with a sophisticated local implementation that never reaches the live URL. If shared tenant UI code changes, include the tenant artifact/image rollout in the completion contract.

When onboarding is meant to create investment before signup, treat the chat as a **capability-density engine**, not generic conversation: every high-yield answer must visibly add truthful agents, surfaces, accounts, and connectors to the canonical workspace; infer volunteered facts; cap the interview; prevent premature completion; and preserve the preview in the real import seed. Follow [`references/capability-dense-guided-onboarding.md`](references/capability-dense-guided-onboarding.md) for the question architecture, progressive graph contract, stable React-handler pitfall, and runtime verification ladder.

For real interactive architecture/program maps embedded in server-rendered or Markdown-synced pages, follow [`references/embedded-react-flow.md`](references/embedded-react-flow.md). It covers local Vite bundling, `process.env.NODE_ENV`, explicit custom-node handles, immutable-cache versioning, watcher restarts, and mount/edge/browser verification.

## Production error sweep

Use when: deployed app logs, PM2/nginx/runtime errors, broken health route, or recurring production failures.

Prompt:
> Read fresh production/app logs and current service state, identify the highest-impact actionable recurring error, trace it to root cause in the repo/config, make the smallest safe fix, run checks, restart only the affected service if needed, and smoke verify. Stop cleanly if no actionable errors are present. Ask before data, credential, or broad infrastructure changes.

## Fresh-clone loop

Use when: validating onboarding/setup docs, repo handoff, or whether another agent/dev can start cleanly.

Prompt:
> In a disposable clean checkout or equivalent isolated state, follow the documented setup exactly. Record the first hidden assumption or failure, fix the docs or setup script minimally, then retry from clean state. Stop when onboarding succeeds from documented steps alone, or when a missing credential/external dependency requires user input.

## Promise-to-proof loop

Use when: claims in docs, landing pages, demos, generated social, or AI answers may not match real product behavior.

Prompt:
> Collect the product claims in scope, verify each against current code, docs, live behavior, screenshots, or tests, and fix or narrow the least-supported material claim. Do not invent capabilities. Stop when every in-scope claim has evidence, is corrected, or is explicitly marked as future/unknown.

## Overnight docs sweep

Use when: code and docs may have drifted, especially after implementation/deployment.

Prompt:
> Compare current docs, README, examples, and runbooks against the live code/config in scope. Fix only confirmed drift, keep style consistent, run available doc/build checks, and stop when no material mismatch remains or the next mismatch requires a product decision.

## Recent-feedback sweep

Use when: Alex has recently reported several issues or similar agent mistakes.

Prompt:
> Review the recent scoped feedback and current project state, group confirmed issues into reusable failure patterns, search the project for matching cases, fix every confirmed match minimally, and run a final sweep/check. Stop when no confirmed pattern remains or a missing decision blocks safe fixes.

## Test stabilizer loop

Use when: tests are flaky or CI/local runs disagree.

Prompt:
> Run the relevant test repeatedly under comparable conditions, identify the first inconsistent failure pattern, fix one root cause without weakening assertions or coverage, then rerun the same command until the agreed stable streak or until evidence shows the issue is external/blocked. Report exact commands and pass/fail counts.

## Housekeeper loop

Use when: conservative cleanup is requested and no functional bug/feature is higher priority.

Prompt:
> Find one small, provably safe cleanup opportunity, make the smallest useful change, run existing checks, and keep it only if behavior and tests are unchanged. Stop after one clean improvement, no safe opportunity, or any uncertainty that requires review.

## When to load full Loop Library

Load `loop-library` when:

- Alex explicitly asks about Loop Library or loop options.
- The task is not a normal build/app workflow.
- A cron, creative, research, ops, or product workflow needs a loop.
- You need to audit/design a custom loop rather than execute one of these house defaults.