85 lines
2.9 KiB
Markdown
85 lines
2.9 KiB
Markdown
# Inventory `agent-docs/` Template
|
|
|
|
Use this structure for Markdown files inside `agent-docs/` when the document's main job is to track a maintained set of entries: media plans, registries, migration queues, or cleanup lists.
|
|
|
|
## Minimum Required Shape
|
|
|
|
```md
|
|
# <Document Title>
|
|
|
|
<Opening statement: what this inventory tracks, when it should be used or updated, and that it must be followed in scope.>
|
|
|
|
## Applies To
|
|
|
|
- <tasks that require reading or updating this inventory>
|
|
|
|
## Does Not Apply To
|
|
|
|
- <tasks that belong in a rule doc, public docs, or another inventory>
|
|
|
|
## Maintenance Rules
|
|
|
|
- <how to add, update, remove, or rewrite entries>
|
|
|
|
## Reclassification Rules
|
|
|
|
- <when an entry changes status or grouping>
|
|
- <when repeated notes should become policy in a rule doc>
|
|
- <when this inventory should split or link to a narrower rule doc>
|
|
|
|
## Classification Authority
|
|
|
|
- <who or what decides the classification scheme or status changes>
|
|
|
|
## Entries
|
|
|
|
### <Grouping Heading>
|
|
|
|
#### <Entry Title>
|
|
|
|
<Recommended fields; keep only the ones that materially help maintainers.>
|
|
|
|
Source:
|
|
- <path or owning document>
|
|
|
|
Status:
|
|
- <planned / in progress / complete / remove / optional>
|
|
|
|
Notes:
|
|
- <what to capture, why it matters, or what to clean up>
|
|
|
|
## Maintenance Checklist
|
|
|
|
- <questions for keeping the inventory current and unambiguous>
|
|
```
|
|
|
|
## Required Sections
|
|
|
|
- `# <Document Title>`
|
|
- opening statement
|
|
- `## Applies To`
|
|
- `## Maintenance Rules`
|
|
- `## Reclassification Rules`
|
|
- `## Classification Authority`
|
|
- `## Entries`
|
|
- `## Maintenance Checklist`
|
|
|
|
## Conditionally Required Sections
|
|
|
|
- `## Does Not Apply To` when the inventory would otherwise be confused with a rule doc, public docs, or another registry
|
|
- grouping headings under `## Entries` when they materially improve scanning or maintenance ownership
|
|
|
|
## Notes
|
|
|
|
- Prefer an inventory template when the document is mostly a maintained list rather than a rules essay.
|
|
- Start with a small field set. `Source`, `Status`, and `Notes` are common defaults, not mandatory fields.
|
|
- Add, rename, or remove entry fields to match the repository's actual maintenance needs.
|
|
- Keep entry fields stable enough within one document that maintainers can scan and update them consistently.
|
|
- Use grouping headings only when they materially improve navigation.
|
|
- Separate durable maintenance rules from the entries themselves.
|
|
- If the governing policy becomes large, move it to a rule doc and link to it from the inventory.
|
|
- Treat `Classification Authority` as required. If status or grouping rules have no authority anchor, the inventory is not stable enough to maintain.
|
|
- Treat `Reclassification Rules` as required. Repeated state transitions should not stay implicit in review comments or maintenance folklore.
|
|
- Write for maintainers and make update decisions explicit.
|
|
- If the document references repository files, write repository-relative paths in backticks, not Markdown links or machine-local absolute filesystem paths.
|