docs: document file naming conventions and clarify structure guidance
Added explicit file-naming rules to page-templates.md so agents know: - Root entry-points: ALL-CAPS (AGENTS.md, README.md) - Containers: <id>-<name>.md (e.g., 101-jellyfin.md) - Infrastructure: lowercase-with-dashes (dns.md, auto-deploy.md) - Plans/investigations: YYYY-MM-DD-slug.md - Skills: lowercase-with-dashes/ folder containing SKILL.md Updated AGENTS.md section 4 (Wiki conventions) to link to page-templates.md and provided quick reference for file naming, page locations, and changelog format. Updated README.md conventions section to mention file naming and link to page-templates.md for the full rules. All agents now have a clear reference chain: 1. AGENTS.md (entry point) → points to conventions 2. page-templates.md (structure) → has file naming + page templates 3. writing-style.md (prose) → has voice, vocabulary, linking rules 4. llm-wiki.md (organization) → has sources/wiki/index/log model Verified: no broken links, all conventions documented, consistency check passes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
18
AGENTS.md
18
AGENTS.md
@@ -75,19 +75,25 @@ Grep is fine for browsing or when MCP is unreachable.
|
||||
|
||||
## 4. Wiki conventions
|
||||
|
||||
- Narrative pages live under `knowledge/wiki/{containers,hosts,vms,infrastructure}/`;
|
||||
See [page-templates.md](.agents/shared/page-templates.md) for file naming, page
|
||||
structure, and the tone standard. Quick reference:
|
||||
|
||||
- **File naming:** Root entry-points are ALL-CAPS (`AGENTS.md`); containers use
|
||||
`<id>-<name>.md`; infrastructure uses lowercase-with-dashes; plans and investigations
|
||||
use `YYYY-MM-DD-slug.md`; skills are folders with `SKILL.md` inside.
|
||||
- **Where pages live:** Narrative under `knowledge/wiki/{containers,hosts,vms,infrastructure}/`;
|
||||
incident records under `knowledge/sources/investigations/`; runbook procedures under
|
||||
`.agents/skills/<name>/SKILL.md`; operator reference under `.agents/operations/`;
|
||||
design docs under `plans/`. Cross-link liberally; orphans are bugs.
|
||||
- Every page ends with a `## Changelog` section, entries in reverse-chrono
|
||||
order:
|
||||
- **Changelog format:** Every page ends with a `## Changelog` section, entries in
|
||||
reverse-chronological order:
|
||||
|
||||
### YYYY-MM-DD — short title
|
||||
one or two lines describing what changed and why.
|
||||
|
||||
- Investigation files are dated and slugged: `YYYY-MM-DD-slug.md`.
|
||||
- Live state takes precedence over docs. If you observe a discrepancy, update
|
||||
the docs *in the same session* (per the same-session update rule).
|
||||
- **Live state precedence.** If you observe a discrepancy between the docs and
|
||||
running state, update the docs *in the same session* (per the same-session update
|
||||
rule in [page-templates.md](.agents/shared/page-templates.md#same-session-update-rule)).
|
||||
|
||||
## 5. Acting on the homelab
|
||||
|
||||
|
||||
Reference in New Issue
Block a user