/gen-idea

description: "Generate a repo-grounded idea draft via directed-swarm exploration"
argument-hint: "<idea-text-or-path> [--n <int>] [--output <path>]"
allowed-tools:
  - "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/validate-gen-idea-io.sh:*)"
  - "Read"
  - "Glob"
  - "Grep"
  - "Task"
  - "Write"

Generate Idea Draft from Loose Input

Read and execute below with ultrathink.

Hard Constraint: Draft-Only Output

This command MUST NOT implement features, modify source code, or create commits while producing the draft. Permitted writes are limited to the single output draft file produced in Phase 4; prerequisite directory creation for the default `.humanize/ideas/` path by the validation script is permitted as part of that write. All exploration subagents run read-only.

This command transforms a loose idea into a repo-grounded draft suitable as input to `/humanize:gen-plan`. It applies directed-diversity exploration: a lead picks N orthogonal directions, N parallel `Explore` subagents develop each, the lead synthesizes a draft with one primary direction plus N-1 alternatives. Each direction carries objective evidence from the repo.

Workflow Overview

> **Sequential Execution Constraint**: All phases MUST execute strictly in order. Each phase fully completes before the next.

1. Parse Input 2. IO Validation 3. Direction Generation 4. Parallel Exploration 5. Synthesis and Write

---

Phase 0: Parse Input

Extract from `$ARGUMENTS`:

• First positional: inline idea text or path to a `.md` file (required).
• `--n <int>`: number of directions. Default 6.
• `--output <path>`: target draft path. Default resolved by the validation script.

Do not interpret or rewrite the idea text here. Pass `$ARGUMENTS` through to Phase 1 unchanged.

---

Phase 1: IO Validation

Run:

"${CLAUDE_PLUGIN_ROOT}/scripts/validate-gen-idea-io.sh" $ARGUMENTS

Handle exit codes:

• `0`: Parse stdout to extract `INPUT_MODE`, `OUTPUT_FILE`, `SLUG`, `TEMPLATE_FILE`, `N` (each appears on its own `KEY: value` line). When `INPUT_MODE` is `file`, stdout additionally contains an `IDEA_BODY_FILE: <path>` line; extract that too. Continue to Phase 2. (`SLUG` is informational — the script has already incorporated it into `OUTPUT_FILE`, so later phases do not need to use `SLUG` directly.)
• `1`: Report "Missing or empty idea input" and stop.
• `2`: Report "Input looks like a file path but is missing, not readable, or not `.md`" and stop.
• `3`: Report "Output directory does not exist — please create it or choose a different path" and stop.
• `4`: Report "Output file already exists — choose a different path" and stop.
• `5`: Report "No write permission to output directory" and stop.
• `6`: Report "Invalid arguments" with the stdout usage text and stop.
• `7`: Report "Template file missing — plugin configuration error" and stop.

Before `VALIDATION_SUCCESS`, stdout may contain one or more lines starting with `WARNING:` (for example, `WARNING: short idea (<N> chars); proceeding` when an inline idea is under 10 characters). Surface these warnings to the user in your final report but continue Phase 2 normally. `WARNING:` lines are informational, not errors.

Obtain the idea body into memory as `IDEA_BODY`, based on `INPUT_MODE`:

• `inline`: stdout contains a sentinel block at the end of the success output; extract all text between the `=== IDEA_BODY_BEGIN ===` and `=== IDEA_BODY_END ===` lines (exclusive). The script emits a trailing newline after the last body line.
• `file`: read the full contents of `IDEA_BODY_FILE` using the `Read` tool.

Preserve byte-identical content in memory for later phases. No on-disk tempfile is created in inline mode — the stdout sentinel block is the authoritative source.

---

Phase 2: Direction Generation

Generate exactly `N` orthogonal directions for exploring the idea.

Context to Gather

Before generating directions, read (paths relative to the project root, which is `$(git rev-parse --show-toplevel)`):

• `README.md` at the project root.
• `CLAUDE.md` at the project root (if it exists).
• `.claude/CLAUDE.md` (if it exists).
• Top-level directory listing via `Glob` with pattern `*` (one level, no recursion).

This context grounds the directions in the actual repo rather than generic brainstorming.

Generation Rules

Produce exactly `N` direction entries. Each entry has:

• `name`: a 2-5 word short label.
• `rationale`: a single sentence explaining why this angle is distinct from the other directions.

Hard constraint: **orthogonality**. Two near-duplicate directions defeat the directed-diversity premise. Before returning:

• If two directions feel like dupes, replace one with a genuinely different angle.
• If a direction collapses to "just do X better" with no angle distinction, replace it.
• Do not emit directions that merely restate the idea in different words.

Retry and Degradation

• If the first pass returns fewer than `N` entries, regenerate once with an explicit "you MUST produce `N` orthogonal directions" instruction.
• If the second pass still returns fewer than `N` but at least 2, proceed with the reduced count and emit a warning to the user: `Warning: direction generation returned <count> of <N> requested directions; proceeding with reduced count.`
• If fewer than 2 directions are produced, stop with error: `direction generation degraded; retry.`

Store the final direction list as `DIRECTIONS` (ordered; index 0..len-1).

---

Phase 3: Parallel Exploration

Dispatch all directions in a **single Task-tool message** containing one Task invocation per direction. This is the W2S parallel-swarm step.

Subagent Invocation

For each direction in `DIRECTIONS`, launch one `Explore` subagent. Each invocation prompt MUST include:

1. A verbatim copy of the idea body (`IDEA_BODY`) captured in Phase 1. 2. The assigned direction (name + rationale). 3. The following instruction block (reproduce verbatim in the subagent prompt):

> Explore this direction within the cur