CC-PAI Optimizer (v2.1.12)

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:

# Check current version
claude --version

# Trusted sources
CC_SOURCES=(
  "https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md"
  "https://github.com/anthropics/claude-code/releases"
  "https://docs.anthropic.com/en/docs/claude-code"
  "https://github.com/marckrenn/claude-code-changelog/blob/main/cc-prompt.md"
)

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

2. Load PAI Repository

# Discover PAI structure
ls -la "$PAI_DIR/.claude/"

3. Run Analysis Pipeline

Execute analysis in this order:

1. Structure Analysis – Directory layout and required files
2. Skills System Audit – SKILL.md format, context types, invocability
3. Hooks Configuration – settings.json hooks, lifecycle events
4. Context Engineering Audit – UFC patterns, progressive disclosure
5. Delegation Patterns – Multi-agent workflows
6. 12-Factor Compliance – Agent principles audit
7. Upgrade Plan Generation – Prioritized recommendations

Analysis Modules

Structure Analysis

Expected PAI v2.x structure:

.claude/
├── context/           # Context files (CLAUDE.md)
├── skills/            # Skill definitions (replaces rules/)
│   └── */SKILL.md    # Each skill with frontmatter
├── agents/            # Agent configurations
├── commands/          # Reusable workflows
├── hooks/             # Hook scripts
├── state/             # State persistence
└── settings.json      # CC configuration with hooks

Skills System Analysis

Check for proper SKILL.md format:

---
name: skill-name
context: fork|same
description: What this skill does
---

Key checks:

• All skills have SKILL.md with frontmatter
• context: fork for isolated execution (subagent)
• context: same for main conversation
• references/, scripts/, workflows/ subdirectories

Hooks Configuration (CC 2.1.x)

Hooks are now in settings.json:

{
  "hooks": {
    "PreToolUse": [...],
    "PostToolUse": [...],
    "SessionStart": [...],
    "SessionEnd": [...],
    "UserPromptSubmit": [...],
    "Stop": [...],
    "SubagentStop": [...]
  }
}

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?
3. Factor 10 – Small Focused Agents: Are agents single-purpose?
4. Factor 12 – Stateless Reducer: Is state externalized?

Output Format

Generate report as:

# PAI Optimization Report

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

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

## Skills System
[SKILL.md format compliance, context types]

## Hooks Configuration
[settings.json hooks audit]

## 12-Factor Compliance
[Factor-by-factor status]

## 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

cd ${PAI_DIR}/skills/cc-pai-optimiser
bun run scripts/analyse-pai.js ${PAI_DIR}/..

Version Check

cd ${PAI_DIR}/skills/cc-pai-optimiser
bun run scripts/cc-version-check.js ${PAI_DIR}/..

Version Tracking

Track CC versions against PAI compatibility:

// Key CC 2.1.x features
const CC_2_1_FEATURES = {
  // 2.1.0
  modelRouting: "2.1.0",      // Per-task model selection
  skillInvocation: "2.1.0",   // Skill tool
  backgroundTasks: "2.1.0",   // run_in_background
  taskResume: "2.1.0",        // Resume via agent ID
  statusLine: "2.1.0",        // Custom status line
  settingsJsonHooks: "2.1.0", // Hooks in settings.json
  webSearch: "2.1.0",         // Built-in WebSearch
  askUserQuestion: "2.1.0",   // Interactive questions
  // 2.1.3
  mergedSkillsCommands: "2.1.3", // Unified slash commands and skills
  releaseChannelToggle: "2.1.3", // stable/latest in /config
  enhancedDoctor: "2.1.3",       // /doctor detects unreachable rules
  extendedHookTimeout: "2.1.3",  // Hook timeout: 60s → 10 min
  // 2.1.4
  disableBackgroundTasks: "2.1.4", // CLAUDE_CODE_DISABLE_BACKGROUND_TASKS env var
  // 2.1.5
  tmpDirOverride: "2.1.5",     // CLAUDE_CODE_TMPDIR env var
  // 2.1.6
  configSearch: "2.1.6",       // Search in /config command
  statsDateFiltering: "2.1.6", // /stats date range filtering
  nestedSkillDiscovery: "2.1.6", // Auto-discovery from nested .claude/skills
  contextWindowPercentage: "2.1.6", // used_percentage in status line input
  // 2.1.7
  turnDurationToggle: "2.1.7", // showTurnDuration setting
  permissionFeedback: "2.1.7", // Feedback on permission prompts
  mcpToolSearchAuto: "2.1.7",  // Auto-defer MCP tools >10% context
  // 2.1.9
  additionalContext: "2.1.9",  // PreToolUse hooks return context to model
  plansDirectory: "2.1.9",     // Custom plan file location
  sessionIdSubstitution: "2.1.9", // ${CLAUDE_SESSION_ID} in skills
  mcpAutoThreshold: "2.1.9",   // auto:N syntax for MCP tool threshold
  // 2.1.10
  // (no new features - bug fixes only)
  // 2.1.11
  mcpConnectionFix: "2.1.11",  // Fixed excessive HTTP/SSE MCP reconnection
  // 2.1.12
  messageRenderingFix: "2.1.12", // Fixed message rendering bug
};

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