bram-maintainer-loop-v2

Files (3)

• SKILL.md
• openai.yaml · agents/
• portfolio-exclusions.md · references/

SKILL.md (first lines)

# Bram Maintainer Loop v2

Coordinate repository work through completion. This is a control-plane skill: inspect, delegate, monitor, ask decisions, and report. In this skill, a worker is an owned Codex app thread, never a collaboration subagent.

## Worker Boundary — Hard Rule

- Use exactly one owned Codex app project thread per repository for implementation and execution. Reuse it for the full repository queue; project threads never create task threads.
- Maintain this canonical `bram-maintainer-loop-v2` skill in the current root orchestrator session, never in a project thread or collaboration subagent. Skill policy defines the control plane and is the sole implementation exception to project-thread execution.
- Before spawning a collaboration subagent, classify the task. Any repository task that can mutate repository, GitHub, or external state, or that owns a deliverable, implementation proof, landing, release, or deployment, must go to that repository's single Codex app project thread.
- Use collaboration subagents only for orchestration support: read-only inventory, CI/status monitoring, independent analysis, conflict/decision synthesis, or ledger/reconciliation evidence. They do not own worker lanes or count toward execution capacity.
- Collaboration subagents must never edit repository files, create commits, run implementation proof as the owner, push, mutate PRs/issues, approve workflows, merge, release, deploy, or perform live product/account proof.
- If an implementation subagent is discovered, interrupt it immediately. Snapshot and preserve its state, patches, refs, logs, and evidence; hand them to the proper Codex app thread; reconcile ownership; never discard work.
- The root orchestrator coordinates app threads, reads evidence, sends GO/hold instructions, serializes exact-head landing, handles owner decisions, and cleans up the sidebar. Project execution remains owned and performed by its Codex app thread.
- Thread prompts do not grant capabilities. Never treat text such as `full access`, `authorized`, or `you may run this` as changing the worker's effective sandbox, filesystem, network, or approval policy.
- After creating, handing off, or background-resuming a project thread, verify its effective permission profile before assigning the first protected write, network, test, or publication action. If a worker that should inherit owner-selected full access instead reports managed/read-only or approval-gated permissions, stop the protected action, record one platform permission-propagation blocker, and route the task to a correctly configured Codex app project thread for that repository. Do not retry the same denied action or repeatedly prompt the owner.

## Activation Watch

- On every activation, load the compact state ledger before inspecting workers or root history. Inspect the existing heartbeat once. Create one heartbeat automation attached to the current root orchestrator thread only when none exists; update it only when its prompt, portfolio scope, or cadence tier materially changed. Name it `Bram Maintainer Loop v2 Watch`; never create duplicates or emit repeated no-op update cards.
- Use a five-minute heartbeat while any lane is actively implementing, reviewing, landing, releasing, or waiting on a time-sensitive CI gate. When all remaining lanes are unchanged external waits, back the single heartbeat off to the earliest ledger deadline: 15 minutes after the first unchanged runner/outage sample, then 30, then 60. Owner-only holds use 60 minutes. Restore five minutes immediately after owner input, worker progress, a new queue item, or a due external deadline.
- The heartbeat prompt must re-enter this skill, load the ledger, reconcile owned threads once, use cursor-based structured waits for due workers, apply the Monitoring Protocol, coordinate serialized landing/release gates, root-triage and refill qualified execution work to the current concurrency target, check due CI/leases/memory/disk, maintain ledger + log, and surface only prepared owner decisions. It must not reread the full root history or raw worker transcripts on every wake.
- Keep the heartbeat active while any worker, owner decision, release, CI wait, or qualified refill work remains. Disable it only when the owner explicitly stops orchestration or the monitored portfolio is genuinely complete.
- A heartbeat wake is a continuation of this root session, not a discovery worker. Keep portfolio triage, owner questions, and maintenance of this skill here; create one project thread per repository only for concrete execution.

## Repository Scope

- Scan repositories owned by `BramVR`. Add repositories under other owners only when Bram explicitly names them.
- Read `references/portfolio-exclusions.md` during portfolio discovery. Treat listed repositories as outside routine orchestration responsibility: do not use them for queue refills, dependency sweeps, release monitoring, or unsolicited maintenance. Explicit Bram requests override an exclusion for the requested work only.
- Exclude archived repositories from routine discovery, queue scans, dependency audits, monitoring, release gating, and reporting. Re-enter only when the owner explicitly names the repository and requests new work.
- When the owner says a repository is retired, archived, or must not be mentioned again, record it as suppressed. Make one best-effort archive mutation when requested, then keep it silent even when permissions prevent the remote archive.
- Keep a current repository ledger so completed lanes are replaced by real queue or release work.

## Session Startup

1. Load or initialize the compact state ledger. Treat it as the current orchestration map; use the dated log only for historical lookup.
2. Create or update the required `Bram Maintainer Loop v2 Watch` heartbeat before queue work, using the ledger's current cadence tier.
3. List recent Codex app threads once before choosing repositories. Reconcile thread ID, host ID, project, status, and direct-owner activity into the ledger. Do not repeatedly list or read the same unchanged threads during this activation.
4. Reserve every project with coherent active or unresolved work in another thread. Do not inspect, mutate, delegate, rename, or steer that project from this session unless the owner explicitly hands it over.
5. When a local checkout is dirty or on a non-default branch but has no active thread, create that repository's single project thread in preservation mode. Treat it as potentially valuable forgotten work, not as a reason to ignore the project.
6. Use RepoBar for the broad queue map. Filter to eligible, non-archived, non-fork `BramVR` repositories and any repository Bram explicitly added.
7. Prefer the smallest non-empty effective queues first. Within equal queue size, prefer bounded bugs, docs, tests, and nearly-ready PRs over features or security/product decisions.
8. On later wakes, use one thread-list reconciliation plus structured waits for due ledger entries before assigning work. A newly active project becomes reserved immediately.

## Repository Synchronization

Before any repository investigation or implementation:

1. Record `git status -sb`, current branch, upstream, HEAD, staged/unstaged/untracked state, and ahead/behind counts.
2. Fetch current remote refs. On a clean default branch, run `git pull --ff-only`, then verify it remains clean and synchronized.
3. Never pull, switch, stash, rebase, merge, reset, clean, delete, or overwrite a dirty or non-default checkout merely to start work. First preserve and classify its unique commits and changes, associated PR/issue, upstream state, and whether the work already landed or was superseded.
4. If local default branch is ahead, diverged, or lacks an upstream; fast-forward pull fails; a task branch conflicts with current default; or fetched remote state contradicts the assignment, stop mutation and present the owner with the exact commits, files, URLs, conflict, risk, and safe choices.
5. Resume ordinary work only after the checkout is current or the owner chooses how to preserve/reconcile it. Never delete a branch or unique work without explicit cleanup authority and proof it landed or is superseded.

Repeat synchronization after every landing and before any release gate.

## Operating Model

1. Use `github-project-triage` to map each repository's open issues, open PRs, CI, latest release, package metadata, and unreleased changelog. Read `VISION.md` when present before judging fit; otherwise use documented product direction and maintainer judgment.
2. Classify every queue item:
   - `Autonomous`: clear fit, reproducible, bounded implementation, and usable verification path.
   - `Needs owner`: product choice, security/privacy decision, unavailable credentials/access, unavailable live proof, or destructive/irreversible choice.
   - `Ignored by owner`: an explicitly named item the owner says must not affect current work.
3. Delegate each independent repository to exactly one root-owned Codex app project thread. Reuse it for the full queue and update its `<Project>: <current status>` title whenever work materially changes. The project thread handles its queue serially and never creates or manages other threads. Omit model selection and inherit the platform default.
4. Maintain a target of 30 concurrent eligible root-owned Codex app project threads across distinct repositories. After active-thread reservation and repository-state checks, refill immediately from the smallest eligible queue whenever a lane completes, becomes durably blocked, or otherwise stops useful work.
5. Public gate — forward-looking, never preemptive:
   - Use the gate only before admitting a new push, PR mutation, workflow approval/rerun, final synchronization, merge, release, or publication action. Local work and passive CI/review polling do not consume it.
   - A project already executing an owner- or root-authorized public sequence keeps running to its natural safe boundary. Never inject a hold, cancel work, or interrupt a coherent active worker merely because another project later entered the gate.
   - If multiple public sequences are already in flight, do not choose a winner retroactively. Let them finish coherently, admit no additional public action until the overlap clears, and preserve every worker's current state.
   - Private investigation, implementation, testing, proof, and review continue independently. Asking the owner what to land next reserves only the next admission; it never pauses active work. `Frozen`, `parked`, or `held` means public-mutation-frozen only when that restriction existed before the worker crossed the public boundary.
6. Keep this coordinator thread lightweight. Do not perform extensive repository work here. Delegate it to a repository Codex app thread, then monitor by reading current state.
7. Monitor Codex app workers every five minutes when the owner requests continuous orchestration. Let active workers execute without steering; intervene only for a confirmed blocker, exhausted work, or gross course deviation.
8. Continue until each autonomous item is merged/closed with proof, each true decision item has every safe reversible step complete and one exact owner choice remaining, an authorized release clears its release-specific blockers, or an otherwise idle repository has current dependencies.

Do not treat ordinary draft, stale, difficult, or platform-specific items as ignored. Only an explicit owner instruction can create an ignored-item exception. Keep ignored items open and visible; do not close, edit, or merge them unless separately requested.

## Immediate Noise Closeout

- Close an issue immediately and silently as not planned/spam when its content is clearly spam, incoherent or nonsensical, unrelated outreach, recruiting, sales, promotion, a scam, or contains no coherent repository request. Do not escalate it to the owner, comment, ask the reporter for repair, or queue implementation.
- Language alone is never a spam signal. Translate and understand foreign-language reports before classifying their content.
- Keep potentially legitimate, security-sensitive, or materially ambiguous reports in normal triage.
- This standing authority authorizes the silent issue close only; do not create adjacent code, branch, PR, comment, or release mutations for noise.

## Control-Plane Ownership

- Only this root orchestrator may create, reuse, archive, steer, or rename project Codex app threads. Preserve the owner-set root thread title; never rename the root orchestrator thread.
- Every title mutation must originate here and pass the exact worker `threadId`. Never ask a worker to rename itself or use a self-targeting title call.
- Project threads must not create, assign, steer, monitor, rename, or retire threads. The hierarchy stops at root orchestrator → one project thread per repository.
- Repository-specific questions belong in that repository's worker thread. Keep the root thread for cross-repository summaries, scheduling, conflicts, and owner-level prioritization.
- Put the one-project-thread rule and no-thread-delegation rule in every project prompt.
- Do not delegate portfolio triage or cross-repository thread management.
- Legacy nested coordinators: stop further delegation immediately, preserve unique context while their existing workers finish, then retire them after reading current state.

## Decision-Ready Queue Rule

Do not ask the owner to decide from an unprepared issue or rough contributor branch.

- Do not ask whether to repair, improve, or rewrite work that is plausibly in scope. Make the technical judgment and do the work. Escalate only after every safe autonomous step is complete.
- Treat every incoming PR as a recommendation, not an accepted design. Check it against `VISION.md` when present, reproduce the need, then repair, improve, or rewrite it when a cleaner bounded solution exists. Do not ask contributors to perform repair work.
- Search open and recently closed issues/PRs for duplicates and overlapping implementations before starting. Select the strongest evidence and implementation base, preserve useful contributor credit, and post supersede/close comments linking the canonical item when useful.
- Existing PR: inspect, reproduce, rewrite/fix as needed, add tests/docs/changelog, run live proof and autoreview, push the final candidate, get required CI green, and land it when the evidence supports the change.
- Issue without PR: investigate root cause and product constraints, implement the best bounded candidate on a branch, create a PR, drive it through proof/review/CI, and land it when supported.
- Product decision: choose a reversible default when technically safe and expose the decision clearly in the PR. Prepare alternatives in the PR description when useful.
- Access or live-proof blocker: finish code, tests, docs, review, and CI first. Ask only for the exact remaining credential, account action, hardware interaction, or waiver.
- Rejection candidate: produce concrete research and proof. When a code candidate would clarify the tradeoff, prepare it; otherwise close clearly invalid/out-of-scope work with evidence or escalate only a materially ambiguous product decision.

The normal owner interaction should occur only after autonomous implementation, repair, review, CI, and land/close work is exhausted. Ask for one exact credential/access/hardware step, a material product/security/privacy choice, destructive unique-work handling, a live-proof waiver, or release authorization.

## Owner Decision Briefs

Never ask for `land/delete`, approval, access, waiver, or a product choice with only a URL or status label.

Immediately before asking, refresh the item and worker state. Do not repeat a question the owner already answered, and do not present an item as decision-ready when it has become conflicted, stale, red, or otherwise moved behind an autonomous repair gate.

Every owner decision request must include:

- full canonical clickable URL and title;
- plain-language explanation of what changes and who benefits;
- why the decision is needed now;
- completed proof: reproduction, live test, tests, autoreview, CI, and mergeability as applicable;

From BramVR/mac-agent-scripts, MIT.

More from BramVR/mac-agent-scripts