developer-standards

Shared standards so AI coding agents follow the same Make, Dockerfile, Compose, CI, and Go-module dialect.

This repo ships skills (agent workflows), activation rules (when to load them), validators, and templates. App repos keep their own checked-in Makefile / Dockerfile / Compose / workflows / Go modules. They do not depend on this repo at runtime.

developer-standards
        │
        ├── makefile-standard  (+ rules, validator, templates)
        ├── dockerfile-standard (+ rules, validators, profiles, templates)
        ├── compose-standard (+ rules, validator, templates)
        ├── ci-standard (+ rules, validator, GHA templates)
        └── go-project-standard (+ rules, validator, golangci + layout templates)
   your app Makefiles / Dockerfiles / Compose / workflows / Go modules stay self-contained

Why you need the skills

makefile-standard coaches Makefile naming and shape. Not a maximal generator.

Problem	What the skill does
Repos name the same job differently	Canonical names: `test`, `lint`, `check`, `deploy`, `prod-backup`, …
Agents pad Makefiles with unused targets	Add only evidenced/requested ops — catalog is vocabulary, not a todo list
Local vs production ops look the same	Production → always `prod-*`; ship-from-local → `deploy` (not `prod-deploy`)
Broken / inconsistent shape	`##` help text, `.PHONY`, kebab-case; `validate_makefile.py` checks

dockerfile-standard creates, reviews, migrates, and validates Dockerfiles and image build artifacts. Adapts to the project (Go, Node, static, CLI, …).

Problem	What the skill does
Floating `latest` / secrets in `ARG`	MUST rules + static validator
Fat single-stage images	Multi-stage + profile guidance; measure before/after
Cache thrash	Ordered COPY + BuildKit cache mounts
Root-by-default runtime	Non-root USER + `validate_image.sh` structure checks

compose-standard creates/reviews lean local Compose files. Not a platform generator.

Problem	What the skill does
Secrets / `:latest` in Compose	MUST rules + `validate_compose.py`
Startup races	healthcheck + `depends_on: condition: service_healthy`
Overbuilt networks/sidecars	Add only evidenced services; default network OK
Wrong ownership vs Make/Dockerfile	Boundaries with makefile-standard / dockerfile-standard

ci-standard creates/reviews lean GitHub Actions that call project Make targets. GHA-only (v1).

Problem	What the skill does
Parallel CI scripts beside Make	Wire to `make check` / `make ci`
No concurrency / over-broad permissions	Concurrency groups + least-privilege defaults
Floating action branches / missed caches	Pin actions; cache when install is non-trivial
Unsolicited deploy-from-CI	Image/deploy only when evidenced

go-project-standard reviews/shapes Go modules (library / service / cli). Not a full project scaffolder.

Problem	What the skill does
Empty `pkg/` / project-layout cargo-cult	Flat start; `cmd/` + `internal/` when evidenced
Weak or v1-only lint	golangci-lint v2 template + curated enables
Missing tests / hard coverage % gates	Soft coach: logic packages get tests; no % ERROR
Tools via blank-import `tools.go` on Go 1.24+	Prefer `tool` directive

Flow agents follow:

Makefile: Need exists? → look up canonical name → add/rename → validate
Dockerfile: Inspect repo → profile/base → write/migrate → validate Dockerfile → validate image → report
Compose: Inspect needs → smallest services → write/migrate → validate → report
CI: Inspect Makefile → wire GHA to make check/ci → concurrency/cache/permissions → validate
Go: Detect profile → layout + golangci + tests → YAGNI → validate → report

Install once (symlink or marketplace plugin). Cursor/Codex rules auto-trigger skills when you touch Makefiles, Dockerfiles, Compose, GitHub Actions, or Go modules. Claude discovers skills via descriptions.

What ships today

Piece	Role
Skill `makefile-standard`	Makefile naming + shape
Skill `dockerfile-standard`	Dockerfile / image construction
Skill `compose-standard`	Local Compose topology
Skill `ci-standard`	GitHub Actions → Make (`check` / `ci`)
Skill `go-project-standard`	Go module layout, golangci-lint v2, test conventions
Validators	`validate_makefile.py`, `validate_dockerfile.py`, `validate_image.sh`, `validate_compose.py`, `validate_workflow.py`, `validate_go_project.py`
Global rules	Short triggers: when to load each skill
Catalogs	`targets.yaml`, Dockerfile/Compose/Go `rules.yaml`, CI rule table in `ci-standard.md`

Planned later: deployment-standard and similar.

Makefile naming (quick)

Always: help (default goal).
Usual core: fmt-check, lint, test, check, build, clean.
Where it acts: local → plain name; production → prod-* (e.g. prod-backup); ship code from this machine → deploy.
Add when evidenced: compose (up/down/logs), deploy (ENV=), prod ops, db (db-migrate/…), multi-component (backend-*/…).

Full vocabulary: skills/makefile-standard/references/targets.yaml. Profiles cheat sheet: profiles.md.

Exceptions in the project Makefile:

# makefile-standard: except <target> — reason here

Dockerfile standard (quick)

Always: stable # syntax=docker/dockerfile:1; versioned trusted bases; secrets via BuildKit mounts; absolute WORKDIR; exec-form ENTRYPOINT/CMD; final non-root USER (unless excepted); appropriate .dockerignore.

Adapt: runtime base (scratch/distroless/Alpine/slim), HEALTHCHECK, multi-platform, CGO — from repo evidence, not checklists.

Full rules: skills/dockerfile-standard/references/dockerfile-standard.md. Catalog: rules.yaml.

# dockerfile-standard: except <rule-id> — reason here

Compose standard (quick)

Always (local stacks): prefer compose.yaml; no obsolete top-level version:; no secret literals in the file (${VAR} / env_file); pin third-party image: tags (not :latest); project app uses build: (Dockerfile → dockerfile-standard).

Adapt: healthcheck + depends_on: condition: service_healthy when startup order matters; named volumes for data, bind mounts for hot-reload code; custom networks/profiles only when evidenced.

Full rules: skills/compose-standard/references/compose-standard.md. Catalog: rules.yaml. Make wrappers (up/down/logs) stay in makefile-standard.

# compose-standard: except <rule-id> — reason here

CI standard (quick)

Always: primary job runs make check (or evidenced make ci); concurrency with cancel-in-progress on PR; top-level permissions: contents: read unless a step needs more; pin Actions (no @main / @master).

Adapt: toolchain cache, path filters, image build after check — only when evidenced. No prod deploy from CI unless evidenced + excepted.

Full rules: skills/ci-standard/references/ci-standard.md. Make target names stay in makefile-standard.

# ci-standard: except <rule-id> — reason here

Go project standard (quick)

Always: valid go.mod; .golangci.yml with version: "2"; default: standard + curated enables (not default: all); no empty cargo-cult pkg/; multi-package binaries use thin cmd/<name>/.

Adapt: library / service / cli profiles; internal/ for private multi-pkg code; soft test coach (table-driven, no hard coverage % gate); Go ≥1.24 tool over tools.go.

Full rules: skills/go-project-standard/references/go-project-standard.md. Catalog: rules.yaml. Profiles: profiles.md. Make/CI/images stay in sibling skills.

# go-project-standard: except <rule-id> — reason here

Installation

Current version: see root VERSION. Plugin id: developer-standards. Skills: makefile-standard, dockerfile-standard, compose-standard, ci-standard, go-project-standard.

Install matrix

Method	Cursor	Codex / ChatGPT	Claude Code	OpenCode
Local symlink `./install.sh`	yes (skills + `~/.cursor/rules`)	yes (`~/.agents/skills` + `~/.codex/skills` + AGENTS markers)	skill only via `~/.agents/skills` (same link); prefer plugin for marketplace updates	yes (`~/.agents/skills`, auto-discovered)
Official / public marketplace	after publish (Cursor Marketplace)	after publish / workspace marketplace	after community catalog approval	n/a — no skills marketplace (OpenCode plugins are code modules)
Git / self-marketplace	`.cursor-plugin/marketplace.json` → `./plugins/developer-standards`	`.agents/plugins/marketplace.json`	`/plugin marketplace add` this repo	n/a
Updates	marketplace update, or `git pull` + `./update.sh`	plugin update, or `./update.sh`	`/plugin marketplace update`, or bump + reinstall	`git pull` + `./update.sh`
Uninstall	Marketplace UI uninstall; or `./uninstall.sh` if local	Plugins UI remove/disable; `./uninstall.sh` clears AGENTS markers from local install	`/plugin uninstall developer-standards@…`; `./uninstall.sh` if you used local skills link	`./uninstall.sh` (removes the `~/.agents/skills` links)

What each path installs

Path	Skills	Activation rules
`./install.sh`	all skills → Codex + agents + Cursor	Cursor `.mdc` rules + Codex AGENTS markers
Cursor plugin	via `./skills`	always-apply rules from plugin
Codex plugin	via `./skills`	no AGENTS marker — use `./install.sh` or paste `integrations/codex/*`
Claude plugin	repo-root `skills/`	skill descriptions; no separate Claude rule in v1
OpenCode (via `./install.sh`)	all skills via `~/.agents/skills`	none needed — `SKILL.md` descriptions trigger; restart session after updates

Local symlink (`./install.sh`)

Works from any checkout path (do not hard-code a home directory):

git clone https://github.com/painhardcore/developer-standards.git
cd developer-standards
./install.sh

What it does:

Symlinks each skill under skills/ → ~/.codex/skills/, ~/.agents/skills/ (also read by OpenCode), ~/.cursor/skills/
Symlinks each rules/*.mdc → ~/.cursor/rules/
Upserts managed marker blocks in ~/.codex/AGENTS.md (backs up first)
Prints optional Cursor User Rules paste text

Safe to re-run. Refuses to overwrite an unrelated real skill directory unless INSTALL_FORCE=1.

Uninstall

Local symlink install

cd /path/to/developer-standards
./uninstall.sh

Removes only artifacts owned by this checkout: skill/rule symlinks that point here, and managed marker blocks in ~/.codex/AGENTS.md. This includes the ~/.agents/skills/* links that OpenCode also reads. Skips foreign symlinks and real directories. Does not remove optional Cursor User Rules paste (edit Settings → Rules manually).

Marketplace / plugin install (UI / CLI — not ./uninstall.sh)

Product	How to uninstall
Cursor	Marketplace / Extensions → find `developer-standards` → Uninstall (or Disable). Reloads skills + bundled rules.
Codex / ChatGPT	Plugins UI → remove/disable `developer-standards`. Does not touch `~/.codex/AGENTS.md` (that comes only from `./install.sh` or a manual paste).
Claude Code	`/plugin uninstall developer-standards@developer-standards` (exact name from `/plugin`). Optional: `/plugin marketplace remove` this marketplace if you added the GitHub URL.

Used both local ./install.sh and a marketplace plugin? Run ./uninstall.sh and uninstall the plugin — otherwise one path keeps the skill active.

Marketplace / plugin install

Cursor — after listing: install developer-standards from Cursor Marketplace. Until then use ./install.sh, or (Teams/Enterprise) Dashboard → Plugins → import this repo URL, then install the developer-standards plugin from that marketplace. Pasting a bare GitHub URL into /add-plugin does not work until publicly listed. Submit checklist: docs/publishing.md.

Codex / ChatGPT — add this repo as a plugin marketplace (see .agents/plugins/marketplace.json), then install developer-standards from the Plugins UI. Global AGENTS activation still needs ./install.sh or a manual paste of integrations/codex/AGENTS.md (all skills).

Claude Code

/plugin marketplace add https://github.com/painhardcore/developer-standards
/plugin install developer-standards@developer-standards

Validate when CLI available: claude plugin validate. Prefer plugin install for versioned updates; ~/.agents/skills symlink from ./install.sh works for personal use without Discover.

Path assumptions

Agent	Path	Mechanism
Codex / ChatGPT / Claude skills	`~/.agents/skills/<name>`	preferred personal skills path (symlink)
OpenCode skills	`~/.agents/skills/<name>`	external-skills auto-scan (`OPENCODE_DISABLE_EXTERNAL_SKILLS=1` disables it)
Codex skills (legacy)	`~/.codex/skills/<name>`	back-compat symlink (still installed)
Codex rules	`~/.codex/AGENTS.md`	marker-managed blocks (`install.sh` only)
Cursor skills	`~/.cursor/skills/<name>`	symlink to this repo
Cursor rules	`~/.cursor/rules/*-standard.mdc`	symlink to `rules/`
Cursor User Rules (optional)	Settings UI	paste text from installer
Never write here	`~/.cursor/skills-cursor/`	Cursor built-ins

Verify installation

./scripts/verify-install.sh
test -L ~/.codex/skills/makefile-standard && readlink ~/.codex/skills/makefile-standard
test -L ~/.codex/skills/dockerfile-standard && readlink ~/.codex/skills/dockerfile-standard
test -L ~/.codex/skills/compose-standard && readlink ~/.codex/skills/compose-standard
test -L ~/.codex/skills/ci-standard && readlink ~/.codex/skills/ci-standard
test -L ~/.codex/skills/go-project-standard && readlink ~/.codex/skills/go-project-standard
test -L ~/.agents/skills/makefile-standard && readlink ~/.agents/skills/makefile-standard
test -L ~/.agents/skills/dockerfile-standard && readlink ~/.agents/skills/dockerfile-standard
test -L ~/.agents/skills/compose-standard && readlink ~/.agents/skills/compose-standard
test -L ~/.agents/skills/ci-standard && readlink ~/.agents/skills/ci-standard
test -L ~/.agents/skills/go-project-standard && readlink ~/.agents/skills/go-project-standard
test -L ~/.cursor/skills/makefile-standard && readlink ~/.cursor/skills/makefile-standard
test -L ~/.cursor/skills/dockerfile-standard && readlink ~/.cursor/skills/dockerfile-standard
test -L ~/.cursor/skills/compose-standard && readlink ~/.cursor/skills/compose-standard
test -L ~/.cursor/skills/ci-standard && readlink ~/.cursor/skills/ci-standard
test -L ~/.cursor/skills/go-project-standard && readlink ~/.cursor/skills/go-project-standard
test -e ~/.cursor/rules/makefile-standard.mdc && readlink ~/.cursor/rules/makefile-standard.mdc
test -e ~/.cursor/rules/dockerfile-standard.mdc && readlink ~/.cursor/rules/dockerfile-standard.mdc
test -e ~/.cursor/rules/compose-standard.mdc && readlink ~/.cursor/rules/compose-standard.mdc
test -e ~/.cursor/rules/ci-standard.mdc && readlink ~/.cursor/rules/ci-standard.mdc
test -e ~/.cursor/rules/go-project-standard.mdc && readlink ~/.cursor/rules/go-project-standard.mdc
grep 'developer-standards:start' ~/.codex/AGENTS.md
python3 skills/makefile-standard/scripts/validate_makefile.py tests/fixtures/valid/Makefile
python3 skills/dockerfile-standard/scripts/validate_dockerfile.py \
  skills/dockerfile-standard/tests/fixtures/valid/go-minimal/Dockerfile
python3 skills/compose-standard/scripts/validate_compose.py \
  skills/compose-standard/tests/fixtures/valid/app-db/compose.yaml
python3 skills/ci-standard/scripts/validate_workflow.py \
  skills/ci-standard/tests/fixtures/valid/ci.yml
python3 skills/go-project-standard/scripts/validate_go_project.py \
  skills/go-project-standard/tests/fixtures/valid/library
python3 -m unittest tests.test_packaging_manifests tests.test_makefile_standard \
  tests.test_dockerfile_standard tests.test_compose_standard tests.test_ci_standard \
  tests.test_go_project_standard

Reload: new Codex session; Cursor reload/restart.

Publishing

Versioning and submit checklists for Cursor, Codex, and Claude Code: docs/publishing.md.

# After bumping VERSION:
./scripts/sync-plugin-versions.sh
git tag "v$(tr -d '[:space:]' < VERSION)"

Using makefile-standard

Automatic: global Codex/Cursor rules tell the agent to apply the skill when touching Makefiles or build/test/lint/deploy/compose flows.

Explicit: ask the agent to use /makefile-standard or “follow makefile-standard”.

Validate a project Makefile:

python3 ~/.cursor/skills/makefile-standard/scripts/validate_makefile.py /path/to/project/Makefile

Application Makefiles must remain usable without this repository on disk (no absolute include of standards files).

Using dockerfile-standard

Automatic: global rules trigger on Dockerfile / .dockerignore / image-build work.

Explicit: /dockerfile-standard or “follow dockerfile-standard”.

Validate:

python3 ~/.cursor/skills/dockerfile-standard/scripts/validate_dockerfile.py /path/to/Dockerfile
bash ~/.cursor/skills/dockerfile-standard/scripts/validate_image.sh IMAGE_REF
bash ~/.cursor/skills/dockerfile-standard/scripts/validate_image.sh IMAGE_REF --smoke --read-only --cap-drop

Using compose-standard

Automatic: global rules trigger on compose.yaml / docker-compose.yml / local Compose topology work.

Explicit: /compose-standard or “follow compose-standard”.

Validate:

python3 ~/.cursor/skills/compose-standard/scripts/validate_compose.py /path/to/compose.yaml

Using ci-standard

Automatic: global rules trigger on .github/workflows/ / GitHub Actions CI work.

Explicit: /ci-standard or “follow ci-standard”.

Validate:

python3 ~/.cursor/skills/ci-standard/scripts/validate_workflow.py /path/to/.github/workflows/ci.yml
python3 ~/.cursor/skills/ci-standard/scripts/validate_workflow.py /path/to/.github/workflows

Using go-project-standard

Automatic: global rules trigger on Go modules / .golangci.yml / package layout work.

Explicit: /go-project-standard or “follow go-project-standard”.

Validate:

python3 ~/.cursor/skills/go-project-standard/scripts/validate_go_project.py /path/to/module
python3 ~/.cursor/skills/go-project-standard/scripts/validate_go_project.py /path/to/module --profile service

Update

cd /path/to/developer-standards
git pull
./update.sh

update.sh refreshes links, validates skill installs, and runs the test suite. On test failure it exits non-zero and leaves existing symlinks intact.

Expected multi-machine flow:

Edit developer-standards → run tests → commit/push → pull elsewhere → ./update.sh

User-level agent directories are not the source of truth. Edit this Git repo.

Another computer / new machine

git clone <repository-url>
cd developer-standards
./install.sh

Paste the printed Cursor User Rules text on that machine.

Remote and ephemeral environments

User-level install is not available in clean containers, CI, cloud agents, or other developers’ machines by default.

Bootstrap options (prefer symlink/pin over copying skill body):

# From a standards checkout, link into a project for local discovery
# (Cursor reads .cursor/skills; OpenCode + agent-compatible tools read .agents/skills):
./scripts/bootstrap-agent-skills.sh /path/to/app

# Or pin a checkout in CI and run validators:
python3 /path/to/developer-standards/skills/makefile-standard/scripts/validate_makefile.py Makefile
python3 /path/to/developer-standards/skills/dockerfile-standard/scripts/validate_dockerfile.py Dockerfile
python3 /path/to/developer-standards/skills/compose-standard/scripts/validate_compose.py compose.yaml
python3 /path/to/developer-standards/skills/ci-standard/scripts/validate_workflow.py .github/workflows
python3 /path/to/developer-standards/skills/go-project-standard/scripts/validate_go_project.py .

Do not commit diverging full copies of skills into every app. If a project needs a local link, use the bootstrap script or a documented pin, then refresh via update.sh / re-clone.

Project-specific exceptions

Makefile: # makefile-standard: except <target> — <reason>.
Dockerfile: # dockerfile-standard: except <rule-id> — <reason>.
Compose: # compose-standard: except <rule-id> — <reason>.
Workflow: # ci-standard: except <rule-id> — <reason>.
Go module: # go-project-standard: except <rule-id> — <reason>.

Adding another skill

Add skills/<name>/ with SKILL.md and its own references/assets/scripts.
Add Codex activation text under integrations/codex/ and a Cursor .mdc under rules/ (via plugin path).
Extend SKILL_SPECS in install.sh / skill lists in uninstall.sh / update.sh / bootstrap-agent-skills.sh.
Add tests (skill-local and/or tests/).
Introduce shared/ only when two or more skills share real code.
Bump VERSION, run ./scripts/sync-plugin-versions.sh, update CHANGELOG.md.

Testing changes

python3 -m unittest tests.test_makefile_standard tests.test_dockerfile_standard \
  tests.test_compose_standard tests.test_ci_standard
./update.sh

Out of scope for application repos

This repository owns the standards. Do not maintain independent forks inside each app. Generate, review, migrate, and validate with these skills; commit only the resulting project files.

Navigation Menu

Repository files navigation

developer-standards

Why you need the skills

What ships today

Makefile naming (quick)

Dockerfile standard (quick)

Compose standard (quick)

CI standard (quick)

Go project standard (quick)

Installation

Install matrix

Local symlink (`./install.sh`)

Uninstall

Marketplace / plugin install

Path assumptions

Verify installation

Publishing

Using makefile-standard

Using dockerfile-standard

Using compose-standard

Using ci-standard

Using go-project-standard

Update

Another computer / new machine

Remote and ephemeral environments

Project-specific exceptions

Adding another skill

Testing changes

Out of scope for application repos

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.agents/plugins		.agents/plugins
.claude-plugin		.claude-plugin
.codex-plugin		.codex-plugin
.cursor-plugin		.cursor-plugin
docs		docs
integrations/codex		integrations/codex
plugins/developer-standards		plugins/developer-standards
rules		rules
scripts		scripts
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
VERSION		VERSION
install.sh		install.sh
skills		skills
uninstall.sh		uninstall.sh
update.sh		update.sh

Latest commit

History

Folders and files

Repository files navigation

developer-standards

Why you need the skills

What ships today

Makefile naming (quick)

Dockerfile standard (quick)

Compose standard (quick)

CI standard (quick)

Go project standard (quick)

Installation

Install matrix

Local symlink (./install.sh)

Uninstall

Marketplace / plugin install

Path assumptions

Verify installation

Publishing

Using makefile-standard

Using dockerfile-standard

Using compose-standard

Using ci-standard

Using go-project-standard

Update

Another computer / new machine

Remote and ephemeral environments

Project-specific exceptions

Adding another skill

Testing changes

Out of scope for application repos

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Local symlink (`./install.sh`)