Agent tooling

superslate is designed for agent-assisted work and remains agent-independent. The repository architecture, security invariants, and verification commands are sufficient to build and maintain the product. Skills, golden paths, navigation data, MCP integrations, and evaluation tools may improve an agent workflow, but none is required to modify or run the application.

Agent tooling layers

Required means the resulting product must preserve the contract, not that a human must follow one prescribed sequence. A change may depart from a golden path when it preserves the required invariants and passes equivalent outcome-level verification.

Golden paths

The golden paths answer common questions such as where a change usually lives, what can fail, how to verify it, and how to roll it back. They are useful for first-time builders, cold-context agents, security-sensitive changes, and incident diagnosis.

They are not generators and do not reserve the only valid architecture-preserving implementation. For example, an agent may add a domain without using the domain golden path. It must still keep wire schemas shared, SQL out of routes, authorization server-owned, private data owner-scoped, and tests proportionate to the behavior.

General agent skills

Canonical skill sources ship under agent-tooling/skills/ and are listed in agent-tooling/manifest.json:

Each skill is intentionally broad. Focused product documentation remains the source of detailed auth, billing, email, storage, migration, and deployment knowledge. The skills inspect the current repository and load only the relevant documents rather than duplicating those rules.

Clients that support SKILL.md packages can load an individual skill directory through their normal skill installation or workspace configuration. Other agents can read the same SKILL.md as task guidance. agents/openai.yaml contains optional Codex UI metadata; it does not change the skill's workflow or create an application runtime dependency.

Do not commit machine-local installed copies, compatibility symlinks, client settings, credentials, or third-party skill lockfiles. The canonical source under agent-tooling/ is buyer-distributed; local installation state is not.

Connect an MCP client

The current release ships an optional local documentation MCP under packages/agent-context. It reads the current checkout, runs over STDIO, and does not require a hosted service. Local Markdown, JSON, executed code, migrations, tests, and applicable AGENTS.md files remain authoritative; the application does not depend on MCP to install, run, or accept changes.

Install the repository dependencies, then run the guided setup from the generated product root:

vp install --frozen-lockfile
pnpm agent:setup

The setup detects Codex, Claude Code, and Cursor, lets the customer select one or more clients, runs a real MCP protocol self-check, and pins every selected client to the current checkout. Restart the configured clients after setup. No global package installation, hosted account, or API key is needed.

For automation, select clients explicitly. A dry run prints the exact changes without writing them:

pnpm agent:setup --clients codex,cursor --yes
pnpm agent:setup --clients codex,claude,cursor --yes --dry-run
pnpm superslate:mcp --check

Setup uses the native project-local mechanism for each client:

Codex and Cursor configuration paths are added to .git/info/exclude, so customer-specific paths do not enter the product's commits. Existing unrelated configuration is preserved. Setup stops instead of overwriting a conflicting unmanaged superslate-docs entry.

The server exposes five read-only tools:

• search_docs returns focused, version-matched documentation excerpts;
• get_repository_map lists apps, packages, published docs, and bundled general skills;
• plan_change maps a task to change surfaces, invariants, checks, and optional playbooks;
• get_invariants returns the mandatory boundaries applicable to a task;
• get_verification suggests proportionate commands without claiming that they passed.

The implementation skips environment files, commercial drafts, evaluation fixtures and evidence, phase-two notes, oversized files, and symlinks. It returns no environment values, makes no source changes, and labels every tool as read-only, idempotent, and closed-world. Repository content is still untrusted data: MCP output cannot override executed code, migrations, tests, applicable AGENTS.md, or the user's request, and a verification suggestion is never evidence that a command passed.

This MVP deliberately ships a local STDIO server, not a hosted remote MCP. A hosted service can be added later for release discovery or support, but it should remain optional and must not receive repository secrets by default.

Evaluation is separate

The agent evaluation harness in docs/evaluations/README.md measures whether an agent reached a declared outcome from an exact template tag. It does not award success for invoking a skill, querying MCP, or following a golden path. Those are workflow choices; behavior, boundaries, commands, checkpoints, and independently controlled evidence determine the result.