Skip to content

Latest commit

 

History

History
44 lines (40 loc) · 4.41 KB

AGENTS.md

File metadata and controls

44 lines (40 loc) · 4.41 KB

AGENTS.md

Guidance for AI coding agents working in this repository. Human contributors should read docs/CONTRIBUTING.md; this file is the single source of truth for agents.

Purpose

A personal homelab and DevOps knowledge base: Markdown cheat sheets with quick-scan command tables for tools, platforms and concepts. There is no build step for the sheets themselves: the repository is Markdown plus small checker scripts and CI config. site/ holds the Hugo site that publishes them (see site/SITE.md).

Layout

  • One folder per theme (linux/, docker/, kubernetes/, networking/, tools/, apps/, and others; new themed folders such as security/ or backup/ appear over time). One sheet per file.
  • README.md: intro and the generated sheet index, grouped by folder.
  • docs/CONTRIBUTING.md and docs/_template.md: house style and a starting template. Folder choice guide is in CONTRIBUTING.
  • scripts/check-links.py: link, anchor and file checker.
  • scripts/gen-index.py: generates the README.md index (--check in CI).
  • .github/PULL_REQUEST_TEMPLATE.md and .github/PULL_REQUEST_TEMPLATE/: default PR template plus new-sheet.md and update-sheet.md (select with ?template=). Fill in the matching one in PR descriptions.
  • .github/ISSUE_TEMPLATE/: issue forms (request-sheet.yml, report-error.yml) and config.yml (blank issues disabled). Keep the folder dropdown in request-sheet.yml in step with the folders listed in CONTRIBUTING.
  • .github/workflows/external-links.yml and .lychee.toml: weekly external link check (lychee), opens one "Broken external links" issue. Not run on PRs.
  • scripts/check-ips.py and .ip-allowlist: flags real-looking public IPv4 addresses. .github/workflows/secret-scan.yml runs it plus gitleaks in CI.
  • scripts/check-freshness.py, .freshness-ignore-revs and .github/workflows/freshness.yml: monthly report of sheets untouched for over 12 months (one "Stale sheets to re-verify" issue). List mechanical bulk-edit commits in .freshness-ignore-revs. The same script also supplies the dates shown on the website.
  • site/ and .github/workflows/pages.yml: the Hugo site (see site/SITE.md). site/scripts/prepare-content.py imports scripts/check-freshness.py (last_touched, load_ignored, is_stale) for each sheet's "Updated" date and stale chip, so keep those names and signatures stable.
  • .markdownlint-cli2.yaml, .github/workflows/lint.yml: CI checks.

House Style

  • First line # Title, then a one or two sentence intro, then optional Documentation: and Project: link lines.
  • ## sections. Commands in COMMAND | DESCRIPTION tables with the command in backticks (escape literal pipes as \|).
  • Multi-line commands and config in fenced blocks with a language tag.
  • Placeholders in ALL CAPS or <ANGLE_BRACKETS>.
  • Cross-link with relative Markdown links including .md (e.g. [Docker](../docker/docker.md)), link text is the target's H1. Never use [[wikilinks]].
  • Kebab-case file names. No empty or title-only files.
  • British English, terse.

Rules

  1. Never invent commands, flags, options or defaults. Verify against the official documentation (or by running the command) before writing it.
  2. Mark anything you could not verify as unverified in the sheet, and say so in the PR description.
  3. No secrets, tokens, real IP addresses, internal hostnames or personal domains. Use placeholders, example.com and documentation ranges (192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24).
  4. Keep every relative link and #anchor valid. When you rename or delete a sheet, fix the links that point to it.
  5. When you add a sheet, regenerate the README.md index (python3 scripts/gen-index.py), and update any site or content list the repository keeps, in the same PR. ([params.sectionDescriptions] and [params.sectionGlyphs] in site/hugo.toml are optional per-folder extras for the home page.)
  6. Edit only what the task requires. Do not reformat unrelated sheets.
  7. Run all three checks before opening a PR and fix what they report in the content, not by loosening the config:
    • python3 scripts/check-links.py
    • python3 scripts/gen-index.py --check
    • npx markdownlint-cli2 "**/*.md"
    • python3 scripts/check-ips.py
  8. Work on a branch and open a pull request. Never push to master. Do not change repository settings or branch protection.
  9. Do not edit renovate.json or the shared preset it extends.
  10. Keep temporary files outside the repository.