Initial commit

2025-11-30 08:58:05 +08:00
commit 36a6fff8d8
20 changed files with 4237 additions and 0 deletions
--- a/skills/cyberarian/references/archiving-criteria.md
+++ b/skills/cyberarian/references/archiving-criteria.md
@@ -0,0 +1,184 @@
+# Document Archiving Criteria
+
+Documents are automatically archived based on their category, status, and age. This ensures the active workspace remains focused on current, relevant documentation.
+
+## Archiving Philosophy
+
+**Goals:**
+- Keep active directories focused on current work
+- Preserve historical context in archive
+- Automate routine maintenance while allowing manual control where needed
+- Make archiving decisions deterministic and transparent
+
+**Non-goals:**
+- Deleting documents (everything is preserved)
+- Aggressive archiving that loses important context
+- One-size-fits-all rules (categories have different lifecycles)
+
+## Category-Specific Rules
+
+### specs/ - Specifications
+**Auto-archive**: Yes  
+**Criteria**: Status is `complete` AND >90 days since last_updated
+
+**Rationale**: Specs are valuable reference material even after implementation. 90 days allows for iteration, rollout, and bug fixes before archiving.
+
+**Manual override**: Set `archivable_after` date in frontmatter to defer archiving.
+
+**Example scenarios:**
+- ✅ Archive: Feature spec marked `complete` 100 days ago
+- ❌ Skip: Active spec being refined
+- ❌ Skip: Complete spec only 30 days old (still in rollout phase)
+
+### analysis/ - Investigation Outputs
+**Auto-archive**: Yes  
+**Criteria**: Status is `complete` AND >60 days since last_updated
+
+**Rationale**: Analysis documents are point-in-time investigations. Once the work is done and changes are implemented, they have less ongoing value. 60 days allows for follow-up work.
+
+**Manual override**: Set `archivable_after` to keep important analyses active longer.
+
+**Example scenarios:**
+- ✅ Archive: Bug investigation completed 70 days ago
+- ✅ Archive: Performance analysis from 2 months ago
+- ❌ Skip: Ongoing investigation (status: `active` or `draft`)
+
+### plans/ - Implementation Plans
+**Auto-archive**: Yes  
+**Criteria**: Status is `complete` AND >30 days since last_updated
+
+**Rationale**: Plans become stale quickly. Once implementation is done, plans are primarily historical. 30 days accounts for plan execution and retrospective.
+
+**Manual override**: Set `archivable_after` for long-running initiatives.
+
+**Example scenarios:**
+- ✅ Archive: Migration plan completed 45 days ago
+- ✅ Archive: Sprint plan from last month (status: `complete`)
+- ❌ Skip: Ongoing multi-phase plan (status: `active`)
+- ❌ Skip: Just-completed plan (20 days old)
+
+### ai_docs/ - Reference Materials
+**Auto-archive**: No  
+**Manual archiving only**
+
+**Rationale**: Reference materials (SDKs, API docs, repo context) are meant to be persistent. These inform Claude Code's understanding and should only be archived manually when truly obsolete.
+
+**When to manually archive:**
+- SDK documentation for deprecated versions
+- API references for sunset APIs
+- Repository context for archived projects
+
+**Example scenarios:**
+- ❌ Auto-archive: Never, regardless of age or status
+- ✅ Manual: Move OAuth 1.0 docs when OAuth 2.0 is fully adopted
+- ✅ Manual: Archive legacy API docs after migration complete
+
+### templates/ - Reusable Templates
+**Auto-archive**: No  
+**Templates never auto-archive**
+
+**Rationale**: Templates are meant to be reused indefinitely. They don't have a lifecycle in the same way as other documents.
+
+**When to manually archive:**
+- Deprecated templates that should no longer be used
+- Templates replaced by improved versions
+
+**Best practice**: Instead of archiving, update templates in place or clearly mark as deprecated in the template itself.
+
+## Archive Structure
+
+Archived documents are moved to `archive/` while preserving their category:
+
+```
+archive/
+├── specs/
+│   └── oauth2-migration-spec.md
+├── analysis/
+│   └── auth-perf-analysis.md
+└── plans/
+    └── q3-migration-plan.md
+```
+
+This structure:
+- Maintains categorical organization
+- Allows easy browsing of archived content
+- Prevents mixing of categories in archive
+
+## Manual Archiving
+
+To manually archive a document:
+
+1. Move it to `archive/<category>/`
+2. Update metadata:
+   ```yaml
+   status: archived
+   archived_date: YYYY-MM-DD
+   archive_reason: "Manual archiving: <reason>"
+   ```
+3. Run `scripts/index_docs.py` to update the index
+
+## Preventing Auto-Archiving
+
+To prevent a document from being auto-archived:
+
+**Option 1**: Keep status as `active` or `draft`  
+**Option 2**: Set explicit `archivable_after` date in frontmatter:
+
+```yaml
+archivable_after: 2025-12-31  # Don't archive until after this date
+```
+
+This is useful for:
+- Long-running projects
+- Reference specs that should remain active
+- Documents with ongoing relevance despite completion
+
+## Running the Archiving Script
+
+```bash
+# Dry run to see what would be archived
+python scripts/archive_docs.py --dry-run
+
+# Actually archive documents
+python scripts/archive_docs.py
+
+# Archive and update index
+python scripts/archive_docs.py && python scripts/index_docs.py
+```
+
+**Best practice**: Run archiving periodically (weekly or monthly) as part of documentation maintenance.
+
+## Retrieval from Archive
+
+Archived documents are not deleted and can be retrieved by:
+
+1. **Browsing**: Navigate to `archive/<category>/`
+2. **Search**: Use grep or file search tools
+3. **Index**: Check `INDEX.md` which includes archived documents
+4. **Unarchiving**: Move document back to its category and update status
+
+To unarchive a document:
+```bash
+# Move file back
+mv archive/specs/old-spec.md specs/
+
+# Update metadata
+# Change status from 'archived' to 'active' or appropriate status
+# Remove archived_date and archive_reason fields
+```
+
+## Monitoring
+
+The archiving script provides a summary:
+```
+Archive Summary:
+  Documents scanned: 45
+  Documents archived: 3
+  Documents skipped: 42
+  Errors: 0
+```
+
+Keep an eye on:
+- **Unexpected archives**: Documents archived sooner than expected
+- **Errors**: Failed archiving operations
+- **Zero archives**: May indicate metadata issues (e.g., status never set to `complete`)
--- a/skills/cyberarian/references/metadata-schema.md
+++ b/skills/cyberarian/references/metadata-schema.md
@@ -0,0 +1,125 @@
+# 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