add agent instructions

.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

DEV_SETUP.md

@@ -0,0 +1,177 @@
+# Development Setup
+
+<!--
+  TEMPLATE INSTRUCTIONS: This file should contain all necessary setup instructions for new developers
+  joining your project. Replace the placeholders below with your actual setup steps.
+-->
+
+## Prerequisites
+
+<!--
+  TEMPLATE INSTRUCTIONS: List all required software, tools, and accounts needed.
+  Examples:
+  - Programming language runtime (Node.js, Python, etc.)
+  - Package managers
+  - Database systems
+  - API keys or credentials
+  - IDE/Editor recommendations
+-->
+
+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
+
+<!--
+  TEMPLATE INSTRUCTIONS: Provide step-by-step installation instructions.
+  Number the steps clearly and include expected output where helpful.
+-->
+
+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
+
+<!--
+  TEMPLATE INSTRUCTIONS: Explain any configuration files that need to be set up.
+  Include examples of common configurations.
+-->
+
+### 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
+
+<!--
+  TEMPLATE INSTRUCTIONS: Provide commands to run the project in development mode.
+-->
+
+### 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
+
+<!--
+  TEMPLATE INSTRUCTIONS: Explain how to run tests.
+-->
+
+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
+
+<!--
+  TEMPLATE INSTRUCTIONS: Provide commands for code quality tools.
+-->
+
+Check code style:
+
+```bash
+[YOUR_LINT_COMMAND]
+```
+
+Auto-fix issues:
+
+```bash
+[YOUR_LINT_FIX_COMMAND]
+```
+
+Format code:
+
+```bash
+[YOUR_FORMAT_COMMAND]
+```
+
+## Troubleshooting
+
+<!--
+  TEMPLATE INSTRUCTIONS: Document common setup issues and their solutions.
+-->
+
+### [COMMON_ISSUE_1]
+
+**Problem**: [DESCRIPTION]
+
+**Solution**: [STEPS_TO_RESOLVE]
+
+### [COMMON_ISSUE_2]
+
+**Problem**: [DESCRIPTION]
+
+**Solution**: [STEPS_TO_RESOLVE]
+
+## Additional Resources
+
+<!--
+  TEMPLATE INSTRUCTIONS: Link to additional documentation, guides, or resources.
+-->
+
+- [Link to architecture docs]
+- [Link to API documentation]
+- [Link to deployment guide]
+- [Link to contributing guidelines]