xtrm-tools 0.6.0 → 0.7.1

package/plugins/xtrm-tools/skills/documenting/scripts/generate_template.py

@@ -1,311 +0,0 @@
-#!/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/plugins/xtrm-tools/skills/documenting/scripts/list_by_category.sh

@@ -1,84 +0,0 @@
-#!/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/plugins/xtrm-tools/skills/documenting/scripts/orchestrator.py

@@ -1,255 +0,0 @@
-#!/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()