Skip to content

Repo Standard V1.0

1. Commit and PR policy

Use Conventional Commits syntax:

<type>[optional scope]: <description>

Allowed types:

feat
fix
docs
refactor
test
chore
ci
build
perf
revert
style

Required CI gate

  • Semantic PR title validation is required in CI.
  • The semantic-pull-request.yml workflow validates every PR title.
  • This is the non-negotiable source of truth for release notes and changelogs.

Optional local gate

  • commitlint (via Husky for Node repos) or pre-commit hooks (for Python repos) are optional but recommended for local feedback.
  • If commitlint is configured with subject-case disabled ([0]), this is intentional: squash-merge PR titles (not individual commits) are the release source of truth. Lowercasing individual commit subjects would not meaningfully improve the final squash message and would add friction to local commits.
  • Squash merge.
  • The squash commit title should be the validated PR title.

2. Release policy

Use Release Please for repos that publish packages, GitHub releases, or user-facing deployable artifacts.

Release Please strategies

Choose the workflow template that matches the repo type:

Repo type Template Notes
Simple / single-component release-please.simple.yml General-purpose; no package.json version file
Node package / library release-please.node.yml Bumps package.json version automatically
Mixed / monorepo release-please.manifest.yml Requires .release-please-manifest.json + release-please-config.json
  • Node package/library repos should use the Node-specific release template (release-please.node.yml).
  • Mixed repos (multiple languages, monorepos) should prefer manifest mode (release-please.manifest.yml).

Release Please should:

  • Create or update release PRs from Conventional Commit history.
  • Maintain changelog.
  • Bump versions where the repo has version files.
  • Create GitHub releases.

Release Please owns release PRs, changelog updates, GitHub releases, and tags for repositories that enable it. Do not manually edit CHANGELOG.md or create release tags for normal releases unless intentionally bypassing Release Please.

Release Please should not be treated as the deploy tool. Deployment remains in repo-specific workflows.

3. AI/editor instruction policy

Use Rulesync.

Canonical files:

.rulesync/rules/*.md
rulesync.jsonc
.repo-policy.yml

Generated files:

AGENTS.md
.cursor/rules/*.mdc
.agents/rules/*.md
.agents/memories/*.md   (when `antigravity-ide` target is enabled)

The CI check should regenerate and fail if generated files drift.

Non-dot agents/ paths

A top-level agents/ directory (without a leading dot) is not part of this standard. The standard only defines behavior for .agents/. If a repo has a flat agents/ directory, it should be for a documented purpose (e.g., an actual AI agent application). The standard's checks will flag agents/ as suspicious unless a documented exception exists.

Rulesync targets

The rulesync.jsonc template defines three targets:

Target Output Purpose
agentsmd AGENTS.md Universal AI agent instructions (works in any AI coding tool)
cursor .cursor/rules/*.mdc Cursor-specific rules for IDE behavior
antigravity-ide .agents/rules/*.md, .agents/memories/*.md Antigravity (Ante AI) IDE rules

All three targets are enabled by default. If a downstream repo does not use a particular IDE, its generated directory can be committed but is effectively unused until that IDE is used.

Important: Rulesync output may list only changed/generated files and should not be the sole source of truth for whether all target outputs exist. To verify that all expected outputs are present, use:

find AGENTS.md .cursor .agents .rulesync -maxdepth 4 -type f -print | sort

.agents/memories/ is generated, not runtime junk

The antigravity-ide Rulesync target generates both .agents/rules/*.md and .agents/memories/*.md. The memories subdirectory is a valid generated output containing AI agent knowledge. If the repo opts into Antigravity IDE support, .agents/memories/ should be committed, not ignored.

If .agents/memories/ exists but rulesync.jsonc does not contain antigravity-ide, that should be flagged for manual review (it may be stale or misconfigured).

AI rules and documentation governance

Human documentation and AI/editor rules must evolve together.

  • docs/ explains the standard for humans.
  • ai/rules/*.md defines reusable AI/editor rule templates in this standards repo.
  • Downstream repos copy those rules into .rulesync/rules/*.md.
  • Rulesync generates AGENTS.md, .cursor/rules/*.mdc, .agents/rules/*.md, and .agents/memories/*.md.
  • Generated AI/editor outputs must not be edited directly as the source of truth.
  • A docs/AI-rule sync check should warn when standards docs or templates change without corresponding AI rule source changes.

See docs/ai-rules-maintenance.md for the full maintenance pipeline.

Run the sync checker locally:

python3 scripts/check_docs_ai_rule_sync.py --base-ref main

Strict mode:

python3 scripts/check_docs_ai_rule_sync.py --base-ref main --strict

The optional Docs / AI Rule Sync workflow template is at templates/workflows/docs-ai-rule-sync.yml.

4. CI quality gates

Every repo should expose the same conceptual gates, even if the commands differ:

install
format_check
lint
typecheck
test
coverage
build
docs

A gate may be explicitly disabled in .repo-policy.yml only when it is not applicable.

File and language checks are governed by the unified code-quality-standards.md model:

  • Repo profile determines which standards apply.
  • File patterns determine which tools/checks run.
  • CI remains authoritative.
  • Pre-commit is optional local feedback.
  • Existing repos should adopt newly introduced checks as warnings/report-only first.

Node version management

Node/TypeScript repositories must have a root .nvmrc file specifying the project's Node.js version (e.g., 24).

  • .nvmrc is the operational source of truth for local development (nvm use, fnm, etc.) and CI (node-version-file).
  • The node_version field in .repo-policy.yml is descriptive -- it documents the intended version, but .nvmrc drives actual setup.
  • .nvmrc is required for Node repositories.
  • AI rules checks use .nvmrc when present and fall back to Node 24 for non-Node repositories.
  • CI workflow templates use node-version-file: ".nvmrc" instead of hardcoded node-version.

A template .nvmrc (with 24) is at configs/node/.nvmrc.

Reusable workflow inputs

When writing CI workflows, prefer using workflow_call with inputs so that runtime versions and commands are configurable per-repo:

Input Default Purpose
node_version "" (uses .nvmrc) Node.js version for setup-node
python_version "3.12" Python version for setup-python
install_command "npm ci" or pip command Install dependencies
format_check_command "npm run format:check" or "ruff format --check ." Format check
lint_command "npm run lint" or "ruff check ." Lint check
typecheck_command "npm run typecheck" or "" Type checking
test_command "npm test" or "pytest" Run tests
coverage_command "npm run test:coverage" or coverage run Coverage report
build_command "npm run build" or "" Build step
strict false Optional file-pattern quality checks may fail on missing tooling
run_tools false Optional file-pattern quality checks may run installed safe tools
fail_on_missing_tools false Alias for strict missing-tool behavior in file-pattern checks
*_enabled true Optional file-area toggles for Python, shell, YAML, Markdown, Docker, and Make checks
*_lint_command / markdown_check_command "" Optional repo-specific file-area check commands

Reusable workflows that support both workflow_call and direct push/pull_request triggers must explicitly handle empty inputs.* values. Do not assume input defaults are available during direct-triggered runs. Workflows that are workflow_call only may rely on their declared input defaults.

Reusable workflows (long-term preferred)

The preferred long-term CI standard is GitHub reusable workflows defined in repo-standards and called from downstream repos. This reduces template drift and ensures updates flow automatically.

See docs/template-drift.md for details and caller examples.

Stable consumers should pin reusable workflows to a release tag such as @v1.0.0. Use @main only for canary repositories that intentionally track unreleased changes.

Reusable workflow locations:

Path Purpose
.github/workflows/*.reusable.yml Live reusable workflows callable by downstream repos
templates/workflows/*.reusable.yml Copy/reference templates, if retained

Live callable workflows:

  • .github/workflows/node-ci.reusable.yml
  • .github/workflows/python-ci.reusable.yml
  • .github/workflows/code-quality.reusable.yml (optional file-pattern analyzer)

Template copies:

  • templates/workflows/node-ci.reusable.yml
  • templates/workflows/python-ci.reusable.yml
  • templates/workflows/code-quality.reusable.yml

5. Coverage policy

Coverage should be phased in.

Baseline:

  • Generate coverage report where tests already exist.
  • Do not block merges on strict percentage initially.

Phase 1:

  • Enforce coverage only for repos with existing coverage scripts.
  • Use repo-local thresholds.

Phase 2:

  • Enforce patch/diff coverage for changed code.
  • Increase thresholds gradually.

Default starting thresholds:

libraries: 80% lines / 70% branches
services/workers: 70% lines / 60% branches
legacy/mixed repos: report-only until stable

Do not fail a useful bugfix because a legacy repo has poor historical coverage. Prefer changed-code coverage first.

Coverage remains report-only unless a repo has stable thresholds.

.gitignore guidance

Ensure the following entries are in every repo's .gitignore:

# Build and coverage artifacts
coverage/
htmlcov/
.coverage

# DO NOT ignore .agents/memories/ if using the antigravity-ide Rulesync target
# .agents/memories/ contains generated AI agent knowledge and should be committed

Previously tracked coverage/ files may appear as D coverage/... in git status after adding coverage/ to .gitignore. This is acceptable cleanup -- not a blocker. Adding or modifying generated coverage/ files (A coverage/... or M coverage/...) should still be a blocker in a standards migration PR.

6. Docs and governance policy

Required docs:

README.md
.repo-policy.yml
AGENTS.md
CONTRIBUTING.md
LICENSE or LICENSE.md
.github/PULL_REQUEST_TEMPLATE.md

Recommended docs:

docs/development.md
docs/deployment.md
docs/release.md

License selection

  • Public/open-source repos should use an explicit open-source license. MIT is the default recommendation (templates/licenses/LICENSE-MIT.txt).
  • Private/proprietary repos should use a proprietary/all-rights-reserved notice (templates/licenses/LICENSE-PROPRIETARY.txt).
  • Do not add or change a license casually. Licensing decisions should be reviewed by the repo owner.
  • Agents must never change license terms unless explicitly instructed.
  • Private repos should not accidentally receive an open-source license.

The .repo-policy.yml visibility and license fields should match the chosen license:

visibility: public # public | private
license: MIT # MIT | proprietary | none
governance:
  contributing: required
  pull_request_template: required

Required README concepts (validated by docs-check.yml via keyword/concept matching, not exact headings):

Overview
Local development
Checks (CI, quality gates, lint, test, etc.)
Deployment or release process
Environment variables / secrets (or "None required")
AI/editor instructions

A repo with no environment variables may satisfy the requirement with "None required."

7. Repo classes

Use these profiles:

typescript-library
typescript-cloudflare-worker
typescript-app
python-home-assistant
python-service
mixed-special

The profile determines CI defaults and migration risk.

Profile templates

Each profile template (under templates/repo-policy.*.yml) includes:

Field Description
name Descriptive example name
profile Profile identifier
visibility Repository visibility (public or private)
license License type (MIT, proprietary, or none)
governance Required governance files (contributing, pull_request_template)
node_version / python_version / package_manager Runtime configuration (descriptive; .nvmrc is operational for Node)
commands Install, format, lint, typecheck, test, coverage, build
quality_gates Required checks
release Release Please configuration
deploy Deploy provider and workflow
migration_notes Notes specific to this profile's migration

Python typechecking

Python typechecking (mypy, pyright, etc.) is adopted repo-by-repo. It is not enforced globally. Templates include an empty typecheck: "" field and a comment explaining the policy. Individual repos may add a typecheck command when ready.

8. Dependency updates

Dependabot

Dependabot is the baseline dependency update tool for all repositories.

Copy templates/dependabot.yml to .github/dependabot.yml in each repo.

The template includes weekly updates for:

  • GitHub Actions
  • npm (root directory, with grouped dev dependency updates)
  • pip (root directory)

For monorepos or repos with nested projects, add additional directory entries for each sub-project.

See docs/dependency-updates.md for customization guidance.

9. Secret scanning

A baseline secret scanning workflow is at templates/workflows/secret-scan.yml.

The workflow uses TruffleHog to scan PR diffs for verified secrets. It is configured conservatively (--results=verified) to reduce false positives.

Branch protection should require the Secret Scan check once it passes consistently in a repo.

See docs/security-scanning.md for configuration and recommended workflow.

10. Template drift management

Repo-standards supports two approaches for managing template drift:

Approach When to use
Copied templates (default) Initial migration, early adoption. Templates are copied into each repo. Drift must be reassessed manually.
GitHub reusable workflows (preferred long-term) After the standard stabilizes. Workflows live in repo-standards and are called from downstream repos. Updates flow automatically.

See docs/template-drift.md for caller examples and migration guidance.

11. Branch protection

After migration, the following required checks should be configured in branch protection rules for the default branch:

Check Required when
Semantic Pull Request Always
AI Rules Always (if .rulesync/ is present)
CI Always
Docs Always
Docs / AI Rule Sync Recommended (warns when docs/templates change without AI rule source updates)
Secret Scan Recommended (once it passes consistently)
Deploy check When deploy workflow is configured
Release check When Release Please is configured

See docs/branch-protection.md for details.

12. Repository health baseline

Required for new repos

Every new repository must include:

README.md
.repo-policy.yml
AGENTS.md
CONTRIBUTING.md
LICENSE or LICENSE.md
SECURITY.md
.github/PULL_REQUEST_TEMPLATE.md
.gitignore
.editorconfig
.env.example

Warnings for existing repos during migration

When migrating existing repositories, the following items should be addressed but are not blockers:

SECURITY.md
.env.example
.editorconfig
issue templates (.github/ISSUE_TEMPLATE/)
ADR directory (docs/decisions/)
CODEOWNERS
devcontainer
license scanning

Repository health files

.gitignore

  • Required for all repos
  • Use templates from templates/gitignore/ based on project type:
  • node.gitignore for Node.js projects
  • python.gitignore for Python projects
  • cloudflare-worker.gitignore for Cloudflare Workers
  • mixed.gitignore for mixed-language projects
  • Ensure coverage/ is ignored in all repos
  • Do not ignore .agents/memories/ if using the antigravity-ide Rulesync target

.env.example

  • Required for all repos with environment variables
  • Document required environment variable names with blank or placeholder values only
  • Do not commit real secret values
  • Include Honeybadger placeholders if using Honeybadger: 
    HONEYBADGER_API_KEY=
HONEYBADGER_ENVIRONMENT=development
  • For Cloudflare Workers, add comments explaining that production secrets should be configured with Wrangler/Cloudflare secrets

.editorconfig

  • Required for all repos
  • Ensures consistent code formatting across editors
  • Template at templates/.editorconfig
  • Default settings:
  • LF line endings
  • UTF-8 charset
  • 2 spaces for JavaScript/TypeScript/JSON/YAML
  • 4 spaces for Python
  • Preserve trailing whitespace in Markdown

SECURITY.md

  • Required for all repos
  • Template at templates/SECURITY.md
  • Include:
  • Supported versions
  • How to report a vulnerability
  • Contact method placeholder
  • Expected response timeline
  • Request not to disclose publicly before coordination
  • Note that secrets should never be included in reports

Issue templates

  • Optional but recommended
  • Templates at templates/.github/ISSUE_TEMPLATE/
  • Include:
  • bug_report.yml - for reporting bugs
  • feature_request.yml - for feature requests
  • config.yml - to disable blank issues and provide contact links

ADRs (Architecture Decision Records)

  • Optional but recommended for significant architectural decisions
  • Template at templates/docs/decisions/ADR-000-template.md
  • Store in docs/decisions/ directory
  • Use ADR-XXX naming convention (e.g., ADR-001, ADR-002)

CODEOWNERS

  • Optional guidance, not required
  • Template at templates/.github/CODEOWNERS
  • Document that users must update the owner before copying
  • Example: 
    # Default owner
* @YOUR_GITHUB_USERNAME

Devcontainers

  • Optional guidance for repos with heavier setup
  • Useful for Cloudflare Workers or Python service repos
  • Not required in the standards assessment
  • Document when and why to use devcontainers

Dependency license scanning

  • Optional future quality gate
  • Not required in current standards
  • For Node: consider tools like license-checker
  • For Python: consider tools like pip-licenses
  • Document as future enhancement in repo documentation

Blocker vs warning guidance

When assessing a standards migration PR, the assessor should distinguish between:

Blockers (must fix before merging)

  • Missing .repo-policy.yml
  • Missing .rulesync/rules/*
  • Missing generated AI/editor files (AGENTS.md, .cursor/rules/*.mdc, .agents/rules/*.md)
  • Changed or added generated coverage artifacts (A coverage/... or M coverage/...)
  • Secret-like files in the diff
  • Risky deploy changes in a standards-only PR

Warnings / follow-up work (standard migration is acceptable)

  • Deleted generated coverage artifacts (D coverage/... when coverage/ is in .gitignore)
  • Low test coverage
  • ESLint warnings or errors
  • npm audit vulnerabilities
  • Legacy stale agent files being removed
  • Missing pinned Rulesync tooling dependency. Rulesync is mandatory for every repo; non-Node repos should use a private tooling-only package.json.
  • Missing .nvmrc in a Node repo (recommended but not yet required)
  • Missing .github/dependabot.yml (recommended but not yet required)
  • Missing secret scanning workflow (recommended but not yet required)
  • Missing .gitignore (warning initially, blocker for strict/new repo mode if supported)
  • Missing .editorconfig (warning initially)
  • Missing .env.example (warning initially)
  • Missing SECURITY.md (warning initially)
  • Missing issue templates (optional warning)
  • Missing ADR directory/template (optional recommendation only)