diff --git a/README.md b/README.md index 14cde09..65fe18c 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ Forks Stargazers Issues + Docs

Agent Rules

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

@@ -26,6 +27,7 @@
  • Installation
  • Usage
  • Contributing
    • +
  • Changelog
  • Contact
    • @@ -156,6 +158,12 @@ Add a license file if you want this repository to be reusable by others. Pull re

    (back to top)

    +## Changelog + +Notable changes are recorded in the docs changelog: https://docs.devcentr.org/agent-rules/changelog.html + +

    (back to top)

    + ## Contact DevCentr.org - support@devcentr.org diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 6978e58..2940513 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1,3 +1,8 @@ * xref:index.adoc[Overview] * xref:usage.adoc[Usage] +* xref:assembly.adoc[Assembly] +* xref:profiles.adoc[Profiles] * xref:architecture.adoc[Architecture] +* xref:modules-reference.adoc[Module reference] +* xref:troubleshooting.adoc[Troubleshooting] +* xref:changelog.adoc[Changelog] diff --git a/docs/modules/ROOT/pages/assembly.adoc b/docs/modules/ROOT/pages/assembly.adoc new file mode 100644 index 0000000..81331f6 --- /dev/null +++ b/docs/modules/ROOT/pages/assembly.adoc @@ -0,0 +1,55 @@ += Assembly + +Agent rules assemble in one batched read when the harness has filesystem access. + +== Entry points + +[cols="1,2"] +|=== +| File | When to use + +| `RULES.md` +| Paste into an app's system prompt or custom instructions. Fill the Constants block at the top before saving. + +| `MAIN.md` +| Modular assembly file when you want explicit parallel-read instructions and optional module gating (documentation, Antora, app architecture). + +| rules-manager +| Compose global + machine sections into `$CODE_ROOT/agent-rules.composed.md` with file watching. https://github.com/dev-centr/rules-manager[`dev-centr/rules-manager`] +|=== + +== Parallel read set (MAIN.md) + +When `$AGENT_RULES_PATH` points at this clone, the agent reads **simultaneously**: + +1. `profiles/.md` +2. `general/global.md` +3. `general/environment.md` +4. `general/.md` (from profile `ENVIRONMENT` or host OS) +5. `general/creator.md` +6. `general/folder-schema.md` + +Conditionally (task-gated in `MAIN.md`): + +* `general/documentation.md` — authoring or publishing docs +* `general/antora-docs-sites.md` — Antora sites, playbooks, hub wiring +* `general/readme-layout.md` — GitHub-facing README layout +* `general/app-architecture.md` — building or shipping applications + +Plus **`$CODE_ROOT/MEMORIES.md`** for workstation facts. + +== Why one step + +Local harnesses (Cursor, Windsurf, VS Code agents) support native file reads. Batching avoids: + +* Multi-turn ping-pong between modules +* CLI `cat` truncation on large rule sets +* Partial context when the agent stops after the first file + +== Paste-only fallback + +If the host cannot read the filesystem, `RULES.md` obligations are the only source. Fill Constants manually; you lose modular depth until filesystem access is available. + +== Dev-Centr product automation + +When the **Dev-Centr application** acts on behalf of the user, load https://github.com/dev-centr/devcentr-agent-rules[`devcentr-agent-rules`] instead of this repository. See xref:architecture.adoc[Architecture]. diff --git a/docs/modules/ROOT/pages/changelog-details/2026-03-23 - initial-forkable-rules.adoc b/docs/modules/ROOT/pages/changelog-details/2026-03-23 - initial-forkable-rules.adoc new file mode 100644 index 0000000..e399865 --- /dev/null +++ b/docs/modules/ROOT/pages/changelog-details/2026-03-23 - initial-forkable-rules.adoc @@ -0,0 +1,26 @@ += 2026-03-23 – Initial forkable rules and 1-step assembly + +== Initial repository + +Canonical forkable agent rules and profiles for Dev-Centr coding assistants. + +Structure: + +* `general/` — portable rule modules (global, environment, OS layers, creator, folder-schema, documentation). +* `profiles/` — machine constants templates (`CODE_ROOT`, `ENVIRONMENT`, optional `GITHUB_USER`, `ISSUES_REPO`). +* `RULES.md` — agent-directed preamble; commands 1-step assembly. +* `MAIN.md` — modular assembly with parallel file reads. + +== OS layers + +Split platform specifics into `general/windows.md`, `general/mac.md`, `general/linux.md`. Profile constant `ENVIRONMENT` selects the active layer. + +== 1-step assembly + +Optimized for local harnesses with filesystem access: agent batches semantic reads of profile + general modules in one turn instead of sequential CLI `cat` (avoids truncation and ping-pong). + +== README + +* Profile constants table. +* Full clone vs paste-only setup paths. +* Clarified human (README) vs agent (`RULES.md`) audience. diff --git a/docs/modules/ROOT/pages/changelog-details/2026-03-31 - main-entrypoint-and-memories.adoc b/docs/modules/ROOT/pages/changelog-details/2026-03-31 - main-entrypoint-and-memories.adoc new file mode 100644 index 0000000..a30e73d --- /dev/null +++ b/docs/modules/ROOT/pages/changelog-details/2026-03-31 - main-entrypoint-and-memories.adoc @@ -0,0 +1,13 @@ += 2026-03-31 – MAIN.md entrypoint and MEMORIES clarification + +== MAIN.md modular entrypoint + +`MAIN.md` became the modular context-assembly file listing parallel reads from `profiles/` and `general/`. `RULES.md` remains the consolidated paste preamble for apps without filesystem access. + +== MEMORIES location + +Documented **`$CODE_ROOT/MEMORIES.md`** as the single workstation memory file: + +* Gitignored; never committed. +* Per-repo `MEMORIES.md` deprecated for project facts (use `AGENTS.md` + docs). +* Format template: `MEMORIES.example.md` in this repository. diff --git a/docs/modules/ROOT/pages/changelog-details/2026-08-03 - software-product-essentials.adoc b/docs/modules/ROOT/pages/changelog-details/2026-08-03 - software-product-essentials.adoc new file mode 100644 index 0000000..f8e79f8 --- /dev/null +++ b/docs/modules/ROOT/pages/changelog-details/2026-08-03 - software-product-essentials.adoc @@ -0,0 +1,7 @@ += 2026-08-03 – Software Product Essentials pointer + +Added `general/app-architecture.md` directing agents to the general-knowledge **Software Product Essentials** hub when scaffolding, building, shipping, or packaging applications. + +Covers About/build info, debug dump, Windows auto-update, installers, and CI release pipelines as core product architecture — not polish. + +Cross-reference: `general-knowledge` → `software-product-essentials.adoc`. diff --git a/docs/modules/ROOT/pages/changelog-details/2026-08-06 - antora-policy-and-readme-layout.adoc b/docs/modules/ROOT/pages/changelog-details/2026-08-06 - antora-policy-and-readme-layout.adoc new file mode 100644 index 0000000..8082565 --- /dev/null +++ b/docs/modules/ROOT/pages/changelog-details/2026-08-06 - antora-policy-and-readme-layout.adoc @@ -0,0 +1,25 @@ += 2026-08-06 – Antora org policy and README layout rules + +== Antora org policy + +Added `general/antora-docs-sites.md`: + +* One Antora site per org with a hub (Dev-Centr → https://docs.devcentr.org). +* Product repos keep `docs/` close to code; wire into hub playbook — do not publish secondary per-repo Antora sites on GitHub Pages. +* Actively deduplicate errant standalone Antora Pages deployments. + +Referenced from `general/documentation.md` and `RULES.md`. + +== README layout + +Expanded `general/readme-layout.md` with Best-README adapted patterns: + +* HTML `` badges inside centered headers (GitHub AsciiDoc/Markdown centering trap). +* Role-grouped Built With sections. +* Tier guidance (full vs simplified vs skip). + +== Other rule updates + +* Creator rules: SDLang in-stack; KDL greenfield; reject Extended SDL/XDL. +* Ported sync-before-work habit into global rules and `.cursor/rules/`. +* rules-manager path documentation in README installation section. diff --git a/docs/modules/ROOT/pages/changelog-details/2026-08-08 - antora-docs-and-personal-ref-cleanup.adoc b/docs/modules/ROOT/pages/changelog-details/2026-08-08 - antora-docs-and-personal-ref-cleanup.adoc new file mode 100644 index 0000000..d699c99 --- /dev/null +++ b/docs/modules/ROOT/pages/changelog-details/2026-08-08 - antora-docs-and-personal-ref-cleanup.adoc @@ -0,0 +1,21 @@ += 2026-08-08 – Antora docs and personal-reference cleanup + +== Summary + +Introduced an Antora documentation component and removed upstream personal-repository references so the canonical repo reads as org-neutral forkable content. + +== Documentation added + +* `docs/antora.yml` — component metadata (`agent-rules`, start page `ROOT:index.adoc`). +* `docs/modules/ROOT/pages/index.adoc` — overview (what this repo is / is not). +* `docs/modules/ROOT/pages/usage.adoc` — clone, paste, rules-manager, MEMORIES. +* `docs/modules/ROOT/pages/architecture.adoc` — relationship to `devcentr-agent-rules` and workstation memory. + +== Text cleanup + +* `README.md`, `CONTRIBUTING.md`, `RULES.md` — replaced personal fork examples with generic guidance. +* README adds hub docs URL; personal constants stay in the user's fork. + +== Hub wiring + +`dev-centr/docs` playbook already includes `https://github.com/dev-centr/agent-rules.git` with `start_path: docs`. Published URL: https://docs.devcentr.org/agent-rules/ diff --git a/docs/modules/ROOT/pages/changelog.adoc b/docs/modules/ROOT/pages/changelog.adoc new file mode 100644 index 0000000..f8dd1ff --- /dev/null +++ b/docs/modules/ROOT/pages/changelog.adoc @@ -0,0 +1,42 @@ += Changelog + +Notable changes to agent-rules rules, profiles, and documentation. Entries are in reverse chronological order. Each entry links to a detailed changelog article where helpful. + +== 2026-08-08 – Antora docs and personal-reference cleanup + +* Added Antora component under `docs/` (overview, usage, architecture). +* Removed personal-repo references from README, CONTRIBUTING, and RULES.md; generic fork guidance instead. +* Wired into https://docs.devcentr.org/agent-rules/[Dev-Centr docs hub] (playbook already lists this component). + +See xref:ROOT:changelog-details/2026-08-08 - antora-docs-and-personal-ref-cleanup.adoc[Detailed changelog]. + +== 2026-08-06 – Antora org policy and README layout rules + +* `general/antora-docs-sites.md`: one Antora site per org; wire components into hub; dedupe errant GitHub Pages sites. +* `general/readme-layout.md`: Best-README adapted layout (HTML badges, centered header, role-grouped Built With). +* SDLang in-stack preference; KDL greenfield; ban Extended SDL/XDL in creator rules. +* Sync-before-work habit and rules-manager path documentation. + +See xref:ROOT:changelog-details/2026-08-06 - antora-policy-and-readme-layout.adoc[Detailed changelog]. + +== 2026-08-03 – Software Product Essentials pointer + +* `general/app-architecture.md` points agents at general-knowledge Software Product Essentials when building apps. + +See xref:ROOT:changelog-details/2026-08-03 - software-product-essentials.adoc[Detailed changelog]. + +== 2026-03-31 – MAIN.md entrypoint and MEMORIES clarification + +* Reorganized into `MAIN.md` modular assembly entrypoint and consolidated `RULES.md` preamble. +* Clarified `$CODE_ROOT/MEMORIES.md` as the canonical workstation memory location. + +See xref:ROOT:changelog-details/2026-03-31 - main-entrypoint-and-memories.adoc[Detailed changelog]. + +== 2026-03-23 – Initial forkable rules and 1-step assembly + +* Initial commit: canonical forkable agent rules for Dev-Centr. +* OS layers split (`general/windows.md`, `general/mac.md`, `general/linux.md`); `ENVIRONMENT` profile constant. +* 1-step assembly architecture in `RULES.md` / `MAIN.md` (parallel batched reads). +* README profile constants table; human vs agent audience clarified. + +See xref:ROOT:changelog-details/2026-03-23 - initial-forkable-rules.adoc[Detailed changelog]. diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 205c09e..ce498d0 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -14,6 +14,14 @@ https://docs.devcentr.org/agent-rules/ * Shared end-user / project agent instructions (`RULES.md`, `general/`, `profiles/`) * Assembled locally (paste or via rules-manager) +== Quick links + +* xref:usage.adoc[Usage] — clone, paste, MEMORIES +* xref:assembly.adoc[Assembly] — 1-step parallel read architecture +* xref:profiles.adoc[Profiles] — machine constants +* xref:troubleshooting.adoc[Troubleshooting] — common pitfalls +* xref:changelog.adoc[Changelog] — notable changes + == What this is not * **Not** Dev-Centr product automation — that lives in https://github.com/dev-centr/devcentr-agent-rules[`devcentr-agent-rules`] diff --git a/docs/modules/ROOT/pages/modules-reference.adoc b/docs/modules/ROOT/pages/modules-reference.adoc new file mode 100644 index 0000000..dff903f --- /dev/null +++ b/docs/modules/ROOT/pages/modules-reference.adoc @@ -0,0 +1,68 @@ += Module reference + +`general/` modules are Markdown rule files the agent loads during assembly. + +== Always loaded + +[cols="1,2"] +|=== +| Module | Covers + +| `global.md` +| Core habits: plain language, gitignore allow-list, sync-before-work, Python venv/uv, build-failure policy, changelogs. + +| `environment.md` +| Cross-platform tooling defaults (Node/pnpm, git hosts, path refresh patterns). + +| `windows.md` / `mac.md` / `linux.md` +| OS-specific shell, paths, and tooling (selected by `ENVIRONMENT`). + +| `creator.md` +| Owned-project rules: transfers, issues workflow, SDL/KDL config preference, changelog structure. + +| `folder-schema.md` +| Code hive layout (`$CODE_ROOT///`, forks, clones). +|=== + +== Task-gated (MAIN.md) + +[cols="1,2"] +|=== +| Module | Load when + +| `documentation.md` +| Authoring or publishing project documentation (Diátaxis, Antora pointers). + +| `antora-docs-sites.md` +| Antora sites, org hub policy, deduplicating errant Pages deployments. + +| `readme-layout.md` +| Creating or revising GitHub-facing READMEs (Best-README adapted). + +| `app-architecture.md` +| Scaffolding, building, shipping, packaging applications. +|=== + +== Repository files + +[cols="1,2"] +|=== +| File | Audience + +| `README.md` +| Humans — install, usage, architecture diagram, contributing. + +| `RULES.md` +| Agents — consolidated preamble; paste into app rules field. + +| `MAIN.md` +| Agents with filesystem access — modular parallel assembly. + +| `MEMORIES.example.md` +| Template for `$CODE_ROOT/MEMORIES.md` format. + +| `CONTRIBUTING.md` +| Humans — where portable vs fork-only changes go. +|=== + +Source files live at the repository root and under `general/`; this page is an index for navigation. diff --git a/docs/modules/ROOT/pages/profiles.adoc b/docs/modules/ROOT/pages/profiles.adoc new file mode 100644 index 0000000..78aa207 --- /dev/null +++ b/docs/modules/ROOT/pages/profiles.adoc @@ -0,0 +1,37 @@ += Profiles + +Machine-specific constants live in `profiles/*.md`. The agent reads **one** profile during context assembly (inferred from filename or your configuration). + +== Template files + +| File | Purpose | +|------|---------| +| `profiles/my-desktop.md` | Desktop workstation template | +| `profiles/my-laptop.md` | Laptop template | + +Rename to match how you use the machine (for example `desktop.md`) and point your agent at that name. + +== Constants + +```text +CODE_ROOT = # e.g. Z:\code or /home/you/src +GITHUB_USER = # optional; path examples +ISSUES_REPO = # optional; omit if unused +ENVIRONMENT = windows # windows | mac | linux +``` + +| Constant | Required? | Purpose | +|----------|-----------|---------| +| `CODE_ROOT` | Yes | Root directory for Git clones (see xref:../folder-schema.adoc[folder schema]). | +| `ENVIRONMENT` | Yes | Selects `general/windows.md`, `general/mac.md`, or `general/linux.md`. | +| `GITHUB_USER` | No | Username for path examples and org layouts. | +| `ISSUES_REPO` | No | Path to your `.issues` workflow repository. | + +== Fork vs upstream + +* **Portable rules** → pull requests to https://github.com/dev-centr/agent-rules[`dev-centr/agent-rules`]. +* **Personal constants, org examples, private paths** → your fork only; never upstream personal workstation facts. + +== Workstation memory + +Profile constants are not the same as `$CODE_ROOT/MEMORIES.md`. Profiles hold stable machine identity; MEMORIES holds discovered facts (PATH gaps, tool locations) with usage counters. See xref:troubleshooting.adoc#memories[troubleshooting]. diff --git a/docs/modules/ROOT/pages/troubleshooting.adoc b/docs/modules/ROOT/pages/troubleshooting.adoc new file mode 100644 index 0000000..b8edc47 --- /dev/null +++ b/docs/modules/ROOT/pages/troubleshooting.adoc @@ -0,0 +1,55 @@ += Troubleshooting + +Common setup mistakes and how to fix them. + +== Agent ignores modular rules + +**Symptom:** Agent only follows the short `RULES.md` preamble. + +**Fix:** Ensure the harness can read `$AGENT_RULES_PATH` (or your clone path). Use `MAIN.md` assembly instructions or rules-manager composed output. Paste-only mode cannot load `general/` modules. + +== Wrong OS layer loaded + +**Symptom:** Windows path examples on Linux, or macOS guidance on Windows. + +**Fix:** Set `ENVIRONMENT` in your active `profiles/*.md` to `windows`, `mac`, or `linux`. Verify the agent reads `general/.md` during assembly. + +== MEMORIES [[memories]] + +**Symptom:** Workstation facts committed to git or stored in per-repo `MEMORIES.md`. + +**Fix:** + +* Use **`$CODE_ROOT/MEMORIES.md`** only (gitignored on your machine). +* Project facts → `AGENTS.md` + docs, not MEMORIES. +* Format: `MEMORIES.example.md` in this repository. + +== Personal constants in upstream PRs + +**Symptom:** Pull request to `dev-centr/agent-rules` contains your `CODE_ROOT`, username, or org-specific paths. + +**Fix:** Keep personal constants in your fork. Upstream only portable rule improvements. + +== Stale local HEAD before multi-file edits + +**Symptom:** Large doc or rule change conflicts with remote. + +**Fix:** `git fetch` and check `git status -sb` for `behind`. Pull/rebase before multi-file work (see `general/global.md`). + +== Docs not on hub + +**Symptom:** README links to `github.io` Antora site instead of https://docs.devcentr.org/agent-rules/ + +**Fix:** Component is wired in `dev-centr/docs` playbook. Do not enable per-repo GitHub Pages for Antora. See `general/antora-docs-sites.md`. + +== rules-manager vs junction + +**Symptom:** Windows directory junction to this repo breaks after moves. + +**Fix:** Prefer rules-manager `rules_repo_path` to compose into `$CODE_ROOT/agent-rules.composed.md`. Junctions are temporary convenience only. + +== Product vs forkable rules confused + +**Symptom:** Dev-Centr app automation loads this repo instead of product rules. + +**Fix:** Product automation → https://github.com/dev-centr/devcentr-agent-rules[`devcentr-agent-rules`]. This repo is for end-user/project agents only. diff --git a/docs/modules/ROOT/pages/usage.adoc b/docs/modules/ROOT/pages/usage.adoc index 58ba633..228a24b 100644 --- a/docs/modules/ROOT/pages/usage.adoc +++ b/docs/modules/ROOT/pages/usage.adoc @@ -1,7 +1,10 @@ = Usage . Clone into your code hive, for example `$CODE_ROOT/github.com//agent-rules`. +. Copy a profile template from `profiles/` and set constants (see xref:profiles.adoc[Profiles]). . Point your assistant at `RULES.md`, or compose with https://github.com/dev-centr/rules-manager[`rules-manager`]. . Put machine-local facts in **`$CODE_ROOT/MEMORIES.md`** (never commit). Format: `MEMORIES.example.md` in this repository. Fork the repository when you need private constants. Upstream portable improvements with pull requests to `dev-centr/agent-rules`. + +For assembly details and module load order, see xref:assembly.adoc[Assembly].