Skip to content

feat: add project instructions to Coder Agents chat projects - #30349

Closed
jaaydenh wants to merge 14 commits into
chat-project-page/chats-listfrom
chat-project-page/instructions
Closed

jaaydenh wants to merge 14 commits into
chat-project-page/chats-listfrom
chat-project-page/instructions

Conversation

@jaaydenh

@jaaydenh jaaydenh commented Oct 5, 2026 •

Copy link
Copy Markdown
Collaborator

Adds project-level instructions to Coder Agents chat projects. A project can hold one block of instructions that is injected into the model context of every chat in that project, for every user who chats there.

API (experimental, behind chat-projects): GET, PUT, and DELETE /api/experimental/organizations/{organization}/chats/projects/{project}/instructions. GET returns an empty value when nothing is set. PUT sanitizes the text, rejects blank or oversized input with 400, and records who made the change. DELETE is idempotent and returns 204. Instructions live in a new organization-scoped chat_project_instructions table (migration 000609) that cascades on project delete. Authorization checks the parent project: read access to view, update access to change. The codersdk client has matching methods.

chatd: instructions are resolved on every turn and added to the system prompt as a <project-instructions> block, before personal instructions. Edits therefore apply to existing chats on their next turn. Subagents inherit the instructions through their root chat. If loading fails, the turn logs a warning and continues without them.

UI: the project page now has Chats and Details columns below the composer. In Details, Instructions shows an empty state with Create, or a three-line preview with a pen icon button to edit. A dialog handles create, edit, and delete. If someone else changes the instructions while the dialog is open, Save and Delete stay disabled until the user loads the latest version or keeps their draft.

Out of scope, planned as follow-ups: project audit logging of instruction changes, project RBAC for who can edit, and the other Details sections (templates, MCPs, repos, skills, members).

Dogfood UAT ran on a remote Coder Agents workspace and passed. It covered the UI flows, the API, and injection into new and existing chats.

Screenshots

From UAT, except "Instructions set", which shows the current pen icon design from Storybook.

Empty state Instructions set
Details panel with no instructions and a Create button Instructions preview clamped to three lines with a pen icon edit button in the top right corner
Edit dialog Concurrent edit warning
Edit instructions dialog with Delete, Cancel, and Save Warning that someone else changed the instructions, with Keep my draft and Load latest
Chat following project instructions

The instructions asked the model to end replies with PINEAPPLE, then were edited to MANGO. The next turn of the same chat followed the edit.

Chat where the first reply ends in PINEAPPLE and the reply after the edit ends in MANGO

Stacked on #30294.

Store one instructions text per chat project, expose it through the
experimental project API (GET/PUT/DELETE .../instructions), and inject it
into the system prompt of every chat in the project on each turn. Subagent
chats inherit the root chat's project instructions.
Show a Details panel beside the project's chats with an Instructions
section: an empty state with a Create button, a clamped preview with an
Edit button, and an updated-by footer. A dialog creates, edits, and
deletes the instructions.
- Report instructions edited by a soft-deleted user without naming them.
- Escape <project-instructions> tags inside the text so it cannot close
  the system prompt block early.
- Treat an empty instructions string like blank text (same 400 message).
- Dialog: show only the latest action's error, clear it when the draft
  changes, show the error detail (which states the byte limit), ignore a
  second Save or Delete while one is in flight, and keep Save disabled for
  surrounding-whitespace-only edits.
- Refetch instructions on window focus so a stale tab edits current text.
Assert that deleting a project with instructions succeeds and removes
them (ON DELETE CASCADE), that the details panel shows the saved
preview and updated-by footer after create, and that the footer is
hidden after delete.
@jaaydenh

jaaydenh commented Oct 5, 2026

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 5, 2026 •

Copy link
Copy Markdown

Codex Review Summary

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

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-05T14:52:00.304124Z b26179e 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: 6c102260c0

ℹ️ 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".

Comment thread coderd/chat_project_instructions.go Resolved
Store organization_id on chat_project_instructions, populated from the
parent project, matching chat_project_memories and the repository rule
that new resources carry direct organization scope.
…ank drafts

Remount the details panel per project so an open editor cannot save a
draft to the next project after route navigation, and treat drafts made
only of characters the server strips as blank.
@jaaydenh

jaaydenh commented Oct 5, 2026

Copy link
Copy Markdown
Collaborator Author

@codex review

@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: bdbeaf5d3a

ℹ️ 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".

…s refetches

Compare the draft with the instructions captured when the editor opened,
so a focus refetch that brings another editor's change cannot enable
Save and overwrite it. Treat invisible-only edits as no change.

Assert cache and form state instead of DOM presence in the panel tests,
per FE1, and make the project-change test verify the discarded draft.
@jaaydenh

jaaydenh commented Oct 5, 2026

Copy link
Copy Markdown
Collaborator Author

@codex review

@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: f4a6b3a048

ℹ️ 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".

Comment thread site/src/api/queries/chatProjects.ts Resolved
…nsaction

A failed read-back after a committed upsert returned 500 for a change
that was saved. Run both in one transaction so the write rolls back.
… states

Report errors without an API message as a failed delete, not a failed
save. Add stories for the invisible-character warning and the saving
and deleting states, and wire the instructions query inline per story.
@jaaydenh

jaaydenh commented Oct 5, 2026

Copy link
Copy Markdown
Collaborator Author

@codex review

@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: 5cfedffd2e

ℹ️ 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".

…fetch

When a refetch changes the saved instructions while the editor is open,
show a warning and keep Save disabled until the user loads the latest
version or chooses to keep their draft and replace it.
@jaaydenh

jaaydenh commented Oct 5, 2026

Copy link
Copy Markdown
Collaborator Author

@codex review

@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: ea8cd713ec

ℹ️ 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".

Comment thread site/src/api/queries/chatProjects.ts Resolved
…flicted deletes

Cancel in-flight instruction fetches before writing a mutation result to
the cache, so a refetch that read the old value cannot overwrite it, and
disable Delete until a refetch conflict is resolved.
@jaaydenh

jaaydenh commented Oct 5, 2026

Copy link
Copy Markdown
Collaborator Author

@codex review

@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: 41e4eade25

ℹ️ 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".

@jaaydenh

jaaydenh commented Oct 5, 2026

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. 👍

Reviewed commit: 41e4eade25

ℹ️ 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".

…dated-by footer

Replace the Edit button with an icon-only pen button in the top right
corner of the instructions preview, and remove the "Instructions
updated by" footer from the details panel.
@jaaydenh

jaaydenh commented Oct 5, 2026

Copy link
Copy Markdown
Collaborator Author

@codex review

@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: 71b757fedc

ℹ️ 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".

Comment thread coderd/x/chatd/project_instructions.go Resolved
Mark where the chatd architecture document needs to describe project
instructions as chat metadata and their per-turn prompt injection, for
the PR author to write.
@jaaydenh

jaaydenh commented Oct 5, 2026

Copy link
Copy Markdown
Collaborator Author

@codex review

@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: b26179e767

ℹ️ 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".


TODO (#27079): messages can now carry a `workspace-file-reference` part (path, name, size, media type, workspace ID) for files uploaded into the chat's workspace. It is metadata only: no file link is written, coderd validates that the path is scoped to the chat's upload directory and that the workspace ID matches the chat's current binding, and prompt conversion renders the reference as text (`[workspace file: <name> (<size>) at <path>]`) so the bytes never reach the model. Describe this here.

TODO (#30349): projects can now hold instructions (`chat_project_instructions`, at most one row per project, organization-scoped, with `updated_by`). They are metadata reached through the project binding, and subagent chats, which carry no `project_id`, use their root chat's project. Describe this here.

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 Resolve the architecture TODOs before merging

Replace this new #30349 TODO and the related prompt-assembly TODO later in the document with the owner's completed architecture updates, or remove them if that documentation is deferred. The repository's review-specific guardrail explicitly requires flagging TODOs added to this architecture document, and leaving both notes in the final change keeps the metadata and per-turn prompt behavior knowingly undocumented.

AGENTS.md reference: AGENTS.md:L74-L75

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Acknowledged. Per AGENTS.md, an agent leaves these TODOs and the human PR author writes the actual architecture updates. I'm leaving this thread open as the author's action item: replace both #30349 TODOs with the real description before merge.

@jaaydenh

jaaydenh commented Oct 5, 2026

Copy link
Copy Markdown
Collaborator Author

Split into four stacked PRs to keep each under 1000 lines, in merge order: #30367 (storage and prompt injection), #30368 (API), #30369 (editor dialog), #30370 (Details panel). The final code matches this PR's head b26179e767, except that the dialog-only tests moved into ProjectInstructionsDialog.test.tsx. The open ARCHITECTURE.md TODO thread carries over to #30367. Closing this PR in favor of the stack.

@jaaydenh jaaydenh closed this Oct 5, 2026
@github-actions github-actions Bot locked and limited conversation to collaborators Oct 5, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant