AGENTS.md — AI Agent Contract

Purpose: the repository-wide operating contract for AI agents and automated contributors. Read this before modifying any file. More specific scoped instructions, when present, refine this contract for their subtree.

What this repository is

agent-toolkit is the capability distribution layer for reusable AI-agent skills, personas, loops, MCP templates, products/packs, target profiles, the native V CLI, and Agent Toolkit Desktop. Changes can affect multiple downstream coding assistants and packaging channels.

Operate precisely: use canonical sources, preserve public/vendor-neutral boundaries, cite evidence, and validate before finalizing.

Canonical document map

Use the narrowest current source of truth instead of old issue prose or historical comments.

Historical ADRs and GitHub issues are evidence, not automatic implementation authority. Reconcile them with current code and governing contracts before acting.

Instruction precedence inside this project

Repository work should follow, in order:

1. explicit current task requirements;
2. this AGENTS.md and any scoped descendant instructions;
3. current ADRs and canonical domain contracts;
4. current product/UX/design contracts;
5. current verified code/tests/runtime behavior;
6. GitHub issue implementation details;
7. historical plans/comments.

This project ordering does not override system/developer/runtime instructions from the agent platform itself.

Global invariants

Always

• Use English for repository content, commits, issues, and PR descriptions.
• Keep secrets, credentials, tokens, private-company content, and private customer data out of this public repository.
• Prefer canonical catalogs/manifests/core operations over duplicated hardcoded rosters.
• Cite the file/contract behind repository conventions when making architectural claims.
• Inspect current code and generated sources before claiming compatibility or completion.
• Work in focused branches/PRs for implementation unless the maintainer explicitly requests another workflow.
• Preserve user-owned files and report partial failure honestly.

Never

• Manufacture plausible production state, progress, health, receipts, provenance, compatibility, costs, activity, or Git history.
• Hand-edit generated catalogs/manifests when a generator owns them.
• Commit credentials or real secret values to MCP templates/examples.
• Claim tool compatibility without evidence from metadata, tests, or explicit supported behavior.
• Add private-organization-specific content to first-party public capabilities.
• Add third-party npm/GitHub/URL packs to distributions/products.yaml or generated plugin surfaces; follow the third-party boundary in docs/CONCEPTS.md.
• Bypass branch protection or weaken validation merely to land a change.

Unknown, unavailable, empty, and unverified are valid states. Fabricated-but-plausible is not.

Repository ownership model

Key source areas:

• skills/ — first-party reusable capability sources (SKILL.md)
• agents/ — tool-agnostic personas (AGENT.md)
• loops/ — loop templates (loop.yaml)
• mcp/ — provider registry/templates
• profiles/ — target-specific adapters/overlays
• packs/ — solution/workflow packs
• capabilities/ — declarative capability registries (targets, skills, hooks); canonical source for supported-target and capability truth
• distributions/ — product compiler input
• plugins/ — generated distribution surfaces; do not hand-edit unless the owning contract explicitly says otherwise
• catalogs/ — generated discovery catalogs
• schemas/ — validation schemas (skills, agents, loops, targets, products)
• modules/agent_toolkit_core/ — shared core/domain implementation
• modules/agent_toolkit_server/ — typed HTTP API over the canonical V domain
• cmd/agent-toolkit/ — native V CLI entrypoint
• apps/desktop/ — shipping Electron + React Desktop, assets, tests, and packaging
• packages/ — PyPI/npm launcher trampolines
• tests/ — parity, security, and adapter test suites
• docs/ — human-facing contracts, guides, ADRs
• scripts/ — validation/generation automation

Generated files

These are generated and must not be manually edited:

• catalogs/skill-catalog.yaml
• catalogs/agent-catalog.yaml
• catalogs/loop-catalog.yaml
• catalogs/skills-layout.json

Regenerate/check with:

./scripts/generate-catalogs.vsh
./scripts/generate-catalogs.vsh --check

If another file is generated, follow its owning ADR/script rather than editing around the generator.

Skills

Before adding a skill:

1. search catalogs/skill-catalog.yaml and existing first-party skills;
2. read docs/UPSTREAM_VS_FIRST_PARTY.md;
3. prefer enhancing an existing first-party capability over vendoring a duplicate;
4. follow docs/SKILL_INTEGRATION_CHECKLIST.md.

A skill lives at skills/<domain>/<skill>/SKILL.md. Required and optional frontmatter (name, description, metadata, domain, tools, requires, triggers) is validated against schemas/skill-md-frontmatter.schema.json. Every distributable SKILL.md must declare origin: {type: first-party|upstream}: scripts/validate-upstream.py enforces this for every SKILL.md (gate 2, see docs/TRUST.md), although the schema keeps origin optional for backwards compatibility.

Validate skill changes with at least:

./scripts/validate-skills.vsh
./scripts/generate-catalogs.vsh --check
AGENT_TOOLKIT_ROOT="$PWD" ./build/agent-toolkit build --check

Use additional checks required by the integration checklist.

Agent personas

Personas live under agents/<name>/AGENT.md. Keep directory/name/frontmatter aligned and follow docs/HOW_TO_ADD_AGENT.md.

Validate with:

./scripts/validate-agents.vsh
./scripts/generate-catalogs.vsh --check

Do not confuse persona AGENT.md files with this repository-wide AGENTS.md contract.

Loops

Loop definitions live in loops/<name>/loop.yaml. STATE.md and report.md are runtime artifacts and must not become committed template state unless a current contract explicitly says otherwise.

Follow docs/HOW_TO_CREATE_LOOP.md and validate with:

./scripts/validate-loops.vsh
./scripts/generate-catalogs.vsh --check

Never weaken L1/L2/L3 mutation boundaries, allow/deny semantics, budgets, or exit conditions casually.

Profiles, MCP, products, and packs

Profiles adapt canonical Agent Toolkit capabilities to supported coding tools. Keep target-specific behavior in the appropriate profile/emitter layer rather than duplicating source capabilities. Profile layout and authoring follow docs/PROFILES.md.

MCP templates use placeholders only. Never commit real credentials. Separate provider/catalog support from user configuration and runtime health.

Products/packs must follow current compiler and concept contracts. Treat generated plugin manifests as outputs, not primary authoring surfaces.

Desktop product work

Before changing Desktop behavior, read at least:

• docs/desktop/PRODUCT_VISION.md
• docs/desktop/UX_ARCHITECTURE.md
• docs/desktop/DESIGN.md

Also read:

• USER_JOURNEYS.md when changing a workflow;
• workflows.yaml when exposing/removing capabilities;
• VISUAL_QA.md for any visual change;
• The git history and ADRs for historical architecture context; current behavior is defined by source, tests, and the workflow ledger.

Desktop invariants

• Keep the production application Electron + React over agent-toolkit serve (ADR-033); keep domain operations in canonical V core/server APIs.
• Engine/shared typed domain APIs remain authoritative. Do not implement Agent Toolkit business logic by shelling out to the Agent Toolkit CLI and parsing output.
• Keep catalog truth, user configuration, runtime state, and evidence/provenance distinct.
• Never invent operational activity to make the World look alive.
• An offline Person remains in the People roster and is absent from the World; only a real live session, job, or run can create runtime character presence.
• Keep workspace, runtime, bundled-data, cache/config, and project path authorities distinct.
• Preserve workspace containment and secret masking before values reach rendering/logging/export.
• Drawing and hit-testing must share geometry; revalidate integer selections after filtering, refresh, and workspace switch before indexing.
• Event precedence is modal → active text field → terminal → focused widget → panel-local shortcuts → global shortcuts.
• Do not require sibling repositories, source-checkout cwd, V toolchain, or interactive-shell PATH for normal packaged first run.
• Do not treat concept images as runtime truth or literal feature requirements.

Desktop visual changes

The visual identity is defined in docs/desktop/DESIGN.md. Major visual work must follow the evidence loop in VISUAL_QA.md:

build → run → navigate → capture → open the screenshot → critique → fix → recapture

Golden comparison proves regression stability, not visual quality. Do not update a golden solely to make CI pass.

Validation by change type

Use the smallest matrix that honestly covers the changed surface, plus any checks required by the touched contract/CI.

Repository-wide primary validation currently includes:

./scripts/validate-skills.vsh
./scripts/validate-agents.vsh
./scripts/validate-loops.vsh
./scripts/generate-catalogs.vsh --check
./make.vsh test
./make.vsh build-cli
AGENT_TOOLKIT_ROOT="$PWD" ./build/agent-toolkit build --check

Check .github/workflows/ before assuming this list exactly matches current CI.

Adapter-only validation when those launchers change:

AGENT_TOOLKIT_ROOT="$PWD" uv run --project packages/pypi/agent-toolkit-cli --directory . pytest -c tests/pytest.ini tests/ -v
npm test --prefix packages/npm/agent-toolkit-cli

Follow .v-version and docs/HOW_TO_DEVELOP_V.md for V-specific constraints.

Git and PR discipline

• Start focused implementation from fresh canonical main unless intentionally targeting another base.
• Keep PRs coherent and reviewable; do not recreate monolithic salvage branches.
• Do not push implementation directly to protected main unless the maintainer explicitly requests/directs that exception.
• Wait for actual required CI before declaring a PR complete.
• Investigate reproducible failures instead of labeling them infrastructure casually.
• Merge only when required CI and review obligations are satisfied.
• Do not publish releases/packages without explicit authorization.

For major Desktop PRs, include user impact, architecture/truth implications, validation, screenshot evidence, and known limitations.

Ecosystem boundary

Agent Toolkit must remain usable on its own. agentic-workstation, agentic-harness, My AI Workspace, and related repositories may integrate through explicit contracts, but they are not mandatory runtime dependencies for Agent Toolkit Desktop or the core CLI.

Cross-repo references:

• agentic-workstation AGENTS.md
• agentic-harness AGENTS.md

Completion rule

Do not equate issue closure, generated output, passing tests, or green goldens with product completion.

Before reporting a change complete, verify the actual affected behavior, run the relevant validation, state what was not verified, and leave the repository's canonical documents/backlog consistent with reality.