Skip to content

docs(agents): surface docs/solutions as a searchable knowledge store #27

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
brettdavies merged 2 commits into from
Jun 1, 2026
Merged

docs(agents): surface docs/solutions as a searchable knowledge store #27

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e84280f
docs(agents): surface docs/solutions as a searchable knowledge store
brettdavies Jun 1, 2026
27fbec0
docs(agents): swap Layout table no-indicator to ✗, exclude symlinked …
brettdavies Jun 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .markdownlint-cli2.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
30 changes: 18 additions & 12 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<!-- unslop: off -->

| Path | Read at runtime by host? | Purpose |
| ---------------------------------------------------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `SKILL.md` | ✓ | Skill metadata + entry-point pointer to `getting-started.md`. The host's first read. |
Expand All @@ -25,16 +23,24 @@ 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. |

<!-- unslop: on -->
| `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

`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
"<topic>" --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

Expand Down