CC-PAI Optimizer

Review and optimize PAI codebases by tracking Claude Code evolution and applying 12-factor agent principles.

Core Workflow

1. Gather Latest Claude Code Features

Before any optimization, fetch current CC capabilities from trusted sources:

# Set trusted sources
CC_SOURCES=(
  "https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md"
  "https://github.com/anthropics/claude-code/releases"
  "https://docs.claude.com/en/release-notes/overview"
)

# Check latest version
claude --version 2>/dev/null || echo "Claude Code not installed locally"

Reference references/cc-trusted-sources.md for complete source list and update frequency recommendations.

2. Load PAI Repository

# Discover PAI structure
find "$PAI_DIR" -name "CLAUDE.md" -o -name ".claude" -type d -exec basename {} \; 2>/dev/null

3. Run Analysis Pipeline

Execute analysis in this order:

1. Feature Gap Analysis - Compare current PAI against latest CC features
2. 12-Factor Compliance - Audit against agent principles
3. Context Engineering Audit - Review context management patterns
4. Upgrade Plan Generation - Create prioritized recommendations

Analysis Modules

Feature Gap Analysis

Compare PAI implementation against CC capabilities:

12-Factor Compliance Check

Reference references/12-factor-checklist.md for complete audit criteria.

Key factors to validate:

1. Factor 3 - Own Context Window: Is context hydration explicit and controlled?
2. Factor 8 - Own Control Flow: Is agent loop logic in application code, not framework?
3. Factor 10 - Small Focused Agents: Are agents single-purpose or monolithic?
4. Factor 12 - Stateless Reducer: Is state externalized properly?

Context Engineering Audit

Evaluate against UFC (Universal File-based Context) principles:

Check hierarchy:
~/.claude/
├── context/           # Should exist with CLAUDE.md files
├── agents/            # Specialized agent configs
├── commands/          # Reusable workflows
└── hooks/             # Event automation

Red flags:

• Context files >500 lines (split needed)
• Missing progressive disclosure patterns
• Hardcoded context (should be file-based)
• No context loading enforcement

Output Format

Generate report as:

# PAI Optimization Report

## Executive Summary
[1-2 sentence overall assessment]

## CC Feature Adoption
| Feature | Status | Priority | Effort |
|---------|--------|----------|--------|

## 12-Factor Compliance
[Factor-by-factor status with specific file references]

## Context Engineering
[UFC audit results]

## Recommended Upgrades
1. [High Priority] ...
2. [Medium Priority] ...

## Implementation Snippets
[Ready-to-use code for top recommendations]

Quick Commands

Full Audit

# Comprehensive PAI review
analyze_pai() {
  local pai_path="${1:-.}"
  echo "=== PAI Analysis: $pai_path ==="
  
  # Structure check
  echo "## Structure"
  tree -L 3 "$pai_path/.claude" 2>/dev/null || echo "No .claude directory"
  
  # Context file audit
  echo "## Context Files"
  find "$pai_path" -name "CLAUDE.md" -exec wc -l {} \;
  
  # MCP configuration
  echo "## MCP Config"
  cat "$pai_path/.mcp.json" 2>/dev/null || echo "No MCP config"
}

Feature Diff

# Compare PAI against CC version
cc_feature_diff() {
  echo "Claude Code Version: $(claude --version 2>/dev/null || echo 'N/A')"
  echo "Checking for:"
  echo "  - Subagent support: $(grep -r 'subagent' . 2>/dev/null | wc -l) references"
  echo "  - Hook usage: $(ls .claude/hooks 2>/dev/null | wc -l) hooks"
  echo "  - Skill definitions: $(ls .claude/rules 2>/dev/null | wc -l) skills"
}

Integration with PAI System

When optimizing an existing PAI setup:

1. Preserve existing context loading protocols (Layer 1-4 enforcement)
2. Enhance with new CC features (subagents, checkpoints, hooks)
3. Validate changes don't break context hydration
4. Document all changes in appropriate CLAUDE.md files

Version Tracking

Track CC versions against PAI compatibility:

// scripts/cc-version-check.js
const CC_MIN_VERSION = "2.0.0";
const FEATURE_REQUIREMENTS = {
  subagents: "1.0.80",
  checkpoints: "2.0.0",
  hooks: "1.0.85",
  skills: "2.0.40",
  planMode: "2.0.50"
};

See scripts/cc-version-check.js for automated compatibility checking.