Skip to content

docs: describe chat project templates - #32379

Draft
jaaydenh wants to merge 5 commits into
chat-project-templates/stale-defaultsfrom
chat-project-templates/docs
Draft

jaaydenh wants to merge 5 commits into
chat-project-templates/stale-defaultsfrom
chat-project-templates/docs

Conversation

@jaaydenh

@jaaydenh jaaydenh commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Documents chat project templates, the feature the PRs below add.

  • docs/coder-agents/projects.md gains a Templates section: attaching templates, the opt-in limit, templates you can't access, the default template with its preset or parameter values, the Edit templates dialog, and existing workspaces.
  • docs/coder-agents/tools.md describes how the template tools treat chats in a project.

Split out of #30898. It sits at the top of the stack because it describes the UI of every PR below.

Stack (merge top to bottom):

projects.md gains a Templates section: attaching templates, the opt-in
limit, templates you cannot access, the default template with its
preset or parameter values, the Edit templates dialog, and existing
workspaces. tools.md describes how the template tools treat chats in a
project.
@jaaydenh

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-18T08:13:16.768251Z 1190f9d Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1190f9db39

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".


You can skip this step and attach templates later.
If you change the **Organization** afterward, the dialog clears the selected templates.
To limit the project's chats to these templates, turn on **Limit chats to these templates**.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Split the optional template actions into separate steps

In the create-project procedure, this is a second instruction inside the numbered step that already tells the reader to select templates, and the following default-template direction adds another branch. Split the limit and default-template actions into their own steps or nonprocedural guidance so the sequence follows the repository's one-instruction-per-step contract.

AGENTS.md reference: docs/AGENTS.md:L28-L30

Useful? React with 👍 / 👎.

If a save fails partway, the dialog shows the error and the changes made before the failure stay saved.
Select **Save** again to save the rest.

While an attached template is deleted, deprecated, or doesn't allow Coder Agents, the project doesn't show it and its chats can't use it.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Match the stale-template claim to actual project results

When an attached template is deprecated or has Coder Agents turned off after attachment, this claim is false: LoadProjectsTemplates fetches attachments with only IDs (coderd/x/chatd/chattool/projecttemplates.go:99-101), without filtering Deprecated or AgentsAllowed, and limited list_templates then uses project.Templates directly (coderd/x/chatd/chattool/listtemplates.go:171-177). The project API therefore still returns these templates, and limited chats can still receive them from list_templates, so readers do not get the documented behavior.

Useful? React with 👍 / 👎.

jaaydenh added a commit that referenced this pull request Nov 18, 2026
Adds the API for attaching workspace templates to a chat project, on the
schema and queries in #32309. A project can attach templates, turn on a
limit that restricts its chats to them, and set a default template with
either a default preset or default parameter values. Attaching a
template never grants access to it: every reader is checked against the
template's own sharing. This PR stores and returns `limit_templates`;
#32310 enforces it.

- The limit is opt-in. `limit_templates` is off unless a request turns
it on, which is what every existing project gets.
- Templates are attached and detached one at a time with `PUT` and
`DELETE /chats/projects/{project}/templates/{template}`, so a caller
never replaces a list they can only partly see. Attaching needs project
`update` and template `use`. Detaching needs project `update` and
template `read`, and a template the caller cannot read is reported as
not found. `POST /chats/projects` accepts `template_ids`,
`limit_templates`, and `default_template` for the new project.
- `PATCH /chats/projects/{project}` sets `limit_templates` and
`default_template`, and no longer changes which templates are attached.
The default must be an attached template the caller can read, and its
preset must belong to the template's active version. Default parameter
names and values are checked against that version for templates on the
classic parameter flow; dynamic parameters are checked when a workspace
is built. Detaching the default template clears the default.
- Project responses list only the attached templates the caller can
read, as `templates`, and count the rest as `hidden_template_count`.
`default_template` is omitted when the caller cannot read it. Deleted,
deprecated, and agent-disabled templates are left out and are not
counted as hidden.
- Editing uses `chat_project:update`, which the project owner and the
project `admin` ACL role have.
- Attaching and detaching are audited as writes to the project, with the
template list before and after, including the templates attached while
creating a project. Changes to `limit_templates` and the default
template are part of the project's own audit diff.

Not included: showing which project members lack access to an attached
template, and MCP server attachments.

Stack (merge top to bottom):
- #32309
- #30754 👈
- #32310
- #30755
- #32371
- #32372
- #30756
- #32373
- #32374
- #32375
- #30898
- #32376
- #32377
- #32378
- #32379

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant