[ OPERATIONS · OPERATOR UTILITY ]

/improve-queue

Run the improvement-queue auto-implementer.

Download the skill file (.md)

/improve-queue — daily auto-improver

Closes the loop on the improvement queue. Colleagues' sandboxed Claude sessions write proposals to ~/scratch/improvements/; the root aggregator (17:00 Sarajevo) bundles them to a Drive doc + #your-channel post AND drops a machine-readable /opt/improvements/pending/<date>.json. This skill is the step that used to be manual ("Faris pastes the doc and says apply this") — it reads those bundles and acts on them.

When to trigger

• Automatic: your server cron under user faris, ~17:30 Sarajevo (after the aggregator). See shared/your server_setup/install_improver_cron.sh.
• Manual: the user says "run the improvement queue", "process the improvements", "apply queued improvements", "what's in the improvement queue", or invokes /improve-queue.

How to run it

This skill is a thin wrapper around the orchestrator. When invoked:

1. Run the orchestrator from the repo root:

• Default (safe): node shared/improvement_queue/improver.mjs → shadow mode (applies each safe proposal, runs the gate, shows the diff, then reverts — nothing is committed or pushed).
• Live: node shared/improvement_queue/improver.mjs --live → commits one revertable commit per proposal (fingerprint in the message) and pushes to main; the deploy cron pulls into /opt within 60s.

1. Relay the digest it prints (auto-applied / would-apply / held-for-ACME Agencyw / already-live / needs-attention). The orchestrator also posts the digest to #your-channel.

Do not hand-edit the queue state. The orchestrator owns git + Slack + the gate.

Triage boundary (who decides what)

Triage is deterministic and defaults to MANUAL on any doubt (triage() in improver.mjs):

Infra/spend keywords that force a bug to manual: .env, secret/token/credential, oauth/password, bridge, clickup_executor, sandbox_guard, preflight, aggregator, ecosystem, meta_lead_ads / meta ad / ad set / campaign / pixel / spend, google ads, billing/payment, webhook, git push.

Landing edits are bounced before triage (isLandingEditProposal() in improver.mjs): a proposal that touches websites/ or describes a change to a deployed lander never enters the auto-apply path — it's held with a "route via /landing-edit" reason and no worker is spawned. Landing edits must go through /landing-edit (auto-deploy, no approval); a sandbox session that writes one as an improvement proposal has bypassed that path. websites/ is also a separate repo and can't be committed from the main repo regardless. Incident: 2026-06-19.

Safety gate (the real guardrail — enforced in code, not by the LLM)

For every auto item the orchestrator:

1. requires a clean tracked working tree on main before starting (else it skips the whole run and Slacks why);
2. spawns an apply-one worker (see contract below) to make the edit;
3. re-derives the actually-changed files from git (ignores the worker's self-report) and reverts + reclassifies to manual if any file matches the PROTECTED denylist — .env, .git, .claude/hooks, the bridge, the ClickUp executor, anything under shared/improvement_queue or shared/your server_setup, run_claude_subprocess.mjs, ecosystem.config.*, meta_lead_ads.mjs / meta_web_leads.mjs / google_ads_optimize.mjs, anything under websites/ (separate repo + gitignored here — landing edits go through /landing-edit, never a proposal), or any secret/credential/token path;
4. runs node --check on every changed JS file and JSON.parse on every changed JSON file — any failure reverts the item;
5. only then (live mode) commits that one proposal and pushes.

Each proposal starts from a clean tree and ends clean (committed-in-live, or reverted-in-shadow/blocked/failed/commit-failed), so items never bleed into each other. A commit/push that fails reverts its own changes too — otherwise the dirty files leaked into the next proposal's git add and cascaded the failure (incident 2026-06-19).

Apply-one worker contract

The orchestrator spawns one claude -p worker per auto proposal (sandbox:false, Max auth). Its rules (also embedded in the spawn prompt):

• Check "already applied" first. Sandbox clones lag, so many proposals are already live on main. If so → make no edits, report already-done.
• Make the minimal change; no unrelated refactors.
• May edit: docs (*.md, CLAUDE.md, SKILL.md), client config JSON, and the single client/skill script the proposal targets.
• Must NOT edit any PROTECTED path (see gate) or run git / Slack / ad-creating skills. If the proposal needs a protected path → report needs-human.
• Run node --check on changed JS; follow the bug-fix protocol (update the matching CLAUDE.md/SKILL.md + incident line where called for).
• End with one line: ###RESULT### {"status":"applied|already-done|needs-human|failed","summary":"…","files":[…],"reason":"…"}

Architecture

colleague sandbox sessions → ~/scratch/improvements/*.md
        │  (root cron 17:00)
        ▼
aggregator.mjs → Drive doc + #your-channel post + /opt/improvements/pending/<date>.json (0644)
        │  (faris cron 17:30)
        ▼
improver.mjs (this skill) → triage → apply-one worker → GATE → commit+push (live) / diff+revert (shadow) → digest
        │  (deploy cron, 60s)
        ▼
/opt/agency-os updated → colleagues' clones sync

State: ~/.improver/improver-state.jsonl (one line per processed fingerprint, in faris's home so the cron needs no root). Pending bundles are READ from /opt/improvements/pending/ (world-readable, written by the root aggregator). Kill switch: touch ~/.improver/improver.disabled.

Deploy (as faris, no sudo): the improver needs no root — /opt/agency-os auto-pulls every 60s, and faris's own clone + crontab are user-writable.

cd ~/agency-os && git pull
bash shared/your server_setup/install_improver_cron.sh        # shadow (default)
# …after ~a week of clean digests:
bash shared/your server_setup/install_improver_cron.sh --live

Tuning

• Loosen/tighten the auto class: edit MANUAL_SIGNALS and triage() in improver.mjs.
• Add a never-auto path: append to PROTECTED in improver.mjs.
• Flip from shadow to live: change the cron in install_improver_cron.sh (add --live) and re-run it on your server, or set IMPROVER_MODE=live.

Rollout

Ships in shadow mode. Watch ~a week of digests (it shows exactly what it would auto-apply and what it holds), confirm the classifier, then flip to --live.