Problem
The README is comprehensive but reads like documentation for someone already familiar with autonomous code evolution and multi-agent systems. Key issues:
- Too many entry points without guidance — 10+ ways to invoke the factory (raw idea, spec file, GitHub URL, interactive, research, focus, loop, tmux, meta, direct agent) with no "start here" recommendation for beginners
- Unexplained concepts — "harness", "meta-harness", "FEEC priority", "leakage guards", "mutable surfaces" are used without definition
- Auto-research mode isn't explained — how the factory builds evaluation harnesses for research projects, iteratively improves systems under test, and guards against metric gaming isn't clear
- Missing decision tree — no guidance on "which mode should I use?" based on what you're trying to accomplish
What's needed
- "Start Here" section — one canonical beginner path (e.g., build a simple CLI tool) before showing advanced modes
- Concepts glossary — define harness, meta-harness, FEEC, leakage guards, mutable surfaces, precheck gates
- "Choose Your Mode" decision tree — simple flowchart: "I have an idea" → Build, "I have a repo" → Improve, "I want to optimize a metric" → Research, etc.
- Explain auto-research clearly — what it means for the factory to be a "harness creator" and "meta-harness", with a concrete example
- Reduce cognitive load — restructure so beginners can skip advanced sections without missing critical concepts
Non-goals
- Not a docs rewrite — the existing deep docs (
docs/) are fine
- Not dumbing down — keep the technical depth, just make it progressive (simple → advanced)
Problem
The README is comprehensive but reads like documentation for someone already familiar with autonomous code evolution and multi-agent systems. Key issues:
What's needed
Non-goals
docs/) are fine