Merge pull request #141 from Horacehxw/dev

feat(explore-idea): add explore-idea command + gen-idea directions.json companion (v1.17.0)

Author: SihaoLiu

.claude/CLAUDE.md

@@ -7,3 +7,5 @@ This is a Claude Code plugin that provides iterative development with Codex revi
 - Version number must be in format of `X.Y.Z` where X/Y/Z is numeric number. Version MUST NOT include anything other than `X.Y.Z`. For example, a good version is `9.732.42`; Bad version examples (MUST NOT USE): `3.22.7-alpha` (extra "-alpha" string), `9.77.2 (2026-01-07)` (useless date/timestamp).
 - The plan template in `commands/gen-plan.md` (Phase 5 Plan Structure section) and `prompt-template/plan/gen-plan-template.md` are intentionally kept in sync. When modifying either file, ensure both are updated to maintain consistency.
 - Conversely, changes to `prompt-template/plan/gen-plan-template.md` must also be reflected in the Plan Structure section of `commands/gen-plan.md`.
+- The directions.json schema v1 is defined in two places that must stay in sync: the jq validation expression in `scripts/validate-directions-json.sh` and the schema documentation in `commands/gen-idea.md` (Step 4.5). When adding, removing, or renaming a field in either place, update the other.
+- Worker constraints (hard caps, isolation rules, no-push rule, sentinel format) are documented in four places that must stay in sync: `commands/explore-idea.md` (coordinator phases), `prompt-template/explore/worker-prompt.md` (worker instructions), `scripts/validate-explore-idea-io.sh` (cap enforcement), and `docs/usage.md` (user-facing option docs). Any change to a cap value or constraint must be reflected in all four.

.gitignore

@@ -4,6 +4,7 @@ temp
 # Local Claude client settings
 /.claude/settings.json
 /.claude/scheduled_tasks.lock
+/.claude/worktrees/
 
 # Local Codex CLI marker (empty file occasionally left behind in worktree)
 /.codex

README.md

@@ -45,29 +45,35 @@ Requires [codex CLI](https://github.com/openai/codex) for review. See the full [
    ```bash
    /humanize:gen-idea "add undo/redo to the editor"
    ```
-   Output goes to `.humanize/ideas/<slug>-<timestamp>.md` by default. Pass a `.md` path to expand existing rough notes. `--n` controls how many parallel directions explore the idea (default 6).
+   Output goes to `.humanize/ideas/<slug>-<timestamp>.md` and a companion `directions.json` artifact. Pass a `.md` path to expand existing rough notes. `--n` controls how many parallel directions explore the idea (default 6).
 
-2. **Generate a plan** from your draft:
+2. **Explore directions as parallel prototypes** (optional — skip if you want to go straight to planning):
    ```bash
-   /humanize:gen-plan --input draft.md --output docs/plan.md
+   /humanize:explore-idea .humanize/ideas/<slug>-<timestamp>.directions.json
    ```
+   Dispatches bounded parallel prototype workers (one per direction), each running in an isolated git worktree. After all workers complete, writes `.humanize/explore/<run-id>/explore-report.md` for audit/ranking details and `.humanize/explore/<run-id>/final-idea.md` as the plan-ready synthesis. Worker worktrees are optional prototype fast paths; the default follow-up is to generate a clean plan from `final-idea.md`.
 
-3. **Refine an annotated plan** before implementation when reviewers add comments (`CMT:` ... `ENDCMT`, `<cmt>` ... `</cmt>`, or `<comment>` ... `</comment>`):
+3. **Generate a plan** from your draft or explored final idea:
+   ```bash
+   /humanize:gen-plan --input .humanize/explore/<run-id>/final-idea.md --output docs/plan.md
+   ```
+
+4. **Refine an annotated plan** before implementation when reviewers add comments (`CMT:` ... `ENDCMT`, `<cmt>` ... `</cmt>`, or `<comment>` ... `</comment>`):
    ```bash
    /humanize:refine-plan --input docs/plan.md
    ```
 
-4. **Run the loop**:
+5. **Run the loop**:
    ```bash
    /humanize:start-rlcr-loop docs/plan.md
    ```
 
-5. **Consult Gemini** for deep web research (requires Gemini CLI):
+6. **Consult Gemini** for deep web research (requires Gemini CLI):
    ```bash
    /humanize:ask-gemini What are the latest best practices for X?
    ```
 
-6. **Monitor progress (in another terminal, not inside Claude Code)**:
+7. **Monitor progress (in another terminal, not inside Claude Code)**:
    ```bash
    source <path/to/humanize>/scripts/humanize.sh # Or just add it into your .bashec or .zshrc
    humanize monitor rlcr       # RLCR loop

commands/explore-idea.md

@@ -3,6 +3,8 @@ 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:*)"
+  - "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/validate-directions-json.sh:*)"
+  - "Bash(rm:*)"
   - "Read"
   - "Glob"
   - "Grep"
@@ -16,7 +18,7 @@ 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 MUST NOT implement features, modify source code, or create commits while producing the draft. Permitted writes are limited to the output draft file and its companion `directions.json` artifact produced in Phase 4; prerequisite directory creation for the default `.humanize/ideas/` path by the validation script is permitted. `rm` is permitted solely to delete those two just-written files when companion JSON validation fails (no-partial-output cleanup). 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.
 
@@ -28,7 +30,7 @@ This command transforms a loose idea into a repo-grounded draft suitable as inpu
 2. IO Validation
 3. Direction Generation
 4. Parallel Exploration
-5. Synthesis and Write
+5. Synthesis, Write Draft, and Write Companion JSON
 
 ---
 
@@ -51,14 +53,15 @@ Run:
 ```
 
 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.)
+- `0`: Parse stdout to extract `INPUT_MODE`, `OUTPUT_FILE`, `DIRECTIONS_JSON_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.
+- `6`: Report "Invalid arguments — output path must have `.md` suffix" with the stdout usage text and stop.
 - `7`: Report "Template file missing — plugin configuration error" and stop.
+- `8`: Report "Companion directions.json already exists — choose a different output path or remove the existing companion file" 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.
 
@@ -190,13 +193,73 @@ Produce the finalized draft content in memory by replacing placeholders:
 
 Write the finalized content to `OUTPUT_FILE` using the `Write` tool. Single write; no progressive edits.
 
-### Step 4.5: Report
+### Step 4.5: Build and Write Companion JSON
+
+Construct the companion `directions.json` in memory using all surviving direction proposals from Phase 3, then write it to `DIRECTIONS_JSON_FILE` (from Phase 1 stdout).
+
+**JSON structure (schema version 1):**
+
+```json
+{
+  "schema_version": 1,
+  "title": "<TITLE from Step 4.2>",
+  "original_idea": "<IDEA_BODY verbatim>",
+  "synthesis_notes": "<SYNTHESIS_NOTES from Step 4.3>",
+  "metadata": {
+    "n_requested": <N>,
+    "n_returned": <count of surviving directions>,
+    "timestamp": "<YYYYMMDD-HHmmss>",
+    "draft_path": "<OUTPUT_FILE>"
+  },
+  "directions": [
+    {
+      "direction_id": "dir-<NN>-<dir-slug>",
+      "dir_slug": "<lowercase-alphanumeric-hyphen slug derived from direction name>",
+      "source_index": <original 0-based index from DIRECTIONS list>,
+      "display_order": <0 for primary, 1..K for alternatives in sequential order>,
+      "is_primary": <true for PRIMARY, false otherwise>,
+      "name": "<direction name>",
+      "rationale": "<direction rationale from Phase 2>",
+      "raw_phase3_response": "<exact raw subagent response text for this direction>",
+      "approach_summary": "<APPROACH_SUMMARY from subagent>",
+      "objective_evidence": ["<bullet item>", ...],
+      "known_risks": ["<bullet item>", ...],
+      "confidence": "<high|medium|low>"
+    }
+  ]
+}
+```
+
+**Field derivation rules:**
+- `direction_id`: `"dir-" + zero-padded source_index (2 digits) + "-" + dir_slug`. Example: `"dir-00-command-history"`.
+- `dir_slug`: Derived from direction name — lowercase, replace non-alphanumeric with hyphens, collapse consecutive hyphens, strip leading/trailing hyphens. Must match `^[a-z0-9-]+$`.
+- `dir_slug` collision handling: if two direction names slugify to the same value, append `-2`, `-3`, etc. by original `source_index` order until every `dir_slug` is unique.
+- `source_index`: The 0-based index of this direction in the original `DIRECTIONS` list from Phase 2 (before any degradation drops).
+- `display_order`: 0 for the primary direction, 1 through K for alternatives in their sequential order.
+- `is_primary`: `true` for exactly one direction (PRIMARY), `false` for all others.
+- `objective_evidence`: Each bullet item from the subagent's `OBJECTIVE_EVIDENCE` field as a string array element.
+- `known_risks`: Each bullet item from the subagent's `KNOWN_RISKS` field as a string array element.
+- `metadata.n_returned` must equal `directions.length`.
+
+After writing `DIRECTIONS_JSON_FILE`, validate it:
+```bash
+"${CLAUDE_PLUGIN_ROOT}/scripts/validate-directions-json.sh" "$DIRECTIONS_JSON_FILE"
+```
+
+If validation fails, delete both `OUTPUT_FILE` and `DIRECTIONS_JSON_FILE` and stop with error: `companion JSON validation failed — this is a bug in the command; please report it`.
+
+### Step 4.6: Report
 
 Report to the user:
-- Path written (`OUTPUT_FILE`).
+- Draft path written: `OUTPUT_FILE`
+- Companion JSON path written: `DIRECTIONS_JSON_FILE`
 - Primary direction name.
 - Requested `N` and the actual direction count (note if reduced due to degradation).
-- Next-step hint: `To turn this draft into a plan, run: /humanize:gen-plan --input <OUTPUT_FILE> --output <plan-path>`.
+- Next-step hints:
+  ```
+  To explore directions as parallel prototypes, run: /humanize:explore-idea <DIRECTIONS_JSON_FILE>
+  To turn this draft into a plan, run: /humanize:gen-plan --input <OUTPUT_FILE> --output <plan-path>
+  ```
 
 ---
 
@@ -206,4 +269,5 @@ Report to the user:
 - Phase 2 degradation follows the retry-once + ≥2 minimum rule stated above.
 - Phase 3 degradation follows the drop-and-continue + ≥2 minimum rule stated above.
 - Never fabricate repo references or prior art. The `exploratory, no concrete precedent` sentinel from subagents is preserved verbatim in the draft.
-- If any phase stops with an error, do not write a partial `OUTPUT_FILE`.
+- If any phase stops with an error, do not write a partial `OUTPUT_FILE` or `DIRECTIONS_JSON_FILE`.
+- If companion JSON validation fails after writing both files, delete both files and stop.

commands/gen-idea.md

@@ -1,6 +1,6 @@
 ---
 description: "Start iterative loop with Codex review"
-argument-hint: "[path/to/plan.md | --plan-file path/to/plan.md] [--max N] [--codex-model MODEL:EFFORT] [--codex-timeout SECONDS] [--track-plan-file] [--push-every-round] [--base-branch BRANCH] [--full-review-round N] [--skip-impl] [--claude-answer-codex] [--agent-teams] [--yolo] [--skip-quiz] [--privacy]"
+argument-hint: "[path/to/plan.md | --plan-file path/to/plan.md] [--max N] [--codex-model MODEL:EFFORT] [--codex-timeout SECONDS] [--track-plan-file] [--push-every-round] [--base-branch BRANCH] [--full-review-round N] [--skip-impl] [--claude-answer-codex] [--agent-teams] [--yolo] [--skip-quiz] [--privacy] [--no-privacy]"
 allowed-tools:
   - "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/setup-rlcr-loop.sh:*)"
   - "Read"

commands/start-rlcr-loop.md

@@ -53,6 +53,10 @@ cp -r skills/humanize-gen-plan ~/.config/agents/skills/
 cp -r skills/humanize-refine-plan ~/.config/agents/skills/
 cp -r skills/humanize-rlcr ~/.config/agents/skills/
 
+# Kimi does not use Codex native Stop hooks, so install the gate-based
+# RLCR entrypoint used by scripts/install-skill.sh --target kimi.
+cp skills/humanize-rlcr/SKILL-kimi.md ~/.config/agents/skills/humanize-rlcr/SKILL.md
+
 # Copy runtime dependencies used by the skills
 # (must match install-skill.sh's install_runtime_bundle)
 cp -r scripts ~/.config/agents/skills/humanize/

docs/install-for-kimi.md

@@ -59,6 +59,8 @@ The quiz is advisory, not a gate. You always have the option to proceed. But tha
 
 | Command | Purpose |
 |---------|---------|
+| `/gen-idea <idea-or-path>` | Generate a repo-grounded idea draft with N parallel directions |
+| `/explore-idea <draft-or-directions.json>` | Launch bounded parallel prototype workers and synthesize a two-tier report |
 | `/start-rlcr-loop <plan.md>` | Start iterative development with Codex review |
 | `/cancel-rlcr-loop` | Cancel active loop |
 | `/gen-plan --input <draft.md> --output <plan.md>` | Generate structured plan from draft |
@@ -67,6 +69,52 @@ The quiz is advisory, not a gate. You always have the option to proceed. But tha
 
 ## Command Reference
 
+### gen-idea
+
+```
+/humanize:gen-idea <idea-text-or-path> [--n <int>] [--output <path>]
+```
+
+Generates a repo-grounded idea draft using directed-diversity exploration. A lead agent picks N orthogonal directions, N parallel Explore subagents develop each direction with objective evidence from the repo, and the lead synthesizes a draft with one primary direction plus N-1 alternatives.
+
+**Outputs:**
+- Draft file: `.humanize/ideas/<slug>-<timestamp>.md` (or `--output` path)
+- Companion JSON: `<draft-path-without-.md>.directions.json` — lossless record of all direction proposals, used as input to `explore-idea`
+
+**Options:**
+- `--n <int>` — number of parallel directions (default: 6)
+- `--output <path>` — custom output path for the draft (must have `.md` suffix)
+
+### explore-idea
+
+```
+/humanize:explore-idea <draft.md | draft.directions.json> [--directions ids] [--concurrency N] [--max-worker-iterations N] [--worker-timeout-min N] [--codex-timeout-min N]
+```
+
+Launches bounded parallel prototype workers — one per selected direction — each running in an isolated git worktree. After all workers complete, synthesizes an explore report plus a plan-ready final idea:
+- **Tier 1**: Best product direction (ranked by user value, evidence, strategic fit)
+- **Tier 2**: Most implementation-ready prototype (ranked by outcome: task status, Codex verdict, tests, commits)
+
+**Options:**
+- `--directions <ids>` — comma-separated `direction_id` or `source_index` values to run (default: first 6 by display order)
+- `--concurrency <N>` — parallel worker count (default: 6, max: 10)
+- `--max-worker-iterations <N>` — per-worker iteration cap (default: 2, max: 3)
+- `--worker-timeout-min <N>` — worker timeout in minutes (default: 60, max: 60)
+- `--codex-timeout-min <N>` — Codex call timeout in minutes (default: 20, max: 20)
+
+**Run artifacts** stored in `.humanize/explore/<RUN_ID>/`:
+- `manifest.json` — coordinator state and per-worker metadata
+- `dispatch-prompts/` — exact prompts sent to each worker
+- `worker-results.jsonl` — machine-readable result rows
+- `explore-report.md` — audit report with two-tier rankings, adoption paths, and cleanup guidance
+- `final-idea.md` — plan-ready synthesis artifact for `/humanize:gen-plan`
+
+Default follow-up:
+```bash
+/humanize:gen-plan --input .humanize/explore/<run-id>/final-idea.md --output docs/plan.md
+/humanize:start-rlcr-loop docs/plan.md
+```
+
 ### start-rlcr-loop
 
 ```

docs/usage.md

@@ -355,7 +355,7 @@ handle_bg_task_short_circuit() {
         local guard_state_file guard_stored_sid
         guard_state_file=$(resolve_active_state_file "$loop_dir")
         if [[ -n "$guard_state_file" ]]; then
-            guard_stored_sid=$(sed -n '/^---$/,/^---$/{ /^'"${FIELD_SESSION_ID}"':/{ s/^'"${FIELD_SESSION_ID}"': *//; p; } }' "$guard_state_file" 2>/dev/null | tr -d ' ')
+            guard_stored_sid=$(awk -v key="${FIELD_SESSION_ID}" 'BEGIN{f=0} /^---$/{f++; next} f==1 && $0 ~ "^"key":"{sub("^"key":[[:space:]]*",""); print; exit}' "$guard_state_file" 2>/dev/null | tr -d ' ') || true
             if [[ -n "$guard_stored_sid" ]] \
                && [[ -n "$hook_session_id" ]] \
                && [[ "$guard_stored_sid" != "$hook_session_id" ]]; then

hooks/lib/loop-bg-tasks.sh

@@ -379,7 +379,7 @@ find_active_loop() {
         fi
 
         local stored_session_id
-        stored_session_id=$(sed -n '/^---$/,/^---$/{ /^'"${FIELD_SESSION_ID}"':/{ s/'"${FIELD_SESSION_ID}"': *//; p; } }' "$any_state" 2>/dev/null | tr -d ' ')
+        stored_session_id=$(awk -v key="${FIELD_SESSION_ID}" 'BEGIN{f=0} /^---$/{f++; next} f==1 && $0 ~ "^"key":"{sub("^"key":[[:space:]]*",""); print; exit}' "$any_state" 2>/dev/null | tr -d ' ')
 
         # Empty stored session_id matches any session (backward compat).
         if [[ -z "$stored_session_id" ]] || [[ "$stored_session_id" == "$filter_session_id" ]]; then
@@ -809,8 +809,8 @@ extract_round_number() {
     local filename_lower
     filename_lower=$(to_lower "$filename")
 
-    # Use sed for portable regex extraction (works in both bash and zsh)
-    echo "$filename_lower" | sed -n 's/.*round-\([0-9][0-9]*\)-\(summary\|prompt\|todos\|contract\)\.md$/\1/p'
+    # Use ERE (-E) so | alternation works on both GNU and BSD sed (macOS)
+    echo "$filename_lower" | sed -En 's/.*round-([0-9]+)-(summary|prompt|todos|contract)\.md$/\1/p'
 }
 
 # Check if a file is in the allowlist for the active loop
@@ -820,6 +820,11 @@ is_allowlisted_file() {
     local file_path="$1"
     local active_loop_dir="$2"
 
+    # Canonicalize both paths to resolve symlinks (e.g. /var -> /private/var on macOS).
+    local canonical_file canonical_loop
+    canonical_file=$(canonicalize_path "$file_path" 2>/dev/null || echo "$file_path")
+    canonical_loop=$(canonicalize_path "$active_loop_dir" 2>/dev/null || echo "$active_loop_dir")
+
     local allowlist=(
         "round-1-todos.md"
         "round-2-todos.md"
@@ -828,7 +833,7 @@ is_allowlisted_file() {
     )
 
     for allowed in "${allowlist[@]}"; do
-        if [[ "$file_path" == "$active_loop_dir/$allowed" ]]; then
+        if [[ "$canonical_file" == "$canonical_loop/$allowed" ]]; then
             return 0
         fi
     done
@@ -1522,7 +1527,7 @@ Use Write or Edit on: {{CORRECT_PATH}}
 
 Rules:
 - Keep the **IMMUTABLE SECTION** unchanged
-- Do not modify `goal-tracker.md` via Bash
+- Do not modify goal-tracker.md via Bash
 - Do not write to an old loop session's tracker"
 
     load_and_render_safe "$TEMPLATE_DIR" "block/goal-tracker-modification.md" "$fallback" \