# Weave Brainstorm And Refine > Use when asked to brainstorm then refine, generate ideas then improve, or explore alternatives and synthesize the best one across passes. - Skill: `tony/weave-brainstorm-and-refine` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add tony/weave-brainstorm-and-refine` - Raw SKILL.md: https://api.skillmd.com/api/skills/tony/weave-brainstorm-and-refine/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tony (https://skillmd.com/u/tony) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tony/weave-brainstorm-and-refine --- # Weave Brainstorm & Refine Generate independent originals from adversarial participants, then refine them through judge-weave-incorporate cycles. Host-native sub-agents are the default; separate model CLIs are available by explicit choice. ## When to Use - You want the best of both worlds: creative divergence then convergent refinement - You want to explore a problem space broadly, then hone in on the best solution - You need a high-quality result and are willing to spend tokens on multiple passes ## Key Features - `--workers=subagents|model-clis`: Use host-native sub-agents by default or explicitly select separate model CLIs - Phase 1 (Brainstorm): Independent originals from each participant, optional `--variants=N` - Transition gate: You choose which originals enter refinement - Phase 2 (Refine): Iterative judge-weave-distribute cycle over `--passes=N` - Full rationale chain from brainstorm through every refinement pass - `--judge=host|round-robin`: Host judges every pass, or rotate judging across participants ## The Pipeline 1. **Brainstorm**: Each participant generates independent original responses 2. **Review**: All originals presented — you pick which ones to refine 3. **Refine**: Judge picks the best, weaves in strengths from runners-up, redistributes to all participants 4. **Repeat**: Each pass improves the woven result until convergence or passes exhausted The full pipeline: generate originals from independent adversarial workers, then iteratively refine them through a judge-weave-distribute cycle. Host-native sub-agents are the default; separate model CLIs are optional. Phase 1 brainstorms diverse responses with optional multiple variants per worker. Phase 2 takes the best originals through iterative refinement where each pass picks the best, incorporates strengths from runners-up, and distributes the woven result back for another round. This is a **project-read-only** command — no files in your repository are written, edited, or deleted. Session artifacts (model outputs, judge assessments, woven results) are persisted to `$AI_AIP_ROOT` for post-session inspection; this directory is outside your repository. The prompt comes from `$ARGUMENTS`. If no arguments are provided, ask the user what they want to brainstorm and refine. ## Worker selection Before any other unresolved configuration choice or operational step, read `references/worker-backends.md`. Resolve `worker_backend` from `--workers=subagents|model-clis` using that reference; if the flag is absent, ask its worker question first. If interactive choice is unavailable, honor its documented headless default. The selected backend governs the whole session: dispatch, retry, judging, refinement, artifacts, session metadata, and presentation. The shared reference adapts provider-named examples across every later phase to that backend. When `worker_backend == subagents`, use only the reference's native sub-agent path. Skip every model-CLI detection, timeout question, timeout resolution, retry, fallback, and dispatch instruction below. Every such instruction below is conditional on `worker_backend == model-clis`. --- ## Phase 1: Gather Context **Goal**: Understand the project and prepare the prompt. 1. **Read CLAUDE.md / AGENTS.md** if present — project conventions inform better responses. 2. **Determine trunk branch** (for prompts about branch changes): ```bash git remote show origin | grep 'HEAD branch' ``` Fall back to `main`, then `master`, if detection fails. 3. **Capture the prompt**: Use `$ARGUMENTS` as the user's prompt. If `$ARGUMENTS` is empty, ask the user what they want to brainstorm and refine. --- ## Phase 1b: Build Context Packet After Phase 1 context gathering (reading CLAUDE.md, exploring files, capturing the task), assemble a structured context bundle that will be included verbatim in ALL model prompts. This ensures every model works from the same information. Write to `$SESSION_DIR/context-packet.md` *(the actual file write happens after Session Directory Initialization in Phase 2 creates `$SESSION_DIR`)*: 1. **Conventions summary** — key rules from CLAUDE.md/AGENTS.md (max 50 lines). Focus on commit format, test patterns, code style, and quality gates relevant to the task. 2. **Repo state** — branch, HEAD ref, trunk branch, uncommitted changes summary: ```bash git status --short ``` 3. **Changed files** — branch changes relative to trunk: ```bash git diff --stat origin/...HEAD ``` 4. **Relevant file list** — files matching task keywords discovered during Phase 1 exploration. Include paths only, not content. 5. **Key snippets** — critical function signatures, types, test patterns, or API contracts relevant to the task (max 200 lines). Prioritize interfaces over implementations. 6. **Known unknowns** — aspects of the task that need discovery during execution. List what the model should investigate. **Size limit**: 400 lines total. Prioritize by task relevance. If the packet exceeds 400 lines, truncate the least relevant sections (snippets first, then file list). **Usage in model prompts**: - For the **Claude Task agent**: reference the file path (`$SESSION_DIR/context-packet.md`) — the agent reads it directly - For **Antigravity and GPT sub-agents**: include the context packet content in the agent prompt, which the sub-agent then passes to the external CLI For `brainstorm-and-refine`, include conventions summary, relevant file list, key snippets, and known unknowns. Prioritize content that helps models produce diverse, high-quality originals. --- ## Phase 2: Configuration and Model Detection ### Step 1: Parse Flags Scan `$ARGUMENTS` for explicit flags anywhere in the text. Flags use `--name=value` syntax and are stripped from the prompt text before sending to models. | Flag | Values | Default | Description | |------|--------|---------|-------------| | `--variants=N` | 1–3 | 1 | Independent prompts per model (brainstorm phase) | | `--passes=N` | 1–5 | 2 | Number of refinement passes (refine phase) | | `--timeout=N\|none` | seconds or `none` | 450s | Timeout for external model commands | | `--mode=fast\|balanced\|deep` | mode preset | `balanced` | Execution mode preset | | `--judge=host\|round-robin` | judge mode | `host` | Who judges refinement passes | | `--preamble=...` | text | built-in | Override brainstorm variant preamble | | `--no-deslop` | flag | off | Skip the final deslop pass on the woven synthesis | | `--quiet-deslop` | flag | off | Replace the 8-line deslop summary with one line | | `--verbose-deslop` | flag | off | Add tier letter, signature id, confidence per finding | **Mode presets** set defaults for variants, passes, and timeout when not explicitly overridden: | Mode | Variants | Passes | Timeout multiplier | |------|----------|--------|--------------------| | `fast` | 1 | 1 | 0.5x default | | `balanced` | 1 | 2 | 1x default | | `deep` | 2 | 3 | 1.5x default | **Backward compatibility**: Legacy trigger words are silently recognized as aliases: - `multipass` (case-insensitive) → `--passes=2` - `x` (N = 2–5, regex `\bx([2-5])\b`) → `--passes=N` - `timeout:` → `--timeout=` - `timeout:none` → `--timeout=none` Legacy triggers are scanned on the first and last line only (to avoid false positives in pasted content). Explicit `--` flags take priority over legacy triggers. Values above 3 for `--variants` are capped at 3 with a note to the user. Values above 5 for `--passes` are capped at 5. **`--judge` flag**: `--judge=host` (default) uses the host agent (Claude) as judge for all refinement passes. `--judge=round-robin` rotates judging across available models: Pass 1 → Claude, Pass 2 → Antigravity, Pass 3 → GPT, Pass 4 → Claude, etc. The rotation includes only models that are available (detected in Step 3). If only one model is available, round-robin degrades to host mode. External model judges produce scores and pick winners; the host agent always weaves. See the External Judge Protocol in Phase 5 Step 1 for details. **Config flags** (used in Step 2): - `variant_count` = parsed from `--variants`, mode preset, or null - `pass_count` = parsed from `--passes`, mode preset, or legacy trigger. Null if not provided. - `timeout_value` = parsed from `--timeout`, mode preset, or legacy trigger. Null if not provided. - `judge_mode` = parsed from `--judge` or `"host"` default ### Step 2: Interactive Configuration **When flags are provided, skip the corresponding question.** When `--variants` is provided, skip the variants question. When `--passes` is provided, skip the passes question. When `--timeout` is provided, skip the timeout question. If `ask-user-choice` is unavailable (headless mode via `claude -p`), use flag values if set, otherwise: 1 variant, 2 passes, 450s timeout. Use `ask-user-choice` to prompt the user for any unresolved settings: **Question 1 — Variants** (skipped when `--variants` was provided): - question: "How many brainstorm variants per model? Each variant gets a distinct creative direction." - header: "Variants" - When `variant_count` exists (from mode preset), move the matching option first with "(Recommended)" suffix. - When `variant_count` is null, use default ordering: - "1 — one per model (Recommended)" — Each model produces one original response. - "2 — two per model" — Each model produces two originals with different creative directions. - "3 — three per model" — Maximum diversity. Three originals per model. **Question 2 — Passes** (skipped when `--passes` was provided): - question: "How many refinement passes after brainstorming? Each pass judges, weaves, and redistributes." - header: "Passes" - When `pass_count` exists (from mode preset or legacy trigger), move the matching option first with "(Recommended)" suffix. - When `pass_count` is null, use default ordering: - "2 — two passes (Recommended)" — One full refinement cycle. Good balance of quality and cost. - "1 — single pass" — Judge and weave once. Minimal refinement. - "3 — triple pass" — Two refinement rounds. Maximum depth, highest token usage. **Question 3 — Timeout** (skipped when `--timeout` was provided): - question: "Timeout for external model commands?" - header: "Timeout" - options: - "Default (450s)" — Use this command's built-in default timeout. - "Quick — 225s" — For fast queries (0.5x default). May timeout on complex tasks. - "Long — 675s" — For complex tasks (1.5x default). Higher wait on failures. - "None" — No timeout. Wait indefinitely for each model. ### Step 3: Detect Available Models **Goal**: Check which AI CLI tools are installed locally. Run these checks in parallel: ```bash command -v agy >/dev/null 2>&1 && echo "agy:available" || echo "agy:missing" ``` ```bash command -v gemini >/dev/null 2>&1 && echo "gemini:available" || echo "gemini:missing" ``` ```bash command -v codex >/dev/null 2>&1 && echo "codex:available" || echo "codex:missing" ``` ```bash command -v agent >/dev/null 2>&1 && echo "agent:available" || echo "agent:missing" ``` #### Model resolution (priority order) | Slot | Priority 1 (native) | Native model | Fallback chain | Agent model | |------|---------------------|--------------|----------------|----------- | | **Claude** | Always available (this agent) | — | — | — | | **Antigravity** | `agy` binary | `Gemini 3.1 Pro (High)` | `gemini -m gemini-3-pro-preview` → `agent --model gemini-3.1-pro` | `gemini-3.1-pro` | | **GPT** | `codex` binary | (default) | `agent --model gpt-5.4-high` | `gpt-5.4-high` | **Resolution logic** for each external slot: 1. Native CLI found → use it 2. Else next CLI in the fallback chain → use it (`agent` slots use the `--model` flag) 3. Else → slot unavailable, note in report The **Antigravity** slot is Google's lane: `agy` (Antigravity) supersedes the standalone `gemini` CLI, which Google retires on 2026-06-18. `agy` has no native read-only mode, so read-only commands isolate it in a disposable git worktree (Repo Guard Layer 1; see `docs/repo-guard-protocol.md`). Because brainstorm runs multiple variants per model that may execute in parallel, each variant isolates `agy` in its own uniquely-named worktree. Report which models will participate and which backend each uses. ### Step 3b: Detect Search Tools Run these checks in parallel alongside model detection: ```bash command -v rg >/dev/null 2>&1 && echo "rg:available" || echo "rg:missing" ``` ```bash command -v ag >/dev/null 2>&1 && echo "ag:available" || echo "ag:missing" ``` ```bash command -v fd >/dev/null 2>&1 && echo "fd:available" || echo "fd:missing" ``` **Resolution priority**: `rg` > `ag` > `grep` for content search; `fd` > `find` for file discovery. Used during context-packet building for faster file/content discovery. ### Step 4: Detect Timeout Command ```bash command -v timeout >/dev/null 2>&1 && echo "timeout:available" || { command -v gtimeout >/dev/null 2>&1 && echo "gtimeout:available" || echo "timeout:none"; } ``` On Linux, `timeout` is available by default. On macOS, `gtimeout` is available via GNU coreutils. If neither is found, run external commands without a timeout prefix — time limits will not be enforced. Do not install packages automatically. Store the resolved timeout command (`timeout`, `gtimeout`, or empty) for use in all subsequent CLI invocations. When constructing bash commands, replace `` with the resolved command and `` with the resolved value (from trigger parsing, interactive config, or the command's default). If no timeout command is available, omit the prefix entirely. When `--timeout=none` is configured (via flag or interactive selection), also omit `` and `` entirely — run external commands without any timeout prefix. ### Session Directory Initialization #### Step 1: Resolve storage root ```bash if [ -n "$AI_AIP_ROOT" ]; then AIP_ROOT="$AI_AIP_ROOT" elif [ -n "$XDG_STATE_HOME" ]; then AIP_ROOT="$XDG_STATE_HOME/ai-aip" elif [ "$(uname -s)" = "Darwin" ]; then AIP_ROOT="$HOME/Library/Application Support/ai-aip" else AIP_ROOT="$HOME/.local/state/ai-aip" fi ``` Create a `/tmp/ai-aip` symlink to the resolved root for backward compatibility (if `/tmp/ai-aip` doesn't already exist or isn't already correct): ```bash ln -sfn "$AIP_ROOT" /tmp/ai-aip 2>/dev/null || true ``` #### Step 2: Compute repo identity ```bash REPO_TOPLEVEL="$(git rev-parse --show-toplevel)" ``` ```bash REPO_SLUG="$(basename "$REPO_TOPLEVEL" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9._-]/-/g')" ``` ```bash REPO_ORIGIN="$(git remote get-url origin 2>/dev/null || true)" ``` ```bash if [ -n "$REPO_ORIGIN" ]; then REPO_KEY="${REPO_ORIGIN}|${REPO_SLUG}" else REPO_KEY="$REPO_TOPLEVEL" fi ``` ```bash if command -v sha256sum >/dev/null 2>&1; then REPO_ID="$(printf '%s' "$REPO_KEY" | sha256sum | cut -c1-12)" else REPO_ID="$(printf '%s' "$REPO_KEY" | shasum -a 256 | cut -c1-12)" fi ``` ```bash REPO_DIR="${REPO_SLUG}--${REPO_ID}" ``` #### Step 3: Generate session ID ```bash SESSION_ID="$(date -u '+%Y%m%d-%H%M%SZ')-$$-$(head -c2 /dev/urandom | od -An -tx1 | tr -d ' ')" ``` #### Step 4: Create session directory ```bash SESSION_DIR="$AIP_ROOT/repos/$REPO_DIR/sessions/brainstorm-and-refine/$SESSION_ID" ``` Create the session directory tree: ```bash mkdir -p -m 700 "$SESSION_DIR/brainstorm/outputs" "$SESSION_DIR/brainstorm/stderr" "$SESSION_DIR/refine/pass-0001/outputs" "$SESSION_DIR/refine/pass-0001/stderr" ``` #### Step 5: Write `repo.json` (if missing) If `$AIP_ROOT/repos/$REPO_DIR/repo.json` does not exist, write it with these contents: ```json { "schema_version": 1, "slug": "", "id": "", "toplevel": "", "origin": "" } ``` #### Step 6: Write `session.json` (atomic replace) Write to `$SESSION_DIR/session.json.tmp`, then `mv session.json.tmp session.json`: ```json { "schema_version": 1, "session_id": "", "command": "brainstorm-and-refine", "status": "in_progress", "phase": "brainstorm", "branch": "", "ref": "", "worker_backend": "", "participants": ["", "..."], "executors": {"": ""}, "judge_mode": "", "variants_per_model": , "pass_count": , "completed_passes": 0, "prompt_summary": "", "created_at": "", "updated_at": "" } ``` When `worker_backend == model-clis`, add a `"models"` array containing the resolved model for each participant. Omit `"models"` when `worker_backend == subagents`. #### Step 7: Append `events.jsonl` Append one event line to `$SESSION_DIR/events.jsonl`: ```json {"event":"session_start","timestamp":"","command":"brainstorm-and-refine","worker_backend":"","participants":["","..."],"variants_per_model":,"pass_count":} ``` #### Step 8: Write `metadata.md` Write to `$SESSION_DIR/metadata.md` containing: - Command name, start time, configured variant count and pass count - Worker backend, participant artifact IDs, and executor mapping - Resolved models only for `model-clis`, timeout setting when applicable, judge mode - Git branch (`git branch --show-current`), commit ref (`git rev-parse --short HEAD`) Store `$SESSION_DIR` for use in all subsequent phases. #### Step 8b: Repo Guard — Capture Fingerprint Capture the repository state before any model runs. See `docs/repo-guard-protocol.md` Layer 2 for the full protocol. ```bash REPO_TOPLEVEL="$(git rev-parse --show-toplevel)" ``` ```bash REPO_HEAD="$(git -C "$REPO_TOPLEVEL" rev-parse HEAD)" ``` ```bash REPO_FINGERPRINT="$(git -C "$REPO_TOPLEVEL" status --porcelain)" ``` Write `$SESSION_DIR/repo-fingerprint.txt` containing the HEAD ref and status output. Store `$REPO_TOPLEVEL` for use in all subsequent phases. #### Step 9: Write Context Packet Write the Context Packet built in Phase 1b to `$SESSION_DIR/context-packet.md`. --- ## Phase 3: Brainstorm — Generate All Originals in Parallel **Goal**: Send the prompt to all available models simultaneously, with variant differentiation. ### Variant Preambles Each variant receives a distinct creative-direction preamble to prevent anchoring. There are no role preambles (no Maintainer/Skeptic/Builder) during brainstorming — brainstorming is about original thinking, not evaluation lenses. | Variant | Default Preamble | |---------|-----------------| | 1 | "Take the most conventional, well-established approach." | | 2 | "Take an unconventional or creative approach. Challenge the obvious solution." | | 3 | "Take a contrarian approach. Question the premise itself." | When `--preamble` is provided, it replaces the built-in preamble text for ALL variants. Variant numbering still differentiates — each variant receives the user preamble prefixed with "Variant N of M." ### Prompt Preparation For each variant, write a separate prompt file containing the fully rendered prompt for that variant. This ensures shell-safe CLI invocation via `$(cat ...)` and persists each variant's exact prompt as a session artifact. For each variant N (1 through `variant_count`), write `$SESSION_DIR/brainstorm/prompts/variant-.md` containing: - **Reasoning directive** (first line): `Think through the problem step-by-step and consider multiple angles before producing your final response.` - The variant preamble for variant N - The base user prompt (with flags stripped) - The context packet content Create the prompts directory: ```bash mkdir -p "$SESSION_DIR/brainstorm/prompts" ``` Also write `$SESSION_DIR/brainstorm/prompt.md` as a summary file listing: the base prompt, all variant preambles, and the context packet reference. ### Claude Variants (Task agents) For each Claude variant (1 through `variant_count`), launch a separate Task agent with `subagent_type: "general-purpose"`: **Prompt for each Claude variant agent**: > [Variant preamble for this variant number] > > Respond to the following prompt about this codebase. Read any relevant files to give a thorough, original response. Read CLAUDE.md/AGENTS.md for project conventions. > > Prompt: > > Read the context packet at `$SESSION_DIR/context-packet.md` for project context. > > Provide a clear, well-structured response. Cite specific files and line numbers where relevant. CRITICAL: Do NOT write, edit, create, or delete any files in the repository. Do NOT use Write, Edit, or Bash commands that modify repository files. All session artifacts are written to `$SESSION_DIR`, which is outside the repository. This is a READ-ONLY research task. Each Claude variant agent writes its output to `$SESSION_DIR/brainstorm/outputs/claude-v.md`. ### Antigravity Variants (sub-agents) For each Antigravity variant (1 through `variant_count`), launch a separate Task agent (`subagent_type: "general-purpose"`, `mode: "default"`) to execute the Antigravity (agy) model. Include in the agent prompt: the resolved backend command and timeout from Phase 2, the `$SESSION_DIR` path, the `$REPO_TOPLEVEL` path and `$REPO_FINGERPRINT` value for repo guard verification, the variant number, and the prompt with variant preamble and additional instructions: > [Variant preamble for this variant number] > > > > --- > Additional instructions: Read relevant files and AGENTS.md/CLAUDE.md for project conventions. Provide a clear, original response citing specific files where relevant. > CRITICAL: Do NOT write, edit, create, or delete any files. Do NOT use any file-writing or file-modification tools. This is a READ-ONLY research task. All output must go to stdout. Any file modifications will be automatically detected and reverted. The agent must: 1. Read the variant prompt from `$SESSION_DIR/brainstorm/prompts/variant-.md` 2. Run the resolved Antigravity command with output redirection. **Repo Guard**: `agy` has no native read-only mode (its print mode reads *and* writes), so isolate it in a disposable git worktree checked out at `HEAD` — agy reads the snapshot while any stray write lands in the throwaway worktree, never the main repo (see `docs/repo-guard-protocol.md` Layer 1). Because multiple variants can run concurrently, each variant's worktree path carries its variant number (`-v`) so parallel runs never share a worktree. The `gemini` and `agent` fallbacks keep their own native read-only modes. **Primary (`agy` CLI, disposable worktree)**: ```bash (AGY_RO_WT="${REPO_TOPLEVEL}-weave-agy-ro-v"; git -C "$REPO_TOPLEVEL" worktree remove --force "$AGY_RO_WT" 2>/dev/null; git -C "$REPO_TOPLEVEL" worktree add -q --detach "$AGY_RO_WT" HEAD && (cd "$AGY_RO_WT" && agy --model "Gemini 3.1 Pro (High)" --add-dir "$AGY_RO_WT" --dangerously-skip-permissions -p "$(cat "$SESSION_DIR/brainstorm/prompts/variant-.md")" "$SESSION_DIR/brainstorm/outputs/agy-v.md" 2>"$SESSION_DIR/brainstorm/stderr/agy-v.txt"); rc=$?; git -C "$REPO_TOPLEVEL" worktree remove --force "$AGY_RO_WT" 2>/dev/null; exit "$rc") ``` **Fallback (`gemini` CLI)**: ```bash (cd "$SESSION_DIR" && gemini -m gemini-3-pro-preview --approval-mode plan --include-directories "$REPO_TOPLEVEL" --skip-trust -p "$(cat "$SESSION_DIR/brainstorm/prompts/variant-.md")" >"$SESSION_DIR/brainstorm/outputs/agy-v.md" 2>"$SESSION_DIR/brainstorm/stderr/agy-v.txt") ``` **Fallback (`agent` CLI)**: ```bash (cd "$SESSION_DIR" && agent -p --mode plan --trust --workspace "$REPO_TOPLEVEL" --model gemini-3.1-pro "$(cat "$SESSION_DIR/brainstorm/prompts/variant-.md")" >"$SESSION_DIR/brainstorm/outputs/agy-v.md" 2>>"$SESSION_DIR/brainstorm/stderr/agy-v.txt") ``` 3. **Repo Guard**: After the CLI command completes, verify the repository was not modified: ```bash CURRENT_STATUS="$(git -C "$REPO_TOPLEVEL" status --porcelain)" ``` If `$CURRENT_STATUS` differs from `$REPO_FINGERPRINT`, revert the repository: ```bash git -C "$REPO_TOPLEVEL" checkout -- . ``` ```bash git -C "$REPO_TOPLEVEL" clean -fd ``` Log the violation: ```bash printf '{"event":"repo_guard_violation","timestamp":"%s","model":"agy","reverted":true}\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" >>"$SESSION_DIR/guard-events.jsonl" ``` 4. On failure: classify (timeout → retry with 1.5x timeout; rate-limit → retry after 10s; credit-exhausted → skip retry, escalate to the next backend immediately; crash → not retryable; empty → retry once), retry max once with same backend, then fall back down the chain (agy → gemini → agent) if a native CLI was used; if all are credit-exhausted or unavailable, use the lesser model (`Gemini 3.5 Flash (High)` via agy for Antigravity; gpt-5.4-mini via agent for GPT) 5. Return: exit code, elapsed time, retry count, output file path ### GPT Variants (sub-agents) For each GPT variant (1 through `variant_count`), launch a separate Task agent (`subagent_type: "general-purpose"`, `mode: "default"`) to execute the GPT model. Include in the agent prompt: the resolved backend command and timeout from Phase 2, the `$SESSION_DIR` path, the `$REPO_TOPLEVEL` path and `$REPO_FINGERPRINT` value for repo guard verification, the variant number, and the prompt with variant preamble and additional instructions: > [Variant preamble for this variant number] > > > > --- > Additional instructions: Read relevant files and AGENTS.md/CLAUDE.md for project conventions. Provide a clear, original response citing specific files where relevant. > CRITICAL: Do NOT write, edit, create, or delete any files. Do NOT use any file-writing or file-modification tools. This is a READ-ONLY research task. All output must go to stdout. Any file modifications will be automatically detected and reverted. The agent must: 1. Read the variant prompt from `$SESSION_DIR/brainstorm/prompts/variant-.md` 2. Run the resolved GPT command with output redirection. **Repo Guard**: invoke the CLI in its native read-only sandbox — it reads the repo but cannot write it (see `docs/repo-guard-protocol.md` Layer 1): **Native (`codex` CLI)**: ```bash (cd "$SESSION_DIR" && codex exec -s read-only -C "$REPO_TOPLEVEL" --skip-git-repo-check .md")" >"$SESSION_DIR/brainstorm/outputs/gpt-v.md" 2>"$SESSION_DIR/brainstorm/stderr/gpt-v.txt") ``` **Fallback (`agent` CLI)**: ```bash (cd "$SESSION_DIR" && agent -p --mode plan --trust --workspace "$REPO_TOPLEVEL" --model gpt-5.4-high "$(cat "$SESSION_DIR/brainstorm/prompts/variant-.md")" >"$SESSION_DIR/brainstorm/outputs/gpt-v.md" 2>>"$SESSION_DIR/brainstorm/stderr/gpt-v.txt") ``` 3. **Repo Guard**: After the CLI command completes, verify the repository was not modified: ```bash CURRENT_STATUS="$(git -C "$REPO_TOPLEVEL" status --porcelain)" ``` If `$CURRENT_STATUS` differs from `$REPO_FINGERPRINT`, revert the repository: ```bash git -C "$REPO_TOPLEVEL" checkout -- . ``` ```bash git -C "$REPO_TOPLEVEL" clean -fd ``` Log the violation: ```bash printf '{"event":"repo_guard_violation","timestamp":"%s","model":"gpt","reverted":true}\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" >>"$SESSION_DIR/guard-events.jsonl" ``` 4. On failure: classify (timeout → retry with 1.5x timeout; rate-limit → retry after 10s; credit-exhausted → skip retry, escalate to agent CLI immediately; crash → not retryable; empty → retry once), retry max once with same backend, then fall back to agent CLI if native was used; if agent is also credit-exhausted or unavailable, use lesser model (`Gemini 3.5 Flash (High)` via agy for Antigravity; gpt-5.4-mini via agent for GPT) 5. Return: exit code, elapsed time, retry count, output file path ### Artifact Capture After each model variant completes, persist its output to the session directory: - **Claude variants**: Written by each Claude Task agent to `$SESSION_DIR/brainstorm/outputs/claude-v.md` - **Antigravity variants**: Written by each Antigravity sub-agent to `$SESSION_DIR/brainstorm/outputs/agy-v.md` - **GPT variants**: Written by each GPT sub-agent to `$SESSION_DIR/brainstorm/outputs/gpt-v.md` ### Execution Strategy - Launch ALL model x variant agents in the same turn to execute simultaneously. If parallel dispatch is unavailable, launch sequentially — the presentation phase handles partial results. - Each variant MUST be a separate, independent prompt invocation. Never send multiple variants to the same model in a single prompt — this prevents anchoring. - Each sub-agent handles its own retry and fallback protocol internally (see steps 3-4 in each agent's instructions above). - After all agents return, verify output files exist in `$SESSION_DIR/brainstorm/outputs/`. - If a sub-agent reports failure after exhausting retries, mark that model variant as unavailable and include failure details in the report. - Never block the entire workflow on a single model variant failure. --- ## Phase 4: Present Brainstorm Results and Transition Gate **Goal**: Display all brainstorm originals, then let the user select which ones enter refinement. ### Step 1: Present All Originals Read each output file from `$SESSION_DIR/brainstorm/outputs/` and present them. When `variant_count` is 1, omit the variant label from output headers. Use just the model name (e.g., "Claude", not "Claude — Variant 1"). **Format for variants=1**: ```markdown # Brainstorm Results **Prompt**: **Models**: Claude, Antigravity, GPT --- ## Claude ## Antigravity ## GPT ``` **Format for variants > 1**: ```markdown # Brainstorm Results **Prompt**: **Models**: Claude, Antigravity, GPT | **Variants per model**: N --- ## Claude — Variant 1 (Conventional) ## Claude — Variant 2 (Creative) ## Antigravity — Variant 1 (Conventional) ## Antigravity — Variant 2 (Creative) ## GPT — Variant 1 (Conventional) ## GPT — Variant 2 (Creative) ``` The variant label in parentheses matches the preamble direction: - Variant 1: (Conventional) - Variant 2: (Creative) - Variant 3: (Contrarian) When `--preamble` was used, omit the parenthetical label since the user provided a custom preamble. Use just "Variant 1", "Variant 2", "Variant 3". If a model variant failed or was unavailable, include a note in place of its response. ### Step 2: Transition Gate After presenting the brainstorm results, **always** ask the user which originals should enter refinement using `ask-user-choice`: - question: "Which brainstorm originals should enter the refinement phase?" - header: "Refine" - options: - "All of them (Recommended)" — All successful originals enter refinement as candidates. - "Let me pick specific ones" — Presents a follow-up multi-select question listing each original by label (e.g., "Claude-v1", "Antigravity-v2"). The user selects which ones to include. - "None — satisfied with brainstorm results" — Exit early. Skip refinement entirely. If the user selects "Let me pick specific ones", present a follow-up `ask-user-choice` with `multiSelect: true`: - question: "Select which originals to refine:" - header: "Originals" - options: One option per successful model variant (e.g., "Claude — Variant 1", "Antigravity — Variant 2") If the user selects "None", finalize the session immediately: 1. Update `session.json` via atomic replace: set `status` to `"completed"`, `phase` to `"brainstorm_only"`, `updated_at` to now. 2. Append events to `events.jsonl`: ```json {"event":"brainstorm_to_refine","timestamp":"","selected_originals":[],"total_available":} ``` ```json {"event":"session_complete","timestamp":"","command":"brainstorm-and-refine","brainstorm_originals":,"selected_for_refine":0,"completed_passes":0,"converged":false} ``` 3. Update `latest` symlink: ```bash ln -sfn "$SESSION_ID" "$AIP_ROOT/repos/$REPO_DIR/sessions/brainstorm-and-refine/latest" ``` Then stop — do not proceed to Phase 5 or beyond. If the user selects originals (either "All" or specific ones), append a `transition` event to `events.jsonl`: ```json {"event":"brainstorm_to_refine","timestamp":"","selected_originals":["claude-v1","agy-v2","..."],"total_available":} ``` Update `session.json` via atomic replace: set `phase` to `"refine"`, `updated_at` to now. --- ## Phase 5: Refine — Initial Judge and Weave **Goal**: Judge the selected brainstorm originals as the initial pool, weave the best, and begin the refinement cycle. ### Step 1: Judge the Brainstorm Originals **Determine this pass's judge.** If `judge_mode` is `"host"`, Claude judges. If `"round-robin"`, build a rotation array from available models starting with Claude: `[claude, agy, gpt]` (skipping any model not detected in Phase 2 Step 3). The judge for pass N is `rotation[(N - 1) % len(rotation)]`. Since Claude is always index 0, Pass 1 is always judged by Claude — this is intentional because brainstorm originals have varied structure where Claude's flexible parsing is most valuable. **Self-judging note**: In round-robin mode, the judge model is also a participant whose output is being judged. The host agent should cross-check the external judge's winner selection against its own reading of the outputs during the weave step. If the external judge selected its own output as winner and the host's assessment disagrees, the host may override the winner selection for weaving purposes. Record any override in `judge.md` with a note: `**Override**: Host overrode external judge's self-selection of — .` #### Host Judge Protocol (Claude judges) When the judge is Claude (host), the host agent reads all selected brainstorm originals and produces an assessment. **Read selected outputs** from `$SESSION_DIR/brainstorm/outputs/`. Only include the originals the user selected in the transition gate. **Score each original** on four dimensions, 0-10: | Dimension | Description | |-----------|-------------| | Quality | Writing quality, clarity, precision, technical accuracy | | Originality | Novel approaches, creative solutions, fresh perspectives | | Completeness | Covers all aspects, nothing important missing | | Coherence | Internal consistency, logical flow, well-structured | Compute the total score for each original (sum of four dimensions, max 40). **Pick the winner**: The original with the highest total score. In case of tie, prefer the original that is most comprehensive. **Write the judge's assessment** to `$SESSION_DIR/refine/pass-0001/judge.md`: ```markdown # Judge's Assessment — Pass 1 (from brainstorm originals) **Judged by**: Claude (host) ## Scores | Dimension | | | ... | |-----------|-----------|-----------|-----| | Quality (0-10) | X | X | ... | | Originality (0-10) | X | X | ... | | Completeness (0-10) | X | X | ... | | Coherence (0-10) | X | X | ... | | **Total** | XX | XX | ... | ## Winner **