Agentic development guidance uses direct, evergreen prose

src/docs/Capabilities/agentic-development/AGENTS.template.md

@@ -9,20 +9,20 @@ This document explains the repository-level `AGENTS.md` template. It is not
 itself the router that agents load. Copy the contents of the fenced `markdown`
 block into an `AGENTS.md` at the repository root.
 
-The router moves from the most specific guidance to the least specific:
-repository-local guidance first, initiative-specific guidance next, and the
-organization's central guidance last.
-Before using a linked repository, clone it locally, keep its configuration local
-to that clone, and update it from its remote.
-Agentic runtimes and local development may materialize that repository in any
-context checkout they control. Clone, freshness, and local configuration
-mechanics belong to that runtime or development setup, not to this portable
-router.
+The router reads repository-local guidance first, initiative-specific guidance
+next, and central organization guidance last.
+
+Before you use a linked repository, clone it locally. Keep its configuration
+local to that clone. Update it from its remote before reading it.
+
+Each runtime or development setup controls its documentation context checkout.
+It owns clone, freshness, and local configuration mechanics. This portable
+router does not define those mechanics.
 
 Client-specific files such as `.claude/CLAUDE.md` and
-`.github/copilot-instructions.md` point to the repository router. The shared
-`msxorg` Agent Plugin improves discoverability through skills that are shallow
-pointers to canonical documentation pages.
+`.github/copilot-instructions.md` point to the repository router.
+The shared `msx` Agent Plugin from the `msxorg` marketplace provides skills that
+point to canonical documentation pages.
 
 ````markdown
 # AGENTS
@@ -41,9 +41,9 @@ clone, and update it before reading it.
 ````
 
 Tailor the entries to real destinations. Keep the local contribution entry only
-[when a local guide is needed](../../Ways-of-Working/Repository-Standard.md#contribution-guidance);
-otherwise replace it with a link to the initiative's required contribution
-source in its public `.github` repository. If the source guide is blank, also
+[when a local guide is needed](../../Ways-of-Working/Repository-Standard.md#contribution-guidance).
+Otherwise, link to the initiative's required contribution source in its public
+`.github` repository. If the source guide is blank, also
 link to the shared
 [Contribution Workflow](../../Ways-of-Working/Contribution-Workflow.md).
 Report a missing required source file in the initiative's community repository.

src/docs/Capabilities/agentic-development/advisory-agents.md

@@ -1,23 +1,21 @@
 ---
 title: Advisory Agents
-description: The pattern for automation that analyses work and publishes its conclusion as advice, without deciding, relabelling, or committing.
+description: The pattern for automation that analyzes work and publishes its conclusion as advice, without deciding, relabeling, or committing.
 ---
 
 # Advisory Agents
 
-Some useful automation produces a **judgement** rather than a change: whether a pull request
-looks ready, whether a specification covers its requirements, whether a change carries risk
-its description does not mention. The judgement is worth having and cannot be expressed as a
-passing or failing check, because it is not a fact — it is an opinion, and opinions can be
-wrong.
+An advisory agent assesses work and publishes a **judgment**, not a change. It can assess
+pull-request readiness, requirement coverage, or risks that a description omits. These
+assessments are opinions that can be wrong. They do not establish a passing or failing
+factual check.
 
-The advisory pattern exists so that such automation can be useful without becoming
-authoritative.
+The advisory pattern keeps these assessments useful without giving them decision authority.
 
 ## Advice, not authority
 
-An advisory agent MUST publish its conclusion as advice and MUST NOT be the thing that
-decides.
+An advisory agent MUST publish its conclusion as advice and MUST NOT decide the artifact's
+outcome.
 
 Concretely, it MUST NOT:
 
@@ -26,77 +24,67 @@ Concretely, it MUST NOT:
 - Overwrite a decision a human has recorded.
 - Re-apply a decision a human has changed.
 
-The last two are the ones that get violated by accident. An agent that sets a label on every
-run will faithfully undo the maintainer who corrected it, and it will do so without malice
-and without noticing. From the maintainer's side, the correction simply does not stick, and
-the reasonable conclusion is that the automation is broken and should be turned off.
+A repeated label update can overwrite a maintainer's correction. The agent can repeat this
+action without recognizing that a human changed the decision. The maintainer then loses
+control of the recorded decision.
 
-So the constraint is behavioural, not just permissive: it is not enough that a human *can*
-override the agent. Overriding it MUST be final.
+The constraint is behavioral, not only a permission setting: a human override MUST be final.
 
 ## Seed once, never relabel
 
-Where an advisory agent expresses its conclusion as a label, it MUST apply that label only
-when no label from the same set is present, and MUST leave the set alone thereafter.
+For label-based advice, the agent MUST apply its label only when no label from the same set
+is present. It MUST leave the set unchanged thereafter.
 
-This gives the agent exactly one turn to speak. It supplies an initial assessment when there
-is none — which is the case where the automation adds most, because the alternative is
-nothing — and from then on the field belongs to whoever curates it.
+The agent supplies an initial assessment only when no label from the set exists.
+Later updates remain outside that assessment.
 
-The rule is what makes the agent safe to run repeatedly. Combined with idempotence, it means a
-re-run on an artifact a human has since touched changes nothing at all.
+On repeated runs, the agent leaves an existing label unchanged, including a label corrected
+by a human.
 
 ## Idempotent by construction
 
 An advisory agent MUST be safe to run repeatedly on the same artifact.
 
-It will be: events fire more than once, workflows are re-run, and an artifact under active
-review is re-examined many times. An agent whose output accumulates turns a busy pull request
-into an unreadable one, and the noise costs more than the advice is worth.
+Events can occur more than once. Contributors can rerun workflows or request another review
+of the same artifact. Duplicate advice makes the review harder to read.
 
-In practice that means an agent updates its previous conclusion in place rather than adding a
-new one, and says nothing when it has nothing new to say. Silence at steady state is a
-feature.
+The agent updates its previous conclusion in place instead of adding duplicate advice.
+If the conclusion has not changed, it publishes no update.
 
 ## Triggering late
 
 An advisory agent SHOULD trigger when work is declared ready rather than on every change.
 
-Advice on unfinished work is mostly advice about the unfinished parts, and a contributor
-learns to ignore it — after which the one useful comment is ignored too. Waiting until the
-author says the work is ready both makes the advice relevant and makes it clear what it is
-about.
+Feedback on unfinished parts can become irrelevant before review. Contributors can then
+ignore later advice, including useful findings. A readiness signal identifies the work the
+author considers complete.
 
-Where an agent must run earlier, it SHOULD scope its advice to what is stable, and MUST NOT
+If an agent must run before readiness, it SHOULD limit advice to stable work. It MUST NOT
 present provisional findings as conclusions.
 
 ## Advice is legible
 
-An advisory agent's output MUST make clear what it is: which agent produced it, what it
-examined, and that it is advice rather than a gate.
+An advisory agent's output MUST identify which agent produced it, what it examined, and its
+status as advice rather than a gate.
 
-An unattributed conclusion is indistinguishable from a requirement, and a reviewer who cannot
-tell the difference either treats optional advice as blocking or treats a real constraint as
-optional. Naming the source also makes the agent's own failures diagnosable: advice that is
-consistently wrong is a fixable bug in the agent, but only if it is traceable to the agent.
+Without attribution, reviewers can confuse advice with a requirement. Attribution also lets
+maintainers trace incorrect advice to its source and correct the agent.
 
-Where advice rests on a rule, it MUST cite the documentation that carries the rule, so the
-reviewer can check the rule rather than trusting the agent's summary of it. An agent MUST NOT
-introduce a requirement that no documentation states — if the rule is real it belongs in
-documentation, and if it is not, the agent is inventing policy.
+When advice depends on a rule, it MUST cite the documentation that states that rule.
+The reviewer can then verify the source instead of relying on the agent's summary.
+An agent MUST NOT introduce a requirement that no documentation states. A required rule
+belongs in the documentation.
 
 ## Composition
 
-Several advisory agents MAY examine the same artifact, and MUST NOT depend on each other's
-output or on the order in which they run.
+Several advisory agents MAY examine the same artifact. They MUST NOT depend on each other's
+output or execution order.
 
-Independence is what keeps them cheap to add and remove. A chain of advisors is a pipeline
-with failure modes, and a pipeline whose stages are opinions has failure modes nobody can
-debug.
+Maintainers can add or remove independent agents without changing other agents. If one opinion
+depends on another, failures can become difficult to isolate.
 
-Where two advisors disagree, both conclusions stand and the human resolves them. That is not
-a defect in the design; disagreement between two opinions is information, and suppressing it
-would mean picking a winner arbitrarily.
+If advisors disagree, both conclusions remain available and a human resolves the disagreement.
+Suppressing one opinion would hide evidence from that review.
 
 ## Where this connects
 

src/docs/Capabilities/agentic-development/agent-interaction.md

@@ -5,13 +5,11 @@ description: How humans and agents coordinate through issues, labels, and pull r
 
 # Agent Interaction
 
-Once more than one participant works a repository — several people, several agents, or a mix
-— they need somewhere to coordinate. The tempting answer is a conversation: a chat, a thread,
-a prompt history. The problem with a conversation is that it is not part of the repository.
-It cannot be reviewed, it cannot be queried, and it disappears when the session does.
+Human and agent participants need durable coordination when they work in the same repository.
+A conversation outside the platform artifacts does not provide the repository's reviewed
+work record. It can become unavailable when the session ends.
 
-The platform already provides durable coordination artifacts. This page states how the
-framework uses them.
+The framework uses the platform's issues, labels, and pull requests as that record.
 
 ## Coordination happens on artifacts
 
@@ -20,18 +18,16 @@ labels, and pull requests — rather than through any channel that leaves no tra
 repository.
 
 The rule follows from
-[everything as code](../../Ways-of-Working/Principles/Engineering-Practices.md#everything-as-code):
-if the decision is not in the repository, the repository does not record why it looks the way
-it does. It also follows from practical asymmetry — an agent's session ends and takes its
-context with it, while an issue persists and can be picked up by a different agent, a
-different runtime, or a person, weeks later.
+[everything as code](../../Ways-of-Working/Principles/Engineering-Practices.md#everything-as-code).
+Repository artifacts preserve decisions and their reasons. Unlike session context, an issue
+remains available to another agent, runtime, or person after the original session ends.
 
 | Artifact | What it carries | Why it, specifically |
 | --- | --- | --- |
 | **Issue** | The intent: what is wanted, why, and what "done" means | Durable, addressable, and independent of who acts on it |
 | **Label** | A discrete decision or state transition | Machine-readable, so automation can react without parsing prose |
-| **Pull request** | The proposed implementation, and the negotiation over it | Reviewable line by line, and revertible as one unit |
-| **Comment** | Reasoning, questions, and advice attached to its subject | Stays with the artifact it concerns rather than in a separate stream |
+| **Pull request** | The proposed implementation and its review | Reviewable line by line, and revertible as one unit |
+| **Comment** | Reasoning, questions, and advice attached to its subject | Keeps reasoning with the relevant artifact |
 
 ## Two artifacts, two questions
 
@@ -43,15 +39,14 @@ governs the issue body. Task and Bug leaves retain technical decisions and test-
 the pull request contains the proposed implementation. Consumer-only aggregate guidance does
 not remove those delivery plans.
 
-The separation earns its keep at rejection. When a single artifact holds both, discarding a
-bad implementation discards the reasoning that motivated it, and the next attempt starts from
-nothing. When they are separate, the pull request closes and the issue stands — still stating
-what is needed, now with a documented approach that did not work.
+The issue preserves the request when reviewers reject a proposed implementation.
+The pull request can close while the issue remains open. The rejected pull request records
+the attempted approach. A later proposal can use that evidence without reconstructing the
+original intent.
 
-It also puts each question in front of the right reviewer. Whether something *should* be done
-is a question about priorities and fit; whether an implementation is *correct* is a question
-about the code. These are different judgements, often made by different people, and merging
-them into one thread means the cheaper question crowds out the harder one.
+This separation also supports different review questions. Priority and fit determine whether
+work is needed. Implementation review determines whether the proposed change is correct.
+The reviewers for these questions can differ.
 
 ```mermaid
 flowchart LR
@@ -60,56 +55,51 @@ flowchart LR
     impl -->|"accepted"| merged["Merged"]
 ```
 
-The consequence is a rule about creation order: an issue exists before the work that resolves
-it. Where a change is genuinely trivial, the pull request MAY stand alone, but it then carries
-its own statement of intent, because something has to.
+An issue exists before work starts to resolve it. For a genuinely trivial change, the pull
+request MAY stand alone, but it contains its own statement of intent.
 
 ## Labels are the control channel
 
 Where automation must be told something, it MUST be told with a label rather than with prose.
 
-Prose is where humans express nuance, which is exactly what makes it a poor instruction to a
-machine: parsing it means guessing, and a guess about whether a maintainer approved something
-is a guess with consequences. A label is unambiguous, appears in the artifact's timeline with
-who applied it and when, and can be required or forbidden by a rule.
+Prose records reasoning and nuance. A label records an explicit machine-readable signal,
+including who applied it and when. Rules can require or prohibit that signal without
+inferring approval from a sentence.
 
 Labels used for coordination MUST follow the organization's
-[label vocabulary](../../Ways-of-Working/Automation-Labels.md), so that a label's owner and
-meaning are knowable without reading the workflow that consumes it. Automation MUST ignore
+[label vocabulary](../../Ways-of-Working/Automation-Labels.md). Its owner and meaning can
+then be determined without reading the workflow that consumes it. Automation MUST ignore
 labels it does not own.
 
 ## An agent is a participant, not an authority
 
 An agent operating on these artifacts MUST do so under the same rules as any other
 participant.
 
-That means it opens issues and pull requests rather than pushing to protected branches, its
-changes are reviewed, and its conclusions are advice until someone acts on them. The
+Agents open issues and pull requests instead of pushing to protected branches. Their changes
+receive review, and their conclusions remain advice until someone acts on them. The
 [four-eyes principle](../../Ways-of-Working/Principles/AI-First-Development.md#4-eyes-or-n-eyes-principle)
-does not weaken because one pair of eyes is automated; an agent reviewing an agent is
-[advisory](advisory-agents.md), and human authority over the merge remains.
+applies to automated participants too. An agent's review of another agent's work is
+[advisory](advisory-agents.md). Humans retain merge authority.
 
-The symmetry is deliberate. A process that gave agents a privileged path would have two sets
-of rules, and the agent path would be the one nobody audits.
+The same rules keep agent work subject to the same review controls as human work.
 
 ## Handover is a state, not a message
 
-Work passed from one participant to another MUST be handed over through the artifact's own
-state — its labels, its assignment, its review status — and MUST NOT depend on a message
-having been delivered.
+Participants MUST hand over work through the artifact's state: labels, assignment, or review
+status. Handover MUST NOT depend on delivery of a message.
 
-An agent that finishes its part and describes the next step in a comment has produced
-something a human must read and act on. An agent that finishes its part and moves the
-artifact into the state the next stage reacts to has produced something the process picks up.
-The first is a notification; the second is a handover.
+A comment that names the next step requires a reader to act on it. A state change supplies
+the signal that the next stage uses. The comment is a notification; the state change is the
+handover.
 
-This is what allows a chain of work to survive interruption. Any participant can determine
-what happens next by looking at the artifact, without reconstructing a conversation.
+Artifact state preserves the handover across session interruptions. A participant can
+determine the next step from that state without reconstructing a conversation.
 
 ## Where this connects
 
 - [Spec](spec.md#requirements) — the requirement that coordination happens on durable artifacts and that intent is separable from implementation.
-- [Advisory Agents](advisory-agents.md) — how an agent publishes judgement onto these artifacts without taking authority.
+- [Advisory Agents](advisory-agents.md) — how an agent publishes judgment onto these artifacts without taking authority.
 - [Automation Labels](../../Ways-of-Working/Automation-Labels.md) — the label vocabulary and ownership rules.
 - [Workflow](../../Ways-of-Working/Workflow.md) — the stages these artifacts move through.
 - [Issues](../../Ways-of-Working/Issues/index.md) and [Issue Planning](../../Ways-of-Working/Issues/Process/Planning.md) — issue discovery and type-specific intent and delivery planning.