feat: add claude subagent setup script and refine ai chain

config/ai.yml

@@ -16,12 +16,15 @@ version: 1
 
 runner:
   command_chain:
-    # Anthropic Claude CLI (reads prompt from stdin when -p is present)
+    # Anthropic Claude CLI with custom subagent (fast Haiku model)
-    - "claude -p"
+    # Create ~/.claude/agents/cdev-patch.md once with: ./tools/setup-claude-agents.sh
-    # OpenAI / Codex-compatible wrapper (expects prompt on stdin)
+    - "claude --agent cdev-patch -p"
-    - "codex-cli --stdin --model gpt-4.1-mini"
+    # OpenAI Codex CLI with GPT-5 (default model, good balance)
-    # Google Gemini CLI (prompt via stdin, raw text response)
+    # Authenticate once with: codex (follow prompts to sign in)
-    - "gemini-cli --model=gemini-1.5-pro --stdin"
+    - "codex --model gpt-5"
+    # Google Gemini 2.5 Flash (fast, 1M context, free tier: 60 req/min)
+    # Authenticate once with: gemini (sign in with Google account)
+    - "gemini --model gemini-2.5-flash"
   sentinel: "CASCADINGDEV_NO_CHANGES"
 
 ramble:
@@ -32,17 +35,18 @@ ramble:
     claude:
       kind: claude_cli
       command: "claude"
-      args: []
+      args:
+        - "--agent"
+        - "cdev-patch"
     codex:
       kind: codex_cli
-      command: "codex-cli"
+      command: "codex"
       args:
-        - "--stdin"
         - "--model"
-        - "gpt-4.1-mini"
+        - "gpt-5"
     gemini:
       kind: gemini_cli
-      command: "gemini-cli"
+      command: "gemini"
       args:
-        - "--model=gemini-1.5-pro"
+        - "--model"
-        - "--stdin"
+        - "gemini-2.5-flash"

docs/AUTOMATION.md

@@ -95,13 +95,27 @@ export CDEV_AI_COMMAND="claude -p '{prompt}'"
 
 Common non-interactive setups:
 
-| Provider | Example command | Required auth | Tips |
+| Provider | CLI Tool | Command Example | Authentication | Notes |
-| --- | --- | --- | --- |
+| --- | --- | --- | --- | --- |
-| Claude CLI | `claude -p` (reads prompt from stdin) | `ANTHROPIC_API_KEY` or `claude login` | Add `--model claude-3-5-sonnet-20241022` or `--agent my-cascading-agent` to target a specific model or saved agent persona. |
+| Claude | `claude` | `claude --agent cdev-patch -p` | Run `claude` and follow prompts to sign in | Supports custom subagents in `~/.claude/agents/`. Create with `./tools/setup-claude-agents.sh`. Uses Haiku (fast) or Sonnet (quality). |
-| Codex / OpenAI | `codex-cli --stdin --model gpt-4.1-mini` | `OPENAI_API_KEY` (+ `OPENAI_ORG_ID` if needed) | The stock `openai` CLI works via `openai api chat.completions.create -m gpt-4o-mini --input -`; wrap it if you prefer shorter aliases. |
+| OpenAI | `codex` | `codex --model gpt-5` | Run `codex` and sign in with ChatGPT account | Codex CLI is OpenAI's terminal coding agent. Default model: GPT-5. Use `gpt-5-mini` for faster, cheaper responses. |
-| Gemini | `gemini-cli --model=gemini-1.5-pro --stdin` | `GOOGLE_API_KEY`/`GEMINI_API_KEY` with Generative Language API enabled | Some CLIs default to streaming mode—add `--no-stream` or similar so stdout is plain text. |
+| Google | `gemini` | `gemini --model gemini-2.5-flash` | Run `gemini` and sign in with Google account | Free tier: 60 req/min. Use `gemini-2.5-flash` (fast) or `gemini-2.5-pro` (1M context, quality). Open source (Apache 2.0). |
 
-Update `config/ai.yml` to match the actual binary names or wrapper scripts on your machine.
+**Recommended Setup:** Use the provided setup script to create Claude subagents:
+```bash
+# One-time setup (creates ~/.claude/agents/cdev-patch.md and cdev-patch-quality.md)
+./tools/setup-claude-agents.sh
+```
+
+This creates two subagent files:
+- `cdev-patch.md` - Uses Haiku model (fast, cost-efficient)
+- `cdev-patch-quality.md` - Uses Sonnet model (higher quality, deeper analysis)
+
+The default `config/ai.yml` uses the fast version. To temporarily use the quality version for complex changes:
+```bash
+# Override for a single commit
+CDEV_AI_COMMAND="claude -p" git commit -m "complex refactor"
+```
 
 **Option 2: Direct API (Alternative)**
 ```bash

tools/setup_claude_agents.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+AGENT_DIR="${HOME}/.claude/agents"
+mkdir -p "${AGENT_DIR}"
+
+create_agent() {
+  local filename="$1"
+  local name="$2"
+  local model="$3"
+  local description="$4"
+  cat <<EOF > "${AGENT_DIR}/${filename}"
+---
+name: ${name}
+description: ${description}
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+model: ${model}
+---
+You are the automated diff writer for CascadingDev. Always return unified git
+diffs wrapped between <<<AI_DIFF_START>>> and <<<AI_DIFF_END>>> markers.
+
+- If no changes are needed, output only CASCADINGDEV_NO_CHANGES.
+- Never include explanations, Markdown fences, or extra commentary.
+- Honour existing file context and minimise edits.
+EOF
+}
+
+create_agent "cdev-patch.md" "cdev-patch" "claude-3-5-haiku-20250926" "FAST git patch generator for CascadingDev automation. MUST BE USED when prompted to create patches."
+create_agent "cdev-patch-quality.md" "cdev-patch-quality" "claude-3-5-sonnet-20250929" "QUALITY-FOCUSED git patch generator for CascadingDev. Use when task is complex or requires deep reasoning."
+
+cat <<'EOF'
+[✓] Claude subagents written to ~/.claude/agents/
+- cdev-patch (Haiku)          → fast diff generation
+- cdev-patch-quality (Sonnet) → deeper analysis fallback
+
+Run `claude agents list` to verify they are available.
+EOF