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

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
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). A diverged branch is 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; Claude 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 design simplicity
release skill — structured PR + merge workflow with separate Codex policy and Claude code-quality reviews; blocking findings from either hold the merge
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

Compact rule routers retain startup boundaries and require their complete coding contracts before the affected action. References load through explicit reads; conditional frontmatter does not reduce Tessl imports. Combined native-session acceptance lives in the acceptance record.

Category	Rule	Summary
Git	commit-conventions	Imperative mood, one change per commit, PR hygiene
Git	sync-before-work	Fetch and branch from the fresh remote 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. PR descriptions carry the archive
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, fixed answers read by meaning → bounded classification, everything else → LLM. Standing operator approval permits direct routing within recorded question, model, score and action bounds. Script stdout carve-outs for paths, versions and wrapped commands
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, owning skill/runtime/service, schema_version, reader contracts and migrations; runtime-owned tables use their migration schema
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	Separate demonstrated defects, binding policy mismatches and optional hardening; require evidence for blockers; resolve mismatches through compliant code or authorized policy amendments
Design and review	simplicity	KISS and YAGNI — build only what today's problem needs; overengineering is forbidden, and machinery without a current caller or observed failure is a review finding; calibrate reviewers with matched inputs and useful outcomes
Concurrency	agent-worktree-isolation	Mandatory git worktrees for concurrent agent work; cleanup; read-only exception
Discipline	boy-scout	Fix coherent in-scope defects; record unrelated blocking risks once; advisories and maintenance create no delivery obligation
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
coding-contracts	Binding policy detail loaded before the action named by each rule router; ordinary startup loads the compact boundaries.
release	PR creation or explicit source-verified existing-PR resumption, Codex policy review + Claude code-quality review, merge + publication confirmation and cleanup
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 immediate Codex policy and Claude quality reviews in `coding-policy`); 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 policy with Codex; the separate `jbaruch-claude-reviewer` App reviews code quality with Claude; both subscription credentials live 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.

On-demand review calibration compares a small fixed PR sample with the same role, instructions and source packet for both models. Assess useful defects, unsupported blockers, unnecessary work and observed rounds. The ordinary Codex-policy and Claude-quality lanes have different contexts and do not establish a matched model comparison.

Central fleet publication

The opt-in central publisher contract keeps Tessl and App credentials in coding-policy. Reviewed consumer enrollment selects a data-only package; source-bound intent, claim and receipt readers retain each publication and its moderation result. Activation stays disabled until the App permissions and consumer publication handoff are verified. The same owner can retain a separately typed later source proof for a verified historical publication whose original receipt bytes are unavailable; this explicit recovery never reconstructs a receipt or republishes. Compatible readers must be installed before proof creation.

The scheduled backstop runs every 15 minutes and examines at most two enrolled consumers per tick. One poll has a shared 200-request central API budget, including native context, paginated artifact reads and up to two dispatches. App-scoped repository discovery and consumer reads use the installation's separate quota and their existing pagination and per-command bounds; they are not charged to the central-token budget. Budget-deferred consumers remain explicit; they are never treated as absent or successfully published. The poll caches only immutable Git objects and comparisons for its own lifetime; native refs, runs, jobs, artifacts, reviews and publication gates stay fresh. The verified native scheduled run creation time selects a UTC quarter-hour slot; child dispatch counts do not change rotation. At 24 stable enrollments and an uninterrupted fifteen-minute schedule, every consumer receives a first proof slot within 24 ticks (six hours); a second slot can complete earlier. Missed or delayed cron runs can defer that coverage. This is backstop latency, not a fifteen-minute consumer delivery guarantee. Explicit selected dispatch remains independent and must pass the full current source, claim and publication checks.

Hooks

The release skill owns the 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 four 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 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. A diverged branch is 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. Silent without `agents.yaml`. Never blocks.
check-leftover-worktrees	SessionStart (via session-start)	Cleans the session's own repository through its owner scripts, `skills/release/lib/prune-worktrees.sh` and `skills/release/lib/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. Runs under `skills/release/lib/bounded-run.sh` and never blocks.
stop-handoff-hygiene	Stop (Claude Code + Codex)	Blocks the handoff once (loop-safe via `stop_hook_active`) on worktrees and local branches `skills/release/lib/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.
session-end-cleanup	SessionEnd (Claude Code + Codex), sessionEnd (Cursor)	Removes the ending session's opt-in `.coding-policy-disposable` scratchpad folder. See file-hygiene and the script's docstring for the cleanup contract.

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.

ACR distribution

The retained general rules, skills and hooks are declared in agent-plugin.yaml at the same explicit version as the Tessl manifest. Install with acr install github:jbaruch/coding-policy@latest, then acr realize.

The serialized publish workflow preserves the manifest version, confirms Tessl availability, then publishes the immutable ACR tag and release asset in a dependent job. Retry a failed ACR job on the same run with gh run rerun <run-id> --failed; keep the original successful Tessl job and registry baseline. A partial publication is reconciled at the same version and commit; never move an existing tag or infer one channel's success from the other. Subsequent releases must update both manifest versions together. Enrolling another plugin repository on the reusable publish pipeline is a maintainer step documented in docs/fleet-publish-setup.md.

.tessl-plugin

skills

README.md

tile.json