tailchat/docs/superpowers/specs/2026-07-19-tailchat-agents-md-design.md

Tailchat Root AGENTS.md Design

Date: 2026-07-19 Status: Approved

Objective

Create a root-level AGENTS.md that is automatically useful to coding agents working anywhere in the Tailchat repository. The document will act as a compact project constitution: it will explain the durable architecture, define change boundaries and non-negotiable invariants, map changes to proportionate verification, and encode the repository's delivery conventions.

The target length is approximately 180-220 lines. It is not a replacement for the README, deployment documentation, plugin tutorials, or human contribution guide.

The document will use concise English, matching the repository's primary public documentation and the supplied agent/PR instructions. Existing identifiers and domain terms remain unchanged.

Chosen approach

Use one root-level constitution rather than a command-only cheat sheet or a hierarchy of nested AGENTS.md files.

This approach is preferred because Tailchat is a monorepo with several distinct toolchains and cross-layer contracts. A command-only document would omit the plugin, permission, authentication, and shared-contract rules that prevent the most expensive mistakes. Nested instruction files would be more precise, but would add maintenance overhead and conflict with the requested single-file scope.

Project model to encode

Tailchat is a noIM platform: instant messaging is the collaboration core, while plugins provide first-class product extensions. Its primary architecture is a React and TypeScript frontend microkernel paired with a Moleculer backend made of independently loadable services.

The root instructions will summarize these source-of-truth boundaries:

• client/web: the browser application, routes, browser-specific integration, and MiniStar plugin host.
• client/shared: cross-platform API, socket, state, hooks, domain models, and utilities shared by web-capable clients.
• client/packages: reusable frontend design, SDK, and declaration-generation packages.
• client/web/plugins: pure frontend plugins and their manifests.
• server/services: core and OpenAPI Moleculer services.
• server/models: Typegoose persistence models.
• server/packages/sdk: the TcService abstraction, service contracts, permissions, gateway support, and runner.
• server/plugins: backend or full-stack plugins, including embedded web plugins when present.
• server/admin: a separate Vite/React and Express administration system.
• packages/types: shared published data structures.
• client/desktop and client/mobile: separate Yarn-managed shells that load the Tailchat web client and bridge native capabilities.
• client/desktop-old: legacy desktop implementation; do not treat it as the default desktop target.
• apps: non-core applications such as the CLI, GitHub app, OAuth demo, and embeddable widget.
• website: Docusaurus documentation and marketing site.

Runtime and data-flow model

The document will give agents a compact mental model of the main execution path:

1. The web entry initializes shared adapters and loads MiniStar plugins before rendering the React application.
2. UI code calls the API/socket wrappers and domain functions in client/shared.
3. The gateway maps HTTP or Socket.IO calls to registered TcService actions.
4. Services validate parameters, authenticate and authorize the caller, invoke other services through explicit contracts, and access Typegoose models.
5. Server notifications return through Socket.IO and update Redux or other shared client state.

Agents must preserve this flow instead of bypassing shared adapters, plugin registries, service actions, or server-side authorization.

Required architectural invariants

The root document will encode the following rules:

• Keep browser, Electron, and React Native capabilities in their platform layers. Put only genuinely cross-platform behavior in client/shared.
• Load and extend frontend plugins through MiniStar registration points. Do not couple core UI directly to a plugin implementation when a registry contract exists.
• Use reverse-domain plugin identifiers consistently across directory names, manifests, service names, URLs, and registration keys.
• Put pure frontend plugins under client/web/plugins; put backend or full-stack plugins under server/plugins.
• Register backend behavior through TcService. New actions declare parameter validation and remain authenticated unless a public route is deliberately reviewed and added to an authentication whitelist.
• Treat action visibility and socket exposure as security boundaries.
• The client may hide unavailable actions, but the server performs final authorization. New group permission points must stay synchronized between frontend presentation and server enforcement.
• Never expose passwords, JWT secrets, API tokens, administrator credentials, or .env contents in source, logs, tests, generated artifacts, or responses.
• Treat shared types, SDK exports, plugin registration APIs, action names, notification names, and persisted schema changes as compatibility-sensitive contracts. Check all known consumers before changing them.
• Prefer backward-compatible optional/default model changes. Add a migration when existing persisted data must be transformed.
• Update generated declarations, OpenAPI artifacts, plugin registries, translations, and generated plugin-list documentation through their owning scripts when the source contract changes. Do not hand-edit generated output into disagreement with its source.

Change workflow

The root document will instruct agents to:

1. Read the nearest source, tests, package scripts, and relevant documentation before editing.
2. Check the working tree and preserve unrelated staged, unstaged, and untracked work.
3. Follow an existing service, component, model, or plugin pattern before introducing a new abstraction.
4. Make the smallest coherent change and avoid unrelated refactors.
5. Add or update focused tests near the changed behavior.
6. Run verification proportional to the affected subsystem.
7. Report exact commands, failures, skipped checks, and environment blockers.

Repository-wide auto-fixing with pnpm lint:fix will not be the default because it can rewrite unrelated files. Agents should lint or format only the files in scope.

Toolchain boundaries

The project baseline is Node.js 18 and pnpm 8.15.8, matching the current CI and Docker build. Agents must not infer support from a newer machine-local Node or pnpm version.

The pnpm workspace covers the root packages, web client, shared client code, server, admin, plugins, public packages, apps, and website. The current desktop, mobile, and legacy desktop clients keep independent Yarn lockfiles and must use their local Yarn workflows.

Dependency edits must use the owning package manager and update the matching lockfile. Generated build directories and installed dependencies are not source changes.

Verification matrix

The final AGENTS.md will provide a concise matrix rather than prescribing a full build for every edit:

• Web or client/shared: run focused tests with pnpm --dir client/web test --runInBand <test-path> and type-check with pnpm --dir client/web check:type; run pnpm --dir client/web build for bundling, plugin-host, or dependency changes.
• Server services, models, SDK, or backend plugins: run server type checking and focused Jest tests with pnpm --dir server check:type and pnpm --dir server test --runInBand <test-path>. State whether required MongoDB, Redis, MinIO, or other integration dependencies were available.
• Cross-layer TypeScript changes: run root pnpm check:type after focused checks pass.
• Admin: run pnpm build:admin.
• Website: run pnpm --dir website build.
• Public packages and SDKs: run pnpm --filter <package-name> build and verify at least one relevant consumer when a public contract changes.
• Frontend plugins: test the affected plugin and verify its MiniStar build with pnpm --dir client/web plugins:all, plus its manifest and registration entry.
• Full-stack plugins: verify both the service/model side and embedded web plugin side; use the plugin's build:web script and regenerate registry assets when applicable.
• Deployment or packaging changes: use the owning build path, such as the root build or Docker build, only when the scope requires it.

Agents must not claim that a check passed unless it was run successfully. A failure must be separated into newly introduced behavior, a reproduced baseline failure, or an environmental blocker.

The current two Web Jest suites that fail on the ESM-only rehype-sanitize dependency are intentionally excluded from the durable root document. Their exact baseline is reported in the task handoff instead, so the constitution does not preserve a transient defect as permanent policy.

Internationalization, documentation, and generated files

User-visible core frontend and backend strings use the existing translation helpers and translation-generation workflows. Plugin strings follow their local translation pattern. Changes to commands, public configuration, deployment, plugin APIs, or public contracts must update the relevant website documentation in the same change.

The root instructions will identify generated artifacts by role and point to their owning commands, without copying large generated-file inventories or environment-variable tables.

Delivery rules

Commits and pull-request titles use Angular/Conventional Commits form: <type>(<scope>): <summary>. Types are lowercase, scopes are concise when useful, summaries are short and imperative, and titles have no trailing period.

When creating a pull request, provide only the title unless the user explicitly asks for a body.

Non-goals

The root AGENTS.md will not:

• duplicate the complete README, deployment guide, environment-variable table, plugin tutorial, or plugin catalog;
• list every service, plugin, route, action, or package;
• prescribe a full repository build for every edit;
• encode transient test failures as permanent policy;
• require unrelated cleanup, dependency upgrades, or architectural rewrites;
• create nested AGENTS.md files in this task.

Acceptance criteria

The implementation is accepted when:

• a single root AGENTS.md exists and is approximately 180-220 lines;
• it accurately describes the current project and directory ownership;
• it captures plugin, service, authorization, permission, public-contract, secret-handling, toolchain, and generated-file invariants;
• it contains concrete, scoped verification commands;
• it records the requested Conventional Commits pull-request title rules and the no-body-by-default rule;
• it does not duplicate long-form project documentation;
• git diff --check -- AGENTS.md passes and no unrelated files are changed by the implementation.