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
73
91%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
View guide
Low
Low-risk findings worth noting
gamussa/coding-policy
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-policyTo 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 declareapplyTo: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 structureThe 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.
- Workspace
- gamussa
- Visibility
- Public
- Created
- Last updated
- Repository
- https://github.com/gAmUssA/coding-policy
- Publish Source
- CLI
- Badge