← LeaderboardThe Skill Leaderboard

brooks-harness

Maintenance orchestrator for the brooks-lint plugin itself. Runs a sequential subagent pipeline — author → eval → QA → trigger-audit → release — to add or edit a skill, refresh the eval suite, keep the four manifests + all README translations + CHANGELOG + AGENTS/GEMINI in sync, audit trigger boundaries, and cut releases. Drives the five agents in .codex/agents/ (skill-author, eval-curator, consistency-qa, trigger-boundary-auditor, release-manager). Triggers when the maintainer asks to work ON brooks-lint itself: "add a new skill", "edit the brooks-debt guide", "update the eval suite", "fix th

Published by hyhmrright ↗hyhmrright/brooks-lint

Try your first task

Maintain one brooks-lint skill

Start a fresh conversation. Replace the highlighted placeholders.

Use brooks-harness in [brooks-lint checkout] to implement [bounded skill or guide maintenance change]. Select the required sequential stages, preserve other contributors' edits and keep assigned file ownership explicit. Synchronize affected evals and repository artifacts, run the mandatory validate/test/evals QA gate, and audit trigger boundaries if descriptions changed. Respect the documented single retry and report failure rather than skipping a stage. Return changed files, stage results and the final verdict; do not release, push or merge without my requested integration choice.

Required inputs

[brooks-lint checkout]
[bounded skill or guide maintenance change]

User-approved starter prompt based on a pinned source version; check current skill requirements before running. Task evidence ↗

SKILL.md

name: brooks-harnessdescription: >  Maintenance orchestrator for the brooks-lint plugin itself. Runs a sequential  subagent pipeline — author → eval → QA → trigger-audit → release — to add or  edit a skill, refresh the eval suite, keep the four manifests + all README translations + CHANGELOG  + AGENTS/GEMINI in sync, audit trigger boundaries, and cut releases. Drives the  five agents in .codex/agents/ (skill-author, eval-curator, consistency-qa,  trigger-boundary-auditor, release-manager).  Triggers when the maintainer asks to work ON brooks-lint itself: "add a new skill",  "edit the brooks-debt guide", "update the eval suite", "fix the trigger  descriptions", "make this change and validate it", "release brooks-lint", "bump and  publish", and follow-ups: "re-run", "re-validate", "update that skill", "redo the  audit", "do the X part again".  Do NOT trigger for: USING the brooks-lint analysis skills on some target codebase  (that's brooks-review / brooks-audit / brooks-debt / brooks-test / brooks-health /  brooks-sweep); generic questions about brooks-lint that don't ask to change it; or  maintenance of a different plugin.

brooks-lint — Maintenance Harness (Orchestrator)

This skill orchestrates work on the brooks-lint repo itself. It runs a sequential subagent pipeline: each stage is a dedicated agent defined in .codex/agents/. Use the available Codex collaboration tools with the matching agent role; inherit the parent model and permissions. If custom roles are not loaded, pass the role's developer_instructions from its TOML file to a standard subagent. Stages run sequentially. Every editing agent must preserve other contributors' changes and own only the files assigned by the orchestrator.

Pipeline

[orchestrator]
   Phase 0  context check
   Phase 1  classify request → select stages
   Phase 2  run selected stages in order, with a QA loop-back:
            skill-author → eval-curator → consistency-qa ─(FAIL)→ back to author
                                              │ PASS
                                              ▼
                            trigger-boundary-auditor   (only if a description changed)
                                              ▼
                                      release-manager  (only if release requested)
   Phase 3  report + collect feedback

Phase 0 — Context check

Determine the run mode before doing anything:

_workspace/brooks-harness/ exists + maintainer asks to redo part of a prior run → partial re-run: invoke only the affected stage(s), reusing prior notes.
_workspace/brooks-harness/ exists + a fresh request → new run: move the old folder to _workspace/brooks-harness_prev/, start clean.
No _workspace/brooks-harness/ → initial run: create it.

Run notes and the QA report live under _workspace/brooks-harness/. The real artifacts are the repo files themselves — agents edit skills/, evals/, manifests directly; _workspace/ only holds the run's notes and the PASS/FAIL verdict for audit.

Phase 1 — Classify the request

Pick the minimal set of stages. The QA stage is never skipped — every change is gated.

Request	author	eval	QA	trigger-audit	release
Add a new skill	✓ (via `new-skill` scaffold)	✓	✓	✓	—
Edit skill / guide content	✓	if codes changed	✓	if `description` changed	—
Edit `_shared/` framework	✓	if risk defs changed	✓	—	—
Codex / maintenance configuration	—	—	✓	—	—
Eval suite only	—	✓	✓	—	—
Fix trigger descriptions	✓	—	✓	✓	—
Release	—	—	✓	—	✓
Full: change + release	✓	as needed	✓	if applicable	✓

Phase 2 — Run the pipeline

Spawn each selected stage as a subagent in order using Codex collaboration tools. Pass each agent (a) the task contract and (b) the previous stage's summary. Agents write their summaries to _workspace/brooks-harness/; read them between stages.

skill-author — creates/edits the content. For a brand-new skill it invokes the new-skill scaffold. Returns the list of files touched + convention-relevant choices (new risk codes, new Step numbers, changed description trigger phrases).
eval-curator — if skill-author reported new/changed risk codes or modes, adds the paired happy-path + false-positive scenarios and runs npm run evals.
consistency-qa (gate — never skipped) — runs npm run validate + npm test + npm run evals, then the cross-document sync checks (manifests, all version-bearing text files, CHANGELOG, AGENTS/GEMINI book count, eval count). Writes a PASS/FAIL verdict. On FAIL: loop back to the agent named in the verdict (author or eval-curator), fix, then re-run QA. Repeat once; if it still fails, stop and report to the maintainer.
trigger-boundary-auditor — run only if a description field changed. It read-only audits the six shipped skills' trigger surfaces for false-triggering and routing collisions. Surface its findings; if it flags a real collision, loop back to skill-author.
release-manager — run only if a release was requested, and only after QA PASS. Cuts the release via the release skill.

Phase 3 — Report & feedback

Report: stages run, files changed, QA verdict, trigger-audit findings (if any), and the release URL (if any). Then offer the maintainer a feedback opening: "Anything to adjust in the result, the agent roles, or the pipeline order?" Record accepted changes in the AGENTS.md harness change-log table.

Conventions this harness enforces

Inherit the current Codex model and permissions; do not select a Claude model.
consistency-qa must be general-purpose (it runs npm scripts); the trigger-boundary-auditor is read-only.
No command wrappers are created — Codex discovers .agents/skills/.
Direct-to-main releases follow AGENTS.md. Commit, push, tag, or publish only when requested. Run the explicit validate/test/evals gate; Claude global rules and hooks do not execute in Codex.

Error handling

A stage that fails once is retried once with its error as input; a second failure stops the pipeline and reports to the maintainer (no silent skip).
QA FAIL never proceeds to release.
Conflicting data is reported with provenance, not deleted.
High-risk git ops (--no-verify, --force, history rewrites) require explicit maintainer authorization — release-manager stops and asks.

Test scenarios

Normal flow — "add a brooks-security skill": Phase 1 selects author+eval+QA+audit. skill-author runs new-skill brooks-security, creates SKILL.md (with a sibling-carving "Do NOT trigger for:" clause) + guide; eval-curator adds an S-code happy-path + a false-positive scenario; consistency-qa runs the gate → PASS; trigger-boundary-auditor confirms no collision with brooks-review/audit. Report lists files + PASS.

Error flow — QA FAIL on book-count drift: maintainer adds a thirteenth book but edits only source-coverage.md. consistency-qa's cross-doc check finds README still says "twelve" → FAIL, attributed to skill-author. Orchestrator loops back; skill-author updates README/AGENTS/GEMINI wording; QA re-runs → PASS. No release was requested, so the pipeline ends at Phase 3.