xtrm-tools 0.5.0

package/skills/documenting/scripts/generate_template.py

@@ -0,0 +1,311 @@
+#!/usr/bin/env python3
+"""
+Generate SSOT memory template with boilerplate metadata.
+
+Creates a new memory file with proper frontmatter structure based on category type.
+"""
+
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+TEMPLATES = {
+    "ssot": """---
+title: {title}
+version: 0.1.0
+updated: {timestamp}
+scope: {scope}
+category: {category}
+subcategory: {subcategory}
+domain: [{domain}]
+applicability: {applicability}
+tracks: []
+changelog:
+  - 0.1.0 ({date}): Initial creation.
+---
+
+<!-- INDEX: auto-generated by validate_metadata.py — do not edit manually -->
+| Section | Summary |
+|---|---|
+<!-- END INDEX -->
+
+## Purpose
+{purpose}
+
+## Overview
+{overview}
+
+## Key Components
+
+### Component 1
+Description...
+
+### Component 2
+Description...
+
+## Current State
+
+### What Works
+- Item 1
+- Item 2
+
+### Known Limitations
+- Limitation 1
+- Limitation 2
+
+## Related SSOTs
+- `related_ssot_1.md` - Description
+- `related_ssot_2.md` - Description
+
+## Next Steps
+- [ ] Task 1
+- [ ] Task 2
+
+## References
+- Internal doc references
+- External resources
+""",
+
+    "pattern": """---
+title: {title}
+version: 0.1.0
+updated: {timestamp}
+scope: {scope}
+category: pattern
+subcategory: {subcategory}
+domain: [{domain}]
+applicability: {applicability}
+tracks: []
+changelog:
+  - 0.1.0 ({date}): Initial creation.
+---
+
+<!-- INDEX: auto-generated by validate_metadata.py — do not edit manually -->
+| Section | Summary |
+|---|---|
+<!-- END INDEX -->
+
+## Purpose
+{purpose}
+
+## Pattern Description
+{description}
+
+## When to Apply
+- Scenario 1
+- Scenario 2
+
+## Implementation
+
+### Approach
+Steps to implement this pattern...
+
+### Example
+```python
+# Code example
+```
+
+## Trade-offs
+
+### Benefits
+- Benefit 1
+- Benefit 2
+
+### Costs
+- Cost 1
+- Cost 2
+
+## Related Patterns
+- `related_pattern_1.md`
+- `related_pattern_2.md`
+""",
+
+    "reference": """---
+title: {title}
+scope: {scope}
+category: reference
+subcategory: {subcategory}
+domain: [{domain}]
+tracks: []
+---
+
+<!-- INDEX: auto-generated by validate_metadata.py — do not edit manually -->
+| Section | Summary |
+|---|---|
+<!-- END INDEX -->
+
+## Purpose
+{purpose}
+
+## Quick Reference
+
+### Category 1
+| Item | Description | Example |
+|------|-------------|---------|
+| Item1 | Desc | `example` |
+
+### Category 2
+Details...
+
+## Detailed Documentation
+
+### Section 1
+Content...
+
+### Section 2
+Content...
+
+## Examples
+
+### Example 1: {example_name}
+```
+Code or configuration example
+```
+
+### Example 2: {example_name}
+```
+Code or configuration example
+```
+
+## Additional Resources
+- Link 1
+- Link 2
+""",
+
+    "plan": """---
+title: {title}
+version: 0.1.0
+updated: {timestamp}
+scope: {scope}
+category: plan
+subcategory: {subcategory}
+status: draft
+tracks: []
+changelog:
+  - 0.1.0 ({date}): Initial plan creation.
+tracks: []
+---
+
+<!-- INDEX: auto-generated by validate_metadata.py — do not edit manually -->
+| Section | Summary |
+|---|---|
+<!-- END INDEX -->
+
+## Objective
+{objective}
+
+## Background
+{background}
+
+## Proposed Approach
+
+### Phase 1: {phase_name}
+- Task 1
+- Task 2
+
+### Phase 2: {phase_name}
+- Task 1
+- Task 2
+
+## Success Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Risks & Mitigations
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Risk 1 | High | Mitigation strategy |
+
+## Timeline
+- Phase 1: Dates
+- Phase 2: Dates
+
+## Related Docs
+- `related_ssot.md`
+- `related_pattern.md`
+""",
+}
+
+
+def generate_timestamp():
+    """Generate ISO8601 timestamp with timezone."""
+    return datetime.now(timezone.utc).isoformat()
+
+
+def generate_date():
+    """Generate YYYY-MM-DD date."""
+    return datetime.now().strftime("%Y-%m-%d")
+
+
+def generate_template(category, **kwargs):
+    """Generate memory template from category."""
+    if category not in TEMPLATES:
+        print(f"ERROR: Invalid category: {category}")
+        print(f"Valid categories: {', '.join(TEMPLATES.keys())}")
+        sys.exit(1)
+
+    # Merge defaults with user-provided values
+    params = {
+        "title": "New Memory",
+        "timestamp": generate_timestamp(),
+        "date": generate_date(),
+        "scope": "to-be-defined",
+        "category": category,
+        "subcategory": "general",
+        "domain": "domain1, domain2",
+        "applicability": "specific area or 'all'",
+        "purpose": "Brief statement of purpose...",
+        "overview": "High-level overview...",
+        "description": "Detailed description...",
+        "objective": "What this plan aims to achieve...",
+        "background": "Context and motivation...",
+        "phase_name": "Phase Name",
+        "example_name": "Example Name",
+    }
+    params.update(kwargs)
+
+    return TEMPLATES[category].format(**params)
+
+
+def main():
+    if len(sys.argv) < 3:
+        print("Usage: generate_template.py <category> <output_filename> [key=value ...]")
+        print("")
+        print("Categories: ssot, pattern, reference, plan")
+        print("")
+        print("Examples:")
+        print("  generate_template.py ssot analytics_new_ssot.md \\")
+        print("      title='New Analytics SSOT' domain='analytics' subcategory='metrics'")
+        print("")
+        print("  generate_template.py pattern caching_strategy_pattern.md \\")
+        print("      title='Caching Strategy Pattern' domain='performance'")
+        sys.exit(1)
+
+    category = sys.argv[1]
+    output_file = sys.argv[2]
+
+    # Parse optional key=value parameters
+    params = {}
+    for arg in sys.argv[3:]:
+        if '=' in arg:
+            key, value = arg.split('=', 1)
+            params[key] = value.strip("'\"")
+
+    # Generate template
+    content = generate_template(category, **params)
+
+    # Write to file
+    output_path = Path(output_file)
+    if output_path.exists():
+        print(f"ERROR: File already exists: {output_file}")
+        print("Use a different filename or remove the existing file first.")
+        sys.exit(1)
+
+    output_path.write_text(content, encoding='utf-8')
+    print(f"✅ Created {category} memory: {output_file}")
+    print(f"📝 Edit the file to fill in placeholders and add content.")
+
+
+if __name__ == "__main__":
+    main()

package/skills/documenting/scripts/list_by_category.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+# List Serena memories filtered by category suffix
+#
+# Usage: list_by_category.sh [category]
+# category: ssot | pattern | plan | reference | archive | troubleshoot | all
+#
+# Examples:
+#   list_by_category.sh ssot       -> List all SSOT memories
+#   list_by_category.sh archive    -> List all archived memories
+#   list_by_category.sh all        -> List all memories grouped by category
+
+set -e
+
+CATEGORY="${1:-all}"
+MEMORIES_DIR="${SERENA_MEMORIES_DIR:-.serena/memories}"
+
+if [ ! -d "$MEMORIES_DIR" ]; then
+    echo "ERROR: Memories directory not found: $MEMORIES_DIR"
+    echo "Set SERENA_MEMORIES_DIR environment variable or run from project root"
+    exit 1
+fi
+
+# Function to list files with a given suffix
+list_suffix() {
+    local suffix=$1
+    local label=$2
+    local files
+
+    files=$(find "$MEMORIES_DIR" -maxdepth 1 -name "*_${suffix}.md" -type f 2>/dev/null | sort)
+
+    if [ -n "$files" ]; then
+        echo ""
+        echo "=== ${label} ==="
+        echo "$files" | while read -r file; do
+            basename "$file"
+        done
+    fi
+}
+
+# List by category
+case "$CATEGORY" in
+    ssot)
+        list_suffix "ssot" "SSOT Memories"
+        ;;
+    pattern)
+        list_suffix "pattern" "Pattern Memories"
+        ;;
+    plan)
+        list_suffix "plan" "Plan Memories"
+        ;;
+    reference)
+        list_suffix "reference" "Reference Memories"
+        ;;
+    archive)
+        list_suffix "archive" "Archived Memories"
+        ;;
+    troubleshoot)
+        list_suffix "troubleshoot" "Troubleshooting Guides"
+        ;;
+    all)
+        echo "Memories in: $MEMORIES_DIR"
+        list_suffix "ssot" "SSOT Memories"
+        list_suffix "pattern" "Pattern Memories"
+        list_suffix "plan" "Plan Memories"
+        list_suffix "reference" "Reference Memories"
+        list_suffix "troubleshoot" "Troubleshooting Guides"
+        list_suffix "archive" "Archived Memories (Deprecated)"
+
+        # Count special files
+        commit_logs=$(find "$MEMORIES_DIR" -maxdepth 1 -name "*_commit_log.md" -type f 2>/dev/null | wc -l)
+        if [ "$commit_logs" -gt 0 ]; then
+            echo ""
+            echo "=== Commit Logs ==="
+            find "$MEMORIES_DIR" -maxdepth 1 -name "*_commit_log.md" -type f | sort | while read -r file; do
+                basename "$file"
+            done
+        fi
+        ;;
+    *)
+        echo "ERROR: Invalid category: $CATEGORY"
+        echo "Valid categories: ssot, pattern, plan, reference, archive, troubleshoot, all"
+        exit 1
+        ;;
+esac

package/skills/documenting/scripts/orchestrator.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+"""
+Documentation orchestrator for coordinating SSOT, CHANGELOG, README, CLAUDE.md updates.
+
+Workflow:
+1. Classify change type (feature, bugfix, refactor, breaking, docs, chore)
+2. Update SSOT memories (.serena/memories/)
+3. Update CHANGELOG.md
+4. Suggest README.md updates
+5. Suggest CLAUDE.md/AGENT.md updates
+6. Validate all changes
+"""
+
+import sys
+from enum import Enum
+from pathlib import Path
+from typing import Dict, List, Optional
+from datetime import datetime, timezone
+
+from scripts.changelog.add_entry import add_entry_to_file, ChangeCategory
+from scripts.changelog.validate_changelog import validate_file as validate_changelog_file
+
+
+class ChangeType(Enum):
+    """Types of changes to document."""
+    FEATURE = "feature"
+    BUGFIX = "bugfix"
+    REFACTOR = "refactor"
+    BREAKING = "breaking"
+    DOCS = "docs"
+    CHORE = "chore"
+
+
+# Mapping of ChangeType to CHANGELOG category
+CHANGE_TYPE_TO_CATEGORY = {
+    ChangeType.FEATURE: ChangeCategory.ADDED,
+    ChangeType.BUGFIX: ChangeCategory.FIXED,
+    ChangeType.REFACTOR: ChangeCategory.CHANGED,
+    ChangeType.BREAKING: ChangeCategory.CHANGED,
+    ChangeType.DOCS: ChangeCategory.CHANGED,
+    ChangeType.CHORE: ChangeCategory.CHANGED,
+}
+
+
+class DocumentingOrchestrator:
+    """Coordinates documentation updates across multiple doc types."""
+
+    def __init__(self, project_root: Path):
+        self.project_root = Path(project_root)
+        self.changelog_path = self.project_root / "CHANGELOG.md"
+        self.readme_path = self.project_root / "README.md"
+        self.claude_path = self._find_agent_doc()
+        self.ssot_dir = self.project_root / ".serena" / "memories"
+
+    def _find_agent_doc(self) -> Optional[Path]:
+        """Find CLAUDE.md or AGENT.md."""
+        for name in ["CLAUDE.md", "AGENT.md"]:
+            path = self.project_root / name
+            if path.exists():
+                return path
+        return None
+
+    def document_change(
+        self,
+        change_type: ChangeType,
+        description: str,
+        details: Optional[Dict] = None
+    ) -> Dict:
+        """
+        Document a change across all relevant documentation.
+
+        Args:
+            change_type: Type of change
+            description: Brief description
+            details: Additional context:
+                - scope: SSOT scope identifier
+                - category: SSOT category
+                - subcategory: SSOT subcategory
+                - files_changed: List of affected files
+                - breaking: Whether change is breaking
+
+        Returns:
+            {
+                "changelog_updated": bool,
+                "ssot_updated": bool,
+                "ssot_file": Optional[Path],
+                "readme_suggestions": List[str],
+                "claude_suggestions": List[str],
+                "validation_errors": List[str]
+            }
+        """
+        details = details or {}
+        result = {
+            "changelog_updated": False,
+            "ssot_updated": False,
+            "ssot_file": None,
+            "readme_suggestions": [],
+            "claude_suggestions": [],
+            "validation_errors": []
+        }
+
+        # 1. Update CHANGELOG
+        if self.changelog_path.exists():
+            try:
+                category = CHANGE_TYPE_TO_CATEGORY[change_type]
+                if details.get("breaking"):
+                    description = f"**BREAKING**: {description}"
+
+                add_entry_to_file(self.changelog_path, category, description)
+                result["changelog_updated"] = True
+            except Exception as e:
+                result["validation_errors"].append(f"CHANGELOG update failed: {e}")
+
+        # 2. Update/Create SSOT (if relevant)
+        if change_type in [ChangeType.FEATURE, ChangeType.REFACTOR, ChangeType.BREAKING]:
+            ssot_result = self._update_ssot(change_type, description, details)
+            result.update(ssot_result)
+
+        # 3. Generate README suggestions
+        if change_type == ChangeType.FEATURE:
+            result["readme_suggestions"] = self._generate_readme_suggestions(description, details)
+
+        # 4. Generate CLAUDE.md suggestions
+        if change_type in [ChangeType.FEATURE, ChangeType.REFACTOR]:
+            result["claude_suggestions"] = self._generate_claude_suggestions(description, details)
+
+        # 5. Validate all documentation
+        validation = self.validate_all()
+        result["validation_errors"].extend(validation["errors"])
+
+        return result
+
+    def _update_ssot(self, change_type: ChangeType, description: str, details: Dict) -> Dict:
+        """Update or create SSOT memory."""
+        # This will be implemented with Serena tools in later tasks
+        # For now, just return placeholder
+        return {
+            "ssot_updated": False,
+            "ssot_file": None
+        }
+
+    def _generate_readme_suggestions(self, description: str, details: Dict) -> List[str]:
+        """Generate suggestions for README.md updates."""
+        suggestions = []
+
+        # Suggest updating features section
+        suggestions.append(f"Consider adding to ## Features section: {description}")
+
+        # If files_changed includes examples, suggest updating usage
+        if details.get("files_changed"):
+            if any("example" in f.lower() for f in details["files_changed"]):
+                suggestions.append("Update ## Usage section with new example")
+
+        return suggestions
+
+    def _generate_claude_suggestions(self, description: str, details: Dict) -> List[str]:
+        """Generate suggestions for CLAUDE.md/AGENT.md updates."""
+        suggestions = []
+
+        if not self.claude_path:
+            return suggestions
+
+        # Suggest architecture updates for major features
+        suggestions.append(f"Review ## Architecture section for: {description}")
+
+        # If files_changed affects setup, suggest updating
+        if details.get("files_changed"):
+            setup_files = ["requirements.txt", "package.json", ".env", "docker-compose.yml"]
+            if any(f in details["files_changed"] for f in setup_files):
+                suggestions.append("Update ## Development Environment section")
+
+        return suggestions
+
+    def validate_all(self) -> Dict:
+        """Validate all documentation."""
+        errors = []
+        warnings = []
+
+        # Validate CHANGELOG
+        if self.changelog_path.exists():
+            result = validate_changelog_file(self.changelog_path)
+            errors.extend(result.get("errors", []))
+            warnings.extend(result.get("warnings", []))
+
+        # TODO: Add SSOT validation
+        # TODO: Add README validation (check for broken links, etc.)
+
+        return {
+            "valid": len(errors) == 0,
+            "errors": errors,
+            "warnings": warnings
+        }
+
+
+def main():
+    """CLI entry point."""
+    if len(sys.argv) < 4:
+        print("Usage: orchestrator.py <project_root> <change_type> <description> [--scope=X] [--category=Y]")
+        print("")
+        print("Change Types: feature, bugfix, refactor, breaking, docs, chore")
+        print("")
+        print("Example:")
+        print('  orchestrator.py . feature "Add semantic search" --scope=search --category=backend')
+        sys.exit(1)
+
+    project_root = Path(sys.argv[1])
+    change_type = ChangeType(sys.argv[2])
+    description = sys.argv[3]
+
+    # Parse optional details
+    details = {}
+    for arg in sys.argv[4:]:
+        if arg.startswith("--"):
+            key, value = arg[2:].split("=", 1)
+            details[key] = value
+
+    orchestrator = DocumentingOrchestrator(project_root)
+    result = orchestrator.document_change(change_type, description, details)
+
+    # Print results
+    print("")
+    print("📝 Documentation Update Results")
+    print("=" * 60)
+
+    if result["changelog_updated"]:
+        print("✅ CHANGELOG.md updated")
+
+    if result["ssot_updated"]:
+        print(f"✅ SSOT updated: {result['ssot_file']}")
+
+    if result["readme_suggestions"]:
+        print("")
+        print("💡 README.md suggestions:")
+        for suggestion in result["readme_suggestions"]:
+            print(f"  - {suggestion}")
+
+    if result["claude_suggestions"]:
+        print("")
+        print("💡 CLAUDE.md suggestions:")
+        for suggestion in result["claude_suggestions"]:
+            print(f"  - {suggestion}")
+
+    if result["validation_errors"]:
+        print("")
+        print("❌ Validation errors:")
+        for error in result["validation_errors"]:
+            print(f"  - {error}")
+        sys.exit(1)
+
+    print("")
+    print("✅ All documentation validated")
+
+
+if __name__ == "__main__":
+    main()