prompt-executor

What this skill does

# Prompt Executor

## Auto-Approval Setup

If the user has to manually confirm the executor bash command, suggest they add this rule to `~/.claude/settings.json` under `permissions.allow`:

```json
"Bash(PLUGIN_ROOT=$(jq -r '.plugins.\"daplug@cruzanstx\"[0].installPath' ~/.claude/plugins/installed_plugins.json):*)"
```

**Quick command to add it:**
```bash
# Add auto-approval rule for prompt executor
jq '.permissions.allow += ["Bash(PLUGIN_ROOT=$(jq -r '"'"'.plugins.\"daplug@cruzanstx\"[0].installPath'"'"' ~/.claude/plugins/installed_plugins.json):*)"]' ~/.claude/settings.json > /tmp/settings.json && mv /tmp/settings.json ~/.claude/settings.json
```

---

Execute prompts from `./prompts/` (including subfolders) using various AI models (Claude, Codex, Gemini, ZAI, etc).

## When to Use This Skill

- User says "run prompt 123" or "execute prompt 123"
- User says "run that prompt with codex/gemini/zai"
- User wants to "run a prompt in a worktree"
- User wants to "run prompts in parallel"
- User asks to "delegate this to codex/gemini"
- User wants to "run with verification loop" or "keep retrying until complete"
- User asks to "check loop status" for a running prompt

## Executor Script

**IMPORTANT:** Get the executor path from Claude's installed plugins manifest:

```bash
PLUGIN_ROOT=$(jq -r '.plugins."daplug@cruzanstx"[0].installPath' ~/.claude/plugins/installed_plugins.json)
EXECUTOR="$PLUGIN_ROOT/skills/prompt-executor/scripts/executor.py"
python3 "$EXECUTOR" [prompts...] [options]
```

**Options:**
- `--model, -m`: claude, cc-sonnet, cc-opus, codex, codex-spark, codex-high, codex-xhigh, gpt54, gpt54-high, gpt54-xhigh, gpt55, gpt55-high, gpt55-xhigh, gpt52, gpt52-high, gpt52-xhigh, gemini, gemini-high, gemini-xhigh, gemini25pro, gemini25flash, gemini25lite, gemini3flash, gemini3pro, gemini31pro, zai, glm5, kimi, opencode, local, qwen, devstral, glm-local, qwen-small
- `--cli`: Override CLI wrapper (codex, opencode, or claude; aliases: claudecode, cc). Unsupported explicit combinations fail with a clear error (no silent fallback).
- `--variant`: Reasoning variant override (`none|low|medium|high|xhigh`). Explicit `--variant` overrides alias defaults (`codex-high`, `gpt55-high`, `gpt54-high`, `gpt52-high`, etc.).
- `--cwd, -c`: Working directory for execution
- `--run, -r`: Actually run the CLI (default: just return info)
- `--info-only, -i`: Only return prompt info, no CLI details
- `--worktree, -w`: Create isolated git worktree for execution
- `--sandbox`: Enable sandboxing (Linux default backend: bubblewrap)
- `--sandbox-type`: Sandbox backend override (`bubblewrap`)
- `--no-sandbox`: Explicitly disable sandboxing
- `--sandbox-profile`: Isolation profile (`strict|balanced|dev`, default `balanced`)
- `--sandbox-workspace`: Override sandbox workspace path (default: execution cwd)
- `--sandbox-net`: Network override (`on|off`; default comes from profile)
- `--base-branch, -b`: Base branch for worktree (default: main)
- `--on-conflict`: How to handle existing worktree (error|remove|reuse|increment)
- `--loop, -l`: Enable iterative verification loop until completion
- `--max-iterations`: Max loop iterations before giving up (default: 3)
- `--completion-marker`: Text pattern signaling completion (default: VERIFICATION_COMPLETE)
- `--loop-status`: Check status of an existing verification loop

**Output:** JSON with prompt content, CLI command, log path, worktree info, and loop state if enabled

## Execution Flows

### Direct Execution (default)

```bash
# Get executor path from installed plugins manifest
PLUGIN_ROOT=$(jq -r '.plugins."daplug@cruzanstx"[0].installPath' ~/.claude/plugins/installed_plugins.json)
EXECUTOR="$PLUGIN_ROOT/skills/prompt-executor/scripts/executor.py"

# Get prompt info
python3 "$EXECUTOR" 123 --model codex

# Force OpenCode path with reasoning variant
python3 "$EXECUTOR" 123 --model codex --cli opencode --variant high

# Folder-qualified prompt (resolves prompts/providers/011-*.md)
python3 "$EXECUTOR" providers/011 --model codex

# Run in current directory
python3 "$EXECUTOR" 123 --model codex --run

# Run in bubblewrap sandbox (Linux)
python3 "$EXECUTOR" 123 --model codex --run --sandbox

# Strict profile (no network by default)
python3 "$EXECUTOR" 123 --model codex --run --sandbox --sandbox-profile strict

# Explicit opt-out
python3 "$EXECUTOR" 123 --model codex --run --no-sandbox
```

### With Worktree (built-in)

Single command creates worktree, copies TASK.md, and optionally runs:

```bash
# Create worktree and get info
python3 "$EXECUTOR" 123 --worktree --model codex

# Create worktree and run immediately
python3 "$EXECUTOR" 123 --worktree --model codex --run

# Use different base branch
python3 "$EXECUTOR" 123 --worktree --base-branch develop --model codex
```

The worktree directory is read from `worktree_dir` in `<daplug_config>` within CLAUDE.md (via config-reader), or defaults to `../worktrees/`.

### With tmux (use tmux-manager skill)

1. Get CLI command from executor:
```bash
python3 "$EXECUTOR" 123 --model codex
# Returns: {"cli_command": ["codex", "exec", "--full-auto"], "content": "...", "log": "..."}
```

2. Create tmux session using tmux-manager patterns:
```bash
SESSION_NAME="prompt-123-$(date +%Y%m%d-%H%M%S)"
tmux new-session -d -s "$SESSION_NAME" -c "$WORKTREE_PATH"
```

3. Send command to session:
```bash
tmux send-keys -t "$SESSION_NAME" "codex exec --full-auto '...' 2>&1 | tee $LOG_FILE" C-m
```

### With Verification Loop

Run prompts with automatic retries until the task is verified complete:

```bash
# Run with verification loop (background, default 3 iterations)
python3 "$EXECUTOR" 123 --model codex --run --loop

# With custom max iterations
python3 "$EXECUTOR" 123 --model codex --run --loop --max-iterations 5

# With custom completion marker
python3 "$EXECUTOR" 123 --model codex --run --loop --completion-marker "TASK_DONE"

# Worktree + loop combo
python3 "$EXECUTOR" 123 --model codex --worktree --run --loop
```

**Output includes:**
```json
{
  "execution": {
    "status": "loop_running",
    "pid": 12345,
    "loop_log": "~/.claude/cli-logs/codex-123-loop-20251229-120000.log",
    "state_file": "~/.claude/loop-state/123.json",
    "max_iterations": 3,
    "completion_marker": "VERIFICATION_COMPLETE"
  }
}
```

Log paths follow `cli_logs_dir` from `<daplug_config>` if configured (default `~/.claude/cli-logs/`).

**Completion markers (required):**
- To end the loop, the model must output a final-line verification tag: `<verification>VERIFICATION_COMPLETE</verification>`.
- To request another iteration, output: `<verification>NEEDS_RETRY: [reason]</verification>`.
- The executor ignores any markers that appear inside echoed prompt instructions (some CLIs print the full prompt into logs).

### Check Loop Status

```bash
# Check specific prompt's loop
python3 "$EXECUTOR" 123 --loop-status

# List all active loops
python3 "$EXECUTOR" --loop-status
```

## Model Reference

| Model | CLI | Description |
|-------|-----|-------------|
| claude | (Task subagent) | Claude Sonnet via subagent |
| codex | codex exec --full-auto | OpenAI Codex (gpt-5.5) |
| codex-high | codex exec --full-auto -c model_reasoning_effort="high" | Codex alias with default `--variant high` |
| codex-xhigh | codex exec --full-auto -c model_reasoning_effort="xhigh" | Codex alias with default `--variant xhigh` |
| gpt54 | codex exec --full-auto -m gpt-5.4 | GPT-5.4 direct shorthand |
| gpt54-high | codex exec --full-auto -m gpt-5.4 -c model_reasoning_effort="high" | GPT-5.4 alias with default `--variant high` |
| gpt54-xhigh | codex exec --full-auto -m gpt-5.4 -c model_reasoning_effort="xhigh" | GPT-5.4 alias with default `--variant xhigh` |
| gpt55 | codex exec --full-auto | GPT-5.5 direct shorthand |
| gpt55-high | codex exec --full-auto -c model_reasoning_effort="high" | GPT-5.5 alias with default `--variant high` |
| gpt55-xhigh | codex exec --full-auto -c model_reasoning_effort="xhigh" | GPT-5.5 alias with default `--variant xhigh`