From b26e24c07e3b5025d1ec738b1d59ecdb58c36e8f Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Thu, 2 Apr 2026 23:42:33 +0000
Subject: [PATCH] Add Asana integration documentation

Co-Authored-By: Matt Dailey <matt@ref.tools>
---
 docs.json                       |  1 +
 plans/integrations/asana.mdx    | 38 +++++++++++++++++++++++++++++++++
 plans/integrations/overview.mdx |  4 ++++
 3 files changed, 43 insertions(+)
 create mode 100644 plans/integrations/asana.mdx

diff --git a/docs.json b/docs.json
index 9853966..4addf78 100644
--- a/docs.json
+++ b/docs.json
@@ -150,6 +150,7 @@
               "plans/integrations/claude-code-web",
               "plans/integrations/codex",
               "plans/integrations/linear",
+              "plans/integrations/asana",
               "plans/integrations/github"
             ]
           },
diff --git a/plans/integrations/asana.mdx b/plans/integrations/asana.mdx
new file mode 100644
index 0000000..0961bc0
--- /dev/null
+++ b/plans/integrations/asana.mdx
@@ -0,0 +1,38 @@
+---
+title: "Asana"
+description: "Connect Asana tasks to Ref Plans for context and status updates."
+---
+
+import GetHelp from '/snippets/get-help.mdx';
+
+The Asana integration lets you attach Asana tasks to your plans for context and have agents update task status based on progress.
+
+## Connect Asana
+
+1. Go to **Settings** in Ref Plans
+2. Click the **Integrations** tab
+3. Find the **Asana** section
+4. Enter your Personal Access Token (PAT)
+5. Click **Test Connection** to verify
+6. Click **Save**
+
+You can generate a PAT from the [Asana developer console](https://app.asana.com/0/my-apps).
+
+## Usage
+
+Once connected, agents can work with Asana tasks in your plans.
+
+When you provide an Asana task, the agent can:
+
+- **Read task details** — The agent uses the task name, description, assignee, due date, and status as context when researching and structuring your plan
+- **Update task fields** — As tasks are completed, the agent can update the task status, assignee, due date, and other fields
+- **Add comments** — The agent can add comments to tasks to report progress or share context
+
+## Tips
+
+- Agents need a task GID to work with specific Asana tasks — you can find the GID in the task URL or share the task link directly in conversation
+- Share Asana task links in conversation so the agent can extract the task GID automatically
+- You can reference multiple tasks in a single plan if they're related
+- The agent can update Asana based on progress, keeping your project management in sync
+
+<GetHelp/>
diff --git a/plans/integrations/overview.mdx b/plans/integrations/overview.mdx
index 1d94549..b8d58b5 100644
--- a/plans/integrations/overview.mdx
+++ b/plans/integrations/overview.mdx
@@ -44,6 +44,7 @@ Pull context from your project management and development tools into your plans:
 | Source | Description |
 | --- | --- |
 | [Linear](/plans/integrations/linear) | Attach Linear tickets for context; agent can update ticket status |
+| [Asana](/plans/integrations/asana) | Attach Asana tasks for context; agent can update task fields and add comments |
 | [GitHub Issues & PRs](/plans/integrations/github) | Attach GitHub issues and PRs; track PRs linked to plans |
 
 <CardGroup cols={2}>
@@ -62,6 +63,9 @@ Pull context from your project management and development tools into your plans:
   <Card title="Linear" icon="circle-nodes" href="/plans/integrations/linear">
     Connect Linear tickets to your plans.
   </Card>
+  <Card title="Asana" icon="list-check" href="/plans/integrations/asana">
+    Connect Asana tasks to your plans.
+  </Card>
   <Card title="GitHub" icon="github" href="/plans/integrations/github">
     Connect GitHub issues and PRs to your plans.
   </Card>