workspace-architect 1.3.0

package/assets/instructions/python-mcp-server.instructions.md

@@ -0,0 +1,204 @@
+---
+description: 'Instructions for building Model Context Protocol (MCP) servers using the Python SDK'
+applyTo: '**/*.py, **/pyproject.toml, **/requirements.txt'
+---
+
+# Python MCP Server Development
+
+## Instructions
+
+- Use **uv** for project management: `uv init mcp-server-demo` and `uv add "mcp[cli]"`
+- Import FastMCP from `mcp.server.fastmcp`: `from mcp.server.fastmcp import FastMCP`
+- Use `@mcp.tool()`, `@mcp.resource()`, and `@mcp.prompt()` decorators for registration
+- Type hints are mandatory - they're used for schema generation and validation
+- Use Pydantic models, TypedDicts, or dataclasses for structured output
+- Tools automatically return structured output when return types are compatible
+- For stdio transport, use `mcp.run()` or `mcp.run(transport="stdio")`
+- For HTTP servers, use `mcp.run(transport="streamable-http")` or mount to Starlette/FastAPI
+- Use `Context` parameter in tools/resources to access MCP capabilities: `ctx: Context`
+- Send logs with `await ctx.debug()`, `await ctx.info()`, `await ctx.warning()`, `await ctx.error()`
+- Report progress with `await ctx.report_progress(progress, total, message)`
+- Request user input with `await ctx.elicit(message, schema)`
+- Use LLM sampling with `await ctx.session.create_message(messages, max_tokens)`
+- Configure icons with `Icon(src="path", mimeType="image/png")` for server, tools, resources, prompts
+- Use `Image` class for automatic image handling: `return Image(data=bytes, format="png")`
+- Define resource templates with URI patterns: `@mcp.resource("greeting://{name}")`
+- Implement completion support by accepting partial values and returning suggestions
+- Use lifespan context managers for startup/shutdown with shared resources
+- Access lifespan context in tools via `ctx.request_context.lifespan_context`
+- For stateless HTTP servers, set `stateless_http=True` in FastMCP initialization
+- Enable JSON responses for modern clients: `json_response=True`
+- Test servers with: `uv run mcp dev server.py` (Inspector) or `uv run mcp install server.py` (Claude Desktop)
+- Mount multiple servers in Starlette with different paths: `Mount("/path", mcp.streamable_http_app())`
+- Configure CORS for browser clients: expose `Mcp-Session-Id` header
+- Use low-level Server class for maximum control when FastMCP isn't sufficient
+
+## Best Practices
+
+- Always use type hints - they drive schema generation and validation
+- Return Pydantic models or TypedDicts for structured tool outputs
+- Keep tool functions focused on single responsibilities
+- Provide clear docstrings - they become tool descriptions
+- Use descriptive parameter names with type hints
+- Validate inputs using Pydantic Field descriptions
+- Implement proper error handling with try-except blocks
+- Use async functions for I/O-bound operations
+- Clean up resources in lifespan context managers
+- Log to stderr to avoid interfering with stdio transport (when using stdio)
+- Use environment variables for configuration
+- Test tools independently before LLM integration
+- Consider security when exposing file system or network access
+- Use structured output for machine-readable data
+- Provide both content and structured data for backward compatibility
+
+## Common Patterns
+
+### Basic Server Setup (stdio)
+```python
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("My Server")
+
+@mcp.tool()
+def calculate(a: int, b: int, op: str) -> int:
+    """Perform calculation"""
+    if op == "add":
+        return a + b
+    return a - b
+
+if __name__ == "__main__":
+    mcp.run()  # stdio by default
+```
+
+### HTTP Server
+```python
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("My HTTP Server")
+
+@mcp.tool()
+def hello(name: str = "World") -> str:
+    """Greet someone"""
+    return f"Hello, {name}!"
+
+if __name__ == "__main__":
+    mcp.run(transport="streamable-http")
+```
+
+### Tool with Structured Output
+```python
+from pydantic import BaseModel, Field
+
+class WeatherData(BaseModel):
+    temperature: float = Field(description="Temperature in Celsius")
+    condition: str
+    humidity: float
+
+@mcp.tool()
+def get_weather(city: str) -> WeatherData:
+    """Get weather for a city"""
+    return WeatherData(
+        temperature=22.5,
+        condition="sunny",
+        humidity=65.0
+    )
+```
+
+### Dynamic Resource
+```python
+@mcp.resource("users://{user_id}")
+def get_user(user_id: str) -> str:
+    """Get user profile data"""
+    return f"User {user_id} profile data"
+```
+
+### Tool with Context
+```python
+from mcp.server.fastmcp import Context
+from mcp.server.session import ServerSession
+
+@mcp.tool()
+async def process_data(
+    data: str, 
+    ctx: Context[ServerSession, None]
+) -> str:
+    """Process data with logging"""
+    await ctx.info(f"Processing: {data}")
+    await ctx.report_progress(0.5, 1.0, "Halfway done")
+    return f"Processed: {data}"
+```
+
+### Tool with Sampling
+```python
+from mcp.server.fastmcp import Context
+from mcp.server.session import ServerSession
+from mcp.types import SamplingMessage, TextContent
+
+@mcp.tool()
+async def summarize(
+    text: str,
+    ctx: Context[ServerSession, None]
+) -> str:
+    """Summarize text using LLM"""
+    result = await ctx.session.create_message(
+        messages=[SamplingMessage(
+            role="user",
+            content=TextContent(type="text", text=f"Summarize: {text}")
+        )],
+        max_tokens=100
+    )
+    return result.content.text if result.content.type == "text" else ""
+```
+
+### Lifespan Management
+```python
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from mcp.server.fastmcp import FastMCP, Context
+
+@dataclass
+class AppContext:
+    db: Database
+
+@asynccontextmanager
+async def app_lifespan(server: FastMCP):
+    db = await Database.connect()
+    try:
+        yield AppContext(db=db)
+    finally:
+        await db.disconnect()
+
+mcp = FastMCP("My App", lifespan=app_lifespan)
+
+@mcp.tool()
+def query(sql: str, ctx: Context) -> str:
+    """Query database"""
+    db = ctx.request_context.lifespan_context.db
+    return db.execute(sql)
+```
+
+### Prompt with Messages
+```python
+from mcp.server.fastmcp.prompts import base
+
+@mcp.prompt(title="Code Review")
+def review_code(code: str) -> list[base.Message]:
+    """Create code review prompt"""
+    return [
+        base.UserMessage("Review this code:"),
+        base.UserMessage(code),
+        base.AssistantMessage("I'll review the code for you.")
+    ]
+```
+
+### Error Handling
+```python
+@mcp.tool()
+async def risky_operation(input: str) -> str:
+    """Operation that might fail"""
+    try:
+        result = await perform_operation(input)
+        return f"Success: {result}"
+    except Exception as e:
+        return f"Error: {str(e)}"
+```

package/assets/instructions/python.instructions.md

@@ -0,0 +1,56 @@
+---
+description: 'Python coding conventions and guidelines'
+applyTo: '**/*.py'
+---
+
+# Python Coding Conventions
+
+## Python Instructions
+
+- Write clear and concise comments for each function.
+- Ensure functions have descriptive names and include type hints.
+- Provide docstrings following PEP 257 conventions.
+- Use the `typing` module for type annotations (e.g., `List[str]`, `Dict[str, int]`).
+- Break down complex functions into smaller, more manageable functions.
+
+## General Instructions
+
+- Always prioritize readability and clarity.
+- For algorithm-related code, include explanations of the approach used.
+- Write code with good maintainability practices, including comments on why certain design decisions were made.
+- Handle edge cases and write clear exception handling.
+- For libraries or external dependencies, mention their usage and purpose in comments.
+- Use consistent naming conventions and follow language-specific best practices.
+- Write concise, efficient, and idiomatic code that is also easily understandable.
+
+## Code Style and Formatting
+
+- Follow the **PEP 8** style guide for Python.
+- Maintain proper indentation (use 4 spaces for each level of indentation).
+- Ensure lines do not exceed 79 characters.
+- Place function and class docstrings immediately after the `def` or `class` keyword.
+- Use blank lines to separate functions, classes, and code blocks where appropriate.
+
+## Edge Cases and Testing
+
+- 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.
+- Write unit tests for functions and document them with docstrings explaining the test cases.
+
+## Example of Proper Documentation
+
+```python
+def calculate_area(radius: float) -> float:
+    """
+    Calculate the area of a circle given the radius.
+    
+    Parameters:
+    radius (float): The radius of the circle.
+    
+    Returns:
+    float: The area of the circle, calculated as π * radius^2.
+    """
+    import math
+    return math.pi * radius ** 2
+```

package/assets/instructions/quarkus-mcp-server-sse.instructions.md

@@ -0,0 +1,49 @@
+---
+applyTo: '*'
+description: 'Quarkus and MCP Server with HTTP SSE transport development standards and instructions'
+---
+# Quarkus MCP Server
+
+Build MCP servers with Java 21, Quarkus, and HTTP SSE transport.
+
+## Stack
+
+- Java 21 with Quarkus Framework
+- MCP Server Extension: `mcp-server-sse`
+- CDI for dependency injection
+- MCP Endpoint: `http://localhost:8080/mcp/sse`
+
+## Quick Start
+
+```bash
+quarkus create app --no-code -x rest-client-jackson,qute,mcp-server-sse your-domain-mcp-server
+```
+
+## Structure
+
+- Use standard Java naming conventions (PascalCase classes, camelCase methods)
+- Organize in packages: `model`, `repository`, `service`, `mcp`
+- Use Record types for immutable data models
+- State management for immutable data must be managed by repository layer
+- Add Javadoc for public methods
+
+## MCP Tools
+
+- Must be public methods in `@ApplicationScoped` CDI beans
+- Use `@Tool(name="tool_name", description="clear description")`
+- Never return `null` - return error messages instead
+- Always validate parameters and handle errors gracefully
+
+## Architecture
+
+- Separate concerns: MCP tools → Service layer → Repository
+- Use `@Inject` for dependency injection
+- Make data operations thread-safe
+- Use `Optional<T>` to avoid null pointer exceptions
+
+## Common Issues
+
+- Don't put business logic in MCP tools (use service layer)
+- Don't throw exceptions from tools (return error strings)
+- Don't forget to validate input parameters
+- Test with edge cases (null, empty inputs)

package/assets/instructions/quarkus.instructions.md

@@ -0,0 +1,98 @@
+---
+applyTo: '*'
+description: 'Quarkus development standards and instructions'
+---
+
+- Instructions for high-quality Quarkus applications with Java 17 or later.
+
+## Project Context
+
+- Latest Quarkus version: 3.x
+- Java version: 17 or later
+- Use Maven or Gradle for build management.
+- Focus on clean architecture, maintainability, and performance.
+
+## Development Standards
+
+  - Write clear and concise comments for each class, method, and complex logic.
+  - Use Javadoc for public APIs and methods to ensure clarity for consumers.
+  - Maintain a consistent coding style across the project, adhering to Java conventions.
+  - Adhere to the Quarkus coding standards and best practices for optimal performance and maintainability.
+  - Follow Jarkarta EE and MicroProfile conventions, ensuring clarity in package organization.
+  - Use Java 17 or later features where appropriate, such as records and sealed classes.
+
+
+## Naming Conventions
+  - Use PascalCase for class names (e.g., `ProductService`, `ProductResource`).
+  - Use camelCase for method and variable names (e.g., `findProductById`, `isProductAvailable`).
+  - Use ALL_CAPS for constants (e.g., `DEFAULT_PAGE_SIZE`).
+
+##  Quarkus
+  - Leverage Quarkus Dev Mode for faster development cycles.
+  - Implement build-time optimizations using Quarkus extensions and best practices.
+  - Configure native builds with GraalVM for optimal performance (e.g., use the quarkus-maven-plugin).
+  - Use quarkus logging capabilities (JBoss, SL4J or JUL) for consistent logging practices.
+
+### Quarkus-Specific Patterns
+- Use `@ApplicationScoped` for singleton beans instead of `@Singleton`
+- Use `@Inject` for dependency injection
+- Prefer Panache repositories over traditional JPA repositories
+- Use `@Transactional` on service methods that modify data
+- Apply `@Path` with descriptive REST endpoint paths
+- Use `@Consumes(MediaType.APPLICATION_JSON)` and `@Produces(MediaType.APPLICATION_JSON)` for REST resources
+
+### REST Resources
+- Always use JAX-RS annotations (`@Path`, `@GET`, `@POST`, etc.)
+- Return proper HTTP status codes (200, 201, 400, 404, 500)
+- Use `Response` class for complex responses
+- Include proper error handling with try-catch blocks
+- Validate input parameters using Bean Validation annotations
+- Implement rate limiting for public endpoints
+
+### Data Access
+- Prefer Panache entities (extend `PanacheEntity`) over traditional JPA
+- Use Panache repositories (`PanacheRepository<T>`) for complex queries
+- Always use `@Transactional` for data modifications
+- Use named queries for complex database operations
+- Implement proper pagination for list endpoints
+
+
+### Configuration
+- Use `application.properties` or `application.yaml` for simple configuration
+- Use `@ConfigProperty` for type-safe configuration classes
+- Prefer environment variables for sensitive data
+- Use profiles for different environments (dev, test, prod)
+
+
+### Testing
+- Use `@QuarkusTest` for integration tests
+- Use JUnit 5 for unit tests
+- Use `@QuarkusIntegrationTest` for native build tests
+- Mock external dependencies using `@QuarkusTestResource`
+- Use RestAssured for REST endpoint testing (`@QuarkusTestResource`)
+- Use `@Transactional` for tests that modify the database
+- Use test-containers for database integration tests
+
+### Don't use these patterns:
+- Don't use field injection in tests (use constructor injection)
+- Don't hardcode configuration values
+- Don't ignore exceptions
+
+
+## Development Workflow
+
+### When creating new features:
+1. Create entity with proper validation
+2. Create repository with custom queries
+3. Create service with business logic
+4. Create REST resource with proper endpoints
+5. Write comprehensive tests
+6. Add proper error handling
+7. Update documentation
+
+## Security Considerations
+
+### When implementing security:
+- Use Quarkus Security extensions (e.g., `quarkus-smallrye-jwt`, `quarkus-oidc`).
+- Implement role-based access control (RBAC) using MicroProfile JWT or OIDC.
+- Validate all input parameters

package/assets/instructions/r.instructions.md

@@ -0,0 +1,116 @@
+---
+description: 'R language and document formats (R, Rmd, Quarto): coding standards and Copilot guidance for idiomatic, safe, and consistent code generation.'
+applyTo: '**/*.R, **/*.r, **/*.Rmd, **/*.rmd, **/*.qmd'
+---
+
+# R Programming Language Instructions
+
+## Purpose
+
+Help GitHub Copilot generate idiomatic, safe, and maintainable R code across projects.
+
+## Core Conventions
+
+- **Match the project’s style.** If the file shows a preference (tidyverse vs. base R, `%>%` vs. `|>`), follow it.
+- **Prefer clear, vectorized code.** Keep functions small and avoid hidden side effects.
+- **Qualify non-base functions in examples/snippets**, e.g., `dplyr::mutate()`, `stringr::str_detect()`. In project code, using `library()` is acceptable when that’s the repo norm.
+- **Naming:** `lower_snake_case` for objects/files; avoid dots in names.
+- **Side effects:** Never call `setwd()`; prefer project-relative paths (e.g., `here::here()`).
+- **Reproducibility:** Set seeds locally around stochastic operations using `withr::with_seed()`.
+- **Validation:** Validate and constrain user inputs; use typed checks and allowlists where possible.
+- **Safety:** Avoid `eval(parse())`, unvalidated shell calls, and unparameterized SQL.
+
+### Pipe Operators
+
+- **Native pipe `|>` (R ≥ 4.1.0):** Prefer in R ≥ 4.1 (no extra dependency).
+- **Magrittr pipe `%>%`:** Continue using in projects already committed to magrittr or when you need features like `.`, `%T>%`, or `%$%`.
+- **Be consistent:** Don't mix `|>` and `%>%` within the same script unless there's a clear technical reason.
+
+## Performance Considerations
+
+- **Large datasets:** consider `data.table`; benchmark with your workload.
+- **dplyr compatibility:** Use `dtplyr` to write dplyr syntax that translates to data.table operations automatically for performance gains.
+- **Profiling:** Use `profvis::profvis()` to identify performance bottlenecks in your code. Profile before optimizing.
+- **Caching:** Use `memoise::memoise()` to cache expensive function results. Particularly useful for repeated API calls or complex computations.
+- **Vectorization:** Prefer vectorized operations over loops. Use `purrr::map_*()` family or `apply()` family for remaining iteration needs.
+
+## Tooling & Quality
+
+- **Formatting:** `styler` (tidyverse style), two-space indents, ~100-char lines.
+- **Linting:** `lintr` configured via `.lintr`.
+- **Pre-commit:** consider `precommit` hooks to lint/format automatically.
+- **Docs:** roxygen2 for exported functions (`@param`, `@return`, `@examples`).
+- **Tests:** prefer small, pure, composable functions that are easy to unit test.
+- **Dependencies:** manage with `renv`; snapshot after adding packages.
+- **Paths:** prefer `fs` and `here` for portability.
+
+## Data Wrangling & I/O
+
+- **Data frames:** prefer tibbles in tidyverse-heavy files; otherwise base `data.frame()` is fine.
+- **Iteration:** use `purrr` in tidyverse code. In base-style code, prefer type-stable, vectorized patterns such as `vapply()`
+   (for atomic outputs) or `Map()` (for elementwise operations) instead of explicit `for` loops when they improve clarity or performance.
+- **Strings & Dates:** use `stringr`/`lubridate` where already present; otherwise use clear base helpers (e.g., `nchar()`, `substr()`, `as.Date()` with explicit format).
+- **I/O:** prefer explicit, typed readers (e.g., `readr::read_csv()`); make parsing assumptions explicit.
+
+## Plotting
+
+- Prefer `ggplot2` for publication-quality plots. Keep layers readable and label axes and units.
+
+## Error Handling
+
+- In tidyverse contexts, use `rlang::abort()` / `rlang::warn()` for structured conditions; in base-only code, use `stop()` / `warning()`.
+- For recoverable operations:
+- Use `purrr::possibly()` when you want a typed fallback value of the same type (simpler).
+- Use `purrr::safely()` when you need to capture both results and errors for later inspection or logging.
+- Use `tryCatch()` in base R for fine-grained control or compatibility with non-tidyverse code.
+- Prefer consistent return structures—typed outputs for normal flows, structured lists only when error details are required.
+
+## Security Best Practices
+
+- **Command execution:** Prefer `processx::run()` or `sys::exec_wait()` over `system()`; validate and sanitize all arguments.
+- **Database queries:** Use parameterized `DBI` queries to prevent SQL injection.
+- **File paths:** Normalize and sanitize user-provided paths (e.g., `fs::path_sanitize()`), and validate against allowlists.
+- **Credentials:** Never hardcode secrets. Use env vars (`Sys.getenv()`), config outside VCS, or `keyring`.
+
+## Shiny
+
+- Modularize UI and server logic for non-trivial apps. Use `eventReactive()` / `observeEvent()` for explicit dependencies.
+- Validate inputs with `req()` and clear, user-friendly messages.
+- Use connection pooling (`pool`) for databases; avoid long-lived global objects.
+- Isolate expensive computations and prefer `reactiveVal()` / `reactiveValues()` for small state.
+
+## R Markdown / Quarto
+
+- Keep chunks focused; prefer explicit chunk options (`echo`, `message`, `warning`).
+- Avoid global state; prefer local helpers. Use `withr::with_seed()` for deterministic chunks.
+
+## Copilot-Specific Guidance
+
+- If the current file uses tidyverse, **suggest tidyverse-first patterns** (e.g., `dplyr::across()` instead of superseded verbs). If base-R style is present, **use base idioms**.
+- Qualify non-base calls in suggestions (e.g., `dplyr::mutate()`).
+- Suggest vectorized or tidy solutions over loops when idiomatic.
+- Prefer small helper functions over long pipelines.
+- When multiple approaches are equivalent, prefer readability and type stability and explain the trade-offs.
+
+---
+
+## Minimal Examples
+
+```r
+# Base R variant
+scores <- data.frame(id = 1:5, x = c(1, 3, 2, 5, 4))
+safe_log <- function(x) tryCatch(log(x), error = function(e) NA_real_)
+scores$z <- vapply(scores$x, safe_log, numeric(1))
+
+# Tidyverse variant (if this file uses tidyverse)
+result <- tibble::tibble(id = 1:5, x = c(1, 3, 2, 5, 4)) |>
+dplyr::mutate(z = purrr::map_dbl(x, purrr::possibly(log, otherwise = NA_real_))) |>
+dplyr::filter(z > 0)
+
+# Example reusable helper with roxygen2 doc
+#' Compute the z-score of a numeric vector
+#' @param x A numeric vector
+#' @return Numeric vector of z-scores
+#' @examples z_score(c(1, 2, 3))
+z_score <- function(x) (x - mean(x, na.rm = TRUE)) / stats::sd(x, na.rm = TRUE)
+```

package/assets/instructions/reactjs.instructions.md

@@ -0,0 +1,162 @@
+---
+description: 'ReactJS development standards and best practices'
+applyTo: '**/*.jsx, **/*.tsx, **/*.js, **/*.ts, **/*.css, **/*.scss'
+---
+
+# ReactJS Development Instructions
+
+Instructions for building high-quality ReactJS applications with modern patterns, hooks, and best practices following the official React documentation at https://react.dev.
+
+## Project Context
+- Latest React version (React 19+)
+- TypeScript for type safety (when applicable)
+- Functional components with hooks as default
+- Follow React's official style guide and best practices
+- Use modern build tools (Vite, Create React App, or custom Webpack setup)
+- Implement proper component composition and reusability patterns
+
+## Development Standards
+
+### Architecture
+- Use functional components with hooks as the primary pattern
+- Implement component composition over inheritance
+- Organize components by feature or domain for scalability
+- Separate presentational and container components clearly
+- Use custom hooks for reusable stateful logic
+- Implement proper component hierarchies with clear data flow
+
+### TypeScript Integration
+- Use TypeScript interfaces for props, state, and component definitions
+- Define proper types for event handlers and refs
+- Implement generic components where appropriate
+- Use strict mode in `tsconfig.json` for type safety
+- Leverage React's built-in types (`React.FC`, `React.ComponentProps`, etc.)
+- Create union types for component variants and states
+
+### Component Design
+- Follow the single responsibility principle for components
+- Use descriptive and consistent naming conventions
+- Implement proper prop validation with TypeScript or PropTypes
+- Design components to be testable and reusable
+- Keep components small and focused on a single concern
+- Use composition patterns (render props, children as functions)
+
+### State Management
+- Use `useState` for local component state
+- Implement `useReducer` for complex state logic
+- Leverage `useContext` for sharing state across component trees
+- Consider external state management (Redux Toolkit, Zustand) for complex applications
+- Implement proper state normalization and data structures
+- Use React Query or SWR for server state management
+
+### Hooks and Effects
+- Use `useEffect` with proper dependency arrays to avoid infinite loops
+- Implement cleanup functions in effects to prevent memory leaks
+- Use `useMemo` and `useCallback` for performance optimization when needed
+- Create custom hooks for reusable stateful logic
+- Follow the rules of hooks (only call at the top level)
+- Use `useRef` for accessing DOM elements and storing mutable values
+
+### Styling
+- Use CSS Modules, Styled Components, or modern CSS-in-JS solutions
+- Implement responsive design with mobile-first approach
+- Follow BEM methodology or similar naming conventions for CSS classes
+- Use CSS custom properties (variables) for theming
+- Implement consistent spacing, typography, and color systems
+- Ensure accessibility with proper ARIA attributes and semantic HTML
+
+### Performance Optimization
+- Use `React.memo` for component memoization when appropriate
+- Implement code splitting with `React.lazy` and `Suspense`
+- Optimize bundle size with tree shaking and dynamic imports
+- Use `useMemo` and `useCallback` judiciously to prevent unnecessary re-renders
+- Implement virtual scrolling for large lists
+- Profile components with React DevTools to identify performance bottlenecks
+
+### Data Fetching
+- Use modern data fetching libraries (React Query, SWR, Apollo Client)
+- Implement proper loading, error, and success states
+- Handle race conditions and request cancellation
+- Use optimistic updates for better user experience
+- Implement proper caching strategies
+- Handle offline scenarios and network errors gracefully
+
+### Error Handling
+- Implement Error Boundaries for component-level error handling
+- Use proper error states in data fetching
+- Implement fallback UI for error scenarios
+- Log errors appropriately for debugging
+- Handle async errors in effects and event handlers
+- Provide meaningful error messages to users
+
+### Forms and Validation
+- Use controlled components for form inputs
+- Implement proper form validation with libraries like Formik, React Hook Form
+- Handle form submission and error states appropriately
+- Implement accessibility features for forms (labels, ARIA attributes)
+- Use debounced validation for better user experience
+- Handle file uploads and complex form scenarios
+
+### Routing
+- Use React Router for client-side routing
+- Implement nested routes and route protection
+- Handle route parameters and query strings properly
+- Implement lazy loading for route-based code splitting
+- Use proper navigation patterns and back button handling
+- Implement breadcrumbs and navigation state management
+
+### Testing
+- Write unit tests for components using React Testing Library
+- Test component behavior, not implementation details
+- Use Jest for test runner and assertion library
+- Implement integration tests for complex component interactions
+- Mock external dependencies and API calls appropriately
+- Test accessibility features and keyboard navigation
+
+### Security
+- Sanitize user inputs to prevent XSS attacks
+- Validate and escape data before rendering
+- Use HTTPS for all external API calls
+- Implement proper authentication and authorization patterns
+- Avoid storing sensitive data in localStorage or sessionStorage
+- Use Content Security Policy (CSP) headers
+
+### Accessibility
+- Use semantic HTML elements appropriately
+- Implement proper ARIA attributes and roles
+- Ensure keyboard navigation works for all interactive elements
+- Provide alt text for images and descriptive text for icons
+- Implement proper color contrast ratios
+- Test with screen readers and accessibility tools
+
+## Implementation Process
+1. Plan component architecture and data flow
+2. Set up project structure with proper folder organization
+3. Define TypeScript interfaces and types
+4. Implement core components with proper styling
+5. Add state management and data fetching logic
+6. Implement routing and navigation
+7. Add form handling and validation
+8. Implement error handling and loading states
+9. Add testing coverage for components and functionality
+10. Optimize performance and bundle size
+11. Ensure accessibility compliance
+12. Add documentation and code comments
+
+## Additional Guidelines
+- Follow React's naming conventions (PascalCase for components, camelCase for functions)
+- Use meaningful commit messages and maintain clean git history
+- Implement proper code splitting and lazy loading strategies
+- Document complex components and custom hooks with JSDoc
+- Use ESLint and Prettier for consistent code formatting
+- Keep dependencies up to date and audit for security vulnerabilities
+- Implement proper environment configuration for different deployment stages
+- Use React Developer Tools for debugging and performance analysis
+
+## Common Patterns
+- Higher-Order Components (HOCs) for cross-cutting concerns
+- Render props pattern for component composition
+- Compound components for related functionality
+- Provider pattern for context-based state sharing
+- Container/Presentational component separation
+- Custom hooks for reusable logic extraction