Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
.beads		.beads
.claude/commands		.claude/commands
.codex/skills/evo-ideator		.codex/skills/evo-ideator
docs/plans		docs/plans
evoidea_codex_bundle_md		evoidea_codex_bundle_md
examples		examples
schemas		schemas
scripts		scripts
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md

███████╗██╗   ██╗ ██████╗ ██╗██████╗ ███████╗ █████╗
██╔════╝██║   ██║██╔═══██╗██║██╔══██╗██╔════╝██╔══██╗
█████╗  ██║   ██║██║   ██║██║██║  ██║█████╗  ███████║
██╔══╝  ╚██╗ ██╔╝██║   ██║██║██║  ██║██╔══╝  ██╔══██║
███████╗ ╚████╔╝ ╚██████╔╝██║██████╔╝███████╗██║  ██║
╚══════╝  ╚═══╝   ╚═════╝ ╚═╝╚═════╝ ╚══════╝╚═╝  ╚═╝

This is a personal experiment exploring memetic algorithms for startup/product ideation. Not production-ready.

📌 ~/problem

Brainstorming startup ideas is chaotic:

ideas get lost or forgotten
no systematic way to evaluate and compare
hard to iterate on weak spots without losing what works
constraints (budget, timeline, skills) often ignored

🧠 ~/solution

Evoidea runs a memetic algorithm on ideas:

GENERATE → CRITIQUE → SELECT → REFINE → repeat

generate diverse ideas from a prompt
critique each idea on 8 dimensions (feasibility, differentiation, moats, etc.)
select elite survivors, archive the weak
refine winners by addressing their weakest scores
constraints hard-filter ideas that violate budget/timeline/skills

Output: structured JSON with full evolution history, exportable to landing page format.

🏗️ ~/architecture

evoidea/
├── .claude/skills/evoidea.md    # Claude Code skill (main interface)
├── src/                          # Rust CLI utilities
│   ├── main.rs                   # list, show, validate, export, tournament
│   └── lib.rs
├── runs/                         # evolution runs (gitignored)
│   └── run-YYYYMMDD-HHMMSS/
│       ├── config.json           # run parameters + constraints
│       ├── state.json            # current population + scores
│       ├── history.ndjson        # event log
│       └── final.json            # winner + runner-up
└── schemas/                      # JSON schemas for validation

Two interfaces:

/evoidea skill in Claude Code (runs the evolution)
evoidea CLI (inspect runs, export, tournament mode)

🚀 ~/quickstart

For Claude Code users

# clone and open in Claude Code
git clone https://github.com/t3chn/evoidea.git
cd evoidea
claude
# run evolution
/evoidea "Build developer productivity tools" --rounds 3 --population 6
# with constraints
/evoidea "SaaS for freelancers" --budget 1000 --timeline 4 --solo --no crypto,hardware
# with discovery (interactive pre-flight)
/evoidea "Developer tools" --discover
# with domain examples (few-shot learning)
/evoidea "Developer tools" --examples examples/devtools.json

CLI utilities

# build CLI
cargo build --release
# list all runs
evoidea list
evoidea list --dir /path/to/runs  # custom runs directory
# show run results
evoidea show --run-id run-20260123-181141
# export to various formats
evoidea export --run-id run-20260123-181141 --preset landing
evoidea export --run-id run-20260123-181141 --preset decision-log
evoidea export --run-id run-20260123-181141 --preset stakeholder-brief
evoidea export --run-id run-20260123-181141 --preset changelog-entry
# visualize evolution tree
evoidea tree --run-id run-20260123-181141
evoidea tree --run-id run-20260123-181141 --format mermaid
# interactive tournament (rank ideas by preference)
evoidea tournament --run-id run-20260123-181141
evoidea tournament --run-id run-20260123-181141 --pairwise  # smart A/B mode (~2n comparisons)
evoidea tournament --run-id run-20260123-181141 --pairwise --rationale  # optionally capture "why" for each choice
evoidea tournament --run-id run-20260123-181141 --auto      # non-interactive, rank by score
# preference profiles (persist tournament calibration)
evoidea profile show --run-id run-20260123-181141
evoidea profile export --run-id run-20260123-181141 --output prefs.json
evoidea profile import --file prefs.json --run-id run-20260123-181141

🤖 ~/agent-guide

For AI agents using this skill

Invocation:

/evoidea "<prompt>" [--rounds N] [--population N] [--elite N] [--threshold N] [--discover] [--profile FILE]

Constraint flags:

Flag	Description	Example
`--discover`	Ask 5 clarifying questions before generation (auto-populate constraints)	`--discover`
`--budget N`	Max USD for MVP	`--budget 500`
`--timeline N`	Max weeks to launch	`--timeline 4`
`--skills LIST`	Required skills (comma-sep)	`--skills rust,python`
`--must LIST`	Required elements	`--must api,cli`
`--no LIST`	Forbidden elements	`--no crypto,hardware`
`--solo`	Solo dev constraint (flag)	`--solo`
`--resume ID`	Continue from run	`--resume run-20260123-181141`
`--examples FILE`	Domain examples for few-shot	`--examples examples/devtools.json`
`--profile FILE`	Preference profile (from `evoidea profile export`)	`--profile prefs.json`

Evolution phases:

GENERATE (iteration 1): Create population_size diverse ideas
CRITIQUE: Score each idea 0-10 on 8 criteria, check constraint violations
SELECT: Archive bottom half, keep top elite_count
REFINE: Improve elite ideas by addressing weakest scores

Stop conditions:

best_score >= threshold (default 9.0)
stagnation (no improvement for 3 rounds)
iteration >= max_rounds

Output structure:

runs/<run_id>/
├── config.json    # parameters
├── state.json     # population + scores
├── history.ndjson # event log
└── final.json     # best_idea + runner_up + stop_reason

Constraint enforcement:

Ideas violating ANY constraint get overall_score = 0 and status = "eliminated"
Constraints are checked BEFORE scoring in CRITIQUE phase
Violation reason is logged for transparency

👤 ~/user-guide

What you get

After running /evoidea, you'll have:

Winning idea with detailed facets:
- audience, problem (JTBD), differentiator
- monetization strategy, distribution channels
- identified risks
Score breakdown on 8 dimensions:
- feasibility, speed_to_value, differentiation
- market_size, distribution, moats, risk, clarity
Evolution history showing how ideas improved
Exportable formats (evoidea export --preset):
- landing → marketing landing page
- decision-log → technical decision record
- stakeholder-brief → executive summary
- changelog-entry → release notes format
Visualization (evoidea tree):
- ASCII tree showing parent→child evolution
- Mermaid diagram for documentation
Preference profiles (evoidea profile):
- Export/import tournament calibration
- Share preferences across runs

Tips for good prompts

# Too vague (bad)
/evoidea "Make money online"
# Specific direction (good)
/evoidea "Build tools for solo developers who ship side projects"
# With constraints (better)
/evoidea "Developer tools" --budget 500 --timeline 2 --solo --skills rust --no marketplace

Understanding scores

Score	Meaning
8-10	Exceptional, rare
6-7	Strong, worth pursuing
4-5	Average, needs work
0-3	Weak, likely archived

The algorithm is intentionally harsh. A 7/10 is a good idea.

🧪 ~/dev

# run tests
cargo test
# build release
cargo build --release
# validate a run
evoidea validate --run-id <run_id>

🗒️ ~/notes

Evolution runs are stored in runs/ (gitignored by default)
The skill uses Claude Code's Task tool to parallelize refinement
Constraints are optional but recommended for realistic ideas
Tournament mode helps calibrate your preferences for future runs (export a profile and pass it via --profile)
Bundled examples: examples/devtools.json, examples/saas.json, examples/consumer.json

License

MIT