diff --git a/src/docs/Capabilities/agentic-development/design.md b/src/docs/Capabilities/agentic-development/design.md index ccee5ec..618faa5 100644 --- a/src/docs/Capabilities/agentic-development/design.md +++ b/src/docs/Capabilities/agentic-development/design.md @@ -325,6 +325,6 @@ Because Copilot code review reads the head branch, a pull request that changes ` - [Agent Interaction](agent-interaction.md) — how agents and humans coordinate through platform artifacts. - [Advisory Agents](advisory-agents.md) — agents that produce advice rather than commits. - [Conformance](conformance.md) — the checklist a repository is measured against. -- [Agentic Development](../../Ways-of-Working/Agentic-Development.md) — the way-of-working standard this framework implements. +- [Agentic Development framework](index.md) — the framework this design delivers. - [Documentation Model](../../Ways-of-Working/Documentation-Model.md) — why spec and design are split. - [README-Driven Context](../../Ways-of-Working/Readme-Driven-Context.md) — why local repository context remains the front door. diff --git a/src/docs/Capabilities/agentic-development/spec.md b/src/docs/Capabilities/agentic-development/spec.md index cf83322..87bb2e5 100644 --- a/src/docs/Capabilities/agentic-development/spec.md +++ b/src/docs/Capabilities/agentic-development/spec.md @@ -22,7 +22,7 @@ This framework rests on the [Principles](../../Ways-of-Working/Principles/index. - **[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 and memory are plain files in git. Changes are reviewed, diffed, and reverted like code. -- **[Written once, referenced everywhere](../../Ways-of-Working/Agentic-Development.md#principles).** Agent instructions point to canonical docs and memory rather than duplicating them. +- **[Written once, referenced everywhere](../../Ways-of-Working/Principles/Software-Design.md#dry-with-judgment).** Agent instructions point to canonical docs and memory 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. ## Scope @@ -64,7 +64,7 @@ Applies to any organization that wants a shared project knowledge base and memor - **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 or memory. The repository router MUST supply the coordinates that make this possible by naming its host and organization. The instruction to segment belongs to the user-global bootstrap, which runs before any repository file is read; a per-repository file MUST NOT restate it. -- **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. [Agentic Development](../../Ways-of-Working/Agentic-Development.md#which-agent-files-a-repository-carries) 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 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. - **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, and memory MUST NOT override documentation. - **Deterministic context resolution.** Agents MUST resolve context in layers: system and client policy, user preferences, the repository router, the context-repository freshness gate, repository context, path-scoped repository rules, organization docs, any inherited ecosystem docs, organization memory, then current task context. - **Local-first availability.** The docs and memory repositories SHOULD be available locally in a predictable workspace so agents can read them without relying on search or web access. @@ -123,6 +123,6 @@ This is the order in which context is **read**, nearest first. It is not the ord - [Agent Interaction](agent-interaction.md) — issues, labels, and pull requests as the coordination substrate. - [Advisory Agents](advisory-agents.md) — the pattern for automation that advises without deciding. - [Conformance](conformance.md) — how a repository is measured against this spec. -- [Agentic Development](../../Ways-of-Working/Agentic-Development.md) — the existing way-of-working standard this framework operationalizes. +- [Agentic Development](index.md) — the framework this specification defines. - [Documentation Model](../../Ways-of-Working/Documentation-Model.md) — how specs and designs are written and kept evergreen. - [Open Knowledge Format](../../Dictionary/index.md#open-knowledge-format) — the Markdown and frontmatter model used for knowledge pages. diff --git a/src/docs/Coding-Standards/Natural-Language.md b/src/docs/Coding-Standards/Natural-Language.md index 8f66903..5d9f4b1 100644 --- a/src/docs/Coding-Standards/Natural-Language.md +++ b/src/docs/Coding-Standards/Natural-Language.md @@ -208,5 +208,5 @@ Do not include secrets, private personal notes, or speculation. - [Documentation](Documentation.md) — where documentation lives and what it explains. - [Markdown](Markdown.md) — Markdown syntax and linted formatting rules. -- [Agentic Development](../Ways-of-Working/Agentic-Development.md) — how agents consume the same docs as humans. +- [Agentic Development](../Capabilities/agentic-development/index.md) — how agents consume the same docs as humans. - [README-Driven Context](../Ways-of-Working/Readme-Driven-Context.md) — why the README is the repository front door. diff --git a/src/docs/Dictionary/index.md b/src/docs/Dictionary/index.md index 1b0e603..a997670 100644 --- a/src/docs/Dictionary/index.md +++ b/src/docs/Dictionary/index.md @@ -15,7 +15,7 @@ The 2018 book by Nicole Forsgren, Jez Humble, and Gene Kim presenting the resear ### Agent -An AI participant that reads the same documentation as a human and acts on the platform — opening issues, proposing pull requests, and reviewing changes. See [Agentic Development](../Ways-of-Working/Agentic-Development.md). +An AI participant that reads the same documentation as a human and acts on the platform — opening issues, proposing pull requests, and reviewing changes. See [Agentic Development](../Capabilities/agentic-development/index.md). ### Anthropic API diff --git a/src/docs/Ways-of-Working/Agentic-Development.md b/src/docs/Ways-of-Working/Agentic-Development.md deleted file mode 100644 index 8911e0e..0000000 --- a/src/docs/Ways-of-Working/Agentic-Development.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: Agentic Development -description: How ways of working, standards, and documentation are authored once and consumed by both humans and agents. ---- - -# Agentic Development - -How the ecosystem's ways of working, coding standards, and documentation are authored — and how both humans and agents consume them. The documentation defines how work is done; agent configuration *references* that documentation, never the other way around. - -## Premise - -Process knowledge — how to open an issue, how to review a pull request, how Terraform is written — belongs in documentation, written once for two audiences. The temptation is to encode it as a tool-specific "skill" or instruction file, tightly coupled to one agent's format and scattered across repositories. That inverts the relationship and guarantees drift: the same rule, copied into many tool files, disagrees with itself the moment one copy changes. - -The specification fixes the direction of the dependency. The docs are the **stable core** that states how work is done. Agent configuration files are **thin pointers** to those docs — the same pages a new team member would read. Adding or swapping an agent runtime means writing new pointers, not rewriting process knowledge. - -## Principles - -This spec rests on the [Principles](Principles/index.md). Four apply directly: - -- **Written once, referenced everywhere.** A standard, a process, or a convention is defined in exactly one place and linked from everywhere else. Agent config, repository docs, and tool integrations point to that definition — they never duplicate it. This is [DRY](Principles/Software-Design.md#dry-with-judgment) applied to process knowledge. -- **[Documentation lives close to the thing it documents](Principles/Engineering-Practices.md#documentation-lives-close-to-the-thing-it-documents).** Repo-specific context lives in the repository; cross-cutting guidance lives in the org-level docs and is referenced by its canonical URL. An agent always reads the repository's own context first. -- **[AI-first development](Principles/AI-First-Development.md).** Humans create context — in issues, docs, and decisions — and agents act on it. Because agents are trained to read documentation, keeping standards in documentation form serves both audiences with a single artifact; no separate "agent manual" exists. -- **[Extensible by default](Principles/Software-Design.md#extensible-by-default).** Ways of working and standards are the stable core. Coding agents are adapters that plug in. The system is pluggable: the docs do not change when a new runtime is added — only a new integration layer is written. - -## Architecture - -Agent configuration files are **pointers, not process containers**. The router — `AGENTS.md` — names the context that governs the work and the order to read it in; every other agent file points at the router and carries no order of its own. None of them select a persona, copy workflow stages, restate standards, or carry the repository's own operating instructions. Documentation lives where it belongs — repo-specific context in each repository's `README.md`, `CONTRIBUTING.md`, and `docs/`; cross-cutting guidance in the org-level documentation site; workspace setup in the user-global bootstrap. - -When an agent receives work, it follows the same documentation trail a human can follow: - -```mermaid -flowchart TD - task["Agent receives work"] --> pointer["1 Read AGENTS.md
the repository's router"] - pointer --> refresh["2 Refresh every context repository
stop unless exactly synchronized"] - refresh --> repo["3 Read repository context
README, CONTRIBUTING, local docs"] - repo --> initiative["4 Read the initiative's
governing documentation"] - initiative --> root["5 Read central docs/index.md
follow Ways of Working to Workflow"] - root --> stage["6 Infer the current stage
read its procedure and standards"] - stage --> memory["7 Read memory last"] - memory --> work["Act and follow stage handoffs"] -``` - -Refresh is a gate before traversal, not a best-effort background step. It governs the clones the bootstrap validates, and those are what context is read from — [a working checkout is not a context source](#a-working-checkout-is-not-a-context-source). After it passes, the indexes are the default discovery mechanism. [Workflow](Workflow.md) owns the process and routes the work to a [stage procedure](Workflow-Stages/index.md); the stage page then points to the standards and artifacts it consumes. A clear prompt such as `Review this PR ` may shortcut directly through the Workflow routing table, but it does not create a second process definition. **Local files never replace central standards — they layer specifics on top.** - -## Where documentation lives - -Documentation is not collected into a single repository. Each page is authored and maintained where it naturally belongs: - -| Scope | Home | Examples | -| --- | --- | --- | -| **Cross-cutting** — ways of working, coding standards, capabilities | The org-level documentation site | This site: | -| **Repo-specific** — architecture, setup, domain context | The repository that owns it | `README.md`, `CONTRIBUTING.md`, `docs/` | - -This split follows [Repository Segmentation](Repository-Segmentation.md) and [README-Driven Context](Readme-Driven-Context.md): the README is the front door of a repository, and the org-level site is the front door of the ecosystem. - -## How an agent runtime plugs in - -Each repository carries an `AGENTS.md` that routes an agent from the repository's own files outward to the documentation and memory that govern it. A client that cannot read that filename gets a route to it, and adds only the small amount of genuinely tool-specific configuration, such as permission scopes or path matching, that cannot live in ordinary documentation. - -Any new runtime follows the same pattern, regardless of vendor: - -- A **route to the router** — a file under the name that runtime reads, pointing at `AGENTS.md`. It does not name the docs and memory roots itself; the router already does. -- Optional **keyword shortcuts** that route a clearly stated task to the matching [Workflow stage](Workflow.md#find-the-current-stage) without copying its procedure. -- **Tool-specific settings** — permissions, model selection, and the like. - -There is no separate process surface for Define, Implement, or Review. If a client exposes a skill, command, named agent, or other convenience, it links to the canonical stage page and adds no process knowledge. When a new runtime is adopted, only this thin integration layer is added. - -### Which agent files a repository carries - -| File | Status | Role | -| --- | --- | --- | -| `AGENTS.md` | Required | The router, at the repository root. A list of destinations, nothing more. | -| `.claude/CLAUDE.md` | Required | Routes Claude Code to the router: `@../AGENTS.md`. | -| `.github/copilot-instructions.md` | Required | Routes the Copilot surfaces that do not read `AGENTS.md` to the router. | -| `.github/instructions/*.instructions.md` | Exceptional | A path-scoped caveat that genuinely has nowhere better to live. | - -One router, and a route for every client that cannot reach it under that name. - -#### What `AGENTS.md` routes to - -`AGENTS.md` is a list of destinations and nothing else. It carries no bootstrap steps, no build commands, no contribution mechanics, and no standards — each of those has a file that already owns it. What it holds is the order: - -1. **`README.md`** — what this repository is and how it builds. -2. **`CONTRIBUTING.md`** — how a change is made and reviewed here. -3. **The repository's own documentation** — conventionally `docs/`, when it has any. -4. **The initiative's governing documentation** — the standards for this family of repositories. -5. **The central MSX documentation** — the ecosystem-wide ways of working and coding standards this site owns. -6. **Memory** — durable lessons from earlier work, read last. - -Nearest first, widening outward. A repository's own files answer the questions only it can answer, and each step out answers a broader one. The order is written generically on purpose: every initiative resolves step 4 to its own documentation, so the same router works in any organization that adopts this model. - -Steps collapse where they coincide. A repository that publishes the standards — this one, whose documentation tree is `src/docs/` — resolves steps 3, 4, and 5 to that one tree and has nothing above it, so its router lists four destinations rather than six. Skipping a step because it does not exist is not the same as omitting it. - -Anything an agent needs *before* it can reach step 1 — cloning the workspace, the freshness gate — belongs to the [user-global bootstrap](#the-workspace-bootstrap), not to a repository file. A per-repository copy of the bootstrap is the same duplication in a different place. - -#### Reading order is not authority order - -An agent reads nearest-first. Authority runs the other way. - -| Layer | Read | Authority | -| --- | --- | --- | -| Repository files | First | Add local nuance and narrow exceptions; never silently override a standard. | -| Initiative documentation | Next | Governs that initiative's repositories, and may adjust an MSX default for them. | -| Central MSX documentation | Next | The ecosystem default every repository inherits. | -| Memory | Last | Informs; never governs. Where memory and documentation disagree, the documentation is right and the memory entry is corrected. | - -Reading nearest-first is what makes an agent efficient. Letting the nearest file win would make it wrong. - -#### Client files route, they never carry process - -Agent runtimes do not agree on a filename. `AGENTS.md` is read natively by Copilot Chat in VS Code, the Copilot cloud agent, and Copilot code review on GitHub.com, among others. Claude Code reads its own name. Copilot Chat on GitHub.com, Visual Studio, JetBrains, Eclipse, and Copilot code review outside GitHub.com read `.github/copilot-instructions.md`, as GitHub's [custom instructions support matrix](https://docs.github.com/en/copilot/reference/custom-instructions-support) records. - -Each of those clients gets a file whose only substance is a route to the router, plus at most the runtime's own settings. The risk these files carry is **duplication, and duplication is a property of content rather than of filenames**. A file that says only "follow `AGENTS.md`" has nothing in it to drift. A file that restates the reading order, the workflow, or a coding standard has everything to drift, no matter what it is called. - -So the rule is about what a client file may contain, not how many of them exist: - -- a route to `AGENTS.md`, and -- at most, genuinely runtime-specific configuration — permission scopes, model choice — that cannot be expressed as documentation. - -It never restates a standard, never describes a workflow stage, and never repeats the reading order below. The router owns all of that, and every client reaches the same copy of it. - -#### Path-scoped instruction files are the exception - -A `.github/instructions/*.instructions.md` file earns its place only when a rule applies to one path in one repository and has nowhere better to live. Before adding one, put the rule where it belongs: - -- a fact about the repository → `README.md`; -- a rule about contributing or reviewing → `CONTRIBUTING.md`; -- anything another repository could reuse → the initiative or central documentation. - -What survives that test is a genuine local caveat, which is the narrow case these files exist for. They never restate a standard and never define workflow behaviour. - -The [agentic development capability](../Capabilities/agentic-development/spec.md) is deliberately broader than this page: it permits a route for any client that points back to the same router, so an organization adopting the framework can support a runtime this one does not use. This page states what an MSX repository carries. - -## Distribution - -The two non-documentation layers have different distribution models: - -- **The canonical process** lives in [Workflow](Workflow.md), which links to ordinary documentation pages for each [stage procedure](Workflow-Stages/index.md). -- **Per-repository pointer files** — `AGENTS.md` and the client routes that reach it — are seeded from a template repository and kept current across existing repositories by a sync mechanism. The routes are stable because they hold no content; what changes over time is the router they point at. A path-scoped instruction file is written by the repository that needs it and is not distributed. - -Process knowledge is never added to a distributed config file. If an agent needs the branch strategy, it goes in [Branching and Merging](Branching-and-Merging.md) or the repo's `CONTRIBUTING.md`; if it needs a coding convention, it goes in the relevant [coding standard](../Coding-Standards/index.md). The config file only points — it never defines. - -## The workspace bootstrap - -The **user-global** entry file is a thin **bootstrap**, not a copy of the docs. Each runtime auto-loads its own user-level file — Copilot from its user instructions, Claude Code from `~/.claude/CLAUDE.md` (which imports the same instructions) — and its first instruction is to make the central workspace present locally, then start at the root indexes. It is central-first by design, because its whole job is to make central context exist before anything reads it. That is distinct from the per-repository `AGENTS.md`, which runs in the opposite direction once the workspace is present. - -The workspace is a git-isolated clone of the central repositories under `~/.msx`: - -- `~/.msx/docs` — this documentation, read as local files. Changes to it go through pull requests. -- `~/.msx/memory` — durable notes and prior session context. Changes to it are pushed to main. - -Each clone carries repository-local git config only, so the workspace never modifies the global git config or the repository the agent is working in — git still reads them, but only repository-local config is written. Before context is read, [`bootstrap/Initialize-MsxWorkspace.ps1`](https://github.com/MSXOrg/docs/blob/main/bootstrap/Initialize-MsxWorkspace.ps1) clones missing repositories and requires every existing context repository to be clean, on its remote default branch, and exactly synchronized with the remote head. Any update failure stops context resolution rather than allowing stale guidance or memory. - -The workspace makes the *central* context present locally; the same local-first stance shapes how each working repository is laid out. Repositories are cloned as [git worktrees](Git-Worktrees.md) — one working directory per branch — so a person and an agent, or several agents, can work on multiple issues in the same repository at once without stashing or switching branches. - -### A working checkout is not a context source - -Canonical context is read from the clones the gate validated. A **working checkout** of a documentation repository — one cloned in order to change it, rather than to be governed by it — is not a context source, even when it sits on disk and reads perfectly well. The distinction is one of role, not of path: what makes a clone canonical is that the gate proved it current, not where it lives, so this holds for any initiative's `docs` and `memory` repositories and for whatever location a contributor happens to clone them into. - -The reason is that a working checkout has no freshness gate. Nothing fetches it, nothing fails when it falls behind, and a superseded page in it is still present and still readable — so the failure is silent and self-confirming. A working checkout of this repository was found 26 commits behind its remote head, clean and zero commits ahead, simply neglected; it predated the Ways of Working restructure and so still carried a page that had been replaced upstream. A task prompt authored from that checkout named the replaced page as the authority for its format, citing a path that had not existed for 26 commits. The agent that received the prompt could not tell, because the page it was sent to opened. - -Whether a given checkout is current is decided by a fetch and a count, neither of which changes anything in the working tree: - -```powershell -git -C fetch origin --quiet -git -C rev-list --left-right --count HEAD...origin/ -``` - -The two numbers are the commits the checkout is ahead of, and behind, the remote head. Both must be zero — the same bar the gate applies, where being ahead or diverged fails just as being behind does. Anything else means the checkout is not fit to be read as guidance: read the validated clone instead, or bring the checkout to the remote head before trusting a word of it. Editing documentation through a working checkout is unchanged by this — the checkout is where a change is written, not where the rules are read. - -## Where this connects - -- [Git Worktrees](Git-Worktrees.md) — how this framework is implemented on a local machine, so several pieces of work run in parallel. -- [Session Interactions](Session-Interactions.md) — recognised phrases that operate on the session, each defined once and referenced by every runtime. -- [Documentation Model](Documentation-Model.md) — the discipline this specification follows. -- [Principles](Principles/index.md) — the beliefs this specification rests on, including the three-layer agent context model. -- [README-Driven Context](Readme-Driven-Context.md) — why the repository's own context comes first. -- [Coding Standards](../Coding-Standards/index.md) — the cross-cutting standards agents pick up in the central layer. diff --git a/src/docs/Ways-of-Working/Documentation-Model.md b/src/docs/Ways-of-Working/Documentation-Model.md index 54e6407..4a686af 100644 --- a/src/docs/Ways-of-Working/Documentation-Model.md +++ b/src/docs/Ways-of-Working/Documentation-Model.md @@ -208,12 +208,12 @@ The same pages serve both. A contributor reads the index, follows the description inward, and drills from section to page until they reach the answer; an agent does exactly the same before it acts. Because the docs are the single source, there is no separate "agent manual" to drift — -[Agentic Development](Agentic-Development.md) explains how agent configuration +[Agentic Development](../Capabilities/agentic-development/index.md) explains how agent configuration points at these pages rather than copying them. ## Where this connects - [Workflow](Workflow.md) — the loop specs and designs revolve around. -- [Agentic Development](Agentic-Development.md) — how humans and agents consume these docs. +- [Agentic Development](../Capabilities/agentic-development/index.md) — how humans and agents consume these docs. - [README-Driven Context](Readme-Driven-Context.md) — why the README is the front door and the spec goes ahead of the code. - [Coding Standards](../Coding-Standards/index.md) — how the code a design describes is written. diff --git a/src/docs/Ways-of-Working/Evolutionary-Development.md b/src/docs/Ways-of-Working/Evolutionary-Development.md index a749d65..72bc36e 100644 --- a/src/docs/Ways-of-Working/Evolutionary-Development.md +++ b/src/docs/Ways-of-Working/Evolutionary-Development.md @@ -110,7 +110,7 @@ A turn is only as good as the context it runs on — output quality tracks input - The [spec](Spec-Driven-Development.md) (why, what, acceptance criteria) and its design (how), or the marked unknowns where they do not exist yet. - The constraints, non-goals, and dependencies that bound the solution. -- Pointers to the code, standards, and prior decisions that already apply — read in layers, local context before central standards ([Agentic Development](Agentic-Development.md)). +- Pointers to the code, standards, and prior decisions that already apply — read in layers, local context before central standards ([Agentic Development](../Capabilities/agentic-development/index.md)). This is [context-first development](Principles/AI-First-Development.md#context-first-development) made operational: the context is created up front — in specs, issues, and ADRs — and the loop runs on it. Context loss is the most common cause of wasted effort; a bet made without context is a bet made blind. Context is not read-only, though: when a turn shows a standard or instruction is wrong — or teaches a better one — updating it is part of the turn (see [The instructions evolve too](#the-instructions-evolve-too)). @@ -129,7 +129,7 @@ When a turn exposes a defect or discovers a better way of working — whether a - A turn goes wrong in a way a clearer instruction would have prevented. - A turn finds a better way — a sharper prompt, a cleaner sequence, a rule worth making the default — worth keeping for the next one. -Because a standard is defined once and pointed to everywhere ([Agentic Development](Agentic-Development.md)), one change propagates to every repo and every agent that reads it — improve it in one place and the whole fleet's behavior evolves. This is the method turned on itself: the same living-documentation discipline that keeps a spec true keeps the instructions true and refines them as understanding grows, so the way of working gets better every time a turn teaches something worth keeping. +Because a standard is defined once and pointed to everywhere ([Agentic Development](../Capabilities/agentic-development/index.md)), one change propagates to every repo and every agent that reads it — improve it in one place and the whole fleet's behavior evolves. This is the method turned on itself: the same living-documentation discipline that keeps a spec true keeps the instructions true and refines them as understanding grows, so the way of working gets better every time a turn teaches something worth keeping. ## Working a v1 diff --git a/src/docs/Ways-of-Working/Git-Worktrees.md b/src/docs/Ways-of-Working/Git-Worktrees.md index 5eda67e..9321c05 100644 --- a/src/docs/Ways-of-Working/Git-Worktrees.md +++ b/src/docs/Ways-of-Working/Git-Worktrees.md @@ -5,13 +5,13 @@ description: How agentic development is implemented locally — a bare-clone and # Git Worktrees -Git worktrees are how [agentic development](Agentic-Development.md) is implemented on a local machine. They are purely a **local development** convenience: a way for one person — or a person and an agent, or several agents — to work on multiple repository-delivery leaves at the same time, without stashing, committing half-finished work, or switching branches. They change nothing about how a repository is built, reviewed, or shipped — that still happens through branches and pull requests, exactly as it would with an ordinary clone. +Git worktrees are how [agentic development](../Capabilities/agentic-development/index.md) is implemented on a local machine. They are purely a **local development** convenience: a way for one person — or a person and an agent, or several agents — to work on multiple repository-delivery leaves at the same time, without stashing, committing half-finished work, or switching branches. They change nothing about how a repository is built, reviewed, or shipped — that still happens through branches and pull requests, exactly as it would with an ordinary clone. All repositories are set up as **bare clones with worktrees**. Each repository-delivery Task or Bug gets its own worktree — an independent working directory for one branch — so parallel work never collides. Epic and PBI aggregates, and operational Tasks without repository artifacts, do not get worktrees. ## Why this matters: working agentically in parallel -The reason this layout is the default — not the occasional convenience it is in most projects — is **parallelism**. [Agentic development](Agentic-Development.md) does not proceed one delivery leaf at a time. A single developer can have several agents working at once, each on a different Task or Bug, alongside their own hands-on changes. Worktrees are what make running many streams at once safe instead of chaotic: +The reason this layout is the default — not the occasional convenience it is in most projects — is **parallelism**. [Agentic development](../Capabilities/agentic-development/index.md) does not proceed one delivery leaf at a time. A single developer can have several agents working at once, each on a different Task or Bug, alongside their own hands-on changes. Worktrees are what make running many streams at once safe instead of chaotic: - **One worktree per repository-delivery Task or Bug, one agent per worktree.** Each agent gets its own working directory, its own branch, and its own uncommitted state. Two agents never write to the same checkout, so their edits cannot corrupt one another. - **No stashing, no branch-switching, no waiting.** Because the worktrees are independent, the agent finishing Task #42 never disturbs the one still working on Bug #99 — and neither touches the clean canonical `/` worktree you read from. Nobody has to reach a clean tree before anyone else can move. @@ -135,6 +135,6 @@ git --git-dir="${repo}.git" worktree prune ## Where this connects -- [Agentic Development](Agentic-Development.md) — the framework these worktrees implement locally, so several pieces of work run in parallel. +- [Agentic Development](../Capabilities/agentic-development/index.md) — the framework these worktrees implement locally, so several pieces of work run in parallel. - [Branching and Merging](Branching-and-Merging.md) — the branch-per-delivery-leaf model each worktree holds. - [Workflow](Workflow.md) — where creating a worktree fits in the flow from issue to delivery. diff --git a/src/docs/Ways-of-Working/Organization-Standard.md b/src/docs/Ways-of-Working/Organization-Standard.md index 706f723..822650d 100644 --- a/src/docs/Ways-of-Working/Organization-Standard.md +++ b/src/docs/Ways-of-Working/Organization-Standard.md @@ -102,7 +102,7 @@ Humans and agents must read the same standards. Do not create a separate hidden Agent files are allowed when they point to, summarize, or operationalize the central standard. They must not become a second source of truth. -The repository-level entry point is `AGENTS.md`, as defined by [Agentic Development](Agentic-Development.md#which-agent-files-a-repository-carries). Agent runtimes do not agree on a filename, so a repository also carries a route file for each client that reads a different one. A route holds a pointer to the router and, at most, genuinely runtime-specific configuration — never a duplicated standard or workflow. The same limit applies to any organization-level instruction setting an agent vendor offers: use it for organization-wide preferences, never as a second copy of a standard. +The repository-level entry point is `AGENTS.md`, as defined by [Agentic Development](../Capabilities/agentic-development/design.md#client-behavior). Agent runtimes do not agree on a filename, so a repository also carries a route file for each client that reads a different one. A route holds a pointer to the router and, at most, genuinely runtime-specific configuration — never a duplicated standard or workflow. The same limit applies to any organization-level instruction setting an agent vendor offers: use it for organization-wide preferences, never as a second copy of a standard. ## Where this connects diff --git a/src/docs/Ways-of-Working/Repository-Standard.md b/src/docs/Ways-of-Working/Repository-Standard.md index d031944..c8305a8 100644 --- a/src/docs/Ways-of-Working/Repository-Standard.md +++ b/src/docs/Ways-of-Working/Repository-Standard.md @@ -29,7 +29,7 @@ discoverability minimum defined below instead. | `SECURITY.md` | Explains supported versions and private vulnerability reporting. | | `SUPPORT.md` | Explains where users ask for help. | | `CODE_OF_CONDUCT.md` | Defines expected community behaviour. | -| `AGENTS.md` and its client routes | Route every agent runtime from this repository's own files outward to the initiative and central documentation, then to memory. [Agentic Development](Agentic-Development.md#which-agent-files-a-repository-carries) names the files and the path each one sits at. | +| `AGENTS.md` and its client routes | Route every agent runtime from this repository's own files outward to the initiative and central documentation, then to memory. [Agentic Development](../Capabilities/agentic-development/design.md#client-behavior) names the files and the path each one sits at. | | `.github/dependabot.yml` | Configures platform-native dependency-update pull requests for supported ecosystems. The `github-actions` ecosystem is expected in virtually every repository; an unsupported ecosystem follows the centrally managed exception path rather than a repository-local updater. | | `.github/CODEOWNERS` | Routes reviews to responsible owners. | | `.github/pull_request_template.md` | Scaffolds pull requests in the MSX [PR Format](PR-Format.md) (PR Manager) style — an icon + change-type + user-facing-outcome title, user-facing description sections, an optional technical-details block, and a related-issues block. | @@ -61,7 +61,7 @@ against its discoverability minimum. Presence is verified by [reconciliation](../Capabilities/repository-governance/design.md#required-files-by-type), not by review. -The agent-file row is the one entry this table does not spell out in full. [Agentic Development](Agentic-Development.md#which-agent-files-a-repository-carries) owns that set — one router at the repository root, plus a route for every client that reads a different filename — and the [agentic development spec](../Capabilities/agentic-development/spec.md) limits what a route may contain: a pointer to the router and, at most, genuinely runtime-specific configuration such as permission scopes, never a reading order, a workflow, or a standard. A repository is audited against that one list, so a second copy here would be a second list to keep in step. +The agent-file row is the one entry this table does not spell out in full. [Agentic Development](../Capabilities/agentic-development/design.md#client-behavior) owns that set — one router at the repository root, plus a route for every client that reads a different filename — and the [agentic development spec](../Capabilities/agentic-development/spec.md) limits what a route may contain: a pointer to the router and, at most, genuinely runtime-specific configuration such as permission scopes, never a reading order, a workflow, or a standard. A repository is audited against that one list, so a second copy here would be a second list to keep in step. ## README defaults @@ -201,7 +201,7 @@ For example, PSModule can define its module-specific managed files in `PSModule/ - [Organization Standard](Organization-Standard.md) — what an initiative organization must define centrally. - [Repository Governance](../Capabilities/repository-governance/spec.md) — how a repository's type selects the controls and the file set it is audited against. - [Automation Labels](Automation-Labels.md) — the namespacing rule every label a repository's automation reads must follow. -- [Agentic Development](Agentic-Development.md) — which agent files a repository carries and why the entry point is a pointer. +- [Agentic Development](../Capabilities/agentic-development/index.md) — which agent files a repository carries and why the entry point is a pointer. - [Repository Type Property](Repository-Type-Property.md) — the `Type` custom property that classifies a repository and drives which type-specific files and controls apply. - [README-Driven Context](Readme-Driven-Context.md) — why the README is the front door. - [PR Format](PR-Format.md) — the PR Manager-style title and description format. diff --git a/src/docs/Ways-of-Working/Workflow-Stages/Maintain-Guidance.md b/src/docs/Ways-of-Working/Workflow-Stages/Maintain-Guidance.md index fff6ed3..efab598 100644 --- a/src/docs/Ways-of-Working/Workflow-Stages/Maintain-Guidance.md +++ b/src/docs/Ways-of-Working/Workflow-Stages/Maintain-Guidance.md @@ -29,7 +29,7 @@ Write the stage as a page in this section, following the shape of its siblings: ### 3. Keep pointers thin -A repository never carries a copy of the workflow. Its `AGENTS.md` — with the client routes that reach it — lists these pages as a destination and nothing more. Repository-specific nuance lives in `README.md`, `CONTRIBUTING.md`, and the repository's own `docs/`; the router points at those files rather than restating them. When a new runtime is adopted, add a route under the filename it reads; do not move process knowledge into it. See [Agentic Development](../Agentic-Development.md#which-agent-files-a-repository-carries). +A repository never carries a copy of the workflow. Its `AGENTS.md` — with the client routes that reach it — lists these pages as a destination and nothing more. Repository-specific nuance lives in `README.md`, `CONTRIBUTING.md`, and the repository's own `docs/`; the router points at those files rather than restating them. When a new runtime is adopted, add a route under the filename it reads; do not move process knowledge into it. See [Agentic Development](../../Capabilities/agentic-development/design.md#client-behavior). ### 4. Validate @@ -45,5 +45,5 @@ A repository never carries a copy of the workflow. Its `AGENTS.md` — with the ## Where this connects -- [Agentic Development](../Agentic-Development.md) — the pointer model this maintains. +- [Agentic Development](../../Capabilities/agentic-development/index.md) — the pointer model this maintains. - [Documentation Model](../Documentation-Model.md) — how these pages stay evergreen. diff --git a/src/docs/Ways-of-Working/index.md b/src/docs/Ways-of-Working/index.md index fe6e0cf..cf11b58 100644 --- a/src/docs/Ways-of-Working/index.md +++ b/src/docs/Ways-of-Working/index.md @@ -24,7 +24,6 @@ This section documents the principles, processes, and norms that every contribut | [Spec-Driven Development](Spec-Driven-Development.md) | The specification is the source of truth — the spec (why and what), its design (how), and how a change moves from need to shipped. | | [Spec-Driven Development Templates](Spec-Driven-Development-Templates.md) | A copyable skeleton for every spec-driven artifact — specification, feature addendum, design, implementation doc, guide, reference, research, decision record, standard, orchestration playbook, and decisions register. | | [Evolutionary Development](Evolutionary-Development.md) | Grow software as bets under selection — variation, feedback, and survival of the fittest, run as one tight loop. | -| [Agentic Development](Agentic-Development.md) | How ways of working, standards, and documentation are authored once and consumed by both humans and agents. | | [Git Worktrees](Git-Worktrees.md) | How agentic development is implemented locally — a bare-clone and worktree layout for working on several things at once. | | [Session Interactions](Session-Interactions.md) | Recognised phrases that steer a working session deterministically, why each is defined once as a standard rather than embedded in tool-specific files, and what an interaction may not do. | | [Organization Standard](Organization-Standard.md) | What every initiative organization must define centrally so humans and agents share the same expectations. | diff --git a/src/zensical.toml b/src/zensical.toml index 087c278..0e65104 100644 --- a/src/zensical.toml +++ b/src/zensical.toml @@ -41,11 +41,8 @@ nav = [ {"Spec-Driven Development" = "Ways-of-Working/Spec-Driven-Development.md"}, {"Spec-Driven Development Templates" = "Ways-of-Working/Spec-Driven-Development-Templates.md"}, {"Evolutionary Development" = "Ways-of-Working/Evolutionary-Development.md"}, - {"Agentic Development" = [ - "Ways-of-Working/Agentic-Development.md", - {"Git Worktrees" = "Ways-of-Working/Git-Worktrees.md"}, - {"Session Interactions" = "Ways-of-Working/Session-Interactions.md"}, - ]}, + {"Git Worktrees" = "Ways-of-Working/Git-Worktrees.md"}, + {"Session Interactions" = "Ways-of-Working/Session-Interactions.md"}, {"Organization Standard" = "Ways-of-Working/Organization-Standard.md"}, {"Repository Standard" = "Ways-of-Working/Repository-Standard.md"}, {"Repository Type Property" = "Ways-of-Working/Repository-Type-Property.md"},