Skip to content

Core concepts

This document explains the repo-standards model: what is copied, what is generated, what is reusable, and how drift is managed.

For how documentation and AI/editor rules stay aligned, see ai-rules-maintenance.md.

Core standard

The core standard applies to every repository that adopts this blueprint. It includes:

  • .repo-policy.yml — profile, commands, quality gates, release, deploy, and governance metadata
  • AI/editor instructions via Rulesync — canonical rules in .rulesync/rules/*.md
  • Semantic PR titles / Conventional Commits
  • Docs and governance files (README.md, CONTRIBUTING.md, LICENSE, PR template)
  • Secret scanning (TruffleHog PR diff scanning)
  • Repository health baseline (.gitignore, .env.example, .editorconfig, SECURITY.md, and related files)
  • Dependabot for GitHub Actions, npm, and pip

Language/runtime tooling, deploy provider behavior, release automation, and strictness levels are modular — chosen via profile and .repo-policy.yml.

Profiles

A profile is a named starting point for .repo-policy.yml. Profiles encode typical language/runtime, deploy assumptions, and default commands. See profiles.md.

Profile detection is advisory. Once adopted, .repo-policy.yml is authoritative.

Modules

Modules are optional or phased capabilities layered on the core standard:

  • Language/runtime CI (Node, Python)
  • Release Please
  • Reusable workflows vs copied templates
  • Coverage thresholds (phased — report-only first)
  • Dependency license scanning
  • Devcontainers

Enable modules through .repo-policy.yml and the workflows you copy or call.

Copied templates

Templates in templates/ are copied into each application repository and customized. Early migrations typically copy workflows directly into .github/workflows/.

Directory Purpose
templates/ Repo policy profiles, Dependabot, governance files, licenses
templates/workflows/ GitHub Actions workflows (CI, release, docs, AI rules, semantic PR, secret scan)
templates/licenses/ MIT and proprietary license templates
templates/gitignore/ Language-specific .gitignore starters
ai/rules/ Canonical AI/editor rules (copied to .rulesync/rules/)
configs/ Starter configs: commitlint, pre-commit, ruff, .nvmrc

Reusable workflows

Long-term, downstream repos should call reusable workflows from this standards repo via uses: instead of copying CI logic. Live callable workflows live in .github/workflows/*.reusable.yml. See template-drift.md.

Stable consumers should pin to a release tag (e.g. @v1.0.0). Use @main only for canary repos.

Generated files

Some files are generated by Rulesync and committed:

Output Source
AGENTS.md Universal AI agent instructions
.cursor/rules/*.mdc Cursor IDE rules
.agents/rules/*.md Antigravity IDE rules
.agents/memories/*.md Antigravity memories (when antigravity-ide target is enabled)

Canonical source:

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

What should NOT be committed

coverage/
htmlcov/
.coverage
dist/
node_modules/
.env
*.pem, id_rsa

Assessment reports

The assessor (scripts/assess_repo_standards.py) scores alignment with Repo Standard V1.0. Reports go to assessments/generated/ by default, or to --output-dir when supplied. See assessment-guide.md.

The detector (scripts/detect_repo_standard.py) is separate — it recommends a starting profile before adoption. It is read-only and advisory.

Drift management

Copied templates drift over time as canonical templates evolve. Mitigations:

  1. Reassess periodically with the assessor
  2. Migrate to reusable workflows once the standard stabilizes
  3. Track template drift — see template-drift.md
Approach Pros Cons
Copied templates Fast to adopt, full customization Drift over time, manual reassessment
Reusable workflows Centralized logic, automatic updates Less customization, requires stable standard

Lifecycle table

Item Lifecycle Notes
.repo-policy.yml Copied and customized Source of truth for repo profile, commands, gates, release, deploy
.rulesync/rules/*.md Copied and customized Canonical AI/editor source
AGENTS.md Generated and committed Generated by Rulesync
.cursor/rules/*.mdc Generated and committed Generated by Rulesync
.agents/rules/*.md Generated and committed Generated by Rulesync
.agents/memories/*.md Generated and committed when enabled Valid output for Antigravity target
.github/workflows/*.yml Copied or reusable Prefer reusable workflows after standard stabilizes
assessments/generated/ Generated and ignored Local assessor output
assessments/examples/ Committed examples Sanitized reference outputs

Repository layout (standards repo)

Directory Purpose
ai/rules/ Canonical AI/editor rules
configs/ Starter configs
docs/ Standard specification and guides
templates/ Copyable templates
profiles/ Profile definitions and detection rules
scripts/ Assessment and detection tools
assessments/ Reference examples and generated output location

Phased enforcement

Phase 1 — Foundation

  • Semantic PR title validation
  • AI rules sync check
  • Docs and governance files
  • Secret scan
  • Existing lint/test/build checks (report-only coverage)

Phase 2 — Automation

  • Reusable workflows
  • Dependabot
  • Release Please (owns release PRs, CHANGELOG.md, GitHub releases, and tags — see release-process.md)
  • Coverage reporting (still report-only)

Phase 3 — Strictness

  • Coverage thresholds (only when stable)
  • Stricter typechecking
  • Deeper security scanning (CodeQL, dependency review)

Licensing

  • Public/open-source repos should use an explicit open-source license (MIT is the default recommendation).
  • Private/proprietary repos should use a proprietary/all-rights-reserved notice.
  • Do not change license terms casually. The .repo-policy.yml visibility and license fields should match the chosen license.

License templates: templates/licenses/LICENSE-MIT.txt, templates/licenses/LICENSE-PROPRIETARY.txt.

Repository health files

Required for new repos

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

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

See repo-standard-v1.md for full health file requirements.