From 3ff7056c31558af53467c0c2405fbf393fef570f Mon Sep 17 00:00:00 2001 From: Rafael Richards Date: Sun, 10 May 2026 20:34:25 -0400 Subject: [PATCH] docs(AGENTS): add Layout conventions section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Specializes the org-level layout rule for m-cli's top-level layout. States the cross-repo rule (docs/ is prose-only) and maps each top-level dir to its purpose: docs/ for prose, dist/ for the Phase 0 contract + drift-gated JSON outputs, examples/ for worked-example artifacts, scripts/ for shell helpers, src/m_cli/ for source, tests/ mirroring src/ one-file-per-module. Links back to .github/CONTRIBUTING.md § Layout conventions for the org-level rule. --- AGENTS.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 4723f7c..4667185 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -146,6 +146,21 @@ Matches `verification_commands` in `dist/repo.meta.json`. - No mocks unless unavoidable — fixtures are real `.m` source strings. - Lint and fmt rules are registered via `register(Rule(...))` / `_register(FmtRule(...))` in `src/m_cli/lint/rules.py` and `src/m_cli/fmt/rules.py`. New rules ship in their own module-level `register(...)` block; the `m capabilities` / `m lint --list-rules --json` / `m fmt --list-rules --json` outputs read from the same registries — never hand-curate the JSON. +## Layout conventions + +`docs/` holds **only** human-readable prose. Technical artifacts live elsewhere — m-cli's top-level layout: + +| Path | Contents | +|---|---| +| `docs/` | Guides (lint user guide, plugin development, pre-commit), `evolution.md` (history), `plans/`, worked-example writeups | +| `dist/` | Phase 0 `repo.meta.json` + `commands.json` / `lint-rules.json` / `fmt-rules.json` (manifest drift gate) | +| `examples/` | Worked-example artifacts (e.g. `vista-lint-presets/m-cli.toml.example`) | +| `scripts/` | Shell helpers (seed/unseed, bench drivers, corpus validation) | +| `src/m_cli/` | Python source | +| `tests/` | Pytest — one file per source module | + +Enforced by `make check-docs-prose` (CI gate). Org-level rule: [`.github/CONTRIBUTING.md` § Layout conventions](https://github.com/m-dev-tools/.github/blob/main/CONTRIBUTING.md#layout-conventions). + --- ## Dev workflow