126 lines
3.7 KiB
Markdown
126 lines
3.7 KiB
Markdown
# Document Metadata Schema
|
|
|
|
All documents in the docs/ directory must include YAML frontmatter with the following structure.
|
|
|
|
## Required Fields
|
|
|
|
### title
|
|
- **Type**: String
|
|
- **Description**: Human-readable document title
|
|
- **Example**: `"OAuth2 Migration Specification"`
|
|
|
|
### category
|
|
- **Type**: String (enum)
|
|
- **Description**: Document category, must match the directory it's in
|
|
- **Valid values**:
|
|
- `ai_docs` - Reference materials for Claude Code
|
|
- `specs` - Feature and migration specifications
|
|
- `analysis` - Investigation outputs
|
|
- `plans` - Implementation plans
|
|
- `templates` - Reusable templates
|
|
- `archive` - Historical documents (auto-set on archiving)
|
|
- **Example**: `specs`
|
|
|
|
### status
|
|
- **Type**: String (enum)
|
|
- **Description**: Current lifecycle status of the document
|
|
- **Valid values**:
|
|
- `draft` - Document is being created
|
|
- `active` - Document is current and relevant
|
|
- `complete` - Work is done, kept for reference
|
|
- `archived` - Document has been archived
|
|
- **Example**: `active`
|
|
- **Lifecycle**: draft → active → complete → archived
|
|
|
|
### created
|
|
- **Type**: Date (YYYY-MM-DD)
|
|
- **Description**: Date the document was created
|
|
- **Example**: `2024-11-16`
|
|
|
|
### last_updated
|
|
- **Type**: Date (YYYY-MM-DD)
|
|
- **Description**: Date the document was last modified
|
|
- **Example**: `2024-11-16`
|
|
- **Note**: Should be updated whenever significant changes are made
|
|
|
|
## Optional Fields
|
|
|
|
### tags
|
|
- **Type**: List of strings
|
|
- **Description**: Keywords for categorization and search
|
|
- **Example**: `[auth, oauth2, security, migration]`
|
|
- **Best practice**: Use consistent tags across related documents
|
|
|
|
### archivable_after
|
|
- **Type**: Date (YYYY-MM-DD)
|
|
- **Description**: Explicit date after which the document can be auto-archived
|
|
- **Example**: `2025-02-16`
|
|
- **Note**: Overrides category-based archiving rules when set
|
|
|
|
### archived_date
|
|
- **Type**: Date (YYYY-MM-DD)
|
|
- **Description**: Date the document was archived (auto-set by archiving script)
|
|
- **Example**: `2024-12-01`
|
|
|
|
### archive_reason
|
|
- **Type**: String
|
|
- **Description**: Reason for archiving (auto-set by archiving script)
|
|
- **Example**: `"90 days old (threshold: 90)"`
|
|
|
|
### author
|
|
- **Type**: String
|
|
- **Description**: Document author or owner
|
|
- **Example**: `"Simon Lamb"`
|
|
|
|
### related_docs
|
|
- **Type**: List of strings (file paths)
|
|
- **Description**: Links to related documents
|
|
- **Example**: `["specs/auth-system/oauth2-spec.md", "plans/oauth2-rollout.md"]`
|
|
|
|
## Complete Example
|
|
|
|
```yaml
|
|
---
|
|
title: OAuth2 Migration Specification
|
|
category: specs
|
|
status: active
|
|
created: 2024-11-16
|
|
last_updated: 2024-11-16
|
|
tags: [auth, oauth2, security, migration]
|
|
author: Simon Lamb
|
|
related_docs:
|
|
- analysis/auth-system-audit.md
|
|
- plans/oauth2-implementation-plan.md
|
|
---
|
|
```
|
|
|
|
## Validation
|
|
|
|
Documents are validated using `scripts/validate_doc_metadata.py`. Run this before committing to ensure all metadata is correct.
|
|
|
|
## Metadata Updates
|
|
|
|
### When Creating a New Document
|
|
1. Copy from `assets/doc_template.md`
|
|
2. Fill in all required fields
|
|
3. Set status to `draft`
|
|
4. Set created and last_updated to current date
|
|
|
|
### When Updating a Document
|
|
1. Update `last_updated` to current date
|
|
2. Update `status` if lifecycle stage changes
|
|
3. Add relevant `tags` if needed
|
|
|
|
### When Completing Work
|
|
1. Set `status` to `complete`
|
|
2. Update `last_updated` to current date
|
|
3. Optionally set `archivable_after` if auto-archiving should be deferred
|
|
|
|
## Best Practices
|
|
|
|
1. **Consistent Tags**: Use a common vocabulary of tags across documents
|
|
2. **Accurate Status**: Keep status up to date as work progresses
|
|
3. **Related Docs**: Link to related documents for context and discoverability
|
|
4. **Regular Updates**: Update `last_updated` whenever making significant changes
|
|
5. **Descriptive Titles**: Use clear, specific titles that describe the content
|