jbaruch/coding-policy

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

• 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
• 23 rules — 17 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
• 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
• install-reviewer skill — enroll a consumer repo in the central fleet policy reviewer (the .github/fleet-review-enabled marker + the Copilot lane); no per-repo workflow or secrets
• 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 install-reviewer 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, reasoning → LLM, the regex trap
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
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)

Skills

Skill	Description
release	PR creation, Codex (subscription-CLI) policy review + Copilot code-quality review, merge + cleanup workflow
install-reviewer	Enroll a consumer repo in the central fleet policy reviewer — scaffold the .github/fleet-review-enabled marker, a thin .github/workflows/review-trigger.yml (fires an immediate PR-time review in coding-policy), and .github/copilot-instructions.md, then open a PR. The coding-policy-fleet-reviewer GitHub App reviews against the jbaruch/coding-policy rules with the Codex CLI on a ChatGPT subscription (no API key). The Codex credential lives only in coding-policy; the consumer sets one stable FLEET_DISPATCH_TOKEN (a narrow 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.

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.