@documentation-robotics/cli 0.2.0 → 0.3.0

package/dist/integrations/github_copilot/skills/dr_03_product_layer/SKILL.md

@@ -6,6 +6,7 @@ triggers:
     "product",
     "feature",
     "persona",
+    "software capability",
     "capability",
     "milestone",
     "user workflow",
@@ -20,7 +21,7 @@ version: 0.8.4
 
 **Layer Number:** 03
 **Specification:** Metadata Model Spec v0.8.4
-**Purpose:** Defines product personas, capabilities, features, user workflows, and milestones that represent what the product does and for whom.
+**Purpose:** Defines product personas, software capabilities, features, user workflows, and milestones that represent what the product does and for whom.
 
 ---
 
@@ -29,7 +30,7 @@ version: 0.8.4
 The Product Layer captures the **product management dimension** of architecture:
 
 - **WHO** - Personas and target user archetypes
-- **WHAT** - Capabilities and features the product delivers
+- **WHAT** - Software capabilities and features the product delivers
 - **HOW** - User workflows describing how users accomplish goals
 - **WHEN** - Milestones representing delivery roadmap
 - **WHY** - Linkage to business goals and requirements
@@ -45,13 +46,14 @@ This layer uses a **custom specification** designed for product planning, priori
 > **CLI Introspection:** Run `dr schema types product` for the authoritative, always-current list of node types.
 > Run `dr schema node <type-id>` for full attribute details on any type.
 
-| Entity Type      | Description                                                | Key Attributes                                                                                        |
-| ---------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| **Persona**      | User archetype with shared goals, behaviors, pain points   | category (primary, secondary, served, negative), proficiency (novice, intermediate, advanced, expert) |
-| **Capability**   | Product ability independent of implementation              | status (proposed, planned, developing, delivered, deprecated), properties                             |
-| **Feature**      | User-visible unit of functionality delivering capabilities | priority (critical, high, medium, low, informational), status, size (xs, s, m, l, xl)                 |
-| **UserWorkflow** | Sequence of user-facing steps to accomplish a goal         | complexity (simple, moderate, complex), properties                                                    |
-| **Milestone**    | Time-bound delivery target grouping features/capabilities  | status (proposed, planned, active, completed, cancelled)                                              |
+| Entity Type            | Description                                                                                 | Key Attributes                                                                                        |
+| ---------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| **Persona**            | User archetype with shared goals, behaviors, pain points                                    | category (primary, secondary, served, negative), proficiency (novice, intermediate, advanced, expert) |
+| **SoftwareCapability** | Ability of the software platform, independent of implementation (not a business capability) | status (proposed, planned, developing, delivered, deprecated), properties                             |
+| **Feature**            | User-visible unit of functionality delivering software capabilities                         | priority (critical, high, medium, low, informational), status, size (xs, s, m, l, xl)                 |
+| **UserWorkflow**       | Sequence of user-facing steps to accomplish a goal                                          | complexity (simple, moderate, complex), properties                                                    |
+| **WorkflowStep**       | One ordered, user-facing step within a UserWorkflow                                         | sequence, action, outcome, optional, properties                                                       |
+| **Milestone**          | Time-bound delivery target grouping features and software capabilities                      | status (proposed, planned, active, completed, cancelled)                                              |
 
 ---
 
@@ -59,54 +61,56 @@ This layer uses a **custom specification** designed for product planning, priori
 
 The Product layer models product structure and planning via these core relationships:
 
-| Source                 | Predicate       | Destination          | Cardinality  | Rationale                                      |
-| ---------------------- | --------------- | -------------------- | ------------ | ---------------------------------------------- |
-| `product.capability`   | `aggregates`    | `product.capability` | many-to-many | Capability decomposition into sub-capabilities |
-| `product.feature`      | `realizes`      | `product.capability` | many-to-many | Feature delivers a capability                  |
-| `product.feature`      | `serves`        | `product.persona`    | many-to-many | Feature targets a persona                      |
-| `product.feature`      | `scheduled-for` | `product.milestone`  | many-to-many | Feature assigned to delivery milestone         |
-| `product.capability`   | `scheduled-for` | `product.milestone`  | many-to-many | Capability assigned to milestone               |
-| `product.userworkflow` | `serves`        | `product.persona`    | many-to-many | Workflow designed for a persona                |
-| `product.userworkflow` | `composes`      | `product.feature`    | many-to-many | Workflow composed of features                  |
-| `product.milestone`    | `precedes`      | `product.milestone`  | many-to-many | Milestone sequencing                           |
-| `product.feature`      | `depends-on`    | `product.feature`    | many-to-many | Feature dependency                             |
+| Source Type        | Predicate     | Target Type        | Example                                                         |
+| ------------------ | ------------- | ------------------ | --------------------------------------------------------------- |
+| SoftwareCapability | aggregates    | SoftwareCapability | "Authentication" aggregates "Multi-Factor Auth"                 |
+| SoftwareCapability | depends-on    | SoftwareCapability | "Order Tracking" depends on "Send Email"                        |
+| SoftwareCapability | scheduled-for | Milestone          | "Customer Segmentation" scheduled for "Q3 2024 Release"         |
+| Feature            | realizes      | SoftwareCapability | "Two-Factor Login" realizes "Authentication"                    |
+| Feature            | serves        | Persona            | "CSV Export" serves "Data Analyst"                              |
+| Feature            | scheduled-for | Milestone          | "Live Cursor Tracking" scheduled for "Q4 Collaboration Release" |
+| Feature            | depends-on    | Feature            | "Scheduled Reports" depends on "Custom Dashboards"              |
+| Milestone          | precedes      | Milestone          | "Q3 Security Release" precedes "Q4 Collaboration Release"       |
+| UserWorkflow       | composes      | WorkflowStep       | "Password Reset" composes "Request Reset Link"                  |
+| UserWorkflow       | serves        | Persona            | "Checkout" serves "Busy Parent"                                 |
+| WorkflowStep       | flows-to      | WorkflowStep       | "Request Reset Link" flows to "Receive Reset Email"             |
+| WorkflowStep       | uses          | Feature            | "Choose New Password" uses "Password Reset"                     |
 
 ---
 
 ## Cross-Layer References
 
-### Outgoing References (Product → Motivation)
-
-Product layer references Motivation layer to justify product decisions with strategic goals:
-
-| Predicate        | Source       | Target      | Rationale                                    |
-| ---------------- | ------------ | ----------- | -------------------------------------------- |
-| `realizes`       | Persona      | Stakeholder | Persona concretizes stakeholder archetypes   |
-| `satisfies`      | Feature      | Requirement | Feature satisfies business/user requirements |
-| `supports`       | Capability   | Goal        | Capability supports strategic goals          |
-| `delivers`       | UserWorkflow | Outcome     | Workflow delivers business outcomes          |
-| `delivers-value` | Feature      | Value       | Feature delivers business value              |
-| `fulfills`       | Capability   | Requirement | Capability fulfills requirements             |
-
-### Outgoing References (Product → Business)
-
-Product layer references Business layer to align with organizational services and roles:
-
-| Predicate    | Source       | Target           | Rationale                               |
-| ------------ | ------------ | ---------------- | --------------------------------------- |
-| `realizes`   | Feature      | BusinessService  | Feature realizes a business service     |
-| `aggregates` | UserWorkflow | BusinessProcess  | Workflow aggregates business processes  |
-| `realizes`   | Capability   | BusinessFunction | Capability realizes a business function |
-| `serves`     | Persona      | BusinessRole     | Persona is served by a business role    |
-
-### Incoming References (Lower Layers → Product)
-
-Higher layers (Security through Testing) reference Product layer for feature-level concerns:
-
-- Application → Feature: Application components implement features
-- UX → Feature: UI views render features
-- Testing → Feature: Test cases validate features
-- API → Feature: API operations expose features
+### Outgoing References (Product → Other Layers)
+
+Product elements point to Motivation to justify product decisions, and to Business to align with organizational services and roles:
+
+| Source Type        | Predicate  | Target Type                 | Example                                              |
+| ------------------ | ---------- | --------------------------- | ---------------------------------------------------- |
+| Persona            | references | `motivation.stakeholder`    | "Busy Parent" realizes "Retail Customers"            |
+| Feature            | satisfies  | `motivation.requirement`    | "Two-Factor Login" satisfies "User Account Security" |
+| Feature            | delivers   | `motivation.value`          | "One-Click Reorder" delivers "Customer Convenience"  |
+| SoftwareCapability | supports   | `motivation.goal`           | "Authentication" supports "Customer Trust"           |
+| SoftwareCapability | satisfies  | `motivation.requirement`    | "Data Export" satisfies "Data Portability"           |
+| UserWorkflow       | delivers   | `motivation.outcome`        | "Checkout" delivers "Cart Abandonment Reduced 15%"   |
+| SoftwareCapability | realizes   | `business.businessfunction` | "Subscription Billing" realizes "Billing"            |
+| UserWorkflow       | realizes   | `business.businessprocess`  | "Checkout" aggregates "Order Fulfillment"            |
+| Persona            | references | `business.businessrole`     | "Power User" serves "Data Analyst" role              |
+
+### Incoming References (Other Layers → Product)
+
+Other layers reference Product elements to record what implements, exposes or verifies them:
+
+| Source Type                      | Predicate | Target Type        | Example                                                   |
+| -------------------------------- | --------- | ------------------ | --------------------------------------------------------- |
+| `application.applicationservice` | realizes  | SoftwareCapability | "EmailService" realizes "Send Email"                      |
+| `technology.technologyservice`   | realizes  | SoftwareCapability | "SMTP Relay" realizes "Send Email"                        |
+| `application.applicationservice` | realizes  | Feature            | "ExportService" realizes "CSV Export"                     |
+| `api.operation`                  | exposes   | Feature            | "GET /reports/{id}/csv" exposes "CSV Export"              |
+| `ux.view`                        | realizes  | Feature            | "Cart Page" realizes "Shopping Cart"                      |
+| `navigation.navigationflow`      | realizes  | UserWorkflow       | "password-reset" flow realizes "Password Reset"           |
+| `navigation.flowstep`            | realizes  | WorkflowStep       | "/reset/new-password" step realizes "Choose New Password" |
+| `testing.testcasesketch`         | tests     | Feature            | "MFA login happy path" tests "Two-Factor Login"           |
+| `testing.testcoveragetarget`     | covers    | Feature            | "Export coverage target" covers "CSV Export"              |
 
 ---
 
@@ -133,16 +137,36 @@ A Persona is a **user archetype** representing a class of users with shared goal
 - **Advanced** - Power users with domain expertise
 - **Expert** - Specialists who push product limits
 
+**Example:**
+
+```
+Persona: "Sales Representative"
+├── category: primary
+├── proficiency: intermediate
+├── realizes → Stakeholder: "Sales Team"
+├── serves → BusinessRole: "Sales Representative"
+└── pain-points:
+    - Time-consuming manual data entry
+    - Limited visibility into customer interactions
+```
+
 ---
 
-## Capability Definition
+## SoftwareCapability Definition
+
+A SoftwareCapability is an **ability of the software platform**, stated as what the software can do (for example "Save documents to files" or "Full-text search"), independent of the features that expose it and the services that implement it. Features realize software capabilities, and a software capability realizes the business function it carries out: "Save documents to files" realizes the business function "Share data".
+
+**Distinction from BusinessCapability (Business layer):**
+
+- **BusinessCapability** - an ability the _organization_ has ("Share data with partners"), which would remain if different software, or none, provided it. Business functions and processes realize it. It is ArchiMate's Capability.
+- **SoftwareCapability** - an ability of the _software platform_ ("Save documents to files"). It reaches the business layer by realizing business functions, which in turn realize business capabilities.
 
-A Capability is an **ability the product possesses**, independent of how it's implemented.
+If removing the software would remove the ability, it is a software capability; if the organization would still need the ability and find another way to provide it, it is a business capability.
 
 **Distinction from BusinessFunction (Business layer):**
 
-- **BusinessFunction** - Internal organizational grouping of behavior
-- **Capability** - Externally-facing product ability
+- **BusinessFunction** - a standing area of organizational work, performed by roles
+- **SoftwareCapability** - what the software can do that carries such work out
 
 **Lifecycle Statuses:**
 
@@ -152,11 +176,25 @@ A Capability is an **ability the product possesses**, independent of how it's im
 - **Delivered** - Implemented and released
 - **Deprecated** - No longer supported
 
+**Decomposition:**
+Software capabilities decompose into narrower software capabilities via `aggregates` relationships.
+
+**Example:**
+
+```
+SoftwareCapability: "Customer Data Management"
+├── status: developing
+├── aggregates → SoftwareCapability: "Customer CRUD"
+├── aggregates → SoftwareCapability: "Customer Segmentation"
+├── realizes → BusinessFunction: "Customer Lifecycle Management"
+└── supports → Goal: "Improve Customer Retention"
+```
+
 ---
 
 ## Feature Definition
 
-A Feature is a **user-visible unit of functionality** that delivers one or more capabilities and is the primary unit of product planning.
+A Feature is a **user-visible unit of functionality** that delivers one or more software capabilities and is the primary unit of product planning.
 
 **Distinction from Requirement (Motivation layer):**
 
@@ -165,7 +203,7 @@ A Feature is a **user-visible unit of functionality** that delivers one or more
 
 **Priority Levels:**
 
-- **Critical** - Product cannot function without it
+- **Critical** - Product cannot function without it (v1 release blocker)
 - **High** - Core functionality users expect
 - **Medium** - Valuable enhancement
 - **Low** - Nice-to-have optimization
@@ -179,23 +217,84 @@ A Feature is a **user-visible unit of functionality** that delivers one or more
 - **L** - 2–4 weeks
 - **XL** - > 4 weeks
 
+**Example:**
+
+```
+Feature: "Two-Factor Authentication"
+├── priority: high
+├── status: developing
+├── size: m
+├── realizes → SoftwareCapability: "Account Security"
+├── serves → Persona: "Security-Conscious User"
+├── satisfies → Requirement: "Support TOTP and SMS 2FA"
+└── scheduled-for → Milestone: "Q3 Security Release"
+```
+
 ---
 
 ## User Workflow Definition
 
 A UserWorkflow is a **sequence of user-facing steps** through the product to accomplish a goal.
 
+**Distinction from BusinessProcess (Business layer) and ExperienceState (UX layer):**
+
+- **BusinessProcess** - Organization-internal process (BPMN, ArchiMate)
+- **UserWorkflow** - User-centric journey through product features
+- **ExperienceState** - UI/interface-level state transitions
+
 **Complexity Assessment:**
 
 - **Simple** - Linear flow, 2–3 steps, minimal decision points
 - **Moderate** - Multiple branches, 5–10 steps, some conditional logic
 - **Complex** - Many decision points, 10+ steps, cross-system integration
 
+**Example:**
+
+```
+UserWorkflow: "Checkout Flow"
+├── complexity: moderate
+├── serves → Persona: "Online Shopper"
+├── composes → Feature: "Shopping Cart"
+├── composes → Feature: "Payment Processing"
+├── composes → Feature: "Order Confirmation"
+├── delivers → Outcome: "Completed Purchase"
+└── aggregates → BusinessProcess: "Order Fulfillment"
+
+Steps:
+1. Add item to cart (Feature: Shopping Cart)
+2. Review cart and shipping (Feature: Checkout)
+3. Enter payment details (Feature: Payment Processing)
+4. Confirm order (Feature: Order Confirmation)
+5. Receive confirmation email
+```
+
+---
+
+**Steps as elements (WorkflowStep):**
+
+Model the steps as `product.workflowstep` elements when you need to trace which features each step
+relies on, or to link steps to navigation routes. A workflow reaches features, and through them software
+capabilities, only through its steps: the workflow composes steps, each step `uses` the features it
+exercises, and those features realize software capabilities. Example: the _Password reset_ workflow
+composes steps, and the platform's _Send email_ capability is reached through the feature that uses it:
+
+```
+UserWorkflow: "Password Reset"
+├── composes → WorkflowStep 1 "Request reset link"   (uses → Feature: Password Reset)
+├── composes → WorkflowStep 2 "Receive reset email"  (uses → Feature: Reset Email)
+├── composes → WorkflowStep 3 "Choose new password"  (uses → Feature: Password Reset)
+└── realizes ← NavigationFlow: "password-reset"       (its FlowSteps realize the WorkflowSteps)
+
+Feature: "Reset Email"     → realizes SoftwareCapability: "Send Email"
+SoftwareCapability: "Send Email"  ← realizes application.applicationservice "EmailService"
+                                  ← realizes technology.technologyservice "SMTP relay"
+```
+
 ---
 
 ## Milestone Definition
 
-A Milestone is a **time-bound delivery target** grouping features or capabilities.
+A Milestone is a **time-bound delivery target** grouping features or software capabilities.
 
 **Lifecycle Statuses:**
 
@@ -205,17 +304,379 @@ A Milestone is a **time-bound delivery target** grouping features or capabilitie
 - **Completed** - Released to users
 - **Cancelled** - Postponed or deprioritized
 
+**Milestone Sequencing:**
+Milestones can precede/follow other milestones for roadmap planning.
+
+**Example:**
+
+```
+Milestone: "Q3 2024 Release"
+├── status: active
+├── scheduled-features:
+│   ├── Feature: "Two-Factor Authentication"
+│   ├── Feature: "Audit Logging"
+│   └── Feature: "API Rate Limiting"
+├── scheduled-software-capabilities:
+│   ├── SoftwareCapability: "Account Security"
+│   └── SoftwareCapability: "System Reliability"
+├── precedes → Milestone: "Q4 2024 Release"
+└── includes → Outcome: "Improved User Trust"
+```
+
+---
+
+## Codebase Detection Patterns
+
+### Pattern 1: Feature Flags
+
+```python
+# Feature flag indicating incomplete feature
+if feature_flags.get("two_factor_auth_enabled"):
+    user.enable_2fa()
+
+# Feature flag with rollout percentage
+if feature_flags.is_enabled("new_checkout", rollout_percentage=10):
+    return new_checkout_flow()
+```
+
+**Maps to:**
+
+- Feature: "Two-Factor Authentication" (status: developing)
+- Feature: "New Checkout Flow" (status: developing, rollout: 10%)
+
+### Pattern 2: Product Roadmap Comment
+
+```python
+# TODO: Implement user segmentation for Q3 milestone
+# Feature: "User Segmentation" (priority: high)
+# SoftwareCapability: "Customer Segmentation"
+# Milestone: "Q3 2024 Release"
+def segment_users_by_behavior():
+    pass
+```
+
+**Maps to:**
+
+- Feature: "User Segmentation" (priority: high)
+- SoftwareCapability: "Customer Segmentation"
+- Milestone: "Q3 2024 Release"
+
+### Pattern 3: User Role / Persona References
+
+```typescript
+// Different workflows for different user personas
+const workflowByPersona = {
+  basicUser: {
+    steps: ["login", "browse", "add-to-cart", "checkout"],
+    complexity: "simple"
+  },
+  powerUser: {
+    steps: [
+      "login",
+      "advanced-search",
+      "bulk-compare",
+      "batch-order",
+      "checkout"
+    ],
+    complexity: "complex"
+  },
+  admin: {
+    steps: ["login", "access-dashboard", "manage-users", "view-analytics"],
+    complexity: "complex"
+  }
+};
+```
+
+**Maps to:**
+
+- Persona: "Basic User" (proficiency: novice)
+- Persona: "Power User" (proficiency: advanced)
+- Persona: "Admin" (proficiency: expert)
+- UserWorkflow: "Basic Checkout Flow" (complexity: simple) → serves → Persona: "Basic User"
+- UserWorkflow: "Power User Ordering" (complexity: complex) → serves → Persona: "Power User"
+
+### Pattern 4: Software Capability Requirements
+
+```yaml
+# Software capability definition
+capabilities:
+  authentication:
+    - password-based
+    - oauth2
+    - saml
+    - multi-factor-auth
+  reporting:
+    - real-time-dashboards
+    - scheduled-reports
+    - custom-queries
+    - data-export
+```
+
+**Maps to:**
+
+- SoftwareCapability: "Authentication" → aggregates → [Password-Based Auth, OAuth2, SAML, Multi-Factor Auth]
+- SoftwareCapability: "Reporting" → aggregates → [Real-Time Dashboards, Scheduled Reports, Custom Queries, Data Export]
+
+### Pattern 5: Persona Attributes in Code
+
+```python
+class UserProfile:
+    """User archetype modeling"""
+    def __init__(self, persona_type: str, proficiency: str):
+        self.persona_type = persona_type  # e.g., "power-user", "casual-user"
+        self.proficiency = proficiency    # e.g., "advanced", "novice"
+        self.pain_points = []
+        self.goals = []
+
+    def can_access_feature(self, feature: str) -> bool:
+        # Persona determines accessible features
+        if self.persona_type == "power-user":
+            return True
+        return feature in self.accessible_features
+```
+
+**Maps to:**
+
+- Persona: "Power User" (proficiency: advanced) → serves → Feature collection
+- Persona: "Casual User" (proficiency: novice) → serves → Limited feature set
+
+---
+
+## Modeling Workflow
+
+### Step 1: Define Target Personas
+
+```bash
+# Identify primary personas
+dr add product persona "power-user" \
+  --description "Expert user who uses all advanced features" \
+  --attributes '{"category":"primary","proficiency":"advanced"}'
+
+dr add product persona "casual-user" \
+  --description "Occasional user focused on core features" \
+  --attributes '{"category":"primary","proficiency":"novice"}'
+
+dr add product persona "admin" \
+  --description "System administrator managing users and settings" \
+  --attributes '{"category":"primary","proficiency":"expert"}'
+```
+
+### Step 2: Define Software Capabilities
+
+```bash
+# Product-level abilities (outcome-focused)
+dr add product softwarecapability "user-authentication" \
+  --description "Authenticate and authorize users" \
+  --attributes '{"status":"planned"}'
+
+dr add product softwarecapability "data-export" \
+  --description "Export user data in multiple formats" \
+  --attributes '{"status":"proposed"}'
+
+dr add product softwarecapability "real-time-collaboration" \
+  --description "Enable multiple users to collaborate simultaneously" \
+  --attributes '{"status":"developing"}'
+```
+
+### Step 3: Define Features
+
+```bash
+# User-visible features (deliverable units)
+dr add product feature "multi-factor-authentication" \
+  --description "Two-factor auth via TOTP or SMS" \
+  --attributes '{"priority":"high","size":"m","status":"developing"}'
+
+dr add product feature "csv-export" \
+  --description "Export data to CSV format" \
+  --attributes '{"priority":"medium","size":"s","status":"planned"}'
+
+dr add product feature "live-cursor-tracking" \
+  --description "See other users' cursor positions in real-time" \
+  --attributes '{"priority":"high","size":"l","status":"proposed"}'
+```
+
+### Step 4: Map Features to Software Capabilities
+
+```bash
+# Features realize software capabilities
+dr relationship add product.feature.multi-factor-authentication \
+  product.softwarecapability.user-authentication --predicate realizes
+
+dr relationship add product.feature.csv-export \
+  product.softwarecapability.data-export --predicate realizes
+
+dr relationship add product.feature.live-cursor-tracking \
+  product.softwarecapability.real-time-collaboration --predicate realizes
+```
+
+### Step 5: Map Features to Personas
+
+```bash
+# Features serve personas
+dr relationship add product.feature.multi-factor-authentication \
+  product.persona.security-conscious-user --predicate serves
+
+dr relationship add product.feature.live-cursor-tracking \
+  product.persona.power-user --predicate serves
+
+dr relationship add product.feature.csv-export \
+  product.persona.data-analyst --predicate serves
+```
+
+### Step 6: Define User Workflows
+
+```bash
+# User journeys through product
+dr add product user-workflow "basic-authentication-flow" \
+  --description "Standard login and session management" \
+  --attributes '{"complexity":"simple"}'
+
+dr add product user-workflow "secure-authentication-flow" \
+  --description "Multi-factor authentication workflow" \
+  --attributes '{"complexity":"moderate"}'
+
+dr add product user-workflow "collaboration-session" \
+  --description "Join and participate in real-time collaboration" \
+  --attributes '{"complexity":"complex"}'
+```
+
+### Step 7: Map Workflows to Features Through Steps
+
+```bash
+# A workflow composes its steps; each step uses the features it exercises
+dr add product workflowstep "enter-verification-code" \
+  --description "The user enters the code sent to their phone"
+
+dr relationship add product.userworkflow.secure-authentication-flow \
+  product.workflowstep.enter-verification-code --predicate composes
+
+dr relationship add product.workflowstep.enter-verification-code \
+  product.feature.multi-factor-authentication --predicate uses
+```
+
+### Step 8: Define Milestones
+
+```bash
+# Delivery roadmap
+dr add product milestone "q3-security-release" \
+  --description "Security-focused quarterly release" \
+  --attributes '{"status":"planned"}'
+
+dr add product milestone "q4-collaboration-release" \
+  --description "Real-time collaboration release" \
+  --attributes '{"status":"proposed"}'
+```
+
+### Step 9: Schedule Features to Milestones
+
+```bash
+# Assign features to delivery targets
+dr relationship add product.feature.multi-factor-authentication \
+  product.milestone.q3-security-release --predicate scheduled-for
+
+dr relationship add product.feature.live-cursor-tracking \
+  product.milestone.q4-collaboration-release --predicate scheduled-for
+```
+
+### Step 10: Cross-Layer Integration
+
+```bash
+# Link to Motivation layer
+dr relationship add product.feature.multi-factor-authentication \
+  motivation.requirement.user-account-security --predicate satisfies
+
+dr relationship add product.softwarecapability.user-authentication \
+  motivation.goal.customer-trust --predicate supports
+
+# Link to Business layer: software capabilities realize the business functions they carry out
+dr relationship add product.softwarecapability.data-export \
+  business.businessfunction.data-sharing --predicate realizes
+
+# A persona references the business role it stands for
+dr relationship add product.persona.power-user \
+  business.businessrole.data-analyst --predicate references
+```
+
+---
+
+## Modeling Patterns
+
+### Pattern 1: Feature Hierarchy
+
+```
+SoftwareCapability: "Order Management"
+├── aggregates → SoftwareCapability: "Order Placement"
+│   └── realizes ← Feature: "Shopping Cart"
+├── aggregates → SoftwareCapability: "Order Tracking"
+│   └── realizes ← Feature: "Order History"
+└── aggregates → SoftwareCapability: "Order Fulfillment"
+    └── realizes ← Feature: "Shipment Tracking"
+```
+
+### Pattern 2: Persona-Driven Features
+
+```
+Persona: "Enterprise Administrator"
+├── proficiency: expert
+├── serves ← Feature: "Bulk User Import"
+├── serves ← Feature: "Advanced Reporting"
+├── serves ← Feature: "API Key Management"
+└── serves → BusinessRole: "IT Operations"
+```
+
+### Pattern 3: Milestone Roadmap
+
+```
+Milestone: "Q1 2025 MVP"
+├── scheduled-for ← Feature: "User Authentication"
+├── scheduled-for ← Feature: "Basic Search"
+├── scheduled-for ← Feature: "Profile Management"
+└── precedes → Milestone: "Q2 2025 Enhancement"
+    ├── scheduled-for ← Feature: "Advanced Search"
+    └── scheduled-for ← Feature: "Real-Time Notifications"
+```
+
+### Pattern 4: Workflow with Multiple Features
+
+```
+UserWorkflow: "Power User Data Analysis"
+├── complexity: complex
+├── serves → Persona: "Data Analyst"
+├── composes → Feature: "Advanced Search"
+├── composes → Feature: "Custom Dashboards"
+├── composes → Feature: "CSV Export"
+├── composes → Feature: "Scheduled Reports"
+└── aggregates → BusinessProcess: "Business Intelligence"
+```
+
 ---
 
 ## Best Practices
 
 1. **Start with Personas, End with Workflows** - Understand users first, model journeys last
-2. **Features Deliver Capabilities** - Every feature should map to at least one capability
-3. **Capabilities Support Goals** - Link capabilities to motivation layer goals for justification
+2. **Features Realize Software Capabilities** - Every feature should realize at least one software capability
+3. **Software Capabilities Support Goals** - Link software capabilities to motivation layer goals for justification
 4. **Milestones Sequence Logically** - Plan dependencies and prerequisites
-5. **Workflows are User-Centric** - Name them from the user's perspective
-6. **Prioritization Reflects Business Value** - Higher priority features deliver more strategic value
-7. **Link to Business Layer** - Map features to business services to show value realization
+5. **Workflows are User-Centric** - Name them from the user's perspective, not system perspective
+6. **Complexity Reflects User Experience** - Complex workflows should have features to manage that complexity
+7. **Prioritization Reflects Business Value** - Higher priority features deliver more strategic value
+8. **Personas Evolve** - As product matures, update persona proficiency and categories
+9. **Features Have Clear Status** - Track development progress from proposed to delivered
+10. **Link to Business Layer** - Map features to business services to show value realization
+
+---
+
+## Validation Tips
+
+| Issue               | Cause                                         | Fix                                   |
+| ------------------- | --------------------------------------------- | ------------------------------------- |
+| Orphaned Feature    | Feature doesn't realize a software capability | Add one or remove feature             |
+| Unused Persona      | Persona serves no features                    | Add features for persona or remove    |
+| Unmapped Capability | SoftwareCapability doesn't support a goal     | Link to Motivation goal or remove     |
+| Incomplete Workflow | Workflow has no features                      | Add feature composition or simplify   |
+| Future Milestone    | Milestone has no scheduled features           | Add features or mark as candidate     |
+| Vague Persona       | Persona lacks proficiency or category         | Define proficiency level and category |
+| Unlinked Feature    | Feature doesn't satisfy a requirement         | Add requirement link or remove        |
 
 ---
 
@@ -224,30 +685,30 @@ A Milestone is a **time-bound delivery target** grouping features or capabilitie
 **Add Commands:**
 
 ```bash
-dr add product persona <name>
-dr add product capability <name>
-dr add product feature <name>
-dr add product user-workflow <name>
-dr add product milestone <name>
+dr add product persona <name> --description <desc> --attributes '{"category":"<category>","proficiency":"<proficiency>"}'
+dr add product softwarecapability <name> --description <desc> --attributes '{"status":"<status>"}'
+dr add product feature <name> --description <desc> --attributes '{"priority":"<priority>","status":"<status>","size":"<size>"}'
+dr add product user-workflow <name> --description <desc> --attributes '{"complexity":"<complexity>"}'
+dr add product milestone <name> --description <desc> --attributes '{"status":"<status>"}'
 ```
 
 **Relationship Commands:**
 
 ```bash
-dr relationship add <source> <destination> --predicate <predicate>
-```
-
-**Available Predicates:**
-
-- `aggregates` - Capability decomposes into sub-capability
-- `realizes` - Feature/Capability realizes capability/service/function
-- `serves` - Feature/Workflow/Persona serves persona/role
-- `scheduled-for` - Feature/Capability scheduled for milestone
-- `composes` - Workflow composed of features
-- `depends-on` - Feature depends on feature
-- `precedes` - Milestone precedes milestone
-- `satisfies` - Feature satisfies requirement
-- `supports` - Capability supports goal
-- `delivers` - Workflow delivers outcome
-- `delivers-value` - Feature delivers value
-- `fulfills` - Capability fulfills requirement
+dr relationship add <software-capability> <software-capability> --predicate aggregates
+dr relationship add <feature> <software-capability> --predicate realizes
+dr relationship add <feature> <persona> --predicate serves
+dr relationship add <workflow> <feature> --predicate composes
+dr relationship add <feature> <milestone> --predicate scheduled-for
+dr relationship add <milestone> <milestone> --predicate precedes
+```
+
+**Cross-Layer Commands:**
+
+```bash
+dr relationship add <persona> <stakeholder> --predicate realizes
+dr relationship add <feature> <requirement> --predicate satisfies
+dr relationship add <software-capability> <goal> --predicate supports
+dr relationship add <workflow> <outcome> --predicate delivers
+dr relationship add <feature> <business-service> --predicate realizes
+```