Skip to content

AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.

docs(frontend): tell coding agents user-facing copy says "workflow", not "agent" or "graph" (#15502)

John Ababseh3e3feac040a4
diff --git a/.claude/skills/pr-review/SKILL.md b/.claude/skills/pr-review/SKILL.md
index c4a2267e78..0e0ba8c977 100644
--- a/.claude/skills/pr-review/SKILL.md
+++ b/.claude/skills/pr-review/SKILL.md
@@ -50,7 +50,7 @@ gh api repos/Significant-Gravitas/AutoGPT/pulls/{N}/reviews
**Security:** input validation at boundaries, no injection (command, XSS, SQL), secrets not logged, file paths sanitized (`os.path.basename()` in error messages).
-**Code quality:** apply rules from backend/frontend CLAUDE.md files.
+**Code quality:** apply rules from backend/frontend CLAUDE.md files and root `AGENTS.md`, including its "User-facing copy" section (text a person reads says workflow, never agent or graph).
**Architecture:** DRY, single responsibility, modular functions. `Security()` vs `Depends()` for FastAPI auth. `data:` for SSE events, `: comment` for heartbeats. `transaction=True` for Redis pipelines.
diff --git a/.claude/skills/write-frontend-tests/SKILL.md b/.claude/skills/write-frontend-tests/SKILL.md
index 389de2023b..7d34bb68fd 100644
--- a/.claude/skills/write-frontend-tests/SKILL.md
+++ b/.claude/skills/write-frontend-tests/SKILL.md
@@ -141,7 +141,7 @@ describe("LibraryPage", () => {
render(<LibraryPage />);
- expect(await screen.findByText(/my agents/i)).toBeDefined();
+ expect(await screen.findByText(/all workflows/i)).toBeDefined();
});
test("shows error state on API failure", async () => {
diff --git a/AGENTS.md b/AGENTS.md
index 2f4d50be72..94106977db 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -52,6 +52,20 @@ See `/frontend/CONTRIBUTING.md` for complete patterns. Quick reference:
- Do not type hook returns, let Typescript infer as much as possible
- Never type with `any`, if not types available use `unknown`
+## User-facing copy
+
+In text people read in the product, never write "agent" or "graph" in any form ("AI agent", "agent builder", "Graph ID"). What the code calls an agent or graph is a **workflow**. The AI doing the work is **Otto** (not AutoPilot or Copilot), an **expert** or **your team** ("experts and workflows" when a sentence covers both), and Otto's helper runs are **subtasks**. Choose the noun by meaning — never search-and-replace, and never call a workflow an expert. See PR #15251.
+
+- Frontend: every string in `autogpt_platform/frontend` a person can see, `.ts` helpers and `__legacy__` components included: toasts and the `Error` messages they show, page titles, default names, `aria-label`/`title`/alt text, and messages the app sends to Otto for the user.
+- Backend: strings a person reads follow the same nouns when you add or edit them: Otto tool-response `message`/`title`/`missing_message`, approval-card schema `title`/`description`, error `detail`s, emails and notifications, and Home attention items. Fix them in the backend; never patch backend text with a frontend replace. Keep tool names, arguments and descriptions Otto reads, prompts, log lines, OpenAPI `summary`/`description`, the "Scheduled agent run" analytics title, the "You have no credits left to run an agent." error that analytics queries match, and `pipeline.py::_GENERIC_NAMES`.
+- Change copy only, because renaming breaks things. Keep agent, graph, copilot and autopilot in every identifier and every value code compares or stores, e.g. routes (`/library/agents/[id]`), API fields and values (`"agent_run"`), tool names and arguments even inside messages to Otto (`find_library_agent`, `agent_id`), `TOOL_AGENT = "Agent"`, `data-testid`/`data-id`, and analytics, storage and flag keys. A value that is both shown and sent as a tag (ErrorCard `context`) is copy. Never hand-edit generated files (`src/app/api/__generated__`, `openapi.json`, the approval-card `realCards.json`/`referenceCards.json`); regenerate them instead.
+- A label built from a key or tool name that would show agent or graph gets an entry in a key-to-label map (e.g. `TOOL_DISPLAY_NAMES`); never rename the key or show it humanized (`humanizeKey` turns `agent_ids` into "Agent ids").
+- Before rewording, search for a distinctive fragment of the string from the repo root (`git grep -inF '<fragment>' -- autogpt_platform`). If code or SQL matches it, reword only outside the matched part and keep the matcher, since saved messages keep the old text (e.g. the `**Here are my answers:**` frame `experts/onboarding.py` reads from stored chats). Update tests and Playwright page objects asserting the string in the same PR; never pin old copy in a new test or story.
+- Do not take wording from identifiers, your task or PR text. Recheck any string you move into a helper, rewrite in a new conditional, copy from a neighbouring message or carry through a merge conflict.
+- Leave as is: the `agent.json` file name, the "Your agents have moved" notice, hidden search keywords (`GlobalSearchModal/navigation.tsx`), admin and dev pages (`copilot/styleguide`), anything users name or type, third-party names (AgentMail, GitHub Copilot, Microsoft 365 Copilot, including a bare "Copilot" that means Microsoft's), titles of third-party pages we link to (the n8n examples in `ExternalWorkflowTab`) and other senses (user-agent, knowledge graph, charts).
+- Awaiting a product decision, so leave them as they appear, without a display map, and do not copy their wording: SEO metadata and og:image alt text (`SITE_DESCRIPTION`, `public/manifest.webmanifest`, the marketplace home and tour pages), `TourHero`, `SignupMarketingPanel`, the `plans.ts` pricing bullets, block names, categories and descriptions however the builder shows them ("Agent Input"), and the `humanizePermission` API-key labels. New text added beside any of these exceptions follows the rule.
+- Out of scope: `classic/`, `docs/`, code comments, test names, and commit and PR text.
+
## Testing
- Backend: `poetry run test` (runs pytest with a docker based postgres + prisma).
diff --git a/autogpt_platform/AGENTS.md b/autogpt_platform/AGENTS.md
index e24876172b..b380d3fdd2 100644
--- a/autogpt_platform/AGENTS.md
+++ b/autogpt_platform/AGENTS.md
@@ -17,7 +17,7 @@ AutoGPT Platform is a monorepo containing:
## Key Concepts
-1. **Agent Graphs**: Workflow definitions stored as JSON, executed by the backend
+1. **Agent Graphs**: Workflow definitions stored as JSON, executed by the backend; identifiers, routes and API fields say agent or graph; any text a person reads says workflow (see "User-facing copy" in the root `AGENTS.md`)
2. **Blocks**: Reusable components in `backend/backend/blocks/` that perform specific tasks
3. **Integrations**: OAuth and API connections stored per user
4. **Store**: Marketplace for sharing agent templates
diff --git a/autogpt_platform/frontend/CONTRIBUTING.md b/autogpt_platform/frontend/CONTRIBUTING.md
index 532ace6672..4805c08a4a 100644
--- a/autogpt_platform/frontend/CONTRIBUTING.md
+++ b/autogpt_platform/frontend/CONTRIBUTING.md
@@ -804,7 +804,7 @@ import LibraryPage from "../page";
test("renders agent list", async () => {
server.use(getGetV2ListLibraryAgentsMockHandler200());
render(<LibraryPage />);
- expect(await screen.findByText("My Agents")).toBeDefined();
+ expect(await screen.findByText("All Workflows")).toBeDefined();
});
```
diff --git a/autogpt_platform/frontend/TESTING.md b/autogpt_platform/frontend/TESTING.md
index 72a92b17e5..2817627c39 100644
--- a/autogpt_platform/frontend/TESTING.md
+++ b/autogpt_platform/frontend/TESTING.md
@@ -60,7 +60,7 @@ describe("LibraryPage", () => {
render(<LibraryPage />);
- expect(await screen.findByText("My Agents")).toBeDefined();
+ expect(await screen.findByText("All Workflows")).toBeDefined();
});
test("shows error state on API failure", async () => {
diff --git a/autogpt_platform/frontend/src/tests/AGENTS.md b/autogpt_platform/frontend/src/tests/AGENTS.md
index 0c209ac411..ff7b7d653d 100644
--- a/autogpt_platform/frontend/src/tests/AGENTS.md
+++ b/autogpt_platform/frontend/src/tests/AGENTS.md
@@ -88,7 +88,7 @@ test("shows error when submission fails", async () => {
server.use(getDeleteV2DeleteStoreSubmissionMockHandler422());
render(<MarketplacePage />);
- await screen.findByText("Featured Agents");
+ await screen.findByText("All AI Workflows");
// ... assert error UI
});
```