diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..6e2172b23 --- /dev/null +++ b/.gitignore @@ -0,0 +1,26 @@ +# macOS-specific files +.DS_Store +.AppleDouble +.LSOverride + +# Thumbnails and system icons +._* +Icon? + +# Files that may appear in the root of a volume +.DocumentRevisions-V100 +.fseventsd +.Spotlight-V100 +.TemporaryItems +.Trashes +.VolumeIcon.icns +.com.apple.timemachine.donotpresent + +# Directories potentially created on remote AFP share +.AppleDB +.AppleDesktop +Network Trash Folder +Temporary Items + +# iCloud files +*.icloud \ No newline at end of file diff --git a/DEV_SETUP.md b/DEV_SETUP.md new file mode 100644 index 000000000..6a3790394 --- /dev/null +++ b/DEV_SETUP.md @@ -0,0 +1,177 @@ +# Development Setup + + + +## Prerequisites + + + +Before you begin, ensure you have the following installed: + +- `[LANGUAGE_RUNTIME]` version `[VERSION]` or higher +- `[PACKAGE_MANAGER]` version `[VERSION]` or higher +- `[DATABASE]` (if applicable) +- `[OTHER_DEPENDENCIES]` + +## Installation + + + +1. Clone the repository: + ```bash + git clone [YOUR_REPO_URL] + cd [YOUR_PROJECT_NAME] + ``` + +2. Install dependencies: + ```bash + cd [YOUR_PROJECT_DIRECTORY] + [YOUR_INSTALL_COMMAND] + # Example: uv sync --dev + # Example: npm install + ``` + +3. Set up environment variables (if applicable): + ```bash + cp .env.example .env + # Edit .env with your configuration + ``` + +4. Install pre-commit hooks (if applicable): + ```bash + [YOUR_PRE_COMMIT_COMMAND] + # Example: uv run pre-commit install + ``` + +## Configuration + + + +### Environment Variables + +Create a `.env` file in the project root with the following variables: + +```env +[VARIABLE_NAME_1]=[DESCRIPTION] +[VARIABLE_NAME_2]=[DESCRIPTION] +[VARIABLE_NAME_3]=[DESCRIPTION] +``` + +### [OTHER_CONFIG_FILES] + +[DESCRIPTION_OF_OTHER_CONFIGURATION] + +## Running the Project + + + +### Development Mode + +```bash +[YOUR_DEV_COMMAND] +``` + +The application will be available at `[YOUR_DEV_URL]` (e.g., http://localhost:3000). + +### Production Build + +```bash +[YOUR_BUILD_COMMAND] +[YOUR_START_COMMAND] +``` + +## Testing + + + +Run the test suite: + +```bash +[YOUR_TEST_COMMAND] +``` + +Run tests in watch mode: + +```bash +[YOUR_TEST_WATCH_COMMAND] +``` + +Run end-to-end tests: + +```bash +[YOUR_E2E_TEST_COMMAND] +``` + +## Linting and Formatting + + + +Check code style: + +```bash +[YOUR_LINT_COMMAND] +``` + +Auto-fix issues: + +```bash +[YOUR_LINT_FIX_COMMAND] +``` + +Format code: + +```bash +[YOUR_FORMAT_COMMAND] +``` + +## Troubleshooting + + + +### [COMMON_ISSUE_1] + +**Problem**: [DESCRIPTION] + +**Solution**: [STEPS_TO_RESOLVE] + +### [COMMON_ISSUE_2] + +**Problem**: [DESCRIPTION] + +**Solution**: [STEPS_TO_RESOLVE] + +## Additional Resources + + + +- [Link to architecture docs] +- [Link to API documentation] +- [Link to deployment guide] +- [Link to contributing guidelines] \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 000000000..885659601 --- /dev/null +++ b/README.md @@ -0,0 +1,312 @@ +# AI Agent Instructions Template + +A comprehensive template repository for AI coding agent workflow instructions and development guidelines. Fork this repository to give your AI coding agents context about your project's architecture, coding standards, and development workflows. + +## What's Included + +This template provides a structured approach to documenting your project for AI coding agents, including: + +- **Agent Instruction Files** (`AGENTS.md`): Comprehensive guidelines for how AI agents should work with your codebase +- **Execution Plans** (`PLANS.md`): Methodology for creating detailed, self-contained implementation plans +- **Development Setup** (`DEV_SETUP.md`): Template for onboarding documentation +- **Directory Structure**: Organized file layout for both backend and frontend projects + +## Repository Structure + +``` +. +├── README.md # This file +├── LICENSE # MIT License +├── DEV_SETUP.md # Development setup template +├── backend/ +│ ├── AGENTS.md # Backend agent instructions (template) +│ └── .agent/ +│ └── PLANS.md # Execution plan methodology +└── frontend/ + ├── AGENTS.md # Frontend agent instructions (template) + └── .agent/ + └── PLANS.md # Execution plan methodology +``` + +## Quick Start + +### 1. Fork or Clone This Repository + +```bash +git clone https://github.com/YOUR_USERNAME/agent-instructions.git +cd agent-instructions +``` + +### 2. Customize for Your Project + +Replace all template placeholders (marked with `[YOUR_*]` or ``) with your project-specific information: + +- **Project Overview**: Describe what your project does +- **Architecture**: Document your code structure and organization +- **Technology Stack**: List frameworks, libraries, and tools you use +- **Development Guidelines**: Add your team's coding standards +- **Testing Approach**: Specify testing frameworks and practices +- **Tools**: Document any MCP tools or custom utilities available + +### 3. Use with Your AI Coding Agent + +Different AI coding agents have different requirements for loading instruction files: + +#### Claude Code + +Claude Code looks for a `CLAUDE.md` file in the project root. You have two options: + +1. **Copy approach** (recommended for separate backend/frontend): + ```bash + cp backend/AGENTS.md CLAUDE.md + # or + cp frontend/AGENTS.md CLAUDE.md + ``` + +2. **Symlink approach** (if you want changes to sync): + ```bash + ln -s backend/AGENTS.md CLAUDE.md + # or + ln -s frontend/AGENTS.md CLAUDE.md + ``` + +#### Cursor + +Cursor typically uses `.cursorrules` in the project root. Create this file and import or reference your `AGENTS.md`: + +```bash +# Option 1: Copy content +cp backend/AGENTS.md .cursorrules + +# Option 2: Reference the file +echo "See backend/AGENTS.md for full guidelines" > .cursorrules +``` + +#### GitHub Copilot + +GitHub Copilot can use `.github/copilot-instructions.md`: + +```bash +mkdir -p .github +cp backend/AGENTS.md .github/copilot-instructions.md +``` + +#### Windsurf / Codeium + +Windsurf typically looks for a `.windsurfrules` file or similar. Check their documentation for the latest conventions: + +```bash +cp backend/AGENTS.md .windsurfrules +``` + +#### Other AI Agents + +For other AI coding agents, consult their documentation for where they expect instruction files. The pattern is usually: +- A file in the project root +- Named according to the agent's convention +- Containing markdown-formatted instructions + +## File Organization + +### AGENTS.md Files + +These are the main instruction files that tell AI agents: +- What your project is and does +- How code is organized (architecture) +- Which technologies and frameworks you use +- Development guidelines and best practices +- Code style and conventions +- Testing requirements +- Available tools and when to use them + +**Location**: Place one in each major part of your project (e.g., `backend/AGENTS.md`, `frontend/AGENTS.md`). + +### PLANS.md Files + +Based on the [OpenAI Cookbook's Codex Execution Plans](https://github.com/openai/openai-cookbook/blob/main/articles/codex_exec_plans.md), these files define how to create detailed, self-contained implementation plans (called "ExecPlans") for complex features. + +**Key concepts**: +- Self-contained: Each plan includes all context needed +- Living documents: Updated as work progresses +- Observable outcomes: Focus on demonstrable results +- Milestones: Break work into verifiable steps + +**Location**: In `.agent/` subdirectories alongside `AGENTS.md`. + +## Customization Guide + +### Step 1: Update Project Overview + +In each `AGENTS.md`, replace the Project Overview section: + +```markdown +# Project Overview + +[YOUR_PROJECT_DESCRIPTION] +``` + +with your actual project description, for example: + +```markdown +# Project Overview + +This is a Next.js/TypeScript web application for managing developer documentation. +It provides a wiki-style interface with full-text search, version control, and +collaborative editing features. +``` + +### Step 2: Document Your Architecture + +Replace the architecture placeholders with your actual structure: + +```markdown +# Architecture + +The project follows a standard Next.js App Router structure: +- Route handlers in `src/app/` +- React components in `src/components/` +- UI primitives in `src/components/ui/` (shadcn/ui) +- Utilities in `src/lib/` +- API routes in `src/app/api/` +``` + +### Step 3: Specify Your Tech Stack + +Update the technology stack section: + +```markdown +## Technology Stack Focus +* **Next.js 14**: App Router, Server Components, Server Actions +* **TypeScript 5**: Strict mode enabled +* **Tailwind CSS**: Utility-first styling +* **shadcn/ui**: Component library +* **PostgreSQL**: Primary database +* **Prisma**: ORM +``` + +### Step 4: Add Your Development Commands + +Replace package management placeholders: + +```markdown +## Package Management + +This project uses `npm` as the package manager. Common commands: + +- `npm install` - Install dependencies +- `npm run dev` - Start development server +- `npm test` - Run tests +- `npm run lint` - Run ESLint +- `npm run build` - Build for production +``` + +### Step 5: Customize Code Style Guidelines + +Add your specific coding standards, patterns, and examples. + +### Step 6: Document Available Tools + +If you have MCP tools or custom utilities available to the agent, document them: + +```markdown +# Tools + +- `context7` - Fetch up-to-date library documentation +- `playwright` - Browser automation for E2E tests +- Custom build scripts in `scripts/` directory +``` + +## ExecPlans (Execution Plans) + +The `PLANS.md` files define a methodology for creating detailed implementation plans. When working on complex features: + +1. **Create a new ExecPlan file** in the `.agent/` +2. **Follow the skeleton** provided in `PLANS.md` +3. **Keep it self-contained** - include all context needed +4. **Update as you go** - it's a living document +5. **Focus on outcomes** - what will work when you're done? + +See the PLANS.md files for complete guidelines. + +## Best Practices + +### For AI Agents + +1. **Read the full AGENTS.md** before starting work on a project +2. **Follow the documented patterns** - don't invent new approaches unless necessary +3. **Use ExecPlans for complex work** - helps maintain context across sessions +4. **Update documentation** when making architectural changes + +### For Developers + +1. **Keep instructions up to date** - outdated docs confuse agents +2. **Be specific** - vague guidelines lead to inconsistent code +3. **Include examples** - show the preferred patterns +4. **Document exceptions** - explain when rules don't apply +5. **Version your instructions** - commit changes to git + +## Credits + +- **PLANS.md methodology**: Based on [Codex Execution Plans](https://github.com/openai/openai-cookbook/blob/main/articles/codex_exec_plans.md) from the OpenAI Cookbook +- **Template structure**: Designed for modern AI coding agents (Claude Code, Cursor, GitHub Copilot, etc.) + +## Contributing + +This is a template repository. If you have suggestions for improving the template structure or documentation: + +1. Fork this repository +2. Make your improvements +3. Submit a pull request + +For issues specific to your project, customize your fork as needed. + +## License + +MIT License - see [LICENSE](LICENSE) file for details. + +## FAQ + +### Why separate AGENTS.md files for backend and frontend? + +Different parts of your codebase often have different: +- Technology stacks +- Coding conventions +- Testing approaches +- Available tools + +Separate files let you provide focused, relevant instructions for each context. + +### Can I use this for a monorepo? + +Absolutely! Place an `AGENTS.md` file in each package or workspace that has distinct development guidelines. You can also have a root-level file for shared conventions. + +### How often should I update these files? + +Update them whenever you: +- Add new frameworks or libraries +- Change architectural patterns +- Establish new coding conventions +- Add new development tools +- Refactor major parts of the codebase + +### Can I delete the ExecPlans methodology if I don't use it? + +Yes, if you don't plan to use the ExecPlan approach, you can delete the `PLANS.md` files and references to them in `AGENTS.md`. However, we recommend trying it for complex features first, many teams find it valuable. + +### What if my AI agent doesn't support loading custom instructions? + +You can still use these files as: +- Onboarding documentation for new team members +- A reference you manually provide to the AI in conversations +- Templates for creating smaller, task-specific instructions + +## Support + +For questions about: +- **This template**: Open an issue in this repository +- **Your specific project**: Customize the template and maintain your own documentation +- **AI coding agents**: Consult the documentation for your specific agent (Claude Code, Cursor, etc.) + +--- + +**Ready to get started?** Fork this repo, customize the templates, and give your AI agents the context they need to write great code for your project! diff --git a/backend/.agent/PLANS.md b/backend/.agent/PLANS.md new file mode 100644 index 000000000..0e4cf11b0 --- /dev/null +++ b/backend/.agent/PLANS.md @@ -0,0 +1,154 @@ +# Codex Execution Plans (ExecPlans): + +> **Attribution**: This document is based on the Codex Execution Plans from the [OpenAI Cookbook](https://github.com/openai/openai-cookbook/blob/main/articles/codex_exec_plans.md). + +This document describes the requirements for an execution plan ("ExecPlan"), a design document that a coding agent can follow to deliver a working feature or system change. Treat the reader as a complete beginner to this repository: they have only the current working tree and the single ExecPlan file you provide. There is no memory of prior plans and no external context. + +## How to use ExecPlans and PLANS.md + +When authoring an executable specification (ExecPlan), follow PLANS.md _to the letter_. If it is not in your context, refresh your memory by reading the entire PLANS.md file. Be thorough in reading (and re-reading) source material to produce an accurate specification. When creating a spec, start from the skeleton and flesh it out as you do your research. + +When implementing an executable specification (ExecPlan), do not prompt the user for "next steps"; simply proceed to the next milestone. Keep all sections up to date, add or split entries in the list at every stopping point to affirmatively state the progress made and next steps. Resolve ambiguities autonomously, and commit frequently. + +When discussing an executable specification (ExecPlan), record decisions in a log in the spec for posterity; it should be unambiguously clear why any change to the specification was made. ExecPlans are living documents, and it should always be possible to restart from _only_ the ExecPlan and no other work. + +When researching a design with challenging requirements or significant unknowns, use milestones to implement proof of concepts, "toy implementations", etc., that allow validating whether the user's proposal is feasible. Read the source code of libraries by finding or acquiring them, research deeply, and include prototypes to guide a fuller implementation. + +## Requirements + +NON-NEGOTIABLE REQUIREMENTS: + +* Every ExecPlan must be fully self-contained. Self-contained means that in its current form it contains all knowledge and instructions needed for a novice to succeed. +* Every ExecPlan is a living document. Contributors are required to revise it as progress is made, as discoveries occur, and as design decisions are finalized. Each revision must remain fully self-contained. +* Every ExecPlan must enable a complete novice to implement the feature end-to-end without prior knowledge of this repo. +* Every ExecPlan must produce a demonstrably working behavior, not merely code changes to "meet a definition". +* Every ExecPlan must define every term of art in plain language or do not use it. + +Purpose and intent come first. Begin by explaining, in a few sentences, why the work matters from a user's perspective: what someone can do after this change that they could not do before, and how to see it working. Then guide the reader through the exact steps to achieve that outcome, including what to edit, what to run, and what they should observe. + +The agent executing your plan can list files, read files, search, run the project, and run tests. It does not know any prior context and cannot infer what you meant from earlier milestones. Repeat any assumption you rely on. Do not point to external blogs or docs; if knowledge is required, embed it in the plan itself in your own words. If an ExecPlan builds upon a prior ExecPlan and that file is checked in, incorporate it by reference. If it is not, you must include all relevant context from that plan. + +## Formatting + +Format and envelope are simple and strict. Each ExecPlan must be one single fenced code block labeled as `md` that begins and ends with triple backticks. Do not nest additional triple-backtick code fences inside; when you need to show commands, transcripts, diffs, or code, present them as indented blocks within that single fence. Use indentation for clarity rather than code fences inside an ExecPlan to avoid prematurely closing the ExecPlan's code fence. Use two newlines after every heading, use # and ## and so on, and correct syntax for ordered and unordered lists. + +When writing an ExecPlan to a Markdown (.md) file where the content of the file *is only* the single ExecPlan, you should omit the triple backticks. + +Write in plain prose. Prefer sentences over lists. Avoid checklists, tables, and long enumerations unless brevity would obscure meaning. Checklists are permitted only in the `Progress` section, where they are mandatory. Narrative sections must remain prose-first. + +## Guidelines + +Self-containment and plain language are paramount. If you introduce a phrase that is not ordinary English ("daemon", "middleware", "RPC gateway", "filter graph"), define it immediately and remind the reader how it manifests in this repository (for example, by naming the files or commands where it appears). Do not say "as defined previously" or "according to the architecture doc." Include the needed explanation here, even if you repeat yourself. + +Avoid common failure modes. Do not rely on undefined jargon. Do not describe "the letter of a feature" so narrowly that the resulting code compiles but does nothing meaningful. Do not outsource key decisions to the reader. When ambiguity exists, resolve it in the plan itself and explain why you chose that path. Err on the side of over-explaining user-visible effects and under-specifying incidental implementation details. + +Anchor the plan with observable outcomes. State what the user can do after implementation, the commands to run, and the outputs they should see. Acceptance should be phrased as behavior a human can verify ("after starting the server, navigating to [http://localhost:8080/health](http://localhost:8080/health) returns HTTP 200 with body OK") rather than internal attributes ("added a HealthCheck struct"). If a change is internal, explain how its impact can still be demonstrated (for example, by running tests that fail before and pass after, and by showing a scenario that uses the new behavior). + +Specify repository context explicitly. Name files with full repository-relative paths, name functions and modules precisely, and describe where new files should be created. If touching multiple areas, include a short orientation paragraph that explains how those parts fit together so a novice can navigate confidently. When running commands, show the working directory and exact command line. When outcomes depend on environment, state the assumptions and provide alternatives when reasonable. + +Be idempotent and safe. Write the steps so they can be run multiple times without causing damage or drift. If a step can fail halfway, include how to retry or adapt. If a migration or destructive operation is necessary, spell out backups or safe fallbacks. Prefer additive, testable changes that can be validated as you go. + +Validation is not optional. Include instructions to run tests, to start the system if applicable, and to observe it doing something useful. Describe comprehensive testing for any new features or capabilities. Include expected outputs and error messages so a novice can tell success from failure. Where possible, show how to prove that the change is effective beyond compilation (for example, through a small end-to-end scenario, a CLI invocation, or an HTTP request/response transcript). State the exact test commands appropriate to the project’s toolchain and how to interpret their results. + +Capture evidence. When your steps produce terminal output, short diffs, or logs, include them inside the single fenced block as indented examples. Keep them concise and focused on what proves success. If you need to include a patch, prefer file-scoped diffs or small excerpts that a reader can recreate by following your instructions rather than pasting large blobs. + +## Milestones + +Milestones are narrative, not bureaucracy. If you break the work into milestones, introduce each with a brief paragraph that describes the scope, what will exist at the end of the milestone that did not exist before, the commands to run, and the acceptance you expect to observe. Keep it readable as a story: goal, work, result, proof. Progress and milestones are distinct: milestones tell the story, progress tracks granular work. Both must exist. Never abbreviate a milestone merely for the sake of brevity, do not leave out details that could be crucial to a future implementation. + +Each milestone must be independently verifiable and incrementally implement the overall goal of the execution plan. + +## Living plans and design decisions + +* ExecPlans are living documents. As you make key design decisions, update the plan to record both the decision and the thinking behind it. Record all decisions in the `Decision Log` section. +* ExecPlans must contain and maintain a `Progress` section, a `Surprises & Discoveries` section, a `Decision Log`, and an `Outcomes & Retrospective` section. These are not optional. +* When you discover optimizer behavior, performance tradeoffs, unexpected bugs, or inverse/unapply semantics that shaped your approach, capture those observations in the `Surprises & Discoveries` section with short evidence snippets (test output is ideal). +* If you change course mid-implementation, document why in the `Decision Log` and reflect the implications in `Progress`. Plans are guides for the next contributor as much as checklists for you. +* At completion of a major task or the full plan, write an `Outcomes & Retrospective` entry summarizing what was achieved, what remains, and lessons learned. + +# Prototyping milestones and parallel implementations + +It is acceptable—-and often encouraged—-to include explicit prototyping milestones when they de-risk a larger change. Examples: adding a low-level operator to a dependency to validate feasibility, or exploring two composition orders while measuring optimizer effects. Keep prototypes additive and testable. Clearly label the scope as “prototyping”; describe how to run and observe results; and state the criteria for promoting or discarding the prototype. + +Prefer additive code changes followed by subtractions that keep tests passing. Parallel implementations (e.g., keeping an adapter alongside an older path during migration) are fine when they reduce risk or enable tests to continue passing during a large migration. Describe how to validate both paths and how to retire one safely with tests. When working with multiple new libraries or feature areas, consider creating spikes that evaluate the feasibility of these features _independently_ of one another, proving that the external library performs as expected and implements the features we need in isolation. + +## Skeleton of a Good ExecPlan + +```md +# + +This ExecPlan is a living document. The sections `Progress`, `Surprises & Discoveries`, `Decision Log`, and `Outcomes & Retrospective` must be kept up to date as work proceeds. + +If PLANS.md file is checked into the repo, reference the path to that file here from the repository root and note that this document must be maintained in accordance with PLANS.md. + +## Purpose / Big Picture + +Explain in a few sentences what someone gains after this change and how they can see it working. State the user-visible behavior you will enable. + +## Progress + +Use a list with checkboxes to summarize granular steps. Every stopping point must be documented here, even if it requires splitting a partially completed task into two (“done” vs. “remaining”). This section must always reflect the actual current state of the work. + +- [x] (2025-10-01 13:00Z) Example completed step. +- [ ] Example incomplete step. +- [ ] Example partially completed step (completed: X; remaining: Y). + +Use timestamps to measure rates of progress. + +## Surprises & Discoveries + +Document unexpected behaviors, bugs, optimizations, or insights discovered during implementation. Provide concise evidence. + +- Observation: … + Evidence: … + +## Decision Log + +Record every decision made while working on the plan in the format: + +- Decision: … + Rationale: … + Date/Author: … + +## Outcomes & Retrospective + +Summarize outcomes, gaps, and lessons learned at major milestones or at completion. Compare the result against the original purpose. + +## Context and Orientation + +Describe the current state relevant to this task as if the reader knows nothing. Name the key files and modules by full path. Define any non-obvious term you will use. Do not refer to prior plans. + +## Plan of Work + +Describe, in prose, the sequence of edits and additions. For each edit, name the file and location (function, module) and what to insert or change. Keep it concrete and minimal. + +## Concrete Steps + +State the exact commands to run and where to run them (working directory). When a command generates output, show a short expected transcript so the reader can compare. This section must be updated as work proceeds. + +## Validation and Acceptance + +Describe how to start or exercise the system and what to observe. Phrase acceptance as behavior, with specific inputs and outputs. If tests are involved, say "run and expect passed; the new test fails before the change and passes after>". + +## Idempotence and Recovery + +If steps can be repeated safely, say so. If a step is risky, provide a safe retry or rollback path. Keep the environment clean after completion. + +## Artifacts and Notes + +Include the most important transcripts, diffs, or snippets as indented examples. Keep them concise and focused on what proves success. + +## Interfaces and Dependencies + +Be prescriptive. Name the libraries, modules, and services to use and why. Specify the types, traits/interfaces, and function signatures that must exist at the end of the milestone. Prefer stable names and paths such as `crate::module::function` or `package.submodule.Interface`. E.g.: + +In crates/foo/planner.rs, define: + + pub trait Planner { + fn plan(&self, observed: &Observed) -> Vec; + } +``` + +If you follow the guidance above, a single, stateless agent -- or a human novice -- can read your ExecPlan from top to bottom and produce a working, observable result. That is the bar: SELF-CONTAINED, SELF-SUFFICIENT, NOVICE-GUIDING, OUTCOME-FOCUSED. + +When you revise a plan, you must ensure your changes are comprehensively reflected across all sections, including the living document sections, and you must write a note at the bottom of the plan describing the change and the reason why. ExecPlans must describe not just the what but the why for almost everything. \ No newline at end of file diff --git a/backend/AGENTS.md b/backend/AGENTS.md new file mode 100644 index 000000000..d2780316d --- /dev/null +++ b/backend/AGENTS.md @@ -0,0 +1,198 @@ +# Project Overview + + + +[YOUR_PROJECT_DESCRIPTION] + +**Example**: This is a [YOUR_LANGUAGE] project that [YOUR_PROJECT_PURPOSE]. + +# ExecPlans + +When writing complex features or significant refactors, use an ExecPlan (as described in .agent/PLANS.md) from design to implementation. + +Skip using an ExecPlan for straightforward tasks (roughly the easiest 25%). + +# Architecture + + + +[YOUR_ARCHITECTURE_DESCRIPTION] + +**Example architecture structure:** +``` +your-project/ +├── src/ +│ ├── [MODULE_1]/ +│ ├── [MODULE_2]/ +│ └── [MODULE_3]/ +├── tests/ +└── [CONFIG_FILES] +``` + +# Development Guidelines + +## General + +- Before implementing a large refactor or new feature explain your plan and get approval. +- Human-in-the-loop: If you're unsure about a design decision or implementation detail, ask for clarification before proceeding. Feel free to ask clarifying questions as you are working. +- Avoid re-inventing the wheel: Use existing libraries and tools where appropriate. + + + +## [YOUR_PRIMARY_LANGUAGE] + +`[YOUR_PACKAGE_MANAGER]` is the command-line tool used to manage the development environment and dependencies. Below are the common commands you'll use: + +- `[INSTALL_COMMAND]` - Install/sync dependencies +- `[ADD_PACKAGE_COMMAND]` - Add a dependency +- `[RUN_TESTS_COMMAND]` - Run tests +- `[LINT_COMMAND]` - Run linting/formatting +- `[BUILD_COMMAND]` - Build the project + +### Technology Stack Focus +- **[LANGUAGE_VERSION]**: [Description] +- **[FRAMEWORK_1]**: [Purpose] +- **[FRAMEWORK_2]**: [Purpose] + +## [YOUR_SECONDARY_LANGUAGE] (if applicable) + +`[PACKAGE_MANAGER]` commands: + +- `[BUILD_COMMAND]` - Build the project +- `[TEST_COMMAND]` - Run tests +- `[LINT_COMMAND]` - Run linter +- `[FORMAT_COMMAND]` - Format code + +### Code Organization and Modularity + +**Prefer highly modular code** that separates concerns into distinct modules. This improves: +- **Testability**: Each module can be tested in isolation +- **Reusability**: Modules can be used independently +- **Maintainability**: Changes are localized to specific modules +- **Readability**: Clear separation of concerns makes code easier to understand + +**Guidelines**: +- Keep modules focused on a single responsibility +- Use clear module boundaries and minimal public APIs +- Prefer composition over large monolithic modules +- Extract shared functionality into dedicated modules as the codebase grows + +# Code Style + +## Documentation + +**IMPORTANT: Documentation means docstrings and type hints in the code, NOT separate documentation files.** + +- You should NOT create any separate documentation pages (README files, markdown docs, etc.) +- The code itself should contain proficient documentation in the form of docstrings and type hints (for Python) +- For Python: Add comprehensive numpy-style docstrings to all functions, classes, and modules +- Type stubs (.pyi files) should have detailed descriptions for all exported functions and classes + +**Avoid Over-Documenting:** +- Do NOT document obvious behavior (e.g., a function named `get_name` that returns a name doesn't need extensive documentation) +- Focus documentation on WHY and HOW, not WHAT (the code itself shows what it does) +- Document edge cases, non-obvious behavior, and important constraints +- Skip docstrings for trivial functions where the name and type hints are self-explanatory +- Prioritize documenting public APIs, complex logic, and non-intuitive design decisions + + + +## [YOUR_LANGUAGE] Code Style + +### Documentation and Comments + +- Write clear and concise comments for each function +- Ensure functions have descriptive names and include type hints/annotations +- Provide documentation following [YOUR_LANGUAGE_CONVENTION] + - Example: Use JSDoc for JavaScript, docstrings for Python + +### Naming Conventions + +- **Variables and Functions**: `[YOUR_CONVENTION]` (e.g., camelCase, snake_case) +- **Classes/Types**: `[YOUR_CONVENTION]` (e.g., PascalCase) +- **Constants**: `[YOUR_CONVENTION]` (e.g., UPPER_SNAKE_CASE) + +### Additional Language-Specific Guidelines + +[YOUR_SPECIFIC_GUIDELINES] + +# Test-Driven Development (TDD) + +- Never create throwaway test scripts or ad hoc verification files +- If you need to test functionality, write a proper test in the test suite + + + +## Testing Guidelines + +- Write tests for all new features in the `[YOUR_TEST_DIRECTORY]/` directory +- Use `[YOUR_TEST_FRAMEWORK]` as the testing framework +- Use `[YOUR_MOCKING_LIBRARY]` for mocking dependencies (if applicable) +- Aim for high test coverage, especially for critical components +- Always include test cases for critical paths of the application +- Account for common edge cases like empty inputs, invalid data types, and large datasets +- Include comments for edge cases and the expected behavior in those cases + +# Tools + + + +You have a collection of tools available to assist with development and debugging. These tools can be invoked as needed. + +- `[TOOL_NAME_1]` + - **When to use:** [Description of when this tool should be used] +- `[TOOL_NAME_2]` + - **When to use:** [Description of when this tool should be used] +- `[TOOL_NAME_3]` + - **When to use:** [Description of when this tool should be used] + +# Updates to This Document +- Update this document as needed to reflect changes in development practices or project structure + - Updates usually come in the form of the package structure changing +- Do NOT contradict existing guidelines in the document +- This document should be an executive summary of the development practices for this project + - Keep low-level implementation details out of this document diff --git a/frontend/.agent/PLANS.md b/frontend/.agent/PLANS.md new file mode 100644 index 000000000..15d121ad9 --- /dev/null +++ b/frontend/.agent/PLANS.md @@ -0,0 +1,154 @@ +# Codex Execution Plans (ExecPlans): + +> **Attribution**: This document is based on the Codex Execution Plans from the [OpenAI Cookbook](https://github.com/openai/openai-cookbook/blob/main/articles/codex_exec_plans.md). + +This document describes the requirements for an execution plan ("ExecPlan"), a design document that a coding agent can follow to deliver a working feature or system change. Treat the reader as a complete beginner to this repository: they have only the current working tree and the single ExecPlan file you provide. There is no memory of prior plans and no external context. + +## How to use ExecPlans and PLANS.md + +When authoring an executable specification (ExecPlan), follow PLANS.md _to the letter_. If it is not in your context, refresh your memory by reading the entire PLANS.md file. Be thorough in reading (and re-reading) source material to produce an accurate specification. When creating a spec, start from the skeleton and flesh it out as you do your research. + +When implementing an executable specification (ExecPlan), do not prompt the user for "next steps"; simply proceed to the next milestone. Keep all sections up to date, add or split entries in the list at every stopping point to affirmatively state the progress made and next steps. Resolve ambiguities autonomously, and commit frequently. + +When discussing an executable specification (ExecPlan), record decisions in a log in the spec for posterity; it should be unambiguously clear why any change to the specification was made. ExecPlans are living documents, and it should always be possible to restart from _only_ the ExecPlan and no other work. + +When researching a design with challenging requirements or significant unknowns, use milestones to implement proof of concepts, "toy implementations", etc., that allow validating whether the user's proposal is feasible. Read the source code of libraries by finding or acquiring them, research deeply, and include prototypes to guide a fuller implementation. + +## Requirements + +NON-NEGOTIABLE REQUIREMENTS: + +* Every ExecPlan must be fully self-contained. Self-contained means that in its current form it contains all knowledge and instructions needed for a novice to succeed. +* Every ExecPlan is a living document. Contributors are required to revise it as progress is made, as discoveries occur, and as design decisions are finalized. Each revision must remain fully self-contained. +* Every ExecPlan must enable a complete novice to implement the feature end-to-end without prior knowledge of this repo. +* Every ExecPlan must produce a demonstrably working behavior, not merely code changes to "meet a definition". +* Every ExecPlan must define every term of art in plain language or do not use it. + +Purpose and intent come first. Begin by explaining, in a few sentences, why the work matters from a user's perspective: what someone can do after this change that they could not do before, and how to see it working. Then guide the reader through the exact steps to achieve that outcome, including what to edit, what to run, and what they should observe. + +The agent executing your plan can list files, read files, search, run the project, and run tests. It does not know any prior context and cannot infer what you meant from earlier milestones. Repeat any assumption you rely on. Do not point to external blogs or docs; if knowledge is required, embed it in the plan itself in your own words. If an ExecPlan builds upon a prior ExecPlan and that file is checked in, incorporate it by reference. If it is not, you must include all relevant context from that plan. + +## Formatting + +Format and envelope are simple and strict. Each ExecPlan must be one single fenced code block labeled as `md` that begins and ends with triple backticks. Do not nest additional triple-backtick code fences inside; when you need to show commands, transcripts, diffs, or code, present them as indented blocks within that single fence. Use indentation for clarity rather than code fences inside an ExecPlan to avoid prematurely closing the ExecPlan's code fence. Use two newlines after every heading, use # and ## and so on, and correct syntax for ordered and unordered lists. + +When writing an ExecPlan to a Markdown (.md) file where the content of the file *is only* the single ExecPlan, you should omit the triple backticks. + +Write in plain prose. Prefer sentences over lists. Avoid checklists, tables, and long enumerations unless brevity would obscure meaning. Checklists are permitted only in the `Progress` section, where they are mandatory. Narrative sections must remain prose-first. + +## Guidelines + +Self-containment and plain language are paramount. If you introduce a phrase that is not ordinary English ("daemon", "middleware", "RPC gateway", "filter graph"), define it immediately and remind the reader how it manifests in this repository (for example, by naming the files or commands where it appears). Do not say "as defined previously" or "according to the architecture doc." Include the needed explanation here, even if you repeat yourself. + +Avoid common failure modes. Do not rely on undefined jargon. Do not describe "the letter of a feature" so narrowly that the resulting code compiles but does nothing meaningful. Do not outsource key decisions to the reader. When ambiguity exists, resolve it in the plan itself and explain why you chose that path. Err on the side of over-explaining user-visible effects and under-specifying incidental implementation details. + +Anchor the plan with observable outcomes. State what the user can do after implementation, the commands to run, and the outputs they should see. Acceptance should be phrased as behavior a human can verify ("after starting the server, navigating to [http://localhost:8080/health](http://localhost:8080/health) returns HTTP 200 with body OK") rather than internal attributes ("added a HealthCheck struct"). If a change is internal, explain how its impact can still be demonstrated (for example, by running tests that fail before and pass after, and by showing a scenario that uses the new behavior). + +Specify repository context explicitly. Name files with full repository-relative paths, name functions and modules precisely, and describe where new files should be created. If touching multiple areas, include a short orientation paragraph that explains how those parts fit together so a novice can navigate confidently. When running commands, show the working directory and exact command line. When outcomes depend on environment, state the assumptions and provide alternatives when reasonable. + +Be idempotent and safe. Write the steps so they can be run multiple times without causing damage or drift. If a step can fail halfway, include how to retry or adapt. If a migration or destructive operation is necessary, spell out backups or safe fallbacks. Prefer additive, testable changes that can be validated as you go. + +Validation is not optional. Include instructions to run tests, to start the system if applicable, and to observe it doing something useful. Describe comprehensive testing for any new features or capabilities. Include expected outputs and error messages so a novice can tell success from failure. Where possible, show how to prove that the change is effective beyond compilation (for example, through a small end-to-end scenario, a CLI invocation, or an HTTP request/response transcript). State the exact test commands appropriate to the project’s toolchain and how to interpret their results. + +Capture evidence. When your steps produce terminal output, short diffs, or logs, include them inside the single fenced block as indented examples. Keep them concise and focused on what proves success. If you need to include a patch, prefer file-scoped diffs or small excerpts that a reader can recreate by following your instructions rather than pasting large blobs. + +## Milestones + +Milestones are narrative, not bureaucracy. If you break the work into milestones, introduce each with a brief paragraph that describes the scope, what will exist at the end of the milestone that did not exist before, the commands to run, and the acceptance you expect to observe. Keep it readable as a story: goal, work, result, proof. Progress and milestones are distinct: milestones tell the story, progress tracks granular work. Both must exist. Never abbreviate a milestone merely for the sake of brevity, do not leave out details that could be crucial to a future implementation. + +Each milestone must be independently verifiable and incrementally implement the overall goal of the execution plan. + +## Living plans and design decisions + +* ExecPlans are living documents. As you make key design decisions, update the plan to record both the decision and the thinking behind it. Record all decisions in the `Decision Log` section. +* ExecPlans must contain and maintain a `Progress` section, a `Surprises & Discoveries` section, a `Decision Log`, and an `Outcomes & Retrospective` section. These are not optional. +* When you discover optimizer behavior, performance tradeoffs, unexpected bugs, or inverse/unapply semantics that shaped your approach, capture those observations in the `Surprises & Discoveries` section with short evidence snippets (test output is ideal). +* If you change course mid-implementation, document why in the `Decision Log` and reflect the implications in `Progress`. Plans are guides for the next contributor as much as checklists for you. +* At completion of a major task or the full plan, write an `Outcomes & Retrospective` entry summarizing what was achieved, what remains, and lessons learned. + +# Prototyping milestones and parallel implementations + +It is acceptable—-and often encouraged—-to include explicit prototyping milestones when they de-risk a larger change. Examples: adding a low-level operator to a dependency to validate feasibility, or exploring two composition orders while measuring optimizer effects. Keep prototypes additive and testable. Clearly label the scope as “prototyping”; describe how to run and observe results; and state the criteria for promoting or discarding the prototype. + +Prefer additive code changes followed by subtractions that keep tests passing. Parallel implementations (e.g., keeping an adapter alongside an older path during migration) are fine when they reduce risk or enable tests to continue passing during a large migration. Describe how to validate both paths and how to retire one safely with tests. When working with multiple new libraries or feature areas, consider creating spikes that evaluate the feasibility of these features _independently_ of one another, proving that the external library performs as expected and implements the features we need in isolation. + +## Skeleton of a Good ExecPlan + +```md +# + +This ExecPlan is a living document. The sections `Progress`, `Surprises & Discoveries`, `Decision Log`, and `Outcomes & Retrospective` must be kept up to date as work proceeds. + +If PLANS.md file is checked into the repo, reference the path to that file here from the repository root and note that this document must be maintained in accordance with PLANS.md. + +## Purpose / Big Picture + +Explain in a few sentences what someone gains after this change and how they can see it working. State the user-visible behavior you will enable. + +## Progress + +Use a list with checkboxes to summarize granular steps. Every stopping point must be documented here, even if it requires splitting a partially completed task into two (“done” vs. “remaining”). This section must always reflect the actual current state of the work. + +- [x] (2025-10-01 13:00Z) Example completed step. +- [ ] Example incomplete step. +- [ ] Example partially completed step (completed: X; remaining: Y). + +Use timestamps to measure rates of progress. + +## Surprises & Discoveries + +Document unexpected behaviors, bugs, optimizations, or insights discovered during implementation. Provide concise evidence. + +- Observation: … + Evidence: … + +## Decision Log + +Record every decision made while working on the plan in the format: + +- Decision: … + Rationale: … + Date/Author: … + +## Outcomes & Retrospective + +Summarize outcomes, gaps, and lessons learned at major milestones or at completion. Compare the result against the original purpose. + +## Context and Orientation + +Describe the current state relevant to this task as if the reader knows nothing. Name the key files and modules by full path. Define any non-obvious term you will use. Do not refer to prior plans. + +## Plan of Work + +Describe, in prose, the sequence of edits and additions. For each edit, name the file and location (function, module) and what to insert or change. Keep it concrete and minimal. + +## Concrete Steps + +State the exact commands to run and where to run them (working directory). When a command generates output, show a short expected transcript so the reader can compare. This section must be updated as work proceeds. + +## Validation and Acceptance + +Describe how to start or exercise the system and what to observe. Phrase acceptance as behavior, with specific inputs and outputs. If tests are involved, say "run and expect passed; the new test fails before the change and passes after>". + +## Idempotence and Recovery + +If steps can be repeated safely, say so. If a step is risky, provide a safe retry or rollback path. Keep the environment clean after completion. + +## Artifacts and Notes + +Include the most important transcripts, diffs, or snippets as indented examples. Keep them concise and focused on what proves success. + +## Interfaces and Dependencies + +Be prescriptive. Name the libraries, modules, and services to use and why. Specify the types, traits/interfaces, and function signatures that must exist at the end of the milestone. Prefer stable names and paths such as `crate::module::function` or `package.submodule.Interface`. E.g.: + +In crates/foo/planner.rs, define: + + pub trait Planner { + fn plan(&self, observed: &Observed) -> Vec; + } +``` + +If you follow the guidance above, a single, stateless agent -- or a human novice -- can read your ExecPlan from top to bottom and produce a working, observable result. That is the bar: SELF-CONTAINED, SELF-SUFFICIENT, NOVICE-GUIDING, OUTCOME-FOCUSED. + +When you revise a plan, you must ensure your changes are comprehensively reflected across all sections, including the living document sections, and you must write a note at the bottom of the plan describing the change and the reason why. ExecPlans must describe not just the what but the why for almost everything. diff --git a/frontend/AGENTS.md b/frontend/AGENTS.md new file mode 100644 index 000000000..5e2e3493e --- /dev/null +++ b/frontend/AGENTS.md @@ -0,0 +1,224 @@ +# Project Overview + + + +[YOUR_PROJECT_DESCRIPTION] + +**Example**: This is a [YOUR_FRAMEWORK]/[YOUR_LANGUAGE] project that [YOUR_PROJECT_PURPOSE]. + +# ExecPlans + +When writing complex features or significant refactors, use an ExecPlan (as described in .agent/PLANS.md) from design to implementation. + +Skip using an ExecPlan for straightforward tasks (roughly the easiest 25%). + +# Architecture + + + +[YOUR_ARCHITECTURE_DESCRIPTION] + +**Example directory structure:** +- Route handlers in `[YOUR_ROUTES_DIR]/` +- Components in `[YOUR_COMPONENTS_DIR]/` +- Utilities in `[YOUR_UTILS_DIR]/` +- Styles in `[YOUR_STYLES_DIR]/` +- Static assets in `[YOUR_ASSETS_DIR]/` +- Tests in `[YOUR_TESTS_DIR]/` + +## Technology Stack Focus + + + +* **[FRAMEWORK]**: [Key features you're using] +* **[UI_LIBRARY]**: [Purpose] +* **[LANGUAGE]**: [Version and key features] +* **[STYLING_SOLUTION]**: [Approach] +* **[STATE_MANAGEMENT]**: [If applicable] + +# Development Guidelines + +## General + +- Before implementing a large refactor or new feature explain your plan and get approval. +- Human-in-the-loop: If you're unsure about a design decision or implementation detail, ask for clarification before proceeding. Feel free to ask clarifying questions as you are working. +- Avoid re-inventing the wheel: Use existing libraries and tools where appropriate (e.g., component libraries like `shadcn/ui`, css frameworks like `tailwindcss`). + +## Package Management + + + +This project uses `[YOUR_PACKAGE_MANAGER]` as the package manager. Below are common commands you'll use: + +- `[INSTALL_COMMAND]` - Install dependencies +- `[TEST_COMMAND]` - Run tests +- `[LINT_COMMAND]` - Run linting +- `[BUILD_COMMAND]` - Build the project +- `[DEV_COMMAND]` - Start the development server +- `[START_COMMAND]` - Start the production server +- `[ADD_PACKAGE_COMMAND]` - Add a dependency +- `[REMOVE_PACKAGE_COMMAND]` - Remove a dependency + +# Code Style + + + +## General Code Style + +- Never use `any` type (if using TypeScript)--always use proper types and interfaces +- [YOUR_COMPONENT_PATTERN] (e.g., prefer function components over class components) +- Always validate external data with `[YOUR_VALIDATION_LIBRARY]` +- Use `[YOUR_FORMATTER]` for code formatting +- Use `[YOUR_LINTER]` for linting and follow its recommendations +- Follow accessibility best practices (e.g., proper use of ARIA attributes, semantic HTML) + +## Component Patterns + + + +Use [YOUR_COMPONENT_PATTERN] with proper type definitions: + +```[YOUR_LANGUAGE] +// Example component following your project's patterns +[YOUR_EXAMPLE_COMPONENT_CODE] +``` + +## Data Fetching + + + +[YOUR_DATA_FETCHING_STRATEGY] + +## Validation + + + +Always validate external data using `[YOUR_VALIDATION_LIBRARY]`. + +## Routing + + + +[YOUR_ROUTING_CONVENTIONS] + +## UI Components + + + +Use `[YOUR_COMPONENT_LIBRARY]` for UI components: + +```[YOUR_LANGUAGE] +// Example UI component usage +[YOUR_EXAMPLE_UI_CODE] +``` + +## Accessibility + +Use semantic HTML first. Only add ARIA when no semantic equivalent exists. + +## Import Standards + + + +Use `[YOUR_IMPORT_ALIAS]` for all internal imports: + +```[YOUR_LANGUAGE] +// ✅ Good +import { Component } from '[YOUR_IMPORT_PATTERN]' + +// ❌ Bad +import { Component } from '[ANTI_PATTERN]' +``` + +## Common Patterns + +- [YOUR_PATTERN_1] +- [YOUR_PATTERN_2] +- [YOUR_PATTERN_3] + +# Test-Driven Development (TDD) + +- Never create throwaway test scripts or ad hoc verification files +- If you need to test functionality, write a proper test in the test suite + + + +## Testing Frameworks + +- Use `[YOUR_UNIT_TEST_FRAMEWORK]` for unit, component, and integration tests +- Use `[YOUR_E2E_TEST_FRAMEWORK]` for end-to-end and snapshot tests + +# Tools + + + +You have a collection of tools available to assist with development and debugging. These tools can be invoked as needed. + +- `[TOOL_NAME_1]` + - **When to use:** [Description of when this tool should be used] +- `[TOOL_NAME_2]` + - **When to use:** [Description of when this tool should be used] +- `[TOOL_NAME_3]` + - **When to use:** [Description of when this tool should be used] + +# Updates to This Document +- Update this document as needed to reflect changes in development practices or project structure. +- Do NOT contradict existing guidelines in the document