Skip to content

Commit 13cd25e

Browse files
SihaoLiuSihaoLiu
committed
Merge branch 'dev' into beta
2 parents 9d8aa7b + 179a87c commit 13cd25e

4 files changed

Lines changed: 454 additions & 5 deletions

File tree

‎README.md‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -41,27 +41,33 @@ Requires [codex CLI](https://github.com/openai/codex) for review. See the full [
4141

4242
## Quick Start
4343

44-
1. **Generate a plan** from your draft:
44+
1. **Generate an idea draft** from a loose thought (optional — skip if you already have a draft):
45+
```bash
46+
/humanize:gen-idea "add undo/redo to the editor"
47+
```
48+
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).
49+
50+
2. **Generate a plan** from your draft:
4551
```bash
4652
/humanize:gen-plan --input draft.md --output docs/plan.md
4753
```
4854

49-
2. **Refine an annotated plan** before implementation when reviewers add comments (`CMT:` ... `ENDCMT`, `<cmt>` ... `</cmt>`, or `<comment>` ... `</comment>`):
55+
3. **Refine an annotated plan** before implementation when reviewers add comments (`CMT:` ... `ENDCMT`, `<cmt>` ... `</cmt>`, or `<comment>` ... `</comment>`):
5056
```bash
5157
/humanize:refine-plan --input docs/plan.md
5258
```
5359

54-
3. **Run the loop**:
60+
4. **Run the loop**:
5561
```bash
5662
/humanize:start-rlcr-loop docs/plan.md
5763
```
5864

59-
4. **Consult Gemini** for deep web research (requires Gemini CLI):
65+
5. **Consult Gemini** for deep web research (requires Gemini CLI):
6066
```bash
6167
/humanize:ask-gemini What are the latest best practices for X?
6268
```
6369

64-
5. **Monitor progress (in another terminal, not inside Claude Code)**:
70+
6. **Monitor progress (in another terminal, not inside Claude Code)**:
6571
```bash
6672
source <path/to/humanize>/scripts/humanize.sh # Or just add it into your .bashec or .zshrc
6773
humanize monitor rlcr # RLCR loop

‎commands/gen-idea.md‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
---
2+
description: "Generate a repo-grounded idea draft via directed-swarm exploration"
3+
argument-hint: "<idea-text-or-path> [--n <int>] [--output <path>]"
4+
allowed-tools:
5+
- "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/validate-gen-idea-io.sh:*)"
6+
- "Read"
7+
- "Glob"
8+
- "Grep"
9+
- "Task"
10+
- "Write"
11+
---
12+
13+
# Generate Idea Draft from Loose Input
14+
15+
Read and execute below with ultrathink.
16+
17+
## Hard Constraint: Draft-Only Output
18+
19+
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.
20+
21+
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.
22+
23+
## Workflow Overview
24+
25+
> **Sequential Execution Constraint**: All phases MUST execute strictly in order. Each phase fully completes before the next.
26+
27+
1. Parse Input
28+
2. IO Validation
29+
3. Direction Generation
30+
4. Parallel Exploration
31+
5. Synthesis and Write
32+
33+
---
34+
35+
## Phase 0: Parse Input
36+
37+
Extract from `$ARGUMENTS`:
38+
- First positional: inline idea text or path to a `.md` file (required).
39+
- `--n <int>`: number of directions. Default 6.
40+
- `--output <path>`: target draft path. Default resolved by the validation script.
41+
42+
Do not interpret or rewrite the idea text here. Pass `$ARGUMENTS` through to Phase 1 unchanged.
43+
44+
---
45+
46+
## Phase 1: IO Validation
47+
48+
Run:
49+
```bash
50+
"${CLAUDE_PLUGIN_ROOT}/scripts/validate-gen-idea-io.sh" $ARGUMENTS
51+
```
52+
53+
Handle exit codes:
54+
- `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.)
55+
- `1`: Report "Missing or empty idea input" and stop.
56+
- `2`: Report "Input looks like a file path but is missing, not readable, or not `.md`" and stop.
57+
- `3`: Report "Output directory does not exist — please create it or choose a different path" and stop.
58+
- `4`: Report "Output file already exists — choose a different path" and stop.
59+
- `5`: Report "No write permission to output directory" and stop.
60+
- `6`: Report "Invalid arguments" with the stdout usage text and stop.
61+
- `7`: Report "Template file missing — plugin configuration error" and stop.
62+
63+
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.
64+
65+
Obtain the idea body into memory as `IDEA_BODY`, based on `INPUT_MODE`:
66+
- `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.
67+
- `file`: read the full contents of `IDEA_BODY_FILE` using the `Read` tool.
68+
69+
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.
70+
71+
---
72+
73+
## Phase 2: Direction Generation
74+
75+
Generate exactly `N` orthogonal directions for exploring the idea.
76+
77+
### Context to Gather
78+
79+
Before generating directions, read (paths relative to the project root, which is `$(git rev-parse --show-toplevel)`):
80+
- `README.md` at the project root.
81+
- `CLAUDE.md` at the project root (if it exists).
82+
- `.claude/CLAUDE.md` (if it exists).
83+
- Top-level directory listing via `Glob` with pattern `*` (one level, no recursion).
84+
85+
This context grounds the directions in the actual repo rather than generic brainstorming.
86+
87+
### Generation Rules
88+
89+
Produce exactly `N` direction entries. Each entry has:
90+
- `name`: a 2-5 word short label.
91+
- `rationale`: a single sentence explaining why this angle is distinct from the other directions.
92+
93+
Hard constraint: **orthogonality**. Two near-duplicate directions defeat the directed-diversity premise. Before returning:
94+
- If two directions feel like dupes, replace one with a genuinely different angle.
95+
- If a direction collapses to "just do X better" with no angle distinction, replace it.
96+
- Do not emit directions that merely restate the idea in different words.
97+
98+
### Retry and Degradation
99+
100+
- If the first pass returns fewer than `N` entries, regenerate once with an explicit "you MUST produce `N` orthogonal directions" instruction.
101+
- 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.`
102+
- If fewer than 2 directions are produced, stop with error: `direction generation degraded; retry.`
103+
104+
Store the final direction list as `DIRECTIONS` (ordered; index 0..len-1).
105+
106+
---
107+
108+
## Phase 3: Parallel Exploration
109+
110+
Dispatch all directions in a **single Task-tool message** containing one Task invocation per direction. This is the W2S parallel-swarm step.
111+
112+
### Subagent Invocation
113+
114+
For each direction in `DIRECTIONS`, launch one `Explore` subagent. Each invocation prompt MUST include:
115+
116+
1. A verbatim copy of the idea body (`IDEA_BODY`) captured in Phase 1.
117+
2. The assigned direction (name + rationale).
118+
3. The following instruction block (reproduce verbatim in the subagent prompt):
119+
120+
> Explore this direction within the current repo. Gather OBJECTIVE EVIDENCE:
121+
> - Specific repo paths with existing patterns worth extending.
122+
> - Prior art or precedent in the codebase or adjacent tooling.
123+
> - Measurable considerations (approximate complexity, LOC surface, performance implications) where discoverable from reading the code.
124+
>
125+
> Read-only. Do not write any files.
126+
>
127+
> 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.
128+
>
129+
> Return a structured proposal with exactly these fields:
130+
> - `APPROACH_SUMMARY`: concrete design description (what to build, core mechanism, affected components).
131+
> - `OBJECTIVE_EVIDENCE`: bullet list of repo paths, prior art, or the `exploratory, no concrete precedent` sentinel.
132+
> - `KNOWN_RISKS`: short bullet list.
133+
> - `CONFIDENCE`: one of `high`, `medium`, `low`.
134+
135+
### Collection and Degradation
136+
137+
Collect all subagent responses. For each response:
138+
- Parse the four required fields. If a field is missing, mark that proposal as degraded and drop it.
139+
- If fewer than 2 proposals survive, stop with error: `exploration phase degraded; retry.`
140+
- Otherwise continue with the surviving proposals.
141+
142+
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.
143+
144+
---
145+
146+
## Phase 4: Synthesis and Write
147+
148+
### Step 4.1: Pick the Primary Direction
149+
150+
Review all surviving proposals. Choose the strongest as the primary based on:
151+
1. Evidence density — more concrete repo references outranks fewer.
152+
2. Fit with existing repo patterns — extending patterns outranks introducing unfamiliar paradigms.
153+
3. Implementation surface area — prefer smaller surface where quality is otherwise comparable.
154+
4. Declared `CONFIDENCE` — `high` > `medium` > `low` as tiebreaker.
155+
156+
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.
157+
158+
### Step 4.2: Infer Title
159+
160+
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`.
161+
162+
### Step 4.3: Populate the Template
163+
164+
Read the template file located at `TEMPLATE_FILE` (from Phase 1 stdout).
165+
166+
Produce the finalized draft content in memory by replacing placeholders:
167+
- `<TITLE>` — the inferred title.
168+
- `<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.
169+
- `<PRIMARY_NAME>` — primary direction's short name.
170+
- `<PRIMARY_RATIONALE>` — primary direction's rationale (from Phase 2).
171+
- `<PRIMARY_APPROACH_SUMMARY>` — primary proposal's `APPROACH_SUMMARY`.
172+
- `<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`.
173+
- `<PRIMARY_KNOWN_RISKS>` — primary proposal's `KNOWN_RISKS`, rendered as a bullet list.
174+
- `<ALTERNATIVES>` — for each non-primary survivor at its Alt index `i` (1-based, sequential per Step 4.1), emit:
175+
176+
```markdown
177+
### Alt-<i>: <name>
178+
- Gist: <one-paragraph summary derived from APPROACH_SUMMARY>
179+
- Objective Evidence:
180+
- <bullet from OBJECTIVE_EVIDENCE>
181+
- ...
182+
- Why not primary: <one sentence stating the tradeoff vs PRIMARY>
183+
```
184+
185+
Separate consecutive Alt entries with a single blank line.
186+
187+
- `<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.
188+
189+
### Step 4.4: Write the Draft File
190+
191+
Write the finalized content to `OUTPUT_FILE` using the `Write` tool. Single write; no progressive edits.
192+
193+
### Step 4.5: Report
194+
195+
Report to the user:
196+
- Path written (`OUTPUT_FILE`).
197+
- Primary direction name.
198+
- Requested `N` and the actual direction count (note if reduced due to degradation).
199+
- Next-step hint: `To turn this draft into a plan, run: /humanize:gen-plan --input <OUTPUT_FILE> --output <plan-path>`.
200+
201+
---
202+
203+
## Error Handling
204+
205+
- Phase 1 validation errors stop the command with a clear message. No partial output.
206+
- Phase 2 degradation follows the retry-once + ≥2 minimum rule stated above.
207+
- Phase 3 degradation follows the drop-and-continue + ≥2 minimum rule stated above.
208+
- Never fabricate repo references or prior art. The `exploratory, no concrete precedent` sentinel from subagents is preserved verbatim in the draft.
209+
- If any phase stops with an error, do not write a partial `OUTPUT_FILE`.

‎prompt-template/idea/gen-idea-template.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# <TITLE>
2+
3+
## Original Idea
4+
5+
<ORIGINAL_IDEA>
6+
7+
## Primary Direction: <PRIMARY_NAME>
8+
9+
### Rationale
10+
11+
<PRIMARY_RATIONALE>
12+
13+
### Approach Summary
14+
15+
<PRIMARY_APPROACH_SUMMARY>
16+
17+
### Objective Evidence
18+
19+
<PRIMARY_OBJECTIVE_EVIDENCE>
20+
21+
### Known Risks
22+
23+
<PRIMARY_KNOWN_RISKS>
24+
25+
## Alternative Directions Considered
26+
27+
<ALTERNATIVES>
28+
29+
## Synthesis Notes
30+
31+
<SYNTHESIS_NOTES>

0 commit comments

Comments
 (0)