Skip to content

AGENTS.md

Latest commit

 

History

History
133 lines (96 loc) · 7.67 KB

AGENTS.md

File metadata and controls

133 lines (96 loc) · 7.67 KB
Raw

Using Vite+, the Unified Toolchain for the Web

This project is using Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called vp. Vite+ is distinct from Vite, but it invokes Vite through vp dev and vp build.

Vite+ Workflow

vp is a global binary that handles the full development lifecycle. Run vp help to print a list of commands and vp <command> --help for information about a specific command.

Start

  • create - Create a new project from a template
  • migrate - Migrate an existing project to Vite+
  • config - Configure hooks and agent integration
  • staged - Run linters on staged files
  • install (i) - Install dependencies
  • env - Manage Node.js versions

Develop

  • dev - Run the development server
  • check - Run format, lint, and TypeScript type checks
  • lint - Lint code
  • fmt - Format code
  • test - Run tests

Execute

  • run - Run monorepo tasks
  • exec - Execute a command from local node_modules/.bin
  • dlx - Execute a package binary without installing it as a dependency
  • cache - Manage the task cache

Build

  • build - Build for production
  • pack - Build libraries
  • preview - Preview production build

Manage Dependencies

Vite+ automatically detects and wraps the underlying package manager such as pnpm, npm, or Yarn through the packageManager field in package.json or package manager-specific lockfiles.

  • add - Add packages to dependencies
  • remove (rm, un, uninstall) - Remove packages from dependencies
  • update (up) - Update packages to latest versions
  • dedupe - Deduplicate dependencies
  • outdated - Check for outdated packages
  • list (ls) - List installed packages
  • why (explain) - Show why a package is installed
  • info (view, show) - View package information from the registry
  • link (ln) / unlink - Manage local package links
  • pm - Forward a command to the package manager

Maintain

  • upgrade - Update vp itself to the latest version

These commands map to their corresponding tools. For example, vp dev --port 3000 runs Vite's dev server and works the same as Vite. vp test runs JavaScript tests through the bundled Vitest. The version of all tools can be checked using vp --version. This is useful when researching documentation, features, and bugs.

Common Pitfalls

  • Using the package manager directly: Do not use pnpm, npm, or Yarn directly. Vite+ can handle all package manager operations.
  • Always use Vite commands to run tools: Don't attempt to run vp vitest or vp oxlint. They do not exist. Use vp test and vp lint instead.
  • Running scripts: Vite+ built-in commands (vp dev, vp build, vp test, etc.) always run the Vite+ built-in tool, not any package.json script of the same name. To run a custom script that shares a name with a built-in command, use vp run <script>. For example, if you have a custom dev script that runs multiple services concurrently, run it with vp run dev, not vp dev (which always starts Vite's dev server).
  • Do not install Vitest, Oxlint, Oxfmt, or tsdown directly: Vite+ wraps these tools. They must not be installed directly. You cannot upgrade these tools by installing their latest versions. Always use Vite+ commands.
  • Use Vite+ wrappers for one-off binaries: Use vp dlx instead of package-manager-specific dlx/npx commands.
  • Import JavaScript modules from vite-plus: Instead of importing from vite or vitest, all modules should be imported from the project's vite-plus dependency. For example, import { defineConfig } from 'vite-plus'; or import { expect, test, vi } from 'vite-plus/test';. You must not install vitest to import test utilities.
  • Type-Aware Linting: There is no need to install oxlint-tsgolint, vp lint --type-aware works out of the box.

CI Integration

For GitHub Actions, consider using voidzero-dev/setup-vp to replace separate actions/setup-node, package-manager setup, cache, and install steps with a single action.

- uses: voidzero-dev/setup-vp@v1
  with:
    cache: true
- run: vp check
- run: vp test

Review Checklist for Agents

  • Run vp install after pulling remote changes and before getting started.
  • Run vp check and vp test to validate changes.

Agent Documentation Model

  • AGENTS.md is the stable policy entrypoint and should stay concise.
  • Operational details belong in the hierarchical docs under docs/developers/agents/.
  • Product/spec source of truth belongs under docs/developers/specs/ and shared docs under docs/.
  • Use progressive discovery: start from docs/developers/agents/index.md, inspect folder names, and read only matching active files.
  • For implementation work, read docs/developers/specs/index.md and then only the relevant spec/status files.
  • Discover structure from docs/developers/agents/ at runtime instead of maintaining exhaustive folder lists here.
  • Keep active context lean: resolved incidents/workarounds should be archived or removed.
  • Run the unified weekly maintenance window that includes cleanup and consistency review, then update maintenance artifacts.
  • If docs/developers/agents/maintenance/consistency-report.md is older than 7 days, ask the user whether to run the weekly consistency review now; if approved, run it and update maintenance artifacts.
  • Enforce filename-title alignment for markdown docs you add or rename under docs/developers/agents/**: the filename words must match the H1 title wording at least semantically (ignoring case, spacing, and dash/underscore differences). Prefer renaming files over drifting titles.
  • Allowed exceptions: folder landing pages (index.md), compatibility landing pages (README.md), and this root policy file (AGENTS.md).

Public Publishing Boundary

  • Website content is sourced from docs/**.
  • Run website publish from apps/website/scripts/publish-website.mjs, which reads markdown from docs/** and emits static website output under apps/website/dist/**.
  • Preserve route mapping from docs paths to website paths (for example, docs/developers/index.md -> /developers/) and avoid one-off URL aliases.
  • Use apps/website/site/ as the processed web root for hosted website files.
  • Keep path-preserving placement inside apps/website/site/** (for example, CSS under apps/website/site/css/**, icons under apps/website/site/icons/**).
  • Keep transformation logic generic and loop-based with path-preserving behavior.

Pre-Publish Compatibility Rule

  • Current phase is pre-publish iteration; default to no backward-compatibility paths, redirects, or legacy aliases.
  • If backward compatibility is proposed, pause and ask whether to remove or override the no-backward-compatibility rule before implementing.

Hidden Memory Policy

  • Default behavior: do not read from or write to hidden agent memory systems.
  • If persistence is needed, store context in repository files so it is reviewable and shared.
  • Before writing long-lived notes, ask for explicit approval from the user.
  • At task end, summarize what was documented in repo files.

Mandatory Agent Preflight

Run this checklist before any substantial work:

  • Confirm hidden memory is not used for persistence. Use repo files under docs/developers/agents/ for durable notes.
  • Read docs/developers/agents/index.md first, then docs/developers/agents/policy/memory-and-discovery.md and relevant policy/context files.
  • On Windows, prefer Bash when available, but verify optional tools exist before use and fall back safely when missing.

If a step is missed, stop and correct course before continuing.