create-universal-ai-context 2.0.0

package/templates/base/agents/deployment-ops.md

@@ -0,0 +1,76 @@
+---
+name: deployment-ops
+version: "1.0.0"
+displayName: "Deployment Operations"
+description: "CI/CD pipeline management, infrastructure as code, and deployment automation specialist"
+category: "deployment"
+complexity: "high"
+context_budget: "~45K tokens"
+capabilities:
+  - "ci-cd-pipeline-design"
+  - "infrastructure-as-code"
+  - "deployment-strategies"
+  - "environment-management"
+  - "monitoring-and-rollback"
+workflows:
+  - "deployment"
+  - "infrastructure"
+  - "ci-cd"
+commands: ["/rpi-research", "/rpi-plan", "/rpi-implement", "/validate-all"]
+dependencies:
+  agents: []
+  commands: []
+hooks:
+  pre_invoke: null
+  post_invoke: "verify-docs-current"
+examples:
+  - invocation: '@deployment-ops "Document deployment pipeline"'
+    description: "Create CI/CD documentation"
+  - invocation: '@deployment-ops "Review infrastructure configuration"'
+    description: "Audit IaC files and configurations"
+  - invocation: '@deployment-ops "Plan rollback strategy"'
+    description: "Design safe rollback procedures"
+---
+
+# Deployment Ops Agent
+
+**Purpose:** CI/CD pipeline management, infrastructure as code, and deployment automation
+
+## Capabilities
+
+This agent specializes in:
+- **Pipeline design and optimization** - Creating and optimizing CI/CD pipelines
+- **Infrastructure as code** - Managing cloud infrastructure with Terraform, CloudFormation, etc.
+- **Deployment strategies** - Implementing blue-green, canary, rolling deployments
+- **Environment management** - Managing development, staging, and production environments
+- **Monitoring and rollback** - Implementing monitoring and automatic rollback strategies
+
+## Usage
+
+After template initialization, this agent will be generated based on your deployment requirements. It will:
+1. Analyze your existing deployment pipelines
+2. Create comprehensive deployment documentation
+3. Identify potential reliability issues
+4. Provide recommendations for deployment optimization
+
+## Example Commands
+
+```bash
+@deployment-ops "Document deployment pipeline for [environment]"
+@deployment-ops "Validate infrastructure as code for [service]"
+@deployment-ops "Generate rollback strategy for [deployment]"
+```
+
+## Integration Points
+
+This agent integrates with:
+- Workflow documentation
+- API design (for deployment endpoints)
+- Monitoring and alerting
+- Security validation
+
+## Validation
+
+- Pipeline reliability checks
+- Infrastructure consistency validation
+- Deployment strategy verification

package/templates/base/agents/integration-hub.md

@@ -0,0 +1,76 @@
+---
+name: integration-hub
+version: "1.0.0"
+displayName: "Integration Hub"
+description: "External service integration, third-party API management, and webhook handling specialist"
+category: "integration"
+complexity: "medium-high"
+context_budget: "~40K tokens"
+capabilities:
+  - "third-party-api-integration"
+  - "webhook-handling"
+  - "authentication-management"
+  - "rate-limiting-implementation"
+  - "error-handling-patterns"
+workflows:
+  - "external-services"
+  - "webhooks"
+  - "integrations"
+commands: ["/rpi-research", "/rpi-plan", "/rpi-implement"]
+dependencies:
+  agents: []
+  commands: []
+hooks:
+  pre_invoke: null
+  post_invoke: "verify-docs-current"
+examples:
+  - invocation: '@integration-hub "Document integration with [service]"'
+    description: "Create integration documentation"
+  - invocation: '@integration-hub "Analyze webhook endpoints"'
+    description: "Review webhook security and reliability"
+  - invocation: '@integration-hub "Review authentication flows"'
+    description: "Audit third-party auth mechanisms"
+---
+
+# Integration Hub Agent
+
+**Purpose:** External service integration, third-party API management, and webhook handling
+
+## Capabilities
+
+This agent specializes in:
+- **Third-party API integration** - Connecting with external services and APIs
+- **Webhook handling** - Managing incoming and outgoing webhooks
+- **Authentication management** - Handling API keys, OAuth, and other auth mechanisms
+- **Rate limiting and retries** - Implementing robust integration patterns
+- **Error handling** - Managing integration failures and retries
+
+## Usage
+
+After template initialization, this agent will be generated based on your integration requirements. It will:
+1. Analyze your existing external integrations
+2. Create comprehensive integration documentation
+3. Identify potential security vulnerabilities
+4. Provide recommendations for integration optimization
+
+## Example Commands
+
+```bash
+@integration-hub "Document integration with [service]"
+@integration-hub "Validate webhook endpoints for [integration]"
+@integration-hub "Generate authentication strategy for [service]"
+```
+
+## Integration Points
+
+This agent integrates with:
+- Workflow documentation
+- API design (for integration endpoints)
+- Testing strategies
+- Monitoring and alerting
+
+## Validation
+
+- Integration security checks
+- Authentication mechanism validation
+- Rate limiting configuration

package/templates/base/analytics/README.md

@@ -0,0 +1,114 @@
+# Analytics Data
+
+Local storage for usage analytics and metrics.
+
+## Overview
+
+This directory stores local analytics data collected during Claude Code sessions. All data is stored locally and never sent externally unless explicitly configured.
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `sessions.json` | Session history and metadata |
+| `commands.json` | Command usage statistics |
+| `agents.json` | Agent invocation tracking |
+| `context.json` | Context budget metrics over time |
+| `exports/` | Exported analytics files |
+
+## Data Schema
+
+### sessions.json
+
+```json
+{
+  "sessions": [
+    {
+      "id": "uuid",
+      "started": "ISO-timestamp",
+      "ended": "ISO-timestamp",
+      "duration_minutes": 45,
+      "files_modified": 12,
+      "commits": 3,
+      "member_id": "dev-1"
+    }
+  ]
+}
+```
+
+### commands.json
+
+```json
+{
+  "commands": {
+    "/rpi-research": {
+      "count": 23,
+      "last_used": "ISO-timestamp",
+      "success_rate": 0.95,
+      "history": [
+        {
+          "timestamp": "ISO-timestamp",
+          "duration_seconds": 120,
+          "success": true
+        }
+      ]
+    }
+  }
+}
+```
+
+### agents.json
+
+```json
+{
+  "agents": {
+    "@core-architect": {
+      "invocations": 18,
+      "last_used": "ISO-timestamp",
+      "avg_context_tokens": 35000,
+      "tasks_completed": 15
+    }
+  }
+}
+```
+
+### context.json
+
+```json
+{
+  "snapshots": [
+    {
+      "timestamp": "ISO-timestamp",
+      "total_tokens": 45000,
+      "breakdown": {
+        "indexes": 12400,
+        "workflows": 18200,
+        "agents": 8600,
+        "commands": 5800
+      },
+      "budget_percentage": 22.5
+    }
+  ]
+}
+```
+
+## Retention
+
+Data is retained according to `telemetry.retention_days` in settings (default: 90 days). Older data is automatically pruned.
+
+## Clearing Data
+
+To clear all analytics data:
+
+```
+/analytics clear
+```
+
+Or manually delete files in this directory (except README.md).
+
+## Privacy
+
+- All data stored locally
+- No external transmission
+- User has full control
+- Can be disabled in settings

package/templates/base/automation/config.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "../schemas/automation.schema.json",
+  "version": "1.0.0",
+  "generators": {
+    "code_mapper": {
+      "enabled": true,
+      "output_path": "context/CODE_TO_WORKFLOW_MAP.md",
+      "scan_patterns": [
+        "context/workflows/*.md",
+        "agents/*.md",
+        "commands/*.md"
+      ],
+      "reference_patterns": [
+        "\\[Line (\\d+)\\]",
+        "\\[Lines (\\d+)-(\\d+)\\]",
+        ":(\\d+)",
+        "::(\\w+)\\(\\)"
+      ],
+      "ignore_paths": [
+        "node_modules",
+        ".git",
+        "dist",
+        "build"
+      ]
+    },
+    "index_builder": {
+      "enabled": true,
+      "rebuild_on_change": true,
+      "indexes": [
+        "indexes/workflows/CATEGORY_INDEX.md",
+        "indexes/code/CATEGORY_INDEX.md",
+        "indexes/agents/CATEGORY_INDEX.md"
+      ]
+    },
+    "gotcha_extractor": {
+      "enabled": false,
+      "scan_git_history": true,
+      "keywords": ["fix", "bug", "revert", "hotfix", "GOTCHA", "WARN"],
+      "output_path": "context/KNOWN_GOTCHAS.md"
+    }
+  },
+  "hooks": {
+    "pre_commit": {
+      "enabled": true,
+      "check_drift": true,
+      "block_on_stale": false
+    },
+    "post_commit": {
+      "enabled": true,
+      "rebuild_code_map": true,
+      "update_hashes": true
+    }
+  },
+  "schedule": {
+    "full_rebuild": "weekly",
+    "drift_check": "on_file_change"
+  }
+}

package/templates/base/automation/generators/code-mapper.js

@@ -0,0 +1,308 @@
+/**
+ * Code Mapper - Auto-generates CODE_TO_WORKFLOW_MAP.md
+ *
+ * Scans workflow files for file:line references and builds
+ * a reverse index mapping code files to their documentation.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const glob = require('glob');
+
+const CLAUDE_DIR = path.join(__dirname, '..', '..');
+const CONFIG_PATH = path.join(__dirname, '..', 'config.json');
+
+/**
+ * Load automation config
+ */
+function loadConfig() {
+  try {
+    const content = fs.readFileSync(CONFIG_PATH, 'utf-8');
+    return JSON.parse(content);
+  } catch (error) {
+    console.error('Failed to load config:', error.message);
+    return null;
+  }
+}
+
+/**
+ * Extract file references from markdown content
+ */
+function extractReferences(content, filePath) {
+  const references = [];
+  const patterns = [
+    // file.ext:123 format
+    /([a-zA-Z0-9_\-./]+\.[a-zA-Z]+):(\d+)/g,
+    // [Line 123] format with preceding file path
+    /`([^`]+)`[^[]*\[Line (\d+)\]/g,
+    // [Lines 123-456] format
+    /`([^`]+)`[^[]*\[Lines (\d+)-(\d+)\]/g,
+    // file.ext::function() semantic anchor format
+    /([a-zA-Z0-9_\-./]+\.[a-zA-Z]+)::(\w+)\(\)/g
+  ];
+
+  // Simple line number extraction
+  const linePattern = /([a-zA-Z0-9_\-./]+\.[a-zA-Z0-9]+):(\d+)/g;
+  let match;
+  while ((match = linePattern.exec(content)) !== null) {
+    references.push({
+      file: match[1],
+      line: parseInt(match[2]),
+      type: 'line',
+      source: filePath
+    });
+  }
+
+  // Semantic anchor extraction
+  const anchorPattern = /([a-zA-Z0-9_\-./]+\.[a-zA-Z0-9]+)::(\w+)\(\)/g;
+  while ((match = anchorPattern.exec(content)) !== null) {
+    references.push({
+      file: match[1],
+      anchor: match[2],
+      type: 'anchor',
+      source: filePath
+    });
+  }
+
+  return references;
+}
+
+/**
+ * Scan workflow files and extract all references
+ */
+function scanWorkflows() {
+  const config = loadConfig();
+  if (!config) return {};
+
+  const allReferences = {};
+  const scanPatterns = config.generators.code_mapper.scan_patterns || [
+    'context/workflows/*.md',
+    'agents/*.md'
+  ];
+
+  for (const pattern of scanPatterns) {
+    const fullPattern = path.join(CLAUDE_DIR, pattern);
+    const files = glob.sync(fullPattern);
+
+    for (const file of files) {
+      try {
+        const content = fs.readFileSync(file, 'utf-8');
+        const relativePath = path.relative(CLAUDE_DIR, file);
+        const refs = extractReferences(content, relativePath);
+
+        for (const ref of refs) {
+          const normalizedPath = ref.file.replace(/\\/g, '/');
+          if (!allReferences[normalizedPath]) {
+            allReferences[normalizedPath] = {
+              documentedIn: [],
+              references: []
+            };
+          }
+
+          // Add source document
+          if (!allReferences[normalizedPath].documentedIn.includes(relativePath)) {
+            allReferences[normalizedPath].documentedIn.push(relativePath);
+          }
+
+          // Add reference details
+          allReferences[normalizedPath].references.push({
+            source: relativePath,
+            line: ref.line,
+            anchor: ref.anchor,
+            type: ref.type
+          });
+        }
+      } catch (error) {
+        console.error(`Error scanning ${file}:`, error.message);
+      }
+    }
+  }
+
+  return allReferences;
+}
+
+/**
+ * Generate CODE_TO_WORKFLOW_MAP.md content
+ */
+function generateMapContent(references) {
+  const now = new Date().toISOString();
+  let content = `# Code to Workflow Map
+
+> **Auto-generated:** ${now}
+> **Generator:** code-mapper.js
+>
+> This file maps source code files to the workflow documentation that references them.
+> Use this to find which docs need updating after code changes.
+
+---
+
+## How to Use
+
+1. **Modified a file?** Search for it below
+2. **Find "Documented In"** section for affected workflows
+3. **Check references** to see what needs updating
+4. **Run \`/verify-docs-current [file]\`** to validate
+
+---
+
+## File Mappings
+
+`;
+
+  // Sort files alphabetically
+  const sortedFiles = Object.keys(references).sort();
+
+  // Group by directory
+  const byDirectory = {};
+  for (const file of sortedFiles) {
+    const dir = path.dirname(file) || '.';
+    if (!byDirectory[dir]) {
+      byDirectory[dir] = [];
+    }
+    byDirectory[dir].push(file);
+  }
+
+  for (const dir of Object.keys(byDirectory).sort()) {
+    content += `### ${dir}/\n\n`;
+
+    for (const file of byDirectory[dir]) {
+      const data = references[file];
+      const fileName = path.basename(file);
+      const refCount = data.references.length;
+
+      content += `#### \`${fileName}\`\n\n`;
+      content += `**Documented In:**\n`;
+      for (const doc of data.documentedIn) {
+        content += `- [${doc}](./${doc})\n`;
+      }
+
+      content += `\n**References:** ${refCount}\n`;
+
+      // Group references by type
+      const lineRefs = data.references.filter(r => r.type === 'line');
+      const anchorRefs = data.references.filter(r => r.type === 'anchor');
+
+      if (lineRefs.length > 0) {
+        content += `\n*Line References:*\n`;
+        for (const ref of lineRefs.slice(0, 5)) {
+          content += `- Line ${ref.line} in ${ref.source}\n`;
+        }
+        if (lineRefs.length > 5) {
+          content += `- ... and ${lineRefs.length - 5} more\n`;
+        }
+      }
+
+      if (anchorRefs.length > 0) {
+        content += `\n*Semantic Anchors:*\n`;
+        for (const ref of anchorRefs) {
+          content += `- \`${ref.anchor}()\` in ${ref.source}\n`;
+        }
+      }
+
+      content += `\n**Update After Changing:**\n`;
+      for (const doc of data.documentedIn) {
+        content += `- [ ] ${doc}\n`;
+      }
+
+      content += '\n---\n\n';
+    }
+  }
+
+  // Summary section
+  content += `## Summary
+
+| Metric | Value |
+|--------|-------|
+| Files Documented | ${sortedFiles.length} |
+| Total References | ${Object.values(references).reduce((sum, r) => sum + r.references.length, 0)} |
+| Workflow Files | ${new Set(Object.values(references).flatMap(r => r.documentedIn)).size} |
+| Generated | ${now} |
+
+---
+
+## Files NOT Currently Documented
+
+*Run \`npx claude-context generate --scan-orphans\` to find undocumented code files.*
+
+---
+
+*This file is auto-generated. Do not edit manually.*
+*Regenerate with: \`npx claude-context generate --code-map\`*
+`;
+
+  return content;
+}
+
+/**
+ * Generate and write CODE_TO_WORKFLOW_MAP.md
+ */
+function generate(options = {}) {
+  const { dryRun = false, verbose = false } = options;
+
+  console.log('Scanning workflow files...');
+  const references = scanWorkflows();
+
+  const fileCount = Object.keys(references).length;
+  const refCount = Object.values(references).reduce(
+    (sum, r) => sum + r.references.length, 0
+  );
+
+  console.log(`Found ${fileCount} files with ${refCount} references`);
+
+  if (verbose) {
+    for (const [file, data] of Object.entries(references)) {
+      console.log(`  ${file}: ${data.references.length} refs in ${data.documentedIn.length} docs`);
+    }
+  }
+
+  const content = generateMapContent(references);
+
+  if (dryRun) {
+    console.log('\n--- DRY RUN OUTPUT ---\n');
+    console.log(content.substring(0, 2000) + '\n...(truncated)');
+    return { success: true, fileCount, refCount };
+  }
+
+  const outputPath = path.join(CLAUDE_DIR, 'context', 'CODE_TO_WORKFLOW_MAP.md');
+  try {
+    fs.writeFileSync(outputPath, content);
+    console.log(`Generated: ${outputPath}`);
+
+    // Update metadata
+    const metaPath = path.join(CLAUDE_DIR, 'context', '.meta', 'generated-at.json');
+    const metaDir = path.dirname(metaPath);
+    if (!fs.existsSync(metaDir)) {
+      fs.mkdirSync(metaDir, { recursive: true });
+    }
+    const metadata = {
+      'CODE_TO_WORKFLOW_MAP.md': {
+        generatedAt: new Date().toISOString(),
+        filesScanned: fileCount,
+        referencesFound: refCount
+      }
+    };
+    fs.writeFileSync(metaPath, JSON.stringify(metadata, null, 2));
+
+    return { success: true, fileCount, refCount, outputPath };
+  } catch (error) {
+    console.error('Failed to write output:', error.message);
+    return { success: false, error: error.message };
+  }
+}
+
+// CLI execution
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const dryRun = args.includes('--dry-run');
+  const verbose = args.includes('--verbose') || args.includes('-v');
+
+  const result = generate({ dryRun, verbose });
+  process.exit(result.success ? 0 : 1);
+}
+
+module.exports = {
+  generate,
+  scanWorkflows,
+  extractReferences,
+  generateMapContent
+};