SuperCharged-Claude-Code-Upgrade/plugins/claude-delegator/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

A Claude Code plugin that provides GPT (via Codex CLI) as specialized expert subagents. Five domain experts that can advise OR implement: Architect, Plan Reviewer, Scope Analyst, Code Reviewer, and Security Analyst.

Development Commands

# Test plugin locally (loads from working directory)
claude --plugin-dir /path/to/claude-delegator

# Run setup to test installation flow
/claude-delegator:setup

# Run uninstall to test removal flow
/claude-delegator:uninstall

No build step, no dependencies. Uses Codex CLI's native MCP server.

Architecture

Orchestration Flow

Claude acts as orchestrator—delegates to specialized GPT experts based on task type. Delegation is stateless: each mcp__codex__codex call is independent (no memory between calls).

User Request → Claude Code → [Match trigger → Select expert]
                                    ↓
              ┌─────────────────────┼─────────────────────┐
              ↓                     ↓                     ↓
         Architect            Code Reviewer        Security Analyst
              ↓                     ↓                     ↓
    [Advisory (read-only) OR Implementation (workspace-write)]
              ↓                     ↓                     ↓
    Claude synthesizes response ←──┴──────────────────────┘

How Delegation Works

1. Match trigger - Check rules/triggers.md for semantic patterns
2. Read expert prompt - Load from prompts/[expert].md
3. Build 7-section prompt - Use format from rules/delegation-format.md
4. Call mcp__codex__codex - Pass expert prompt via developer-instructions
5. Synthesize response - Never show raw output; interpret and verify

The 7-Section Delegation Format

Every delegation prompt must include: TASK, EXPECTED OUTCOME, CONTEXT, CONSTRAINTS, MUST DO, MUST NOT DO, OUTPUT FORMAT. See rules/delegation-format.md for templates.

Retry Handling

Since each call is stateless, retries must include full history:

• Attempt 1 fails → new call with original task + error details
• Up to 3 attempts → then escalate to user

Component Relationships

Component	Purpose	Notes
rules/*.md	When/how to delegate	Installed to ~/.claude/rules/delegator/
prompts/*.md	Expert personalities	Injected via developer-instructions
commands/*.md	Slash commands	/setup, /uninstall
config/providers.json	Provider metadata	Not used at runtime

Expert prompts adapted from oh-my-opencode

Five GPT Experts

Expert	Prompt	Specialty	Triggers
Architect	prompts/architect.md	System design, tradeoffs	"how should I structure", "tradeoffs of", design questions
Plan Reviewer	prompts/plan-reviewer.md	Plan validation	"review this plan", before significant work
Scope Analyst	prompts/scope-analyst.md	Requirements analysis	"clarify the scope", vague requirements
Code Reviewer	prompts/code-reviewer.md	Code quality, bugs	"review this code", "find issues"
Security Analyst	prompts/security-analyst.md	Vulnerabilities	"is this secure", "harden this"

Every expert can operate in advisory (sandbox: read-only) or implementation (sandbox: workspace-write) mode based on the task.

Key Design Decisions

1. Native MCP only - Codex has codex mcp-server, no wrapper needed
2. Stateless calls - Each delegation includes full context (Codex MCP doesn't expose session IDs to Claude Code)
3. Dual mode - Any expert can advise or implement based on task
4. Synthesize, don't passthrough - Claude interprets GPT output, applies judgment
5. Proactive triggers - Claude checks for delegation triggers on every message

When NOT to Delegate

• Simple syntax questions (answer directly)
• First attempt at any fix (try yourself first)
• Trivial file operations
• Research/documentation tasks