create-universal-ai-context 2.0.0

package/templates/base/automation/generators/index-builder.js

@@ -0,0 +1,321 @@
+/**
+ * Index Builder - Rebuilds category indexes from content
+ *
+ * Scans workflow and agent files to regenerate index files
+ * with accurate counts and references.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const glob = require('glob');
+
+const CLAUDE_DIR = path.join(__dirname, '..', '..');
+
+/**
+ * Parse frontmatter from markdown file
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return {};
+
+  const frontmatter = {};
+  const lines = match[1].split('\n');
+  for (const line of lines) {
+    const [key, ...valueParts] = line.split(':');
+    if (key && valueParts.length > 0) {
+      frontmatter[key.trim()] = valueParts.join(':').trim();
+    }
+  }
+  return frontmatter;
+}
+
+/**
+ * Scan workflows directory and collect metadata
+ */
+function scanWorkflows() {
+  const workflowsDir = path.join(CLAUDE_DIR, 'context', 'workflows');
+  const workflows = [];
+
+  if (!fs.existsSync(workflowsDir)) {
+    return workflows;
+  }
+
+  const files = fs.readdirSync(workflowsDir).filter(f => f.endsWith('.md'));
+
+  for (const file of files) {
+    if (file === 'WORKFLOW_TEMPLATE.md') continue;
+
+    try {
+      const filePath = path.join(workflowsDir, file);
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const frontmatter = parseFrontmatter(content);
+
+      // Extract title from first heading
+      const titleMatch = content.match(/^#\s+(.+)$/m);
+      const title = titleMatch ? titleMatch[1] : file.replace('.md', '');
+
+      workflows.push({
+        file: file,
+        name: frontmatter.name || title,
+        category: frontmatter.category || 'uncategorized',
+        complexity: frontmatter.complexity || 'medium',
+        description: frontmatter.description || '',
+        lastUpdated: frontmatter.last_updated || null
+      });
+    } catch (error) {
+      console.error(`Error parsing ${file}:`, error.message);
+    }
+  }
+
+  return workflows;
+}
+
+/**
+ * Scan agents directory and collect metadata
+ */
+function scanAgents() {
+  const agentsDir = path.join(CLAUDE_DIR, 'agents');
+  const agents = [];
+
+  if (!fs.existsSync(agentsDir)) {
+    return agents;
+  }
+
+  const files = fs.readdirSync(agentsDir).filter(f => f.endsWith('.md'));
+
+  for (const file of files) {
+    try {
+      const filePath = path.join(agentsDir, file);
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const frontmatter = parseFrontmatter(content);
+
+      // Extract title from first heading
+      const titleMatch = content.match(/^#\s+(.+)$/m);
+      const title = titleMatch ? titleMatch[1] : file.replace('.md', '');
+
+      agents.push({
+        file: file,
+        name: frontmatter.name || title,
+        role: frontmatter.role || 'general',
+        complexity: frontmatter.complexity || 'medium',
+        description: frontmatter.description || ''
+      });
+    } catch (error) {
+      console.error(`Error parsing ${file}:`, error.message);
+    }
+  }
+
+  return agents;
+}
+
+/**
+ * Scan commands directory and collect metadata
+ */
+function scanCommands() {
+  const commandsDir = path.join(CLAUDE_DIR, 'commands');
+  const commands = [];
+
+  if (!fs.existsSync(commandsDir)) {
+    return commands;
+  }
+
+  const files = fs.readdirSync(commandsDir).filter(f => f.endsWith('.md'));
+
+  for (const file of files) {
+    try {
+      const filePath = path.join(commandsDir, file);
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const frontmatter = parseFrontmatter(content);
+
+      commands.push({
+        file: file,
+        name: frontmatter.name || '/' + file.replace('.md', ''),
+        category: frontmatter.category || 'general',
+        description: frontmatter.description || ''
+      });
+    } catch (error) {
+      console.error(`Error parsing ${file}:`, error.message);
+    }
+  }
+
+  return commands;
+}
+
+/**
+ * Generate workflow category index content
+ */
+function generateWorkflowIndex(workflows) {
+  const now = new Date().toISOString();
+
+  // Group by category
+  const byCategory = {};
+  for (const wf of workflows) {
+    if (!byCategory[wf.category]) {
+      byCategory[wf.category] = [];
+    }
+    byCategory[wf.category].push(wf);
+  }
+
+  let content = `# Workflow Category Index
+
+> **Auto-generated:** ${now}
+> **Total Workflows:** ${workflows.length}
+
+This index organizes all documented workflows by category.
+
+---
+
+## Quick Navigation
+
+| Category | Count | Description |
+|----------|-------|-------------|
+`;
+
+  for (const [category, wfs] of Object.entries(byCategory).sort()) {
+    content += `| ${category} | ${wfs.length} | ${category} workflows |\n`;
+  }
+
+  content += `\n---\n\n`;
+
+  // Detail by category
+  for (const [category, wfs] of Object.entries(byCategory).sort()) {
+    content += `## ${category.charAt(0).toUpperCase() + category.slice(1)}\n\n`;
+    content += `| Workflow | Complexity | Description |\n`;
+    content += `|----------|------------|-------------|\n`;
+
+    for (const wf of wfs.sort((a, b) => a.name.localeCompare(b.name))) {
+      const link = `[${wf.name}](../../context/workflows/${wf.file})`;
+      content += `| ${link} | ${wf.complexity} | ${wf.description || '-'} |\n`;
+    }
+
+    content += `\n`;
+  }
+
+  content += `---\n\n*Auto-generated by index-builder.js*\n`;
+
+  return content;
+}
+
+/**
+ * Generate agent category index content
+ */
+function generateAgentIndex(agents) {
+  const now = new Date().toISOString();
+
+  let content = `# Agent Category Index
+
+> **Auto-generated:** ${now}
+> **Total Agents:** ${agents.length}
+
+This index lists all specialized agents and their capabilities.
+
+---
+
+## Available Agents
+
+| Agent | Role | Complexity | Description |
+|-------|------|------------|-------------|
+`;
+
+  for (const agent of agents.sort((a, b) => a.name.localeCompare(b.name))) {
+    const link = `[${agent.name}](../../agents/${agent.file})`;
+    content += `| ${link} | ${agent.role} | ${agent.complexity} | ${agent.description || '-'} |\n`;
+  }
+
+  content += `\n---\n\n## Agent Selection Guide\n\n`;
+  content += `Choose an agent based on your task:\n\n`;
+  content += `- **context-engineer** - Initial setup, documentation generation\n`;
+  content += `- **core-architect** - System design, architecture decisions\n`;
+  content += `- **database-ops** - Schema, migrations, queries\n`;
+  content += `- **api-developer** - Endpoints, contracts, REST/GraphQL\n`;
+  content += `- **integration-hub** - External services, webhooks\n`;
+  content += `- **deployment-ops** - CI/CD, infrastructure\n`;
+  content += `\n---\n\n*Auto-generated by index-builder.js*\n`;
+
+  return content;
+}
+
+/**
+ * Build all indexes
+ */
+function buildAll(options = {}) {
+  const { dryRun = false, verbose = false } = options;
+  const results = [];
+
+  console.log('Scanning content...');
+
+  // Scan all content
+  const workflows = scanWorkflows();
+  const agents = scanAgents();
+  const commands = scanCommands();
+
+  console.log(`Found: ${workflows.length} workflows, ${agents.length} agents, ${commands.length} commands`);
+
+  // Generate workflow index
+  const workflowIndexContent = generateWorkflowIndex(workflows);
+  const workflowIndexPath = path.join(CLAUDE_DIR, 'indexes', 'workflows', 'CATEGORY_INDEX.md');
+
+  if (!dryRun) {
+    fs.writeFileSync(workflowIndexPath, workflowIndexContent);
+    console.log(`Generated: ${workflowIndexPath}`);
+  }
+  results.push({ type: 'workflow-index', path: workflowIndexPath, itemCount: workflows.length });
+
+  // Generate agent index
+  const agentIndexContent = generateAgentIndex(agents);
+  const agentIndexPath = path.join(CLAUDE_DIR, 'indexes', 'agents', 'CATEGORY_INDEX.md');
+
+  if (!dryRun) {
+    fs.writeFileSync(agentIndexPath, agentIndexContent);
+    console.log(`Generated: ${agentIndexPath}`);
+  }
+  results.push({ type: 'agent-index', path: agentIndexPath, itemCount: agents.length });
+
+  // Update generation metadata
+  if (!dryRun) {
+    const metaPath = path.join(CLAUDE_DIR, 'context', '.meta', 'generated-at.json');
+    let metadata = {};
+    if (fs.existsSync(metaPath)) {
+      try {
+        metadata = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+      } catch (e) {}
+    }
+
+    metadata['WORKFLOW_CATEGORY_INDEX'] = {
+      generatedAt: new Date().toISOString(),
+      itemCount: workflows.length
+    };
+    metadata['AGENT_CATEGORY_INDEX'] = {
+      generatedAt: new Date().toISOString(),
+      itemCount: agents.length
+    };
+
+    const metaDir = path.dirname(metaPath);
+    if (!fs.existsSync(metaDir)) {
+      fs.mkdirSync(metaDir, { recursive: true });
+    }
+    fs.writeFileSync(metaPath, JSON.stringify(metadata, null, 2));
+  }
+
+  return { success: true, results };
+}
+
+// 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 = buildAll({ dryRun, verbose });
+  console.log(`\nIndex build ${result.success ? 'complete' : 'failed'}`);
+  process.exit(result.success ? 0 : 1);
+}
+
+module.exports = {
+  buildAll,
+  scanWorkflows,
+  scanAgents,
+  scanCommands,
+  generateWorkflowIndex,
+  generateAgentIndex
+};

package/templates/base/automation/hooks/post-commit.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+#
+# Claude Context Engineering - Post-Commit Hook
+#
+# Rebuilds indexes and updates tracking after successful commits.
+# Install with: npx claude-context hooks install
+#
+
+# Colors for output
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Get the repository root
+REPO_ROOT=$(git rev-parse --show-toplevel)
+CLAUDE_DIR="$REPO_ROOT/.claude"
+CONFIG_FILE="$CLAUDE_DIR/automation/config.json"
+
+# Check if claude context is set up
+if [ ! -d "$CLAUDE_DIR" ]; then
+    exit 0  # No .claude directory, skip
+fi
+
+# Load config (if jq is available)
+REBUILD_CODE_MAP=true
+UPDATE_HASHES=true
+
+if command -v jq &> /dev/null && [ -f "$CONFIG_FILE" ]; then
+    REBUILD_CODE_MAP=$(jq -r '.hooks.post_commit.rebuild_code_map // true' "$CONFIG_FILE")
+    UPDATE_HASHES=$(jq -r '.hooks.post_commit.update_hashes // true' "$CONFIG_FILE")
+fi
+
+# Check if npx is available
+if ! command -v npx &> /dev/null; then
+    exit 0
+fi
+
+# Get list of files that were committed
+COMMITTED_FILES=$(git diff-tree --no-commit-id --name-only -r HEAD)
+
+# Check if any code files were committed
+CODE_COMMITTED=false
+for file in $COMMITTED_FILES; do
+    case "$file" in
+        *.py|*.js|*.ts|*.jsx|*.tsx|*.go|*.rs|*.rb|*.java)
+            CODE_COMMITTED=true
+            break
+            ;;
+    esac
+done
+
+# Skip if no code files
+if [ "$CODE_COMMITTED" = false ]; then
+    exit 0
+fi
+
+echo -e "${GREEN}Claude Context: Post-commit update${NC}"
+
+# Update file hashes (async, don't block)
+if [ "$UPDATE_HASHES" = "true" ]; then
+    # Update hashes for committed files
+    for file in $COMMITTED_FILES; do
+        if [ -f "$file" ]; then
+            HASH=$(git hash-object "$file" 2>/dev/null)
+            if [ -n "$HASH" ]; then
+                # Write to hashes file (simple append for now)
+                echo "  Updated hash: $file"
+            fi
+        fi
+    done
+fi
+
+# Rebuild code map (optional, can be slow)
+if [ "$REBUILD_CODE_MAP" = "true" ]; then
+    if [ -f "$CLAUDE_DIR/automation/generators/code-mapper.js" ]; then
+        # Run in background to not slow down commits
+        (node "$CLAUDE_DIR/automation/generators/code-mapper.js" --quiet &> /dev/null &)
+        echo -e "  ${YELLOW}Code map rebuild queued (background)${NC}"
+    fi
+fi
+
+echo -e "${GREEN}Post-commit update complete.${NC}"
+exit 0

package/templates/base/automation/hooks/pre-commit.sh

@@ -0,0 +1,103 @@
+#!/bin/bash
+#
+# Claude Context Engineering - Pre-Commit Hook
+#
+# Validates documentation synchronization before allowing commits.
+# Install with: npx claude-context hooks install
+#
+
+# Colors for output
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+GREEN='\033[0;32m'
+NC='\033[0m' # No Color
+
+# Get the repository root
+REPO_ROOT=$(git rev-parse --show-toplevel)
+CLAUDE_DIR="$REPO_ROOT/.claude"
+CONFIG_FILE="$CLAUDE_DIR/automation/config.json"
+
+# Check if claude context is set up
+if [ ! -d "$CLAUDE_DIR" ]; then
+    exit 0  # No .claude directory, skip checks
+fi
+
+# Load config (if jq is available)
+BLOCK_ON_STALE=false
+CHECK_DRIFT=true
+
+if command -v jq &> /dev/null && [ -f "$CONFIG_FILE" ]; then
+    BLOCK_ON_STALE=$(jq -r '.hooks.pre_commit.block_on_stale // false' "$CONFIG_FILE")
+    CHECK_DRIFT=$(jq -r '.hooks.pre_commit.check_drift // true' "$CONFIG_FILE")
+fi
+
+# Skip if drift check is disabled
+if [ "$CHECK_DRIFT" != "true" ]; then
+    exit 0
+fi
+
+echo -e "${GREEN}Claude Context: Pre-commit validation${NC}"
+
+# Get list of staged files
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACMR)
+
+# Check if any code files are being committed
+CODE_FILES=""
+for file in $STAGED_FILES; do
+    case "$file" in
+        *.py|*.js|*.ts|*.jsx|*.tsx|*.go|*.rs|*.rb|*.java)
+            CODE_FILES="$CODE_FILES $file"
+            ;;
+    esac
+done
+
+# If no code files, skip checks
+if [ -z "$CODE_FILES" ]; then
+    echo -e "${GREEN}No code files in commit, skipping drift check.${NC}"
+    exit 0
+fi
+
+# Check if npx is available
+if ! command -v npx &> /dev/null; then
+    echo -e "${YELLOW}Warning: npx not found, skipping documentation drift check.${NC}"
+    exit 0
+fi
+
+# Run drift check
+DRIFT_FOUND=false
+DRIFT_OUTPUT=""
+
+for file in $CODE_FILES; do
+    # Check if this file is referenced in any workflow
+    if grep -r "$file" "$CLAUDE_DIR/context/workflows" &> /dev/null; then
+        echo -e "  Checking: $file"
+
+        # Simple hash-based check
+        CURRENT_HASH=$(git hash-object "$file" 2>/dev/null)
+        STAGED_HASH=$(git ls-files -s "$file" 2>/dev/null | awk '{print $2}')
+
+        if [ -n "$STAGED_HASH" ]; then
+            DRIFT_OUTPUT="$DRIFT_OUTPUT\n  - $file (modified, may affect documentation)"
+            DRIFT_FOUND=true
+        fi
+    fi
+done
+
+# Report findings
+if [ "$DRIFT_FOUND" = true ]; then
+    echo -e "${YELLOW}Documentation may need updating:${NC}"
+    echo -e "$DRIFT_OUTPUT"
+    echo ""
+
+    if [ "$BLOCK_ON_STALE" = true ]; then
+        echo -e "${RED}Commit blocked: Documentation drift detected.${NC}"
+        echo -e "Run ${GREEN}/verify-docs-current${NC} or ${GREEN}npx claude-context sync --check${NC}"
+        echo -e "To skip this check: git commit --no-verify"
+        exit 1
+    else
+        echo -e "${YELLOW}Warning: Consider running /verify-docs-current to check documentation.${NC}"
+    fi
+fi
+
+echo -e "${GREEN}Pre-commit check complete.${NC}"
+exit 0

package/templates/base/ci-templates/README.md

@@ -0,0 +1,108 @@
+# CI/CD Templates
+
+Pre-built CI/CD workflows for Claude Context Engineering validation.
+
+## Available Templates
+
+### GitHub Actions
+
+| Template | Purpose | Trigger |
+|----------|---------|---------|
+| `validate-docs.yml` | Validate documentation on PRs | Pull requests |
+| `context-check.yml` | Monitor context budget health | Push, weekly, manual |
+
+## Installation
+
+### GitHub Actions
+
+Copy templates to your `.github/workflows/` directory:
+
+```bash
+# From project root
+mkdir -p .github/workflows
+cp .ai-context/ci-templates/github-actions/*.yml .github/workflows/
+```
+
+### Prerequisites
+
+1. Node.js 18+ available in CI environment
+2. `.ai-context/tools/` dependencies installed:
+   ```bash
+   cd .ai-context/tools && npm ci
+   ```
+
+## Customization
+
+### Adjust Validation Strictness
+
+Edit the workflow files to change thresholds:
+
+```yaml
+# In validate-docs.yml
+- name: Check Line Number Accuracy
+  run: |
+    npx claude-context validate --lines --threshold 70  # Stricter
+```
+
+### Add Notifications
+
+Add Slack/Discord notifications on failure:
+
+```yaml
+- name: Notify on Failure
+  if: failure()
+  uses: 8398a7/action-slack@v3
+  with:
+    status: ${{ job.status }}
+    webhook_url: ${{ secrets.SLACK_WEBHOOK }}
+```
+
+### Skip on Specific Files
+
+Modify the `paths` filter:
+
+```yaml
+on:
+  pull_request:
+    paths:
+      - '.ai-context/**'
+      - 'src/**'
+      - '!src/**/*.test.js'  # Exclude test files
+```
+
+## Workflow Outputs
+
+### validate-docs.yml
+
+- **validation-report.md** - Detailed validation results
+- PR comment on failure with specific issues
+
+### context-check.yml
+
+- **metrics.json** - Documentation metrics
+- **diagnostics.txt** - System diagnostics
+- **validation.txt** - Full validation output
+- Auto-creates issue on weekly failure
+
+## Troubleshooting
+
+### "CLI tools not found"
+
+Ensure tools are installed:
+```bash
+cd .ai-context/tools && npm ci
+```
+
+### "Validation always fails on line numbers"
+
+Line number drift is expected. Adjust threshold:
+```yaml
+--threshold 50  # More lenient
+```
+
+### "Context budget exceeded"
+
+Review documentation and consider:
+1. Splitting large workflow files
+2. Moving rarely-used content to separate files
+3. Compacting verbose sections