📖 [Docs]: Ways of working now follows the canonical issue model

src/docs/Agents/agent-author.md

@@ -1,47 +1,47 @@
 ---
-title: Agent Author
-description: Create and maintain the agent role descriptions and the per-repository pointer files that reference them.
+title: Maintain Agent Workflow
+description: Maintain the shared workflow stages and the thin repository pointers that reference them.
 ---
 
-# Agent Author
+# Maintain Agent Workflow
 
-Create and maintain the agent roles in this section, and the per-repository pointer files that reference them. Every role description is grounded in the [Ways of Working](../Ways-of-Working/index.md); every pointer file stays thin. Agent Author keeps descriptions and pointers honest — it does not encode standards into either.
+Maintain the workflow stages in this section and the per-repository pointer files that reference them. Every stage description is grounded in the [Ways of Working](../Ways-of-Working/index.md), and every pointer file stays thin. This maintenance path keeps the workflow and pointers honest; it does not encode standards into either.
 
-## When to use
+## Enter this maintenance path when
 
-Create a new agent role, update an existing one, review agent quality, or refactor a bloated agent file back into a thin pointer over the docs.
+Create a new workflow stage, update an existing stage, review workflow quality, or refactor a bloated agent file back into a thin pointer over the docs.
 
 ## Flow
 
 ### 1. Gather requirements
 
-1. Identify the role — the single job it owns, and its boundary.
-2. Identify the docs pages that govern that role; confirm they exist.
-3. Identify what the role must **not** do — boundaries prevent scope creep.
+1. Identify the stage — its entry condition, job, handoff, and boundary.
+2. Identify the docs pages that govern the stage; confirm they exist.
+3. Identify what the stage must **not** do — boundaries prevent scope creep.
 
 ### 2. Author the description
 
-Write the role as a page in this section, following the shape of its siblings: front matter (`title`, `description`), a one-paragraph role and boundary, when to use, a numbered flow, operating rules, and a "Where this connects" list.
+Write the stage as a page in this section, following the shape of its siblings: front matter (`title`, `description`), a one-paragraph purpose and boundary, entry condition, input, numbered flow, operating rules, and a "Where this connects" list.
 
 - **Link, don't inline.** If a standard exists in the docs, link to it — never paste it in.
 - **Procedural, not conversational.** Numbered imperatives, no filler.
 - **Keyword-rich description.** The front-matter `description` is the discovery surface.
 
 ### 3. Keep pointers thin
 
-A repository never carries a copy of a role. Its `AGENTS.md` — and the `CLAUDE.md` that imports it — point to these pages and add only repo-specific nuance and the genuinely tool-specific settings (permission scopes, model choice) that cannot be expressed as a pointer. When a new runtime is adopted, add a thin pointer; do not move process knowledge into it. See [Agentic Development](../Ways-of-Working/Agentic-Development.md).
+A repository never carries a copy of the workflow. Its `AGENTS.md` — and the `CLAUDE.md` that imports it — point to these pages and add only repo-specific nuance and the genuinely tool-specific settings (permission scopes, model choice) that cannot be expressed as a pointer. When a new runtime is adopted, add a thin pointer; do not move process knowledge into it. See [Agentic Development](../Ways-of-Working/Agentic-Development.md).
 
 ### 4. Validate
 
 1. Front-matter YAML parses cleanly.
 2. Every link resolves, and the body duplicates no doc content.
-3. The role is added to the navigation so its index row generates.
+3. The stage is added to the navigation so its index row generates.
 
 ## Operating rules
 
 1. Docs are the source of truth. If a standard is missing, propose adding it to the docs — do not embed it in an agent.
-2. One agent, one job. Multiple roles mean multiple pages.
-3. Update the navigation when adding or removing a role.
+2. One stage, one job and handoff. Distinct stages use distinct pages.
+3. Update the navigation when adding or removing a stage.
 
 ## Where this connects
 

src/docs/Agents/define.md

@@ -1,13 +1,13 @@
 ---
-title: Define
-description: Capture, refine, and plan a change into an actionable issue ready for implementation.
+title: Define Stage
+description: The workflow stage that captures, routes, refines, and plans work at the correct issue altitude.
 ---
 
-# Define
+# Define Stage
 
-Take something someone wants — a feature, a bug, an improvement, external feedback, or a production signal — and turn it into a planned, actionable issue. The output is either a single Task with its three sections populated, or a decomposed initiative with structured sub-issues. Define plans work; it does not build it.
+Define is the first stage of the [Agent Workflow](index.md). It takes something someone wants — a feature, a bug, an improvement, external feedback, or a production signal — and routes it to the correct native issue type. The stage hands off an Epic or PBI ready to coordinate and decompose, or a Task or Bug ready for delivery. Define plans work; it does not build it.
 
-## When to use
+## Enter this stage when
 
 Capture a desire for change, write an issue, plan work, decompose an epic, refine a bug report, create sub-issues, structure a feature request, or turn feedback into a task.
 
@@ -19,10 +19,10 @@ A description of a desired change, a feedback issue from a non-contributor (trea
 
 ### 1. Capture
 
-Turn the input into an issue with Section 1 (context and request).
+Turn the input into an issue with a provisional native type and enough local context to refine it.
 
 1. Search for duplicates first — propose consolidation rather than creating a new issue.
-2. Frame from the user's perspective per [Issue Format](../Ways-of-Working/Issues/Process/Format.md).
+2. Follow the universal [Issue Format](../Ways-of-Working/Issues/Process/Format.md) and the selected type page for its body.
 3. Acceptance criteria must be user-observable and testable.
 
 ### 2. Refine
@@ -38,21 +38,22 @@ Ground the issue so anyone reading it agrees on what "done" means, up to the [De
 
 Decide how the work will happen and record the decisions.
 
-1. **Task** — one deliverable, one pull request. Populate the technical decisions and the implementation plan per [Issue Format](../Ways-of-Working/Issues/Process/Format.md).
-2. **Larger work** — decompose into child issues per [Issue Hierarchy](../Ways-of-Working/Issues/Types/Hierarchy.md).
-3. Find the minimum viable path — spike, then proof of concept, then minimum viable product, then improve.
-4. Record decisions with their rationale and the alternatives considered.
-5. Resolve open questions before finishing; defer anything that does not block this slice to a follow-up issue.
+1. Route the work through the [Issue Hierarchy](../Ways-of-Working/Issues/Types/Hierarchy.md); do not infer altitude from effort, priority, or a legacy label.
+2. For an Epic or PBI, establish native containment and dependency relationships and refine the first required children to their own readiness gates.
+3. For a Task or Bug, produce one executable delivery plan sized for one pull request. Use the audited operational Task path only when no repository artifact exists.
+4. Find the minimum viable path — spike, then proof of concept, then minimum viable product, then improve.
+5. Record decisions at the issue's [planning altitude](../Ways-of-Working/Issues/Process/Planning.md), with rationale and alternatives where they matter.
+6. Resolve open questions before finishing; defer anything that does not block this slice to a follow-up issue.
 
 ## Operating rules
 
 1. Tone is impersonal. The issue description is the source of truth; comments record what changed.
 2. External references are hyperlinks.
 3. Do not modify a feedback issue from a non-contributor — create an internal issue and cross-link.
-4. Stop when the issue is plannable. Do not build, branch, or open pull requests — that is [Implement](implement.md).
+4. Stop when the issue meets the readiness gate for its altitude. Hand a ready delivery leaf to the [Implement stage](implement.md); do not build, branch, or open pull requests here.
 
 ## Where this connects
 
 - [Workflow](../Ways-of-Working/Workflow.md) — the loop this opens.
-- [Issue Format](../Ways-of-Working/Issues/Process/Format.md) and [Issue Hierarchy](../Ways-of-Working/Issues/Types/Hierarchy.md) — issue structure and levels.
+- [Issue Format](../Ways-of-Working/Issues/Process/Format.md), [Issue Planning](../Ways-of-Working/Issues/Process/Planning.md), [Issue Relationships](../Ways-of-Working/Issues/Process/Relationships.md), and [Issue Hierarchy](../Ways-of-Working/Issues/Types/Hierarchy.md) — canonical issue ownership.
 - [Definition of Ready and Done](../Ways-of-Working/Definition-of-Ready-and-Done.md) — the readiness bar this aims for.

src/docs/Agents/implement.md

@@ -1,43 +1,43 @@
 ---
-title: Implement
-description: Take a planned issue and deliver it as a review-ready pull request — branch, build, self-review, and finalize.
+title: Implement Stage
+description: The workflow stage that delivers one ready Task or Bug as a review-ready pull request.
 ---
 
-# Implement
+# Implement Stage
 
-Take a planned issue and deliver working software in a review-ready pull request. Owns the full delivery loop: branching, coding, committing, opening the pull request, tracking progress, running the automated review loop, responding to feedback, and finalizing the release note. Implement builds; it does not plan from scratch or review others' work.
+Implement is the delivery stage of the [Agent Workflow](index.md). It takes one ready, unblocked Task or Bug and produces working software in a review-ready pull request. The stage owns branching, coding, committing, opening the pull request, tracking progress, running the automated review loop, responding to feedback, and finalizing the release note. Implement builds delivery leaves; it does not implement an Epic or PBI aggregate, plan from scratch, or supply the independent review.
 
-## When to use
+## Enter this stage when
 
-Implement an issue, build a feature, fix a bug, create a branch, open a pull request, respond to review feedback, or finalize a pull request. Given an initiative rather than a task, pick the next unfinished sub-issue.
+Implement a Task, fix a Bug, create a branch, open a pull request, respond to review feedback, or finalize a pull request. Given an Initiative, Epic, or PBI, follow native containment and blocked-by relationships to a ready delivery leaf; do not treat list order as execution order.
 
 ## Input
 
-A Task issue number or URL with its three sections populated.
+A ready repository-delivery Task or Bug number or URL. An operational Task follows its canonical [operational delivery path](../Ways-of-Working/Issues/Types/Task.md#operational-delivery) instead of this pull-request flow.
 
 ## Flow
 
 ### 1. Orient
 
-1. Read the issue fully — all three sections per [Issue Format](../Ways-of-Working/Issues/Process/Format.md).
+1. Read the delivery issue fully, including its type-specific body, native parent, and dependency edges.
 2. Read the repository README first per [README-Driven Context](../Ways-of-Working/Readme-Driven-Context.md).
 3. Identify the stack and load the relevant [Coding Standards](../Coding-Standards/index.md). Repo-local linter config wins where it disagrees with a published standard.
 
 ### 2. Branch and draft pull request
 
-Use [git worktrees](../Ways-of-Working/Git-Worktrees.md) for every issue.
+Use [git worktrees](../Ways-of-Working/Git-Worktrees.md) for every repository-delivery Task or Bug.
 
 1. Create a worktree from the default branch per [Branching and Merging](../Ways-of-Working/Branching-and-Merging.md).
 2. Push an initial commit and immediately open a **draft** pull request so CI attaches from the first push.
-3. Link the issue with a closing keyword, and assign the pull request.
+3. Close exactly that Task or Bug in the pull request. Reference a parent PBI or Epic only as non-closing context, then assign the pull request.
 
 ### 3. Build
 
-For each task in the plan:
+For each checklist item in the delivery plan:
 
 1. Implement the change and self-review the staged diff.
 2. Commit per [Commit Conventions](../Ways-of-Working/Commit-Conventions.md) — one logical change per commit.
-3. Update the issue as each task completes — do not batch.
+3. Update the issue as each checklist item completes — do not batch.
 4. Push regularly so CI runs against current work.
 
 When the plan is wrong, stop and document the conflict in a comment, then update the plan before resuming. Out-of-scope problems go to [Define](define.md).
@@ -57,13 +57,14 @@ When the change meets the [Definition of Ready for Review](../Ways-of-Working/De
 ## Operating rules
 
 1. Micro-commits, one logical change each, with descriptive messages.
-2. Progress is visible — issues updated as tasks complete, not in bulk.
+2. Progress is visible — the delivery issue is updated as checklist items complete, not in bulk.
 3. Draft pull request from the start; stay in the issue's scope.
-4. Mark ready only when the change meets the Definition of Ready for Review — never with open tasks.
-5. No planning from scratch (that is [Define](define.md)); no reviewing others' pull requests (that is [Reviewer](reviewer.md)).
+4. Mark ready only when the change meets the Definition of Ready for Review — never with open checklist items.
+5. Return unplanned work to [Define](define.md) and hand review-ready work to [Review](reviewer.md).
 
 ## Where this connects
 
 - [Contribution Workflow](../Ways-of-Working/Contribution-Workflow.md) — the draft-first loop this runs.
+- [Issue Lifecycle](../Ways-of-Working/Issues/Process/Lifecycle.md) and [Issue Relationships](../Ways-of-Working/Issues/Process/Relationships.md) — delivery-leaf eligibility and blockers.
 - [Definition of Ready and Done](../Ways-of-Working/Definition-of-Ready-and-Done.md) — the gate this hands off at.
 - [PR Format](../Ways-of-Working/PR-Format.md) and [Branching and Merging](../Ways-of-Working/Branching-and-Merging.md) — packaging and landing.

src/docs/Agents/index.md

@@ -1,26 +1,43 @@
 ---
-title: Agents
-description: The roles agents play across the ecosystem — authored once as documentation and pointed to from each repository.
+title: Agent Workflow
+description: The stages agents follow to define, implement, and review work across the ecosystem.
 ---
 
-# Agents
+# Agent Workflow
 
-The roles agents play across the MSX ecosystem, authored once as documentation. Each page describes one role — its job, when to use it, and the steps it follows — grounded in the [Ways of Working](../Ways-of-Working/index.md) rather than restating them.
+This is the workflow agents follow across the MSX ecosystem. Each page describes one stage: its entry condition, boundary, procedure, and handoff. The stages apply the [Ways of Working](../Ways-of-Working/index.md) without restating the standards they consume.
 
-These descriptions are the **single source for agent behaviour**. A repository does not carry its own copy; its `AGENTS.md` and `CLAUDE.md` are thin pointers to these pages ([Agentic Development](../Ways-of-Working/Agentic-Development.md)). Humans read the same pages a new teammate would.
+These stage descriptions are the **single source for agent workflow behavior**. A repository does not carry its own copy; its `AGENTS.md` and `CLAUDE.md` are thin pointers to these pages ([Agentic Development](../Ways-of-Working/Agentic-Development.md)). Humans can follow the same workflow.
 
-The lifecycle runs **Define → Implement → Review**: capture and plan the work, build it in a pull request, then review it. Two supporting roles — Security Reviewer and Agent Author — run alongside.
+## The workflow
 
-## Contents
+```mermaid
+flowchart LR
+    D[Define] --> I[Implement]
+    I --> R[Review]
+    R -->|changes required| I
+    R -->|approved| Done[Merge gate]
+    R -->|specialized security pass| S[Security Review]
+    S --> R
+```
+
+- **Define** captures, routes, refines, and plans work until it meets the readiness gate for its issue altitude.
+- **Implement** takes one ready Task or Bug through delivery and hands off a review-ready pull request.
+- **Review** supplies the independent perspective and either returns actionable feedback or approves the change.
+- **Security Review** is a specialized review path entered when the requested scope requires a defensive security assessment.
+
+[Maintain Agent Workflow](agent-author.md) is not a delivery stage. It updates these stage descriptions and the thin repository pointers when the workflow itself changes.
+
+## Stages and maintenance
 
 <!-- INDEX:START -->
 
 | Page | Description |
 | --- | --- |
-| [Define](define.md) | Capture, refine, and plan a change into an actionable issue ready for implementation. |
-| [Implement](implement.md) | Take a planned issue and deliver it as a review-ready pull request — branch, build, self-review, and finalize. |
-| [Reviewer](reviewer.md) | Review someone else's pull request for delivery, taste, security, and undiscussed decisions. |
-| [Security Reviewer](security-reviewer.md) | A structured, defensive security review that reports vulnerabilities as an actionable responsible-disclosure issue. |
-| [Agent Author](agent-author.md) | Create and maintain the agent role descriptions and the per-repository pointer files that reference them. |
+| [Define Stage](define.md) | The workflow stage that captures, routes, refines, and plans work at the correct issue altitude. |
+| [Implement Stage](implement.md) | The workflow stage that delivers one ready Task or Bug as a review-ready pull request. |
+| [Review Stage](reviewer.md) | The workflow stage that independently reviews a pull request for delivery, taste, security, and decisions. |
+| [Security Review Stage](security-reviewer.md) | A specialized workflow stage for defensive security review and responsible disclosure. |
+| [Maintain Agent Workflow](agent-author.md) | Maintain the shared workflow stages and the thin repository pointers that reference them. |
 
 <!-- INDEX:END -->