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

[Marius Storhaug (MariusStorhaug)]

Ways of Working now treats Epic and PBI as planning aggregates while Task and Bug delivery leaves own implementation and pull-request closure. Workflow is the single process entry point, and ordinary stage procedures live under Ways of Working.

Changed: Agent setup remains actionable

AGENTS.md retains the complete agent-only installation and operating contract: improvement/escalation, ecosystem setup, local identity, README/CONTRIBUTING orientation, worktree discipline, micro-commits, push-every-commit, and MSXOrg memory's direct-main policy.

Changed: Docs use bare backing plus canonical worktree

Each docs repository uses docs.git as a bare backing repository and docs as its clean readable default-branch worktree. Missing installs create that topology directly. Safe simple clones migrate with local branches/tags verified and a retained backup; canonical and legacy worktrees are reused; unsafe states fail with rollback/actionable guidance. Memory remains a simple checkout.

Changed: Refresh-first discovery is enforced

The copied bootstrap seed refreshes and proves an existing bare default branch before creating/loading the canonical worktree. The full bootstrap then validates every configured context repository before any index traversal.

---

Technical details

• Makes Workflow.md the sole process and stage-routing owner.
• Moves stage procedures to Ways-of-Working/Workflow-Stages/.
• Restores all material root AGENTS policy without copying stages.
• Aligns Git Worktrees and bootstrap on sibling docs.git + docs topology.
• Preserves branches/tags during simple-clone migration and rolls back failures.
• Tests the executable Markdown seeds and all supported/unsafe topology states hermetically.

Relevant issues (or links)

• Fixes Align ways-of-working guidance with the issue model #86

[Copilot]

Pull request overview

This PR updates “Ways of Working”, agent role guidance, and affected capability docs to consistently consume the canonical issue model: Epic/PBI as planning aggregates and Task/Bug as delivery leaves, with delivery pull requests closing exactly one Task or Bug.

Changes:

• Reframes workflow and readiness/done gates around aggregate planning vs delivery-leaf execution (Task/Bug).
• Tightens PR/branching/stacking guidance so each delivery PR closes exactly one Task/Bug and uses native dependency edges for gating.
• Updates agent role docs and downstream automation docs to follow the same delivery-leaf closure contract.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/docs/Ways-of-Working/Workflow.md	Updates the end-to-end workflow to route planning through Epic/PBI and execute only ready Task/Bug delivery leaves.
src/docs/Ways-of-Working/Spec-Driven-Development.md	Replaces “tasks” framing with “delivery issues” framing and aligns decomposition guidance to canonical planning altitude.
src/docs/Ways-of-Working/Review-Etiquette.md	Narrows review scope to one closing Task/Bug and updates “reason from evidence” wording accordingly.
src/docs/Ways-of-Working/Repository-Standard.md	Adds requirement that PR descriptions close exactly one Task/Bug per PR Format.
src/docs/Ways-of-Working/Principles/Purpose-and-Direction.md	Moves strategy-path ownership to Goal Setting and delivery-path ownership to Issue Planning.
src/docs/Ways-of-Working/PR-Format.md	Codifies “exactly one closing Task/Bug” rule and clarifies aggregate issues are contextual/non-closing.
src/docs/Ways-of-Working/index.md	Updates generated index descriptions to match the revised delivery-leaf model wording.
src/docs/Ways-of-Working/Goal-Setting.md	Clarifies Initiative is strategy-layer and links to repository epics rather than mapping 1:1 into them.
src/docs/Ways-of-Working/Git-Worktrees.md	Re-scopes worktrees to repository-delivery Task/Bug leaves and excludes aggregates/operational tasks.
src/docs/Ways-of-Working/Fleet-Orchestration.md	Refactors campaign model to track one Task/Bug + PR per repository slice (adoption rules included).
src/docs/Ways-of-Working/Documentation-Model.md	Re-locates per-change implementation detail to delivery-leaf planning altitude + PR rather than generic “issue format”.
src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md	Splits readiness/done semantics across aggregates vs delivery leaves (including operational task path).
src/docs/Ways-of-Working/Contribution-Workflow.md	Defines the contribution flow as specifically for repository-delivery Task/Bug leaves.
src/docs/Ways-of-Working/Branching-and-Merging.md	Updates branch and stacked-PR guidance to align with Task/Bug leaves and native dependency edges.
src/docs/Capabilities/downstream-release-propagation/spec.md	Updates requirements so propagation creates/reuses a Task delivery leaf and opens a PR that closes it.
src/docs/Capabilities/downstream-release-propagation/design.md	Updates design flow so agent creates/reuses Task issue before opening the closing PR.
src/docs/Agents/reviewer.md	Aligns Reviewer role to validate “closes exactly one Task/Bug” and review against that delivery leaf.
src/docs/Agents/index.md	Updates agent lifecycle page descriptions to match routing/planning vs delivery-leaf execution.
src/docs/Agents/implement.md	Refocuses Implement role on ready, unblocked Task/Bug leaves and checklist-item execution.
src/docs/Agents/define.md	Refocuses Define role on routing to correct native type and planning at correct altitude.

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

src/docs/Capabilities/downstream-release-propagation/spec.md:46

• Grammar: “one Task and closing PR” is missing an article. Consider “one Task and a closing PR …” so the sentence reads cleanly.

- A stable release yields one Task and closing PR in each declared dependent, carrying the immutable reference and an impact summary without manual coordination.

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 29 out of 29 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 43 out of 43 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 43 out of 43 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 43 out of 43 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 43 out of 43 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 43 out of 43 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 43 out of 43 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (2)

src/docs/Ways-of-Working/Git-Worktrees.md:130

• This cleanup command uses "<repo>.git" and a hard-coded branch name, which is inconsistent with the variables defined in the preceding example. Prefer $repo.git and $branchName so the snippet remains internally consistent.

git --git-dir="<repo>.git" branch -D feat/42-add-pagination

src/docs/Ways-of-Working/Git-Worktrees.md:133

• This cleanup command uses the literal placeholder "<repo>.git"; for consistency with the earlier commands in the example, use $repo.git.

git --git-dir="<repo>.git" worktree prune

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Marius Storhaug (MariusStorhaug)]

Suggestion (non-blocking): would it help to add an explicit standards-pass bullet in 3. Assess the diff so reviewers systematically walk every applicable standards chapter, rather than only the first ones that come to mind? That would keep "write once, reference everywhere" centralized here and reduce the need for downstream bespoke validation procedures.

Proposed bullet text:

• Standards conformance — identify every standards chapter that applies to the languages and domains the diff touches (cross-cutting Coding Standards and relevant project-specific standards), then check the change against each one.

Optional follow-on: consider mirroring a short pointer in Implement.md step 4 (self-review/triage) so author-side passes apply the same coverage before handoff.

[Copilot]

Pull request overview

Copilot reviewed 43 out of 43 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 43 out of 43 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 43 out of 43 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 43 out of 43 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 43 out of 43 changed files in this pull request and generated no new comments.