dev v1.16.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.15.4"
+      "version": "1.16.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.15.4",
+  "version": "1.16.0",
   "author": {
     "name": "PolyArch"
   },

.claude/CLAUDE.md

@@ -3,7 +3,7 @@ This is a Claude Code plugin that provides iterative development with Codex revi
 
 # Humanize Project Rules
 - Everything about this project, including but not limited to implementations, comments, tests and documentations should be in English. No Emoji or CJK char is allowed.
-- If under `main` branch, every commit MUST include a version bump in `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` and `README.md` (the "Current Version" line). If not under `main` branch, please make sure that the current branch's `version` in those three files has a incremental update compared to that of `main` branch. The `version` must be identical in those three files.
+- If version bump is required, please bump them in three files: `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` and `README.md` (the "Current Version" line).
 - 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`.

.gitignore

@@ -3,9 +3,12 @@ temp
 
 # Local Claude client settings
 /.claude/settings.json
+/.claude/scheduled_tasks.lock
 
 # Humanize state directories (runtime-generated, project-local)
 .humanize/
+.claude-flow/
+.swarm/
 
 # Python cache
 __pycache__/

README.md

@@ -1,6 +1,6 @@
 # Humanize
 
-**Current Version: 1.15.4**
+**Current Version: 1.16.0**
 
 > Derived from the [GAAC (GitHub-as-a-Context)](https://github.com/SihaoLiu/gaac) project.
 
@@ -25,6 +25,7 @@ A Claude Code plugin that provides iterative development with independent AI rev
 
 The loop has two phases: **Implementation** (Claude works, Codex reviews summaries) and **Code Review** (Codex checks code quality with severity markers). Issues feed back into implementation until resolved.
 
+
 ## Install
 
 ```bash
@@ -40,25 +41,39 @@ Requires [codex CLI](https://github.com/openai/codex) for review. See the full [
 
 ## Quick Start
 
-1. **Generate a plan** from your draft:
+1. **Generate an idea draft** from a loose thought (optional — skip if you already have a draft):
+   ```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).
+
+2. **Generate a plan** from your draft:
    ```bash
    /humanize:gen-plan --input draft.md --output docs/plan.md
    ```
 
-2. **Refine an annotated plan** before implementation when reviewers add `CMT:` ... `ENDCMT` comments:
+3. **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
    ```
 
-3. **Run the loop**:
+4. **Run the loop**:
    ```bash
    /humanize:start-rlcr-loop docs/plan.md
    ```
 
-4. **Monitor progress**:
+5. **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)**:
    ```bash
-   source <path/to/humanize>/scripts/humanize.sh
-   humanize monitor rlcr
+   source <path/to/humanize>/scripts/humanize.sh # Or just add it into your .bashec or .zshrc
+   humanize monitor rlcr       # RLCR loop
+   humanize monitor skill      # All skill invocations (codex + gemini)
+   humanize monitor codex      # Codex invocations only
+   humanize monitor gemini     # Gemini invocations only
    ```
 
 ## Monitor Dashboard

commands/cancel-rlcr-loop.md

@@ -17,6 +17,7 @@ To cancel the active loop:
 2. Check the first line of output:
    - **NO_LOOP** or **NO_ACTIVE_LOOP**: Say "No active RLCR loop found."
    - **CANCELLED**: Report the cancellation message from the output
+   - **CANCELLED_METHODOLOGY_ANALYSIS**: Report the cancellation message from the output
    - **CANCELLED_FINALIZE**: Report the cancellation message from the output
    - **FINALIZE_NEEDS_CONFIRM**: The loop is in Finalize Phase. Continue to step 3
 
@@ -33,6 +34,6 @@ To cancel the active loop:
    - **If user chooses "No, let it finish"**:
      - Report: "Understood. The Finalize Phase will continue. Once complete, the loop will end normally."
 
-**Key principle**: The script handles all cancellation logic. A loop is active if `state.md` (normal loop) or `finalize-state.md` (Finalize Phase) exists in the newest loop directory.
+**Key principle**: The script handles all cancellation logic. A loop is active if `state.md` (normal loop), `methodology-analysis-state.md` (Methodology Analysis Phase), or `finalize-state.md` (Finalize Phase) exists in the newest loop directory.
 
 The loop directory with summaries, review results, and state information will be preserved for reference.

commands/gen-idea.md

@@ -0,0 +1,209 @@
+---
+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:
+```bash
+"${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 current repo. Gather OBJECTIVE EVIDENCE:
+> - Specific repo paths with existing patterns worth extending.
+> - Prior art or precedent in the codebase or adjacent tooling.
+> - Measurable considerations (approximate complexity, LOC surface, performance implications) where discoverable from reading the code.
+>
+> Read-only. Do not write any files.
+>
+> If no concrete evidence exists for this direction, report the literal string `exploratory, no concrete precedent` once in OBJECTIVE_EVIDENCE and stop exploring further. Fabrication of references is forbidden.
+>
+> Return a structured proposal with exactly these fields:
+> - `APPROACH_SUMMARY`: concrete design description (what to build, core mechanism, affected components).
+> - `OBJECTIVE_EVIDENCE`: bullet list of repo paths, prior art, or the `exploratory, no concrete precedent` sentinel.
+> - `KNOWN_RISKS`: short bullet list.
+> - `CONFIDENCE`: one of `high`, `medium`, `low`.
+
+### Collection and Degradation
+
+Collect all subagent responses. For each response:
+- Parse the four required fields. If a field is missing, mark that proposal as degraded and drop it.
+- If fewer than 2 proposals survive, stop with error: `exploration phase degraded; retry.`
+- Otherwise continue with the surviving proposals.
+
+Associate each surviving proposal with its originating direction (so Phase 4 can label it with the original direction name). When numbering alternatives in Phase 4 after any drops, renumber survivors sequentially as Alt-1..Alt-K (where K is the count of surviving non-primary directions). Do not preserve gaps from dropped proposals.
+
+---
+
+## Phase 4: Synthesis and Write
+
+### Step 4.1: Pick the Primary Direction
+
+Review all surviving proposals. Choose the strongest as the primary based on:
+1. Evidence density — more concrete repo references outranks fewer.
+2. Fit with existing repo patterns — extending patterns outranks introducing unfamiliar paradigms.
+3. Implementation surface area — prefer smaller surface where quality is otherwise comparable.
+4. Declared `CONFIDENCE` — `high` > `medium` > `low` as tiebreaker.
+
+Record the chosen direction as `PRIMARY`; the remaining surviving directions become the Alt-1..Alt-K list (where K is the number of non-primary survivors, K ≤ N-1), numbered sequentially in their original direction order with no gaps for any dropped proposals.
+
+### Step 4.2: Infer Title
+
+Generate a 4-10 word Title Case title that captures the primary direction, not the original input phrasing verbatim. Example: idea `add undo/redo` with primary direction `command-pattern history` yields title `Command-Pattern Undo Stack For The Editor`.
+
+### Step 4.3: Populate the Template
+
+Read the template file located at `TEMPLATE_FILE` (from Phase 1 stdout).
+
+Produce the finalized draft content in memory by replacing placeholders:
+- `<TITLE>` — the inferred title.
+- `<ORIGINAL_IDEA>` — byte-identical value of `IDEA_BODY` captured in Phase 1. Preserve line breaks, trailing newline, and all formatting. Do NOT paraphrase or re-indent.
+- `<PRIMARY_NAME>` — primary direction's short name.
+- `<PRIMARY_RATIONALE>` — primary direction's rationale (from Phase 2).
+- `<PRIMARY_APPROACH_SUMMARY>` — primary proposal's `APPROACH_SUMMARY`.
+- `<PRIMARY_OBJECTIVE_EVIDENCE>` — primary proposal's `OBJECTIVE_EVIDENCE`, rendered as a bullet list. If the subagent returned only the literal sentinel `exploratory, no concrete precedent`, render it as a single bullet: `- exploratory, no concrete precedent`.
+- `<PRIMARY_KNOWN_RISKS>` — primary proposal's `KNOWN_RISKS`, rendered as a bullet list.
+- `<ALTERNATIVES>` — for each non-primary survivor at its Alt index `i` (1-based, sequential per Step 4.1), emit:
+
+  ```markdown
+  ### Alt-<i>: <name>
+  - Gist: <one-paragraph summary derived from APPROACH_SUMMARY>
+  - Objective Evidence:
+    - <bullet from OBJECTIVE_EVIDENCE>
+    - ...
+  - Why not primary: <one sentence stating the tradeoff vs PRIMARY>
+  ```
+
+  Separate consecutive Alt entries with a single blank line.
+
+- `<SYNTHESIS_NOTES>` — one paragraph describing which elements from the alternatives could fold into the primary if the user chose a different direction. This is the lead's own synthesis note, not a subagent output.
+
+### Step 4.4: Write the Draft File
+
+Write the finalized content to `OUTPUT_FILE` using the `Write` tool. Single write; no progressive edits.
+
+### Step 4.5: Report
+
+Report to the user:
+- Path written (`OUTPUT_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>`.
+
+---
+
+## Error Handling
+
+- Phase 1 validation errors stop the command with a clear message. No partial output.
+- 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`.