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

.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
       "name": "humanize",
       "source": "./",
       "description": "Humanize - An iterative development plugin that uses Codex to review Claude's work. Creates a feedback loop where Claude implements plans and Codex independently reviews progress, ensuring quality through continuous refinement.",
-      "version": "1.16.0"
+      "version": "1.17.0"
     }
   ]
 }

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "humanize",
   "description": "Humanize - An iterative development plugin that uses Codex to review Claude's work. Creates a feedback loop where Claude implements plans and Codex independently reviews progress, ensuring quality through continuous refinement.",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "author": {
     "name": "PolyArch"
   },

.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 three places that must stay in sync: `commands/explore-idea.md` (coordinator phases), `prompt-template/explore/worker-prompt.md` (worker instructions), and `scripts/validate-explore-idea-io.sh` (cap enforcement). Any change to a cap value or constraint must be reflected in all three.

.gitignore

@@ -4,6 +4,7 @@ temp
 # Local Claude client settings
 /.claude/settings.json
 /.claude/scheduled_tasks.lock
+/.claude/worktrees/
 
 # Humanize state directories (runtime-generated, project-local)
 .humanize/
@@ -13,3 +14,6 @@ temp
 # Python cache
 __pycache__/
 *.pyc
+
+# Refactoring leftovers - use hooks/lib/ versions instead
+hooks/loop-codex-stop-hook-helpers.sh

README.md

@@ -1,6 +1,6 @@
 # Humanize
 
-**Current Version: 1.16.0**
+**Current Version: 1.17.0**
 
 > Derived from the [GAAC (GitHub-as-a-Context)](https://github.com/SihaoLiu/gaac) project.
 
@@ -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: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, synthesizes a two-tier report ranking the best product direction and the most implementation-ready prototype.
+
+3. **Generate a plan** from your draft:
    ```bash
    /humanize:gen-plan --input draft.md --output docs/plan.md
    ```
 
-3. **Refine an annotated plan** before implementation when reviewers add comments (`CMT:` ... `ENDCMT`, `<cmt>` ... `</cmt>`, or `<comment>` ... `</comment>`):
+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