/gen-plan

description: "Generate implementation plan from draft document"
argument-hint: "--input <path/to/draft.md> --output <path/to/plan.md> [--auto-start-rlcr-if-converged] [--discussion|--direct]"
allowed-tools:
  - "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/validate-gen-plan-io.sh:*)"
  - "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/ask-codex.sh:*)"
  - "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/setup-rlcr-loop.sh:*)"
  - "Read"
  - "Glob"
  - "Grep"
  - "Task"
  - "Write"
  - "AskUserQuestion"

Generate Plan from Draft

Read and execute below with ultrathink.

Hard Constraint: No Coding During Plan Generation

This command MUST ONLY generate a plan document during the planning phases. It MUST NOT implement tasks, modify repository source code, or make commits/PRs while producing the plan.

Permitted writes (before any optional auto-start) are limited to:

• The plan output file (`--output`)
• Optional translated language variant (only when `ALT_PLAN_LANGUAGE` is configured)

If `--auto-start-rlcr-if-converged` is enabled, the command MAY immediately start the RLCR loop by running `/humanize:start-rlcr-loop <output-plan-path>`, but only in `discussion` mode when `PLAN_CONVERGENCE_STATUS=converged` and there are no pending user decisions. All coding happens in that subsequent command/loop, not during plan generation.

This command transforms a user's draft document into a well-structured implementation plan with clear goals, acceptance criteria (AC-X format), path boundaries, and feasibility suggestions.

Workflow Overview

> **Sequential Execution Constraint**: All phases below MUST execute strictly in order. Do NOT parallelize tool calls across different phases. Each phase must fully complete before the next one begins.

1. **Execution Mode Setup**: Parse optional behaviors from command arguments 2. **Load Project Config**: Resolve merged Humanize config defaults for `alternative_plan_language` and `gen_plan_mode` 3. **IO Validation**: Validate input and output paths 4. **Relevance Check**: Verify draft is relevant to the repository 5. **Codex First-Pass Analysis**: Use one planning Codex before Claude synthesizes plan details 6. **Claude Candidate Plan (v1)**: Claude builds an initial plan from draft + Codex findings 7. **Iterative Convergence Loop**: Claude and a second Codex iteratively challenge/refine plan reasonability 8. **Issue and Disagreement Resolution**: Resolve unresolved opposite opinions (or skip manual review if converged, auto-start mode is enabled, and `GEN_PLAN_MODE=discussion`) 9. **Final Plan Generation**: Generate the converged structured plan.md with task routing tags 10. **Write and Complete**: Write output file, optionally write translated language variant, optionally auto-start implementation, and report results

---

Phase 0: Execution Mode Setup

Parse `$ARGUMENTS` and set:

• `AUTO_START_RLCR_IF_CONVERGED=true` if `--auto-start-rlcr-if-converged` is present
• `AUTO_START_RLCR_IF_CONVERGED=false` otherwise
• `GEN_PLAN_MODE_DISCUSSION=true` if `--discussion` is present
• `GEN_PLAN_MODE_DIRECT=true` if `--direct` is present
• If both `--discussion` and `--direct` are present simultaneously, report error "Cannot use --discussion and --direct together" and stop

`AUTO_START_RLCR_IF_CONVERGED=true` allows skipping manual plan review and starting implementation immediately (by invoking `/humanize:start-rlcr-loop <output-plan-path>`), but only when `GEN_PLAN_MODE=discussion`, plan convergence is achieved, and no pending user decisions remain. In `direct` mode this condition is never satisfied.

---

Phase 0.5: Load Project Config

After setting execution mode flags, resolve configuration using `${CLAUDE_PLUGIN_ROOT}/scripts/lib/config-loader.sh`. Reuse that behavior; do not read `.humanize/config.json` directly.

Config Merge Semantics

1. Source `${CLAUDE_PLUGIN_ROOT}/scripts/lib/config-loader.sh`. 2. Call `load_merged_config "${CLAUDE_PLUGIN_ROOT}" "${PROJECT_ROOT}"` to obtain `MERGED_CONFIG_JSON`, where `PROJECT_ROOT` is the repository root where the command was invoked. 3. `load_merged_config` merges these layers in order:

• Required default config: `${CLAUDE_PLUGIN_ROOT}/config/default_config.json`
• Optional user config: `${XDG_CONFIG_HOME:-$HOME/.config}/humanize/config.json`
• Optional project config: `${HUMANIZE_CONFIG:-$PROJECT_ROOT/.humanize/config.json}`

4. Later layers override earlier layers. Malformed optional JSON objects are warnings and ignored. A malformed required default config, missing `jq`, or any other fatal `load_merged_config` failure is a configuration error and must stop the command.

Values to Extract

Use `get_config_value` against `MERGED_CONFIG_JSON` to read:

• `CONFIG_ALT_LANGUAGE_RAW` from `alternative_plan_language`
• `CONFIG_GEN_PLAN_MODE_RAW` from `gen_plan_mode`
• `CONFIG_CHINESE_PLAN_RAW` from `chinese_plan` (legacy fallback only)

Also detect whether `alternative_plan_language` is explicitly present in `MERGED_CONFIG_JSON` so an empty string still counts as an explicit override:

• `HAS_ALT_LANGUAGE_KEY=true` when `MERGED_CONFIG_JSON` contains the `alternative_plan_language` key
• `HAS_ALT_LANGUAGE_KEY=false` otherwise

Alternative Language Resolution

1. Resolve the effective `alternative_plan_language` value with this priority:

• Merged config `alternative_plan_language`, when `HAS_ALT_LANGUAGE_KEY=true` (even if the value is an empty string)
• Deprecated merged config `chinese_plan`, only when `HAS_ALT_LANGUAGE_KEY=false`
• Default disabled state

2. Backward compatibility for deprecated `chinese_plan`:

• If `HAS_ALT_LANGUAGE_KEY=true` and `CONFIG_CHINESE_PLAN_RAW` is `true`, log: `Warning: deprecated "chinese_plan" field ignored; "alternative_plan_language" takes precedence. Remove "chinese_plan" from your humanize config.`
• If `HAS_ALT_LANGUAGE_KEY=false` and `CONFIG_CHINESE_PLAN_RAW` is `true`, treat the effective `alternative_plan_language` as `"Chinese"`. Log: `Warning: deprecated "chinese