Custom relations

docs/.vitepress/config.ts

@@ -473,6 +473,7 @@ export default defineConfig({
             link: "/core-concepts/issues/time-tracking",
           },
           { text: "Workflows and Approvals", link: "/workflows-and-approvals/workflows" },
+          { text: "Custom Relations", link: "/advanced-management/custom-relations" },
           {
             text: "Automations",
             link: "/automations/custom-automations",

docs/advanced-management/custom-relations.md

@@ -0,0 +1,54 @@
+---
+title: Define relation types for work items
+description: Define custom relation types at the workspace level to represent how work items connect across your projects.
+---
+
+# Custom relations <Badge type="warning" text="Enterprise Grid" />
+
+Relations describe how work items are connected to each other.
+
+Plane includes three [default relation types](/core-concepts/issues/overview#add-relations) that cover common use cases. You can create additional relation types tailored to how your organization thinks about work. For example, a team might define a "Tests" relation so QA work items link back to the features they validate, or a "Depends On" relation to model logical dependencies that don't map to scheduling constraints.
+
+Custom relations are workspace-level configurations. Once created, they're available when linking work items across any project in the workspace.
+
+## Create a custom relation
+
+> **Role**: Workspace Admin
+
+1. Go to **Workspace Settings > Relations**.
+2. Click **Add relation**.
+3. Fill in the three fields:
+   - **Title** — the name of the relation type.
+   - **Inward name** — how the relation reads from the perspective of the work item you're adding it to (e.g., "blocking," "depended on by," "tested by").
+   - **Outward name** — how the relation reads from the perspective of the work item you're linking to (e.g., "blocked by," "depends on," "tests").
+4. Click **Save**.
+
+![Create custom relation](https://media.docs.plane.so/workspaces/custom-relations.webp#hero)
+
+The directional naming ensures the relation reads correctly from either side. The inward name appears on the work item you're adding the relation to, and the outward name appears on the work item you're linking.
+
+### Examples
+
+| Title     | Inward name | Outward name |
+| --------- | ----------- | ------------ |
+| Tests     | tested by   | tests        |
+| Caused by | caused      | caused by    |
+
+## Edit or delete a custom relation
+
+> **Role**: Workspace Admin
+
+From **Workspace Settings > Relations**, click on any custom relation to update its title, inward name, or outward name. You can also delete custom relations you no longer need.
+
+Changes apply across the workspace and update how the relation appears on any work items that already use it.
+
+## Use relations in work items
+
+Once a custom relation exists, any project member can use it when linking work items.
+
+1. Open a work item.
+2. Click **Add relation**.
+3. Choose the relation type from the dropdown — both default and custom relations appear here.
+4. Select the work item to link.
+
+The relation appears on both work items using the appropriate inward or outward label. Learn more about [adding relations to work items](/core-concepts/issues/overview#add-relations).

docs/core-concepts/issues/overview.md

@@ -61,23 +61,29 @@ Duplicates the work item to another project in your workspace. This is particula
 
 Duplicating work items is perfect for replicating recurring tasks, or moving work between project phases while maintaining all the essential context and settings.
 
-## Add relations
+## Add dependencies
+
+Set up scheduling dependencies between work items using the **Add dependency** button. Dependencies control the order in which work happens and are visualized as connectors in the [Timeline layout](/core-concepts/issues/timeline-dependency).
 
-You can also set up relations and dependencies between work items using the **Relations** property. These relationships help clarify how work items are interconnected and how the completion of one task might affect another.
+- **Blocked by** — this work item cannot proceed until the other work item is completed.
+- **Blocking** — this work item must be completed before the other work item can proceed.
+- **Starts Before** — this work item must start before the other work item starts.
+- **Starts After** — this work item can only start after the other work item starts.
+- **Finishes Before** — this work item must finish before the other work item finishes.
+- **Finishes After** — this work item can only finish after the other work item finishes.
 
-![Work item relations](https://media.docs.plane.so/issues/issue-relations.webp#hero-br)
+When both work items have start and due dates set, dependencies appear as visual connectors in the Timeline layout. Violated dependencies — where the dates conflict with the dependency type — are shown as red lines.
 
-- **Relates to**  
-  This relation is used when two work items are linked by some kind of context or dependency, but one does not directly affect the other’s completion.
+## Add relations
 
-- **Duplicate of**  
-  This relation is used when one work item is a duplicate of another. The original work item remains active, while the duplicate work item is linked and typically closed or archived.
+Link work items that are logically connected using the **Add relation** button. Relations describe how work items relate to each other but don't enforce scheduling constraints.
 
-- **Blocking**  
-  When a work item is marked as Blocking, it means that the work item needs to be resolved first before the second work item can progress.
+- **Relates To** — the two work items are connected by context but don't directly affect each other's completion.
+- **Duplicate** — this work item is a duplicate of another. The original remains active while the duplicate is typically closed.
+- **Implements** — this work item implements or fulfills the other work item.
+- **Implemented By** — this work item is implemented by the other work item.
 
-- **Blocked by**  
-  If a work item is marked as Blocked by, it indicates that the work item cannot proceed until the blocking work item is completed.
+To create custom relation types for your workspace, see [Custom relations](/advanced-management/custom-relations).
 
 ## Add links and attachments
 

docs/core-concepts/issues/timeline-dependency.md

@@ -40,6 +40,4 @@ Plane supports three main types of dependencies:
 
 ## Dependency relations
 
-You can also set up dependencies between work items using the **Relations** property. However, for the connectors to show up in the Timeline layout, you'll need to set the **Start date** and **Due date** for the work items.
-
-![Dependency relations](https://media.docs.plane.so/issues/dependency-relations.webp#hero)
+You can also set up dependencies between work items using the **Add dependency** button. However, for the connectors to show up in the Timeline layout, you'll need to set the **Start date** and **Due date** for the work items. See [Add dependencies](/core-concepts/issues/overview#add-dependencies) for more information.