Repository navigation
Say how work divides when several agents run at once (#746) - #1020
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
AGENTS.mdhas 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 leavesmasterwithout 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.mdonly, +114 lines, one new## Agentic developmentsection inserted between Workingpractice and Write for the reader, briefly. Nothing existing is reworded and no other section
moves —
git diff --statis1 file changed, 114 insertions(+).No code, so no behaviour change and no
BREAKING-CHANGES.mdentry.Merge order
AGENTS.mdis also edited by #1014 and #1016. Whichever of the three merges second and third paysone mechanical conflict round each; the three edits are in different sections, so the resolution is
mechanical.
Part of #746.