From e84280f2ee1c2abdcc046074bfdd254f765ccca2 Mon Sep 17 00:00:00 2001 From: Brett Date: Mon, 1 Jun 2026 13:59:51 -0500 Subject: [PATCH 1/2] docs(agents): surface docs/solutions as a searchable knowledge store AGENTS.md mentioned `docs/solutions/` only as a `dev`-only path guarded out of `main` by `guard-main-docs.yml`. An agent reading that learned the path is forbidden on `main` but not that it is a searchable knowledge store of cross-repo solutions worth consulting before researching from scratch. Adds a short Documented Solutions section adjacent to Layout: names the symlink target, frontmatter fields (`module`, `tags`, `problem_type`), and the `qmd query "" --collection solutions` search command. Matches the pattern already in `agentnative-spec/AGENTS.md` and `agentnative-cli/CLAUDE.md`. Discoverability-only edit; no policy change. The `docs/plans/`, `docs/solutions/`, `docs/brainstorms/`, `docs/reviews/` guard-from-main mention later in the file is unchanged. --- AGENTS.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 43f087a..8b3ba29 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -36,6 +36,16 @@ auto-discovers `SKILL.md` at the install root and ignores everything else. Produ +## Documented Solutions + +`docs/solutions/` is a symlink to `~/dev/solutions-docs/`, a shared private repo of cross-repo solutions and best +practices, organized by category with YAML frontmatter (`module`, `tags`, `problem_type`). Search with `qmd query +"" --collection solutions`. Relevant when researching artifact-sync, calver, frontmatter, or skill-bundle +patterns before building from scratch. + +The consuming repo's `git status` shows nothing for `docs/solutions/` because the symlink target is gitignored. If the +symlink is missing, recreate it: `ln -s ~/dev/solutions-docs docs/solutions`. + ## Lint & Format ```bash From 27fbec0dc03b9b4991e07936b771e1b75935098a Mon Sep 17 00:00:00 2001 From: Brett Date: Mon, 1 Jun 2026 14:16:36 -0500 Subject: [PATCH 2/2] =?UTF-8?q?docs(agents):=20swap=20Layout=20table=20no-?= =?UTF-8?q?indicator=20to=20=E2=9C=97,=20exclude=20symlinked=20solutions?= =?UTF-8?q?=20from=20lint?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Layout table's column-2 "no" indicator was an em-dash (`—`) wrapped in ` / ` so the prose-scorer would not count the 8 cell em-dashes against the file's density score. Cleaner: use `✗` directly, parallel to the existing `✓` for the "yes" rows. Drop the wrap. The `` mechanism is for legitimate-but-flagged content the file's author wants the scorer to skip. The Layout table's em-dashes were always "data, not prose" — the wrap was treating them as if they were prose-flagged-but-OK. The ✓ / ✗ pair is the structurally correct fix: data indicators, no need to silence the scorer. Also exclude `docs/solutions/**` from `.markdownlint-cli2.yaml`. The path is a symlink to `~/dev/solutions-docs` (a separate private repo with its own lint config). Once the symlink was added in this PR, this repo's pre-push markdownlint walked into the foreign content and failed on its line-length rules. The exclusion makes the symlink-walk safe. --- .markdownlint-cli2.yaml | 6 ++++++ AGENTS.md | 20 ++++++++------------ 2 files changed, 14 insertions(+), 12 deletions(-) diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml index 7e0d44d..d455f60 100644 --- a/.markdownlint-cli2.yaml +++ b/.markdownlint-cli2.yaml @@ -87,6 +87,12 @@ ignores: # bullets per PR; line-length wrapping would conflict with the generator. # CHANGELOG.md is regenerated, never hand-edited. - "CHANGELOG.md" + # Symlinked to ~/dev/solutions-docs (a separate private repo). Content + # is governed by its own lint config; consuming repos do not enforce + # this repo's rules on it. The symlink is gitignored globally + # (~/.config/git/ignore), so this exclusion only affects local lint + # walks that follow the symlink. + - "docs/solutions/**" # Fix automatically when --fix is used fix: true diff --git a/AGENTS.md b/AGENTS.md index 8b3ba29..d2cfdc7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,8 +14,6 @@ The repo ships to consumers via plain `git clone`. After install, the host (Clau auto-discovers `SKILL.md` at the install root and ignores everything else. Producer-side files (`scripts/`, `docs/`, `.github/`, `cliff.toml`, etc.) clone alongside the skill content but are inert at runtime. - - | Path | Read at runtime by host? | Purpose | | ---------------------------------------------------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | `SKILL.md` | ✓ | Skill metadata + entry-point pointer to `getting-started.md`. The host's first read. | @@ -25,16 +23,14 @@ auto-discovers `SKILL.md` at the install root and ignores everything else. Produ | `references/` | ✓ | Implementation guidance: framework idioms (Rust + others), project structure, Rust/clap patterns. | | `templates/` | ✓ | Drop-in starter files for greenfield Rust CLIs (`clap-main.rs`, `error-types.rs`, `output-format.rs`, `agents-md-template.md`). | | `VERSION` | ✓ | Single-line current version. `bin/check-update` reads this for the upgrade comparison. | -| `scripts/sync-spec.sh` | — | Vendor the latest `agentnative-spec` v\* tag into `spec/`. Mirror of the agentnative-cli script. | -| `scripts/generate-changelog.sh` | — | Release-time CHANGELOG generator (git-cliff + PR-body extraction). | -| `AGENTS.md`, `RELEASES.md`, `CONTRIBUTING.md`, `README.md`, `SECURITY.md` | — | Producer-repo docs. | -| `.github/rulesets/` | — | Version-controlled GitHub repository rulesets. | -| `.github/workflows/` | — | CI: markdownlint, shellcheck. Plus `guard-main-docs.yml` to keep engineering docs off `main`. | -| `.github/ISSUE_TEMPLATE/` | — | Bug report + bundle-proposal templates. | -| `docs/plans/` | — | Engineering plans (`dev`-only — guarded out of `main`). | -| `.markdownlint-cli2.yaml`, `.shellcheckrc`, `.gitattributes`, `.gitignore`, `cliff.toml` | — | Local lint configs, git-cliff config, and repo metadata. | - - +| `scripts/sync-spec.sh` | ✗ | Vendor the latest `agentnative-spec` v\* tag into `spec/`. Mirror of the agentnative-cli script. | +| `scripts/generate-changelog.sh` | ✗ | Release-time CHANGELOG generator (git-cliff + PR-body extraction). | +| `AGENTS.md`, `RELEASES.md`, `CONTRIBUTING.md`, `README.md`, `SECURITY.md` | ✗ | Producer-repo docs. | +| `.github/rulesets/` | ✗ | Version-controlled GitHub repository rulesets. | +| `.github/workflows/` | ✗ | CI: markdownlint, shellcheck. Plus `guard-main-docs.yml` to keep engineering docs off `main`. | +| `.github/ISSUE_TEMPLATE/` | ✗ | Bug report + bundle-proposal templates. | +| `docs/plans/` | ✗ | Engineering plans (`dev`-only — guarded out of `main`). | +| `.markdownlint-cli2.yaml`, `.shellcheckrc`, `.gitattributes`, `.gitignore`, `cliff.toml` | ✗ | Local lint configs, git-cliff config, and repo metadata. | ## Documented Solutions