Coding policy plugin for Baruch's AI agents. Language-agnostic code quality rules plus Tessl-specific plugin authoring standards — covering commits, testing, error handling, skill structure, and script delegation.

What's New

Report-cache cleanup — check-report-caches runs at session start and removes regenerable build and package caches (Go build and module caches, pip, npm, virtualenvs, node_modules, bytecode, copied plugin caches) from idle Herdr reports directories the foreman ledger names. Only a directory matching an enumerated cache kind by name, signature and top-level entries is removed, whole; every other file and directory stays. Workers keep those caches out of the reports directory in the first place
Worktree and branch cleanup — anything origin can restore is removed without a word; work that exists nowhere else is reported, never touched
- check-leftover-worktrees runs at session start for the session's own repository
- An idle clean worktree whose HEAD origin holds is removed
- A local branch origin holds or merged is deleted
- An unprotected branch on origin merged with no open pull request is deleted
- An idle dirty or unpushed worktree, an unpushed local branch, and a stale unmerged branch on origin with no pull request are listed for the operator
- sweep-worktrees.sh applies the worktree and local-branch rules to every repository with a worktree directory under ~/.worktrees in a Herdr round preflight
herdr-foreman and herdr-standup skills + agent-team-operation rule (the standalone-versus-team-round mode test; the team-round contract ships as skills/herdr-foreman/references/team-operation.md, which the foreman loads and every worker brief names) + herdr-team-status hook — run a three-agent team round inside Herdr: measure each worker's subscription headroom, assign developer / tester / reviewer by measured headroom, clear each worker's context and send a fresh role brief, wait on the report file plus its REPORT: marker, and hand the merge to release; a non-rotating judge seat on the most capable model, dispatched from its own balancer config, adjudicates contested reviewer or tester verdicts, report VERDICT: lines the classifier gate contradicts, bot disagreements, and weighing nominations, and diagnoses fix loops that exhaust their allowance, on the investigator's assessment
stop-handoff-hygiene hook — a Stop hook (Claude Code + Codex) that blocks the handoff once (loop-safe via stop_hook_active) when prune-worktrees.sh --dry-run would remove leftover worktrees or local branches, or on diagnostics findings in the changed set; a dirty working tree is reported, not blocked
check-acr-latest hook — the ACR counterpart of check-tessl-latest: runs acr freshness run --policy install in a project with agents.yaml, so ACR dependencies at latest update at session start instead of being reported as behind. Never blocks
check-tessl-latest hook — runs tessl update every session and reports each jbaruch/* dependency's version, flagging one pinned instead of latest (rules/dependency-management.md). Never blocks
session-start hook — the plugin's one SessionStart entry, native for Claude Code and Codex and portable for other agents: runs every SessionStart hook and merges their statuses into one payload
check-git-sync hook — fetches origin every session and fast-forwards a local default branch strictly behind origin/<default> (rules/sync-before-work.md). Diverged and Herdr-worker sessions are reported only. Never blocks
Policy review runs on the OpenAI Codex CLI authenticated by a ChatGPT subscription (no API key) via .github/workflows/review-codex.yml, reviewing every PR against the in-tree rules/*.md; Copilot stays as the complementary code-quality lane
26 rules — 20 always-on, 6 conditional (scoped via applyTo: to the files where the rule's prescriptions actually fire). Breakdown: 10 covering code quality, 7 covering plugin authoring, 1 covering concurrency, 1 covering review discipline, 1 covering reviewer-feedback reading, 1 covering review severity, 1 covering external-repo action scope, 1 covering response communication, 1 covering merge/ship autonomy, 1 covering hook-status reporting, 1 covering multi-agent team operation
release skill — structured PR + merge workflow gated on the Codex policy review's blocking findings; Copilot is the complementary code-quality lane and is always advisory
onboard-repo skill (renamed from install-reviewer) — bootstrap a consumer repo onto coding-policy: enroll it in the central fleet policy reviewer, pin its jbaruch/* tessl deps to latest, and add the tessl-generated-artifacts .gitignore block so agents never commit per-developer output
adopt-fork-pr skill — bring a fork PR's branch into the base repo as a same-repo PR the reviewer can run on
0.3.0 added onboard-repo upgrade mode (--override) — refreshes the reviewer artifacts in place instead of requiring a manual git rm-and-rerun
Language-agnostic: works with any stack, no Python/JS assumptions

See CHANGELOG.md for full version history.

Installation

tessl install jbaruch/coding-policy

What's Included

Category	Rule	Summary
Git	commit-conventions	Imperative mood, one change per commit, PR hygiene
Git	sync-before-work	Fetch and sync the local checkout to the remote default before reading, planning, or editing; branch from the fresh default
Testing	testing-standards	Outcome-based, deterministic, no binary fixtures
Errors	error-handling	Specific exceptions (with outer-boundary process-contract carve-out), actionable messages, structured logging
Deps	dependency-management	Stdlib-first, pinned versions kept fresh via a renewal mechanism, lock files
Files	file-hygiene	Proper .gitignore, no generated files committed
CI	ci-safety	Never skip tests, never modify CI without asking
Secrets	no-secrets	No credentials in code, env vars or secrets manager
Style	code-formatting	Use project's formatter, don't mix style with logic
Types	language-diagnostics	Enable the project's language server; its findings are non-dismissible without cause; gate the headless checker in CI at zero findings
Authoring	context-artifacts	Plugin structure, rule format, review iteration, surface sync, consistency checks
Authoring	context-writing-style	Prose discipline for rules, skills, and READMEs — what to cut, what to keep, structural format. CHANGELOG entries follow looser archive discipline
Authoring	rule-frontmatter	Frontmatter conventions for rule files — passthrough model, per-agent field map, when to path-scope
Authoring	skill-authoring	SKILL.md structure, step numbering, typed calls, plugin.json reference
Authoring	script-delegation	Deterministic → script, a fixed answer set read by meaning → bounded classification, everything else → LLM, the regex trap. A classification label may add a reversible gate, never remove one. Carve-outs for scripts whose stdout is a path, a version, or a wrapped command's own output (`bounded-run.sh`)
Authoring	script-as-black-box	Skills reference the script's contract (inputs/outputs/exit codes), not its internal logic — thresholds and predicates live in the script
Authoring	stateful-artifacts	Cross-invocation state: schema, owner skill, schema_version, hints-not-authority, migration
Review	reviewer-feedback-reading	A review's state classifies merge-gating, not whether its body must be read; read every reviewer's body before declaring merge-ready, COMMENTED-with-zero-inline included
Review	review-severity	Findings carry a severity — blocking (correctness, security, contract) gates the merge; advisory (prose, style, Copilot) never does; read all, act by severity, never burn a round on a lone advisory
Concurrency	agent-worktree-isolation	Mandatory git worktrees for concurrent agent work; cleanup; read-only exception
Teamwork	agent-team-operation	Standalone versus Herdr team round; a team round follows team-operation as a must-read — flexible multi-agent teams: capability and contribution based staffing, an on-demand specialist bench, YOLO workers within classified assignments, one writer per worktree, report files as the worker channel, persistent task acceptance ledger, saved daily and pre-transition retrospectives, internal review before the PR opens
Discipline	boy-scout	Leave it better than you found it; "pre-existing" is not a valid concept; in-scope cleanups bundle, out-of-scope ones get filed
Scope	external-repo-contributions	Default deny on issues, PRs, comments, reactions, and discussions in repos the operator does not own; explicit permission required per repo and action type
Communication	response-clarity	Shape responses action-first: lead with the command, number steps, show progress, plain errors, one concrete next step, no preamble or closers (exceptions for explanations, destructive actions, debug, ambiguity)
Discipline	ship-on-green	Green gate is the approval — merge, never ask; asking in a costume (flag/confirm/"say go") is deciding not to ship; stakes raise care not permission; three objective exits only — Red / No undo / Murky
Automation	hook-action-reporting	Relay any `Session-start status —` hook payloads to the user once at session start, then act on any action they name (a SessionStart hook's output reaches the model, not the transcript)

Skills

Skill	Description
release	PR creation, Codex (subscription-CLI) policy review + Copilot code-quality review, merge + cleanup workflow
onboard-repo	Bootstrap a consumer repo onto coding-policy, then open a PR. Scaffolds the fleet reviewer (`.github/fleet-review-enabled` marker, a thin `.github/workflows/review-trigger.yml` that fires an immediate PR-time review in `coding-policy`, `.github/copilot-instructions.md`); pins `jbaruch/*` tessl deps to `latest` (third-party pins left as-is); and adds the tessl-generated-artifacts `.gitignore` block (keeping `AGENTS.md`/`CLAUDE.md`/`GEMINI.md` committed). The `coding-policy-fleet-reviewer` GitHub App reviews against the `jbaruch/coding-policy` rules with the Codex CLI (no API key); the Codex credential lives only in `coding-policy`; the consumer sets one `FLEET_DISPATCH_TOKEN` PAT. Supports `--override` for in-place upgrades.
adopt-fork-pr	Classify a PR by number. Same-repo PRs pass through to the reviewer; fork PRs get adopted into the base repo as a same-repo PR, preserving the contributor's commits.
migrate-to-plugin	Migrate a legacy `tile.json` plugin to the `.tessl-plugin/plugin.json` form: runs `tessl plugin migrate`, renames `.tileignore`, removes the obsolete `tile.json`, re-lints, then reconciles residual "tile" wording to "plugin" while preserving contract surfaces.
herdr-foreman	Run coding rounds in Herdr as a nonworking foreman that assigns, supervises and accepts work but never does it: measure headroom, select capable independent workers, compose briefs, provision worktrees, sweep spent worktrees across every repository with a worktree directory under `~/.worktrees`, and dispatch workers in verified YOLO mode. Consult UX, accessibility, investigation, architecture, security, performance and documentation specialists as needed. Save their assessed contributions and retain eligible same-task consultations. Track evidence-backed acceptance in a persistent task ledger independently of Herdr status. Save retrospectives daily during active work and before worker transitions; retrieve them later without a live team. Preserve scoped lessons, foreman handoffs, and pending user attention. Observe every enrolled worker through durable events and an exact-session Stop backstop. Model tiers use verified relaunches and measured or unknown billing windows. A pinned judge rules on disputes and diagnoses an exhausted fix loop into a bounded remedy. Composition triggers are detected from the round's diff against the repo's own declaration. Delivered reports are classified by atomic questions through Jev, with no fallback classifier; a confident label adds a block or re-read gate, cleared only by evidence the ledger already records, never an approval.
herdr-standup	Hold a daily standup with the named Herdr agents: ask each idle worker for four lines (DONE / PLAN / BLOCKED / REPORT), never interrupt a working one, fill its row from the round log instead, show unresolved user attention first, then render a banner-topped fixed-width table the operator can find while scrolling back — plus a Markdown record under the round's reports directory.

Hooks

Hook	Event	Description
session-start	SessionStart (native: Claude Code + Codex; portable: other agents)	The plugin's only SessionStart entry. Native for Claude Code and Codex, so it keeps the session's environment; the portable entry serves other agents and exits under a native one, so each session runs it once. Runs the six hooks below in order and merges their statuses into one payload. A failed hook is reported as its own status line. Never blocks.
check-git-sync	SessionStart (via session-start)	Fetches origin every session (a `SYNC_THROTTLE_HOURS` window is optional) and fast-forwards a local default branch strictly behind `origin/<default>`; git refuses a non-fast-forward or an overwrite of local changes, and the refusal is reported. Repo hooks do not run. Diverged and Herdr-worker sessions are reported only. Never blocks.
check-tessl-latest	SessionStart (via session-start)	Runs `tessl update --yes` and reports every `jbaruch/*` dependency's version, flagging one pinned instead of `latest` (`rules/dependency-management.md`). Third-party pins are out of scope. Never blocks.
check-acr-latest	SessionStart (via session-start)	In a project with `agents.yaml`, runs `acr freshness run --policy install` once the checkout is freshly fetched, contains origin's default branch, and has a clean tree: reconciles ACR dependencies declared `latest`, realizes changed files, and reports ACR's output (a `restart_required` notice included). An unsafe checkout gets a "not updated" status naming why, and nothing changes. Pinned tags and commits never move; `agents.yaml` is not rewritten. An `acr` older than `ACR_MIN_VERSION` (top of the script) is reported, not run. It is the deterministic check for the Runtime-Managed Manifest Carve-Out's consumer `agents.yaml` (`rules/dependency-management.md`): it names `github:jbaruch/*` dependencies not at `latest` and refuses to update while `.agents/registry.lock` is committed or not gitignored. In a Herdr session, and under tessl for other agents, it reports the check's findings but never updates. Silent without `agents.yaml`. Never blocks.
check-leftover-worktrees	SessionStart (via session-start)	Cleans the session's own repository through its owner scripts, `skills/herdr-foreman/prune-worktrees.sh` and `skills/herdr-foreman/prune-remote-branches.sh`. Idle clean worktrees origin holds, local branches origin holds or merged, and unprotected merged branches on origin with no open pull request go silently. Lists only what the operator must decide: idle dirty or unpushed worktrees, unpushed local branches, stale unmerged branches on origin with no pull request. A failed, timed-out or tool-less check is one "could not check" line. Deletes nothing in a Herdr worker session. Under tessl a main checkout only reports, from a dry run, and a linked worktree is skipped. Runs under `skills/herdr-foreman/bounded-run.sh` and never blocks.
check-report-caches	SessionStart (via session-start)	Removes regenerable build and package caches from idle Herdr reports directories through its owner script, `skills/herdr-foreman/prune-report-caches.py` (discovery from the foreman ledger, idleness and cache signatures in its top-of-file docstring). Removes only a directory matching an enumerated cache kind by name, signature and top-level entries, whole; every other file and directory stays. Reports the reclaimed size; a failed removal, an unreadable ledger or a spent budget is its own status line. Runs nothing in a Herdr session. Under tessl it only reports, from a dry run, and a linked worktree is skipped. Runs under `skills/herdr-foreman/bounded-run.sh` and never blocks.
herdr-supervision-stop	Stop (Claude Code + Codex)	Gates the exact bound Herdr foreman while assignments or unhandled events remain. A saved pause or handoff covers every active assignment. Reads local state only; workers and unrelated sessions are unaffected.
stop-handoff-hygiene	Stop (Claude Code + Codex)	Blocks the handoff once (loop-safe via `stop_hook_active`) on worktrees and local branches `skills/herdr-foreman/prune-worktrees.sh --dry-run` would remove (naming the command that removes them), or diagnostics findings in the changed set (uncommitted `.sh`/`.py`, linted with shellcheck/pyright). Dirty or unpushed idle worktrees and a dirty working tree are reported, not blocked. Fail-open.
herdr-team-status	SessionStart (via session-start)	Names the live Herdr team: each named worker, its kind, and its lifecycle state. Silent outside Herdr and when no other named worker is live. Informative only, never blocks.

Philosophy

Language-agnostic code rules. The code quality rules (commits through formatting) apply to Python, TypeScript, Go, Rust, Java — any language. No framework-specific assumptions.
Tessl-specific authoring rules. The Authoring-category rules in the table above are specific to the Tessl plugin workflow. They codify how to build, test, and ship plugins.
One concern per rule. Each file covers one topic. Easy to read, easy to reference, easy to override if a project needs an exception.
Opinionated but practical. These rules reflect real patterns found across 17+ repositories and the Tessl plugin authoring workflow. They solve problems that actually come up when agents write and ship code.
Loaded by default; scoped by intent. Universal rules are alwaysApply: true. Rules whose prescriptions only fire in specific files are alwaysApply: false with applyTo: declaring the scope — the agent's model reads the frontmatter and narrows when to act. See rules/rule-frontmatter.md.

.tessl-plugin

hooks

skills

README.md

tile.json