developer-standards

Shared standards so AI coding agents write Makefiles, Dockerfiles, Compose files, GitHub Actions, and Go modules the same way in every repo.

This repo ships five skills, the activation rules that decide when to load them, validators, and templates. Your app repos keep their own checked-in Makefile, Dockerfile, compose.yaml, workflows, and Go module. None of them depend on this repo at runtime.

The skills

makefile-standard

Naming and shape for Makefiles. Not a target 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	Adds only evidenced or requested ops. The catalog is vocabulary, not a to-do list
Local and production ops look alike	Production is always prod-*. Shipping from your machine is deploy, not prod-deploy
Broken or inconsistent shape	## help text, .PHONY, kebab-case, checked by validate_makefile.py

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 plus a static validator
Fat single-stage images	Multi-stage and profile guidance, measured before and after
Cache thrash	Ordered COPY and BuildKit cache mounts
Root-by-default runtime	Non-root USER, structure checks in validate_image.sh

compose-standard

Creates and reviews lean local Compose files. Not a platform generator.

Problem	What the skill does
Secrets or :latest in Compose	MUST rules plus validate_compose.py
Startup races	healthcheck and depends_on: condition: service_healthy
Overbuilt networks and sidecars	Only evidenced services. The default network is fine
Wrong ownership against Make and Dockerfile	Explicit boundaries with the sibling skills

ci-standard

Creates and reviews GitHub Actions workflows that call your Make targets. GitHub Actions only in v1.

Problem	What the skill does
Parallel CI scripts beside Make	Wires the job to make check or make ci
No concurrency, over-broad permissions	Concurrency groups and least-privilege defaults
Floating action branches, missed caches	Pins actions, caches when install is non-trivial
Unsolicited deploy from CI	Image build and deploy only when evidenced

go-project-standard

Reviews and shapes Go modules (library, service, cli). Not a project scaffolder.

Problem	What the skill does
Empty pkg/, project-layout cargo cult	Flat start, cmd/ and internal/ when evidenced
Weak or v1-only lint	golangci-lint v2 template with curated enables
Missing tests, hard coverage gates	Logic packages get tests. No coverage percentage that fails the build
tools.go blank imports on Go 1.24+	Prefers the tool directive

Also in the box: the six validators (validate_makefile.py, validate_dockerfile.py, validate_image.sh, validate_compose.py, validate_workflow.py, validate_go_project.py), short activation rules that say when to load each skill, and the rule catalogs each skill reads.

The rules

Each skill carries its full rules, and each reference doc links its own catalog and profiles.

• makefile-standard
• dockerfile-standard
• compose-standard
• ci-standard
• go-project-standard

Installation

Current version is in VERSION. Plugin id: developer-standards. Pick the path for your agent below. Run only one path per agent; mixing a marketplace install with ./install.sh for the same agent duplicates the skills.

Claude Code

/plugin marketplace add painhardcore/developer-standards
/plugin install developer-standards@developer-standards

Update with /plugin marketplace update. Uninstall with /plugin uninstall developer-standards@developer-standards.

Claude has no separate rule file. It picks the skills up from their descriptions, or you can name one directly (/makefile-standard).

Codex / ChatGPT

codex plugin marketplace add painhardcore/developer-standards

This registers the marketplace. Installing the plugin itself is a UI step: open the Plugins Directory in the ChatGPT desktop app (or Work mode) and install developer-standards from that source.

The marketplace install does not touch ~/.codex/AGENTS.md, so the skills won't fire until you also run the local install below.

Cursor

Not on the public Cursor Marketplace yet. On a Team or Enterprise plan, go to Dashboard → Plugins → Import Marketplace and paste https://github.com/painhardcore/developer-standards. Otherwise, use the local install below. Publishing checklist: docs/publishing.md.

OpenCode

No marketplace. Use the local install below; OpenCode auto-scans ~/.agents/skills.

Local install (any agent)

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

This symlinks every skill into ~/.codex/skills/, ~/.agents/skills/, and ~/.cursor/skills/, symlinks rules/*.mdc into ~/.cursor/rules/, and upserts marker blocks in ~/.codex/AGENTS.md (after a backup). It also prints Cursor User Rules text you can paste in by hand. Re-running is safe. It won't overwrite an unrelated real skill directory unless you set INSTALL_FORCE=1.

To update: git pull && ./update.sh.

./uninstall.sh removes only what this checkout owns: symlinks pointing here and the managed marker blocks. It skips foreign symlinks and real directories, and leaves any pasted Cursor User Rules in place (remove those yourself under Settings → Rules).

Where things land

Agent	Path	Mechanism
Codex, ChatGPT, Claude skills	~/.agents/skills/<name>	preferred personal skills path (symlink)
OpenCode skills	~/.agents/skills/<name>	auto-scan, disable with OPENCODE_DISABLE_EXTERNAL_SKILLS=1
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/
Never write here	~/.cursor/skills-cursor/	Cursor built-ins

Verify

./scripts/verify-install.sh

It checks repo packaging, plugin manifests, and every symlink, rule, and AGENTS marker, and tells you which parts are merely not installed rather than broken. Then reload: a new Codex session, a Cursor restart.

Using the skills

Cursor and Codex rules fire on the matching files. Claude picks the skill up from its description. You can also name the skill explicitly, as /makefile-standard or "follow makefile-standard".

Skill	Triggers on	Validate
makefile-standard	Makefiles, build/test/lint/deploy flows	validate_makefile.py /path/to/Makefile
dockerfile-standard	Dockerfile, .dockerignore, image builds	validate_dockerfile.py /path/to/Dockerfile
compose-standard	compose.yaml, docker-compose.yml	validate_compose.py /path/to/compose.yaml
ci-standard	.github/workflows/	validate_workflow.py /path/to/.github/workflows
go-project-standard	Go modules, .golangci.yml, package layout	validate_go_project.py /path/to/module

Validators live under skills/<name>/scripts/, reachable after a local install at ~/.cursor/skills/<name>/scripts/:

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

The image validator takes an image reference and optional runtime checks:

bash ~/.cursor/skills/dockerfile-standard/scripts/validate_image.sh IMAGE_REF --smoke --read-only --cap-drop

Application Makefiles must stay usable without this repo on disk. No absolute include of standards files.

Project-specific exceptions

One comment line, in the file that breaks the rule, with a reason:

# makefile-standard: except <target> - <reason>
# dockerfile-standard: except <rule-id> - <reason>
# compose-standard: except <rule-id> - <reason>
# ci-standard: except <rule-id> - <reason>
# go-project-standard: except <rule-id> - <reason>

Remote and ephemeral environments

A user-level install is not available in clean containers, CI, cloud agents, or a colleague's machine. Link a checkout into the project instead of copying skill bodies around:

# Cursor reads .cursor/skills, OpenCode and agent-compatible tools read .agents/skills
./scripts/bootstrap-agent-skills.sh /path/to/app

Or pin a checkout and call the validators straight from it:

python3 /path/to/developer-standards/skills/ci-standard/scripts/validate_workflow.py .github/workflows

Copies of skills committed into app repos drift within a month and nobody notices. Use the bootstrap script or a documented pin, then refresh with update.sh.

Updating

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

update.sh refreshes the links, checks the skill installs, and runs the test suite. A failing test exits non-zero and leaves the existing symlinks alone.

The multi-machine flow is: edit this repo, run tests, commit and push, pull elsewhere, ./update.sh. The directories under ~ are copies. This Git repo is the source of truth, and so is the fork question: this repo owns the standards, app repos commit only the files the skills produce.

Contributing

Adding a skill:

1. Add skills/<name>/ with a SKILL.md and its own references, assets, and scripts.
2. Add Codex activation text under integrations/codex/ and a Cursor .mdc under rules/.
3. Extend SKILL_SPECS in install.sh, and the skill lists in uninstall.sh, update.sh, and bootstrap-agent-skills.sh.
4. Add tests, skill-local or under tests/.
5. Add shared/ only once two skills genuinely share code.
6. Bump VERSION, run ./scripts/sync-plugin-versions.sh, update CHANGELOG.md.

Running the tests:

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
./update.sh

Releasing, after bumping VERSION:

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

Submit checklists for Cursor, Codex, and Claude Code are in docs/publishing.md.