gamussa/coding-policy

Coding policy for Viktor Gamov's AI agents: language-agnostic quality rules, autonomous shipping discipline, and stack defaults for JVM, Swift, TypeScript, and Python

Quality

91%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

gamussa/coding-policy

Name: gamussa/coding-policy
Rating: 73.4 (1 reviews)
Author: gamussa

Coding policy plugin for Viktor Gamov's AI agents. Language-agnostic code quality rules, autonomous shipping discipline, stack defaults for JVM, Swift, TypeScript, and Python, plus the hooks, reviewer, and release workflow that enforce them.

A fork-in-spirit of jbaruch/coding-policy: the code rules, the ship-on-green stance, the session hooks, the Codex policy reviewer, and the Herdr multi-agent team layer are ported; the fleet reviewer App and the auto-bump publishing pipeline are not. See CHANGELOG.md for what was kept, dropped, and added.

Installation

Tessl

tessl install gamussa/coding-policy

To wire a repository fully (plugin at latest, per-repo Codex policy reviewer, Copilot lane, .tessl/ hygiene), run the onboard-repo skill from that repository. See docs/consumer-setup.md.

Codex personal marketplace

Use the plugin-creator skill to register this repository as gamussa-coding-policy in your personal marketplace and install it. Preserve existing marketplace entries and source files. The Codex manifest is .codex-plugin/plugin.json.

Review the plugin hooks with /hooks in Codex, then start a new thread. Choose Tessl or the Codex plugin for a given Codex environment; enabling both runs both sets of hooks. See docs/codex-setup.md for installation, path handling, updates, and verification.

What's Included

Rules

Category	Rule	Summary
Git	commit-conventions	Imperative mood, one change per commit, PR hygiene, no AI attribution trailers
Git	sync-before-work	Fetch and sync the local checkout to the remote default before reading, planning, or editing
Testing	testing-standards	Outcome-based, deterministic, no binary fixtures; per-stack test conventions
Errors	error-handling	Specific exceptions, shell `set -euo pipefail`, actionable messages, structured logging
Deps	dependency-management	Stdlib first, uv for Python execution, documented bootstrap/hook exceptions, pinned versions, lock files, no vendoring
Files	file-hygiene	Proper `.gitignore`, no generated files, entry-point guards, idempotent scripts
CI	ci-safety	Never skip tests, never smuggle CI edits, always watch CI to a terminal state
Secrets	no-secrets	No credentials in code; env vars or a secrets manager; `.env.example`
Style	code-formatting	Use the project's formatter; stack defaults when none exists; no style-plus-logic commits
Types	language-diagnostics	Enable the language engine, never silence a finding without cause, gate CI at zero
Discipline	boy-scout	Leave it better than you found it; "pre-existing" is not a concept
Discipline	ship-on-green	Green gate is the approval; asking is deciding not to ship; three objective exits only
Discipline	verify-before-done	"Done" means a shown passing run; "should work" is not a state
Discipline	environment-changes	State a machine-level install or a new dependency before making it
Communication	response-clarity	Action first, numbered steps, plain errors, one next step, no preamble
Concurrency	agent-worktree-isolation	Git worktrees for concurrent agent work; cleanup; read-only exception
Teamwork	agent-team-operation	Herdr teams: capability and contribution based staffing, an on-demand specialist bench with diff-detected triggers, YOLO workers within classified assignments, one writer per worktree, report files as the worker channel, task ledger, a judge that adjudicates disputes and diagnoses exhausted fix loops, stall detection, review partitions, retrospectives, internal review before the PR opens
Review	review-severity	Blocking gates the merge, advisory never does; Copilot is always advisory
Review	reviewer-feedback-reading	Read every reviewer's body before declaring merge-ready, `COMMENTED` included
Scope	external-repo-contributions	Default deny on issues, PRs, comments, and reactions in repos the operator does not own
Automation	hook-action-reporting	Relay `Session-start status —` hook payloads once, then act on what they name
Demos	demo-readiness	Talk and workshop repos run from a fresh clone with one command and a documented reset
Tracking	work-tracking	In a repo with `.beans.yml`, every task is a bean: found or created before the work, checked off during it, completed with a summary, committed with the code
Scope	cross-boundary-changes	Map producer, consumers, contract, and verification per boundary before editing; decompose a multi-component task and build one component at a time; staged migrations
Docs	architecture-decisions	An architecture-altering change ships an ADR in `docs/adr/` in the same PR; records are immutable and superseded, never rewritten
Authoring	script-delegation	Deterministic work goes in scripts, reasoning stays in the LLM; skills cite a script's contract
Authoring	skill-authoring	`SKILL.md` structure, flat step numbering, typed `Skill()` calls, manifest reference
Authoring	context-artifacts	Plugin structure, rule format and frontmatter, writing style, surface sync, manual versioning
Authoring	stateful-artifacts	Cross-invocation state: schema, owner skill, `schema_version`, hints-not-authority, migration

Skills

Skill	Description
release	Ship a branch: readiness checks, PR, Codex policy review plus advisory Copilot review, watch to a verdict, address feedback, merge on green, cleanup, and publish confirmation for plugin repos.
onboard-repo	Bootstrap a consumer repo: install the plugin at `latest`, gitignore `.tessl/`, scaffold the per-repo Codex reviewer workflow and Copilot instructions, set `CODEX_AUTH_JSON`, open the PR.
herdr-teamlead	Lead coding rounds in Herdr: measure headroom, select capable independent workers, compose briefs, provision worktrees, dispatch workers in verified YOLO mode, observe the fleet, and gate release on their reports. Consult UX, accessibility, investigation, architecture, security, performance and documentation specialists when the round's diff trips a trigger declared in `.herdr/triggers.json`. A persistent task ledger tracks acceptance independently of Herdr status; retrospectives, lead handoffs, and an attention queue survive worker transitions and lead resets. A pinned judge adjudicates disputes and diagnoses an exhausted fix loop into a bounded remedy; stalled workers and spent worktrees are detected from evidence and pruned.
herdr-standup	Daily standup with the named Herdr agents: ask each idle worker for DONE / PLAN / BLOCKED / REPORT, never interrupt a working one, show unresolved user attention first, then render a fixed-width table plus a Markdown record.

Hooks

Hook	Event	Description
check-policy-freshness	SessionStart	Warns (throttled once a day) when installed Tessl plugins are behind the registry. Informative only.
check-git-sync	SessionStart	Fetches origin (throttled once an hour per repo) and warns when the local default branch is behind or diverged. Informative only.
check-tessl-latest	SessionStart	Warns when `tessl.json` pins a `gamussa/*` dependency instead of `latest`. Informative only.
beans-prime	SessionStart	In a repo with `.beans.yml`, loads the `beans prime` usage guide as context; warns when the CLI is missing. Silent elsewhere. Informative only.
herdr-team-status	SessionStart	Names the live Herdr team: each named worker, its kind, and its lifecycle state. Silent outside Herdr. Informative only.
stop-handoff-hygiene	Stop (Claude Code + Codex)	Blocks the handoff once on leftover merged branches, spent worktrees (clean and holding nothing the default branch lacks, pushed or not), or shellcheck/pyright findings in the changed set (venv-aware). Dirty, unmerged, locked, and detached worktrees and a dirty tree are reported, not blocked.
herdr-supervision-stop	Stop (Claude Code + Codex)	Gates the exact bound Herdr lead while assignments or unhandled events remain; a saved pause or handoff covering every active assignment releases it. Reads local state only.
codex-session-start	SessionStart (Codex plugin)	Identifies rule paths and scopes, maps co-shipped script paths, and translates every Tessl-declared SessionStart hook into native Codex context. Registered in hooks/hooks.json.

Philosophy

Language-agnostic rules, stack-aware defaults. The rules apply to any language. Where a tool choice matters (test runner, formatter, diagnostics engine), the rule names a default per stack and defers to whatever the project already uses.
Autonomous by default. Green required checks are the approval. The agent merges, cleans up, and reports; it asks only on Red, No-undo, or Murky.
Proof over claims. A task is done when the run is shown. Hooks and CI mechanize the rules that agents forget: sync at session start, hygiene at handoff, policy review on every PR.
One concern per rule. Each file covers one topic so it can be read, cited, and overridden on its own.
Deterministic things are scripts. Anything with fixed inputs and outputs is a tested script the skill calls; the LLM keeps the judgment calls.
Loaded by default, scoped by intent. Universal rules are alwaysApply: true; rules that only fire in specific files declare applyTo: so the agent narrows when to act.

Development

Python tooling requires Python 3.11+ and uv. The Python suites use the standard library; no dependency lock file is needed for these commands.

bash scripts/run-diagnostics.sh   # shellcheck + pyright at zero findings
uv run --no-project --no-python-downloads --python '>=3.11' bash scripts/run-tests.sh
tessl plugin lint                 # manifest and structure

The direct-Python exception covers hooks/hooks.json invoking hooks/codex-session-start.py and hooks/herdr-supervision-stop.sh invoking teamlead.supervision_hook. These standard-library-only runtime hooks run in consumer sessions before developer tooling is available. They use an existing Python 3.11+ interpreter; hook execution must not install tools or download Python.

Remaining entry-point migration: .github/workflows/tests.yml, .github/workflows/publish.yml, skills/herdr-teamlead/teamlead.sh, and skills/herdr-teamlead/prune-worktrees.sh. Migrate each when its execution path is next changed, under rules/dependency-management.md Python Execution.

Every PR that changes shipped content bumps version in .tessl-plugin/plugin.json and adds a ## <version> — <date> heading to CHANGELOG.md; scripts/check-version-bump.sh enforces it in CI. Merging to main publishes that version.

.tessl-plugin

hooks

skills

README.md

tile.json