Initial commit

skills/guardian/Templates/README.md

@@ -0,0 +1,304 @@
+# Guardian Templates
+
+This directory contains templates for different Guardian review and planning tasks. Templates provide structured, consistent prompts for Haiku subagents with appropriate constraints and output formats.
+
+## Available Templates
+
+### security_review.json
+**Focus**: Security vulnerabilities and OWASP Top 10
+
+**Best For:**
+- Authentication/authorization code
+- Cryptographic implementations
+- Input validation
+- API endpoints
+- Payment processing
+- Sensitive data handling
+
+**Output Format**: Suggestions with severity, CWE references, exploit scenarios
+
+### performance_review.json
+**Focus**: Performance optimization and efficiency
+
+**Best For:**
+- Database queries
+- API performance
+- Algorithm complexity
+- Memory usage
+- Async operations
+- Caching opportunities
+
+**Output Format**: Suggestions with complexity analysis and estimated improvements
+
+### feature_planning.json
+**Focus**: Breaking down complex features into subtasks
+
+**Best For:**
+- Large feature implementations
+- Multi-component systems
+- Complex refactoring
+- Integration projects
+
+**Output Format**: Subtasks with dependencies, estimates, risks, and acceptance criteria
+
+## Using Templates
+
+### Via Command Line
+
+```bash
+# List available templates
+python guardian/scripts/template_loader.py --list
+
+# Load a template
+python guardian/scripts/template_loader.py --template security_review
+
+# Show template configuration
+python guardian/scripts/template_loader.py --template security_review --show-config
+```
+
+### Via Guardian Skill
+
+```bash
+# Use a template for review
+python guardian/scripts/guardian.py review --file auth.py --template security_review
+
+# Use a template for planning
+python guardian/scripts/guardian.py plan --task "Build REST API" --template feature_planning
+```
+
+### In Code
+
+```python
+from template_loader import load_template, apply_template_to_context
+
+# Load template
+template = load_template('security_review')
+
+# Apply to context
+prompt = apply_template_to_context(template, minimal_context)
+
+# Get configuration for context_filter.py
+config = get_template_config(template)
+```
+
+## Creating Custom Templates
+
+### Option 1: Base on Existing Template
+
+```bash
+python guardian/scripts/template_loader.py \
+    --create my_security_review \
+    --based-on security_review \
+    --description "Custom security review for our codebase"
+```
+
+This creates `my_security_review.json` which you can then customize.
+
+### Option 2: Create from Scratch
+
+```bash
+python guardian/scripts/template_loader.py \
+    --create my_custom_review \
+    --description "Custom review template"
+```
+
+This creates a minimal template you can build on.
+
+### Option 3: Manual Creation
+
+Create a JSON file with this structure:
+
+```json
+{
+  "name": "my_review",
+  "description": "My custom review template",
+  "task_type": "review",
+  "focus": "my_focus_keywords",
+  "agent_prompt_template": "You are a READ-ONLY code reviewer...\n\n{context}\n\nReturn JSON array...",
+  "oracle_categories": ["patterns", "gotchas"],
+  "oracle_tags_required": ["tag1", "tag2"],
+  "max_oracle_patterns": 5,
+  "max_oracle_gotchas": 5,
+  "always_include_files": [],
+  "validation_rules": {
+    "min_confidence": 0.5,
+    "block_contradictions": true
+  }
+}
+```
+
+## Template Structure
+
+### Required Fields
+
+- `name`: Unique template identifier
+- `description`: Human-readable description
+- `task_type`: "review", "plan", or "debug"
+- `agent_prompt_template`: Prompt template with `{context}` placeholder
+
+### Optional Fields
+
+- `focus`: Keywords for context filtering (e.g., "security performance")
+- `oracle_categories`: Oracle knowledge categories to load ["patterns", "gotchas", "corrections", "solutions"]
+- `oracle_tags_required`: Tags to filter Oracle knowledge by
+- `max_oracle_patterns`: Maximum Oracle patterns to include (default: 5)
+- `max_oracle_gotchas`: Maximum Oracle gotchas to include (default: 5)
+- `always_include_files`: Additional files to always include (e.g., config files)
+- `validation_rules`: Rules for validating subagent suggestions
+
+### Validation Rules
+
+```json
+{
+  "min_confidence": 0.5,           // Minimum confidence score to present
+  "block_contradictions": true,     // Block suggestions that contradict Oracle
+  "require_severity": false,        // Require severity field in suggestions
+  "require_impact": false,          // Require impact field in suggestions
+  "require_dependencies": false     // Require dependencies field (for planning)
+}
+```
+
+## Prompt Template Guidelines
+
+### Critical Constraints Section
+
+Always include:
+
+```
+CRITICAL CONSTRAINTS:
+- DO NOT use Write, Edit, NotebookEdit, or Bash tools
+- DO NOT modify any files
+- DO NOT execute any code
+- ONLY read the provided context and return suggestions
+```
+
+### Context Placeholder
+
+Include `{context}` where minimal context should be inserted:
+
+```
+Your task: Review this code for security issues.
+
+{context}
+
+Return your findings...
+```
+
+### Output Format
+
+Specify clear JSON output format:
+
+```json
+[
+  {
+    "text": "Clear description of the issue",
+    "category": "security|performance|style|bugs",
+    "file": "file path",
+    "line": line_number (if applicable, otherwise null)
+  }
+]
+```
+
+### Reminder Section
+
+End with:
+
+```
+Remember: You are READ-ONLY. Only analyze and suggest, never modify.
+```
+
+## Best Practices
+
+### For Review Templates
+
+1. **Be Specific**: Focus on particular types of issues (security, performance, style)
+2. **Provide Examples**: Show what good/bad code looks like
+3. **Reference Standards**: OWASP, CWE, language style guides
+4. **Request Details**: Ask for line numbers, severity, remediation steps
+
+### For Planning Templates
+
+1. **Encourage Decomposition**: Break large tasks into small, testable pieces
+2. **Request Dependencies**: Ask for task ordering and prerequisites
+3. **Ask for Risks**: Identify potential issues early
+4. **Require Estimates**: Time and complexity estimates help prioritization
+
+### For All Templates
+
+1. **Minimal Context**: Only request what's needed for the task
+2. **Read-Only Focus**: Emphasize analysis over action
+3. **Structured Output**: Request JSON for easy parsing
+4. **Oracle Integration**: Leverage Oracle knowledge for context
+
+## Template Versioning
+
+Templates follow semantic versioning via filename suffixes:
+
+- `security_review.json` - Latest version
+- `security_review_v2.json` - Explicit version 2
+- `security_review_legacy.json` - Deprecated version
+
+When updating templates, create a new version and mark old ones as legacy.
+
+## Contributing Templates
+
+To contribute a new template:
+
+1. Create your template following the structure above
+2. Test it with real code reviews
+3. Document what it's best for
+4. Submit a PR with:
+   - Template JSON file
+   - Example usage
+   - Test results
+
+Good templates help the entire community!
+
+## Examples
+
+### Example: Security Review
+
+```bash
+# Run security review on auth file
+python guardian/scripts/guardian.py review \
+    --file src/auth.py \
+    --template security_review
+
+# Guardian will:
+# 1. Load security_review.json template
+# 2. Extract minimal context (auth.py + security Oracle patterns)
+# 3. Apply template to context
+# 4. Spawn Haiku agent with structured prompt
+# 5. Validate suggestions against Oracle
+# 6. Present results with confidence scores
+```
+
+### Example: Performance Review
+
+```bash
+# Run performance review on database queries
+python guardian/scripts/guardian.py review \
+    --file src/database/queries.py \
+    --template performance_review
+
+# Focuses on:
+# - Query complexity
+# - N+1 problems
+# - Missing indexes
+# - Caching opportunities
+```
+
+### Example: Feature Planning
+
+```bash
+# Plan a new REST API
+python guardian/scripts/guardian.py plan \
+    --task "Build REST API with auth and rate limiting" \
+    --template feature_planning
+
+# Returns:
+# - Subtask breakdown
+# - Dependencies
+# - Estimates
+# - Risk assessment
+```

skills/guardian/Templates/feature_planning.json

@@ -0,0 +1,17 @@
+{
+  "name": "feature_planning",
+  "description": "Feature development task breakdown template",
+  "task_type": "plan",
+  "focus": "task_breakdown",
+  "agent_prompt_template": "You are a READ-ONLY task planner for Guardian. You can ONLY analyze and plan.\n\nCRITICAL CONSTRAINTS:\n- DO NOT use Write, Edit, NotebookEdit, or Bash tools\n- DO NOT modify any files\n- DO NOT execute any code\n- ONLY analyze the task and return a breakdown plan\n\nYour task: Break down this feature into implementable subtasks.\n\n{context}\n\n**Planning Methodology:**\n\n1. **Decomposition Strategy:**\n   - Start with infrastructure/foundation tasks\n   - Build incrementally (each task should be independently testable)\n   - Identify critical path and parallel work opportunities\n   - Consider deployment and rollback strategies\n\n2. **Task Characteristics:**\n   - Each task should be completable in one focused session\n   - Clear acceptance criteria\n   - Minimal coupling with other tasks\n   - Explicit dependencies\n\n3. **Risk Assessment:**\n   - Identify high-risk/high-complexity tasks\n   - Suggest proof-of-concept or spike tasks for unknowns\n   - Consider edge cases and error scenarios\n\n4. **Integration Points:**\n   - API contracts\n   - Database schema changes\n   - Configuration requirements\n   - Third-party dependencies\n\nReturn your plan as a JSON array of subtasks with this format:\n[\n  {{\n    \"task_id\": \"unique_identifier\",\n    \"task\": \"Clear, actionable description of the subtask\",\n    \"estimated_lines\": approximate lines of code needed,\n    \"estimated_time\": \"e.g., '1 hour', '2-3 hours', '1 day'\",\n    \"dependencies\": [\"list\", \"of\", \"prerequisite\", \"task_ids\"],\n    \"files_affected\": [\"list of files that will be created/modified\"],\n    \"priority\": \"high|medium|low\",\n    \"complexity\": \"high|medium|low\",\n    \"risks\": [\"list of potential risks or unknowns\"],\n    \"acceptance_criteria\": [\"specific criteria to consider task complete\"],\n    \"testing_strategy\": \"How to test this subtask\"\n  }}\n]\n\nAlso include a summary:\n{{\n  \"total_tasks\": number,\n  \"critical_path\": [\"task_ids in order\"],\n  \"parallel_opportunities\": [[\"task_ids that can be done in parallel\"]],\n  \"estimated_total_time\": \"e.g., '1-2 days'\",\n  \"high_risk_tasks\": [\"task_ids\"],\n  \"recommended_order\": [\"task_ids in recommended execution order\"]\n}}\n\nRemember: You are READ-ONLY. Only analyze and plan, never modify.",
+  "oracle_categories": ["patterns", "solutions"],
+  "oracle_tags_required": [],
+  "max_oracle_patterns": 5,
+  "max_oracle_gotchas": 3,
+  "always_include_files": [],
+  "validation_rules": {
+    "min_confidence": 0.6,
+    "block_contradictions": false,
+    "require_dependencies": true
+  }
+}

skills/guardian/Templates/performance_review.json

@@ -0,0 +1,17 @@
+{
+  "name": "performance_review",
+  "description": "Performance and optimization code review template",
+  "task_type": "review",
+  "focus": "performance",
+  "agent_prompt_template": "You are a READ-ONLY performance code reviewer for Guardian. You can ONLY analyze and suggest.\n\nCRITICAL CONSTRAINTS:\n- DO NOT use Write, Edit, NotebookEdit, or Bash tools\n- DO NOT modify any files\n- DO NOT execute any code\n- ONLY read the provided context and return suggestions\n\nYour task: Perform a thorough performance review focusing on:\n\n**Algorithmic Efficiency:**\n- Time complexity (O(n), O(n²), O(log n), etc.)\n- Space complexity and memory usage\n- Unnecessary iterations or nested loops\n- Inefficient data structures\n\n**Common Performance Issues:**\n- N+1 query problems\n- Premature optimization\n- Synchronous operations that should be async\n- Blocking I/O operations\n- Missing indexes on database queries\n- Unnecessary object creation/allocation\n- String concatenation in loops\n- Regex compilation in hot paths\n- Missing caching opportunities\n- Memory leaks\n\n**Platform-Specific:**\n- JavaScript: Unnecessary re-renders, large bundle sizes\n- Python: GIL contention, list comprehensions vs generators\n- Database: Missing indexes, inefficient joins, full table scans\n- API: Missing rate limiting, pagination, compression\n\n{context}\n\nReturn your findings as a JSON array of suggestions with this format:\n[\n  {{\n    \"text\": \"Clear description of the performance issue and recommended fix\",\n    \"category\": \"performance\",\n    \"impact\": \"critical|high|medium|low\",\n    \"file\": \"file path\",\n    \"line\": line_number (if applicable, otherwise null),\n    \"current_complexity\": \"O(...) or description\",\n    \"improved_complexity\": \"O(...) or description\",\n    \"estimated_improvement\": \"e.g., '10x faster', '50% less memory'\"\n  }}\n]\n\nIf you find no performance issues, return an empty array: []\n\nRemember: You are READ-ONLY. Only analyze and suggest, never modify.",
+  "oracle_categories": ["patterns", "gotchas"],
+  "oracle_tags_required": ["performance", "optimization", "async", "caching"],
+  "max_oracle_patterns": 8,
+  "max_oracle_gotchas": 5,
+  "always_include_files": [],
+  "validation_rules": {
+    "min_confidence": 0.5,
+    "block_contradictions": true,
+    "require_impact": true
+  }
+}

skills/guardian/Templates/security_review.json

@@ -0,0 +1,17 @@
+{
+  "name": "security_review",
+  "description": "Security-focused code review template",
+  "task_type": "review",
+  "focus": "security",
+  "agent_prompt_template": "You are a READ-ONLY security code reviewer for Guardian. You can ONLY analyze and suggest.\n\nCRITICAL CONSTRAINTS:\n- DO NOT use Write, Edit, NotebookEdit, or Bash tools\n- DO NOT modify any files\n- DO NOT execute any code\n- ONLY read the provided context and return suggestions\n\nYour task: Perform a thorough security review focusing on:\n\n**OWASP Top 10 (2025):**\n1. Injection vulnerabilities (SQL, Command, XSS, etc.)\n2. Broken authentication and session management\n3. Sensitive data exposure\n4. XML external entities (XXE)\n5. Broken access control\n6. Security misconfiguration\n7. Cross-site scripting (XSS)\n8. Insecure deserialization\n9. Using components with known vulnerabilities\n10. Insufficient logging and monitoring\n\n**Additional Security Checks:**\n- Cryptographic weaknesses (weak algorithms, hardcoded keys)\n- Race conditions and TOCTOU vulnerabilities\n- Input validation and sanitization\n- Output encoding\n- CSRF protection\n- Secure defaults\n- Principle of least privilege\n- Defense in depth\n\n{context}\n\nReturn your findings as a JSON array of suggestions with this format:\n[\n  {{\n    \"text\": \"Clear description of the security issue and recommended fix\",\n    \"category\": \"security\",\n    \"severity\": \"critical|high|medium|low\",\n    \"cwe\": \"CWE-XXX (if applicable)\",\n    \"file\": \"file path\",\n    \"line\": line_number (if applicable, otherwise null),\n    \"exploit_scenario\": \"Brief description of how this could be exploited\",\n    \"remediation\": \"Specific fix recommendation\"\n  }}\n]\n\nIf you find no security issues, return an empty array: []\n\nRemember: You are READ-ONLY. Only analyze and suggest, never modify.",
+  "oracle_categories": ["patterns", "gotchas", "corrections"],
+  "oracle_tags_required": ["security", "auth", "crypto", "injection", "xss"],
+  "max_oracle_patterns": 10,
+  "max_oracle_gotchas": 5,
+  "always_include_files": ["*.config", "*.env.example"],
+  "validation_rules": {
+    "min_confidence": 0.4,
+    "block_contradictions": true,
+    "require_severity": true
+  }
+}

skills/guardian/Templates/session_health.json

@@ -0,0 +1,131 @@
+{
+  "name": "Session Health Monitor",
+  "description": "Tracks session degradation signals and recommends when to start fresh",
+  "version": "1.0.0",
+  "triggers": {
+    "automatic": true,
+    "interval_minutes": 10,
+    "on_error": true,
+    "on_correction": true
+  },
+  "metrics": {
+    "context_usage": {
+      "check": "token_count / max_tokens",
+      "warning_threshold": 0.7,
+      "critical_threshold": 0.85,
+      "weight": 0.25
+    },
+    "error_frequency": {
+      "check": "errors_last_30min",
+      "warning_threshold": 3,
+      "critical_threshold": 5,
+      "weight": 0.2
+    },
+    "correction_rate": {
+      "check": "corrections_last_30min",
+      "warning_threshold": 3,
+      "critical_threshold": 5,
+      "weight": 0.2
+    },
+    "file_churn": {
+      "check": "same_file_edits_in_10min",
+      "warning_threshold": 5,
+      "critical_threshold": 8,
+      "weight": 0.15
+    },
+    "repeated_errors": {
+      "check": "same_error_count",
+      "warning_threshold": 2,
+      "critical_threshold": 3,
+      "weight": 0.2
+    }
+  },
+  "health_score_calculation": "weighted_average_of_metrics",
+  "recommendations": {
+    "90-100": {
+      "status": "✅ Excellent",
+      "color": "green",
+      "message": "Session is healthy. Continue working.",
+      "action": "none"
+    },
+    "70-89": {
+      "status": "✓ Good",
+      "color": "blue",
+      "message": "Session is performing well.",
+      "action": "none"
+    },
+    "50-69": {
+      "status": "⚠️  Fair",
+      "color": "yellow",
+      "message": "Session showing minor degradation. Consider taking a break or refocusing.",
+      "action": "suggest_break"
+    },
+    "30-49": {
+      "status": "⚠️  Warning",
+      "color": "orange",
+      "message": "Session degrading. Recommend starting fresh session soon.",
+      "action": "suggest_handoff"
+    },
+    "0-29": {
+      "status": "❌ Critical",
+      "color": "red",
+      "message": "Session severely degraded. Strongly recommend session handoff NOW.",
+      "action": "recommend_handoff_now"
+    }
+  },
+  "handoff_triggers": {
+    "health_below": 40,
+    "context_above": 0.85,
+    "repeated_errors_above": 3,
+    "corrections_above": 5,
+    "session_duration_minutes": 180
+  },
+  "dashboard_display": {
+    "show_in_status": true,
+    "format": "Session Health: {score}/100 {status_icon}",
+    "details_on_request": true,
+    "details_format": {
+      "title": "Session Health Dashboard",
+      "sections": [
+        {
+          "name": "Overall Health",
+          "display": "{score}/100 - {status}"
+        },
+        {
+          "name": "Metrics",
+          "display": [
+            "Context Usage: {context_usage}% ({status_icon})",
+            "Error Rate: {errors_last_30min} in 30min ({status_icon})",
+            "Correction Rate: {corrections_last_30min} in 30min ({status_icon})",
+            "File Churn: {max_file_edit_count} edits to same file ({status_icon})",
+            "Repeated Errors: {repeated_error_count} ({status_icon})"
+          ]
+        },
+        {
+          "name": "Recommendation",
+          "display": "{recommendation_message}"
+        },
+        {
+          "name": "Session Stats",
+          "display": [
+            "Duration: {duration_minutes} minutes",
+            "Files Modified: {files_modified_count}",
+            "Commands Run: {commands_run_count}",
+            "Tokens Used: {tokens_used}/{max_tokens}"
+          ]
+        }
+      ]
+    }
+  },
+  "oracle_integration": {
+    "record_health_scores": true,
+    "record_handoff_events": true,
+    "track_degradation_patterns": true,
+    "learn_from_successful_sessions": true
+  },
+  "evaluator_integration": {
+    "track_health_metrics": true,
+    "track_handoff_frequency": true,
+    "track_post_handoff_success": true
+  }
+}