Initial commit

skills/cyberarian/scripts/init_docs_structure.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""
+Initialize the docs/ directory structure for document lifecycle management.
+Creates all required directories and initial README.md.
+"""
+
+import os
+import sys
+from pathlib import Path
+from datetime import datetime
+
+
+DIRECTORY_STRUCTURE = {
+    'ai_docs': 'Reference materials for Claude Code: SDKs, API docs, repo context',
+    'specs': 'Feature and migration specifications',
+    'analysis': 'Investigation outputs: bug hunting, optimization, cleanup',
+    'plans': 'Implementation plans from specs, analysis, or ad-hoc tasks',
+    'templates': 'Reusable document templates',
+    'archive': 'Historical and completed documents'
+}
+
+
+README_TEMPLATE = """# Documentation Structure
+
+This directory contains project documentation organized by purpose and lifecycle stage.
+
+## Directory Structure
+
+{directory_descriptions}
+
+## Document Lifecycle
+
+Documents follow a lifecycle managed through YAML frontmatter:
+
+1. **Draft** → Document is being created
+2. **Active** → Document is current and relevant
+3. **Complete** → Work is done, kept for reference
+4. **Archived** → Moved to archive/ when no longer relevant
+
+## Metadata Requirements
+
+All documents should include YAML frontmatter:
+
+```yaml
+---
+title: Document Title
+category: specs|analysis|plans|ai_docs|templates
+status: draft|active|complete|archived
+created: YYYY-MM-DD
+last_updated: YYYY-MM-DD
+tags: [tag1, tag2]
+---
+```
+
+See INDEX.md for a complete list of all documents.
+
+## Temporary Documents
+
+Ephemeral/scratch documents should be created in `/tmp` or system temp directories,
+NOT in this docs/ directory. The docs/ directory is for persistent documentation only.
+
+---
+Last updated: {timestamp}
+"""
+
+
+def create_directory_structure(base_path: Path) -> None:
+    """Create the docs directory structure."""
+    docs_path = base_path / 'docs'
+    
+    # Create main docs directory
+    docs_path.mkdir(exist_ok=True)
+    print(f"✅ Created: {docs_path}")
+    
+    # Create category directories
+    for directory, description in DIRECTORY_STRUCTURE.items():
+        dir_path = docs_path / directory
+        dir_path.mkdir(exist_ok=True)
+        print(f"✅ Created: {dir_path}")
+        
+        # Create .gitkeep for empty directories
+        gitkeep = dir_path / '.gitkeep'
+        if not any(dir_path.iterdir()):
+            gitkeep.touch()
+
+
+def create_readme(base_path: Path) -> None:
+    """Create the README.md file."""
+    docs_path = base_path / 'docs'
+    readme_path = docs_path / 'README.md'
+    
+    # Format directory descriptions
+    descriptions = []
+    for directory, description in DIRECTORY_STRUCTURE.items():
+        descriptions.append(f"- **{directory}/** - {description}")
+    
+    readme_content = README_TEMPLATE.format(
+        directory_descriptions='\n'.join(descriptions),
+        timestamp=datetime.now().strftime('%Y-%m-%d')
+    )
+    
+    readme_path.write_text(readme_content)
+    print(f"✅ Created: {readme_path}")
+
+
+def create_index(base_path: Path) -> None:
+    """Create initial INDEX.md file."""
+    docs_path = base_path / 'docs'
+    index_path = docs_path / 'INDEX.md'
+    
+    index_content = f"""# Documentation Index
+
+Auto-generated index of all documents. Last updated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
+
+Run `python scripts/index_docs.py` to regenerate this index.
+
+---
+
+## Summary
+
+Total documents: 0
+
+---
+
+_No documents found. Add documents to the category directories and regenerate the index._
+"""
+    
+    index_path.write_text(index_content)
+    print(f"✅ Created: {index_path}")
+
+
+def main():
+    """Main entry point."""
+    if len(sys.argv) > 1:
+        base_path = Path(sys.argv[1]).resolve()
+    else:
+        base_path = Path.cwd()
+    
+    print(f"Initializing docs structure at: {base_path}")
+    print()
+    
+    create_directory_structure(base_path)
+    create_readme(base_path)
+    create_index(base_path)
+    
+    print()
+    print("🎉 Documentation structure initialized successfully!")
+    print()
+    print("Next steps:")
+    print("1. Add documents to the category directories")
+    print("2. Run 'python scripts/index_docs.py' to update the index")
+    print("3. Run 'python scripts/archive_docs.py' periodically to maintain the archive")
+
+
+if __name__ == '__main__':
+    main()