Skip to content

Improve README for beginner friendliness #205

@akashgit

Description

@akashgit

Problem

The README is comprehensive but reads like documentation for someone already familiar with autonomous code evolution and multi-agent systems. Key issues:

  1. 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
  2. Unexplained concepts — "harness", "meta-harness", "FEEC priority", "leakage guards", "mutable surfaces" are used without definition
  3. 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
  4. 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)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions