Agent tooling

This foundation 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 read-only context server 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 agent: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 agent-docs entry.

The server exposes six read-only tools:

• search_docs returns focused, version-matched documentation excerpts;
• search_implementation returns ranked source, migration, test, configuration, and deployment evidence with repository-relative file and line locations;
• get_repository_map lists apps, packages, published docs, and bundled general skills;
• plan_change maps a task through the machine-readable navigation contract and returns matched rules with reasons, current implementation evidence, applicable instruction files, change surfaces, invariants, prohibitions, 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 planner reads docs/agent-navigation-contract.json from the current checkout, discovers scoped AGENTS.md files above matched change surfaces, and searches those surfaces for current evidence. Unmatched tasks return base guidance and repository-wide evidence without inventing product surfaces. Implementation search is bounded to buyer-distributed source roots and skips seller surfaces, environment files, dependencies, generated output, locks, oversized files, and symlinks. Documentation search also skips commercial drafts and private evaluation material. The server 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 behavior, 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.