coilyco-flight-deck/agent-compose

Watch

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

New issue

Open

opened 2026-08-16 00:25:59 +00:00 by coilyco-ops · 2 comments

coilyco-ops commented

2026-08-16 00:25:59 +00:00

Member

The actual constraint

The GitHub description is the banner tagline. assets/banner/agent-compose-banner.jpg renders it under the heading, and scripts/banners/agent_compose_banner.py in agentic-os-xxx carries the same string as TAGLINE.

The design rule in that repo's banner-system.md is that the tagline "stays narrower than the name". Measured against the shipped file, Avenir Next Demi at 50/1280 for the heading and Regular at 31/1280 for the tagline:

heading agent-compose // $ acompose, 27 chars, 709px
tagline Eval driven agent roles and personas, 36 chars, 520px, ratio 0.73

Parity with the heading arrives at about 49 tagline chars. Past that the lockup flattens and the tagline overruns the name it is meant to sit under. A ratio of 0.85, about 42 chars, is the practical ceiling.

So the description has a hard design ceiling of roughly 42 characters, and the current string at 36 is close to optimal for the space rather than underwritten.

The one real defect

Eval driven agent roles and personas

A trailing space, 37 chars where the banner tagline is 36. The description and the tagline are the same sentence maintained in two places with nothing binding them, and this space is the drift that proves it.

homepage is also set to the empty string rather than a URL. umbra ships GitHub Pages, this does not.

Proposals

Measured ratios against the 709px heading. The constraint that the string retains "eval" is satisfied by all three.

Strip the space only, 36 chars, ratio 0.73 - Eval driven agent roles and personas. Zero risk, matches the shipped banner exactly, no reminting.
39 chars, ratio 0.76 - Eval driven agent roles, every harness. Adds the differentiator and still fits.
41 chars, ratio 0.80 - Eval driven agent roles for every harness. Same idea, no terminal period.

Anything at or above 43 chars measures over 0.85 and starts crowding the heading. For reference, the two replacements originally proposed here measured 1.27 and 1.61 times the heading width.

If a replacement other than the first is chosen, the banner needs reminting so the two strings stay identical, which pulls in agentic-os-xxx and Designer. The first option needs no art change.

Where the reader payload should go instead

The original complaint, that the description does not tell a newcomer what acompose does for them, is a real problem. It just cannot be solved in 42 characters. That job belongs to the README hook line and quickstart, tracked in #285.

Open question, deferred by the human

There is still no written convention for repo description length. What this issue establishes is narrower: for a repo carrying a banner, the description is bounded by type metrics, not by editorial taste. Repos without a banner have no such ceiling, and the corpus across 32 public repos runs min 29, median 100, p90 157, max 238.

The open decision for the convention: are the GitHub description and the banner tagline one string with one owner, or two strings that are allowed to differ? Today they are the same sentence in two places with no validator binding them.

Scope

Content-only for the description and homepage. Reminting the banner is Designer plus agentic-os-xxx.

Rewritten after the banner constraint came to light. The original framing called this description underwritten and proposed longer replacements. That was wrong. See the correction comment below for what changed. ## The actual constraint The GitHub description **is the banner tagline**. `assets/banner/agent-compose-banner.jpg` renders it under the heading, and `scripts/banners/agent_compose_banner.py` in `agentic-os-xxx` carries the same string as `TAGLINE`. The design rule in that repo's `banner-system.md` is that the tagline "stays narrower than the name". Measured against the shipped file, Avenir Next Demi at 50/1280 for the heading and Regular at 31/1280 for the tagline: * heading `agent-compose // $ acompose`, 27 chars, **709px** * tagline `Eval driven agent roles and personas`, 36 chars, **520px**, ratio **0.73** Parity with the heading arrives at about 49 tagline chars. Past that the lockup flattens and the tagline overruns the name it is meant to sit under. A ratio of 0.85, about 42 chars, is the practical ceiling. So the description has a hard design ceiling of roughly 42 characters, and the current string at 36 is close to optimal for the space rather than underwritten. ## The one real defect ``` Eval driven agent roles and personas ``` A **trailing space**, 37 chars where the banner tagline is 36. The description and the tagline are the same sentence maintained in two places with nothing binding them, and this space is the drift that proves it. `homepage` is also set to the empty string rather than a URL. umbra ships GitHub Pages, this does not. ## Proposals Measured ratios against the 709px heading. The constraint that the string retains "eval" is satisfied by all three. * **Strip the space only, 36 chars, ratio 0.73** - `Eval driven agent roles and personas`. Zero risk, matches the shipped banner exactly, no reminting. * **39 chars, ratio 0.76** - `Eval driven agent roles, every harness.` Adds the differentiator and still fits. * **41 chars, ratio 0.80** - `Eval driven agent roles for every harness`. Same idea, no terminal period. Anything at or above 43 chars measures over 0.85 and starts crowding the heading. For reference, the two replacements originally proposed here measured 1.27 and 1.61 times the heading width. **If a replacement other than the first is chosen, the banner needs reminting** so the two strings stay identical, which pulls in `agentic-os-xxx` and Designer. The first option needs no art change. ## Where the reader payload should go instead The original complaint, that the description does not tell a newcomer what `acompose` does for them, is a real problem. It just cannot be solved in 42 characters. That job belongs to the README hook line and quickstart, tracked in #285. ## Open question, deferred by the human There is still no written convention for repo description length. What this issue establishes is narrower: for a repo carrying a banner, the description is bounded by type metrics, not by editorial taste. Repos without a banner have no such ceiling, and the corpus across 32 public repos runs min 29, median 100, p90 157, max 238. The open decision for the convention: are the GitHub description and the banner tagline **one string with one owner**, or two strings that are allowed to differ? Today they are the same sentence in two places with no validator binding them. ## Scope Content-only for the description and homepage. Reminting the banner is Designer plus `agentic-os-xxx`.

coilyco-ops changed title from ~~Rewrite the GitHub description to carry reader value, and set homepage~~ to Strip the trailing space from the description, and set homepage

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

coilyco-ops commented

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

Author

Member

Correction record

The body was rewritten. Original filing missed that this repo carries a banner and that the description is its tagline, so it argued from the wrong premise.

What the original said: the description is thin and carries no reader payload, replace it with something longer. Proposed Eval driven agent roles and personas. One roster, every harness. at 64 chars, and Compiles eval driven agent roles and personas into per-harness context bundles. at 79.

Why that was wrong: measured in the shipped banner's own font, those two land at 902px and 1143px against a 709px heading, ratios of 1.27 and 1.61. The tagline would have run wider than the name it sits under, inverting the lockup. banner-system.md states the tagline stays narrower than the name.

What stands: the trailing space, and the unset homepage.

What was retracted: the claim that the string is underwritten. At a 42-char ceiling it is close to optimal.

Also worth flagging for the convention discussion: the description and TAGLINE in scripts/banners/agent_compose_banner.py are the same sentence stored in two repos with nothing keeping them in sync. The trailing space is already drift between them.

## Correction record The body was rewritten. Original filing missed that this repo carries a banner and that the description is its tagline, so it argued from the wrong premise. **What the original said:** the description is thin and carries no reader payload, replace it with something longer. Proposed `Eval driven agent roles and personas. One roster, every harness.` at 64 chars, and `Compiles eval driven agent roles and personas into per-harness context bundles.` at 79. **Why that was wrong:** measured in the shipped banner's own font, those two land at 902px and 1143px against a 709px heading, ratios of 1.27 and 1.61. The tagline would have run wider than the name it sits under, inverting the lockup. `banner-system.md` states the tagline stays narrower than the name. **What stands:** the trailing space, and the unset homepage. **What was retracted:** the claim that the string is underwritten. At a 42-char ceiling it is close to optimal. Also worth flagging for the convention discussion: the description and `TAGLINE` in `scripts/banners/agent_compose_banner.py` are the same sentence stored in two repos with nothing keeping them in sync. The trailing space is already drift between them.

coilyco-ops referenced this issue from coilyco-flight-deck/agentic-os

2026-08-16 01:11:50 +00:00

Teach generate_repo_pointer_skill that a repo carries a banner and what binds its description #1080

coilyco-ops commented

2026-08-16 01:11:58 +00:00

Author

Member

Second correction: the description is not the tagline, it opens with it

Checking sirens-echo as a second banner-carrying repo overturns the framing in the body above. Both of my earlier readings were wrong, in opposite directions.

sirens-echo ships:

banner tagline - a discord community agent harness, 33 chars
GitHub description - A discord community agent harness - home of sirens echo and sirens deep, 71 chars

The description opens with the tagline, capitalized, then extends past it with -. agent-compose only looked like a one-to-one binding because its extension happens to be empty.

So the 42-char ceiling binds the opening of the description, not its whole length. The remainder is free prose that never reaches the art.

Revised proposal

This dissolves the tradeoff. The original complaint, that the description carries no reader payload, can be fixed without touching the banner:

Eval driven agent roles and personas - one roster, every harness

63 chars. The first 36 are byte-identical to the shipped tagline, so no reminting is needed. The extension carries the payload. It matches the pattern sirens-echo already ships, and it keeps "eval" as required.

The three options in the body remain valid as tagline-length replacements. This one is better than all of them, because it changes only the free part.

Also confirmed

The ceiling is per-product, not a constant. agent-compose sits at ratio 0.73 with a 42-char ceiling, sirens-echo at 0.84 with 33. And when Sirens // Discord measured 1.46, Designer's fix was to enlarge the heading from 50 to 81 rather than cut the tagline, so "shorten the words" is not the only lever available.

Both figures reproduce the numbers already recorded in agentic-os-xxx scripts/banners/sirens_banner.py.

Generator-level fix proposed at coilyco-flight-deck/agentic-os, so the next agent to touch a description learns this from the pointer skill instead of from a near miss.

## Second correction: the description is not the tagline, it opens with it Checking sirens-echo as a second banner-carrying repo overturns the framing in the body above. Both of my earlier readings were wrong, in opposite directions. sirens-echo ships: * banner tagline - `a discord community agent harness`, 33 chars * GitHub description - `A discord community agent harness - home of sirens echo and sirens deep`, 71 chars The description opens with the tagline, capitalized, then extends past it with ` - `. agent-compose only looked like a one-to-one binding because its extension happens to be empty. **So the 42-char ceiling binds the opening of the description, not its whole length.** The remainder is free prose that never reaches the art. ### Revised proposal This dissolves the tradeoff. The original complaint, that the description carries no reader payload, can be fixed without touching the banner: ``` Eval driven agent roles and personas - one roster, every harness ``` 63 chars. The first 36 are byte-identical to the shipped tagline, so **no reminting is needed**. The extension carries the payload. It matches the pattern sirens-echo already ships, and it keeps "eval" as required. The three options in the body remain valid as tagline-length replacements. This one is better than all of them, because it changes only the free part. ### Also confirmed The ceiling is per-product, not a constant. agent-compose sits at ratio 0.73 with a 42-char ceiling, sirens-echo at 0.84 with 33. And when `Sirens // Discord` measured 1.46, Designer's fix was to enlarge the heading from 50 to 81 rather than cut the tagline, so "shorten the words" is not the only lever available. Both figures reproduce the numbers already recorded in `agentic-os-xxx` `scripts/banners/sirens_banner.py`. Generator-level fix proposed at coilyco-flight-deck/agentic-os, so the next agent to touch a description learns this from the pointer skill instead of from a near miss.

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#284

No description provided.

Rows
Columns