diff --git a/README.md b/README.md index 14cde09..b71f54d 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,8 @@

Agent Rules

Forkable modular agent rules with 1-step assembly for local AI coding assistants.

+ Explore the docs » +

Report Bug · Request Feature @@ -25,6 +27,7 @@

  • Installation
  • Usage
    • +
  • Changelog
  • Contributing
  • Contact
    • @@ -144,6 +147,12 @@ Public README blanks live in [dev-centr/readme-template](https://github.com/dev-

    (back to top)

    +## Changelog + +Notable functional changes: [changelog on the docs site](https://docs.devcentr.org/agent-rules/changelog.html). + +

    (back to top)

    + ## Contributing Add a license file if you want this repository to be reusable by others. Pull requests with portable rule improvements are welcome. diff --git a/RULES.md b/RULES.md index f08a39c..da305dd 100644 --- a/RULES.md +++ b/RULES.md @@ -35,14 +35,14 @@ ## Creator (owned orgs) - Transfers: `gh api`. - Config: SDL (`.sdl`) for DevCentr-owned / `sdlang-d` surfaces; **KDL** (`.kdl`) for greenfield outside that stack; JSON5 when stuck in the JSON family. Do **not** adopt Extended SDL/XDL. -- Changelog: every project; README links to it; timeline + `changelog-details/date - title`. +- Changelog: every project; functional changes; README links to it; index + `changelog-details/date - title`; backfill from git if missing; wire into docs; alert user if cross-org secrets are required. ## Docs - Structure: Diátaxis (tutorials, how-to, explanation, reference). -- Format: AsciiDoc unless host requires Markdown (e.g. npm). -- Antora: follow `dev-centr` publishing guidance. +- Format: AsciiDoc by default; retain Markdown on upstream forks; keep/add Markdown when a package registry only parses Markdown. +- Antora: Valentus theme + org branding; Lunr + `antora-supplemental` AI search (`antora-search-chat`); follow `dev-centr` publishing guidance. If those extensions cannot be found, alert the user and wait. - **One Antora site per org** with a hub (e.g. docs.devcentr.org): wire `docs/` into the hub playbook; never publish a second Antora site on project GitHub Pages. Deduplicate errant sites. See `general/antora-docs-sites.md`. (Does not apply to mixing Antora with other docs systems.) -- **Public README layout:** when creating/revising GitHub-facing READMEs, follow `general/readme-layout.md` (Best-README adapted: linked badges, centered header, role-grouped Built With, back-to-top). Hand-edit per repo; blanks in `dev-centr/readme-template`. +- **Public README layout:** when creating/revising GitHub-facing READMEs, follow `general/readme-layout.md` (Best-README adapted: centered for-the-badge chrome, **Explore the docs »** → org hub, TOC if >3 sections, role-grouped Built With, back-to-top). Do not add Docs/CI shields that break the established look. Hand-edit per repo; blanks in `dev-centr/readme-template`. - Titles: follow site `STYLE.adoc` / `AGENTS.md` (not MEMORIES). Short defaults — first-party news omits org; action essays pass implied [On] and drop surplus *the*; prefer `X as Y` / *when* / disproof / questions over rigid `X is Y`; attach floating modifiers to an object; docs topics = concept names. Philosophy: `Titles as orientation`. Cursor rules = `.cursor/rules/*.mdc` dir; this file stays the paste preamble. - Project facts: `AGENTS.md` + README/docs. Do not commit per-repo `MEMORIES.md`. - **App shipping architecture:** when scaffolding/building/shipping apps, read `general/app-architecture.md` and adhere to Software Product Essentials under `$CODE_ROOT/github.com/dev-centr/general-knowledge/docs/modules/ROOT/pages/explanation/architecture/` (hub: `software-product-essentials.adoc`). About/build info, debug dump, Windows auto-update, installers, and CI release pipelines are core—not polish. diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 6978e58..559e360 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1,3 +1,4 @@ * xref:index.adoc[Overview] * xref:usage.adoc[Usage] * xref:architecture.adoc[Architecture] +* xref:changelog.adoc[Changelog] diff --git a/docs/modules/ROOT/pages/changelog-details/2026-03-23 - Initial forkable agent rules.adoc b/docs/modules/ROOT/pages/changelog-details/2026-03-23 - Initial forkable agent rules.adoc new file mode 100644 index 0000000..29eb620 --- /dev/null +++ b/docs/modules/ROOT/pages/changelog-details/2026-03-23 - Initial forkable agent rules.adoc @@ -0,0 +1,14 @@ += 2026-03-23 — Initial forkable agent rules + +== Summary + +First public release of canonical forkable agent rules for Dev-Centr coding assistants. + +== Changes + +* Repository structure: `general/`, `profiles/`, `RULES.md`, `README.md`. +* **1-step assembly** — Paste `RULES.md`; agent batches reads of profile + general modules via native file tools. +* Split OS layers: `general/windows.md`, `general/mac.md`, `general/linux.md` selected by profile `ENVIRONMENT`. +* Added `general/documentation.md`, trimmed `general/creator.md`, placeholder profiles with required constants. +* README: profile constants table; clone vs paste-only setup; human vs agent audience clarification. +* `RULES.md` as agent-directed entrypoint. diff --git a/docs/modules/ROOT/pages/changelog-details/2026-03-31 - RULES.md preamble consolidation.adoc b/docs/modules/ROOT/pages/changelog-details/2026-03-31 - RULES.md preamble consolidation.adoc new file mode 100644 index 0000000..9067cc6 --- /dev/null +++ b/docs/modules/ROOT/pages/changelog-details/2026-03-31 - RULES.md preamble consolidation.adoc @@ -0,0 +1,12 @@ += 2026-03-31 — RULES.md preamble consolidation + +== Summary + +Reorganized the human vs agent entrypoints and clarified workstation memory location. + +== Changes + +* `MAIN.md` — Human-oriented assembly entrypoint listing modules to paste or compose. +* `RULES.md` — Generalized consolidated preamble for direct paste into agent rules fields. +* Clarified **`$CODE_ROOT/MEMORIES.md`** as canonical workstation memory (not per-repo `MEMORIES.md` in this clone). +* `MEMORIES.example.md` committed as format reference; per-repo copy remains gitignored. diff --git a/docs/modules/ROOT/pages/changelog-details/2026-08-03 - App shipping architecture layer.adoc b/docs/modules/ROOT/pages/changelog-details/2026-08-03 - App shipping architecture layer.adoc new file mode 100644 index 0000000..ca4eff5 --- /dev/null +++ b/docs/modules/ROOT/pages/changelog-details/2026-08-03 - App shipping architecture layer.adoc @@ -0,0 +1,11 @@ += 2026-08-03 — App shipping architecture layer + +== Summary + +Agents scaffolding or shipping applications must follow product-architecture guidance, not just coding style rules. + +== Changes + +* Added `general/app-architecture.md` optional layer. +* `RULES.md` — Point agents at Software Product Essentials under `general-knowledge` when building apps (About, updates, installers, CI release pipelines as core—not polish). +* Separated app shipping architecture from Dev-Centr product automation (`devcentr-agent-rules`). diff --git a/docs/modules/ROOT/pages/changelog-details/2026-08-06 - README layout and Antora org policy.adoc b/docs/modules/ROOT/pages/changelog-details/2026-08-06 - README layout and Antora org policy.adoc new file mode 100644 index 0000000..e07d171 --- /dev/null +++ b/docs/modules/ROOT/pages/changelog-details/2026-08-06 - README layout and Antora org policy.adoc @@ -0,0 +1,13 @@ += 2026-08-06 — README layout and one Antora site policy + +== Summary + +Documented public README layout conventions and org-wide Antora publishing policy. + +== Changes + +* `general/readme-layout.md` — Best-README–adapted layout: HTML-linked shields in centered header, role-grouped Built With, back-to-top, contrib.rocks tiering. +* `general/antora-docs-sites.md` — **One Antora site per org**; wire `docs/` into hub playbook; dedupe secondary GitHub Pages Antora sites. +* `general/creator.md` — Prefer SDL (`.sdl`) in DevCentr stack; KDL (`.kdl`) greenfield; ban Extended SDL/XDL. +* `RULES.md` / README — Sync-before-work habit; rules-manager path for composed rules. +* README aligned with public template layout (centered chrome, TOC, Built With). diff --git a/docs/modules/ROOT/pages/changelog-details/2026-08-07 - Antora component docs.adoc b/docs/modules/ROOT/pages/changelog-details/2026-08-07 - Antora component docs.adoc new file mode 100644 index 0000000..39b685b --- /dev/null +++ b/docs/modules/ROOT/pages/changelog-details/2026-08-07 - Antora component docs.adoc @@ -0,0 +1,12 @@ += 2026-08-07 — Antora component docs + +== Summary + +Introduced an Antora documentation component for this repository and scrubbed personal-repo references from public-facing text. + +== Changes + +* Added `docs/antora.yml` and ROOT pages: overview, usage, architecture. +* Wired component into `dev-centr/docs` hub playbook (`agent-rules` source). +* README and docs point at `https://docs.devcentr.org/agent-rules/` instead of personal clones. +* Distinguished **agent-rules** (forkable end-user rules) from **devcentr-agent-rules** (product automation). diff --git a/docs/modules/ROOT/pages/changelog-details/2026-08-08 - Documentation standards expansion.adoc b/docs/modules/ROOT/pages/changelog-details/2026-08-08 - Documentation standards expansion.adoc new file mode 100644 index 0000000..b9f5a81 --- /dev/null +++ b/docs/modules/ROOT/pages/changelog-details/2026-08-08 - Documentation standards expansion.adoc @@ -0,0 +1,15 @@ += 2026-08-08 — Documentation standards expansion + +== Summary + +Expanded agent-facing documentation rules so README, Antora, and changelog expectations match Dev-Centr org docs automation practice. + +== Changes + +* `RULES.md` — AsciiDoc-by-default README format; Valentus + Lunr + `antora-search-chat`; changelog backfill and cross-repo wiring alerts. +* `general/readme-layout.md` — Format-choice table; **Explore the docs »** hub CTA instead of a Docs shield; optional CI badges; TOC when >3 sections. +* `general/documentation.md` — Valentus default UI; Lunr + AI search extensions; alert-and-wait if `antora-supplemental` is missing. +* `general/creator.md` — Functional changelog requirement; index + `changelog-details/` structure; git backfill; cross-org secret alerts. +* `general/antora-docs-sites.md` — Default UI and search section. +* `general/global.md` — Load `antora-docs-sites.md` and `readme-layout.md` when relevant. +* `README.md` — Centered **Explore the docs »** link to `https://docs.devcentr.org/agent-rules/`. diff --git a/docs/modules/ROOT/pages/changelog-details/index.adoc b/docs/modules/ROOT/pages/changelog-details/index.adoc new file mode 100644 index 0000000..f36af48 --- /dev/null +++ b/docs/modules/ROOT/pages/changelog-details/index.adoc @@ -0,0 +1,10 @@ += Changelog details + +Full changelog entries for xref:changelog.adoc[agent-rules]. + +* xref:2026-08-08 - Documentation standards expansion.adoc[2026-08-08 — Documentation standards expansion] +* xref:2026-08-07 - Antora component docs.adoc[2026-08-07 — Antora component docs] +* xref:2026-08-06 - README layout and Antora org policy.adoc[2026-08-06 — README layout and one Antora site policy] +* xref:2026-08-03 - App shipping architecture layer.adoc[2026-08-03 — App shipping architecture layer] +* xref:2026-03-31 - RULES.md preamble consolidation.adoc[2026-03-31 — RULES.md preamble consolidation] +* xref:2026-03-23 - Initial forkable agent rules.adoc[2026-03-23 — Initial forkable agent rules] diff --git a/docs/modules/ROOT/pages/changelog.adoc b/docs/modules/ROOT/pages/changelog.adoc new file mode 100644 index 0000000..3338dbd --- /dev/null +++ b/docs/modules/ROOT/pages/changelog.adoc @@ -0,0 +1,47 @@ += Changelog +:description: Notable functional changes to forkable agent rules, profiles, and documentation standards. + +Timeline of notable changes to **agent-rules**. +Detailed notes live under xref:changelog-details/index.adoc[changelog-details]. + +== 2026-08-08 — Documentation standards expansion + +xref:changelog-details/2026-08-08 - Documentation standards expansion.adoc[Details] + +* Expanded README, Antora, and changelog guidance across `RULES.md` and `general/*.md`. +* README header: **Explore the docs »** hub CTA; no separate Docs/CI shields in the centered chrome. + +== 2026-08-07 — Antora component docs + +xref:changelog-details/2026-08-07 - Antora component docs.adoc[Details] + +* Added Antora component under `docs/` (overview, usage, architecture). +* Removed personal-repo path examples from upstream-facing text. + +== 2026-08-06 — README layout and one Antora site policy + +xref:changelog-details/2026-08-06 - README layout and Antora org policy.adoc[Details] + +* Documented Best-README–adapted public README layout (`general/readme-layout.md`). +* **One Antora site per org** policy; dedupe errant per-repo GitHub Pages Antora builds. +* SDL in-stack / KDL greenfield config rules; sync-before-work habit in rules. + +== 2026-08-03 — App shipping architecture layer + +xref:changelog-details/2026-08-03 - App shipping architecture layer.adoc[Details] + +* Agents building apps must read `general/app-architecture.md` and Software Product Essentials. + +== 2026-03-31 — RULES.md preamble consolidation + +xref:changelog-details/2026-03-31 - RULES.md preamble consolidation.adoc[Details] + +* Consolidated paste preamble into `RULES.md`; `MAIN.md` as human assembly entrypoint. +* Clarified `$CODE_ROOT/MEMORIES.md` as the canonical workstation memory file. + +== 2026-03-23 — Initial forkable agent rules + +xref:changelog-details/2026-03-23 - Initial forkable agent rules.adoc[Details] + +* Canonical forkable rules for Dev-Centr coding assistants. +* 1-step assembly architecture, OS-specific layers, placeholder profiles with `ENVIRONMENT`. diff --git a/general/antora-docs-sites.md b/general/antora-docs-sites.md index 76ae515..831cfbf 100644 --- a/general/antora-docs-sites.md +++ b/general/antora-docs-sites.md @@ -36,3 +36,8 @@ When you find a secondary Antora site in an Antora org: - Repo-local `antora-playbook.yml` for **developer preview** of one component is fine if it does **not** get published as an org-facing site. - Production publish path for Dev-Centr Antora components is always the `dev-centr/docs` aggregator. + +## Default UI and search + +- Prefer **Valentus** (`antora-supplemental/valentus-theme`) with org brand colors/logo from the org’s central assets. +- Every published site: `@antora/lunr-extension` plus the AI search/help extension from `antora-supplemental` (`antora-search-chat`; see also `antora-ai-help-extension`). Details in `general/documentation.md`. diff --git a/general/creator.md b/general/creator.md index 7edbb1a..2591d6e 100644 --- a/general/creator.md +++ b/general/creator.md @@ -16,7 +16,9 @@ Do not apply these rules to third-party open-source contributions unless explici ## Changelogs -- When you create a project, integrate a changelog into its docs. If it lacks docs, put the changelog in the repo base. +- All **functional** changes should appear in the changelog. Prefer the project’s existing changelog style when one exists (`general/global.md`). +- When you create a project, integrate a changelog into its docs (or docs substructure for an existing documentation system). If it lacks docs, put the changelog in the repo base. - Put a link to the changelog in the README in a Changelog section. -- The changelog should contain a timeline with quick summaries and links to very detailed changelogs for each date in a `changelog-details` subfolder that names files by `date - title`. -- If you add docs afterward, update its changelog structure. +- Structure: an index page named **changelog** (timeline of dates + short summaries + links) and detail pages under `changelog-details/` named `date - title`. Wire the changelog into the active docs system (Antora nav, etc.) when docs exist. +- If no changelog exists, **create it** and **backfill** from observed functional changes in git history. Unpack commits when the subject line is too thin. +- Wiring may require commits in **related** repositories (e.g. org docs hub playbook). If any of those repos cross **org** boundaries and CI/docs fetch needs auth, **alert the user** that a cross-repo deploy key or org/repo secret must be added (say which secret and which org/repo). diff --git a/general/documentation.md b/general/documentation.md index 66b9e23..ecc749e 100644 --- a/general/documentation.md +++ b/general/documentation.md @@ -9,8 +9,11 @@ Read this file when you **author, structure, or publish** project documentation ## Antora (when used) +- **Default stack:** Antora + **Valentus** UI (`antora-supplemental/valentus-theme`). Customize colors and logo from the org’s existing brand assets (org `.github` profile, eponymous site repo, or other central branding repo)—do not invent a one-off palette per component. - If the project uses **Antora**, follow the publishing and layout guidance in the Dev-Centr documentation repository: `dev-centr/devcentr` — see `docs/modules/publishing/pages/antora-deployment.adoc` for deployment-oriented details. -- **One Antora site per org** that already has a hub (e.g. https://docs.devcentr.org). Do not publish secondary per-repo Antora sites on GitHub Pages. Keep `docs/` in the product repo; **wire** into the hub playbook. See `general/antora-docs-sites.md`. Actively deduplicate when you find errant sites. Does **not** apply to mixtures of different docs systems (Antora + Fumadocs is fine). +- **One Antora site per org** that already has a hub (e.g. https://docs.devcentr.org). Do not publish secondary per-repo Antora sites on GitHub Pages. Keep `docs/` in the product repo; **wire** into the hub playbook. See `general/antora-docs-sites.md`. Actively deduplicate when you find errant sites. Does **not** apply to mixtures of different docs systems (Antora + Fumadocs is fine). Repo-local `antora-playbook.yml` for **preview/validation CI** is fine if it does **not** publish a second public site. +- **Search:** Enable `@antora/lunr-extension` on every published Antora site. Add the AI-assisted search/help layer from **`antora-supplemental`** — prefer [`@antora-supplemental/antora-search-chat`](https://github.com/antora-supplemental/antora-search-chat) (Lunr-first Search/Ask omnibox). Related: [`antora-ai-help-extension`](https://github.com/antora-supplemental/antora-ai-help-extension). Register Lunr before wrappers that depend on it. +- If `antora-supplemental` (or those extensions) cannot be found after a reasonable search (rename/move), **stop and alert the user** (email, Slack, or whatever channel is available) so they can notify whoever owns this automation rule — then wait for a reply before inventing a substitute. ## Relationship to creator rules diff --git a/general/global.md b/general/global.md index e3dac59..fba6e71 100644 --- a/general/global.md +++ b/general/global.md @@ -35,6 +35,8 @@ These apply universally unless a profile says otherwise. - If `ENVIRONMENT` is missing, ask the user which file applies before assuming an OS. - You **must** read `general/creator.md` before acting. - Read `general/documentation.md` when you are authoring, structuring, or publishing project documentation (optional layer for doc-heavy work). +- Read `general/antora-docs-sites.md` when the task involves Antora sites, playbooks, GitHub Pages for docs, or wiring components into an org docs hub. +- Read `general/readme-layout.md` when creating or revising a GitHub-facing README. - Read `general/app-architecture.md` when you are scaffolding, building, shipping, packaging, or maintaining an application, CLI, TUI, publishable library, game client, or service (optional layer; points at local Software Product Essentials docs). ## Memory management diff --git a/general/readme-layout.md b/general/readme-layout.md index c0f716e..e389a3b 100644 --- a/general/readme-layout.md +++ b/general/readme-layout.md @@ -2,11 +2,28 @@ Read this when creating or revising a **GitHub-facing** `README.md` / `README.adoc` for owned or org repos. Structure inspiration: [othneildrew/Best-README-Template](https://github.com/othneildrew/Best-README-Template). Canonical blanks: [dev-centr/readme-template](https://github.com/dev-centr/readme-template) (fork to other orgs / personal profile as needed). -Do **not** batch-script README rewrites across repos. Hand-edit each file so stack grouping, contact, and omitted sections stay accurate. +Do **not** batch-script README rewrites across repos. Hand-edit each file so stack grouping, contact, and omitted sections stay accurate. Not every repo needs the full template — omit fields that will never apply (e.g. no logo). That template assumes the repo is a project hub; lighter repos stay simpler. + +## Format choice + +| Situation | README format | +|-----------|----------------| +| **Default (owned / first-party)** | Prefer **AsciiDoc** (`README.adoc`). On GitHub, use embedded HTML for the centered title/header; use `[.text-center]` (or HTML) for other centered blocks. | +| **Fork of an upstream project** | **Retain Markdown** if upstream is Markdown. Do not convert away from the fork’s face format. | +| **Package registry that only parses Markdown** (npm, crates.io listing copy, etc.) | Keep or add a **Markdown** README (or registry-facing copy) for the registry. Do **not** delete a Markdown copy that exists for that reason. Deep docs may still be AsciiDoc/Antora. | +| **Major user-facing + Best-README HTML centering** | GitHub’s AsciiDoc subset centers poorly; **`README.md`** as the repo face is fine (deep docs under `docs/`). | + +## Docs link (org repos) + +For **organization** repositories with a README: include an **Explore the docs »** text link in the centered header (same pattern as `dev-centr/readme-template` / `switchyard`), pointing at the **org docs hub** component URL (e.g. `https://docs.devcentr.org//`), not a secondary per-repo Pages Antora site. Do **not** add a separate `Docs | Org` shield — that fights the established contributors/forks/stars/issues/(license) chrome. + +**CI status badges** are optional. Prefer leaving them out of the centered header unless the repo already uses one; do not require a CI chip for every workflow-enabled repo. + +Personal-user repos: skip the org-hub docs CTA unless that user publishes a docs site you should link. ## Why the prior refresh broke -1. **Badge targets** — Shields must open the *thing they represent* (contributors graph, stargazers, issues, license blob, tech homepage). Never the shield image URL. +1. **Badge targets** — Shields must open the *thing they represent* (contributors graph, stargazers, issues, license blob, tech homepage). Never the shield image URL. Docs discovery is the **Explore the docs »** text link (hub URL), not an extra Docs shield. 2. **Markdown inside `
    `** — GitHub often does **not** resolve `[![x][shield]][url]` inside HTML blocks, so badges appear to link only to the image (or nowhere useful). **In the centered header, use HTML:** `…`. 3. **AsciiDoc `env-github` trap** — Do **not** strip `link=` under `ifdef::env-github[]`. Prefer HTML `` on GitHub, or always keep `link=` on `image:` macros. 4. **Centering** — One centered block for **badges + title + one-liner + quick links**. Title-only centering with badges left above is incomplete. @@ -17,11 +34,13 @@ Do **not** batch-script README rewrites across repos. Hand-edit each file so sta | Audience | Layout | |----------|--------| -| **User-facing / downstream** (apps, installable CLIs, public libs, product sites) | Full: centered header, linked shields, structured Built With, TOC, section back-to-top, Contact, optional contrib.rocks | +| **User-facing / downstream** (apps, installable CLIs, public libs, product sites) | Full: centered header (contributors/forks/stars/issues/license as applicable), **Explore the docs »** → hub when docs exist, structured Built With, TOC when >3 sections, section back-to-top, Contact, optional contrib.rocks | | **Internal / non-downstream** | Simplified: linked shields + short About + install/usage if needed + License/Contact. Skip LinkedIn, empty Roadmap/Acknowledgments, contrib.rocks, demo marketing links | | **Skip** | School repos, org `.github` profiles, archived, package-tap / registry-instruction-only, empty repos | -Prefer keeping `README.adoc` when the repo is AsciiDoc-native **except** major user-facing repos that need Best-README HTML centering: GitHub’s AsciiDoc subset does not center like Markdown. For those, use **`README.md`** as the repo face (deep docs stay under `docs/`). +## Table of contents + +Include a TOC when the README has **more than three** sections (collapsible `
    ` is fine on Markdown). ## Markdown header (required shape) @@ -39,7 +58,7 @@ Prefer keeping `README.adoc` when the repo is AsciiDoc-native **except** major u

    project_description
    -     Explore the docs » + Explore the docs »

    View Demo @@ -51,7 +70,7 @@ Prefer keeping `README.adoc` when the repo is AsciiDoc-native **except** major u

    ``` -Omit license badge / demo / docs links when absent. Collapsible TOC via `
    ` is fine. +Omit license / demo / docs links when absent. Point **Explore the docs** at the org hub component URL when the org has a docs site. Collapsible TOC via `
    ` is fine when the README has more than three sections. ### Built With (outside the HTML header)