feat(gen-idea): directed-swarm idea drafting command (1.16.1) - #99
Conversation
Introduces a design document for a new /humanize:gen-idea command that sits one step before gen-plan in the Humanize workflow. The command applies the directed-diversity insight from Anthropic's Automated W2S Researcher note: a lead picks N orthogonal directions and delegates one direction per Explore subagent, then synthesizes a repo-grounded draft suitable as gen-plan input. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Five-task plan covering the draft template, IO validation script, command spec, README/version bumps, and an end-to-end smoke check. Targets dev for the 1.16.1 release. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Skeleton populated by the command's Phase 4 synthesis step. Placeholders <TITLE>, <ORIGINAL_IDEA>, <PRIMARY_*>, <ALTERNATIVES>, <SYNTHESIS_NOTES> are filled deterministically by the command body. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Detects inline vs .md file input, writes inline text to a tempfile so downstream phases always consume a file, derives a URL-safe slug, and resolves the default output path under .humanize/ideas/. Exit codes parallel validate-gen-plan-io.sh. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two corrections required to pass macOS smoke tests: - Path heuristic now treats slashes as path-indicating only when no whitespace is present, so inline ideas like "add undo/redo" are not misread as paths. - mktemp template drops the .md suffix (BSD mktemp does not support a suffix after the X template). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Code-quality review surfaced three items on the IO validation script: - Guard `realpath $IDEA_INPUT` with a fallback so older macOS does not trip `set -e` on the file-input branch. - Comment explaining the caller owns tempfile cleanup (no trap) so a future maintainer does not silently break the caller. - Comment clarifying the path-vs-inline heuristic and its limitation (a non-existent path with spaces falls through to inline mode). The plan's literal script copy is updated to match. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Five-phase command: parse, validate via scripts/validate-gen-idea-io.sh, generate N orthogonal directions grounded in repo context, fan out N parallel Explore subagents in a single Task-tool message, synthesize one primary plus N-1 alternatives into the new template, write the draft. No Codex, no tests, no config-loader integration in this pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Five documentation patches to commands/gen-idea.md (and the mirrored copy in the plan doc): - State that degraded runs renumber surviving alternatives Alt-1..Alt-K sequentially rather than preserving source-index gaps. - Specify the rendering of the `exploratory, no concrete precedent` sentinel as a single bullet when it is the sole evidence. - Note that the Hard Constraint permits the validation script's prerequisite `.humanize/ideas/` directory creation. - Bold the Sequential Execution Constraint label for style parity with gen-plan.md. - Pin the Phase 2 context paths (README.md, CLAUDE.md, .claude/CLAUDE.md) to the project root via `git rev-parse --show-toplevel`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add a Quick Start entry for /humanize:gen-idea above the existing gen-plan step and sync version across plugin.json, marketplace.json, and the README header. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Address final-review findings: - Implement the spec's warn-and-continue behavior for inline ideas shorter than 10 characters by emitting a `WARNING: short idea ...` line on stdout before VALIDATION_SUCCESS. The command spec documents this as a non-error informational line that should be surfaced to the user but does not block Phase 2. - Note in Phase 1 that SLUG is informational; it is already baked into OUTPUT_FILE by the script and does not need to be consumed directly by later phases. - Mirror both edits into the plan doc copies. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1adeca421e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| if [[ "$IDEA_INPUT" == *.md ]]; then | ||
| looks_like_path=true |
There was a problem hiding this comment.
Any argument ending in .md is forced into looks_like_path=true, so inline ideas such as "rename README.md" fail with INPUT_NOT_FOUND when no file exists. This blocks valid prompts that merely mention a markdown filename and contradicts the command’s advertised auto-detection behavior of using file mode only when an existing .md path is provided.
Useful? React with 👍 / 👎.
| looks_like_path=true | ||
| fi | ||
|
|
||
| if [[ -f "$IDEA_INPUT" ]]; then |
There was a problem hiding this comment.
The file-input branch validates existence, extension, and non-empty content but never checks readability, so an unreadable .md can pass validation and then fail later when the command reads IDEA_BODY_FILE. That bypasses the documented exit-code path for “missing/not readable” input and produces a less actionable runtime failure for users.
Useful? React with 👍 / 👎.
An argument ending in .md was unconditionally classified as a path, so inline ideas that mention a markdown filename (for example "rename README.md") failed validation with INPUT_NOT_FOUND instead of being accepted as inline text. Gate the .md heuristic on the same "no whitespace" rule the "/" branch already applied. Ideas with any whitespace fall through to inline mode, while clean strings like "./idea.md" or "path/to/idea.md" still surface a helpful INPUT_NOT_FOUND error when the file is absent.
The file-input branch validated existence, .md extension, and non-empty
content but never checked readability. An unreadable regular .md file
passed validation and then triggered a less actionable runtime failure
when the command itself tried to read IDEA_BODY_FILE.
Insert an -r readability check between the extension and emptiness
checks. Emit VALIDATION_ERROR: INPUT_NOT_READABLE with exit 2, aligning
with the advertised exit-code path ("missing, not readable, or not .md")
in the command spec.
|
@codex review this PR as entirety |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 04116b90ce
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| # Deliberately no `trap ... EXIT` to remove TMPFILE: the caller consumes | ||
| # IDEA_BODY_FILE after this script exits, so a naive trap would delete | ||
| # the file the caller needs. On error paths the tempfile is leaked in | ||
| # $TMPDIR; the OS sweeps $TMPDIR on reboot and the cost is negligible. | ||
| TMPFILE="$(mktemp "${TMPDIR:-/tmp}/gen-idea-inline-XXXXXX")" |
There was a problem hiding this comment.
Inline mode writes every idea into a new mktemp file and explicitly avoids deleting it, so each /humanize:gen-idea run leaves another file in /tmp containing user-provided idea text. On long-lived developer machines or CI workers this creates unbounded tempfile growth and retains potentially sensitive ideas beyond command completion; this should be cleaned up via an explicit caller-side delete contract (or equivalent success/failure cleanup path).
Useful? React with 👍 / 👎.
Inline mode created a per-run mktemp file under TMPDIR and deliberately left it in place so the caller could read it after the script exited. On long-lived developer machines or CI workers this produced unbounded tempfile growth and retained user-provided idea text on disk beyond command completion. Eliminate the tempfile entirely. The script now emits the inline idea body on stdout between the literal sentinel lines "=== IDEA_BODY_BEGIN ===" and "=== IDEA_BODY_END ===". The caller extracts the body from that block when INPUT_MODE is inline, and still reads IDEA_BODY_FILE from disk in file mode. IDEA_BODY_FILE is now only emitted in file mode; stdout contract for inline mode gains the sentinel block but drops the on-disk handoff. Update commands/gen-idea.md to document the new mode-aware body retrieval and to reference the in-memory IDEA_BODY value in the Phase 3 subagent prompt and Phase 4 template placeholder.
|
@codex review this PR as entirety |
|
Codex Review: Didn't find any major issues. 🎉 ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
2 participants
Summary
/humanize:gen-idea: takes a loose idea (inline text or.mdfile) and produces a repo-grounded draft suitable as input to/humanize:gen-plan.Exploresubagents develop each with objective repo evidence, the lead synthesizes one primary + N-1 alternatives.1.16.0→1.16.1acrossplugin.json,marketplace.json, and the README header.What ships
commands/gen-idea.md— slash-command spec (five phases: parse → validate → direction generation → parallel exploration → synthesize + write).prompt-template/idea/gen-idea-template.md— output draft skeleton with nine placeholders.scripts/validate-gen-idea-io.sh— bash IO validation + slug + default-path resolution. Exit codes parallelvalidate-gen-plan-io.sh. Includes short-idea warning, macOSrealpathfallback, and a deliberate no-trap tempfile contract documented inline.README.md— new Quick Start step (step 1) abovegen-plan; version header to1.16.1.docs/superpowers/specs/2026-04-20-gen-idea-design.md+docs/superpowers/plans/2026-04-20-gen-idea.md— design + implementation plan used to drive this change.Command signature
Positional arg auto-detects inline text vs existing
.mdfile.--nis[2, 10], default6.--outputdefaults to.humanize/ideas/<slug>-<YYYYMMDD-HHMMSS>.mdand refuses to overwrite.Test plan
bash -n scripts/validate-gen-idea-io.sh).plugin.jsonandmarketplace.json.MISSING_IDEA,N_OUT_OF_RANGE,INVALID_N,INPUT_NOT_FOUND,INPUT_NOT_MD,INPUT_EMPTY,OUTPUT_EXISTS,OUTPUT_DIR_NOT_FOUND).realpathfallback, BSDmktemptemplate, Alt-N numbering scheme, sentinel rendering, Hard-Constraint carve-out, short-idea warning).add a /humanize:list-loops command that shows all active RLCR and PR loops with state and elapsed time,--n 4): draft produced at.humanize/ideas/...mdwith one primary direction plus three alternatives, every alt carrying concrete repo line-range evidence; idea preserved verbatim; theexploratory, no concrete precedentsentinel correctly surfaced where appropriate.tests/run-all-tests.sh) — requires bash 4+; validated locally on macOS bash 3.2 only via shell-syntax + JSON + version checks. CI will run the full suite on Linux./humanize:gen-idea "...", and confirms the five-phase flow renders a valid draft that passes through/humanize:gen-plan --input <draft>without human edits.Out of scope (tracked in the design spec for future passes)
--chain-to-gen-planflag for auto-handoff.--directionsoverride for user-pinned angles.gen-planPhase 2.🤖 Generated with Claude Code