From fda6b1e3487a45c0bf2d7bd63c627365f709e54a Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sat, 21 Feb 2026 16:31:21 +0000 Subject: [PATCH] Add AGENTS.md and symlink to agent configs - Create AGENTS.md with instructions for TDD, Storybook, and documentation. - Symlink AGENTS.md to CLAUDE.md, GEMINI.md, .cursorrules, .windsurfrules, .github/copilot-instructions.md. - Update README.md to reference AGENTS.md. Co-authored-by: mtthwcmpbll <226487+mtthwcmpbll@users.noreply.github.com> --- .cursorrules | 1 + .github/copilot-instructions.md | 1 + .windsurfrules | 1 + AGENTS.md | 48 +++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + GEMINI.md | 1 + README.md | 4 +++ 7 files changed, 57 insertions(+) create mode 120000 .cursorrules create mode 120000 .github/copilot-instructions.md create mode 120000 .windsurfrules create mode 100644 AGENTS.md create mode 120000 CLAUDE.md create mode 120000 GEMINI.md diff --git a/.cursorrules b/.cursorrules new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/.cursorrules @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 120000 index 0000000..be77ac8 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1 @@ +../AGENTS.md \ No newline at end of file diff --git a/.windsurfrules b/.windsurfrules new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/.windsurfrules @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..2540536 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,48 @@ +# Agentic Workflow Instructions + +This document outlines the standard operating procedures for building features and contributing to the Turtorial codebase. + +## 1. Test-Driven Development (TDD) + +**Always write failing tests first.** + +* **Backend (Java/Spring Boot):** + * Use JUnit 5 for unit and integration tests. + * Ensure new services and components are tested in isolation where possible. + * Run tests via `./mvnw test`. + +* **Frontend (React/TypeScript):** + * Use Vitest for unit testing logic and components. + * Use Playwright for end-to-end and component testing. + * Ensure new components have accompanying tests. + * Run tests via `npm run test` (Vitest) or `npm run e2e` (Playwright). + +## 2. Frontend Component Architecture + +**Keep components independent, decoupled, and testable.** + +* **Storybook:** Develop and test UI components in isolation using Storybook (`npm run storybook`). +* **Decoupling:** Avoid tight coupling between components. Use props and composition to maximize reusability. +* **State Management:** Keep state local where possible, or lift it up responsibly. Avoid global state pollution. + +## 3. Feature Independence & Decoupling + +* **Modularity:** Design features to be modular and self-contained. +* **Separation of Concerns:** Clearly separate business logic from presentation and data access. +* **Interfaces:** Use interfaces to define contracts between modules, facilitating easier testing and refactoring. + +## 4. Documentation & Lesson Updates + +**When adding a new feature, you MUST document it for users.** + +* **Target Audience:** Lesson authors (users writing tutorials). +* **Location:** The default lesson included on the classpath (`src/main/resources/lessons/introduction`). +* **Requirement:** + * Add a new step or section to the default lesson explaining how the feature works and how to use it. + * Provide clear examples and code snippets. + * Ensure the documentation is visible immediately when a user starts the application. +* **Why:** This ensures that new capabilities are immediately discoverable and usable by the community. + +## 5. Source of Truth + +This `AGENTS.md` file is the single source of truth for agent instructions. It is symlinked to various agent-specific configuration files (e.g., `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, etc.) to ensure consistency across different AI assistants. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/GEMINI.md b/GEMINI.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/README.md b/README.md index 0dfaf23..5664832 100644 --- a/README.md +++ b/README.md @@ -131,6 +131,10 @@ Open your browser to `http://localhost:8080` to see your lesson in action! We love contributions! If you're a developer looking to improve the platform itself (the Java backend or React frontend), check out [BUILDING.md](BUILDING.md) for technical build instructions. +## 🤖 Agentic Workflow + +If you are an AI agent or using AI tools to contribute to this project, please refer to [AGENTS.md](AGENTS.md) for specific instructions and guidelines. This file serves as the source of truth for all agentic workflows. + ## 📄 License [MIT License](LICENSE)