Skip to content

Say how work divides when several agents run at once (#746) - #1020

Merged
Rafael-SOWNet merged 4 commits into
masterfrom
docs/agentic-development
Aug 23, 2026
Merged

Rafael-SOWNet merged 4 commits into
masterfrom
docs/agentic-development

Conversation

@Rafael-SOWNet

Copy link
Copy Markdown
Member

AGENTS.md has a working practice for one agent: branch, failing test first, run everything,
record a changed answer, read the thread before merging. It says nothing about the case this
repository is actually in, which is several agents working at the same time.

That case has failure modes the single-agent rules do not cover, and they are not the ones people
expect. Being slow is not the problem. Two agents building the same abstraction twice is, and so is
one reverting the other — and neither shows up as a merge conflict. Git warns about a second edit to
the same line; it does not warn about a second design.

What the new section settles

Ownership is claimed before writing, and by component rather than by issue number. Two issues in
one file are one task; one issue across two subsystems is usually two.

A merged PR is not the synchronisation primitive. Dependent work may build on an unmerged branch
once that branch's design is stable, and independent work never waits at all. The real constraint
runs the other way: a foundational abstraction still being argued about should not have a pile of
downstream work on it yet. The mechanical trap git does not warn about is recorded alongside it — a
branch cut on top of another branch merges into that branch, reads MERGED, and leaves master
without the code.

The repository is the source of truth, not the tracker and not another agent's description of
the code. An open issue does not mean the functionality is missing and a closed one does not mean it
is complete; both have been wrong here, which is why the 2026-08-23 audit of #746 struck items
through against the code rather than against their issue state.

When two streams need the same foundational code, parallel implementation of that part stops
until one design is agreed. Throughput gets no exception from the rule at the top of the file.

It also records the roadmap-execution loop — audit, dependency graph, critical path, run everything
unblocked concurrently, integrate, repeat — because a large issue is a dependency graph written down
as a list, and the list order is not the execution order.

Scope

AGENTS.md only, +114 lines, one new ## Agentic development section inserted between Working
practice
and Write for the reader, briefly. Nothing existing is reworded and no other section
moves
— git diff --stat is 1 file changed, 114 insertions(+).

No code, so no behaviour change and no BREAKING-CHANGES.md entry.

Merge order

AGENTS.md is also edited by #1014 and #1016. Whichever of the three merges second and third pays
one mechanical conflict round each; the three edits are in different sections, so the resolution is
mechanical.

Part of #746.

AGENTS.md has a working practice for one agent: branch, failing test first,
run everything, record a changed answer, read the thread before merging. It
says nothing about the case this repository is actually in, which is several
agents working at the same time.

That case has failure modes the single-agent rules do not cover, and they are
not the ones people expect. Being slow is not the problem; two agents building
the same abstraction twice is, and so is one reverting the other. Neither shows
up as a merge conflict -- git will not warn about a second design, only about a
second edit to the same line.

So the new section settles four things:

Ownership is claimed before writing, and by component rather than by issue
number. Two issues in one file are one task; one issue across two subsystems is
usually two.

A merged PR is not the synchronisation primitive. Dependent work may build on an
unmerged branch once that branch's design is stable, and independent work never
waits at all. The real constraint is the other direction: a foundational
abstraction that is still being argued about should not have a pile of
downstream work on it yet. The mechanical trap that git does not warn about is
recorded with it -- a branch cut on top of another branch merges into that
branch, reads MERGED, and leaves master without the code.

The repository is the source of truth, not the tracker and not another agent's
description of it. An open issue does not mean the functionality is missing and
a closed one does not mean it is complete; both have been wrong here.

And when two streams turn out to need the same foundational code, parallel
implementation of that part stops until one design is agreed. Throughput does
not get an exception from the rule at the top of this file.

Nothing existing is reworded and no other section moves.
Docs/Contributing/Packaging.md is added by another branch and answers #746's
item 78: which capabilities ship in the kernel and which ship separately. It
belongs in the table for the same reason CanonicalForm.md does -- somebody
about to land something large in the kernel should find it before writing the
paragraph it already contains.
Docs/Usage/Comparison.md is added by another branch and is where #746's item 40
lands: the head-to-head figures against Math.NET Symbolics, Symbolism and SymPy,
which until now existed only in an out-of-tree workspace. It belongs in the
table because the question it answers -- how do we compare -- is one a reader
asks before they ask anything else in this file.
@Rafael-SOWNet
Rafael-SOWNet merged commit 6ed4507 into master Aug 23, 2026
27 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant