diff --git a/src/docs/Capabilities/agentic-development/AGENTS.template.md b/src/docs/Capabilities/agentic-development/AGENTS.template.md index 0e9f097a..8d31ad0c 100644 --- a/src/docs/Capabilities/agentic-development/AGENTS.template.md +++ b/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. diff --git a/src/docs/Capabilities/agentic-development/advisory-agents.md b/src/docs/Capabilities/agentic-development/advisory-agents.md index 122448ae..b81a3090 100644 --- a/src/docs/Capabilities/agentic-development/advisory-agents.md +++ b/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 diff --git a/src/docs/Capabilities/agentic-development/agent-interaction.md b/src/docs/Capabilities/agentic-development/agent-interaction.md index ef9ed3b5..d14edd6f 100644 --- a/src/docs/Capabilities/agentic-development/agent-interaction.md +++ b/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,22 +55,20 @@ 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 @@ -83,33 +76,30 @@ labels it does not own. 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. diff --git a/src/docs/Capabilities/agentic-development/conformance.md b/src/docs/Capabilities/agentic-development/conformance.md index 00fe305c..343c9d8e 100644 --- a/src/docs/Capabilities/agentic-development/conformance.md +++ b/src/docs/Capabilities/agentic-development/conformance.md @@ -5,13 +5,12 @@ description: What a repository must provide to be conformant with the agentic de # Conformance -A framework that cannot be checked is a preference. This page states what conformance to -agentic development means for a single repository: the baseline it MUST provide, what it MAY -add, and the conditions that indicate it has drifted. +Conformance defines the required files, context resolution, and duplication limits for a +repository. This page states the baseline it MUST provide, what it MAY add, and how to +identify a deviation. -The checks are deliberately structural. Whether a repository's documentation is *good* is a -review question; whether its agent context resolves correctly is a property that can be -determined by looking. +These checks assess structure and content. Documentation quality requires review; file and +content inspection establishes whether agent context resolves correctly. ## The mandatory baseline @@ -26,18 +25,15 @@ A conformant repository MUST provide all of the following. | **Freshness** | Canonical context is synchronized at the start of every session, in every runtime ([context freshness](design.md#context-freshness)) | | **Precedence** | The router states that local files never override a standard | -The baseline is small on purpose. Every item is something an agent needs before it can find -anything else; nothing on the list is a judgement about how the repository should be -documented. +Each baseline item supports context discovery. The baseline does not assess the quality of +the repository's documentation. ## The router stays thin The router MUST NOT restate a standard. -This is the check that decays fastest, because adding one useful line to the router is always -easier than finding where that line belongs. A router that has grown into a summary is the -worst of both outcomes: it is not authoritative, so it may be wrong, and it is convenient, so -it is what gets read. +A router can accumulate copied rules when contributors add summaries instead of links. +Readers can then use a convenient summary that differs from its authoritative source. A repository is non-conformant where any of these hold: @@ -49,12 +45,12 @@ A repository is non-conformant where any of these hold: - A named intent carries a copy of the procedure it invokes ([plugin distribution](plugin-distribution.md)). -Each of these is the same fault: one fact in two places, which is -[one fact one place](../../Ways-of-Working/Documentation-Model.md) violated, and which -resolves in whichever direction the reader happens to look first. +These cases either duplicate guidance or put guidance in a file that does not own it. +They violate [one fact one place](../../Ways-of-Working/Documentation-Model.md). +The order in which files are read can then affect the applied rule. -The remedy is always the same, and it is not deletion of the content: move the content to the -layer that owns it, then reduce the local file to a pointer. +Move the affected content to the layer that owns it, then reduce the local file to a pointer. +Do not remove required information merely to shorten the router. ## What a repository may add @@ -62,11 +58,10 @@ Beyond the baseline, a repository MAY add: - **Path-scoped rules**, for a caveat that is genuinely local to a directory and cannot be stated as a standard. -- **Runtime adapters**, for a client the organization has not yet standardized on, provided the +- **Runtime adapters**, for a client outside the organization's standard set, provided the adapter is a route and adds no content. - **Named intents**, for recurring workflows, provided they remain pointers. -- **Repository-specific documentation**, which is normal and expected — the constraint is on - restating standards, not on documenting the repository. +- **Repository-specific documentation**, without copies of shared standards. An addition MUST NOT introduce a requirement. Where local practice differs from a standard, the resolution is to change the standard or to record an @@ -75,8 +70,7 @@ only agents will read it. ## Levels -Conformance is graded, so that a repository can be positioned honestly rather than being -either compliant or not. +The levels distinguish required baseline checks from stricter consistency and runtime checks. | Level | Meaning | | --- | --- | @@ -84,23 +78,20 @@ either compliant or not. | **Consistent** | Baseline, plus no duplication findings: no local file restates a standard | | **Uniform** | Consistent, plus every supported runtime resolves identically, and the shared tool layer is declared in each ([MCP servers](mcp-servers.md)) | -Only **Baseline** is required. The higher levels describe a repository whose agent context -needs no per-runtime knowledge to work with, which is the state the framework is aiming at. +Only **Baseline** is required. The higher levels describe context that does not require +runtime-specific knowledge. ## Checking Conformance MUST be checkable without running an agent. -The baseline is a set of file and content properties, and duplication is detectable by -comparing local text against the standards it might be restating. Both are amenable to the -same [drift detection](../repository-governance/design.md#drift-detection-and-reconciliation) -the organization already applies to repository structure, and a conformance finding MUST name -its remedy for the same reason every other finding does: a finding that only reports a problem -becomes a number people learn to ignore. +The baseline uses file and content properties. Comparing local text with canonical standards +identifies duplication. Both kinds of finding fit the +[drift detection](../repository-governance/design.md#drift-detection-and-reconciliation) +model. A conformance finding MUST name its remedy so a maintainer can act on it. -Determining conformance by asking an agent whether it understood the repository MUST NOT be -treated as a check. The answer is generated from the same context whose adequacy is in -question. +An agent's report that it understood the repository MUST NOT count as a conformance check. +That answer depends on the same context being assessed. ## Where this connects diff --git a/src/docs/Capabilities/agentic-development/decisions/index.md b/src/docs/Capabilities/agentic-development/decisions/index.md index d414191c..2a058eb8 100644 --- a/src/docs/Capabilities/agentic-development/decisions/index.md +++ b/src/docs/Capabilities/agentic-development/decisions/index.md @@ -8,4 +8,4 @@ description: Immutable records of one-way-door choices in the agentic developmen These records explain choices that constrain the framework. A later decision supersedes an earlier one; it does not rewrite it. -There are currently no decisions recorded for this capability. +No decision records are listed for this capability. diff --git a/src/docs/Capabilities/agentic-development/design.md b/src/docs/Capabilities/agentic-development/design.md index 2f6e3157..b26d9b52 100644 --- a/src/docs/Capabilities/agentic-development/design.md +++ b/src/docs/Capabilities/agentic-development/design.md @@ -5,7 +5,7 @@ description: How the agentic development framework is built — OKF documentatio # Agentic Development — Design -The behavior in the [spec](spec.md) is delivered by an organization-level documentation repository, adopted by each product repository through thin pointer files. The design keeps project knowledge in one reviewed place and lets each agent runtime adapt without copying process knowledge. The repository name is not fixed; the organization identifies the source that owns its documentation. +The [spec](spec.md) defines the framework's behavior. An organization-level documentation repository owns reviewed project knowledge. Each product repository adopts that guidance through thin pointer files. Each runtime uses the same process knowledge without copying it. The organization selects its documentation repository; the repository name is not fixed. ## Organization anatomy @@ -18,7 +18,7 @@ The GitHub organization is the project boundary. The host distinguishes work fro / ``` -Current project scopes follow the same shape: +The project scopes use these documentation sources: | Host | Organization | Canonical documentation repository | | --- | --- | --- | @@ -26,7 +26,7 @@ Current project scopes follow the same shape: | `github.com` | `PSModule` | `PSModule/Process-PSModule` | | `` | `` | Designated `/` | -The last row is the general case: any adopting organization on any GitHub host — public or an enterprise instance — plugs into the same shape without changing the framework. +An adopting organization uses the same model on a public or enterprise GitHub host. It selects the canonical documentation repository without changing the framework. ## Repository roles @@ -60,13 +60,15 @@ Product repositories carry local context and thin pointers: docs/ # architecture and domain context ``` -The repository owns only repository-specific nuance, and each kind has a file that owns it: `README.md` for what the repository is and how it builds, `.github/CONTRIBUTING.md` for contribution mechanics [when a local guide is needed](../../Ways-of-Working/Repository-Standard.md#contribution-guidance), `docs/` for architecture and domain context, and path-scoped rule files for local caveats. `AGENTS.md` points at them and holds none of it. Cross-cutting standards remain in `docs`. Thin means "no duplicated reusable process," not "discard the local operating contract" — the contract lives, it just lives in the file a human would read. +`README.md` describes the repository and its build. `.github/CONTRIBUTING.md` defines contribution mechanics [when a local guide is needed](../../Ways-of-Working/Repository-Standard.md#contribution-guidance). `docs/` describes architecture and domain context. Path-scoped rule files hold local caveats. + +`AGENTS.md` points to those sources; it does not contain their content. Cross-cutting standards remain in the canonical organization documentation. A thin router does not duplicate reusable process. Each repository-specific contract remains in the file that owns it. Inherited community files are not included in clones. When no local contribution guide is needed, the router links 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; do not create a local guide merely to fill a router entry. ## OKF page model -The `docs` repository uses the [Open Knowledge Format](../../Dictionary/index.md#open-knowledge-format) style: Markdown with YAML frontmatter, one concept per page, paths as stable identity, and indexes as navigation maps. +The `docs` repository uses the [Open Knowledge Format](../../Dictionary/index.md#open-knowledge-format) style: Markdown with YAML frontmatter, one concept per page, paths as stable identity, and indexes for navigation. Minimum page frontmatter: @@ -81,7 +83,7 @@ The body stays concise. If a page grows into multiple concepts, split it and lin ## Indexes as the mindmap -Indexes are the navigation layer. An agent starts at the root index, reads descriptions, then drills inward until it reaches the relevant page. +Indexes provide documentation navigation. The agent starts at the root index and reads the page descriptions. The agent follows index links until it reaches the relevant page. ```text docs/ @@ -95,7 +97,7 @@ docs/ ``` -Every index describes what sits below it. Generated indexes are preferred where tooling exists. +Every index describes the pages and sections below it. Generated indexes are preferred where tooling exists. ## Context resolution flow @@ -129,7 +131,7 @@ flowchart TD newpath -->|"No"| done["Respond, commit, or open PR"] ``` -Resolution is deterministic. If the active repository remote is `github.com/PSModule/Json`, the selected project context is `PSModule`; if it is `github.com/MSXOrg/docs`, the selected project context is `MSXOrg`. Multi-root workspaces use the active file, explicit user prompt, current terminal directory, or branch repository to select the project. Ambiguity is resolved by asking the user before acting. +The active repository remote selects project context. For `github.com/PSModule/Json`, the context is `PSModule`. For `github.com/MSXOrg/docs`, the context is `MSXOrg`. In a multi-root workspace, the active file, explicit user prompt, terminal directory, or branch repository selects the project. If that context is ambiguous, ask the user before acting. ## Pointer files @@ -154,11 +156,13 @@ clone, and update it before reading it. Read nearest first. A local file never overrides a standard. ``` -A router lists the destinations that actually exist — the ones above are an example, not a required layout. Replace the optional local contribution entry with a link to the inherited organization default when no local guide is needed. A repository with no documentation of its own drops that line; one that publishes the standards resolves steps 3 and 4 to the same tree and drops the duplicate. Writing a real path or source link matters more than matching the example, because the router is read literally. +A router lists only destinations that exist. The example does not require that layout. When no local guide is needed, replace that entry with a link to the inherited organization default. If the repository has no documentation, omit that entry. A standards repository omits the duplicate entry when its local and organization documentation use the same tree. The router uses each path or source link literally. + +The index trail is the default route. A clear prompt can select a stage directly. `Review this PR ` enters Review. `Make this issue ` enters Define. `Implement ` enters Implement. -The index trail is the default. A clear prompt can shortcut stage discovery: `Review this PR ` enters Review, `Make this issue ` enters Define, and `Implement ` enters Implement. These phrases are routing hints interpreted by [Workflow](../../Ways-of-Working/Workflow.md#find-the-current-stage), not commands with independent procedures. +[Workflow](../../Ways-of-Working/Workflow.md#find-the-current-stage) interprets these phrases as routing hints. They do not define independent procedures. -> **Reading order vs. conflict precedence** — the router reads the repository's own files first and widens outward, because nearest context is cheapest and most specific. Precedence runs the other way: repository files add nuance and narrow exceptions and never silently override an organization standard unless that standard permits a local exception. +> **Reading order vs. conflict precedence** — the router reads repository files before organization documentation. This order provides specific context before broader context. Conflict precedence runs in the opposite direction: repository files add detail and narrow exceptions. They do not override an organization standard unless that standard permits a local exception. `.claude/CLAUDE.md` is a single import: @@ -166,7 +170,7 @@ The index trail is the default. A clear prompt can shortcut stage discovery: `Re @../AGENTS.md ``` -Claude Code accepts either `./CLAUDE.md` or `./.claude/CLAUDE.md` as the project file, and resolves a relative import against the file that contains it — so from `.claude/`, the router is `../AGENTS.md`. Writing `@AGENTS.md` there would resolve to `.claude/AGENTS.md` and silently load nothing. +Claude Code accepts either `./CLAUDE.md` or `./.claude/CLAUDE.md` as the project file. It resolves each relative import from the file that contains it. From `.claude/`, the router is `../AGENTS.md`. An import of `@AGENTS.md` instead resolves to `.claude/AGENTS.md`, so it does not load the repository router. `.github/copilot-instructions.md` has the same shape, for the Copilot surfaces that do not read `AGENTS.md`: @@ -174,15 +178,14 @@ Claude Code accepts either `./CLAUDE.md` or `./.claude/CLAUDE.md` as the project Follow the instructions in [AGENTS.md](../AGENTS.md). ``` -That is the entire file. It holds no reading order, no workflow, and no standard, so there is nothing in it that can fall out of step with the router. Any future runtime is handled the same way: give it a route under whatever filename it reads, and leave the content in `AGENTS.md`. +The file contains only that pointer. It does not duplicate reading order, workflow, or standards. Other runtimes use a route under their recognized filename and keep shared content in `AGENTS.md`. Path-scoped instruction files are reserved for local rules that cannot live centrally because they apply only to a repository path, and only when the rule does not belong in `README.md` or `.github/CONTRIBUTING.md` instead. They never define workflow stages. ## Local workspace -A runtime or development setup may materialize a documentation repository in -any context checkout it controls. The framework does not prescribe that -checkout's filesystem location. +A runtime or development setup can create a documentation context checkout at a +location it controls. The framework does not prescribe that filesystem location. Before context is read, the agent ensures the clone exists, fetches its remote, and fast-forwards its default branch. Each clone must be clean, checked out on @@ -196,14 +199,11 @@ verified. ## Context freshness -The freshness gate is only worth as much as the last time it ran. A clone -synchronized once is current at that moment and progressively less so -afterwards, and an agent reading a week-old clone reads a standard that has -since changed while believing it is canonical. +Git synchronization establishes freshness at session start. A clone can become +stale after synchronization when its remote changes. -So Git synchronization runs at the **start of every session**, not once per -machine. What differs between runtimes is where the trigger hangs, never what -it does: +Synchronization runs at the **start of every session**, not once per machine. +Each runtime uses its lifecycle point for the same check: | Runtime shape | Lifecycle point | How context freshness is established | | --- | --- | --- | @@ -212,24 +212,22 @@ it does: | Review-time agent | Pull request event | Instructions are read from the pull request's head branch, so freshness follows the branch under review rather than a local clone. | | Batch or scheduled agent | Job start | The job's first step clones or synchronizes the context repository; a scheduled run has no earlier lifecycle point to rely on. | -Each of these is one **declaration** of the same behavior. The runtime ensures -the clone is clean, on the remote default branch, and exactly equal to the -fetched head before context is read. A runtime may use its own lifecycle hook, -or the agent may perform the Git check explicitly. +Each runtime declares the same behavior. Before context is read, the runtime +verifies that the clone is clean, on the remote default branch, and exactly +equal to the fetched head. The runtime can use its lifecycle hook, or the agent +can perform the Git check explicitly. -The synchronization MUST be idempotent, because it runs far more often than it -changes anything. A process that is expensive or noisy when everything is -already current gets disabled, and a disabled process is worse than no process, -because the workspace still appears synchronized. +Synchronization MUST be idempotent. It runs each session even when the remote +has not changed. Excessive cost or output can lead operators to disable it. +The workspace can then appear current without a freshness check. -Where a runtime offers no lifecycle point at all, Git synchronization MUST be -invoked explicitly before context is read. It MUST NOT be skipped on the -grounds that the workspace was synchronized recently; "recently" is not a state -the agent can observe, and the gate exists precisely to replace that judgment -with a check. +Where a runtime offers no lifecycle point, Git synchronization MUST run +explicitly before context is read. It MUST NOT be skipped because the workspace +was synchronized recently. The Git check establishes observable state; elapsed +time does not. -Each shape's obligations beyond context freshness — its entry file, tool declaration, and identity — -are set out in [Runtime Integration](runtime-integration.md). +[Runtime Integration](runtime-integration.md) defines each shape's other +obligations: entry file, tool declaration, and identity. ## Client behavior @@ -243,7 +241,7 @@ Different clients load different files, but the framework keeps the same depende | Copilot surfaces without `AGENTS.md` support | `.github/copilot-instructions.md` | Copilot Chat on GitHub.com, Visual Studio, JetBrains, Eclipse, and Copilot code review outside GitHub.com read this file. It routes them to the router and adds nothing else. | | Copilot code review | Head-branch instructions | Reads repository instructions, agent instructions, and skills from the pull request's **head** branch, not the base branch. | -Because Copilot code review reads the head branch, a pull request that changes `AGENTS.md`, a client route, or a path-scoped instruction file also changes the instructions used to review that pull request. Those files are therefore reviewed by a human on their own merits, and an automated approval is never treated as independent of them. What this means for repositories that accept outside contributions is still open — see [MSXOrg/docs#123](https://github.com/MSXOrg/docs/issues/123). +Copilot code review uses the head-branch versions of `AGENTS.md`, client routes, and path-scoped instruction files. A pull request that changes these files also changes the instructions for its own review. Human review assesses these files directly. Automated approval does not provide an independent assessment of the instructions that produced it. The outside-contribution trust boundary is tracked in [MSXOrg/docs#123](https://github.com/MSXOrg/docs/issues/123). ## Failure modes @@ -263,7 +261,7 @@ Because Copilot code review reads the head branch, a pull request that changes ` 2. Add the canonical Workflow and linked stage procedures to `docs`. 3. Add the `AGENTS.md` router to each product repository, plus a route for every client that cannot read it. 4. Document the canonical docs clone and require Git synchronization before use. -5. Review new work for pointer discipline: facts live once, links point to them. +5. Review new work for pointer discipline: each fact has one source, and other files link to it. ## Where this connects diff --git a/src/docs/Capabilities/agentic-development/index.md b/src/docs/Capabilities/agentic-development/index.md index b29e9ad0..66dc6383 100644 --- a/src/docs/Capabilities/agentic-development/index.md +++ b/src/docs/Capabilities/agentic-development/index.md @@ -1,13 +1,13 @@ --- title: Agentic Development -description: The framework for org-scoped documentation that gives agents project-specific standards and behavior. +description: Organization-scoped documentation for project-specific agent standards and behavior. --- # Agentic Development -The Agentic Development framework makes an organization the operating boundary for human and agent work. Each organization identifies a canonical documentation repository; every product repository carries a short router that points to that source and keeps its own nuance in the files a human already reads. +The Agentic Development framework uses the GitHub organization as the boundary for human and agent work. Each organization identifies a canonical documentation repository. Each product repository routes agents to that source through a short router. Repository-specific guidance stays in the files that also serve human readers. -A repository adopts the framework by carrying a short router and the client routes that reach it, and by letting agents read outward — the repository's own files first, then the organization documentation, then the current task. The organization selects *which* context applies; the reading order decides what is read first. +A repository adopts the framework with a router and the client routes that reach it. Agents read repository context, then organization and inherited ecosystem documentation, then task context. The organization selects which standards apply. Reading order determines when each source is read. diff --git a/src/docs/Capabilities/agentic-development/mcp-servers.md b/src/docs/Capabilities/agentic-development/mcp-servers.md index bfa0bdc3..dc86fec9 100644 --- a/src/docs/Capabilities/agentic-development/mcp-servers.md +++ b/src/docs/Capabilities/agentic-development/mcp-servers.md @@ -5,48 +5,39 @@ description: How one logical set of tool servers is defined once and declared by # MCP Servers -An agent that can only read files is limited to what the repository already knows. Useful -work needs the platform itself: opening an issue, reading a pull request, querying a -tracker, fetching a reference. Those capabilities reach the agent through **tool servers** -declared by the runtime — the [Model Context Protocol](https://modelcontextprotocol.io/) is -the interface they present. +Agents use tool servers to work with platform data outside the repository. Examples include +issues, pull requests, trackers, and reference sources. Runtimes declare these **tool servers**, +which expose the [Model Context Protocol](https://modelcontextprotocol.io/) interface. -The design question is not which servers exist. It is whether they are the *same* servers -everywhere. +The framework defines a shared server set, not a catalog of specific services. ## One logical layer -The set of tool servers available to agents MUST be defined once, as a property of the -organization rather than of a runtime. +The organization MUST define one set of tool servers for its agents, independent of the runtime. -The alternative is what happens by default: each runtime accumulates the servers whoever -configured it happened to need. The result is a documented procedure that works in one -client and fails in another, and the failure is not legible — the agent does not report -"this client lacks that tool", it reports that it could not do the thing. A contributor then -concludes the procedure is wrong. +Separate runtime configurations can expose different servers. A documented procedure can then +work in one client and fail in another. Without an explicit missing-tool error, a contributor +cannot distinguish a configuration gap from an incorrect procedure. -A shared layer makes capability a fixed premise. When documentation says an agent opens an -issue, that instruction holds for every agent, because the server that opens issues is part -of the layer rather than part of someone's local setup. +A shared layer fixes the available capabilities across runtimes. If a documented procedure +opens an issue, every runtime declares the server that provides that capability. | Server kind | Why the layer includes it | | --- | --- | | **Source platform** | Issues, pull requests, reviews, and repository metadata are the artifacts the process is defined in terms of ([agent interaction](agent-interaction.md)) | -| **Issue tracker** | Where planning lives, when it lives outside the source platform | -| **Knowledge base** | Where reference material lives, when it is not in a `docs` repository | +| **Issue tracker** | Planning data when it is outside the source platform | +| **Knowledge base** | Reference material outside a `docs` repository | | **Organization-specific services** | Whatever else the organization's procedures name | -The kinds are stable; the specific services are the organization's choice. What matters is -that the choice is made once. +The organization chooses the specific services once for all runtimes. ## Same contract, different declaration syntax Every runtime MUST declare the same logical set, in its own native configuration format. -Runtimes disagree about where server configuration lives, what the file is called, and how a -server's transport and credentials are expressed. None of that is worth fighting. What is -worth insisting on is that the *contract* — which servers, offering which capabilities — is -identical, so translation is mechanical: +Each runtime uses its native configuration syntax for the same server contract. File +locations, schemas, transports, and credential declarations can differ. The logical server +set and capabilities remain identical: ```text one logical server set @@ -56,9 +47,9 @@ one logical server set └──> runtime C: its own configuration file, its own schema ``` -This is the same relationship the framework already uses for instructions, where -[client routes](design.md#client-behavior) differ in filename and are identical in content. A -declaration is a route to a capability, and a route holds nothing that can drift. +This matches the framework's [client routes](design.md#client-behavior): filenames can differ +while each route points to the same instructions. A server declaration likewise connects a +runtime to the shared capabilities without copying process rules. The consequence is a rule about additions: adding a server means adding it to the logical set and then to every runtime's declaration. A server declared in one runtime only is a local @@ -68,32 +59,28 @@ convenience, and MUST NOT be relied on by documentation. The layer defines *which* servers and *what* they offer. It MUST NOT carry credentials. -Authentication is per-operator and per-environment: a local agent authenticates as the -person running it, a hosted agent as the identity its environment grants. Both reach the -same servers with different permissions, and that difference is correct — it is -[least privilege](../../Ways-of-Working/Principles/Purpose-and-Direction.md#least-privilege) -working as intended. A server declaration that embedded a credential would either leak it or -force every agent to share one identity. +Authentication depends on the operator and environment. A local agent uses the operator's +identity; a hosted agent uses the identity its environment grants. Both reach the same +servers with different permissions under +[least privilege](../../Ways-of-Working/Principles/Purpose-and-Direction.md#least-privilege). +An embedded credential can expose a secret or force agents to share one identity. -So a declaration names the server and how to reach it, and resolves its credential from the -environment. An agent that cannot authenticate to a server MUST fail visibly rather than -silently proceeding without the capability, because a procedure that assumed the capability -will otherwise produce a confusing partial result. +A declaration names the server and its connection settings. It resolves credentials from +the environment. If an agent cannot authenticate to a server, it MUST fail visibly rather +than continue without the capability. Otherwise, a documented procedure can produce a +partial result. ## Tools do not replace documentation -A tool server changes what an agent *can do*. It MUST NOT change what the agent is *supposed -to do*. +A tool server provides capabilities. It MUST NOT change the agent's documented procedure. -The distinction matters because tool descriptions are themselves instructions, and a -capable server is tempting to treat as guidance: it knows how to open an issue, so let it -decide what an issue should contain. That inverts the framework — the procedure for opening -an issue is documentation, and the server is how the documented result is achieved. +Tool descriptions are instructions about tool use. The documentation, not the server, +defines what an issue must contain. The server provides the operations that produce the +documented result. A server MUST NOT be the source of a process rule, for the same reason a -[skill or command MUST NOT define a workflow stage](spec.md#requirements): a rule that lives -in a tool is a rule nobody reviews, and it disagrees with the documentation the moment either -one changes. +[skill or command MUST NOT define a workflow stage](spec.md#requirements). A rule stored only +in tool instructions can diverge from reviewed documentation. ## Where this connects diff --git a/src/docs/Capabilities/agentic-development/plugin-distribution.md b/src/docs/Capabilities/agentic-development/plugin-distribution.md index b4bd27d6..766f0c93 100644 --- a/src/docs/Capabilities/agentic-development/plugin-distribution.md +++ b/src/docs/Capabilities/agentic-development/plugin-distribution.md @@ -5,27 +5,23 @@ description: How recurring workflows are packaged as named intents that point to # Plugin Distribution -Some workflows recur often enough to earn a name. "Review this pull request", "open an issue -for this", "wrap up and hand off" — each is a procedure the organization has already -documented, invoked repeatedly, by everyone. +Recurring workflows can have **named intents**. Examples include "review this pull request", +"open an issue for this", and "wrap up and hand off". Each intent points to a documented +procedure. -Runtimes offer somewhere to put such things: a command, a skill, a named agent, a plugin. -The name differs; the shape does not. This page calls them **named intents**, and states what -one may contain. +Runtimes expose an intent as a command, skill, named agent, or plugin. This page defines what +that packaged entry point can contain. ## An intent is a pointer A named intent MUST resolve to the canonical documentation for its workflow and MUST contain only the runtime mechanics needed to get there. -This is the same rule that governs [client routes](design.md#client-behavior), applied to -behaviour instead of instructions, and for the same reason. An intent that restates its -procedure is a second definition of that procedure — one that no reviewer of the -documentation knows exists, and that starts disagreeing with the documentation the moment -either changes. Whichever one an agent happens to load then determines what the organization -appears to require. +The [client routes](design.md#client-behavior) rule also applies to workflow entry points. +An intent that restates a procedure creates a second definition. Either copy can change +without the other, so the agent's loaded copy can determine the apparent rule. -So the division is strict: +The content boundary is: | An intent MAY contain | An intent MUST NOT contain | | --- | --- | @@ -34,32 +30,28 @@ So the division is strict: | Runtime mechanics: which tools to enable, how to gather the current artifacts | A workflow stage definition | | Where to start reading | A copy of anything in `docs` | -The test is whether the intent would still be correct if the documentation changed. If it -would silently become wrong, it is carrying a copy. +The content check compares the intent with its canonical procedure. Repeated process steps +are copied content, not runtime mechanics. ## Why intents are worth having anyway -A pointer sounds like it adds nothing. What it adds is **reliable entry**. +Named intents provide **reliable entry** to documented procedures. -Without a named intent, reaching a procedure depends on the prompt being phrased in a way -that leads the agent to the right document. That usually works and occasionally doesn't, and -when it doesn't the agent invents a plausible process instead of following the documented -one. An intent removes the guess: the name maps to exactly one starting point. +Without an intent, procedure discovery depends on the prompt. The agent can select the wrong +document or substitute an undocumented process. A named intent maps the request to one +canonical entry point. -Named intents also make the set of recurring workflows **visible**. A runtime that lists its -available intents is showing the organization's procedures, which is a discovery path a -newcomer can use without knowing any file path. +A runtime's intent list also makes recurring workflows **visible**. A contributor can +discover a procedure without knowing its file path. ## One model, many runtimes -The set of named intents MUST be one shared model, and each runtime MUST express that same -set in its own format. +The set of named intents MUST be one shared model. Each runtime MUST express the same set +in its own format. -An intent available in one client and absent in another produces the failure mode the -framework exists to avoid: the same request behaves differently depending on which client -receives it, and no one can tell whether the difference is intended. Because an intent is -only a pointer plus mechanics, translating one into another runtime's format is mechanical — -there is no logic to port. +If runtimes expose different intent sets, the same request can use different procedures. +A pointer and its runtime mechanics can use each runtime's native format without copying +the procedure. ## Standards profile @@ -79,16 +71,16 @@ The portable package root contains only the Agent Plugins components. Skills liv commands, hooks, rules, or extensions belong under `com.github.copilot/`, where another client can ignore them without changing the portable contract. -Agent Skills use progressive disclosure: clients discover the `name` and `description`, -load `SKILL.md` when the request matches, and read referenced resources only when the -active skill needs them. A description therefore names both the capability and its trigger; -the body stays a short route and runtime procedure. +Agent Skills use progressive disclosure. Clients first discover the `name` and `description`. +When a request matches, they load `SKILL.md`. They read referenced resources only when the +active skill needs them. A description names both the capability and its trigger. +The body stays a short route with runtime mechanics. ## Marketplace structure and skill boundaries -The [Plugin Marketplaces design](design-plugin-marketplaces.md) is the single source of truth -for marketplace ownership, repository layout, plugin identities, and skill granularity. This -page covers how named intents are distributed; it does not repeat those structural rules. +The [Plugin Marketplaces design](design-plugin-marketplaces.md) owns marketplace ownership, +repository layout, plugin identities, and skill granularity. This page describes named-intent +distribution and links to those structural rules. For consumer upgrades, `msx-ways-of-working-consumer-upgrades` is the shared pointer to [Consumer Upgrades](../../Ways-of-Working/Consumer-Upgrades.md). @@ -109,9 +101,9 @@ Skills configured for Copilot CLI are also available in the [GitHub Copilot app](https://docs.github.com/en/copilot/how-tos/github-copilot-app/customize-github-copilot-app). The app also exposes installed plugins under **Settings > Plugins**. -An enterprise can publish the same marketplace and plugin to the app and every other -supported Copilot client through `copilot/managed-settings.json` in its `.github-private` -governance repository: +An enterprise can publish the same marketplace and plugin through +`copilot/managed-settings.json` in its `.github-private` governance repository. The settings +apply to the app and other supported Copilot clients: ```json { @@ -137,33 +129,28 @@ allowlist blocks every non-built-in marketplace. An intent MUST NOT bundle a copy of the documentation it points to. -Bundling is tempting because it makes an intent self-contained and therefore easy to -distribute. It is also how the framework's central premise gets broken: a bundled procedure -is a snapshot, and a snapshot distributed to many places is drift with extra steps. The -canonical documentation is available to every agent through the -[freshness gate](design.md#context-freshness); the intent can rely on it being there and current. +A bundled procedure is a snapshot that can differ from its canonical source. +Copies across installations can diverge independently. The intent relies on the +[freshness gate](design.md#context-freshness) for current canonical documentation. -The practical consequence is that updating a procedure needs no redistribution. The -documentation changes, and every intent pointing at it is immediately correct — which is the -whole reason the intent holds a pointer instead of a copy. +If its route remains valid, a procedure update does not require redistributing the intent. +The intent continues to resolve to the canonical procedure. ## Intents do not define process A named intent MUST NOT define a workflow stage, and MUST NOT add a requirement of its own. -The prohibition matters most where an intent looks like the natural place for a rule: a -review intent that "also checks X". If X is genuinely required, it belongs in the review -procedure, where it applies to every review including the ones nobody invoked an intent for. -If it is not required, the intent is inventing policy that no one reviewed. +A rule added only to a review intent does not apply to reviews reached by other routes. +If the rule is required, the canonical review procedure owns it. Otherwise, the intent +introduces unreviewed policy. -An intent whose contents grew past mechanics is a signal that the documentation is missing -something. The fix is to move the content into the documentation and shrink the intent back -to a pointer. +If an intent contains process content, move that content to its canonical documentation. +Reduce the intent to its pointer and runtime mechanics. ## Where this connects - [Spec](spec.md#requirements) — the requirement that named intents stay pointer-based and that no client convenience redefines a stage. -- [Design](design.md#pointer-files) — the pointer-file discipline this extends from instructions to behaviour. +- [Design](design.md#pointer-files) — the pointer-file discipline this extends from instructions to behavior. - [MCP Servers](mcp-servers.md) — the tool layer an intent's mechanics may enable, which likewise defines no procedure. - [Workflow](../../Ways-of-Working/Workflow.md) — the canonical stage procedures intents point at. - [Conformance](conformance.md) — the anti-duplication checks that catch an intent carrying a copy. diff --git a/src/docs/Capabilities/agentic-development/runtime-integration.md b/src/docs/Capabilities/agentic-development/runtime-integration.md index ddfb9cd0..6dde4c13 100644 --- a/src/docs/Capabilities/agentic-development/runtime-integration.md +++ b/src/docs/Capabilities/agentic-development/runtime-integration.md @@ -1,18 +1,15 @@ --- title: Runtime Integration -description: How a runtime is wired into the framework — the entry file it reads, the lifecycle point where it verifies context freshness, the permissions it needs, and what a new runtime must supply to be supported. +description: Requirements for a runtime's entry file, context freshness, tool declaration, identity, and permissions. --- # Runtime Integration -The framework is deliberately indifferent to which agent runtime a contributor uses. A -procedure documented once holds for every runtime, because a runtime supplies *capability -and lifecycle*, never process. +The framework supports different agent runtimes. A runtime supplies capabilities and +lifecycle points, not process rules. Each runtime follows the same documented procedure. -That indifference is not free. It holds only while each runtime is integrated the same way, -and a runtime integrated by improvisation becomes the one place where the documented process -is not what actually happens. So integration is itself a defined shape: four things a runtime -MUST supply, and nothing else. +Every runtime MUST supply the four integration elements below. These elements keep +runtime-specific mechanics separate from shared process. ## What a runtime must supply @@ -23,20 +20,19 @@ MUST supply, and nothing else. | **Tool declaration** | The shared tool server set, expressed in the runtime's own configuration format | [MCP Servers](mcp-servers.md#same-contract-different-declaration-syntax) | | **Identity** | The credential the runtime authenticates with, and the permissions that identity holds | [Permissions](#permissions-follow-the-identity-not-the-runtime) | -A runtime that supplies all four is supported. A runtime missing any of them is usable by a -human who knows what is missing, and MUST NOT be relied on by documentation — because the -documentation cannot say which part of the procedure will silently not happen. +A runtime that supplies all four elements is supported. A human who knows the gap can use +a runtime with a missing element. Documentation MUST NOT rely on such a runtime, because +part of the procedure can fail without a visible error. -Nothing on that list is process. That is the point: the list is short because integration -work is *plumbing*, and plumbing is where a new runtime's cost should be. +Integration covers entry files, lifecycle points, tool declarations, and identity. +Process remains in the canonical documentation. ## Runtime shapes, not runtime names -Integration differs by the **shape** of the runtime, not by which product it is. Shapes are -stable; the products occupying them change, and a design pinned to a product name expires -with it. +Integration depends on the runtime's **shape**, not its product name. A shape describes +where the runtime runs and when it can prepare context. -Four shapes cover the field: +The framework distinguishes four runtime shapes: | Shape | Where it runs | Distinguishing constraint | | --- | --- | --- | @@ -45,68 +41,63 @@ Four shapes cover the field: | **Review-time** | Triggered by a platform event on a pull request | Reads instructions from the branch under review, not from a local clone | | **Scheduled** | On a timer, with no human present | No earlier lifecycle point exists, and no one is watching a failure | -The same Git synchronization contract, the same router, and the same tool contract serve all -four. What changes is only where synchronization runs. +All four use the same Git synchronization contract, router, and tool contract. +Only the synchronization lifecycle point differs. ### Local interactive -The durable workspace is the hazard. A local runtime is the only shape whose context -survives between sessions, which means it is the only shape that can read a week-old standard -while believing it is canonical. +A durable local workspace can contain context from an earlier session. The runtime can +therefore read a stale standard as if it were current. -So Git synchronization MUST attach to a session-start lifecycle point in the runtime's own -configuration, and it MUST run before the first turn rather than on first use of context. +Git synchronization MUST run at a session-start lifecycle point in the runtime's own +configuration. It MUST run before the first turn, not on first context use. Where the runtime offers no session-start point, Git synchronization MUST be invoked explicitly before context is read. ### Hosted -A hosted runtime gets a fresh workspace per run, so staleness is not the risk — *absence* -is. The environment either establishes context during setup or the agent works without it. +A hosted runtime receives a fresh workspace for each run. Setup provides the required +context before the agent starts. -Git synchronization therefore belongs in the environment's setup steps, and setup failure MUST fail -the run. An agent that starts successfully against missing context produces work that looks -finished and was never governed, which is the most expensive failure in the set because it is -the one that reaches review looking normal. +The environment runs Git synchronization during setup. A setup failure MUST fail the run. +Without this failure signal, ungoverned work can appear complete at review. ### Review-time -A review-time runtime reads from the head branch of the pull request it is reviewing. This -inverts the usual freshness problem: context follows the branch under review, so a change to -the instructions is in effect for the very pull request that proposes it. +A review-time runtime reads instructions from the head branch of the pull request under +review. An instruction change therefore applies to the pull request that proposes it. -That is correct and worth stating, because it means a contributor can change agent behaviour -and see the result in the same review — and it means instruction changes MUST be reviewed as -carefully as code, since they are live before merge. +A contributor can change agent behavior and observe the result in the same review. +Reviewers MUST assess instruction changes as carefully as code because those instructions +apply before merge. ### Scheduled -A scheduled runtime has no lifecycle point earlier than the job itself, so Git synchronization -is the job's first step. It also has no human to notice a problem, which raises the bar on -failure handling: a scheduled run MUST fail loudly and MUST NOT proceed with partial context, -because a silent partial run repeats on the schedule. +The job itself is a scheduled runtime's first lifecycle point, so Git synchronization is +the job's first step. No human is present to observe a failure. A scheduled run MUST report +a visible failure and MUST NOT proceed with partial context. Otherwise, the same partial +run can repeat on the schedule. ## Permissions follow the identity, not the runtime -Every runtime reaches the same tool servers. What differs is the identity it authenticates -as, and therefore what it is permitted to do. +Every runtime reaches the same tool servers. Its authenticated identity determines +what it is permitted to do. A local runtime acts as the person operating it. A hosted or scheduled runtime acts as the identity its environment grants. A review-time runtime acts with whatever the platform event -provides. These are different permission sets reaching an identical tool contract, and the -difference is -[least privilege](../../Ways-of-Working/Principles/Purpose-and-Direction.md#least-privilege) -working as designed rather than an inconsistency to normalise. +provides. These permission sets use the same tool contract. Their differences implement +[least privilege](../../Ways-of-Working/Principles/Purpose-and-Direction.md#least-privilege); +they are not runtime inconsistencies. Two rules follow: -- A runtime MUST be granted the narrowest permission set its documented tasks require. A - runtime that only advises does not need write access, and - [advisory automation](advisory-agents.md) that holds it will eventually be asked to use it. -- A permission a runtime lacks MUST surface as a visible failure, never as a quietly skipped - step. An agent that cannot open an issue and continues anyway reports success for work that - did not happen. +- A runtime MUST have only the permissions its documented tasks require. A runtime that + only advises does not need write access. The + [advisory automation](advisory-agents.md) pattern separates advice from authority. +- If a required permission is missing, the runtime MUST report a visible failure rather + than skip the step. An agent that cannot open an issue cannot report that the issue + was created. Permissions are not part of the shared tool layer, for the same reason [credentials are not](mcp-servers.md#credentials-are-not-part-of-the-layer): they are a @@ -123,14 +114,12 @@ Adding a runtime is a documentation change plus four declarations, in this order 4. Declare the **shared tool set** in the runtime's native configuration format. 5. Record the **identity** it authenticates as and the permissions that identity holds. -No step writes a procedure, and none of them may be satisfied by copying an existing runtime's -instructions. A copy is the failure mode this whole model exists to prevent: two runtimes with -their own copies of a procedure disagree the moment either is edited, and neither one is -obviously wrong. +These steps add runtime declarations, not process. Do not copy another runtime's +instructions to complete them. Copies can diverge when either runtime changes its version +of the procedure. -If integrating a runtime appears to require new process rules, the rules belong in -documentation and the requirement is a signal that the documentation was incomplete — not -that this runtime is special. +If integration requires a process rule, define that rule in the canonical documentation. +The runtime configuration does not own process. ## Where this connects @@ -138,5 +127,5 @@ that this runtime is special. - [Design](design.md#client-behavior) — why entry files differ in filename and are identical in content. - [MCP Servers](mcp-servers.md) — the shared tool layer every runtime declares. - [Plugin Distribution](plugin-distribution.md) — named intents, which are per-runtime packaging over the same documented procedures. -- [Session Interactions](../../Ways-of-Working/Session-Interactions.md) — the phrase vocabulary a runtime recognises without defining. +- [Session Interactions](../../Ways-of-Working/Session-Interactions.md) — the phrase vocabulary a runtime recognizes without defining. - [Conformance](conformance.md#checking) — how a repository's runtime declarations are verified. diff --git a/src/docs/Capabilities/agentic-development/spec.md b/src/docs/Capabilities/agentic-development/spec.md index b2784957..67aaaa3a 100644 --- a/src/docs/Capabilities/agentic-development/spec.md +++ b/src/docs/Capabilities/agentic-development/spec.md @@ -7,26 +7,24 @@ description: Requirements for fresh, index-first agentic development through can ## Premise -An agent does useful work only when it knows which project it is serving, which standards apply, and what the team has already learned. That context MUST be project-scoped, durable, reviewable, and readable by humans and agents alike. The project boundary is the GitHub organization — `github.com/MSXOrg`, `github.com/PSModule`, and any other organization that adopts the framework, on any GitHub host. +An agent needs the project identity, applicable standards, and recorded project knowledge before it acts. That context MUST be project-scoped, durable, reviewable, and readable by humans and agents. The GitHub organization defines the project boundary. Examples include `github.com/MSXOrg`, `github.com/PSModule`, and adopting organizations on other GitHub hosts. -Each organization identifies a canonical documentation repository: - -- The documentation repository owns the reviewed knowledge base: vision, standards, workflows, specs, designs, glossary, onboarding, and project-wide rules. It may be named `docs`, such as `MSXOrg/docs`, or be the repository that owns an initiative's process and standards, such as `PSModule/Process-PSModule`. +Each organization identifies a canonical documentation repository. It owns reviewed project knowledge: vision, standards, workflows, specs, designs, glossary, onboarding, and project-wide rules. The name can be `docs`, as in `MSXOrg/docs`. Another repository can own the initiative's process and standards, as `PSModule/Process-PSModule` does. Product repositories do not copy that knowledge. They carry thin pointer files that identify the organization context and direct agents to the relevant documentation repository before acting. ### Principles -This framework rests on the [Principles](../../Ways-of-Working/Principles/index.md): +The framework follows the [Principles](../../Ways-of-Working/Principles/index.md): -- **[Documentation lives close to the thing it documents](../../Ways-of-Working/Principles/Engineering-Practices.md#documentation-lives-close-to-the-thing-it-documents).** Organization-wide ways of working live in the organization `docs` repository; repository-specific nuance lives in the repository. -- **[Everything as Code](../../Ways-of-Working/Principles/Engineering-Practices.md#everything-as-code).** Standards are plain files in git. Changes are reviewed, diffed, and reverted like code. +- **[Documentation lives close to the thing it documents](../../Ways-of-Working/Principles/Engineering-Practices.md#documentation-lives-close-to-the-thing-it-documents).** The organization documentation repository owns organization-wide ways of working. Product repositories own repository-specific details. +- **[Everything as Code](../../Ways-of-Working/Principles/Engineering-Practices.md#everything-as-code).** Standards are plain files in Git. Changes are reviewed, diffed, and reverted like code. - **[Written once, referenced everywhere](../../Ways-of-Working/Principles/Software-Design.md#dry-with-judgment).** Agent instructions point to canonical docs rather than duplicating them. -- **[AI-first development](../../Ways-of-Working/Principles/AI-First-Development.md).** Humans create durable context; agents consume that context and leave useful improvements behind. +- **[AI-first development](../../Ways-of-Working/Principles/AI-First-Development.md).** Humans create durable context; agents use it and record improvements. ## Scope -Applies to any organization that wants a shared project knowledge base for agents across multiple repositories. +The framework applies to organizations that share agent context across repositories. **In scope** @@ -34,9 +32,9 @@ Applies to any organization that wants a shared project knowledge base for agent - Markdown documents with YAML frontmatter, following the [Open Knowledge Format](../../Dictionary/index.md#open-knowledge-format) model. - Thin repository pointer files: a required `AGENTS.md` router, and a route to it for every client that cannot read it. - Path-scoped rule files, reserved for local caveats that cannot live in repository or central documentation. -- The shared tool layer agents call out to, and how each runtime declares it. +- The shared tool-server set and each runtime's declaration. - Named intents that package recurring workflows as pointers to canonical procedure. -- Advisory automation that publishes judgement without taking authority. +- Advisory automation that publishes judgment without taking authority. - Coordination between humans and agents on platform artifacts. - Refresh-first, index-first discovery from canonical context repositories to the Workflow and its stage procedures. - Deterministic context resolution by host, organization, repository, path, and task. @@ -61,16 +59,16 @@ Applies to any organization that wants a shared project knowledge base for agent - **Stage resolution from work.** Agents MUST infer the current stage from the prompt and current artifacts. Explicit task language MAY shortcut to the matching stage, but the shortcut MUST resolve to the canonical documentation. - **One process source.** Skills, commands, named agents, and tool-specific instruction files MUST NOT redefine Workflow stages. A client convenience MAY link to a stage procedure and add only runtime mechanics. - **Segmentation before loading.** An agent MUST segment work by host, organization, repository, path, and task before loading project standards. The active repository context supplies the coordinates that make this possible; a per-repository router MUST NOT restate them. -- **Client routes.** A runtime that cannot read `AGENTS.md` under its own filename MUST be given a route file — `.claude/CLAUDE.md`, `.github/copilot-instructions.md`, or the equivalent path for that runtime. A route file MUST contain only a pointer to `AGENTS.md` plus, at most, genuinely runtime-specific configuration that cannot be expressed as documentation. It MUST NOT restate standards, describe workflow behavior, or repeat the reading order. Duplication is a property of content rather than of filenames: a route holds nothing that can drift, so the number of route files is unconstrained while their contents are strictly limited. [Client behavior](design.md#client-behavior) names the exact set an MSX repository carries; an adopting organization MAY carry a different set for the runtimes it uses. +- **Client routes.** A runtime that cannot read `AGENTS.md` under its own filename MUST be given a route file — `.claude/CLAUDE.md`, `.github/copilot-instructions.md`, or the equivalent path for that runtime. A route file MUST contain only a pointer to `AGENTS.md` plus, at most, genuinely runtime-specific configuration that cannot be expressed as documentation. It MUST NOT restate standards, describe workflow behavior, or repeat the reading order. Duplication is a property of content rather than filenames. The number of route files is unconstrained, but their contents are strictly limited. [Client behavior](design.md#client-behavior) names the exact set an MSX repository carries; an adopting organization MAY carry a different set for the runtimes it uses. - **Reading order and authority order are distinct.** An agent MUST read nearest context first, in the order the repository router defines. Precedence on conflict MUST run the opposite way: repository-local files MAY add nuance and narrow exceptions but MUST NOT override an organization or inherited ecosystem standard unless that standard permits a local exception. - **Deterministic context resolution.** Agents MUST resolve context in layers: system and client policy, user preferences, the repository router, the context-repository Git freshness gate, repository context, path-scoped repository rules, organization docs, any inherited ecosystem docs, then current task context. - **Local-first availability.** The canonical documentation repository SHOULD be available locally in a predictable workspace so agents can read it without relying on search or web access. - **Fresh context before use.** Every canonical context repository MUST be fetched and exactly synchronized with its remote default branch before its contents are read. Agents use Git directly; dirty, locally ahead, diverged, wrong-branch, or unreachable repositories MUST stop context resolution rather than fall back to stale content. - **Working checkouts are not context sources.** Canonical context MUST be read from the documentation repository clone that passed the freshness gate. A working checkout cloned to change that repository rather than to be governed by it MUST NOT be used as a context source, whatever path it occupies, because it sits outside the gate. -- **Synchronize once per session, not once per machine.** The freshness gate MUST run at the start of every agent session, in every runtime. A workspace that was synchronized at some earlier point MUST NOT be treated as current, because elapsed time is not a state the agent can observe. The agent MUST use Git to synchronize it or stop when the clone cannot be safely synchronized. +- **Synchronize once per session, not once per machine.** The freshness gate MUST run at the start of every agent session, in every runtime. A workspace synchronized earlier MUST NOT be treated as current on that basis. Elapsed time does not establish the remote repository state. The agent MUST use Git to synchronize it or stop when the clone cannot be safely synchronized. - **One tool layer, declared per runtime.** Where agents use external tools, the set of tool servers MUST be defined once as a logical layer and each runtime MUST declare that same set in its own native configuration format. A runtime MUST NOT define tools of its own that other runtimes lack, because a capability available in one client and absent in another makes the documented procedure conditional on which client is running it. -- **Named intents stay pointer-based.** A packaged shortcut for a recurring workflow — however a runtime names it — MUST resolve to the canonical documentation for that workflow and MUST contain only the runtime mechanics needed to get there. It MUST NOT restate the procedure, since a shortcut that carries a copy of the process becomes a second, silently diverging definition of it. -- **Advice and authority are separate.** An automated agent MAY analyse work and publish its conclusion as advice on the artifact under review. It MUST NOT be the thing that decides: it MUST NOT overwrite a human's decision, MUST NOT re-apply a decision a human has changed, and MUST NOT commit to the branch it is advising on. Its output is an input to the review, not a substitute for it. +- **Named intents stay pointer-based.** A packaged shortcut for a recurring workflow — however a runtime names it — MUST resolve to the canonical documentation for that workflow and MUST contain only the runtime mechanics needed to get there. It MUST NOT restate the procedure. A copied process can diverge from its canonical definition. +- **Advice and authority are separate.** An automated agent MAY analyze work and publish its conclusion as advice on the artifact under review. It MUST NOT decide the artifact's outcome: it MUST NOT overwrite a human's decision, MUST NOT re-apply a decision a human has changed, and MUST NOT commit to the branch it is advising on. Its output is an input to the review, not a substitute for it. - **Coordination happens on durable artifacts.** Where agents and humans coordinate, they MUST do so through the platform's own artifacts — issues, labels, and pull requests — rather than through a channel that leaves no trace in the repository. Intent MUST be separable from implementation: the issue states *what* is wanted and *why*, and the pull request proposes *how*, so that a rejected implementation does not discard the intent. - **Reviewed knowledge changes.** Changes to the canonical documentation repository MUST happen through pull requests. - **No cross-project bleed.** An agent working in one organization MUST NOT apply another organization's standards unless the current task explicitly asks for cross-organization work.