Guidelines for All (g4a)

Guidelines for All turns your linter configurations into readable coding standards, and helps you set up and maintain those configurations. The command is g4a.

Coding guidelines usually live in a wiki that nobody reads and that drifts out of sync with what the linters actually enforce. Guidelines for All works backward from the tools your team already runs, so the guidelines stay accurate and are available to everyone who touches the code, not just the people who wrote the lint config.

What it does

1. Generates coding standards from linter configs. g4a reads ESLint, Prettier, Ruff, Pyright, Roslyn, Checkstyle, PMD, SpotBugs and 16 more tools, then writes a coding-standards document (Markdown or Word) with each rule's upstream documentation.
2. Helps you manage the configs. It can scan a codebase for the conventions your team already follows and write matching linter configs, find rules that conflict across tools, and generate a script that runs every linter.

Because the document is generated from the configs, it changes when the configs change.

Features

• Coding standards document — A front section (purpose, scope, definitions, tooling) followed by one appendix per tool, as Markdown or Word. Use the built-in templates or your own.
• Rules your tools enforce by default — Rules a tool turns on by itself or through a preset the config selects (Clippy's default groups, Ruff's default set, Pyright's type-checking mode, TypeScript strict, eslint:recommended, ...) are documented too, each with its source.
• Convention discovery — g4a discover scans Python, JavaScript, TypeScript, Rust and Go source and writes linter configs that match what the code already does.
• Rule interference detection — Finds rules that conflict across tools, such as ESLint semi and Prettier semi.
• Lint runner — g4a generate-script writes a bash script that runs every configured linter in check or fix mode.
• AI-friendly export — g4a export-rules writes the enforced rules as JSON, YAML or Markdown for coding assistants.
• Terminal UI — Browse rules, run the discover wizard and check interference interactively.

Status

v1.3.0 (released 2026-10-29), beta. See CHANGELOG.md for what changed.

Installation

pip install guidelines-for-all
g4a --version

pip install g4a installs the same package. Optional extras, which need the full package name:

pip install "guidelines-for-all[tui]"         # terminal UI (g4a tui)
pip install "guidelines-for-all[similarity]"  # semantic interference detection (large download)

Requirements

From source

For unreleased features or development:

git clone https://github.com/coreyt/guidelines-for-all.git
cd guidelines-for-all
pip install -e .
g4a --version

Quick start

Fastest: one command

In a project that has linter configs:

g4a --auto

This detects the tools, fetches their rule documentation and writes generated/coding-standards.md. It does not create a g4a.yaml; use the steps below when you want to keep settings.

You already have linter configs

g4a init     # Detect linter configs and write g4a.yaml
g4a sync     # Fetch rule documentation from GitHub into .g4a-cache/
g4a build    # Write docs/guidelines/coding-standards.md

What each step creates:

Other forms of build:

g4a build --markdown-only      # one Markdown file per tool instead of one document
g4a build --appendix-only      # only the appendices, to paste into an existing document
g4a build --format docx        # Word document (needs Pandoc and a template)
g4a build -o out/              # another output directory

Edit g4a.yaml to change the project name, add or remove tools, or point at config files g4a did not find. Run g4a check to validate it.

Starting without linter configs

g4a discover scans your source code, reports the conventions it finds, and can write linter configs that match them.

g4a discover                # Report detected conventions (writes nothing)
g4a discover --dry-run      # Show the config files it would write
g4a discover --apply        # Write the linter configs and g4a.yaml
g4a check-interference      # Look for rules that conflict across tools
g4a build                   # Write generated/coding-standards.md

discover --apply writes g4a.yaml without an output setting, so build writes to generated/. Add output: {markdown: {output_dir: docs/guidelines}} to g4a.yaml to change that, and add .g4a-cache/ to .gitignore.

The generated document

g4a build writes one document with three parts:

┌─────────────────────────────────────┐
│  Front section                      │  ← Purpose, scope, definitions, tooling
├─────────────────────────────────────┤
│  How to read the appendices         │
├─────────────────────────────────────┤
│  Appendix A: ESLint Rules           │
│  Appendix B: Prettier Rules         │  ← One per tool, from its config
│  ...                                │
└─────────────────────────────────────┘

• Templates. --template-preset minimal|standard|enterprise (or document.template_preset in g4a.yaml) picks how much front matter you get; standard is the default. To write your own front section, set document.stub to a Markdown file.
• Markdown dialect. The document uses [[_TOC_]] for its table of contents and \pagebreak for page breaks. GitLab and Azure DevOps render the table of contents and Pandoc honours both; on GitHub they appear as plain text.
• Rules from defaults and presets. Rules the config names get a full section. Rules a tool enables by default or through a preset are listed in one table per tool. Set output.markdown.default_rules to full for full sections or omit for a count only.

Word output

g4a build --format docx --docx-template path/to/template.docx

Word output needs Pandoc and a Word template that defines the styles g4a uses: TableCompact, Bullet List 1–3, Ordered List 1–3, GrayBlock Text and GrayBlock Bullet List 1–3. g4a uses --docx-template if given, else output.docx.template in g4a.yaml, else a file named docx-template.docx in the project directory or the current directory. --format all writes both Markdown and Word.

Commands

Run g4a <command> --help for each command's options.

Options that go before the command:

Using g4a in CI

g4a check
g4a check-interference --fail-on-conflict
g4a build

Set GITHUB_TOKEN in the CI environment, and cache .g4a-cache/ between runs to avoid refetching.

Supported tools

24 tools. g4a finds these config files automatically; any other path can be set with config_path in g4a.yaml.

TypeScript/JavaScript

Python

C#/.NET

dotnet format enforces .editorconfig settings through the Roslyn analyzers, so its IDE* rules are covered by the Roslyn adapter.

Java

C/C++

Rust

Go

Lua

Markdown

Multi-language

The front section of the document is written for the project's main ecosystem: JavaScript/TypeScript, Python, C#/.NET, Java, C/C++, Rust, Go, Lua or Markdown. g4a picks it from the enabled tools; set document.ecosystem in g4a.yaml to choose it yourself.

Configuration

g4a init writes g4a.yaml. A typical file:

project:
  name: "My Project"

tools:
  ruff:
    enabled: true
    config_path: pyproject.toml
  markdownlint:
    enabled: true
    config_path: .markdownlint.json

output:
  markdown:
    output_dir: ./docs/guidelines   # default when the key is absent: ./generated

document:
  template_preset: standard         # minimal, standard or enterprise
  appendices:
    style: alpha                    # A, B, C (or numeric: 1, 2, 3)
    prefix: Appendix

interference:
  on_conflict: warn                 # or error: build exits with code 5
  ignore:
    - "eslint/semi:prettier/semi"   # pairs you enforce in both tools on purpose

cache:
  ttl_days: 7

g4a ignores keys it does not know, so a misspelled key has no effect. g4a check and the pre-flight checks name each such key in a warning. Check spelling against the configuration reference.

Rule interference

g4a looks for rules that conflict across tools, for example:

• ESLint semi and Prettier semi
• ESLint quotes and Prettier singleQuote
• ESLint no-unused-vars and TypeScript-ESLint no-unused-vars

g4a check-interference                     # report conflicts
g4a check-interference --format json       # as JSON
g4a check-interference --fail-on-conflict  # exit code 5 when conflicts are found

g4a build runs the same check. List pairs you enforce in both tools on purpose under interference.ignore.

Checking the generated Markdown

• g4a build --lint runs markdownlint-cli2 on the output (install it with npm).
• The pymarkdown_lint setting runs PyMarkdown (pip install pymarkdownlnt) with a preset for where the document will be read:

pymarkdown_lint:
  enabled: true
  preset: pandoc          # or gfm
  fail_on_error: false

GitHub token

Rule documentation is fetched from GitHub. Without a token the limit is 60 requests an hour; with one it is 5,000.

1. Create a token at GitHub settings → Developer settings → Personal access tokens. A classic token with no scopes is enough, because g4a only reads public repositories.
2. Set it before running g4a:

export GITHUB_TOKEN=ghp_your_token_here

Add that line to your shell profile (~/.bashrc, ~/.zshrc) to keep it, or use a tool such as direnv for per-project settings. Never commit the token. g4a check reports whether a token was found.

Fetched documentation is cached in .g4a-cache/ for 7 days (cache.ttl_days), so later builds work offline.

Documentation

• Usage guide - Every command and setting, with examples
• Codebase analyzer - How g4a discover detects conventions
• Adding linter adapters - Supporting another tool
• Changelog - Release history
• Roadmap - What is planned next
• Contributing - Development setup, tests and project layout

License

Licensed under the Elastic License 2.0 (ELv2). ELv2 is a source-available license; it is not an OSI-approved open-source license.

In plain terms (the LICENSE text is what governs), you may use, copy, modify and redistribute the software, including inside your company and in your CI pipelines, but you may not:

• provide it to third parties as a hosted or managed service that gives them access to a substantial part of its features;
• move, change, disable or circumvent any license-key functionality;
• alter, remove or obscure licensing, copyright or other notices.

License history

• Up to and including v1.0.0 (January 2026): MIT. Anyone who received v1.0.0 keeps the MIT rights to that version.
• From the March 2026 relicense onward (v1.2.0 and later): Elastic License 2.0.