Skip to content

Detection

The repo standard detector recommends a starting profile and relevant templates for a target repository. It is read-only and advisory.

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

Principles

Detection is:

  • read-only — never modifies the target repository
  • advisory — recommends; does not enforce
  • evidence-based — lists files and content matches that drove the recommendation
  • conservative — prefers mixed-special when uncertain
  • intended to recommend a starting profile and relevant modules

Once a project adopts the standard, .repo-policy.yml is the source of truth.

Usage

python3 /path/to/repo-standards/scripts/detect_repo_standard.py --repo /path/to/project
python3 /path/to/repo-standards/scripts/detect_repo_standard.py --repo /path/to/project --format json
python3 /path/to/repo-standards/scripts/detect_repo_standard.py --repo /path/to/project --format markdown

Markdown is the default output format.

What it detects

Field Possible values
language typescript, python, mixed, unknown
package_manager npm, pnpm, yarn, bun, pip-requirements, uv, poetry, unknown
deployment_provider cloudflare, gcp, railway, none, unknown
recommended_profile See profiles.md

Example JSON output

{
  "language": "typescript",
  "package_manager": "npm",
  "deployment_provider": "cloudflare",
  "recommended_profile": "typescript-cloudflare-worker",
  "confidence": 0.92,
  "evidence": [
    "package.json exists",
    "wrangler.toml exists",
    ".github/workflows/deploy.yml mentions wrangler"
  ],
  "recommended_templates": [
    "templates/repo-policy.typescript-cloudflare.yml",
    "templates/rulesync.jsonc",
    "ai/rules/*",
    "templates/workflows/semantic-pull-request.yml",
    "templates/workflows/ai-rules-check.yml",
    "templates/workflows/docs-check.yml",
    "templates/workflows/secret-scan.yml",
    "templates/dependabot.yml"
  ],
  "manual_review": [
    "Verify deploy workflow should remain repo-specific"
  ]
}
Concept Description
Detected state What the script infers from files (language, package manager, deploy provider)
Recommended profile Starting profile based on detection rules in profiles/detection.yml
Adopted .repo-policy.yml What the repo owner sets after review — authoritative

The detector may recommend typescript-cloudflare-worker, but the owner may choose typescript-app if the project is transitioning away from Workers. That is fine — update .repo-policy.yml accordingly.

Detection rules

Declarative rules live in profiles/detection.yml. The script loads this file when PyYAML is available; otherwise it uses built-in defaults.

Manual review notes

The detector may flag items requiring human judgment:

  • Unusual monorepo layouts
  • Multiple deploy providers detected
  • Could not confidently detect language/profile
  • Deploy workflow should remain repo-specific during first migration

Always review .repo-policy.yml before adopting the standard.

GitHub Models-assisted detection

For ambiguous repositories, an optional advisory layer can call GitHub Models to interpret detection signals. It does not replace deterministic detection or .repo-policy.yml.

See github-models-detection.md.