README opens at the wrong altitude for a first-time reader #285

New issue

Open

opened 2026-08-16 00:26:08 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-16 00:26:08 +00:00

Member

Problem

After the banner and a one-line summary, the first section is "Ownership boundary", followed by roughly twenty bullets of internal architecture: roster packages, personality meld resolution, bundle materialization, role-scoped providers, model tiers, load-point adapters.

Every one of those lines is meaningful to someone already inside the system. None of them tells a newcomer what problem acompose solves, or how to try it. A reader arriving cold from a link gets one orienting sentence and then a specification.

This repo is a stated promotion priority and currently sits at 0 stars, so the first screen is doing all the work.

Evidence that the fix is already in-house

mcp-beaver gets this exact structure right, and it is the best writing in the portfolio:

Hook line - "A dam is not a wall. It decides what gets through."
Short About - what it renders, from what, into what.
Quickstart - a runnable command inside the first screen.
Detail and boundaries after.

Nothing new needs inventing. Copy that shape.

Proposed change

Keep the banner.
Add a hook line under the title.
Follow with a three-sentence About covering what acompose takes in and what it produces.
Promote a Quickstart with one runnable acompose command above the fold.
Move "Ownership boundary" below the quickstart, or into docs/, linked from the README.

The boundary content is accurate and worth keeping. This issue is about ordering, not deletion.

Scope

Content-only. Reverting changes human-facing words and static structure, leaving behavior, flags, and output unchanged.

## Problem After the banner and a one-line summary, the first section is "Ownership boundary", followed by roughly twenty bullets of internal architecture: roster packages, personality meld resolution, bundle materialization, role-scoped providers, model tiers, load-point adapters. Every one of those lines is meaningful to someone already inside the system. None of them tells a newcomer what problem `acompose` solves, or how to try it. A reader arriving cold from a link gets one orienting sentence and then a specification. This repo is a stated promotion priority and currently sits at 0 stars, so the first screen is doing all the work. ## Evidence that the fix is already in-house `mcp-beaver` gets this exact structure right, and it is the best writing in the portfolio: 1. Hook line - "A dam is not a wall. It decides what gets through." 2. Short About - what it renders, from what, into what. 3. Quickstart - a runnable command inside the first screen. 4. Detail and boundaries after. Nothing new needs inventing. Copy that shape. ## Proposed change * Keep the banner. * Add a hook line under the title. * Follow with a three-sentence About covering what `acompose` takes in and what it produces. * Promote a Quickstart with one runnable `acompose` command above the fold. * Move "Ownership boundary" below the quickstart, or into `docs/`, linked from the README. The boundary content is accurate and worth keeping. This issue is about ordering, not deletion. ## Scope Content-only. Reverting changes human-facing words and static structure, leaving behavior, flags, and output unchanged.

coilyco-ops referenced this issue

2026-08-16 00:33:17 +00:00

Strip the trailing space from the description, and set homepage #284

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

coilyco-flight-deck/agent-compose#285

No description provided.

Rows
Columns