From 22a596d526ea873a53eea956f36dd1a3bf1c0b96 Mon Sep 17 00:00:00 2001
From: Cian Johnston <cian@coder.com>
Date: Wed, 22 Oct 2025 18:40:10 +0100
Subject: [PATCH 1/5] chore(docs/ai-coder): add migration guide for provider
 version 2.12.0

---
 docs/ai-coder/tasks.md | 77 +++++++++++++++++++++++++++++++++++++-----
 1 file changed, 69 insertions(+), 8 deletions(-)

diff --git a/docs/ai-coder/tasks.md b/docs/ai-coder/tasks.md
index 878c542350472..55e76fd4cb93e 100644
--- a/docs/ai-coder/tasks.md
+++ b/docs/ai-coder/tasks.md
@@ -45,10 +45,15 @@ To import the template and begin configuring it, follow the [documentation in th
 
 A template becomes a Task template if it defines a `coder_ai_task` resource and a `coder_parameter` named `"AI Prompt"`. Coder analyzes template files during template version import to determine if these requirements are met. Try adding this terraform block to an existing template where you'll add our Claude Code module. Note: the `coder_ai_task` resource is defined within the [Claude Code Module](https://registry.coder.com/modules/coder/claude-code?tab=readme), so it's not defined within this block.
 
+
 ```hcl
-data "coder_parameter" "ai_prompt" {
-    name = "AI Prompt"
-    type = "string"
+terraform {
+  required_providers {
+    coder = {
+      source = "coder/coder"
+      version = ">= 2.12"
+    }
+  }
 }
 
 data "coder_parameter" "setup_script" {
@@ -66,7 +71,7 @@ data "coder_parameter" "setup_script" {
 # Or use a custom agent:
 module "claude-code" {
   source   = "registry.coder.com/coder/claude-code/coder"
-  version  = "3.0.1"
+  version  = "4.0.0"
   agent_id = coder_agent.example.id
   workdir  = "/home/coder/project"
 
@@ -77,7 +82,7 @@ module "claude-code" {
   claude_code_version = "1.0.82" # Pin to a specific version
   agentapi_version    = "v0.6.1"
 
-  ai_prompt = data.coder_parameter.ai_prompt.value
+  ai_prompt = coder_task.task.prompt
   model     = "sonnet"
 
   # Optional: run your pre-flight script
@@ -97,6 +102,10 @@ module "claude-code" {
   EOF
 }
 
+resource "coder_ai_task" "task" {
+  app_id = module.claude-code.task_app_id
+}
+
 # Rename to `anthropic_oauth_token` if using the Oauth Token
 variable "anthropic_api_key" {
   type        = string
@@ -105,13 +114,65 @@ variable "anthropic_api_key" {
 }
 ```
 
-> [!NOTE]
-> This definition is not final and may change while Tasks is in beta. After any changes, we guarantee backwards compatibility for one minor Coder version. After that, you may need to update your template to continue using it with Tasks.
-
 Because Tasks run unpredictable AI agents, often for background tasks, we recommend creating a separate template for Coder Tasks with limited permissions. You can always duplicate your existing template, then apply separate network policies/firewalls/permissions to the template. From there, follow the docs for one of our [built-in modules for agents](https://registry.coder.com/modules?search=tag%3Atasks) in order to add it to your template, configure your LLM provider.
 
 Alternatively, follow our guide for [custom agents](./custom-agents.md).
 
+## Migrating Task Templates for Coder version 2.28.0
+
+Prior to Coder version 2.28.0, the definition of a Coder task was different to the above. It required the following to be defined in the template:
+
+1. A Coder parameter specifically named `"AI Prompt"`,
+2. A `coder_workspace_app` that runs the `coder/agentapi` binary,
+3. A `coder_ai_task` resource in the template that sets `sidebar_app.id`. This was generally defined in Coder modules specific to AI Tasks.
+
+Note that 2 and 3 were generally handled by the `coder/agentapi` Terraform module.
+
+The pre-2.28.0 definition will be supported until the release of 2.29.0. You will need to update your Tasks-enabled templates to continue using Tasks after this release.
+
+You can view an [example here](https://github.com/coder/coder/pull/20426). Alternatively, follow the steps below:
+
+1. Update the Coder Terraform provider to at least version 2.12.0:
+
+```diff
+terraform {
+  required_providers {
+    coder = {
+      source = "coder/coder"
+-      version = "x.y.z"
++      version = ">= 2.12"
+    }
+  }
+}
+```
+
+1. Define a `coder_ai_task` resource in your template:
+
+```diff
++resource "coder_ai_task" "task" {}
+```
+
+1. Update the version of the respective AI agent module (e.g. `claude-code`) to at least 4.0.0 and provide the prompt from `coder_ai_task.prompt` instead of the "AI Prompt" parameter:
+
+```diff
+module "claude-code" {
+  source              = "registry.coder.com/coder/claude-code/coder"
+-  version             = "4.0.0"
++  version             = "4.0.0"
+    ...
+-  ai_prompt           = data.coder_parameter.ai_prompt.value
++  ai_prompt           = coder_ai_task.task.prompt
+}
+```
+
+1. Update the `coder_ai_task` resource and set `app_id` to the `task_app_id` output of the module:
+
+```diff
+resource "coder_ai_task" "task" {
++ app_id = module.claude-code.task_app_id
+}
+```
+
 ## Customizing the Task UI
 
 The Task UI displays all workspace apps declared in a Task template. You can customize the app shown in the sidebar using the `sidebar_app.id` field on the `coder_ai_task` resource.

From 6cff4cfa7b561655a5673f268ab81d2bd2adf73c Mon Sep 17 00:00:00 2001
From: Cian Johnston <cian@coder.com>
Date: Thu, 23 Oct 2025 09:56:51 +0100
Subject: [PATCH 2/5] Apply suggestion from @bpmct

Co-authored-by: Ben Potter <ben@coder.com>
---
 docs/ai-coder/tasks.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/ai-coder/tasks.md b/docs/ai-coder/tasks.md
index 55e76fd4cb93e..ba89fba229b2e 100644
--- a/docs/ai-coder/tasks.md
+++ b/docs/ai-coder/tasks.md
@@ -165,7 +165,7 @@ module "claude-code" {
 }
 ```
 
-1. Update the `coder_ai_task` resource and set `app_id` to the `task_app_id` output of the module:
+1. Add the `coder_ai_task` resource and set `app_id` to the `task_app_id` output of the module:
 
 ```diff
 resource "coder_ai_task" "task" {

From 4c9667c2e359c6c6aac5cbc7ad01d85e5dab8676 Mon Sep 17 00:00:00 2001
From: Cian Johnston <cian@coder.com>
Date: Thu, 23 Oct 2025 11:54:54 +0100
Subject: [PATCH 3/5] adjust definition of Task template

---
 docs/ai-coder/tasks.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/docs/ai-coder/tasks.md b/docs/ai-coder/tasks.md
index ba89fba229b2e..cc5ba56442ac3 100644
--- a/docs/ai-coder/tasks.md
+++ b/docs/ai-coder/tasks.md
@@ -43,8 +43,7 @@ To import the template and begin configuring it, follow the [documentation in th
 
 ### Option 2&rpar; Create or Duplicate Your Own Template
 
-A template becomes a Task template if it defines a `coder_ai_task` resource and a `coder_parameter` named `"AI Prompt"`. Coder analyzes template files during template version import to determine if these requirements are met. Try adding this terraform block to an existing template where you'll add our Claude Code module. Note: the `coder_ai_task` resource is defined within the [Claude Code Module](https://registry.coder.com/modules/coder/claude-code?tab=readme), so it's not defined within this block.
-
+A template becomes a Task template if it defines a `coder_ai_task` resource. Coder analyzes template files during template version import to determine if these requirements are met. Try adding this terraform block to an existing template where you'll add our Claude Code module. Note: the `coder_ai_task` resource is defined within the [Claude Code Module](https://registry.coder.com/modules/coder/claude-code?tab=readme), so it's not defined within this block.
 
 ```hcl
 terraform {

From a49b0b945bc874d0e222c358dd0a90f7f1906085 Mon Sep 17 00:00:00 2001
From: Cian Johnston <cian@coder.com>
Date: Tue, 4 Nov 2025 12:00:48 +0000
Subject: [PATCH 4/5] Address addition of new data source in provider v2.13.0

---
 docs/ai-coder/tasks-core-principles.md |  39 +++---
 docs/ai-coder/tasks-migration.md       | 161 +++++++++++++++++++++++++
 docs/ai-coder/tasks.md                 |  65 ++--------
 docs/manifest.json                     |   6 +
 docs/tutorials/quickstart.md           |   2 +-
 5 files changed, 196 insertions(+), 77 deletions(-)
 create mode 100644 docs/ai-coder/tasks-migration.md

diff --git a/docs/ai-coder/tasks-core-principles.md b/docs/ai-coder/tasks-core-principles.md
index 337d499d95ec9..bdb3be0829e2d 100644
--- a/docs/ai-coder/tasks-core-principles.md
+++ b/docs/ai-coder/tasks-core-principles.md
@@ -49,19 +49,16 @@ There are two approaches to turning a Template into a Task Template:
 
 You can use a pre-existing agent module that [Coder maintains](https://registry.coder.com/modules). When using an agent module, you must define:
 
-- `coder_parameter` named _ai_prompt_: Define the AI prompt input so users can define/specify what tasks need to run
+- `coder_ai_task` resource: links a `coder_app` to a Task.
 - **Agentic Module** that defines the agent you want to use, e.g. Claude Code, Codex CLI, Gemini CLI
 
-Coder maintains various agentic modules; see [Coder Labs](https://registry.coder.com/contributors/coder-labs). These modules, in addition to defining connection information for the specific agent, reference the [AgentAPI module](https://registry.coder.com/modules/coder/agentapi) which provides connection, reporting, and agent life cycle management operations. The module also defines the `coder_ai_task` resource which allows the Task to be visible in the UI.
+Coder maintains various agentic modules; see [Coder Labs](https://registry.coder.com/contributors/coder-labs). These modules, in addition to defining connection information for the specific agent, reference the [AgentAPI module](https://registry.coder.com/modules/coder/agentapi) which provides connection, reporting, and agent life cycle management operations. The modules also output the specific `coder_app` identifier for the specific agent running inside the workspace.
 
-The following code snippet can be dropped into any existing template to modify it into a Claude-Code enabled task template. This snippet also includes space for a setup script that will prime the agent for execution.
+The following code snippet can be dropped into any existing template in Coder v2.28 or above to modify it into a Claude-Code enabled task template. This snippet also includes space for a setup script that will prime the agent for execution.
 
-```hcl
-data "coder_parameter" "ai_prompt" {
-    name = "AI Prompt"
-    type = "string"
-}
+> [!NOTE] This requires at least version 2.13.0 of the `coder/coder` Terraform provider.
 
+```hcl
 data "coder_parameter" "setup_script" {
   name         = "setup_script"
   display_name = "Setup Script"
@@ -72,12 +69,18 @@ data "coder_parameter" "setup_script" {
   default      = ""
 }
 
+data "coder_ai_task_prompt" "me" {}
+
+resource "coder_ai_task" "task" {
+  app_id = module.claude-code.task_app_id
+}
+
 # The Claude Code module does the automatic task reporting
 # Other agent modules: https://registry.coder.com/modules?search=agent
-# Or use a custom agent:  
+# Or use a custom agent:
 module "claude-code" {
   source   = "registry.coder.com/coder/claude-code/coder"
-  version  = "3.0.1"
+  version  = "4.0.0"
   agent_id = coder_agent.example.id
   workdir  = "/home/coder/project"
 
@@ -118,19 +121,19 @@ variable "anthropic_api_key" {
 
 Let's break down this snippet:
 
-- The `module "claude-code"` sets up the Task template to use Claude Code, but Coder's Registry supports many other agent modules like [OpenAI's Codex](https://registry.coder.com/modules/coder-labs/codex) or [Gemini CLI](https://registry.coder.com/modules/coder-labs/gemini)
-- Each module defines its own specific inputs. Claude Code expects the `claude_api_key` input, but OpenAI based agents expect `OPENAI_API_KEY` for example. You'll want to check the specific module's defined variables to know what exactly needs to be defined
+- The `module "claude-code"` sets up the Task template to use Claude Code. Coder's Registry supports many other agent modules like [OpenAI's Codex](https://registry.coder.com/modules/coder-labs/codex) or [Gemini CLI](https://registry.coder.com/modules/coder-labs/gemini)
+- Each module defines its own specific inputs. Claude Code expects the `claude_api_key` input, but OpenAI based agents expect `OPENAI_API_KEY` for example. You'll want to check the specific module's defined variables to know what exactly needs to be defined. You will also generally need to pass `data.coder_task.me.prompt`
+- Each module outputs the UUID of the `coder_app` related to the AI agent. In the above example, the output is named `task_app_id`. See the relevant documentation for the module for more detailed information.
 - You can define specific scripts to run before the module is installed, `pre_install_script`, or after install, `pre_install_script`. For example, you could define a setup script that calls to AWS S3 and pulls specific files you want your agent to have access to
 
 #### Using a Custom Agent
 
 Coder allows you to define a custom agent. When doing so, you must define:
 
-- `coder_parameter` named _ai_prompt_: Define the AI prompt input so users can define/specify what tasks need to run
-- `coder_ai_task` which registers the task with the UI and allows the task to be visible
-- **AgentAPI binary** which provides runtime execution logistics for the task
+- A `coder_app` resource that uses [`coder/agentapi`](https://github.com/coder/agentapi) to run the custom agent. **AgentAPI** provides runtime execution logistics for the task.
+- A `coder_ai_task` resource which associates the `coder_app` related to the AI agent with the Task.
 
-You can find the latest [AgentAPI binary here](https://github.com/coder/agentapi/releases). You can alternatively import and use the [AgentAPI module](https://registry.coder.com/modules/coder/agentapi?tab=variables) Coder maintains, which also conveniently defines the `coder_ai_task` resource.
+You can find the latest [AgentAPI binary here](https://github.com/coder/agentapi/releases). You can alternatively import and use the [AgentAPI module](https://registry.coder.com/modules/coder/agentapi?tab=variables) Coder maintains.
 
 Read more about [custom agents here](https://coder.com/docs/ai-coder/custom-agents).
 
@@ -141,7 +144,7 @@ Coder recommends using pre-existing agent modules when making a Task Template. M
 1. Identify the existing agent you want access to in our [Registry](https://registry.coder.com/modules)
 1. Add the agent's module to your existing template
 1. Define the module's required inputs
-1. Define the `coder_parameter`
+1. Define the `coder_ai_task` resource.
 
 and you're all set to go! If you want to build your own custom agent, read up on our [Custom Agents](https://coder.com/docs/ai-coder/custom-agents) documentation.
 
@@ -163,7 +166,7 @@ These design principles aren’t just technical guidelines; they're the lens thr
 
 ### Practical Considerations
 
-Tasks don't expose template parameters at runtime, other than the AI Prompt. If users need to choose different compute, region, or tooling options for example, you can define workspace presets in the template and have users select a preset when starting the Task. See workspace presets for details: ../admin/templates/extending-templates/parameters#workspace-presets.
+Tasks don't expose template parameters at runtime. If users need to choose different compute, region, or tooling options for example, you can define workspace presets in the template and have users select a preset when starting the Task. See workspace presets for details: ../admin/templates/extending-templates/parameters#workspace-presets.
 
 ### Identity, Security, and Access
 
diff --git a/docs/ai-coder/tasks-migration.md b/docs/ai-coder/tasks-migration.md
new file mode 100644
index 0000000000000..9de8e7646905f
--- /dev/null
+++ b/docs/ai-coder/tasks-migration.md
@@ -0,0 +1,161 @@
+# Migrating Task Templates for Coder version 2.28.0
+
+Prior to Coder version 2.28.0, the definition of a Coder task was different to the above. It required the following to be defined in the template:
+
+1. A Coder parameter specifically named `"AI Prompt"`,
+2. A `coder_workspace_app` that runs the `coder/agentapi` binary,
+3. A `coder_ai_task` resource in the template that sets `sidebar_app.id`. This was generally defined in Coder modules specific to AI Tasks.
+
+Note that 2 and 3 were generally handled by the `coder/agentapi` Terraform module.
+
+The pre-2.28.0 definition will be supported until the release of 2.29.0. You will need to update your Tasks-enabled templates to continue using Tasks after this release.
+
+You can view an [example migration here](https://github.com/coder/coder/pull/20420). Alternatively, follow the steps below:
+
+## Upgrade Steps
+
+1. Update the Coder Terraform provider to at least version 2.13.0:
+
+```diff
+terraform {
+  required_providers {
+    coder = {
+      source = "coder/coder"
+-      version = "x.y.z"
++      version = ">= 2.13"
+    }
+  }
+}
+```
+
+1. Define a `coder_ai_task` resource and `coder_task` data source in your template:
+
+```diff
++data "coder_task" "me" {}
++resource "coder_ai_task" "task" {}
+```
+
+1. Update the version of the respective AI agent module (e.g. `claude-code`) to at least 4.0.0 and provide the prompt from `data.coder_task.me.prompt` instead of the "AI Prompt" parameter.
+
+```diff
+module "claude-code" {
+  source              = "registry.coder.com/coder/claude-code/coder"
+-  version             = "4.0.0"
++  version             = "4.0.0"
+    ...
+-  ai_prompt           = data.coder_parameter.ai_prompt.value
++  ai_prompt           = data.coder_task.me.prompt
+}
+```
+
+1. Add the `coder_ai_task` resource and set `app_id` to the `task_app_id` output of the Claude module.
+
+> [!NOTE] Refer to the documentation for the specific module you are using for the exact name of the output.
+
+```diff
+resource "coder_ai_task" "task" {
++ app_id = module.claude-code.task_app_id
+}
+```
+
+## Coder Tasks format pre-2.28
+
+Below is a minimal illustrative example of a Coder Tasks template pre-2.28.0:
+
+```hcl
+terraform {
+  required_providers {
+    coder = {
+      source = "coder/coder
+    }
+  }
+}
+
+data "coder_workspace" "me" {}
+
+resource "coder_agent" "main" { ... }
+
+# The prompt is passed in via the specifically named "AI Prompt" parameter.
+data "coder_parameter" "ai_prompt" {
+  name    = "AI Prompt"
+  mutable = true
+}
+
+# This coder_app is the interface to the Coder Task.
+# This is assumed to be a running instance of coder/agentapi
+resource "coder_app" "ai_agent" {
+  ...
+}
+
+# Assuming that the below script runs `coder/agentapi` with the prompt
+# defined in ARG_AI_PROMPT
+resource "coder_script" "agentapi" {
+  agent_id     = coder_agent.main.id
+  run_on_start = true
+  script       = <<EOT
+    #!/usr/bin/env bash
+    ARG_AI_PROMPT=${data.coder_parameter.ai_prompt.value} \
+    /tmp/run_agentapi.sh
+  EOT
+  ...
+}
+
+# The coder_ai_task resource associates the task to the app.
+resource "coder_ai_task" "task" {
+  sidebar_app {
+    id = coder_app.ai_agent.id
+  }
+}
+```
+
+## Tasks format post-2.28
+
+In v2.28 and above, the following changes were made:
+
+- The explicitly named "AI Prompt" parameter is deprecated. The task prompt is now available in the `coder_ai_task` resource (provider version 2.12 and above) and `coder_task` data source (provider version 2.13 and above).
+- Modules no longer define the `coder_ai_task` resource. These must be defined explicitly in the template.
+- The `sidebar_app` field of the `coder_ai_task` resource is now deprecated. In its place, use `app_id`.
+
+Example:
+
+```hcl
+terraform {
+  required_providers {
+    coder = {
+      source = "coder/coder
+      version = ">= 2.13.0
+    }
+  }
+}
+
+data "coder_workspace" "me" {}
+
+# The prompt is now available in the coder_task data source.
+data "coder_task" "me" {}
+
+resource "coder_agent" "main" { ... }
+
+# This coder_app is the interface to the Coder Task.
+# This is assumed to be a running instance of coder/agentapi (for instance, started via `coder_script`).
+resource "coder_app" "ai_agent" {
+  ...
+}
+
+# Assuming that the below script runs `coder/agentapi` with the prompt
+# defined in ARG_AI_PROMPT
+resource "coder_script" "agentapi" {
+  agent_id     = coder_agent.main.id
+  run_on_start = true
+  script       = <<EOT
+    #!/usr/bin/env bash
+    ARG_AI_PROMPT=${data.coder_task.me.prompt} \
+    /tmp/run_agentapi.sh
+  EOT
+  ...
+}
+
+# The coder_ai_task resource associates the task to the app.
+resource "coder_ai_task" "task" {
+  app_id = coder_app.ai_agent.id
+}
+```
diff --git a/docs/ai-coder/tasks.md b/docs/ai-coder/tasks.md
index cc5ba56442ac3..395a0cc369131 100644
--- a/docs/ai-coder/tasks.md
+++ b/docs/ai-coder/tasks.md
@@ -39,7 +39,7 @@ Try prompts such as:
 - "document the project structure"
 - "change the primary color theme to purple"
 
-To import the template and begin configuring it, follow the [documentation in the Coder Registry](https://registry.coder.com/templates/coder-labs/tasks-docker)
+To import the template and begin configuring it, import the example [Run Coder Tasks on Docker](https://github.com/coder/coder/tree/main/examples/templates/tasks-docker) template.
 
 ### Option 2&rpar; Create or Duplicate Your Own Template
 
@@ -50,7 +50,7 @@ terraform {
   required_providers {
     coder = {
       source = "coder/coder"
-      version = ">= 2.12"
+      version = ">= 2.13"
     }
   }
 }
@@ -65,6 +65,8 @@ data "coder_parameter" "setup_script" {
   default      = ""
 }
 
+data "coder_task" "me" {}
+
 # The Claude Code module does the automatic task reporting
 # Other agent modules: https://registry.coder.com/modules?search=agent
 # Or use a custom agent:
@@ -81,7 +83,7 @@ module "claude-code" {
   claude_code_version = "1.0.82" # Pin to a specific version
   agentapi_version    = "v0.6.1"
 
-  ai_prompt = coder_task.task.prompt
+  ai_prompt = data.coder_task.me.prompt
   model     = "sonnet"
 
   # Optional: run your pre-flight script
@@ -117,64 +119,11 @@ Because Tasks run unpredictable AI agents, often for background tasks, we recomm
 
 Alternatively, follow our guide for [custom agents](./custom-agents.md).
 
-## Migrating Task Templates for Coder version 2.28.0
-
-Prior to Coder version 2.28.0, the definition of a Coder task was different to the above. It required the following to be defined in the template:
-
-1. A Coder parameter specifically named `"AI Prompt"`,
-2. A `coder_workspace_app` that runs the `coder/agentapi` binary,
-3. A `coder_ai_task` resource in the template that sets `sidebar_app.id`. This was generally defined in Coder modules specific to AI Tasks.
-
-Note that 2 and 3 were generally handled by the `coder/agentapi` Terraform module.
-
-The pre-2.28.0 definition will be supported until the release of 2.29.0. You will need to update your Tasks-enabled templates to continue using Tasks after this release.
-
-You can view an [example here](https://github.com/coder/coder/pull/20426). Alternatively, follow the steps below:
-
-1. Update the Coder Terraform provider to at least version 2.12.0:
-
-```diff
-terraform {
-  required_providers {
-    coder = {
-      source = "coder/coder"
--      version = "x.y.z"
-+      version = ">= 2.12"
-    }
-  }
-}
-```
-
-1. Define a `coder_ai_task` resource in your template:
-
-```diff
-+resource "coder_ai_task" "task" {}
-```
-
-1. Update the version of the respective AI agent module (e.g. `claude-code`) to at least 4.0.0 and provide the prompt from `coder_ai_task.prompt` instead of the "AI Prompt" parameter:
-
-```diff
-module "claude-code" {
-  source              = "registry.coder.com/coder/claude-code/coder"
--  version             = "4.0.0"
-+  version             = "4.0.0"
-    ...
--  ai_prompt           = data.coder_parameter.ai_prompt.value
-+  ai_prompt           = coder_ai_task.task.prompt
-}
-```
-
-1. Add the `coder_ai_task` resource and set `app_id` to the `task_app_id` output of the module:
-
-```diff
-resource "coder_ai_task" "task" {
-+ app_id = module.claude-code.task_app_id
-}
-```
+> [!IMPORTANT] Upgrading from Coder v2.27 or earlier? See the [Tasks Migration Guide](./tasks-migration.md) for breaking changes in v2.28.0.
 
 ## Customizing the Task UI
 
-The Task UI displays all workspace apps declared in a Task template. You can customize the app shown in the sidebar using the `sidebar_app.id` field on the `coder_ai_task` resource.
+The Task UI displays all workspace apps declared in a Task template. You can customize the app shown in the sidebar using the `app_id` field on the `coder_ai_task` resource.
 
 If a workspace app has the special `"preview"` slug, a navbar will appear above it. This is intended for templates that let users preview a web app they’re working on.
 
diff --git a/docs/manifest.json b/docs/manifest.json
index 8ef8e3e5fa326..49c2a482332ed 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -900,6 +900,12 @@
 							"path": "./ai-coder/custom-agents.md",
 							"state": ["beta"]
 						},
+						{
+							"title": "Tasks Migration Guide",
+							"description": "Changes to Coder Tasks made in v2.28",
+							"path": "./ai-coder/tasks-migration.md",
+							"state": ["beta"]
+						},
 						{
 							"title": "Security \u0026 Boundaries",
 							"description": "Learn about security and boundaries when running AI coding agents in Coder",
diff --git a/docs/tutorials/quickstart.md b/docs/tutorials/quickstart.md
index 19f9571326cf7..b3db328ab0ceb 100644
--- a/docs/tutorials/quickstart.md
+++ b/docs/tutorials/quickstart.md
@@ -239,7 +239,7 @@ advanced capabilities that Coder offers.
 ### Get Coder Tasks Running
 
 Coder Tasks is an interface that allows you to run and manage coding agents like
-Claude Code within a given Workspace. Tasks become available when the Template for a Workspace has the `coder_ai_task` resource and `coder_parameter` named `AI Prompt` defined in its source code.
+Claude Code within a given Workspace. Tasks become available when the Template for a Workspace has the `coder_ai_task` resource defined in its source code.
 In other words, any existing template can become a Task template by adding in that
 resource and parameter.
 

From 5d258517163b317e873ce896e886a2786b248e55 Mon Sep 17 00:00:00 2001
From: Cian Johnston <cian@coder.com>
Date: Tue, 4 Nov 2025 14:33:03 +0000
Subject: [PATCH 5/5] address maf's comments

---
 docs/ai-coder/tasks-core-principles.md | 14 ++++++++------
 docs/ai-coder/tasks-migration.md       |  7 ++++---
 docs/ai-coder/tasks.md                 | 12 +++++++-----
 docs/tutorials/quickstart.md           |  2 +-
 4 files changed, 20 insertions(+), 15 deletions(-)

diff --git a/docs/ai-coder/tasks-core-principles.md b/docs/ai-coder/tasks-core-principles.md
index bdb3be0829e2d..66053d486d8de 100644
--- a/docs/ai-coder/tasks-core-principles.md
+++ b/docs/ai-coder/tasks-core-principles.md
@@ -69,7 +69,7 @@ data "coder_parameter" "setup_script" {
   default      = ""
 }
 
-data "coder_ai_task_prompt" "me" {}
+data "coder_task" "me" {}
 
 resource "coder_ai_task" "task" {
   app_id = module.claude-code.task_app_id
@@ -91,7 +91,7 @@ module "claude-code" {
   claude_code_version = "1.0.82" # Pin to a specific version
   agentapi_version    = "v0.6.1"
 
-  ai_prompt = data.coder_parameter.ai_prompt.value
+  ai_prompt = data.coder_task.me.prompt
   model     = "sonnet"
 
   # Optional: run your pre-flight script
@@ -141,10 +141,12 @@ Read more about [custom agents here](https://coder.com/docs/ai-coder/custom-agen
 
 Coder recommends using pre-existing agent modules when making a Task Template. Making a Task Template boils down to:
 
-1. Identify the existing agent you want access to in our [Registry](https://registry.coder.com/modules)
-1. Add the agent's module to your existing template
-1. Define the module's required inputs
-1. Define the `coder_ai_task` resource.
+1. Identify the existing agent you want access to in our [Registry](https://registry.coder.com/modules).
+1. Add the agent's module to your existing template.
+1. Define the `coder_ai_task` resource and `coder_task` data source.
+1. Wire in the module's inputs and outputs:
+    - Pass the prompt from the `coder_task` data source into the module.
+    - Pass the module's `task_app_id` output into the `coder_ai_task` resource.
 
 and you're all set to go! If you want to build your own custom agent, read up on our [Custom Agents](https://coder.com/docs/ai-coder/custom-agents) documentation.
 
diff --git a/docs/ai-coder/tasks-migration.md b/docs/ai-coder/tasks-migration.md
index 9de8e7646905f..d489c1d4742d7 100644
--- a/docs/ai-coder/tasks-migration.md
+++ b/docs/ai-coder/tasks-migration.md
@@ -60,7 +60,8 @@ resource "coder_ai_task" "task" {
 
 ## Coder Tasks format pre-2.28
 
-Below is a minimal illustrative example of a Coder Tasks template pre-2.28.0:
+Below is a minimal illustrative example of a Coder Tasks template pre-2.28.0.
+**Note that this is NOT a full template.**
 
 ```hcl
 terraform {
@@ -108,7 +109,7 @@ resource "coder_ai_task" "task" {
 }
 ```
 
-## Tasks format post-2.28
+## Tasks format from 2.28 onwards
 
 In v2.28 and above, the following changes were made:
 
@@ -116,7 +117,7 @@ In v2.28 and above, the following changes were made:
 - Modules no longer define the `coder_ai_task` resource. These must be defined explicitly in the template.
 - The `sidebar_app` field of the `coder_ai_task` resource is now deprecated. In its place, use `app_id`.
 
-Example:
+Example (**not** a full template):
 
 ```hcl
 terraform {
diff --git a/docs/ai-coder/tasks.md b/docs/ai-coder/tasks.md
index 395a0cc369131..c5235b208e8af 100644
--- a/docs/ai-coder/tasks.md
+++ b/docs/ai-coder/tasks.md
@@ -43,7 +43,9 @@ To import the template and begin configuring it, import the example [Run Coder T
 
 ### Option 2&rpar; Create or Duplicate Your Own Template
 
-A template becomes a Task template if it defines a `coder_ai_task` resource. Coder analyzes template files during template version import to determine if these requirements are met. Try adding this terraform block to an existing template where you'll add our Claude Code module. Note: the `coder_ai_task` resource is defined within the [Claude Code Module](https://registry.coder.com/modules/coder/claude-code?tab=readme), so it's not defined within this block.
+A template becomes a Task-capable template if it defines a `coder_ai_task` resource. Coder analyzes template files during template version import to determine if these requirements are met. Try adding this terraform block to an existing template where you'll add our Claude Code module.
+
+> [!NOTE] The `coder_ai_task` resource is not defined within the [Claude Code Module](https://registry.coder.com/modules/coder/claude-code?tab=readme). You need to define it yourself.
 
 ```hcl
 terraform {
@@ -67,6 +69,10 @@ data "coder_parameter" "setup_script" {
 
 data "coder_task" "me" {}
 
+resource "coder_ai_task" "task" {
+  app_id = module.claude-code.task_app_id
+}
+
 # The Claude Code module does the automatic task reporting
 # Other agent modules: https://registry.coder.com/modules?search=agent
 # Or use a custom agent:
@@ -103,10 +109,6 @@ module "claude-code" {
   EOF
 }
 
-resource "coder_ai_task" "task" {
-  app_id = module.claude-code.task_app_id
-}
-
 # Rename to `anthropic_oauth_token` if using the Oauth Token
 variable "anthropic_api_key" {
   type        = string
diff --git a/docs/tutorials/quickstart.md b/docs/tutorials/quickstart.md
index b3db328ab0ceb..2b7b2c2e385bb 100644
--- a/docs/tutorials/quickstart.md
+++ b/docs/tutorials/quickstart.md
@@ -239,7 +239,7 @@ advanced capabilities that Coder offers.
 ### Get Coder Tasks Running
 
 Coder Tasks is an interface that allows you to run and manage coding agents like
-Claude Code within a given Workspace. Tasks become available when the Template for a Workspace has the `coder_ai_task` resource defined in its source code.
+Claude Code within a given Workspace. Tasks become available when a Workspace Template has the `coder_ai_task` resource defined in its source code.
 In other words, any existing template can become a Task template by adding in that
 resource and parameter.