agentleFS
LatandLatand/delegatus/.claude/skills/delegatus-conveyor/SKILL.md

delegatus-conveyor

Skill39 starsChanged 5 days agoMITView on GitHub

The full issue→implement→review→merge→deploy conveyor for Delegatus — wake loop, lane lifecycle, merge bars, deploy protocol, resource guard, and recovery playbooks. Use when orchestrating multi-lane development on this repo, running long autonomous sessions, or recovering from crashes/stuck reviews. Builds on delegatus-orchestration (spawn/messaging) and the pipeline review stages in `docs/review-loop.md`.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Design-critique gate on all UI/UX: every visual change is designed or critiqued against rendered screenshots.

    line 27
  2. Very specific:

    Before accepting the recovery, join /api/pipelines, /api/files, and viewer.snapshot: the reviewer path must have the expected pipeline …

    line 40
  3. Very specific:

    Call deploy_exact_sha with revision=<sha>.

    line 49
  4. Very specific:

    Machine reboot: check viewer-release.json container running.

    line 75
  5. Distinctive:

    Every user-visible defect gets a GitHub issue with the diagnosis baked in, then a lane.

    line 85

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Delegatus conveyor — autonomous multi-lane pipeline

The orchestrator (a long-lived Claude session in ~/.agents/tools/live-log-viewer-next) drives every open issue through: issue → worktree lane → builder stage → reviewer stage with a fail edge to a fix stage → merge on a pass at the reviewed head → batched deploy → cleanup. Delegatus owns the clock (#1245): its seat tick checks this project every few minutes and wakes the seat when work is owed, so the seat never schedules itself — no ScheduleWakeup, no CronCreate, no Monitor loop, and a seat still holding one deletes it the moment the mandate arrives. "Every checkpoint" below means every arriving wake, and each wake re-derives board state from bounded snapshots rather than from what the previous one remembered, so the loop survives compaction, host death and rotation.

Lane lifecycle

  1. Issue with full spec on GitHub (agent: * label names the owner role — runtime comes from the role registry). Bodies with control chars → write file, --body-file (or REST gh api -X POST repos/.../issues -f ... when GraphQL is rate-limited). The operator's words go into issues and PRs only paraphrased in English, never quoted verbatim: the operator dictates with slang and does not want it quoted.
  2. Pipeline worktree: pin the fetched base branch and commit in POST /api/pipelines; let the Pipeline API provision its dedicated worktree and branch.
  3. Materialize the implementer as a pipeline stage. Create the owning pipeline through POST 127.0.0.1:8898/api/pipelines with src set to the orchestrator transcript and the implementer plus review stages declared before Start. The controller mints the stable client attempt ID, parent edge, and durable pipeline membership. A dead-host recovery may use retry-stage after a clean-worktree check or explicit operator approval for its hard reset and clean. Preserve a dirty interrupted worktree in needs_decision for the recovery-stage adoption path tracked in #387. A terminal container with a committed head gets an explicit successor pipeline with recovery and review stages; prior attempts remain historical evidence. Prompts stay English; the controller appends the stage_report contract, so a stage prompt names no verdict format of its own. Stage prompts name their deliverable, permitted work and verification. Add a scope restriction only with its source, protected resource and current reason. Required dependent tests and adapters need a permitted owner. Existing controller publication and project release procedures supply their own boundaries. Prompt content is role + scope only; model identity and reasoning level are launch parameters. Never name the model or reasoning level in the prompt text.
  4. Run review as run stages. Declare a read-only reviewer run stage with onFail: {to: "<fix>", maxRounds: N} and a builder apply-fixes stage whose next returns to the reviewer; each round starts a fresh reviewer on the new head. Reviewer runtime comes from the role registry. The review budget defaults to 3; choose it with the mandate's risk rubric. Never compose a review-loop stage or start a flow: the server refuses POST/PATCH /api/flows.
  5. Round policing each checkpoint: read the lane with get_pipeline (stage attempts, verdicts, findings). A pass approves only the exact head that reviewer saw; a commit after it needs a new review. A parked stage (needs_decision) is answered with pipeline_action resolve-decision; a clean parked stage may use retry-stage, and dirty recovery work gets a durable successor stage (Review recovery, below). continue-review is always refused: the budget is fixed at creation, so a budget that was too small needs a new pipeline. A spent budget never counts as a pass: a terminal advance gate re-checks the last fix once, and a failed re-check parks the lane.
  6. Merge on a passing review of the PR's current head per the bar (below): gh pr merge --squash or REST gh api -X PUT repos/.../pulls/N/merge -f merge_method=squash.
  7. CLEANUP ONLY AFTER state == MERGED (burned 4×): kill panes → git worktree remove --force → branch -D (worktree before branch).
  8. Deploy in batches (below), then PATCH Delegatus task cards (/api/tasks/<uuid>) — the user tracks progress on the board, never in internal task lists.

Merge bars

Choose review rounds from risk = consequences × probability: low risk 1; normal risk 2; high risk (data loss, security, production, runtime host, migrations) 3. The default is 3. More than 3 only when the operator asks; state the reason in the brief.

  • DATA bar (runtime/pipelines/agent/scanner/data-integrity): a passing review at the final head required; choose the review budget with the risk rubric above. Extend beyond 3 only when the operator asks, with the reason in the brief.
  • UI bar (components/styling/mobile): choose the review budget with the risk rubric above. More than 3 only when the operator asks, with the reason in the brief. Merge only on a passing review of the PR's current head; any commit after that review, including tests, comments or screenshots, needs a new review before merging. Non-blocking findings in a passing review go to a follow-up issue.
  • Design-critique gate on all UI/UX: every visual change is designed or critiqued against rendered screenshots. Reuse or extend the demo-capture renderer (scripts/demo-capture*) to capture the feature. Do not interrupt active lanes; critique lands at their finish.
  • UI lane order: builder → design critique with an onFail edge back to the builder → one code review at the final head. The critique owns judgment (weight, wording, hierarchy) and its fail verdict returns the lane to the builder; the review runs once, on the head the critique passed. Blocking layout breakage is the reviewer's job too — the standing scaffold rule (REVIEW_FRAME_RULES) makes rendered surfaces part of correctness, so evidence that skips a surface the issue names is a fail on its own, and overflow, clipped or zero-width controls and overlap are severity-ranked findings with viewport and measured numbers, rendered from an export of the reviewed HEAD (never the live worktree, never the operator's Delegatus).

Reviewer isolation & delegation depth (#393)

  • Reviewer and verifier roles are terminal. Each performs every assigned check inside its own single visible session and has zero child-launch capability: no helpers, workflows, teams, swarms, native subagents, Delegatus children, or MCP children — regardless of engine. A reviewer that needs more coverage says so in its verdict; the orchestrator adds a stage.
  • Multiple perspectives = explicit stages. Extra review angles run as separate visible pipeline stages the operator sees on the board (additional reviewer stages), never as fan-out from inside a review session.
  • Delegating roles stay bounded. Builder, architect, and orchestrator spawns always record lineage (src, plus role/reviews for reviewer spawns) and keep the delegation chain within the configured maximum depth — initially two (orchestrator → builder → helper; nothing deeper). Product enforcement is tracked in #393.

Review recovery (a review stage cannot run)

When the implementer transcript disappears or the engine cannot run rounds, park the owning stage with needs_decision. The orchestrator retries the review stage through the Pipeline API or creates a successor pipeline whose first run stage performs one fresh read-only review (role reviewer; its runtime comes from the role registry) and whose final stage verifies the repair. Set pipeline src to the orchestrator transcript; record the previous implementer path and conversation ID in the pipeline spec and review directive. The reviewer reports through stage_report with severity-tagged findings for the head it reviewed. Reviewer isolation per #393 still holds: the recovery reviewer runs its checks alone and launches nothing. Raw reviewer /api/spawn calls have no place in pipeline work.

Before accepting the recovery, join /api/pipelines, /api/files, and viewer.snapshot: the reviewer path must have the expected pipeline membership and parent in /api/files, and the active operator snapshot must include that path in the rendered view. Keep the earlier attempts and verdicts as compact history.

Deploy protocol

This section, and the tool it names, are about deploying this application — Delegatus, the one serving the board — and about no other project's release. The mandate carries none of it (#1760): a manager of somebody else's project reads its own project's release steps, not these.

The manager's own path (#795, #1321). YOU decide when to deploy, and you execute it yourself. Your authority is your designated seat, attributed server-side — a session that is not the designated orchestrator is refused, and a seat acts only for its own project, so deploy_exact_sha refuses every caller but this project's own seat. Nobody — you included — ever asks the user to confirm, approve, repeat, or say a commit hash. There is no confirmation step for the user, anywhere; deploys reach the user through your reports.

  1. Prepare: merges landed on origin/main, gates green. Never deploy red.
  2. Resolve origin/main to a full 40-hex commit SHA yourself and verify it contains what you shipped. The SHA is machine evidence — never route it through the user.
  3. Call deploy_exact_sha with revision=<sha>. Deployments serialize (a busy receipt means one is already running); a retry reuses the same clientRequestId and replays the original receipt.
  4. Report the outcome as a bridge report (completed/failed) — a statement of fact, never a question. The deployment ledger is the durable audit of what shipped and when.

From a shell, the same deploy is scripts/rebuild.sh (timeout 600000), run from any checkout of the repository — a worktree is fine. That is the whole command: no wrapper around it and no git pull before it. The script posts a revision and the runtime host builds that revision from its own canonical Git mirror, never from the working tree, so the checked-out branch is irrelevant and must not be moved (#1309). With no argument and no LLV_DEPLOY_REVISION override it reads the canonical refs/heads/main tip itself and posts that exact SHA; pass a full 40-character commit SHA in either case to pin a redeploy or rollback. The script posts explicit SHAs lowercase. Phases end with deployment phase: succeeded. Then ALWAYS:

  1. curl 127.0.0.1:8898/ → 200 (first hit after promote can take ~25s cold).
  2. Remove the outgoing container — promotion leaves it running (bug, #137): keep only the container named in ~/.config/agent-log-viewer/state/viewer-release.json.
  3. Topology: runtime-host container owns the 8898 proxy → promoted llv-deploy-* on its candidate port. Nothing else may hold 8898, or the runtime-host crash-loops on bind; a machine that still has a retired systemd unit gets the CLI's migration notice (docs/docker.md, "Moving off the systemd install").
  4. Remind the user to hard-reload the tab (stale client after deploy causes phantom UI behavior).
  5. Runtime-host protocol changes (anything under src/runtime-host/ or new socket methods): rebuild its image too — docker compose build runtime-host && LLV_VIEWER_DEPLOYMENTS=1 docker compose up -d runtime-host (WITHOUT LLV_VIEWER_DEPLOYMENTS=1 the recreate silently drops the 8898 proxy). Stale runtime-host symptom: viewer logs runtime request method is unsupported.
  6. Since the #194 cutover (2026-07-14) spawns are pane-less (LLV_SPAWN_TRANSPORT=structured, target:null); the tmux transport is removed. Module-level singletons in route-reachable code MUST live on globalThis (Next standalone bundles instrumentation separately — in-process tests can't catch it). docker logs survives restarts — use --since to check whether a restart cleared an error. First Claude structured spawn after a deploy may time out (cold broker) — retry once. Batch merges into one deploy; deploy immediately for user-blocking fixes.

Resource guard (every checkpoint — the machine has OOM'd)

  • free -h: available < 4–6G or swap > 30% → act. Kill ONLY orphaned MCP processes (ppid=1, etime > 2h). Live panes' MCP fleets belong to the user — never kill them; suggest closing finished panes instead.
  • pgrep -c -f "codex exec" > ~7 → investigate. Cap concurrent codex reviewer rounds at ~2 (brief 3 OK when >10G free).
  • Root causes already fixed (keep them true): #162 headless codex runs with mcp_servers={} + process-group kill + reaper + probe backoff; #168 integration tests use isolated temp homes.

Data safety (hard rules, learned the hard way)

  • NEVER delete transcripts/user data without explicit per-batch user confirmation — present the candidate list first. Identify fixture transcripts ONLY by their first user prompt; never body-grep (real sessions quote test markers).
  • Deleted-but-open transcripts are recoverable: (deleted) rollout links in /proc/<pid>/fd/ → copy fd content back to the path; re-sync while the session lives (fd size > file size → overwrite).
  • Conversations with ≥1 human-authored message are untouchable, always.

Recovery playbooks

  • Machine reboot: check viewer-release.json container running; runtime-host owns 8898 (see deploy §3); panes are gone while worktrees survive. Inspect each pipeline worktree first. Clean parked stages may use retry-stage; dirty stages stay needs_decision and retain every byte for the #387 recovery-stage adoption path.
  • Controller hang (all stages spawning, no logs, 0 codex exec): docker restart <current llv-deploy> → 8898=200 → retry-stage each clean parked stage.
  • "agent registry is busy" (accounts UI dead, stages pausing): transient lock contention (#179) — retry the operation; a review that passed mid-error still counts for the head it reviewed.
  • Claude spawn lands on login screen: account with dead token selected (#178) — kill pane, respawn with explicit accountId; re-login via CLAUDE_CONFIG_DIR=~/.config/agent-log-viewer/accounts/claude/<id> claude + /login.
  • codex CLI self-update mid-spawn (spawn 500s, pane says "restart Codex"): kill pane, respawn; expect rollout format drift after updates (e.g. 0.144 moved cwd to payload.cwd).
  • GraphQL rate limit exhausted (agents share 5000/hr): everything has a REST equivalent — gh api repos/... for view/merge/issues/comments.

Interaction rules

  • User messages (UA/RU, often dictated) override the current checkpoint plan — his active complaint becomes the top lane immediately.
  • Every user-visible defect gets a GitHub issue with the diagnosis baked in, then a lane; answer the user with cause → what's already done → what ships next.
  • Board cards (/api/tasks) are the single user-facing progress tracker: PATCH on merges/deploys, status: "done" when shipped.
  • zsh traps: unquoted $VAR does not word-split (use explicit loops); ===== needs quoting; heredocs for anything with braces.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.