docs(agents): name the question surface, so batching stops meaning prose #1168

Merged

coilyco-ops merged 1 commit from aos/claude/xk77-ask-modality into main

2026-08-20 10:41:55 +00:00

coilyco-ops commented

2026-08-20 10:39:46 +00:00

Owner

The autonomy rules in AGENTS.md, and the role sources that narrow them further, all suppress asking. Agents read that as a reason to avoid the harness's structured question tool entirely, including for the end-of-run batch the wall rule already asks for.

Two things had collapsed into one word:

Whether to stop and wait - a real cost, correctly minimized.
Which surface carries a question asked anyway - no extra cost at all.

A picker is less blocking than prose, not more, and it takes four questions in one call, so it is the batching mechanism rather than a competitor to it. The added paragraph also says what to do past four, since dropping the remainder into prose is the failure a four-question limit invites.

Caps

Raises agents_md_max_lines 319 to 321 and agents_md_max_chars 30000 to 30500, with the reasoning in pyproject.toml in the established format. The rule binds every session and every role, so no role source can hold it, and it has to land before the first question rather than conditionally. Same shape as the 290 to 296 raise for "A pushed branch owes its pull request".

A docs page was not available: docs/ sits at the large band's 40-doc cap and docs/documentation-bands.md forbids trading the count cap against this one. The craft of composing the questions stays in the issue-prioritization reference that already owns it.

Paired with agent-compose build-software (closes agent-compose#312), which sets per-role asking frequency. This sets modality for every seat.

The autonomy rules in `AGENTS.md`, and the role sources that narrow them further, all suppress asking. Agents read that as a reason to avoid the harness's structured question tool entirely, including for the end-of-run batch the wall rule already asks for. Two things had collapsed into one word: * **Whether to stop and wait** - a real cost, correctly minimized. * **Which surface carries a question asked anyway** - no extra cost at all. A picker is less blocking than prose, not more, and it takes four questions in one call, so it is the batching mechanism rather than a competitor to it. The added paragraph also says what to do past four, since dropping the remainder into prose is the failure a four-question limit invites. ## Caps Raises `agents_md_max_lines` 319 to 321 and `agents_md_max_chars` 30000 to 30500, with the reasoning in `pyproject.toml` in the established format. The rule binds every session and every role, so no role source can hold it, and it has to land before the first question rather than conditionally. Same shape as the 290 to 296 raise for "A pushed branch owes its pull request". A docs page was not available: `docs/` sits at the large band's 40-doc cap and `docs/documentation-bands.md` forbids trading the count cap against this one. The craft of composing the questions stays in the issue-prioritization reference that already owns it. Paired with agent-compose `build-software` (closes agent-compose#312), which sets per-role asking frequency. This sets modality for every seat.

coilyco-ops added 1 commit

2026-08-20 10:39:46 +00:00

docs(agents): name the question surface, so batching stops meaning prose

ci / aos-eval-tests (pull_request) Successful in 8s

Details

ci / aos-cli-tests (pull_request) Successful in 18s

Details

ci / ward-doctor (pull_request) Successful in 13s

Details

ci / gate (pull_request) Successful in 1m1s

Details

f6abc140f4

The autonomy rules here, and the role sources that narrow them further, all
suppress asking. Agents read that as a reason to avoid the harness's structured
question tool entirely, including for the end-of-run batch the wall rule
already asks for. Two things had collapsed into one word: whether to stop and
wait, which is a real cost, and which surface carries a question that is being
asked anyway, which costs nothing. A picker is less blocking than prose, not
more, and it takes four questions in one call, so it is the batching mechanism
rather than a competitor to it.

Also says what to do past four, since dropping the remainder into prose is the
failure the four-question limit invites.

Raises the AGENTS.md caps by one section with the reasoning in pyproject.toml.
docs/ is at the large band's 40-doc cap, and documentation-bands.md forbids
trading that count against this one, so a docs page was not available.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

coilyco-ops merged commit 9d0a8bb6f2 into main

2026-08-20 10:41:55 +00:00

coilyco-ops deleted branch aos/claude/xk77-ask-modality

2026-08-20 10:41:55 +00:00

coilyco-ops referenced this pull request from a commit

2026-08-20 10:41:57 +00:00

docs(agents): name the question surface, so batching stops meaning prose (#1168)