Skip to content

Add a README before/after diagram + outcome bullets above the Commands table #18

Description

@ivklgn

Rescoped — part of this landed. The README now opens with a value proposition, a host line and an embedded demo above the Commands table (see #19). What is still missing is the legible half: the before/after and the concrete first-session deltas.

Problem

README.md currently opens with:

  1. tagline — "Make your AI code like it already knows your repo",
  2. one paragraph of what it does, one line of supported hosts,
  3. "See it work" + demo.gif,
  4. the Commands table.

That answers "what is this" and shows motion, but a first-time visitor still cannot see what changes in their repo after install — there is no before/after and no statement of the first-session deltas. The demo carries the whole burden of conveying outcome, and a reader who does not watch it gets nothing.

Expected result

A tight (<20-line) block above the Commands table:

  • a two-column before/after diagram — flat ad-hoc markdown pile → typed, related graph — as a Mermaid flowchart so it stays diffable and needs no asset;
  • three short outcome bullets naming concrete first-session deltas ("your ADRs are reachable by the agent without you pasting them", etc.).

It should sit next to demo.gif, not replace it: the gif shows the loop in motion, the diagram shows the end state.

Impact

Communicates value in the first screenful for readers who don't play the demo, reducing bounce and raising the odds a visitor installs or contributes. Pure-markdown change with no external assets — a good first contribution.

Proposed approach

  • Add the before/after Mermaid diagram + three outcome bullets above the Commands table.
  • Check the surrounding narrative still reads in order after the insert.

Acceptance criteria

  • The diagram renders on GitHub (Mermaid in a fenced ```mermaid block).
  • The outcome bullets name concrete deltas, not adjectives.

References

Design rationale: .archcore/plugin/readme-first-60-seconds.idea.md (status: draft). Code: README.md.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions