create-universal-ai-context 2.0.0

package/templates/base/ci-templates/github-actions/context-check.yml

@@ -0,0 +1,144 @@
+# Claude Context Engineering - Context Budget Check
+#
+# This workflow monitors context budget and documentation health.
+# Copy this file to .github/workflows/context-check.yml to enable.
+#
+# Runs on:
+# - Push to main/master branches
+# - Weekly schedule
+# - Manual trigger
+
+name: Context Budget Check
+
+on:
+  push:
+    branches:
+      - main
+      - master
+    paths:
+      - '.ai-context/**'
+  schedule:
+    # Run weekly on Monday at 9am UTC
+    - cron: '0 9 * * 1'
+  workflow_dispatch:
+
+jobs:
+  context-health:
+    name: Check Context Engineering Health
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          cache: 'npm'
+          cache-dependency-path: '.ai-context/tools/package-lock.json'
+
+      - name: Install CLI tools
+        run: |
+          cd .ai-context/tools
+          npm ci
+
+      - name: Run Full Diagnostics
+        id: diagnose
+        run: |
+          echo "🔬 Running diagnostics..."
+          npx .ai-context/tools/bin/claude-context.js diagnose --verbose > diagnostics.txt 2>&1
+          cat diagnostics.txt
+        continue-on-error: true
+
+      - name: Calculate Documentation Metrics
+        run: |
+          echo "📊 Calculating metrics..."
+
+          # Count workflow files
+          WORKFLOW_COUNT=$(find .ai-context/context/workflows -name "*.md" 2>/dev/null | wc -l || echo "0")
+          echo "Workflow files: $WORKFLOW_COUNT"
+
+          # Count agent files
+          AGENT_COUNT=$(find .ai-context/agents -name "*.md" 2>/dev/null | wc -l || echo "0")
+          echo "Agent files: $AGENT_COUNT"
+
+          # Count command files
+          COMMAND_COUNT=$(find .ai-context/commands -name "*.md" 2>/dev/null | wc -l || echo "0")
+          echo "Command files: $COMMAND_COUNT"
+
+          # Estimate total documentation tokens (rough: 1 token ≈ 4 chars)
+          TOTAL_CHARS=$(find .claude -name "*.md" -exec cat {} \; 2>/dev/null | wc -c || echo "0")
+          ESTIMATED_TOKENS=$((TOTAL_CHARS / 4))
+          echo "Estimated documentation tokens: $ESTIMATED_TOKENS"
+
+          # Calculate as percentage of budget
+          MAX_TOKENS=200000
+          PERCENTAGE=$((ESTIMATED_TOKENS * 100 / MAX_TOKENS))
+          echo "Context budget usage: ${PERCENTAGE}%"
+
+          # Save metrics
+          cat > metrics.json << EOF
+          {
+            "workflow_count": $WORKFLOW_COUNT,
+            "agent_count": $AGENT_COUNT,
+            "command_count": $COMMAND_COUNT,
+            "estimated_tokens": $ESTIMATED_TOKENS,
+            "budget_percentage": $PERCENTAGE,
+            "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+          }
+          EOF
+
+          cat metrics.json
+
+      - name: Check Budget Threshold
+        run: |
+          PERCENTAGE=$(jq '.budget_percentage' metrics.json)
+          echo "Current usage: ${PERCENTAGE}%"
+
+          if [ "$PERCENTAGE" -gt 60 ]; then
+            echo "⚠️ WARNING: Documentation exceeds 60% of context budget!"
+            echo "Consider compacting or splitting documentation."
+            exit 1
+          elif [ "$PERCENTAGE" -gt 40 ]; then
+            echo "📊 Documentation is at ${PERCENTAGE}% - approaching target limit"
+          else
+            echo "✅ Documentation is within healthy range (${PERCENTAGE}%)"
+          fi
+
+      - name: Run Validation Suite
+        run: |
+          echo "🔍 Running validation..."
+          npx .ai-context/tools/bin/claude-context.js validate --all > validation.txt 2>&1 || true
+          cat validation.txt
+
+      - name: Upload Metrics
+        uses: actions/upload-artifact@v4
+        with:
+          name: context-metrics
+          path: |
+            metrics.json
+            diagnostics.txt
+            validation.txt
+          retention-days: 30
+
+      - name: Create Issue on Failure
+        if: failure() && github.event_name == 'schedule'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            let metrics = {};
+            try {
+              metrics = JSON.parse(fs.readFileSync('metrics.json', 'utf8'));
+            } catch (e) {
+              metrics = { error: 'Could not read metrics' };
+            }
+
+            github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: '⚠️ Claude Context Engineering Health Check Failed',
+              body: `## Weekly Health Check Failed\n\n**Metrics:**\n\`\`\`json\n${JSON.stringify(metrics, null, 2)}\n\`\`\`\n\n**Action Required:**\n- Review documentation health\n- Run \`npx claude-context diagnose\` locally\n- Consider documentation compaction if over budget\n\n---\n*Generated by Claude Context Engineering CI*`,
+              labels: ['documentation', 'maintenance']
+            });

package/templates/base/ci-templates/github-actions/validate-docs.yml

@@ -0,0 +1,105 @@
+# Claude Context Engineering - Documentation Validation
+#
+# This workflow validates that documentation is accurate and up-to-date.
+# Copy this file to .github/workflows/validate-docs.yml to enable.
+#
+# Runs on:
+# - Pull requests that modify .ai-context/ or source files
+# - Manual trigger
+
+name: Validate Documentation
+
+on:
+  pull_request:
+    paths:
+      - '.ai-context/**'
+      - 'src/**'
+      - 'lib/**'
+      - 'app/**'
+  workflow_dispatch:
+
+jobs:
+  validate:
+    name: Validate Claude Context Documentation
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          cache: 'npm'
+          cache-dependency-path: '.ai-context/tools/package-lock.json'
+
+      - name: Install CLI tools
+        run: |
+          cd .ai-context/tools
+          npm ci
+
+      - name: Validate JSON Schemas
+        run: |
+          echo "🔍 Validating JSON schemas..."
+          npx .ai-context/tools/bin/claude-context.js validate --schema
+        continue-on-error: false
+
+      - name: Validate Markdown Links
+        run: |
+          echo "🔗 Checking markdown links..."
+          npx .ai-context/tools/bin/claude-context.js validate --links
+        continue-on-error: false
+
+      - name: Check for Unresolved Placeholders
+        run: |
+          echo "📝 Checking for placeholders..."
+          npx .ai-context/tools/bin/claude-context.js validate --placeholders
+        continue-on-error: true  # Warning only
+
+      - name: Validate Directory Structure
+        run: |
+          echo "📁 Validating structure..."
+          npx .ai-context/tools/bin/claude-context.js validate --structure
+        continue-on-error: false
+
+      - name: Check Line Number Accuracy
+        run: |
+          echo "📍 Checking line number accuracy..."
+          npx .ai-context/tools/bin/claude-context.js validate --lines --threshold 60
+        continue-on-error: true  # Warning only for line drift
+
+      - name: Generate Validation Report
+        if: always()
+        run: |
+          echo "📊 Generating full validation report..."
+          npx .ai-context/tools/bin/claude-context.js validate --all --output markdown > validation-report.md
+          cat validation-report.md
+
+      - name: Upload Validation Report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: validation-report
+          path: validation-report.md
+          retention-days: 7
+
+      - name: Comment on PR
+        if: github.event_name == 'pull_request' && failure()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            let report = '';
+            try {
+              report = fs.readFileSync('validation-report.md', 'utf8');
+            } catch (e) {
+              report = 'Validation report not available.';
+            }
+
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: `## 🔍 Documentation Validation Failed\n\n${report}\n\n---\n*Generated by Claude Context Engineering CI*`
+            });

package/templates/base/commands/analytics.md

@@ -0,0 +1,238 @@
+---
+name: analytics
+version: "1.0.0"
+displayName: "Usage Analytics"
+description: "View local usage statistics and context metrics"
+category: "system"
+complexity: "low"
+context_budget: "~5K tokens"
+typical_context_usage: "2%"
+prerequisites:
+  - "Analytics enabled in settings (optional)"
+outputs:
+  - "Usage statistics report"
+  - "Context metrics summary"
+  - "Exported metrics file (with --export)"
+related_agents: []
+examples:
+  - command: "/analytics"
+    description: "View local usage statistics"
+  - command: "/analytics context"
+    description: "Show context budget metrics"
+  - command: "/analytics export"
+    description: "Export metrics to JSON file"
+---
+
+# /analytics - Usage Analytics Command
+
+View local usage statistics, context metrics, and export data for analysis.
+
+## Privacy First
+
+**All analytics are local by default.** No data is sent externally unless explicitly configured in `.ai-context/settings.json`:
+
+```json
+{
+  "telemetry": {
+    "enabled": false
+  }
+}
+```
+
+## Subcommands
+
+### `/analytics` (default)
+
+Display summary of local usage statistics.
+
+**Metrics Shown:**
+- Session count (last 7/30 days)
+- Command usage frequency
+- Agent invocation counts
+- Average session duration
+- Files modified per session
+
+### `/analytics context`
+
+Show context budget metrics and trends.
+
+**Metrics Shown:**
+- Current documentation size (tokens)
+- Budget utilization percentage
+- Largest context consumers
+- Token trend over time
+- Recommendations for optimization
+
+### `/analytics commands`
+
+Show command usage breakdown.
+
+**Metrics Shown:**
+- Most used commands
+- Command success/failure rates
+- Average command duration
+- Command usage by day/week
+
+### `/analytics agents`
+
+Show agent utilization breakdown.
+
+**Metrics Shown:**
+- Most invoked agents
+- Agent task completion rates
+- Average context per agent
+- Agent usage patterns
+
+### `/analytics export`
+
+Export metrics to JSON file.
+
+**Output:** `.ai-context/analytics/export-YYYY-MM-DD.json`
+
+### `/analytics clear`
+
+Clear local analytics data.
+
+**Confirmation required** before clearing.
+
+## Usage Examples
+
+### View Summary Statistics
+
+```
+User: /analytics
+
+Claude: ## Usage Analytics (Local)
+
+### Session Summary (Last 30 Days)
+| Metric | Value |
+|--------|-------|
+| Total Sessions | 42 |
+| Avg Duration | 45 min |
+| Files Modified | 312 |
+| Commits Made | 87 |
+
+### Top Commands
+1. /rpi-research (23 uses)
+2. /rpi-implement (19 uses)
+3. /verify-docs-current (15 uses)
+4. /rpi-plan (12 uses)
+5. /help (8 uses)
+
+### Top Agents
+1. @core-architect (18 invocations)
+2. @api-developer (14 invocations)
+3. @database-ops (9 invocations)
+
+### Context Health
+- Documentation: 45K tokens (23% of budget)
+- Status: Healthy ✓
+
+Data stored locally in .ai-context/analytics/
+```
+
+### View Context Metrics
+
+```
+User: /analytics context
+
+Claude: ## Context Budget Analysis
+
+### Current State
+| Category | Tokens | % Budget |
+|----------|--------|----------|
+| Indexes | 12,400 | 6.2% |
+| Workflows | 18,200 | 9.1% |
+| Agents | 8,600 | 4.3% |
+| Commands | 5,800 | 2.9% |
+| **Total** | **45,000** | **22.5%** |
+
+### Budget Status
+✓ Under 40% target (healthy)
+
+### Largest Files
+1. context/workflows/authentication.md (4,200 tokens)
+2. context/ARCHITECTURE_SNAPSHOT.md (3,800 tokens)
+3. agents/core-architect.md (2,100 tokens)
+
+### Trend (Last 4 Weeks)
+Week 1: 42K tokens
+Week 2: 43K tokens
+Week 3: 44K tokens
+Week 4: 45K tokens (+7% growth)
+
+### Recommendations
+- Growth rate sustainable
+- No immediate action needed
+- Review if exceeds 50K tokens
+```
+
+### Export Metrics
+
+```
+User: /analytics export
+
+Claude: Exporting analytics data...
+
+Exported to: .ai-context/analytics/export-2024-01-15.json
+
+Contents:
+- Session history (42 sessions)
+- Command usage (156 invocations)
+- Agent usage (41 invocations)
+- Context metrics (4 weekly snapshots)
+
+File size: 24 KB
+```
+
+## Data Storage
+
+Analytics data is stored locally in `.ai-context/analytics/`:
+
+```
+.ai-context/analytics/
+├── sessions.json      # Session history
+├── commands.json      # Command usage
+├── agents.json        # Agent invocations
+├── context.json       # Context metrics
+└── exports/           # Exported files
+```
+
+## Configuration
+
+Configure analytics behavior in `.ai-context/settings.json`:
+
+```json
+{
+  "telemetry": {
+    "enabled": false,
+    "events": {
+      "command_usage": true,
+      "context_metrics": true,
+      "error_reports": false
+    },
+    "retention_days": 90
+  }
+}
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `enabled` | false | Enable/disable all tracking |
+| `command_usage` | true | Track command invocations |
+| `context_metrics` | true | Track context budget |
+| `error_reports` | false | Track errors (local only) |
+| `retention_days` | 90 | Days to retain data |
+
+## Privacy Notes
+
+1. **Local Only**: All data stays on your machine
+2. **No External Calls**: Nothing sent to external services
+3. **User Control**: Clear data anytime with `/analytics clear`
+4. **Opt-in**: Tracking disabled by default
+5. **Transparent**: All data in readable JSON files
+
+## Related
+
+- [Settings Configuration](./../settings.json)
+- [Context Budget Guidelines](./../README.md#context-budget)

package/templates/base/commands/auto-sync.md

@@ -0,0 +1,172 @@
+---
+name: auto-sync
+description: Automatically synchronize documentation with code
+version: 1.0.0
+category: sync
+context_budget: 15000
+outputs:
+  - context/CODE_TO_WORKFLOW_MAP.md (regenerated)
+  - sync/anchors.json (updated)
+  - sync/hashes.json (updated)
+  - sync/staleness.json (updated)
+---
+
+# /auto-sync
+
+Automatically synchronize all documentation with the current code state.
+
+## Syntax
+
+```
+/auto-sync [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--check` | Check for drift without making changes |
+| `--fix` | Auto-fix shifted line numbers and anchors |
+| `--rebuild-map` | Force rebuild CODE_TO_WORKFLOW_MAP |
+| `--update-hashes` | Update file content hashes |
+| `--report` | Generate detailed drift report |
+| `--dry-run` | Preview changes without writing |
+
+## What It Does
+
+1. **Scans Workflows** - Extracts all file:line references from documentation
+2. **Resolves Anchors** - Converts semantic anchors to current line numbers
+3. **Detects Drift** - Compares documented references with actual code
+4. **Updates Tracking** - Refreshes hashes and staleness timestamps
+5. **Regenerates Map** - Rebuilds CODE_TO_WORKFLOW_MAP.md
+
+## Examples
+
+### Check for Drift
+```
+/auto-sync --check
+```
+
+Output:
+```
+DRIFT CHECK REPORT
+
+Workflows Checked: 8
+  ✓ authentication.md - HEALTHY
+  ⚠ user-management.md - NEEDS UPDATE (3 line shifts)
+  ✗ payment.md - STALE (file deleted)
+
+Summary:
+  Healthy: 6
+  Needs Update: 1
+  Stale: 1
+```
+
+### Auto-Fix Issues
+```
+/auto-sync --fix
+```
+Automatically updates line numbers that have shifted.
+
+### Full Rebuild
+```
+/auto-sync --rebuild-map
+```
+Regenerates CODE_TO_WORKFLOW_MAP.md from scratch.
+
+## Drift Levels
+
+| Level | Meaning | Action |
+|-------|---------|--------|
+| HEALTHY | Documentation matches code | None needed |
+| LOW | Line numbers shifted slightly | Auto-fixable |
+| MEDIUM | Function moved or renamed | Review required |
+| HIGH | Logic changed significantly | Manual update needed |
+| CRITICAL | File deleted or major restructure | Full re-documentation |
+
+## Integration
+
+### With Git Hooks
+The pre-commit hook can run `--check` automatically:
+```bash
+npx claude-context hooks install
+```
+
+### With CI/CD
+Add to your pipeline:
+```yaml
+- name: Check documentation drift
+  run: npx claude-context sync --check --strict
+```
+
+## Process
+
+```
+1. Load workflow files from context/workflows/
+
+2. For each workflow:
+   a. Extract file:line references
+   b. Extract semantic anchors (file::function())
+   c. Resolve current locations
+   d. Compare with documented locations
+
+3. Generate drift report
+
+4. If --fix:
+   a. Update shifted line numbers
+   b. Update broken anchors where possible
+   c. Flag unfixable issues
+
+5. If --rebuild-map:
+   a. Scan all workflows for references
+   b. Build reverse index
+   c. Write CODE_TO_WORKFLOW_MAP.md
+
+6. Update tracking files:
+   - sync/hashes.json
+   - sync/staleness.json
+   - sync/anchors.json
+```
+
+## Output Files
+
+### CODE_TO_WORKFLOW_MAP.md
+```markdown
+## File Mappings
+
+### src/auth.py
+
+**Documented In:**
+- workflows/authentication.md
+- workflows/session.md
+
+**Update After Changing:**
+- [ ] authentication.md (lines 45, 78, 120)
+- [ ] session.md (line 33)
+```
+
+### sync/staleness.json
+```json
+{
+  "workflows": {
+    "authentication.md": {
+      "lastVerified": "2025-01-24T10:30:00Z",
+      "status": "verified"
+    }
+  }
+}
+```
+
+## Related Commands
+
+- `/verify-docs-current [file]` - Check specific file
+- `/validate-all` - Full validation suite
+- `/session-save` - Save session state
+
+## CLI Equivalent
+
+```bash
+npx claude-context sync --check
+npx claude-context sync --fix
+npx claude-context generate --code-map
+```