agentme 0.33.1 → 0.35.0

package/.filedist-package.yml

@@ -28,7 +28,7 @@ sets:
       path: .
       gitignore: false
       symlinks:
-        - source: .xdrs/**/skills/150-plan-mode-consistency
+        - source: .xdrs/**/skills/refine-plan-mode
           target: .agents/skills
     presets:
       - basic

package/.xdrs/agentme/bdrs/index.md

@@ -0,0 +1,20 @@
+# agentme BDRs Index
+
+Business decisions for software development project management practices in the agentme scope.
+
+## Principles
+
+Organisational structure, team topology, and strategic alignment concepts.
+
+- [agentme-bdr-001](principles/001-company-organizational-levels.md) - **Company organizational levels** — Defines the Group, Company, and Business Unit taxonomy used to describe how organisations are structured
+- [agentme-bdr-002](principles/002-okr-framework.md) - **OKR framework** — Defines the Strategic, Tactical, and Operational OKR framework and connection rules
+- [agentme-bdr-003](principles/003-product-delivery-value-flow.md) - **Product delivery value flow** — Defines the end-to-end chain from Strategic OKRs through roles and artefacts to fulfilled Tactical OKRs
+
+## Operations
+
+Project management workflow and structure for development teams.
+
+- [agentme-bdr-401](operations/401-epic-feature-story-planning.md) - **Epic / Feature / User Story planning** — Organize development work as epics, features, and user stories using XDRS plan documents
+- [agentme-bdr-402](operations/402-digital-product-roles.md) - **Digital product roles — organisation & cross-team** — Defines team purpose, workforce allocation, roles overview, and org-level and cross-team roles (PM, Principal Engineer, Solution Architect)
+- [agentme-bdr-403](operations/403-product-team-composition.md) - **Product team composition** — Defines team composition models, squad structure, squad dynamics, and known structural gaps for Product Teams
+- [agentme-bdr-404](operations/404-team-roles-and-specialists.md) - **Digital product roles — team & specialists** — Defines team-level roles (PO, PjM, BA, AI BA, AI Lead, AI Engineer, Tech Lead, engineers) and shared specialist roles

package/.xdrs/agentme/bdrs/operations/.assets/team-composition.svg

@@ -0,0 +1,171 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="920" height="685" viewBox="0 0 920 685">
+  <defs>
+    <marker id="arr" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
+      <polygon points="0 0, 8 3, 0 6" fill="#9CA3AF"/>
+    </marker>
+    <marker id="arr-v" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
+      <polygon points="0 0, 8 3, 0 6" fill="#7C3AED"/>
+    </marker>
+  </defs>
+
+  <rect width="920" height="685" fill="#F8FAFC"/>
+
+  <!-- ===== CROSS-TEAM ===== -->
+  <rect x="10" y="10" width="900" height="95" rx="8" fill="#EEF2FF" stroke="#C7D2FE" stroke-width="1.5"/>
+  <text x="22" y="30" font-family="system-ui,sans-serif" font-size="10" font-weight="700" fill="#6366F1" letter-spacing="1">ORGANISATION &amp; CROSS-TEAM ROLES</text>
+
+  <rect x="65" y="38" width="165" height="52" rx="6" fill="#4F46E5"/>
+  <text x="147" y="59" font-family="system-ui,sans-serif" font-size="12" font-weight="700" fill="white" text-anchor="middle">Product Manager</text>
+  <text x="147" y="76" font-family="system-ui,sans-serif" font-size="10" fill="#C7D2FE" text-anchor="middle">What / When</text>
+
+  <rect x="378" y="38" width="165" height="52" rx="6" fill="#1D4ED8"/>
+  <text x="460" y="59" font-family="system-ui,sans-serif" font-size="12" font-weight="700" fill="white" text-anchor="middle">Principal Engineer</text>
+  <text x="460" y="76" font-family="system-ui,sans-serif" font-size="10" fill="#BFDBFE" text-anchor="middle">How</text>
+
+  <rect x="692" y="38" width="165" height="52" rx="6" fill="#1D4ED8"/>
+  <text x="774" y="59" font-family="system-ui,sans-serif" font-size="12" font-weight="700" fill="white" text-anchor="middle">Solution Architect</text>
+  <text x="774" y="76" font-family="system-ui,sans-serif" font-size="10" fill="#BFDBFE" text-anchor="middle">What</text>
+
+  <!-- Arrow: cross-team → team -->
+  <line x1="460" y1="105" x2="460" y2="122" stroke="#9CA3AF" stroke-width="1.5" marker-end="url(#arr)"/>
+
+  <!-- ===== TEAM ===== -->
+  <rect x="10" y="125" width="900" height="95" rx="8" fill="#F0FDF4" stroke="#86EFAC" stroke-width="1.5"/>
+  <text x="22" y="144" font-family="system-ui,sans-serif" font-size="10" font-weight="700" fill="#16A34A" letter-spacing="1">TEAM X</text>
+
+  <!-- PO — shared, dashed border -->
+  <rect x="22" y="150" width="138" height="55" rx="6" fill="#4F46E5" stroke="#A5B4FC" stroke-width="1.5" stroke-dasharray="5,3"/>
+  <text x="91" y="170" font-family="system-ui,sans-serif" font-size="11" font-weight="700" fill="white" text-anchor="middle">Product Owner</text>
+  <text x="91" y="185" font-family="system-ui,sans-serif" font-size="9" fill="#C7D2FE" text-anchor="middle">What / When</text>
+  <text x="91" y="198" font-family="system-ui,sans-serif" font-size="9" fill="#E0E7FF" text-anchor="middle">↔ all squads</text>
+
+  <!-- PM -->
+  <rect x="178" y="150" width="138" height="55" rx="6" fill="#7C3AED"/>
+  <text x="247" y="170" font-family="system-ui,sans-serif" font-size="11" font-weight="700" fill="white" text-anchor="middle">Project Manager</text>
+  <text x="247" y="185" font-family="system-ui,sans-serif" font-size="9" fill="#DDD6FE" text-anchor="middle">When / How</text>
+  <text x="247" y="198" font-family="system-ui,sans-serif" font-size="9" fill="#EDE9FE" text-anchor="middle">cross-squad deps</text>
+
+  <!-- Tech Lead — shared, dashed border -->
+  <rect x="567" y="150" width="138" height="55" rx="6" fill="#059669" stroke="#6EE7B7" stroke-width="1.5" stroke-dasharray="5,3"/>
+  <text x="636" y="170" font-family="system-ui,sans-serif" font-size="11" font-weight="700" fill="white" text-anchor="middle">Tech Lead</text>
+  <text x="636" y="185" font-family="system-ui,sans-serif" font-size="9" fill="#A7F3D0" text-anchor="middle">How / When</text>
+  <text x="636" y="198" font-family="system-ui,sans-serif" font-size="9" fill="#D1FAE5" text-anchor="middle">↔ all squads</text>
+
+  <!-- AI Lead — shared, dashed border -->
+  <rect x="723" y="150" width="138" height="55" rx="6" fill="#D97706" stroke="#FDE68A" stroke-width="1.5" stroke-dasharray="5,3"/>
+  <text x="792" y="170" font-family="system-ui,sans-serif" font-size="11" font-weight="700" fill="white" text-anchor="middle">AI Lead</text>
+  <text x="792" y="185" font-family="system-ui,sans-serif" font-size="9" fill="#FDE68A" text-anchor="middle">How / When</text>
+  <text x="792" y="198" font-family="system-ui,sans-serif" font-size="9" fill="#FEF3C7" text-anchor="middle">↔ all squads</text>
+
+  <!-- Arrows: team → squads -->
+  <line x1="152" y1="220" x2="152" y2="237" stroke="#9CA3AF" stroke-width="1.5" marker-end="url(#arr)"/>
+  <line x1="460" y1="220" x2="460" y2="237" stroke="#9CA3AF" stroke-width="1.5" marker-end="url(#arr)"/>
+  <line x1="768" y1="220" x2="768" y2="237" stroke="#9CA3AF" stroke-width="1.5" marker-end="url(#arr)"/>
+
+  <!-- BA fluidity labels and arrows (between BA row of adjacent squads) -->
+  <text x="305" y="287" font-family="system-ui,sans-serif" font-size="9" fill="#7C3AED" text-anchor="middle" font-style="italic">fluid</text>
+  <line x1="279" y1="293" x2="330" y2="293" stroke="#7C3AED" stroke-width="1.5" stroke-dasharray="4,3" marker-end="url(#arr-v)"/>
+  <text x="613" y="287" font-family="system-ui,sans-serif" font-size="9" fill="#7C3AED" text-anchor="middle" font-style="italic">fluid</text>
+  <line x1="587" y1="293" x2="638" y2="293" stroke="#7C3AED" stroke-width="1.5" stroke-dasharray="4,3" marker-end="url(#arr-v)"/>
+
+  <!-- ===== SQUAD 1 ===== -->
+  <rect x="10" y="240" width="283" height="365" rx="8" fill="#FFFBEB" stroke="#FCD34D" stroke-width="1.5"/>
+  <text x="152" y="262" font-family="system-ui,sans-serif" font-size="12" font-weight="700" fill="#92400E" text-anchor="middle">Squad 1</text>
+
+  <rect x="24" y="270" width="255" height="46" rx="5" fill="#7C3AED"/>
+  <text x="152" y="288" font-family="system-ui,sans-serif" font-size="11" font-weight="700" fill="white" text-anchor="middle">Business Analyst</text>
+  <text x="152" y="304" font-family="system-ui,sans-serif" font-size="9" fill="#EDE9FE" text-anchor="middle">Requirements · Process Design</text>
+
+  <rect x="24" y="325" width="255" height="46" rx="5" fill="#D97706"/>
+  <text x="152" y="343" font-family="system-ui,sans-serif" font-size="11" font-weight="700" fill="white" text-anchor="middle">AI Engineer</text>
+  <text x="152" y="359" font-family="system-ui,sans-serif" font-size="9" fill="#FEF3C7" text-anchor="middle">Models · Agents · Evals</text>
+
+  <rect x="24" y="380" width="255" height="46" rx="5" fill="#D97706"/>
+  <text x="152" y="398" font-family="system-ui,sans-serif" font-size="11" font-weight="700" fill="white" text-anchor="middle">AI Engineer</text>
+  <text x="152" y="414" font-family="system-ui,sans-serif" font-size="9" fill="#FEF3C7" text-anchor="middle">Models · Agents · Evals</text>
+
+  <!-- FS Eng 1 = Squad Lead (thicker border) -->
+  <rect x="24" y="435" width="255" height="46" rx="5" fill="#059669" stroke="#34D399" stroke-width="2"/>
+  <text x="152" y="453" font-family="system-ui,sans-serif" font-size="11" font-weight="700" fill="white" text-anchor="middle">Engineer  ★</text>
+  <text x="152" y="469" font-family="system-ui,sans-serif" font-size="9" fill="#D1FAE5" text-anchor="middle">APIs · Pipelines · Frontend</text>
+
+  <rect x="24" y="490" width="255" height="46" rx="5" fill="#059669"/>
+  <text x="152" y="508" font-family="system-ui,sans-serif" font-size="11" font-weight="700" fill="white" text-anchor="middle">Engineer</text>
+  <text x="152" y="524" font-family="system-ui,sans-serif" font-size="9" fill="#D1FAE5" text-anchor="middle">APIs · Pipelines · Frontend</text>
+
+  <text x="152" y="556" font-family="system-ui,sans-serif" font-size="8" fill="#92400E" text-anchor="middle" font-style="italic">★ Squad Lead — ceremonies, shielding, prioritisation</text>
+
+  <!-- ===== SQUAD 2 ===== -->
+  <rect x="318" y="240" width="283" height="365" rx="8" fill="#FFFBEB" stroke="#FCD34D" stroke-width="1.5"/>
+  <text x="460" y="262" font-family="system-ui,sans-serif" font-size="12" font-weight="700" fill="#92400E" text-anchor="middle">Squad 2</text>
+
+  <rect x="332" y="270" width="255" height="46" rx="5" fill="#7C3AED"/>
+  <text x="460" y="288" font-family="system-ui,sans-serif" font-size="11" font-weight="700" fill="white" text-anchor="middle">AI Business Analyst</text>
+  <text x="460" y="304" font-family="system-ui,sans-serif" font-size="9" fill="#EDE9FE" text-anchor="middle">AI Requirements · Agent Specs</text>
+
+  <!-- AI Eng 1 = Squad Lead -->
+  <rect x="332" y="325" width="255" height="46" rx="5" fill="#D97706" stroke="#FDE68A" stroke-width="2"/>
+  <text x="460" y="343" font-family="system-ui,sans-serif" font-size="11" font-weight="700" fill="white" text-anchor="middle">AI Engineer  ★</text>
+  <text x="460" y="359" font-family="system-ui,sans-serif" font-size="9" fill="#FEF3C7" text-anchor="middle">Models · Agents · Evals</text>
+
+  <rect x="332" y="380" width="255" height="46" rx="5" fill="#D97706"/>
+  <text x="460" y="398" font-family="system-ui,sans-serif" font-size="11" font-weight="700" fill="white" text-anchor="middle">AI Engineer</text>
+  <text x="460" y="414" font-family="system-ui,sans-serif" font-size="9" fill="#FEF3C7" text-anchor="middle">Models · Agents · Evals</text>
+
+  <rect x="332" y="435" width="255" height="46" rx="5" fill="#059669"/>
+  <text x="460" y="453" font-family="system-ui,sans-serif" font-size="11" font-weight="700" fill="white" text-anchor="middle">Engineer</text>
+  <text x="460" y="469" font-family="system-ui,sans-serif" font-size="9" fill="#D1FAE5" text-anchor="middle">APIs · Pipelines · Frontend</text>
+
+  <rect x="332" y="490" width="255" height="46" rx="5" fill="#059669"/>
+  <text x="460" y="508" font-family="system-ui,sans-serif" font-size="11" font-weight="700" fill="white" text-anchor="middle">Engineer</text>
+  <text x="460" y="524" font-family="system-ui,sans-serif" font-size="9" fill="#D1FAE5" text-anchor="middle">APIs · Pipelines · Frontend</text>
+
+  <text x="460" y="556" font-family="system-ui,sans-serif" font-size="8" fill="#92400E" text-anchor="middle" font-style="italic">★ Squad Lead — ceremonies, shielding, prioritisation</text>
+
+  <!-- ===== SQUAD 3 ===== -->
+  <rect x="626" y="240" width="283" height="365" rx="8" fill="#FFFBEB" stroke="#FCD34D" stroke-width="1.5"/>
+  <text x="768" y="262" font-family="system-ui,sans-serif" font-size="12" font-weight="700" fill="#92400E" text-anchor="middle">Squad 3</text>
+
+  <rect x="640" y="270" width="255" height="46" rx="5" fill="#7C3AED"/>
+  <text x="768" y="288" font-family="system-ui,sans-serif" font-size="11" font-weight="700" fill="white" text-anchor="middle">Business Analyst</text>
+  <text x="768" y="304" font-family="system-ui,sans-serif" font-size="9" fill="#EDE9FE" text-anchor="middle">Requirements · Process Design</text>
+
+  <rect x="640" y="325" width="255" height="46" rx="5" fill="#D97706"/>
+  <text x="768" y="343" font-family="system-ui,sans-serif" font-size="11" font-weight="700" fill="white" text-anchor="middle">AI Engineer</text>
+  <text x="768" y="359" font-family="system-ui,sans-serif" font-size="9" fill="#FEF3C7" text-anchor="middle">Models · Agents · Evals</text>
+
+  <rect x="640" y="380" width="255" height="46" rx="5" fill="#D97706"/>
+  <text x="768" y="398" font-family="system-ui,sans-serif" font-size="11" font-weight="700" fill="white" text-anchor="middle">AI Engineer</text>
+  <text x="768" y="414" font-family="system-ui,sans-serif" font-size="9" fill="#FEF3C7" text-anchor="middle">Models · Agents · Evals</text>
+
+  <rect x="640" y="435" width="255" height="46" rx="5" fill="#059669"/>
+  <text x="768" y="453" font-family="system-ui,sans-serif" font-size="11" font-weight="700" fill="white" text-anchor="middle">Engineer</text>
+  <text x="768" y="469" font-family="system-ui,sans-serif" font-size="9" fill="#D1FAE5" text-anchor="middle">APIs · Pipelines · Frontend</text>
+
+  <!-- Eng 2 = Squad Lead -->
+  <rect x="640" y="490" width="255" height="46" rx="5" fill="#059669" stroke="#34D399" stroke-width="2"/>
+  <text x="768" y="508" font-family="system-ui,sans-serif" font-size="11" font-weight="700" fill="white" text-anchor="middle">Engineer  ★</text>
+  <text x="768" y="524" font-family="system-ui,sans-serif" font-size="9" fill="#D1FAE5" text-anchor="middle">APIs · Pipelines · Frontend</text>
+
+  <text x="768" y="556" font-family="system-ui,sans-serif" font-size="8" fill="#92400E" text-anchor="middle" font-style="italic">★ Squad Lead — ceremonies, shielding, prioritisation</text>
+
+  <!-- ===== LEGEND ===== -->
+  <rect x="10" y="622" width="900" height="52" rx="6" fill="#F3F4F6" stroke="#E5E7EB" stroke-width="1"/>
+
+  <rect x="20" y="632" width="11" height="11" rx="2" fill="#4F46E5"/>
+  <text x="35" y="642" font-family="system-ui,sans-serif" font-size="10" fill="#374151">Vision / Product</text>
+
+  <rect x="160" y="632" width="11" height="11" rx="2" fill="#7C3AED"/>
+  <text x="175" y="642" font-family="system-ui,sans-serif" font-size="10" fill="#374151">Requirements / BA</text>
+
+  <rect x="315" y="632" width="11" height="11" rx="2" fill="#D97706"/>
+  <text x="330" y="642" font-family="system-ui,sans-serif" font-size="10" fill="#374151">AI Engineering</text>
+
+  <rect x="455" y="632" width="11" height="11" rx="2" fill="#059669"/>
+  <text x="470" y="642" font-family="system-ui,sans-serif" font-size="10" fill="#374151">Engineering</text>
+
+  <rect x="575" y="632" width="11" height="11" rx="2" fill="#1D4ED8"/>
+  <text x="590" y="642" font-family="system-ui,sans-serif" font-size="10" fill="#374151">Arch / Standards</text>
+
+  <text x="20" y="660" font-family="system-ui,sans-serif" font-size="9" fill="#6B7280" font-style="italic">★ = Squad Lead (formal role, selected at squad formation)     - - border = shared across all squads     ╌╌▶ = BA / AI BA moves between squads (self-organised, PO aware)</text>
+</svg>

package/.xdrs/agentme/bdrs/operations/401-epic-feature-story-planning.md

@@ -0,0 +1,159 @@
+---
+name: agentme-bdr-policy-401-epic-feature-user-story-planning
+description: Defines how to organize software development project management work as epics, features, and user stories using XDRS plan documents. Use when creating, reviewing, or navigating epic plans, feature milestones, or user story files.
+apply-to: AI coding agents and developers managing software development work in projects that follow agentme standards
+valid-from: 2026-08-28
+---
+
+# agentme-bdr-policy-401: Epic / Feature / User Story Planning
+
+## Context and Problem Statement
+
+Development teams need a lightweight, code-adjacent way to organize and track software development work. Without a standard structure, epics, features, and user stories are scattered across external tools or undocumented, making it difficult for agents and developers to discover what has been planned, what is pending, and what has been implemented.
+
+How should software development project management work be organized within an XDRS-enabled workspace so that agents and developers can find, create, and refine work items alongside the code?
+
+## Decision Outcome
+
+**Epics are XDRS plan documents. Features are Milestones inside those plans. User stories are key tasks linked to detail files.**
+
+### Details
+
+#### 01-epic-structure
+
+An epic is a group of features that together achieve a well-defined objective. Epics typically span 1–12 months.
+
+- Each epic MUST be represented as one XDRS plan document of type BDR, placed at:
+  `.xdrs/[scope]/bdrs/operations/plans/NNN-epic-slug.md`
+- The plan heading MUST follow the format: `# [scope]-bdr-plan-NNN: [Epic Title]`
+- NNN is the plan's unique number within the `[scope]/bdrs/operations/plans/` namespace, assigned sequentially per `_core-adr-policy-007`.
+- The slug MUST be lowercase, hyphen-separated, and descriptive (e.g., `001-epic-improve-checkout.md`).
+- Each epic plan MUST include all required sections from `_core-adr-policy-007`: Executive Summary, Context and Problem Statement, Proposed Solution (with Expected end date), and Milestones.
+- Epic plans are ephemeral and MUST be deleted after the epic is fully implemented, per `_core-adr-policy-007`.
+
+#### 02-feature-as-milestone
+
+A feature is a specific activity, tool, or functionality that contributes to the epic's objective. Features typically span 2 weeks to 6 months.
+
+- Each feature MUST be represented as one `### Milestone N: [Feature Name]` section inside the epic plan.
+- One Milestone per Feature; do not combine unrelated features into a single Milestone.
+- Milestone sections MUST follow the structure defined in `_core-adr-policy-007`:
+  - Owner, Due date, Description, optional Acceptance checklist, Key tasks, optional Risks.
+
+#### 03-user-story-as-key-task
+
+A user story is a unit of work within a Feature that delivers perceivable value to a specific audience. User stories MUST be completable in less than 2 weeks. Stories estimated to exceed 2 weeks MUST be split into smaller independent stories.
+
+- Each user story MUST appear as a key task entry inside its parent Milestone's `**Key tasks:**` list, always as a markdown link to its detail file.
+- **Pending (not yet refined):** `- [Brief description — pending]{.assets/userstory-NNN-slug.md}` — file has `**Status:** to-be-refined`
+- **Refined:** `- [Story title]{.assets/userstory-NNN-slug.md}` — no status field in the file
+- NNN is local to the epic plan's `.assets/` folder; it restarts at 001 for each epic.
+- Story slugs MUST be lowercase and hyphen-separated (e.g., `userstory-001-add-login-page`).
+
+#### 04-user-story-detail-file
+
+Each refined user story MUST have a detail file placed at:
+`.xdrs/[scope]/bdrs/operations/plans/.assets/userstory-NNN-slug.md`
+
+- NNN and slug MUST match the placeholder file that was refined (extracted from its `**Story ID:**` line). For new stories without a placeholder, use the next available NNN in `.assets/` and derive the slug by kebab-casing the story title to at most 7 words.
+- The file MUST begin with a `**Story ID:** userstory-NNN-slug` line. A refined file has no `**Status:**` field; the absence of the status field indicates the story is complete.
+
+A **pending placeholder file** is created for every story added to the plan before it is refined. It MUST contain:
+```markdown
+**Story ID:** userstory-NNN-slug
+**Status:** to-be-refined
+
+## Title
+[preliminary description]
+
+## Notes from intake
+[Any context captured when this story was created: split rationale, relationship to other stories,
+ known API details, contacts, or business rules discovered so far.]
+
+## Related
+- [Reason]: [userstory-NNN-other-story](.assets/userstory-NNN-other-story.md)
+```
+
+The detail file MUST follow this template:
+
+```markdown
+**Story ID:** userstory-NNN-slug
+
+## Title
+[max 10 words, outcome-focused]
+
+## User Story
+As a [role], I want to [action], so that [benefit].
+
+## Scope
+[max 200 words. List features, behaviors, screens, or services in scope.]
+- [feature or behavior]
+
+## Edge Cases
+[optional — max 50 words. Known edge cases and expected handling.]
+- [edge case — expected handling]
+
+## Out of Scope
+[optional — max 30 words.]
+- [out-of-scope item]
+
+## Constraints
+[optional — max 30 words. Any rule, technology, regulatory, or business constraint that must be respected.]
+- [constraint]
+
+## Detailed Specs
+[Required when any API, integration, or data detail was discovered. Mark N/A if none.
+ A story lacking sufficient detail here is not ready for implementation.]
+- [External API / integration: endpoint, method, payload, auth, behavior]
+- [Data field: type, format, valid values, meaning, constraints]
+- [Doc link: URL or file path — what it covers]
+- [Contact: name/role — what they own or can clarify]
+- [Process rule or business constraint not captured in Constraints above]
+
+## Acceptance Criteria
+- [ ] [verifiable outcome]
+
+## Attachments
+[highly desirable — screenshots, mockups, or diagrams illustrating the feature.]
+- [attachment]
+
+**Epic plan:** [NNN-epic-slug.md](../NNN-epic-slug.md)
+```
+
+#### 05-detailed-specs-requirement
+
+A user story that lacks enough detail to begin architecture, planning, or implementation is not ready for implementation and MUST be re-refined before it is moved to in-progress.
+
+- The `## Detailed Specs` section MUST be present in every user story detail file.
+- When integration or interface details were discovered during refinement (external APIs, data contracts, documentation links, contact names), the section MUST be populated with those details.
+- When no such details apply, the section MUST be explicitly marked `N/A`.
+- A story with an empty or absent `## Detailed Specs` section is treated as not refined.
+
+#### 06-refinement-workflow
+
+Stories MUST be refined using the `151-refine-user-story` skill. The skill:
+- Detects active epic plan documents and lists pending stories for selection.
+- MUST run a structured 10-phase refinement process including interface/integration spec discovery.
+- MUST write the resulting detail file and update the key task link in the plan's Milestone.
+- When a story is split, MUST create placeholder files for each deferred slice and add them as pending task links in the plan.
+
+#### 07-ephemeral-lifecycle
+
+Epic plans and their associated user story detail files are ephemeral artifacts. Once an epic is fully implemented:
+- The epic plan document MUST be deleted.
+- The `.assets/` folder and all user story detail files MUST be deleted with it.
+- The lasting outputs of an epic are the implemented code, decisions, skills, articles, and other artifacts produced during execution.
+
+#### 08-okr-connection
+
+Epics SHOULD be connected to one or more Tactical OKRs from `agentme-bdr-002` that represent the quarterly goals the epic is helping achieve.
+
+- The OKR reference MUST be placed in a `## OKRs` section immediately after the heading line of the epic plan document, listing each Tactical OKR by name or identifier.
+- An epic without a linked Tactical OKR MUST document the reason in the `## OKRs` section (e.g., "No Tactical OKR defined for this quarter — tracked as a conscious decision").
+- The relationship is many-to-many: one Tactical OKR MAY drive multiple Epics; one Epic MAY contribute to multiple Tactical OKRs.
+
+## References
+
+- [`_core-adr-policy-007`](../../../_core/adrs/principles/007-plan-standards.md) — Plan document standards: structure, lifecycle, and Milestone template
+- [`agentme-bdr-002`](../principles/002-okr-framework.md) — OKR framework: Tactical OKR definition and epic connection rule
+- [`agentme-edr-skill-151`](../../edrs/principles/skills/151-refine-user-story/SKILL.md) — Refine user story skill: structured refinement workflow that produces output following this policy

package/.xdrs/agentme/bdrs/operations/402-digital-product-roles.md

@@ -0,0 +1,149 @@
+---
+name: agentme-bdr-policy-402-digital-product-roles-org-cross-team
+description: Defines organisation-level and cross-team roles — Product Manager, Principal Engineer, and Solution Architect — along with team purpose, scope, workforce allocation, and a roles overview table. Use when staffing or assigning responsibilities at the organisation or cross-team level.
+apply-to: Organisation-level and cross-team roles in digital product organisations
+valid-from: 2026-08-30
+---
+
+# agentme-bdr-policy-402: Digital product roles — org & cross-team
+
+## Context and Problem Statement
+
+Digital product organisations involve roles at multiple levels — from strategy and product direction at the organisation level, through cross-team architectural and engineering standards, to daily execution inside product teams. Without a clear definition of each role's responsibilities, boundaries, and expected skills, ambiguity accumulates about who owns what, leading to gaps in coverage, duplicated effort, and unclear escalation paths.
+
+What roles are involved in building and operating digital products, and what does each role own?
+
+## Decision Outcome
+
+**A defined set of organisation-level, cross-team, team-level, and specialist roles with explicit responsibilities, authority boundaries, and skill requirements**
+
+### Details
+
+#### 01-product-team-purpose
+
+A product team is responsible for a product consumed by others: an API used by another team in the company, a business process used by customers, or a platform that other teams build on.
+
+Strategic objectives typically originate outside the team. However, the team MUST own a defined set of OKRs or KPIs and be fully autonomous within its domain to change processes and implement systems that affect those objectives. The team MUST be accountable for results within its domain; it MUST NOT depend on other teams to execute changes within scope.
+
+#### 02-product-team-scope-of-work
+
+The team MUST own the full lifecycle of its product:
+
+- Model as-is business processes and define to-be target processes
+- Design architecture and system components
+- Implement and deploy features across all environments
+- Test software components, runtime services, and business processes
+- Monitor production operation
+- Fix incidents and manage production stability
+- Communicate outages and new feature rollouts to users
+
+The team MUST NOT hand off any of these responsibilities to a separate function. Ownership is end-to-end.
+
+#### 03-workforce-allocation
+
+Teams MUST allocate available capacity across three categories. These are targets, not rigid weekly quotas — they SHOULD balance over a rolling 4–6 week window:
+
+| Category | Target | Scope |
+|---|---|---|
+| New features | 50% | Spiking, designing, implementing, and testing new capabilities |
+| Tech and cognitive debt | 25% | Reducing complexity, improving maintainability, resolving known deficiencies |
+| Operations and controls | 25% | Monitoring, incident response, compliance checks, access reviews, process audits |
+
+#### 04-roles-overview
+
+All roles MUST be filled by a person with the required hard skills. Organisation-level roles MUST operate at the Group, Company, or Business Unit level. Cross-team roles MUST operate across all product teams within a domain. Team-level roles MUST belong to a specific product team.
+
+| Role | Scope | Focus |
+|---|---|---|
+| Product Manager (PM) | Org-level | What / When |
+| Principal Engineer | Cross-team | How |
+| Solution Architect | Cross-team | What |
+| Product Owner (PO) | Team | What / When |
+| Project Manager (PjM) | Team | When / How |
+| Business Analyst (BA) | Team / Squad | What / How |
+| AI Business Analyst (AI BA) | Team / Squad | What / How |
+| AI Lead | Team / Squad | How / When |
+| AI Engineer | Squad | How |
+| Tech Lead | Team / Squad | How / When |
+| Backend Engineer | Squad | How |
+| Frontend Engineer | Squad | How |
+| DevOps/Infra Engineer | Squad | How |
+| Full Stack Engineer | Squad | How |
+
+#### 05-organisation-and-cross-team-roles
+
+The following roles operate at the organisation level (Group, Company, or Business Unit) or across all product teams within a domain. They MUST NOT belong to a single product team.
+
+---
+
+**Product Manager (PM)**
+
+*Purpose*: Own the product direction for the organisation — defining what to build and why — and translate strategic objectives into Tactical OKRs that product teams execute.
+
+*Responsibilities*:
+- Translate Strategic OKRs (set at Group, Company, or Business Unit level) into Tactical OKRs for quarterly execution
+- Prioritise Epics across product teams to maximise contribution to Tactical OKRs
+- Communicate Tactical OKRs and Epic priorities to Product Owners (POs) so teams can execute against them; the PO is the primary recipient of this direction and executes it within the team
+- Maintain visibility into the product portfolio and adjust priorities as market or business conditions change
+- Own the product roadmap and communicate it to stakeholders
+
+*Authority*: The PM owns WHAT the organisation builds at the portfolio level and WHEN Tactical OKRs are set. The PM does NOT own day-to-day team decisions — those remain with each team's Product Owner and Tech Lead. The PM does NOT set engineering practices or platform choices — those are owned by the Principal Engineer.
+
+*Soft skills*: Strategic thinking, product vision, stakeholder communication, prioritisation across competing goals, ability to synthesise market and business context into clear direction
+
+*Hard skills*: OKR methodology, product roadmap management, market and business analysis, Epic-level prioritisation across multiple product teams
+
+*Common activities*: OKR planning cycles, product roadmap reviews, Epic prioritisation sessions, Product Owner alignment meetings, stakeholder presentations, portfolio health reviews
+
+---
+
+**Principal Engineer**
+
+*Purpose*: Own the HOW across all product teams — engineering practices, tooling standards, platform choices, and AI practices — and synthesise them into a blueprint that leads can apply.
+
+*Responsibilities*:
+- Define and maintain engineering standards across all product teams (coding practices, testing, CI/CD, observability)
+- Select and standardise platforms and tooling used by teams
+- Shape AI engineering practices and the adoption of AI-assisted development
+- Connect architecture decisions, business requirements, and standardised platforms into a coherent engineering blueprint
+- Mentor Tech Leads and AI Leads on standards and practices
+- Connect with Product Manager (PM), Project Manager (PjM), Solution Architects, and team leads to translate, converge, and align the technological landscape, standards, and processes
+
+*Soft skills*: Technical leadership, communication across skill levels, systems thinking, mentoring, cross-team influence — a nexialist connecting engineering, management, architecture, platforms, and product
+
+*Hard skills*: Software architecture, platform engineering, AI/ML practices, CI/CD, observability, security engineering, developer experience
+
+*Common activities*: Engineering standards authoring, tech radar reviews, architecture and platform reviews, Tech Lead and AI Lead mentoring sessions, cross-team engineering syncs
+
+---
+
+**Solution Architect**
+
+*Purpose*: Define the architecture for solutions that require new cross-system standards, new platforms, integrations with external systems, or significant security and compliance concerns.
+
+*Responsibilities*:
+- Design architectural solutions for Epics or initiatives that span multiple systems or teams
+- Define new integration patterns, platform adoptions, and cross-system standards when existing standards do not cover the need
+- Produce architectural blueprints that Tech Leads and AI Leads can implement within their teams
+- Assess security, compliance, and risk dimensions of proposed architectures
+- Ensure architectural consistency across product teams within the domain
+
+*Soft skills*: Holistic thinking, stakeholder communication, structured documentation, facilitation, ability to balance pragmatism with rigour
+
+*Hard skills*: Enterprise architecture, system integration patterns, cloud architecture, security architecture, business process modelling, platform evaluation, domain-driven design
+
+*Common activities*: Architecture design for complex Epics, blueprint authoring, cross-system integration design, security and compliance assessment, architecture review participation, cross-team design alignment sessions
+
+#### 06-team-and-specialist-roles
+
+Team-level and specialist roles are defined in [`agentme-bdr-404`](404-team-roles-and-specialists.md). Practitioners MUST consult that policy when staffing or onboarding team-level roles.
+
+## References
+
+- [`_core-adr-policy-016`](../../../_core/adrs/principles/016-policy-subjects.md) — Policy subjects: BDR operations subject definition
+- [`_core-adr-policy-017`](../../../_core/adrs/principles/017-policy-numbering-ranges.md) — Policy numbering: BDR operations block 401–500
+- [`agentme-bdr-001`](../principles/001-company-organizational-levels.md) — Company organisational levels: Group, Company, and Business Unit definitions
+- [`agentme-bdr-002`](../principles/002-okr-framework.md) — OKR framework: Strategic, Tactical, and Operational OKR definitions
+- [`agentme-bdr-003`](../principles/003-product-delivery-value-flow.md) — Product delivery value flow: end-to-end chain from Strategic OKRs to fulfilled Tactical OKRs
+- [`agentme-bdr-403`](403-product-team-composition.md) — Team composition models, squad dynamics, and known structural gaps
+- [`agentme-bdr-404`](404-team-roles-and-specialists.md) — Team-level roles and specialists: PO, PjM, BA, AI BA, AI Lead, AI Engineer, Tech Lead, engineers, and specialists

package/.xdrs/agentme/bdrs/operations/403-product-team-composition.md

@@ -0,0 +1,102 @@
+---
+name: agentme-bdr-policy-403-product-team-composition
+description: Defines team composition models, squad structure, squad dynamics, and known structural gaps for Product Teams. Use when structuring or scaling a new or existing product team.
+apply-to: All product teams and cross-team roles in the organisation
+valid-from: 2026-08-18
+---
+
+# agentme-bdr-policy-403: Product team composition
+
+## Context and Problem Statement
+
+Product teams vary in scope and AI surface. Without a defined composition model, teams grow informally, leading to inconsistent structures, unclear coordination patterns, and unmanaged structural risks.
+
+How should a product team be structured, and what known risks must teams manage proactively?
+
+## Decision Outcome
+
+**Two composition models (simple and complex) with defined squad structure, squad dynamics, and documented structural gaps with required mitigations**
+
+### Details
+
+#### 01-composition-model-selection
+
+Teams MUST apply one of the two composition models defined in this policy — simple or complex — based on their product scope and AI surface. Teams MUST NOT operate with an undefined or informal structure.
+
+![Team composition diagram](.assets/team-composition.svg)
+
+#### 02-team-composition-simple
+
+A team with a bounded product scope and limited AI surface MUST operate as a simple team with no internal squads.
+
+| Role | Count | Notes |
+|---|---|---|
+| Product Owner | 1 | |
+| Business Analyst or AI BA | 1 | |
+| Tech Lead | 1 | |
+| Engineer | 1–2 | Any sub-type from `agentme-bdr-404` (Backend, Frontend, DevOps/Infra, Full Stack) |
+| AI Engineer (if AI work exists) | 0–1 | |
+
+The Tech Lead MAY also contribute as an engineer in a simple team. The BA MUST work directly with the PO on requirements without squad separation.
+
+#### 03-team-composition-complex
+
+A team with a broad product scope or significant AI surface MUST operate with internal squads.
+
+| Role | Count | Notes |
+|---|---|---|
+| Product Owner | 1 | Shared across all squads |
+| Tech Lead | 1 | Shared across all squads |
+| AI Lead | 1 | Shared across all squads |
+| Squad | 3 | See squad composition below |
+
+**Squad composition** (per squad):
+
+| Role | Count | Notes |
+|---|---|---|
+| Business Analyst (BA or AI BA) | 1 | Ideally one per squad; may move |
+| AI Engineer | 2 | |
+| Engineer | 2 | Any sub-type from `agentme-bdr-404` (Backend, Frontend, DevOps/Infra, Full Stack) |
+| Squad Lead | 1 | One of the engineers above, designated by soft skills |
+
+Squads MUST NOT exceed 4 engineers (AI + Full Stack combined) to preserve cohesion and limit coordination overhead.
+
+#### 04-squad-dynamics
+
+**Squad stability**: Engineers assigned to a squad MUST remain stable over time. Squad membership changes MUST be deliberate and infrequent; frequent reassignment prevents team bonding and reduces squad effectiveness.
+
+**BA and AI BA fluidity**: One BA or AI BA MUST be assigned to each squad, ideally working one sprint ahead on upcoming features. When squad needs shift — for example, when a squad moves from a non-AI phase to an AI-heavy phase — the BA and AI BA MAY exchange positions. Movement is self-organised between the BAs with PO awareness and is not restricted to sprint boundaries.
+
+**Squad Lead**: Each squad MUST have a designated Squad Lead — one of its engineers (AI Engineer or Engineer) selected based on available soft skills. The Squad Lead is a formal role with the following responsibilities:
+- Run squad ceremonies (standups, retrospectives)
+- Shield the squad from unplanned external interruptions
+- Make within-squad prioritisation calls when the PO or Tech Lead / AI Lead are unavailable
+
+The Squad Lead MUST be identified at squad formation, not selected on-demand when a situation arises. The role does not change the engineer's technical responsibilities and does not carry a formal seniority change, but soft skills MUST be taken into account at the time of assignment.
+
+**Cross-squad coordination**: Cross-squad dependencies within the same team MUST be the Project Manager (PjM)'s explicit responsibility. The PjM MUST proactively identify and resolve scheduling conflicts between squads.
+
+**Tech Lead and AI Lead interaction**: The PO, Tech Lead, and AI Lead MUST connect to all squads. For integrated features spanning AI and non-AI components, the Tech Lead and AI Lead MUST co-own the technical design. The Tech Lead holds the tiebreaker on system boundaries and non-AI components; the AI Lead holds the tiebreaker on AI components.
+
+#### 05-known-gaps-and-mitigations
+
+Teams MUST be aware of the following structural gaps and MUST apply the recommended mitigations proactively.
+
+| Gap | Risk | Mitigation |
+|---|---|---|
+| PO, Tech Lead, AI Lead spanning 3 squads | Bandwidth overload; leads become bottlenecks | Squad Lead MUST absorb daily unblocking and within-squad prioritisation; leads focus on design, mentoring, and cross-squad alignment |
+| Principal Engineer covering all teams | Single point of knowledge for engineering standards | Architecture documentation MUST be kept current; Principal Engineer MUST actively pair with Tech Leads and AI Leads to distribute knowledge |
+| No embedded UX/Design role | UI and interaction design absorbed informally by BA or PO | A UX Designer Specialist (see `agentme-bdr-404`) SHOULD be engaged for user-facing features with significant interaction design needs; otherwise bring in a contract designer |
+| No Data Engineering / MLOps role | Data pipelines, feature stores, and model serving infrastructure absorbed by Engineers and AI Engineers | Teams MUST plan a dedicated hire when the AI surface grows beyond squad capacity |
+| No embedded QA role | Test quality depends on individual engineer discipline with no gate owner | A Tester / QA Specialist (see `agentme-bdr-404`) SHOULD be engaged during high-complexity delivery phases; Tech Lead and AI Lead MUST own quality gates; acceptance criteria from BA and AI BA MUST include testable conditions |
+| No Security / SecOps role | Security design and review absorbed by Tech Lead on top of architecture load | Teams MUST schedule an external security review cadence; Principal Engineer MUST maintain security standards in the engineering blueprint |
+| BA squad fluidity | Knowledge transfer cost each time a BA moves | BAs MUST coordinate handoff timing to minimise disruption |
+| Squad Lead selection uncertainty | Squads without a clear lead default to ambiguity in ceremonies and prioritisation | Squad Lead MUST be identified at squad formation; MUST NOT be left to emerge organically after work has started |
+| Cross-squad dependency coordination | Without explicit ownership, cross-squad dependencies surface late and block delivery | Project Manager (PjM) MUST own cross-squad dependency tracking and resolution as part of their stakeholder-connecting mandate |
+
+## References
+
+- [`_core-adr-policy-016`](../../../_core/adrs/principles/016-policy-subjects.md) — Policy subjects: BDR operations subject definition
+- [`_core-adr-policy-017`](../../../_core/adrs/principles/017-policy-numbering-ranges.md) — Policy numbering: BDR operations block 401–500
+- [`agentme-bdr-402`](402-digital-product-roles.md) — Digital product roles (org & cross-team): PM, Principal Engineer, and Solution Architect definitions
+- [`agentme-bdr-404`](404-team-roles-and-specialists.md) — Digital product roles (team & specialists): role definitions for all team-level roles and specialists referenced in this policy