chore: add AGENTS.md documentation for AI agent development guidance

AGENTS.md

@@ -0,0 +1,56 @@
+# AI Agent Development Guide
+
+This document provides AI-agent-specific guidance for working with the vite-plugin-react monorepo. For comprehensive documentation, see:
+
+- **[README.md](README.md)** - Repository overview and package links
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Setup, testing, debugging, and contribution guidelines
+
+## Quick Reference for AI Agents
+
+### Repository Navigation
+
+This monorepo contains multiple packages (see [README.md](README.md#packages) for details):
+
+- `packages/plugin-react/` - Main React plugin with Babel
+- `packages/plugin-react-swc/` - SWC-based React plugin
+- `packages/plugin-rsc/` - React Server Components ([AI guidance](packages/plugin-rsc/AGENTS.md))
+- `packages/plugin-react-oxc/` - Deprecated (merged with plugin-react)
+
+### Essential Setup Commands
+
+```bash
+pnpm install && pnpm build   # Initial setup (see CONTRIBUTING.md for details)
+pnpm dev                     # Watch mode development
+pnpm test                    # Run all tests
+```
+
+### AI-Specific Workflow Tips
+
+1. **Start with existing documentation** - Always read package-specific READMEs before making changes
+2. **Use playground tests** - Each package has `playground/` examples for testing changes
+3. **Focus on minimal changes** - Prefer surgical edits over large refactors
+4. **Test early and often** - Run `pnpm test` after each logical change
+5. **Follow existing patterns** - Study similar implementations in the codebase first
+
+### Common Development Tasks
+
+#### Making Changes to Plugin Logic
+
+1. Read the package README and existing code patterns
+2. Use `pnpm dev` for watch mode during development
+3. Test changes with relevant playground examples
+4. Run tests: `pnpm test-serve` and `pnpm test-build`
+
+#### Debugging Build Issues
+
+1. Check individual package builds with `pnpm --filter ./packages/<name> build`
+2. Use playground tests to isolate problems
+3. See [CONTRIBUTING.md debugging section](CONTRIBUTING.md#debugging) for detailed guidance
+
+#### Adding Tests
+
+1. Follow patterns in existing `__tests__` directories
+2. Use playground integration tests for feature verification
+3. See [CONTRIBUTING.md testing section](CONTRIBUTING.md#running-tests) for comprehensive testing guide
+
+For detailed development setup, testing procedures, and contribution guidelines, refer to [CONTRIBUTING.md](CONTRIBUTING.md).

packages/plugin-rsc/AGENTS.md

@@ -0,0 +1,54 @@
+# AI Agent Guide for @vitejs/plugin-rsc
+
+This document provides AI-agent-specific guidance for the React Server Components (RSC) plugin. For comprehensive documentation, see:
+
+- **[README.md](README.md)** - Plugin overview, concepts, and examples
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Development setup and testing guidelines
+
+## Quick Reference for AI Agents
+
+### Key Plugin Concepts
+
+The RSC plugin creates three environments (see [README.md Basic Concepts](README.md#basic-concepts) for diagrams):
+
+- **rsc** - Server component rendering
+- **ssr** - Server-side rendering
+- **client** - Browser hydration
+
+### Essential Commands
+
+```bash
+pnpm -C packages/plugin-rsc dev       # Watch mode development
+pnpm -C packages/plugin-rsc test-e2e  # Run e2e tests
+pnpm -C packages/plugin-rsc test-e2e basic  # Test specific example
+```
+
+### AI-Specific Development Tips
+
+#### Making RSC Changes
+
+1. **Start with `examples/starter/`** - Best learning resource for understanding RSC flows
+2. **Use `examples/basic/` for testing** - Comprehensive test suite with routing
+3. **Test across all environments** - Verify rsc, ssr, and client functionality
+4. **Check virtual modules** - Important for RSC manifest and reference handling
+
+#### Testing Patterns
+
+- **examples/basic** - Add test cases to `src/routes/`, update routing, add tests to `e2e/basic.test.ts`
+- **setupInlineFixture** - For isolated edge cases (see `e2e/ssr-thenable.test.ts` pattern)
+
+#### Important File Locations
+
+- `src/plugin.ts` - Main plugin implementation
+- `src/environment/` - Environment-specific logic
+- `rsc/`, `ssr/`, `browser/` - Runtime APIs
+- `examples/` - Test applications and learning resources
+
+### Debugging RSC Issues
+
+1. Use `examples/starter` for basic reproduction
+2. Check environment builds in `.vite/` directory
+3. Examine RSC streams and client/server manifests
+4. Verify HMR behavior across environments
+
+For detailed setup, testing procedures, and architectural deep-dives, refer to the comprehensive documentation in [README.md](README.md) and [CONTRIBUTING.md](CONTRIBUTING.md).